docs: add proxy canister guide and dfx wallet migration scenario#560
Merged
marc0olo merged 6 commits intoMay 19, 2026
Merged
Conversation
- Add docs/guides/proxy-canister.md: explains why a proxy is needed, local vs connected network setup, --proxy/--cycles usage, authorization model, how the proxy works internally, and a pointer to the wallet migration for dfx users - Add "Replacing the dfx Wallet Canister" section to from-dfx.md: feature comparison table, verified reinstall strategy (cycles and controllers are preserved, only WASM state is wiped), step-by-step migration, alternative fresh-proxy path, and identity considerations - Update local-development.md proxy section to document that only identities present at network-start time are proxy controllers - Add proxy canister to docs/index.md guide listing and sidebar - Add astro-mermaid integration for rendered flowchart diagrams
- Replace --template with correct --subfolder flag for icp new - Remove non-existent dfx wallet managed-canisters and dfx canister list commands - Fix dfx identity get-principal --identity (--identity is a global flag, not a subcommand flag) - Add missing --network ic to all mainnet dfx commands in the migration guide
icp cycles balance/transfer operate on the cycles ledger (not canister computation balances). The correct replacements for dfx wallet send and dfx wallet balance are icp canister top-up and icp canister status.
…keys Both dfx and icp-cli extract the same raw key bytes from PEM and derive the same principal. The claimed mismatch scenario does not exist in practice — icp-cli also handles nonconforming old dfx PKCS#8 PEM files.
lwshang
reviewed
May 19, 2026
lwshang
reviewed
May 19, 2026
lwshang
reviewed
May 19, 2026
lwshang
requested changes
May 19, 2026
- Fix icp canister update-settings -> icp canister settings update (the subcommand is 'settings update', not 'update-settings') - Restructure "Deploy a Fresh Proxy" alternative: move wallet funding to the end so it reads as draining the wallet after verifying the proxy, rather than funding an arbitrary amount right after deployment
lwshang
approved these changes
May 19, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/guides/proxy-canister.md— comprehensive explanation of the proxy canister pattern: why it exists (IC protocol constraints on clients), local vs connected network setup,--proxy/--cyclesusage across all commands, authorization model, how forwarding works internally, and a link to the wallet migration for dfx usersfrom-dfx.md— "Replacing the dfx Wallet Canister": feature comparison table, the verified reinstall strategy (cycles and IC-level controller assignments survive a WASM reinstall, only WASM state is wiped), step-by-step guide, an alternative fresh-proxy path, and identity principal matching considerationslocal-development.mdproxy section — documents that the auto-deployed proxy's controllers are set to all identities present aticp network starttime; identities created afterwards need to be added manuallyindex.mdand sidebar — proxy canister guide added to guides listingastro-mermaidintegration — enablesmermaidcode blocks for rendered flowchart diagrams; used for the proxy flow diagram in the new guideMigration strategy — end-to-end tested
The reinstall approach was verified on a live local dfx network:
dfx canister callandicp canister call --proxy: both working after reinstall