Canton-EVM Bridge

What This System Does

The Canton-Zenith Bridge is a two-way token bridge that allows digital assets to move between two distinct financial infrastructure layers: the Canton ledger (a privacy-preserving, enterprise-grade distributed ledger built on Daml) and the Zenith EVM (an Ethereum-compatible blockchain). A user with assets on Canton can "bridge in" to receive equivalent ERC-20 tokens on the EVM; those tokens can later be "bridged out" to reclaim the original Canton assets. At no point are assets duplicated: the Canton-side tokens are held in escrow for the duration of their EVM representation, and the EVM tokens are burned before the Canton escrow is released.

The bridge is designed for regulated, institutional use. It uses a multi-party validator threshold (M-of-N) rather than trusting any single operator. Every mint on the EVM requires cryptographic signatures from at least M independent validators. Every Canton escrow release requires the same M-of-N threshold, verified in Daml smart contract code. Admin operations on the EVM are time-locked behind a 48-hour governance delay, enforced by a TimelockController controlled by a Safe multisig.

Atomicity is enforced at the Daml transaction layer using Canton's externalCall primitive, which embeds the EVM transaction submission inside the same Canton transaction as the escrow state change.

Current Security Posture

All critical and high vulnerabilities identified during the red-team review phase have been remediated. The system has moved from a devnet-only proof-of-concept (with hardcoded private keys, unauthenticated endpoints, and shell injection) to a hardened architecture with authenticated endpoints, HSM-ready key management, mutual TLS, AML/sanctions screening, SQLite-backed replay prevention, and supply parity monitoring.

The architecture is not yet production-ready. It requires external security audits (Solidity, Daml, backend, cryptographic protocol), completion of the BridgeOperator external party migration, and deployment of production HSM key storage.

Key Risks and Mitigations

Component Overview

+---------------------------------------------------------------------+
|                         Canton Ledger                               |
|  +--------------------------------------------------------------+   |
|  | Bridge.daml contracts                                        |   |
|  |  BridgeWorkflow  BridgeRegistry  AddressMapping              |   |
|  |  BridgeOperation BridgeEscrowHolding ValidatorConfigProposal |   |
|  +--------------------------------------------------------------+   |
|  Parties: EndUser · BridgeOperator · TokenIssuer · Validator1/2     |
+---------------------------+------------------------------------------+
                            | Canton HTTP Ledger API v2
+---------------------------v------------------------------------------+
|                      Bridge Backend (Node.js)                       |
|  +---------------------+  +--------------------------------------+  |
|  |  coordinator.js     |  |  canton-http-client.js               |  |
|  |  settlement-intent  |  |  bridge-reactor.js                   |  |
|  |  nonce-store-sqlite |  |  supply-parity-monitor.js            |  |
|  |  sanctions-screener |  |  canton-signer.js (HSM / KMS)        |  |
|  +----------+----------+  +--------------------------------------+  |
|             | mTLS (mutual cert auth)                               |
|  +----------v-----------------------------------------------------+ |
|  |  Validator Nodes (N)                                           | |
|  |  POST /api/sign-settlement-intent  (rate-limited, mTLS auth)  | |
|  |  secp256k1 signing via SoftwareKeySigner / KmsSigner           | |
|  +----------------------------------------------------------------+ |
+---------------------------+------------------------------------------+
                            | eth_sendRawTransaction / eth_call
+---------------------------v------------------------------------------+
|                         Zenith EVM                                  |
|  +---------------------------+  +--------------------------------+   |
|  |  BridgeVault.sol          |  |  BridgedToken.sol              |   |
|  |  M-of-N ecrecover         |  |  Beacon-upgradeable ERC-20     |   |
|  |  EIP-712 MintIntent       |  |  onlyMinter (=BridgeVault)     |   |
|  |  usedIntents mapping      |  |  ERC-7201 storage              |   |
|  +----------+----------------+  +--------------------------------+   |
|             |                                                        |
|  +----------v---------------------------------------------------+   |
|  |  Safe multisig --> TimelockController (48h) --> BridgeVault  |   |
|  +--------------------------------------------------------------+   |
+---------------------------------------------------------------------+

Technology Stack

Trust Boundaries

A user locks their Canton tokens, the bridge verifies the lock, collects cryptographic approval from multiple independent validators, and mints an equivalent number of ERC-20 tokens on the EVM.

Failure Modes and Recovery

A user burns their EVM tokens, the bridge collects cryptographic approval from multiple validators, and releases the equivalent Canton escrow back to the user.

Failure Modes and Recovery

Key Types by Role

Signing Convention: Double-Hash

intentHash    = keccak256(encodeIntent(intent))       [32 bytes]
signingDigest = sha256(intentHash)                    [32 bytes]
signature     = secp256k1.sign(signingDigest, privKey) [64 bytes compact]

Coordinator verification:  secp.verify(sig, sha256(intentHash), pubKey)

Canton in-contract (DA.Crypto.Text.secp256k1):
  Crypto.secp256k1(sig, intentHash, pk)
  -- internally computes sha256(bytes(intentHash)) then ECDSA verify

EVM BridgeVault (EIP-712 ecrecover):
  keccak256("\x19\x01" || DOMAIN_SEPARATOR || structHash(MintIntent))
  -- separate signing path for EVM lane

SettlementIntent Encoding

Fields (in order, deterministic encoding):
  version             : uint32 BE (= 1)
  escrowContractId    : len(uint32 BE) + UTF-8 bytes
  recipient           : len(uint32 BE) + UTF-8 bytes
  amount              : uint64 BE (base units, BigInt)
  assetId             : len(uint32 BE) + UTF-8 bytes
  nonce               : uint64 BE
  deadline            : uint64 BE (Unix milliseconds)
  bridgeVaultAddress  : len(uint32 BE) + UTF-8 bytes  <-- cross-deployment binding
  chainId             : uint64 BE                       <-- cross-chain binding

intentHash = keccak256(encodedBytes)

M-of-N Threshold: Dual Layer

BridgeVault.sol

BridgedToken.sol (BridgedTokenV1)

TimelockController

• Minimum delay: 172,800 seconds (48 hours)
• PROPOSER_ROLE: Safe multisig
• CANCELLER_ROLE: Safe multisig (abort window for malicious proposals)
• EXECUTOR_ROLE: address(0) — anyone can execute after delay
• TIMELOCK_ADMIN_ROLE: address(0) — self-governing, no superadmin

Test Coverage

42 Forge unit tests across BridgeVault, BridgedToken, TimelockController integration, and upgrade scenarios. Supply invariant fuzz test: 256 runs × 128,000 calls verifying totalSupply never exceeds total minted minus total burned.

VerifiedBridgeOut (production bridge-out path)

The only permitted bridge-out path in production (devMode = False). Enforces atomically:

1. Intent expiry: now ≤ intentDeadline
2. M-of-N secp256k1: DA.Crypto.Text.secp256k1(sig, intentHash, pk) for each (pk, sig); dedup prevents one validator counting twice
3. Escrow binding (Fix 1): show escrowHoldingCid == intentEscrowContractId — sig bundle bound to specific escrow contract ID; cannot release a different escrow
4. Custodian check: holding.custodian == admin
5. Registry check: !globalPaused, asset.bridgeOutEnabled
6. Atomic EVM execution: burn tx submitted via DelegatedApplyTransactionWithReceipt; asserts receipt.success

BridgeEscrowHolding

• Contains evmBurnTxHash + evmBurnLogIndex for unique identification (prevents confusion between concurrent bridge-outs of equal amounts)
• expiresAt: 1 hour from creation; user cancels after expiry via CancelBridgeIn; admin force-cancels at any time

AddressMapping — Fix 3

UpdateEvmAddress requires both admin AND cantonParty as controllers. A compromised admin cannot silently redirect bridge-in recipients without the end user's co-signature.

ValidatorConfigProposal

Validator pubkey rotation uses multi-party approval: requires adminApprovalThreshold approvals from bridgeAdmins list. Single compromised admin key cannot rotate validator set.

Legacy BridgeOut — Gated

The legacy BridgeOut choice (no validator sigs, admin-only) is gated behind devMode == True. Production deployments must set devMode = False.

DA.Crypto.Text Alpha API

DA.Crypto.Text.secp256k1 is the sole alpha API in use (warning suppressed with -Wno-crypto-text-is-alpha). Migration plan documented in deploy/docs/daml-alpha-api-tracking.md. Behavior expected to be preserved when stable API is released.

External Party Migration (Scaffolded)

API Authentication

Key Management

No keys are hardcoded. Production validators use KmsSigner (VALIDATOR_HSM_PROVIDER=aws-kms) — the raw private key never leaves hardware.

Rate Limiting

Shell Injection — Fixed

coordinator.js previously used execSync with string-interpolated intent fields. Fixed to execFileSync(binary, argv_array) — no shell is invoked; metacharacters in argv values cannot be interpreted.

Nonce Store — SQLite Persistence

Validator nonce store backed by SQLite (NONCE_DB_PATH). Nonces persist across restarts; a restart does not open a replay window. Each nonce is marked used atomically before signing.

Fireblocks Webhooks

• v2 format required (v1 deprecated June 15 2026 — already migrated)
• HMAC computed over timestamp + "." + rawBody with FIREBLOCKS_WEBHOOK_SECRET (required at startup)
• Timestamp freshness window: 5 minutes
• HMAC comparison uses crypto.timingSafeEqual (timing-safe)

mTLS: Coordinator ↔ Validators

Coordinator uses a mutual TLS HTTPS Agent (COORDINATOR_CERT_PATH, COORDINATOR_KEY_PATH, VALIDATOR_CA_CERT_PATH). Certificate setup documented in deploy/docs/mtls-setup.md. Devnet fallback (X-Coordinator-Secret) is explicitly logged at startup and must not be used in production.

AML / Sanctions Screening

All bridge requests screened against AML/sanctions databases before processing. Supported providers: Chainalysis, Elliptic, mock (testing). Sanctioned addresses rejected with 403 before any Canton or EVM operations are initiated.

BigInt Arithmetic

All token amounts use JavaScript BigInt throughout the coordinator and server. Floating-point representations (Math.round(amount * 1e10)) fully replaced. No precision loss possible in amount encoding, intent hashing, or EVM calldata.

Supply Parity Monitor

Continuously compares BridgedToken.totalSupply() on EVM against the sum of all BridgeEscrowHolding.amount values on Canton. Any discrepancy indicates a stuck bridge operation. Alerts sent via SSE to GET /api/admin/supply-parity. Triggers recovery procedures documented in deploy/docs/recovery-runbook.md.

Validator Set Synchronization

CLI sync tool (just sync-validators) detects and reports mismatches between EVM BridgeVault.validatorSet and Canton BridgeWorkflow.validatorPubKeys. Out-of-sync sets cause SignerNotValidator errors on EVM or signature threshold failures on Canton.

Transaction Recovery Runbook

Stuck bridge-in (Canton locked, EVM mint failed)

1. Detect via supply parity alert (delta > 0) or stale escrow scan
2. Verify EVM mint did not succeed (check EVM logs)
3. Cancel via POST /api/admin/recovery/cancel-bridge-in with escrow contract ID
4. User accepts ReleaseProposal to reclaim FungibleHolding

Stuck bridge-out (EVM burned, Canton release not submitted)

1. Detect via EVM burn events cross-referenced against Canton ACS
2. Re-POST to POST /api/bridge/bridge-out-request with original burn tx
3. Coordinator re-collects fresh M-of-N sigs with new deadline
4. VerifiedBridgeOut submits; user accepts ReleaseProposal

HSM Key Storage

Click any row to expand attack vector and mitigation details.

Residual Risks

Governance Attack Vectors

G-1: Safe Multisig Compromise (EVM)

If a Safe owner key quorum is compromised, an attacker can propose any governance action. The 48-hour TimelockController delay provides detection and response window. Any Safe owner can submit cancel() to abort a scheduled operation. Response team must act within 48 hours. Recommended: 3-of-5 Safe with hardware wallets, geographically distributed owners.

G-2: Single BridgeAdmin Key (Canton)

Canton BridgeAdmin is currently a single key. Compromise grants full BridgeRegistry and AddressMapping control. However, validator config changes now require multi-party approval (ValidatorConfigProposal) — a single compromised key cannot rotate validator keys. Residual risk: Medium until external party migration completes.

G-3: Validator Collusion Below Threshold

If exactly M validators collude, they can forge arbitrary SettlementIntent signatures — minting unlimited EVM tokens or releasing any Canton escrow. M/N should be > 2/3 for meaningful security. Minimum recommended for mainnet: 3-of-5, operated by independent organizations, geographically distributed.

Six audits are required before the bridge handles real funds, listed in priority order.

All items must be complete before the bridge handles real user funds.