docs: token ledgers guide

[marc0olo]

Summary

• Practical guide for interacting with ICRC token ledgers from canisters and frontends
• Covers ICRC-1 transfers, balance queries, ICRC-2 approve/transfer-from, subaccount management, NFTs (ICRC-7/37), and local test ledger setup
• Rust and Motoko code examples adapted from icskills, with JS SDK linked (not duplicated)
• Canonical canister IDs and account format sourced from icskills
• Local test ledger section with icp.yaml config using pre-built build step

Sync recommendation

informed by dfinity/portal docs/defi/token-standards/, docs/defi/token-integrations/ — icrc-1.mdx, icrc-2.mdx, icrc-7.mdx, icrc-37.mdx; dfinity/icskills skills/icrc-ledger/SKILL.md; dfinity/examples motoko/nft-creator

[marc0olo]

Review

Must-fix

1. Invalid icp.yaml configuration for local test ledger — Uses recipe: type: custom with candid:/wasm:/config: init_arg_file: keys — none of which are valid icp-cli config. type: custom is a dfx-ism. Should use build: steps: - type: pre-built with url: and init_args: path: per .sources/icp-cli/docs/reference/configuration.md. Note: the icrc-ledger skill itself has the same invalid config, so this is a skill-level issue too.

2. Missing imports in Motoko subaccount snippet — Uses Array.tabulate and Nat8.fromNat but only imports Principal and Blob. Needs import Array "mo:core/Array" and import Nat8 "mo:core/Nat8".

3. PR description Sync recommendation doesn't match <!-- Upstream: --> comment — PR body is missing icskills, examples, and ICRC-7/37 references that appear in the in-page comment. Must match.

4. Needs rebase on main — Branch includes reverse-diffs of merged PRs docs: access management guide #29/docs: asset canister guide #30 and an AGENTS.md change that removes an important instruction. Rebase will clean this up.

Suggestions

1. Unlabeled code fence for Account type pseudo-code — consider adding a candid or text language tag.

2. No icrc1_balance_of canister-side example — CLI section shows balance checking but Rust/Motoko examples are missing for this very common operation.

3. Motoko approve_spender captures caller but never uses it — Either use it for access control or remove for consistency with the Rust version.

4. NFT section could mention deployed ICRC-7 ledger canister IDs if canonical deployments exist.

Verified

• All internal links resolve (token-standards, chain-key-tokens, wallet-integration, onchain-calls)
• Canister IDs and fees match icrc-ledger skill exactly
• Rust CDK API verified: Call::unbounded_wait, .with_arg(), .candid_tuple(), ic_cdk::api::time()
• Rust crate versions match skill (ic-cdk = "0.19", candid = "0.10", icrc-ledger-types = "0.1")
• Motoko Time.now() pattern and type definitions verified
• Subaccount derivation pattern matches both icrc-ledger and ckbtc skills
• CLI commands verified against .sources/icp-cli/docs/reference/cli.md
• Shell substitution warning correct per skill's "Mistakes That Break Your Build"
• Deduplication advice correct (24h window)
• Build passes, no dfx references, Diataxis how-to pattern respected

[marc0olo]

Feedback addressed:

• Must-fix 1: Replaced invalid recipe: type: custom icp.yaml config with correct build: steps: - type: pre-built using url: and init_args: path: per icp-cli config reference
• Must-fix 2: Added missing import Array "mo:core/Array" and import Nat8 "mo:core/Nat8" to Motoko subaccount snippet
• Must-fix 3: Updated PR description sync recommendation to match in-page <!-- Upstream: --> comment (added icskills, examples, ICRC-7/37 references)
• Must-fix 4: Rebased on main — stale reverse-diffs from merged PRs docs: access management guide #29/docs: asset canister guide #30 are gone
• Suggestion 1: Added candid language tag to Account type code fence
• Suggestion 2: Added icrc1_balance_of examples for both Rust and Motoko
• Suggestion 3: Removed unused ({ caller }) capture from Motoko approveSpender
• Suggestion 4: Skipped — no canonical ICRC-7 deployments on mainnet to reference