Skip to main content

How It Works — BTC and EVM Routes

ZenBridge is a trust-minimized cross-chain bridge connecting:

  • Zenchain ↔ EVM chains (currently Sepolia), and
  • Bitcoin ↔ Zenchain (deposit BTC → mint zBTC on Zenchain; burn zBTC → receive BTC).

Across both routes, the bridge uses CAIP identifiers (chain, asset, account) embedded in a signed CCIM (Cross-Chain Interoperability Message). Contracts validate CCIM fields and signatures, enforce pausability and token-mapping checks, and gate claims by a configurable operator quorum.

EVM ↔ Zenchain​

A) EVM → Zenchain (Lock → Mint)​

Source (EVM, e.g., Sepolia)

  1. User locks tokens by calling lockAndTransfer (or lockAndTransferWithPermit) on ExternalEVMBridge with (amount, token, destinationRecipientOnZenchain). This emits a CCIM initiation event and records the transfer. Bridge‐level and token‐level pausability, token mapping, and destination checks are enforced by the EVM directory.
  2. Indexer captures the event and surfaces transfer data for operators.

Aggregation (Zenchain)

  1. Operators sign the CCIM payload (CAIP chain/asset/account, amount, transferId, etc.) and submit signatures on-chain via signMessage to the ZenchainBridge. Signatures are tracked per message with a bitmap; the ZenchainBridgeDirectory supplies the active operator set & quorum.

Destination (Zenchain)

  1. User mints the mapped token (e.g., zTOKEN) by calling mint(ccim, v[], r[], s[]) on ZenchainBridge once quorum is reached. The contract validates CAIP fields, verifies signatures against the current version’s operator bitmap/quorum, and applies replay protection.

The EVM directory provides token-mapping & pausability checks for the lock side; the Zenchain directory provides operator/quorum info for signature verification on the mint side.

B) Zenchain → EVM (Burn → Unlock)​

Source (Zenchain)

  1. User burns & initiates by calling burnAndTransfer(amount, token, destinationAccount) (or …WithPermit) on ZenchainBridge. The bridge packages a CAIP-conformant CCIM message and emits the initiation event.
  2. Operators sign the CCIM and store signatures (bitmap) via signMessage on ZenchainBridge; the directory enforces operator set & quorum.

Destination (EVM)

  1. User unlocks the original ERC-20 by calling unlock(ccim, v[], r[], s[]) on ExternalEVMBridge. The contract validates the message, verifies signatures against ExternalBridgeDirectory’s active version/quorum, and checks pausability/token-mapping state before releasing funds.

Bitcoin ↔ Zenchain​

A) Deposit BTC → Mint zBTC (BTC → Zenchain)​

  1. Dedicated deposit address — The bridge generates a BTC multisig deposit address bound to the user/session. The user sends BTC to that address.
  2. Index & record — A BTC indexer detects the UTXO and records the deposit in PostgreSQL; after the required confirmations, the deposit is finalized.
  3. Operator signing — Operators read the finalized deposit, assemble the CAIP-aware CCIM (BTC → Zenchain, asset/account/amount), sign it, and submit signatures on-chain to ZenchainBridge (signMessage). The ZenchainBridgeDirectory tracks operator versions/quorum.
  4. Mint on Zenchain — Once the quorum is visible on-chain, the user calls mint(ccim, v[], r[], s[]) on ZenchainBridge to receive zBTC. CAIP validation, signature verification, and replay protection apply.

Using dedicated deposit addresses simplifies attribution and enables clean state handling for refunds/timeout policies on the BTC side (as coordinated by the indexer & operators).

B) Burn zBTC → Receive BTC (Zenchain → BTC)​

  1. Burn on Zenchain — The user calls burnAndTransfer on ZenchainBridge, specifying the BTC recipient address encoded per CAIP account semantics.
  2. Operators sign & broadcast — Operators sign the CCIM (Zenchain → BTC) and coordinate a threshold-signed Bitcoin transaction that pays out to the specified BTC address once quorum is met and policy allows spend.
  3. Confirmations — The system monitors Bitcoin confirmations and finalizes the transfer status.

CCIM, CAIP & Validation​

  • CAIP everywhere — Chain IDs, asset IDs, and account IDs are represented with CAIP and converted/validated inside contracts. (e.g., toEvm, toString, validate). This ensures unambiguous identification across Zenchain, EVM chains, and Bitcoin.
  • Message processing — mint/unlock call internal routines that validate CCIM fields, check replay protection, and verify each signature against the active operator set (bitmap/quorum) before state changes occur.

Operator Sets, Versions & Quorum​

  • Directories maintain operator versions (bitmap of allowed signers), quorum, supported chains/tokens, and pausability. They expose getters (current version, quorum, operator count) and governance flows (propose/activate/cancel/end version).
  • Quorum enforcement — Contracts can verify that a set of signers meets the required quorum for a given version (verifyQuorum). Message-level signatures are checked via ecrecover, and ZenchainBridge tracks who signed each message using a signature bitmap (getSignatureBitmap, hasOperatorSigned).

Token Mappings & Pausability​

  • Mappings — Directories manage token correspondences between chains (EVM: setTokenMapping, getDestinationToken; Zenchain dir: CAIP-namespace mappings), preventing overwrites and allowing deprecation/removal with timelocks.
  • Checks before actions — Contracts revert if bridge, chain (Zenchain dir), or token are paused/deprecated, or if mint/unlock operations are paused (checkIfTokenCanBeMinted/Locked/Unlocked).

Fees​

The ZenchainBridge includes internal fee-handling hooks that split per-operator fee shares either on the source or destination chain depending on the CCIM context; fee math can use per-billion units in the directory. (Implementation details: _handleFee, _handleSourceChainFee, _handleDestinationChainFee, bridgeFeePerbill).

Notes & Guarantees​

  • Tamper-resistance: Any change to a signed CCIM field alters the hash; ecrecover will not match a registered operator → the claim is rejected.

  • Replay protection: Processed CCIMs are tracked; duplicate submissions revert.

  • Governance safety: Operator-set version changes are time-locked and require explicit activation; chain/token deprecations honor grace periods.