docs: add Canton chain support specification by ganchoradkov · Pull Request #139 · WalletConnectFoundation/docs

ganchoradkov · 2026-03-24T11:15:02Z

Summary

Add new Canton chain support page at wallet-sdk/chain-support/canton.mdx covering the full WalletConnect integration specification
Register Canton in sidebar navigation (docs.json) and ecosystem overview page

What's Documented

Network / Chain Information: Operator-defined CAIP-2 network IDs (no fixed mainnet/testnet), CAIP-10 account format with URL-encoded party IDs
7 RPC Methods (all prefixed with canton_):
- canton_prepareSignExecute — prepare, sign, and execute ledger transactions with multiple signing provider support
- canton_listAccounts — retrieve all configured wallet accounts
- canton_getPrimaryAccount — retrieve the primary wallet account
- canton_getActiveNetwork — discover the active network configuration
- canton_status — check wallet connectivity to the Canton ledger
- canton_ledgerApi — proxy raw Ledger API requests through the wallet
- canton_signMessage — sign arbitrary messages with Ed25519
3 Events: accountsChanged, statusChanged, chainChanged
Auto-approve vs manual-approve classification for read-only vs ledger-mutating methods
dApp SDK method mapping (canton_prepareExecute / canton_prepareExecuteAndWait → canton_prepareSignExecute)
Signing providers: participant, wallet-kernel, blockdaemon with their Ledger API flows
Session lifecycle: Pairing with optionalNamespaces (no hardcoded chains), approval with CAIP-10 accounts
Error codes: 5000, 5001, 5100, 6000

Test plan

Run mint dev and verify the Canton page renders correctly at /wallet-sdk/chain-support/canton
Verify sidebar navigation shows Canton under Chain Support
Verify overview page links to Canton
Check all JSON/TypeScript code blocks render properly
Confirm internal anchor links work (e.g. #canton_getactivenetwork)

Add per-chain specification for Canton Network covering WalletConnect integration with operator-defined networks, Ed25519 signing, and the full RPC method surface (prepareSignExecute, listAccounts, getPrimaryAccount, getActiveNetwork, status, ledgerApi, signMessage). Made-with: Cursor

mintlify · 2026-03-24T11:15:19Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
walletconnect-docs	🟢 Ready	View Preview	Mar 24, 2026, 11:16 AM

Copilot

Pull request overview

Adds documentation for Canton chain support in the Wallet SDK docs, and wires the new page into the Chain Support navigation so integrators can find and follow the WalletConnect JSON-RPC/event surface for Canton.

Changes:

Add a new wallet-sdk/chain-support/canton.mdx specification covering methods, events, session lifecycle, and error codes.
Add Canton to the Chain Support overview page.
Register the Canton page in the docs sidebar (docs.json).

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 4 comments.

File	Description
wallet-sdk/chain-support/overview.mdx	Adds Canton to the ecosystem reference list.
wallet-sdk/chain-support/canton.mdx	Introduces the Canton WalletConnect integration spec (methods/events/session/error codes).
docs.json	Adds Canton to the “Chain Support” navigation group.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-24T11:18:18Z

wallet-sdk/chain-support/canton.mdx

+Read-only methods are auto-approved by the wallet. Methods that mutate the ledger or perform sensitive operations require explicit user approval.
+
+| Method               | Approval     |
+| -------------------- | ------------ |
+| `listAccounts`       | Auto-approve |
+| `getPrimaryAccount`  | Auto-approve |
+| `getActiveNetwork`   | Auto-approve |
+| `status`             | Auto-approve |
+| `ledgerApi`          | Auto-approve |
+| `prepareSignExecute` | Manual       |
+| `signMessage`        | Manual       |


ledgerApi is marked as auto-approve, but the method is described as proxying raw Ledger API requests (including POST). Unless the wallet strictly enforces a read-only allowlist (e.g. only /v2/state/*) this can be used to perform ledger-mutating actions without user approval. Either (a) change ledgerApi to require manual approval, or (b) explicitly document and enforce a read-only/resource allowlist and reject any mutating endpoints.

Suggested change

Read-only methods are auto-approved by the wallet. Methods that mutate the ledger or perform sensitive operations require explicit user approval.

| Method | Approval |

| -------------------- | ------------ |

| `listAccounts` | Auto-approve |

| `getPrimaryAccount` | Auto-approve |

| `getActiveNetwork` | Auto-approve |

| `status` | Auto-approve |

| `ledgerApi` | Auto-approve |

| `prepareSignExecute` | Manual |

| `signMessage` | Manual |

Read-only methods are auto-approved by the wallet. Methods that mutate the ledger or perform sensitive operations require explicit user approval. In particular, `ledgerApi` MUST either (a) require manual user approval for all requests, or (b) be restricted by the wallet to a strictly read-only allowlist of Ledger API resources (for example, `/v2/state/*` and other GET-only endpoints), rejecting any mutating calls.

| Method | Approval |

| -------------------- | ------------------------------------------------ |

| `listAccounts` | Auto-approve |

| `getPrimaryAccount` | Auto-approve |

| `getActiveNetwork` | Auto-approve |

| `status` | Auto-approve |

| `ledgerApi` | Manual **(or auto-approve only for read-only)** |

| `prepareSignExecute` | Manual |

| `signMessage` | Manual |

Copilot · 2026-03-24T11:18:19Z

wallet-sdk/chain-support/canton.mdx

+
+## Notes & Considerations
+
+- All requests and responses comply with JSON-RPC structure (`id`, `jsonrpc`, etc.).


The request examples use the WalletConnect topic/chainId/request envelope, but the note says “All requests and responses comply with JSON-RPC structure (id, jsonrpc, etc.)”. As written, that’s inaccurate/misleading because the example requests omit id/jsonrpc and the JSON-RPC fields are handled by the client layer. Please clarify whether you’re documenting the WC session request envelope vs the underlying JSON-RPC payload, or update the examples to include id/jsonrpc consistently.

Suggested change

- All requests and responses comply with JSON-RPC structure (`id`, `jsonrpc`, etc.).

- WalletConnect requests/responses use the standard `topic/chainId/request` envelope. The `request` field inside that envelope is a JSON-RPC 2.0 payload (`jsonrpc`, `id`, `method`, `params`). For brevity, examples on this page may omit the `jsonrpc` and `id` fields, which are typically managed by the WalletConnect client.

Copilot · 2026-03-24T11:18:19Z

wallet-sdk/chain-support/canton.mdx

+- The `ledgerApi` method acts as a transparent proxy — the wallet handles authentication with the Canton Ledger API. Only `GET` and `POST` are supported; other HTTP methods will return a `5001` error.
+- Party IDs in CAIP-10 accounts are URL-encoded (e.g. `operator::1220abc...` becomes `operator%3A%3A1220abc...`).
+- The `prepareSignExecute` method always performs the full prepare → sign → execute cycle synchronously, responding only when the transaction is complete.
+- The WC session `chainId` (e.g. `canton:devnet`) may differ from the `networkId` in wallet/network records (e.g. `canton:production`). The `chainId` identifies the chain at pairing time, while `networkId` reflects the wallet's internal network configuration.


This page repeatedly shows chainId: canton:devnet in requests while responses report networkId: canton:production, and the note claims chainId may differ from networkId. For CAIP-2/CAIP-10, the network identifier should be consistent across session chainId and returned account/network metadata; otherwise dApps can’t reliably interpret which network they’re on. Please align examples so chainId/networkId match, and/or rename/clarify networkId if it’s an internal label rather than the CAIP-2 identifier.

Suggested change

- The WC session `chainId` (e.g. `canton:devnet`) may differ from the `networkId` in wallet/network records (e.g. `canton:production`). The `chainId` identifies the chain at pairing time, while `networkId` reflects the wallet's internal network configuration.

- The WC session `chainId` (e.g. `canton:devnet`) and any `networkId` returned in account or network metadata MUST refer to the same CAIP-2 network identifier. If the wallet maintains additional internal labels for networks, they should not be confused with or substituted for this CAIP-2 `chainId`.

Copilot · 2026-03-24T11:18:19Z

wallet-sdk/chain-support/canton.mdx

+        },
+        "network": {
+            "networkId": "canton:production",
+            "ledgerApi": "http://127.0.0.1:5003"


The ledgerApi/getActiveNetwork examples return ledgerApi: http://127.0.0.1:5003. Using a loopback URL in docs is confusing because it’s not reachable from most clients; consider replacing with a placeholder host (e.g. https://<ledger-api-host>) and/or explicitly stating that this URL is only meaningful from the wallet’s execution environment.

Suggested change

"ledgerApi": "http://127.0.0.1:5003"

"ledgerApi": "https://<ledger-api-host>"

jakubuid · 2026-03-24T11:29:34Z

wallet-sdk/chain-support/canton.mdx

+const CANTON_WC_METHODS = [
+    'prepareSignExecute',


I'm in favor of adding canton_ prefix. You?

Out of curiosity, what is the reason for re-mapping prepareExecute and prepareExecuteAndWait?

hey @mjuchli-da hey, we did it because both methods this way result in single prepareSignExecute method on the other (wallet side), makes handling easier (one method instead of two) and the handling is the same. If you think we should keep both thats fine as well

the nature of the two are different in the sense that prepareExecute is async and prepareExecuteAndWait is blocking. How are you planning to mix the two? It is reasonable to assume that every wallet can provide the blocking version?

It is reasonable to assume that every wallet can provide the blocking version?

yes, thats the idea which is in line with pretty much every other blockchain so implementing apps/wallets are already familiar with the pattern i.e. request -> wallet responds -> request resolves with the result

Okay I think I understand the reasoning behind it and see that similar mappings are being done for other chains. That said, I am a bit concerned about the fact that we deviate from the CIP-103 API naming here and wonder if it wouldn't be better to replicate the logic for both method names individually, so that clients can stick to standardized naming. I"m curious what you think on this?

Made-with: Cursor

Copilot AI review requested due to automatic review settings March 24, 2026 11:15

Copilot started reviewing on behalf of ganchoradkov March 24, 2026 11:15 View session

mintlify bot deployed to staging March 24, 2026 11:16 View deployment

Copilot AI reviewed Mar 24, 2026

View reviewed changes

jakubuid reviewed Mar 24, 2026

View reviewed changes

docs: prefix prepareSignExecute with canton_ namespace

cc9cd1c

Made-with: Cursor

mintlify bot deployed to staging March 24, 2026 13:04 View deployment

docs: prefix all Canton methods with canton_ namespace

5ab50fa

Made-with: Cursor

mintlify bot deployed to staging April 8, 2026 09:19 View deployment

jakubuid mentioned this pull request Apr 9, 2026

feat: add Canton blockchain integration to sample wallet reown-com/reown-kotlin#361

Merged

5 tasks

ignaciosantise mentioned this pull request Apr 9, 2026

feat(rn_cli_wallet): add Canton blockchain support reown-com/react-native-examples#469

Merged

8 tasks

jakubuid mentioned this pull request Apr 10, 2026

feat: add Canton blockchain integration to sample wallet reown-com/reown-swift#301

Merged

5 tasks


		## Notes & Considerations

		- All requests and responses comply with JSON-RPC structure (`id`, `jsonrpc`, etc.).

	- All requests and responses comply with JSON-RPC structure (`id`, `jsonrpc`, etc.).
	- WalletConnect requests/responses use the standard `topic/chainId/request` envelope. The `request` field inside that envelope is a JSON-RPC 2.0 payload (`jsonrpc`, `id`, `method`, `params`). For brevity, examples on this page may omit the `jsonrpc` and `id` fields, which are typically managed by the WalletConnect client.

	- The WC session `chainId` (e.g. `canton:devnet`) may differ from the `networkId` in wallet/network records (e.g. `canton:production`). The `chainId` identifies the chain at pairing time, while `networkId` reflects the wallet's internal network configuration.
	- The WC session `chainId` (e.g. `canton:devnet`) and any `networkId` returned in account or network metadata MUST refer to the same CAIP-2 network identifier. If the wallet maintains additional internal labels for networks, they should not be confused with or substituted for this CAIP-2 `chainId`.

	"ledgerApi": "http://127.0.0.1:5003"
	"ledgerApi": "https://<ledger-api-host>"

Conversation

ganchoradkov commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's Documented

Test plan

Uh oh!

mintlify bot commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

jakubuid Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

ganchoradkov Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

mjuchli-da Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

ganchoradkov Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

mjuchli-da Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

ganchoradkov Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

mjuchli-da Apr 8, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ganchoradkov commented Mar 24, 2026 •

edited

Loading

mintlify bot commented Mar 24, 2026 •

edited

Loading