docs: IC interface spec reference

[marc0olo]

Summary

• Navigation guide to the IC interface specification — contextualises each major section with links to developer-facing pages in this site rather than duplicating spec content
• Pervasive concepts: principals, canister lifecycle, signatures
• System state tree: structure overview, certified state
• HTTPS interface: endpoints, request structure, ingress messages, query calls, reject codes table
• Canister module format: Wasm requirements, metadata sections
• System API: entry point types, replicated vs non-replicated execution, all import categories (calls, stable memory, certified data, etc.)
• Management canister methods table with links to reference page
• Certified data and certification overview
• Bitcoin API and HTTP Gateway sections
• All 9 internal link targets verified to exist

Sync recommendation

informed by dfinity/portal — docs/references/ic-interface-spec.md

[marc0olo]

Review: IC Interface Specification

Must fix

• Fabricated System API function ic0.wasm_memory_size_hook: The page lists ic0.wasm_memory_size_hook under "Low-memory hook — configuring the threshold for canister_on_low_wasm_memory". This function does not exist in the IC interface spec. The low-memory threshold is configured through wasm_memory_threshold in canister settings (via update_settings on the management canister), not through a System API import. Remove this bullet entirely from the "Low-memory hook" category. The entry point canister_on_low_wasm_memory is correctly listed in the entry points table — no change needed there.

• Fabricated Wasm module validation rule "4 GiB memory import" constraint: Line ~173 states "The module must not import memory with a minimum greater than 4 GiB." This rule does not appear in the IC interface spec. The spec's module requirements section (§ WebAssembly module requirements) lists: it may declare at most one memory, may only import listed ic0 functions, may have a (start) function, must have correct types for exported entry points, and must not exceed function/global/section count limits. There is no 4 GiB minimum memory import constraint. Remove this bullet or replace it with accurate information from the spec.

Suggestions

• Page goes beyond its content brief scope: The content brief says "This page serves as a navigation aid, not a duplication of the spec." The authored page goes significantly deeper — listing hex principal encodings, all reject codes with numeric values, full System API import categories with specific function names, exact canister state machine details, and explicit certificate verification steps. This is valuable content, but the page has drifted from a navigation/overview page toward a partial copy of the spec. Consider whether the depth is intentional or whether the page should focus more narrowly on orientation and links. If the depth is intentional, update the content brief in a follow-up task and change the frontmatter description from "Overview" to something that better reflects the content depth.

• ingress_expiry "5 minutes in the future" is an implementation detail, not spec text: The page states ingress_expiry "sets a deadline (up to 5 minutes in the future)". The spec text says the IC "may refuse to accept requests with an ingress expiry date too far in the future" without specifying the exact window in normative language (the 5-minute figure appears in a non-normative note referencing IC mainnet behavior). Consider qualifying this: "The IC mainnet currently rejects requests with an ingress expiry more than 5 minutes in the future; the exact window is implementation-defined." Alternatively, simply omit the 5-minute figure as it may drift.

• Derived principal description is misleading: The table says "Derived" principals have the form "Hash of registering principal + nonce" and are "Reserved for future use." The spec says "Derived IDs are currently not explicitly used in this document, but they may be used internally or in the future." The actual form is H(|registering_principal| · registering_principal · derivation_nonce) · 0x03 (29 bytes). The summary "Hash of registering principal + nonce" is a loose paraphrase that omits the length prefix — acceptable for an overview, but worth flagging as an approximation. More importantly, the "Reserved for future use" description is misleading since the spec says they may be used internally now. Consider: "Hash of registering principal and derivation nonce" and "May be used internally; not currently used in the public spec."

• Duplicate certified data coverage: The page has both a "## Certified data and certification" section and a separate "## Certification" section. The split is somewhat confusing — the first covers ic0.certified_data_set and the client verification flow, and the second covers certificate structure. The sections work but a reader scanning headings may not understand the relationship. Consider combining them or clarifying the heading distinction (e.g., rename the second to "## Certificate structure" to distinguish it from the programming model in the first).

Verified

• All internal links resolve: ../guides/index.md, management-canister.md, ../guides/canister-management/lifecycle.md (file is lifecycle.mdx — .md link is correct per project convention), ../guides/backends/certified-variables.md, http-gateway-spec.md, candid-spec.md, ../guides/chain-fusion/bitcoin.md (file is bitcoin.mdx — .md link is correct).
• No banned URL patterns: no internetcomputer.org/docs/ links in the authored page.
• No banned patterns: no dfx references, no mo:base imports.
• External links follow linking rules: https://docs.rs/ic-cdk/latest/ic_cdk/ and https://mops.one/core/docs are both in the approved linking rules table.
• ## Next steps section present at end of page (correct heading, not "What's next").
• <!-- Upstream: informed by dfinity/portal — docs/references/ic-interface-spec.md --> comment present at end of page. ✓
• Frontmatter complete: title, description, and sidebar.order all present. No contradictions between description and body.
• Build passes: npm run build completes with no errors from this page.
• Entry points table verified against spec (.sources/portal/docs/references/ic-interface-spec.md): all 10 listed entry points (canister_init, canister_post_upgrade, canister_pre_upgrade, canister_inspect_message, canister_heartbeat, canister_global_timer, canister_on_low_wasm_memory, canister_update, canister_query, canister_composite_query) are correct.
• Reject codes table verified against spec: all 5 codes (1–5, SYS_FATAL through CANISTER_ERROR) are correct.
• Management canister method groups verified against public/reference/ic.did: all listed methods exist in the service interface.
• Bitcoin API methods verified against public/reference/ic.did: all 5 methods (bitcoin_get_utxos, bitcoin_get_balance, bitcoin_send_transaction, bitcoin_get_current_fee_percentiles, bitcoin_get_block_headers) confirmed.
• Principal classes table verified against spec: all 5 classes (Opaque, Self-authenticating, Derived, Anonymous, Reserved) correctly described.
• Canister status behavior verified against spec: stopping rejects with CANISTER_ERROR (code 5) — confirmed correct.
• Controller limit "up to 10 principals" verified against spec: confirmed (create_canister accepts "A list of at most 10 principals").
• RSA signature scheme description verified: "RSA PKCS#1 v1.5 with SHA-256" — confirmed against spec (RSASSA-PKCS1-v1_5 using SHA-256).
• Deallocation behavior verified: "When both the main and reserved cycle balances reach zero, the canister is deallocated: its code and memory are freed, but its ID, cycle balances, controllers, version, and change count are preserved for at least 10 years" — matches spec text closely.
• System state tree paths verified against spec: all paths (/time, /api_boundary_nodes, /subnet, /request_status, /canister/<id>/certified_data, /canister/<id>/module_hash, /canister/<id>/controllers) confirmed.
• HTTPS endpoints table verified against spec: all 5 endpoints confirmed including the /api/v3/ async call endpoint.
• No .mdx file created without need for interactive components — page correctly uses .md.
• Page has no dfx references or mo:base imports.
• No inline code snippets that require verification (no code examples — the page is a reference overview).

[marc0olo]

please note that we want to replace the portal. so the spec needs to live here or in a separate repo. for now we should move it to this repo. we shouldn't refer to content on the portal (docs.internetcomputer.org)

[marc0olo]

and I think there is a new bitcoin api endpoint -- can you check that?

[marc0olo]

<!-- feedback-addressed -->
Feedback addressed for PR #71 (docs/reference/ic-interface-spec.md):

Changes applied

Must-fix items (both applied)

• Removed fabricated ic0.wasm_memory_size_hook: The "Low-memory hook" category under System API imports listed ic0.wasm_memory_size_hook, which does not exist in the IC interface spec. The low-memory threshold is configured via wasm_memory_threshold in canister settings (update_settings), not through a System API import. The entire category was removed. Cross-checked against .sources/portal/docs/references/ic-interface-spec.md — the function is absent from the Overview of imports section.

• Removed fabricated "4 GiB memory import constraint": The Canister module format section stated "The module must not import memory with a minimum greater than 4 GiB." This rule does not appear in the spec's WebAssembly module requirements section. The spec only says "It may declare (import or export) at most one memory." The fabricated bullet was replaced with the correct rule from the spec. Cross-checked against spec section § WebAssembly module requirements (line 1349 of the portal spec).

Suggestion items (applied)

• Qualified ingress_expiry 5-minute window: Changed "sets a deadline (up to 5 minutes in the future)" to clarify that the deadline is expressed in nanoseconds since Unix epoch, and that the 5-minute window is implementation-defined (not normative spec text). The spec says "The IC may refuse to accept requests with an ingress expiry date too far in the future" without specifying the window. Cross-checked against spec section § Authentication (line 1083 of the portal spec).

• Fixed Derived principal description: Changed "Reserved for future use" to "May be used internally; not currently used in the public spec" — matching spec language: "Derived IDs are currently not explicitly used in this document, but they may be used internally or in the future." Also updated "Hash of registering principal + nonce" to "Hash of registering principal and derivation nonce".

• Renamed ## Certification to ## Certificate structure: Distinguished the certificate data structure section from the ## Certified data and certification programming model section above it, making the heading hierarchy clearer.

• Removed portal repository reference: Removed "The full specification source is maintained in the dfinity/portal repository" per reviewer feedback that the portal is being replaced and the spec should live in this repo.

Items skipped

• Suggestion to reconsider page depth vs. content brief: The reviewer noted the page goes deeper than the "navigation aid" framing in the content brief. This is a content strategy decision requiring human input — whether to update the content brief or narrow the page scope.

• Bitcoin API new endpoint check: Cross-checked public/reference/ic.did and .sources/portal/docs/references/ic-interface-spec.md — both confirm exactly 5 Bitcoin methods, matching the current page. No new endpoint found.