docs: Batch 8 — tokens, ledgers, and cycles concepts

[marc0olo]

Summary

• New page: `docs/concepts/network-economics.md` — ICP token uses (governance, cycles, node rewards, SNS swaps), voting rewards and maturity mechanism (10%→5% over 8 years), supply dynamics (inflation/deflation with diagram), SNS tokenomics configuration; node provider rewards exchange rate computation (CMC, 30-day moving average)
• New page: `docs/concepts/ledgers.md` — ICP ledger (AccountIdentifier), ICRC ledgers (principal + subaccount), append-only transaction log, archive canisters, index canisters, fee models
• Expanded: `docs/concepts/cycles.md` — added cycles ledger section (canister IDs, ICRC-1/2/3, deposit/withdraw/create_canister, 100M fee per block, architecture diagram); updated cycles ledger limitation note to give two clear patterns (top-up vs proxy canister); added interface spec link to system-canisters reference
• Expanded: `docs/guides/canister-management/cycles-management.mdx` — added "Calling canisters that require cycles" section covering inter-canister `Cycles.add`/`msg_cycles_add` pattern and the proxy canister template for CLI/agent use cases
• Updated: `docs/concepts/governance.md` — replaced external Learn Hub link with internal `network-economics.md` link
• Updated: `docs/concepts/index.md` — added network-economics and ledgers entries; fixed chain-fusion link to subdirectory
• Updated: `sidebar.mjs` — added concepts/network-economics and concepts/ledgers sidebar entries
• Images: cycles ledger architecture diagram, ICP supply dynamics (deflation/inflation) diagram

Sync recommendation

`network-economics.md`: `informed by learn-hub staging — tokens-governance/tokens-governance.md, tokens-governance/tokenomics.md, sns/tokenomics.md`
`ledgers.md`: `informed by learn-hub staging — tokens-governance/how-token-ledgers-work-on-the-internet-computer.md`
`cycles.md` additions: `informed by learn-hub staging — canister-smart-contracts/cycles.md, canister-smart-contracts/cycles-ledger.md`
`cycles-management.mdx` additions: `informed by dfinity/icp-cli-templates proxy template, dfinity/proxy-canister`

[marc0olo]

Review notes

Two blocking issues and one minor fix needed:

1. Broken links (blocking, dependency on #213): Two links point into concepts/chain-fusion/ which only exists once PR #213 merges:

• index.md links to chain-fusion/index.md
• token-ledgers.md links to chain-fusion/chain-key-tokens.md

Options: batch-merge after #213, or temporarily link to the flat concepts/chain-fusion.md that currently exists on main.

2. Em-dash in token-ledgers.md (banned per CLAUDE.md): The AccountIdentifier definition uses an em-dash: **AccountIdentifier** — a 32-byte hash.... Replace with a colon: **AccountIdentifier**: a 32-byte hash....

3. Minor: guides/digital-assets/ledgers.md is actually ledgers.mdx. Astro resolves .md links to .mdx files correctly, so this is not a hard error, but worth noting for consistency.

No other issues: frontmatter complete on all new pages, governance.md and cycles.md cross-links correct, <!-- Upstream: --> comment present.

[marc0olo]

Three issues to address before merging:

1. Em-dash in token-ledgers.md line 29

Em-dashes are banned project-wide (CLAUDE.md). Please replace:

**AccountIdentifier** — a 32-byte hash derived from...

with:

**AccountIdentifier**: a 32-byte hash derived from...

2. Broken link in cycles.md — "How charging works" section

The new section links to protocol/execution.md#deterministic-time-slicing, but docs/concepts/protocol/ does not exist yet (it is added by PR #209). Until that PR merges, this link will be broken. Two options:

• Remove the hyperlink and mention DTS as plain text.
• Hold this change until after docs: add protocol stack concept pages (Batch 1) #209 merges.

3. Chain-fusion link dependencies in concepts/index.md and token-ledgers.md

concepts/index.md links to chain-fusion/index.md, and token-ledgers.md links to chain-fusion/chain-key-tokens.md (twice). Neither path exists until PR #213 merges. Two options:

• Temporarily revert these to the flat chain-fusion.md link that currently exists on main.
• Batch-merge after docs: Chain Fusion deep dives #213 is in.

Suggested merge order: #209 → #213 → #215.

[marc0olo]

Feedback addressed:

• Fixed **AccountIdentifier** — → **AccountIdentifier**: in token-ledgers.md line 29
• Reverted chain-fusion/chain-key-tokens.md links to chain-fusion.md (the flat page on main) in token-ledgers.md (lines 21, 71) and concepts/index.md (line 27) — will update to the proper subdirectory paths after PR docs: Chain Fusion deep dives #213 merges
• Removed broken link to protocol/execution.md#deterministic-time-slicing in cycles.md (plain text for now, link can be restored after PR docs: add protocol stack concept pages (Batch 1) #209 merges)

Suggested merge order: #209 → #213 → #215

[marc0olo]

Feedback addressed:

• network-economics.md:14: expanded NNS on first use — "the NNS governance system" → "the Network Nervous System (NNS) governance system"
• network-economics.md:14: fixed broken anchor — governance.md#neurons-and-voting-power → governance.md#neurons (verified heading at line 36 of governance.md)

Lower-priority observations noted but deferred:

• SNS not expanded on first use — non-blocking per brand rules; leaving for consistency pass if needed
• cycles.md:62 "sensitive workloads" — pre-existing, flagged for future cleanup
• create_canister_from omitted from cycles ledger operations list — spec link is present; skipped to keep the section focused on the common-path operations