From 139619500a6d2597d13516f0dea972ddba40f802 Mon Sep 17 00:00:00 2001 From: Marco Walz Date: Wed, 18 Mar 2026 15:35:30 +0100 Subject: [PATCH] fix: move wallet-integration from authentication to DeFi section Wallet integration covers ICRC signer standards for transaction approval, not authentication. Moving it to guides/defi/ where it belongs alongside token-ledgers and chain-key-tokens. Closes #25 --- .docs-plan/decisions.md | 7 +++++++ .docs-plan/developer-journey.md | 4 ++-- .docs-plan/icp-cli-examples-inventory.md | 4 ++-- .docs-plan/jssdk-skills-mapping.md | 4 ++-- .docs-plan/migration-plan.md | 4 ++-- .docs-plan/portal-deep-dive.md | 2 +- .docs-plan/synthesis.md | 4 ++-- docs/getting-started/what-next.md | 2 +- docs/guides/authentication/internet-identity.md | 2 +- docs/guides/{authentication => defi}/wallet-integration.md | 2 +- docs/reference/token-standards.md | 2 +- 11 files changed, 22 insertions(+), 15 deletions(-) rename docs/guides/{authentication => defi}/wallet-integration.md (98%) diff --git a/.docs-plan/decisions.md b/.docs-plan/decisions.md index 8608e17e..3bea0631 100644 --- a/.docs-plan/decisions.md +++ b/.docs-plan/decisions.md @@ -169,3 +169,10 @@ Record decisions that constrain future work — things an agent needs to know th **Decision:** (1) Merged all binding-generation content into `candid.md` as a "Binding generation" section. (2) Removed the `binding-generation.md` stub. (3) Updated `didc` tool table to focus on validation/encoding (removed `didc bind` rows). (4) Documented both auto-generated and hand-written `.did` file paths for Motoko. (5) Updated `onchain-calls.md` canister discovery section with a cross-link to the new bindings section. (6) Removed Beads task and updated migration plan dependencies. **Rationale:** The developer flow is linear: define interface → generate `.did` → generate bindings → use them. Splitting bindings into a separate page creates an artificial seam. The Candid guide is the natural home for the full flow. **Alternatives considered:** Keep separate page (creates overlap and navigation friction), move all `.did` generation to the bindings page (splits related content) + +## 2026-03-18: Move wallet-integration from authentication to DeFi section + +**Context:** The wallet-integration page covers ICRC signer standards (ICRC-21/25/27/29/49) for transaction approval, not authentication. The wallet-integration icskill itself distinguishes wallet signers (transaction approval) from Internet Identity (authentication/login). Under `guides/authentication/`, the page was grouped with II and verifiable credentials — a different concern. +**Decision:** Move `guides/authentication/wallet-integration.md` → `guides/defi/wallet-integration.md`. Update cross-links in `what-next.md`, `internet-identity.md`, and `token-standards.md`. Update Beads task title. No sidebar config change needed (both directories use `autogenerate`). +**Rationale:** Transaction signing is closer to the DeFi/token workflow than to authentication. Developers looking for wallet transaction approval would look in DeFi, not Authentication. Discussed in PR #23 and filed as GitHub issue #25. +**Alternatives considered:** Keep in authentication (misleading grouping), create a new "Wallets" subsection (over-engineering for one page) diff --git a/.docs-plan/developer-journey.md b/.docs-plan/developer-journey.md index 2188b35b..e44aa819 100644 --- a/.docs-plan/developer-journey.md +++ b/.docs-plan/developer-journey.md @@ -66,7 +66,7 @@ | Framework integration | guides/frontends/frameworks.md | [JS SDK](https://js.icp.build) | — | | Custom domains | guides/frontends/custom-domains.md | — | — | | User login | guides/authentication/internet-identity.md | — | `icp-internet-identity` | -| Wallet connection | guides/authentication/wallet-integration.md | — | — | +| Wallet connection | guides/defi/wallet-integration.md | — | — | | Response verification | guides/frontends/certification.md | — | — | **Templates used:** `react-starter`, `vanilla-js-starter`. @@ -348,7 +348,7 @@ guides/ frameworks.md authentication/ # Add user login internet-identity.md - wallet-integration.md + wallet-integration.md (moved to guides/defi/) testing/ # Test before deploying strategies.md pocket-ic.md diff --git a/.docs-plan/icp-cli-examples-inventory.md b/.docs-plan/icp-cli-examples-inventory.md index 27c03a48..eb1c2c21 100644 --- a/.docs-plan/icp-cli-examples-inventory.md +++ b/.docs-plan/icp-cli-examples-inventory.md @@ -27,7 +27,7 @@ Compiled 2026-03-11. Sources: icp-cli/docs (33 files), icp-cli-recipes (4 recipe | `guides/canister-snapshots.md` | guides/canister-management/snapshots | sync candidate — this IS the snapshots guide | | `guides/canister-migration.md` | guides/canister-management/lifecycle | link — advanced canister migration | | `guides/managing-environments.md` | guides/canister-management/cycles-management | link — multi-env setup | -| `guides/managing-identities.md` | guides/authentication/wallet-integration | link — identity management reference | +| `guides/managing-identities.md` | guides/defi/wallet-integration | link — identity management reference | | `guides/tokens-and-cycles.md` | guides/canister-management/cycles-management, guides/defi/token-ledgers | link — ICP/cycles/ICRC-1 token commands | | `guides/containerized-networks.md` | guides/testing/strategies | link — Docker-based test networks | | `guides/using-recipes.md` | getting-started/project-structure | link — how to configure build recipes | @@ -228,7 +228,7 @@ canisters: | hosting/godot-html5-template | Godot | Godot game hosting | guides/frontends/frameworks | Link | | hosting/unity-webgl-template | Unity | Unity WebGL hosting | guides/frontends/frameworks | Link | | hosting/my_crypto_blog | JS | Blog with crypto features | guides/frontends/asset-canister | Link | -| hosting/oisy-signer-demo | JS | OISY wallet signer demo | guides/authentication/wallet-integration | Link | +| hosting/oisy-signer-demo | JS | OISY wallet signer demo | guides/defi/wallet-integration | Link | | svelte/svelte-motoko-starter | Svelte+Motoko | Svelte + Motoko starter | guides/frontends/frameworks | Link | | svelte/sveltekit-starter | SvelteKit | SvelteKit starter | guides/frontends/frameworks | Link | diff --git a/.docs-plan/jssdk-skills-mapping.md b/.docs-plan/jssdk-skills-mapping.md index 3ec93070..7a799d31 100644 --- a/.docs-plan/jssdk-skills-mapping.md +++ b/.docs-plan/jssdk-skills-mapping.md @@ -57,7 +57,7 @@ | `sns-launch` | `guides/governance/launching`, `guides/governance/managing`, `guides/governance/testing`, `concepts/governance` | Maps to all three governance guide pages | | `stable-memory` | `guides/backends/data-persistence`, `guides/canister-management/lifecycle`, `concepts/orthogonal-persistence` | Primary is data-persistence; lifecycle covers upgrade patterns | | `vetkd` | `concepts/vetkeys`, `guides/security/data-integrity` | Primary is concepts/vetkeys; security/data-integrity for encryption use cases | -| `wallet-integration` | `guides/authentication/wallet-integration` | Direct 1:1 mapping | +| `wallet-integration` | `guides/defi/wallet-integration` | Direct 1:1 mapping | | `wallet` (alias) | (same as `cycles-management`) | Not a separate mapping needed | ## JS SDK to Docs Pages Mapping @@ -71,7 +71,7 @@ | | `guides/canister-calls/candid` | Agent/actor creation from JS side | | | `concepts/app-architecture` | Frontend-to-canister communication overview | | **Auth** (`@icp-sdk/auth`) | `guides/authentication/internet-identity` | "Frontend integration" section; link to https://js.icp.build/auth | -| | `guides/authentication/wallet-integration` | Auth prerequisites section | +| | `guides/defi/wallet-integration` | Auth prerequisites section | | | `guides/frontends/frameworks` | Auth setup in React/Svelte/Vue apps | | **Canisters** (`@icp-sdk/canisters`) | `guides/frontends/asset-canister` | "Programmatic uploads" section; link to https://js.icp.build/canisters | | | `guides/defi/token-ledgers` | JS ledger actor usage examples | diff --git a/.docs-plan/migration-plan.md b/.docs-plan/migration-plan.md index 1995ba48..bad17557 100644 --- a/.docs-plan/migration-plan.md +++ b/.docs-plan/migration-plan.md @@ -223,7 +223,7 @@ These pages fill out the docs site with important secondary content. | 43 | 4 | `guides/canister-management/snapshots.md` | M | lifecycle | Portal snapshots.mdx; icp-cli canister-snapshots | rewrite, sync | | 44 | 3 | `guides/frontends/custom-domains.md` | M | asset-canister | Portal custom-domains/ (2 files) | rewrite | | 45 | 3+ | `guides/frontends/certification.md` | M | asset-canister, certified-variables | Portal asset-security.mdx | rewrite | -| 46 | 4 | `guides/authentication/wallet-integration.md` | M | internet-identity | Portal integrate-misc-wallets.mdx; icskills: wallet-integration | rewrite | +| 46 | 4 | `guides/defi/wallet-integration.md` | M | internet-identity | Portal integrate-misc-wallets.mdx; icskills: wallet-integration | rewrite | ### Sprint 6: Canister Calls, Production, Security, Tools (11 pages) @@ -368,7 +368,7 @@ concepts/network-overview.md getting-started/project-structure.md └── guides/frontends/asset-canister.md ├── guides/authentication/internet-identity.md - │ ├── guides/authentication/wallet-integration.md + │ ├── guides/defi/wallet-integration.md │ └── guides/authentication/verifiable-credentials.md ├── guides/frontends/custom-domains.md ├── guides/frontends/certification.md (also needs: certified-variables) diff --git a/.docs-plan/portal-deep-dive.md b/.docs-plan/portal-deep-dive.md index 747f12d6..a5450991 100644 --- a/.docs-plan/portal-deep-dive.md +++ b/.docs-plan/portal-deep-dive.md @@ -50,7 +50,7 @@ |------------|---------------|--------|-------------------|----------|-------| | building-apps/authentication/overview.mdx | explanation | ALREADY-PLANNED | guides/authentication/internet-identity.md | high | Auth overview | | building-apps/authentication/integrate-internet-identity.mdx | how-to | KEEP-REWRITE | guides/authentication/internet-identity.md | high | II integration guide | -| building-apps/authentication/integrate-misc-wallets.mdx | how-to | KEEP-REWRITE | guides/authentication/wallet-integration.md | medium | NFID, Plug, etc. | +| building-apps/authentication/integrate-misc-wallets.mdx | how-to | KEEP-REWRITE | guides/defi/wallet-integration.md | medium | NFID, Plug, etc. | | building-apps/authentication/alternative-origins.mdx | how-to | KEEP-REWRITE | guides/authentication/internet-identity.md | medium | Alternative origins for II | | building-apps/authentication/independently-verifying-ic-signatures.mdx | reference | KEEP-REWRITE | guides/security/data-integrity.md | low | Signature verification | diff --git a/.docs-plan/synthesis.md b/.docs-plan/synthesis.md index afd2b653..c0db0e46 100644 --- a/.docs-plan/synthesis.md +++ b/.docs-plan/synthesis.md @@ -66,7 +66,7 @@ | # | Path | Title | doc_type | level | Content Brief | Source Material | Cross-Links | Priority | |---|------|-------|----------|-------|---------------|-----------------|-------------|----------| | 23 | `guides/authentication/internet-identity.md` | Internet Identity | how-to | intermediate | Integrate passkey-based authentication. Frontend setup with @icp-sdk/auth, delegation handling, principal-per-app isolation, alternative origins. Unity native app integration. | Portal building-apps/authentication/overview.mdx, integrate-internet-identity.mdx, alternative-origins.mdx; icskills: internet-identity; JS SDK: @icp-sdk/auth; examples: internet_identity_integration (Motoko), encrypted-notes-dapp-vetkd (both), unity native-apps | concepts/security, guides/frontends/frameworks, reference/internet-identity-spec | P0 | -| 24 | `guides/authentication/wallet-integration.md` | Wallet Integration | how-to | advanced | Connect ICRC signer-standard wallets (OISY, Plug, NFID). ICRC-21/25/27/29/49 standards, popup wallet model, consent messages. | Portal building-apps/authentication/integrate-misc-wallets.mdx; icskills: wallet-integration; examples: oisy-signer-demo; icp-cli guides/managing-identities.md | guides/authentication/internet-identity, reference/token-standards | P1 | +| 24 | `guides/defi/wallet-integration.md` | Wallet Integration | how-to | advanced | Connect ICRC signer-standard wallets (OISY, Plug, NFID). ICRC-21/25/27/29/49 standards, popup wallet model, consent messages. | Portal building-apps/authentication/integrate-misc-wallets.mdx; icskills: wallet-integration; examples: oisy-signer-demo; icp-cli guides/managing-identities.md | guides/authentication/internet-identity, reference/token-standards | P1 | ### Guides -- Canister Calls (3 pages) @@ -174,7 +174,7 @@ | 68 | `reference/system-canisters.md` | System Canisters | reference | intermediate | Inventory of system-level canisters: NNS canisters (governance, ledger, registry, CMC, cycles minting), Internet Identity, ICP ledger with canister IDs. | Portal references/system-canisters; icskills: ic-dashboard | reference/management-canister, concepts/governance | P1 | | 69 | `reference/protocol-canisters.md` | Protocol Canisters | reference | intermediate | Canisters that implement protocol-level features: Bitcoin canister, EVM RPC canister, exchange rate canister, SNS-W. Canister IDs and interfaces. | Portal references/ (scattered); icskills: ckbtc, evm-rpc | guides/chain-fusion/bitcoin, guides/chain-fusion/ethereum, reference/system-canisters | P1 | | 70 | `reference/application-canisters.md` | Application Canisters | reference | intermediate | Notable application-layer canisters: asset canister, SNS canisters. Canister IDs, interfaces, versioning. | Portal references/ (scattered); icskills: asset-canister, sns-launch | guides/frontends/asset-canister, guides/governance/launching | P2 | -| 71 | `reference/token-standards.md` | Token Standards | reference | intermediate | ICRC-1 (fungible transfers), ICRC-2 (approve/transferFrom), ICRC-3 (transaction log), ICRC-7 (NFT). Standard interfaces, canister IDs for ledgers. | Portal defi/tokens/token-standards files; icskills: icrc-ledger, wallet-integration | guides/defi/token-ledgers, guides/authentication/wallet-integration | P0 | +| 71 | `reference/token-standards.md` | Token Standards | reference | intermediate | ICRC-1 (fungible transfers), ICRC-2 (approve/transferFrom), ICRC-3 (transaction log), ICRC-7 (NFT). Standard interfaces, canister IDs for ledgers. | Portal defi/tokens/token-standards files; icskills: icrc-ledger, wallet-integration | guides/defi/token-ledgers, guides/defi/wallet-integration | P0 | | 72 | `reference/cycles-costs.md` | Cycles Costs | reference | intermediate | Exact cycle costs for compute, storage, HTTPS outcalls, signing, canister creation. Cost tables, comparison with cloud pricing. Resource limits. | Portal building-apps/canister-management/resource-limits.mdx, defi cost tables; reference/subnet-types for pricing tiers | guides/canister-management/cycles-management, concepts/reverse-gas-model | P0 | | 73 | `reference/subnet-types.md` | Subnet Types Reference | reference | intermediate | All subnet types: application, system, European, fiduciary, Bitcoin, II. Node counts, replication factors, cycle cost multipliers. | Portal building-apps/developing-canisters/deploy-specific-subnet.mdx; icp-cli guides/deploying-to-specific-subnets.md | guides/canister-management/subnet-selection, reference/cycles-costs | P1 | | 74 | `reference/execution-errors.md` | Execution Errors | reference | intermediate | Common canister execution errors with explanations and fixes. Trap codes, out-of-cycles, instruction limit exceeded, memory limit, call context errors. | Portal building-apps/canister-management/trapping.mdx, resource-limits.mdx | guides/canister-management/lifecycle, guides/canister-management/optimization, reference/cycles-costs | P1 | diff --git a/docs/getting-started/what-next.md b/docs/getting-started/what-next.md index 44240fc2..c28c35bf 100644 --- a/docs/getting-started/what-next.md +++ b/docs/getting-started/what-next.md @@ -46,7 +46,7 @@ ICP can serve web assets directly from the blockchain through an asset canister, - [Framework integration](../guides/frontends/frameworks.md) -- use React, Vue, Svelte, or other frameworks - [Custom domains](../guides/frontends/custom-domains.md) -- serve your app from your own domain name - [Internet Identity](../guides/authentication/internet-identity.md) -- add passwordless authentication -- [Wallet integration](../guides/authentication/wallet-integration.md) -- connect user wallets +- [Wallet integration](../guides/defi/wallet-integration.md) -- connect user wallets ## Chain fusion (cross-chain) diff --git a/docs/guides/authentication/internet-identity.md b/docs/guides/authentication/internet-identity.md index 789dac08..1879bd1a 100644 --- a/docs/guides/authentication/internet-identity.md +++ b/docs/guides/authentication/internet-identity.md @@ -20,5 +20,5 @@ Integrate Internet Identity (II) for passkey-based user authentication. Cover fr - concepts/security -- identity and trust - guides/frontends/frameworks -- framework-specific auth setup -- guides/authentication/wallet-integration -- alternative to II +- guides/defi/wallet-integration -- alternative to II - reference/internet-identity-spec -- protocol details diff --git a/docs/guides/authentication/wallet-integration.md b/docs/guides/defi/wallet-integration.md similarity index 98% rename from docs/guides/authentication/wallet-integration.md rename to docs/guides/defi/wallet-integration.md index becacacf..28859097 100644 --- a/docs/guides/authentication/wallet-integration.md +++ b/docs/guides/defi/wallet-integration.md @@ -2,7 +2,7 @@ title: "Wallet Integration" description: "Connect ICRC signer-standard wallets like OISY, Plug, and NFID" sidebar: - order: 2 + order: 4 icskills: [wallet-integration] --- diff --git a/docs/reference/token-standards.md b/docs/reference/token-standards.md index b0e6f936..fb79cab9 100644 --- a/docs/reference/token-standards.md +++ b/docs/reference/token-standards.md @@ -17,5 +17,5 @@ Reference for ICP token standards. Document ICRC-1 (fungible token transfers, ba - guides/defi/token-ledgers -- practical token operations -- guides/authentication/wallet-integration -- ICRC signer standards +- guides/defi/wallet-integration -- ICRC signer standards - guides/defi/chain-key-tokens -- ckBTC/ckETH are ICRC-1 tokens