Canton Network Wallet

Canton Network is a public, permissioned blockchain built for regulated financial assets. Applications on Canton act on behalf of parties, and an external party is identified by the fingerprint of an Ed25519 public key. Whoever controls that private key controls the party: they can sign the topology transactions that define it and every ledger transaction it submits.

The Canton Wallet Gateway is the reference wallet implementation of the Canton Network. It delegates all signing to a pluggable signing driver. The Securosys signing driver is such a driver: it generates the party key inside a Securosys Primus HSM or CloudHSM and performs every signature through the Transaction Security Broker (TSB) REST API.

The driver was contributed by Securosys and is part of the upstream Canton Network wallet repository. It requires no fork and no patched Wallet Gateway build.

Why This Matters

A Canton external party is only as trustworthy as the key behind it. By default the Wallet Gateway stores that key in its signing store database, or leaves it in the keystore of a Canton participant node. In both cases the private key exists in software, on a host that also runs application code, and a copy of the database or a snapshot of the host is enough to impersonate the party — sign transfers, reassign holdings, or rewrite the party's topology.

Unlike a payment reversal, a settled on-ledger transfer cannot be undone. Prevention is the only control that works.

With the Securosys signing driver:

• The Ed25519 party key is generated inside the HSM and marked non-extractable. No copy of the private key ever exists outside the HSM boundary, so a compromised Wallet Gateway host, database dump, or backup does not yield a plaintext key.
• Every signature is an explicit, logged HSM request, carrying the internal transaction id, the user identifier, and the key identifier as metadata.
• Signing authority can be constrained with Smart Key Attributes (SKA), so that releasing a signature requires an m-of-n quorum of independent approvers rather than possession of an API key. See Approval Workflows.
• Key custody is consolidated: the same HSM partition, the same operational procedures, and the same audit trail already used for the rest of the organisation's key material.

Architecture

The Wallet Gateway keeps its wallet, party, and transaction state, but holds no key material for Securosys-backed wallets. Key generation, key storage, and signing all happen inside the tamper-proof HSM. The TSB is the REST front end that orchestrates the SKA workflows with the approvers.

The Securosys signing driver registers itself with the Wallet Gateway under the signing provider id securosys and in EXTERNAL party mode. The signing provider is selected per party, so Securosys-backed wallets can coexist with other providers in the same Gateway instance.

Party creation

1. The Gateway calls createKey. The driver creates an Ed25519 key in the HSM through the TSB.
2. The Gateway derives the party namespace fingerprint from the returned public key and builds the Canton topology transactions for the new party.
3. The multi-hash of those topology transactions is sent to POST /v1/sign. TSB returns a request id, which the Gateway stores as the wallet's external transaction id.
4. The Gateway polls the TSB for the signature result.
5. When the request reaches EXECUTED, the Gateway retrieves the signature and allocates the party. Until then the wallet stays in status initialized with reason TOPOLOGY_TRANSACTION_PENDING, and party allocation completes on a later call.

Transaction signing

1. The dApp prepares a transaction; the participant returns the prepared transaction and its hash.
2. The Gateway resolves the wallet's key by its public-key-derived label and calls POST /v1/sign with the prepared transaction hash as the payload.
3. TSB returns a request id immediately. The Gateway polls GET /v1/request/{id} until the request is executed, then submits the signature to the ledger.

Because signing is request-based rather than a blocking call, the same code path works whether a signature is released immediately or only after human approval.

Air-Gapped deployment

The HSM does not have to be reachable from the online environment at all. With the Air-Gapped Profile TSB, the Wallet Gateway keeps talking to a TSB over REST, but that TSB holds no key material — it records the sign request, collects the approvals, and stages them for export to the offline environment where the HSM lives.

1. The driver calls POST /v1/sign as usual. The Air-Gapped Profile TSB records the request and returns a request id.
2. Approvers fetch and authorize their tasks with POST /v1/approval. The request stays PENDING, with result set to Execution shall be made with offline HSM and an inputOfflineHsm object carrying the sign request and the signed approvals.
3. The approved request is exported — as JSON from GET /v1/request/{id}, or as one or more QR codes from GET /v1/request/qrCode/{id} — and physically carried into the air-gapped environment on a USB device or on paper.
4. Inside the air-gapped environment a local-profile TSB submits it to the HSM with POST /v1/synchronousSign. The HSM checks the approvals against the key policy and against the exact payload before signing.
5. The signature is carried back out and inserted into the online TSB with PUT /v1/resultFromOfflineHsm. The request becomes EXECUTED and the Wallet Gateway's next poll picks up the signature.

The Wallet Gateway sees inputOfflineHsm in the transaction metadata, so the request staged for export is visible from the Gateway.

warning

The ceremony has to fit inside Canton's submission delay — see Timing and transaction validity. An air-gapped process that takes days will produce a valid HSM signature that the ledger then refuses as too old.

Timing and transaction validity

Approval quorums and air-gapped ceremonies add human latency to signing. The Securosys side will wait; Canton will not.

• The Wallet Gateway does not time out. POST /v1/sign returns a request id immediately, so the driver never blocks on a signature. The Gateway's signing worker re-polls every server.signingWorker.pollInterval milliseconds (default 5000) for any transaction that has an external transaction id, with no attempt limit and no deadline. A wallet whose topology transaction is still pending stays at initialized and is completed on a later poll. Because the request id is persisted, a Gateway restart during the wait is harmless.
• Canton prepared transactions have a submission delay budget, and this is the binding constraint. A transaction must be executed within a limited window after it was prepared. For Canton Coin end-user token-standard operations that window is 24 hours, raised from the earlier 10 minutes by CIP-0107 precisely because external signing "often requires explicit human approval sometimes even from multiple people". Reward minting is still subject to the 10-minute delay.

warning

Plan approval and air-gap ceremonies to complete well inside the applicable submission delay. The HSM will happily sign a request days later, and Canton will then reject the result. Consider applying quorums to high-value parties, or to the topology transactions that define a party, rather than to every transaction in a deployment.

Approval Workflows with SKA

Keys are created with an empty SKA policy: no approval is required, and signatures are released as soon as TSB executes the request. This keeps the default deployment simple.

The policy can be tightened out-of-band — through POST /v1/synchronousModify or the Authorization App — to add a ruleUse requiring a quorum of approvers before any signature is produced. No change to the Wallet Gateway is needed:

• Signing requests stay in TSB status PENDING until the quorum is reached.
• The Securosys signing driver maps that to Wallet Gateway status pending and surfaces approvedBy, notYetApprovedBy, and rejectedBy in the transaction metadata.
• A rejected, cancelled, or expired request maps to rejected, and the Gateway marks the affected wallet or transaction accordingly.

The same mechanism supports a ruleBlock policy, which lets a quorum block a key immediately — an effective kill switch for a compromised wallet, without touching the ledger.

Supported Operations

Wallet Gateway operation	Support	TSB endpoint
createKey	Yes — Ed25519, non-extractable	POST /v1/key, PATCH /v1/key/changeAttributes
getKeys	Yes — enumerates the partition	GET /v1/key, POST /v1/key/attributes
signTransaction	Yes — returns the TSB request id	POST /v1/sign
getTransaction	Yes	GET /v1/request/{id}
getTransactions	By request id; by public key from the driver cache	GET /v1/request/{id}, POST /v1/filteredRequests
getConfiguration / setConfiguration	Yes — secrets are masked on read	—
signMessage	Not supported	—
subscribeTransactions	Not supported — the Gateway polls	—

References

• Securosys signing driver in the Canton Network wallet repository
• @canton-network/core-signing-securosys on npm
• Canton Wallet Gateway signing providers