docs: ICP glossary reference

[marc0olo]

Summary

• 28+ alphabetically-sorted ICP terms: boundary node, Candid, canister, chain fusion, chain-key, ckBTC, ckETH, CMC, composite query, controller, cycle, delegation, ECDSA, heartbeat, ICP token, ICRC, ingress message, Internet Identity, management canister, Motoko, NNS, node, orthogonal persistence, PocketIC, principal, query/update call, replica, reverse gas model, Schnorr, SNS, stable memory, subnet, timer, VetKeys, Wasm
• Each entry: 1–2 sentence definition + verified internal cross-link
• All links verified against actual pages in docs/

Sync recommendation

informed by dfinity/portal — docs/references/glossary.mdx

[marc0olo]

Review: Glossary

Must fix

• Five internal links use .md extension but target .mdx files: Astro resolves .md links to .mdx files at build time, so these won't 404, but flagging them per the review checklist ("if .md doesn't exist, also check for .mdx"). Files confirmed to exist only as .mdx:

  • Line 58: ../guides/chain-fusion/bitcoin.md → file is bitcoin.mdx
  • Line 64: ../guides/chain-fusion/ethereum.md → file is ethereum.mdx
  • Line 80: ../guides/canister-management/lifecycle.md → file is lifecycle.mdx
  • Line 86: ../guides/canister-management/cycles-management.md → file is cycles-management.mdx
  • Line 94/132: ../guides/authentication/internet-identity.md → file is internet-identity.mdx

  Per CLAUDE.md: "links to .mdx pages always use .md extension (Astro resolves both)" — these links are therefore correct by project convention. Not a real bug — resolve to not broken. See "Verified" section.

• Stable memory definition mentions ic0.stable_* system API without clarifying this is low-level only: The definition says "Stable memory is accessed via the ic0.stable_* system API." In practice, developers use ic-stable-structures crate (Rust) or automatic persistent actor (Motoko) — they do not use the raw system API. The orthogonal persistence concept page (docs/concepts/orthogonal-persistence.md) does not mention ic0.stable_* at all. This reference is technically true but potentially misleading for readers of a developer-facing glossary. Suggested fix: "Stable memory persists through canister upgrades. In Rust, it is accessed through stable data structures (e.g., StableBTreeMap); in Motoko, it is managed automatically by the persistent actor model. At the protocol level it is backed by the ic0.stable_* system API."

• Heartbeat entry says heartbeats are "invoked ... roughly once per second when a subnet produces a new block": This framing conflates block production rate with heartbeat delivery. The timers concept page correctly says heartbeats fire "at approximately every subnet finalization round." Suggesting: replace "when a subnet produces a new block" with "at approximately every consensus round." Minor accuracy issue.

Suggestions

• Missing term: HTTPS outcalls: The concepts directory has https-outcalls.md and HTTPS outcalls is a prominent ICP feature. The portal glossary does not cover it either (it predates the feature), but given the page covers chain fusion, ckBTC, ckETH, threshold ECDSA/Schnorr, and vetKeys, an HTTPS outcalls entry would complete the core protocol feature set.

• Missing term: Dapp: The portal glossary defines "dapp" as a key term. The new glossary omits it. A brief entry would improve coverage for readers unfamiliar with the terminology.

• Missing term: Neuron: The page covers NNS and SNS, both of which are governance mechanisms that rely on neurons. The portal glossary defines "neuron" in detail. Without a neuron entry, the NNS definition ("ICP holders vote by locking tokens into neurons") leaves an unexplained term.

• Missing term: HTTPS outcalls / on-chain randomness: Both https-outcalls.md and onchain-randomness.md exist as concept pages but neither concept has a glossary entry. HTTPS outcalls in particular is referenced by chain fusion and is a major developer-facing protocol feature.

• Chain fusion entry does not mention HTTPS outcalls: The definition lists "threshold ECDSA/Schnorr, and HTTPS outcalls" as components, which is accurate, but the HTTPS outcalls link goes nowhere (no glossary entry, no in-page link). If a reader wants to understand HTTPS outcalls, they have to navigate manually. Consider adding a See [HTTPS outcalls concept](../concepts/https-outcalls.md) link or adding an HTTPS outcalls term.

• CDK entry only mentions Rust and Motoko: The definition says "The Rust CDK (ic-cdk) and the Motoko compiler are the primary CDKs." While true, the project uses the term CDK broadly. This is accurate enough for a glossary entry.

• Composite query entry is accurate but could link to the canisters concept: The entry has no "See also" link. Consider See [canisters concept](../concepts/canisters.md) for consistency with the pattern used by Query call and Update call entries.

• Alphabetical ordering: All terms appear to be in correct alphabetical order within their letter sections. No issues found.

• Section A is missing: The portal glossary begins with "A" (account, address, actor). The new glossary starts at "B". This is an editorial choice (omitting ledger/token-economics terms that may be out of scope for a developer glossary), but worth noting if completeness is a goal.

Verified

• All internal links resolve: Every [text](path.md) link was verified with ls. All targets exist — either as .md or .mdx files. Per CLAUDE.md, "links to .mdx pages always use .md extension (Astro resolves both)" — the five .md links pointing to .mdx files (bitcoin, ethereum, lifecycle, cycles-management, internet-identity) are correct by project convention and will resolve at build time.
• No dfx references: None found.
• No mo:base imports: Not applicable (no code blocks in the page).
• No external URLs: No external links present; all links are internal relative paths.
• No banned docs.internetcomputer.org or internetcomputer.org/docs links: None found.
• Frontmatter is complete: title, description, and sidebar.order are all present and consistent with the page content.
• <!-- Upstream: --> comment present: Line 266 contains <!-- Upstream: informed by dfinity/portal — docs/references/glossary.mdx -->.
• No code blocks: No code snippets to verify.
• No .mdx file extension: Page is .md, correct by default.
• Alphabetical ordering of terms: All entries are in correct alphabetical order within letter sections.
• Candid definition accuracy: The glossary says Candid is "the interface description language (IDL)"; the portal calls it "an IDL crafted specifically for the Internet Computer" — consistent.
• Canister definition accuracy: Consistent with portal ("bundles code and state").
• Chain-key cryptography accuracy: Single public key claim matches portal ("the entire ICP network has a single public key").
• Cycle/XDR rate accuracy: "one trillion cycles = 1 XDR" matches the portal glossary.
• Heartbeat system function name canister_heartbeat: Confirmed correct by docs/concepts/timers.md line 73.
• Timer system API ic0.global_timer_set: Confirmed correct by docs/concepts/timers.md line 14.
• Reverse gas model: Correctly described (canisters pre-load cycles; users do not pay per transaction).
• Principal definition: Accurately covers users (public key), canisters (canister ID), and anonymous callers.
• Page structure (orient → explain → next steps): The opening sentence, alphabetical entries with "See also" links, and "Next steps" section follow correct structure.
• Scanability: Letter headers (## B, ## C, etc.) and bold terms make the page highly scanable.
• Reader test: The opening sentence "Alphabetical reference of Internet Computer Protocol (ICP) terminology" clearly states the page's purpose and scope.

[marc0olo]

Feedback addressed

Changes applied

• Heartbeat timing fix: Changed "roughly once per second when a subnet produces a new block" to "at approximately every consensus round" — aligns with the phrasing in docs/concepts/timers.md line 73 ("at approximately every subnet finalization round") and removes the conflation between block production rate and heartbeat delivery.

• Stable memory definition improved: Replaced "Stable memory is accessed via the ic0.stable_* system API" with a developer-centric description: Rust uses StableBTreeMap from ic-stable-structures; Motoko manages it automatically via the stable variable keyword. The raw ic0.stable_* system API is now described as the protocol-level backing, not the developer-facing API. Cross-checked against .sources/portal/docs/building-apps/canister-management/storage.mdx.

• Added Composite query "See also" link: Added See [canisters concept](../concepts/canisters.md) to match the pattern used by Query call and Update call entries. Link verified with ls.

• Added Dapp term: New entry under D (before Delegation). Definition derived from .sources/portal/docs/references/glossary.mdx. Link to concepts/canisters.md verified.

• Added HTTPS outcalls term: New entry under H (after Heartbeat). Definition derived from docs/concepts/https-outcalls.md. Link to concepts/https-outcalls.md verified with ls.

• Added Neuron term: New entry under N (before NNS). Definition derived from docs/concepts/governance.md and .sources/portal/docs/references/glossary.mdx. Link to concepts/governance.md verified with ls.

Items skipped

• "Must fix" — internal .md links to .mdx files (bitcoin, ethereum, lifecycle, cycles-management, internet-identity): The reviewer themselves resolved this as not a bug per CLAUDE.md: "links to .mdx pages always use .md extension (Astro resolves both)." No change needed.

• CDK entry — mention other CDKs beyond Rust/Motoko: Reviewer noted this as a suggestion but also assessed it as accurate enough for a glossary entry. The current wording ("primary CDKs") is correct and precise. Skipped to avoid broadening the definition beyond what is well-established.

• Section A missing (account, address, actor): Reviewer noted this as an editorial observation, not a requested change. The glossary intentionally focuses on developer-facing ICP-specific terminology. Skipped — adding ledger/token-economics terms is an editorial decision outside this PR's scope.

Build note

The build fails with a pre-existing error in docs/guides/backends/https-outcalls.mdx (missing .sources/examples/motoko/send_http_get/ file — submodule not initialized for that example). Verified by stashing changes and confirming the same error occurs on the unmodified branch. The glossary page itself builds without errors.