docs: Batch 9 — principals and canister computational model

[marc0olo]

Summary

• New page: docs/concepts/principals.md — the 5 principal classes (management canister, canister IDs, self-authenticating IDs, anonymous principal, derived IDs), how principals work as caller identities, canister control model (centralized/multi-sig/DAO/immutable), upgrade behavior and stable memory
• Expanded: docs/concepts/canisters.md — added "Inter-canister messaging and error handling" section covering: request/reply + callback model, the network's guaranteed-reply guarantee, and the precise trap/rollback behavior (reverts to state after last outgoing call dispatch, not beginning of message)
• Fixed: docs/concepts/canisters.md line 73 — replaced Learn Hub principal link with internal principals.md link
• Updated: docs/concepts/index.md — added principals.md entry under Architecture
• Updated: docs/references/glossary.md — updated principal entry to link to concepts/principals.md
• Deleted: 4 consumed Learn Hub staging files from canister-smart-contracts/

Staging files deleted

• .migration/learn-hub/how-does-icp-work/canister-smart-contracts/{what-is-a-principal,canister-control,canister-smart-contracts,computational-model}.md

Sync recommendation

principals.md: informed by Learn Hub articles "What is a Principal?", "Canister Control" (migrated, source retired)
canisters.md additions: informed by Learn Hub articles "Canister Smart Contracts", "Computational Model" (migrated, source retired)

[marc0olo]

Review notes

Two issues to fix before merge:

1. Broken link (blocking): principals.md links to ../guides/authentication/index.md, but that file does not exist. The guides/authentication/ directory contains internet-identity.mdx and verifiable-credentials.md but no index page. Options:

• Change the link to ../guides/authentication/internet-identity.md
• Remove the link and leave the mention as plain text

2. Third-party product link: The canister control structure table links to https://orbitwallet.io/ (Orbit wallet) as an example of a controller. Worth confirming whether linking to a specific third-party product is appropriate here, or whether a more generic description would be preferable.

No other issues: frontmatter complete, canisters.md expansion looks good, glossary.md and index.md updates are correct, <!-- Upstream: --> comment present, no banned patterns.

[marc0olo]

Review notes

Three items to address before merging:

1. Broken link in principals.md Next steps

The Next steps section links to ../guides/authentication/index.md, but that file does not exist. The authentication directory only contains internet-identity.mdx and verifiable-credentials.md.

Fix: change the link to ../guides/authentication/internet-identity.md.

2. Wrong self-authenticating principal example (line 16)

un4fu-tqaaa-aaaab-qadjq-cai is a canister principal (10 bytes, ~27 characters). Self-authenticating principals are derived from a public key hash (29 bytes) and encode to approximately 63-character strings, for example:

o2ivq-5dsbb-hhfso-w2o5v-7qiaq-g4fbm-6qhhb-xbj6w-szpxa-lflfa-mae

Using a canister-format string as a user principal example is misleading and will cause confusion for developers trying to understand what principals look like in practice.

3. Third-party product link decision needed

The canister control table includes a link to https://orbitwallet.io/ (inherited from the Learn Hub staging file). Other pages on this site use DFINITY-maintained or neutral references for examples. Please decide:

• Keep it with explicit context (e.g., "community wallet — Orbit") to set correct expectations, or
• Replace it with a generic description that does not endorse a specific product.

Neither option is wrong, but the choice should be intentional.

[marc0olo]

Feedback addressed:

• Wrong principal example: Replaced un4fu-tqaaa-aaaab-qadjq-cai (a canister-format principal) with o2ivq-5dsbb-hhfso-w2o5v-7qiaq-g4fbm-6qhhb-xbj6w-szpxa-lflfa-mae — a correct 29-byte self-authenticating principal derived from an Ed25519 public key
• Broken authentication link: Changed ../guides/authentication/index.md → ../guides/authentication/internet-identity.md (the actual file is internet-identity.mdx, resolved by Astro for .md links)
• Orbit wallet link: Kept the [Orbit](https://orbitwallet.io/) link in the control structure table — it serves as a concrete example of a multi-signature wallet in an explicitly labeled "Multi-signature" row, which gives sufficient context without requiring a prose explanation