docs(connect): document the gateway, WalletConnect and ledger route contracts

[fernandomg]

Summary

Closes #2

canton-connect connects through a Wallet Gateway and through WalletConnect with no library change, but nothing said so: a developer had to guess the configuration, learn by trial that a reload restores only a gateway registered at startup, and hit the gateway refusing a ledger route spelled with the value inline. Both paths were walked end to end (connect, reload, lock, disconnect, popup checks, a real transaction) and every finding is now on the surfaces a consumer reads: the README, the config and hook JSDoc, the wagmi comparison, the architecture seam.

Changes

• architecture: Remote gateway, WalletConnect and Ledger reads sections; Add a remote/OIDC connector for the Wallet Gateway path #2 leaves Deferred
• README: how to configure a gateway and WalletConnect, the restore, lock and network id rules, a local gateway recipe, the templated route rule
• CantonConnectConfig examples show networkId, walletConnectProjectId and a RemoteAdapter
• useLedger prose states the route rule and its example uses path
• coming-from-wagmi: connectors and read-hooks rows

Deviations

• WalletConnect and the ledger route rule were documented in the same PR, not only the gateway: the walks proved them together and the rules are one contract seen from three wallets

Acceptance criteria

• a dApp with a gateway in additionalAdapters connects, reloads with the session intact, locks, disconnects, and sends a transaction, each step recorded
• the popup check passes on a gateway
• the extension path walked again on the same build, unchanged
• no change outside canton-connect and canton-dappbooster; anything that seemed to need one is documented as a follow-up
• useWalletStatus behavior on lock is decided and documented
• canton-connect/architecture.md lists the gateway as supported, with the configuration and the local recipe
• the session-wipe entry exists in the SDK issues doc

Test plan

Automated tests

1. pnpm lint, pnpm -C canton-connect typecheck, pnpm docs:check (compiles every example): all green on the branch.

Manual verification

1. Check out feat/frontend-walletconnect: the demo with WalletConnect in its picker, on top of this branch.
2. Set VITE_WC_PROJECT_ID in the root .env (a free Reown project id) and bring the stack up with scripts/dev-stack.sh up.
3. Run Carpincho's web build (pnpm dev in its repo, same id in its .env.local) and, for the gateway, npx @canton-network/wallet-gateway-remote@1.10.0 -c config.json with the config shape from the README.
4. On http://localhost:3012: connect through WalletConnect (pair from Carpincho with the popup's URI), reload, disconnect; then connect through the gateway (type its URL in the picker), reload, disconnect. What you see is what the README says: WalletConnect restores after reload, the typed gateway does not, lock never shows on either.

Breaking changes

None.

Checklist

• Self-reviewed my own diff
• Tests added or updated (docs only; the examples are compiled by docs:check)
• Docs updated (if applicable)
• No unrelated changes bundled in

Screenshots

Screen.Recording.2026-09-09.at.20.34.06.mov

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
demo.canton-dappbooster	Ready	Preview	Sep 9, 2026 7:07pm UTC
docs.canton-dappbooster	Building	Preview	Sep 9, 2026 7:07pm UTC

[Copilot]

🟡 Changes recommended

The README and architecture.md give contradictory statements about whether useWalletStatus().isLocked can become true over WalletConnect, which should be reconciled before this documentation is published.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This documentation-only PR closes #2 by documenting the Wallet Gateway (remote RemoteAdapter), WalletConnect, and the Canton JSON API "templated route" contract across the surfaces a canton-connect consumer reads. No code changes: the SDK already supports all three paths through additionalAdapters, so the work is to make the configuration, restore/lock/networkId rules, and the ledgerApi route rule discoverable in the README, JSDoc, the wagmi comparison, and the architecture seam. It also drops the now-implemented "Remote / Wallet Gateway" item from the architecture Deferred list.

Changes:

• Adds README + architecture sections for configuring a gateway and WalletConnect, including restore/lock/networkId behavior and a local gateway recipe.
• Expands the CantonConnectConfig and useLedger JSDoc examples to show walletConnectProjectId, a RemoteAdapter, and the templated path-based ledger route.
• Adds/updates coming-from-wagmi.md rows for connectors and read hooks.

File summaries

File	Description
canton-connect/src/types.ts	Extends CantonConnectConfig JSDoc with a WalletConnect example and a RemoteAdapter gateway example (stays within docs-check caps).
canton-connect/src/hooks/useLedger.ts	Documents the templated-route rule and updates the @example to use resource + path.
canton-connect/README.md	Adds "Connecting through a Wallet Gateway" and "Connecting through WalletConnect" sections plus the ledger route rule.
canton-connect/coming-from-wagmi.md	Adds a connectors row and updates the read-hook row to reflect the templated route.
canton-connect/architecture.md	Adds Remote gateway, WalletConnect, and Ledger reads seams; removes the gateway item from Deferred.

One issue worth reconciling: the README states useWalletStatus().isLocked "never turns true" over WalletConnect, while the newly added architecture.md says it "stays false until the wallet answers a request again" (implying it can become true). These two consumer-facing docs contradict each other for the WalletConnect case.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.