Bridge Flows

This page documents the flow for each bridge direction - the steps, verifications, and error handling involved in a transfer.

EVM → Casper Flow (Lock and Mint)

Overview

1. User locks ERC-20 tokens in the locker contract on the EVM chain
2. Relayers wait for finality and independently verify the deposit
3. Relayers submit the finalized block header and a majority-signed mint approval to Casper
4. CEP-18 tokens are minted to the user's Casper address

Detailed Flow

sequenceDiagram
    participant User
    participant Wallet as EVM Wallet
    participant Locker as Locker Contract
    participant EVMChain as EVM Chain
    participant Relayers as Relayer Network
    participant EthClient
    participant TokenFactory
    participant CEP18 as CEP-18 Token

    Note over User,CEP18: Phase 1: Approve & Lock
    User->>Wallet: Initiate bridge
    Wallet->>Locker: Approve token spending
    Wallet->>Locker: Lock tokens
    Locker->>EVMChain: Emit Locked event

    Note over User,CEP18: Phase 2: Wait for Finality
    EVMChain->>EVMChain: Block containing the lock finalizes
    Relayers->>EVMChain: Observe finalized lock event

    Note over User,CEP18: Phase 3: Verify & Sign
    Relayers->>Relayers: Each relayer independently proves the lock is in the finalized block
    Relayers->>Relayers: Majority signs the block header and mint approval

    Note over User,CEP18: Phase 4: Submit to Casper
    Relayers->>EthClient: Submit signed block header
    EthClient->>EthClient: Verify majority signatures, store header
    Relayers->>TokenFactory: Submit mint approval + inclusion proof
    TokenFactory->>EthClient: Fetch stored header
    TokenFactory->>TokenFactory: Verify proof and signatures on-chain
    TokenFactory->>CEP18: Mint tokens
    CEP18-->>User: Tokens received on Casper

Phase Details

Phase 1 - Approve & Lock. The user first approves the locker contract to spend the token (standard ERC-20 approval), then calls the lock function with the amount and their Casper recipient address. The locker takes custody of the tokens, assigns the deposit a unique nonce, and emits a Locked event that includes the chain ID.

Phase 2 - Finality. EVM chains can reorganize recent blocks, so the bridge waits until the block containing the lock is protocol-finalized (plus a per-chain confirmation floor) before acting. On Ethereum this takes roughly 13 minutes; faster chains finalize sooner. See Multi-Chain Support for how finality is handled per chain.

Phase 3 - Verify & Sign. Each relayer independently generates and checks a Merkle proof that the lock event is included in the finalized block, then signs two things: an attestation of the block header, and an approval of the specific mint. Signatures are exchanged over the relayers' encrypted peer-to-peer network until a majority is collected.

Phase 4 - Submit to Casper. The signed block header is stored on-chain by the EthClient contract. The TokenFactory then validates the mint approval: it checks the majority signatures, verifies the inclusion proof against the stored header, and confirms this deposit has not been processed before. Only then does it mint the CEP-18 tokens to the recipient.

Exposure-control TokenFactory (ERC-7786 gateways)

With an exposure-control TokenFactory, a lock or burn on an EVM chain travels as one ERC-7786 message through the bridge's gateways instead of a signed mint or unlock:

1. The locker commits the transfer and sends it through its chain's gateway, which emits MessageSent.
2. Once the block is final, each relayer proves the message in it on its own: the block's receipts root, the transaction's receipt in that root, and that exact log from the gateway.
3. The block header is stored in EthClient as above. A majority signs the message for the Casper gateway, and one relayer submits deliver. The gateway checks the signatures against EthClient's relayer set, checks the block's receipts root against the stored header, and hands the transfer to TokenFactory.
4. TokenFactory executes it, queues it or holds it. Queued and held transfers are completed later by anyone, without a new delivery.

The relayer picks the path from the TokenFactory's version, so a transfer is never signed both ways. A TokenFactory that has not been upgraded keeps the flow above.

Casper → EVM Flow (Burn and Unlock)

Overview

1. User burns bridged CEP-18 tokens on Casper
2. Relayers detect and independently verify the burn (Casper finality is near-instant)
3. Relayers collect majority signatures and submit the unlock to the EVM chain
4. ERC-20 tokens are released to the user's EVM address

Detailed Flow

sequenceDiagram
    participant User
    participant Wallet as Casper Wallet
    participant TokenFactory
    participant Relayers as Relayer Network
    participant Locker as Locker Contract

    Note over User,Locker: Phase 1: Burn
    User->>Wallet: Initiate bridge
    Wallet->>TokenFactory: Burn tokens (with EVM recipient + target chain)
    TokenFactory->>TokenFactory: Burn CEP-18, emit burn event with unique nonce

    Note over User,Locker: Phase 2: Detect & Verify
    Relayers->>TokenFactory: Observe burn event (finalized immediately)
    Relayers->>Relayers: Each relayer independently verifies the burn on-chain

    Note over User,Locker: Phase 3: Sign & Submit
    Relayers->>Relayers: Majority signs the unlock approval
    Relayers->>Locker: Submit unlock with signatures
    Locker->>Locker: Verify majority signatures, check nonce unused
    Locker->>User: Transfer ERC-20 tokens

Phase Details

Phase 1 - Burn. The user burns their bridged CEP-18 tokens through the TokenFactory, specifying the EVM recipient address and target chain. Bridged tokens can only be returned to the chain they originally came from. The burn is assigned a unique nonce.

Phase 2 - Detect & Verify. Casper finalizes blocks in seconds and never reorganizes them, so relayers can act as soon as the burn lands. Each relayer independently confirms the burn exists on-chain before signing - a relayer will not co-sign a transfer it cannot verify itself.

Phase 3 - Sign & Submit. Once a majority of signatures is collected, the unlock is submitted to the locker contract on the target chain. The contract verifies every signature against the authorized relayer set, confirms the nonce has never been used, and releases the tokens.

This direction completes in a few minutes since there is no long finality wait.

Exposure-control lockers (ERC-7786 gateways)

On an exposure-control locker (version 18 and later) a burn or lock on Casper travels as one ERC-7786 message through the bridge's gateways instead of a signed unlock or mint:

1. TokenFactory commits the transfer and sends it through the Casper gateway, which emits MessageSent.
2. Each relayer confirms the message on independent public Casper nodes: they must agree on the deploy, the block that executed it, that block's state root, and that the event was written to the gateway's own event store in that state.
3. A majority signs the message for the EVM gateway, and one relayer submits deliver. The gateway checks the signatures against the locker's relayer set and hands the transfer to the locker.
4. The locker executes it, or queues it (large releases wait out the queue delay and the rate limit), or holds it (for example while paused). Queued and held transfers are completed later by anyone, without a new delivery.

The relayer picks the path per destination chain from the locker's version, so a transfer is never signed both ways. Older lockers keep the flow above until they are upgraded.

Native Token Flows

Casper-native tokens (like CSPR) bridge in the opposite pattern - locked on Casper, minted as wrapped ERC-20 on the EVM side:

sequenceDiagram
    participant User
    participant TokenFactory
    participant Relayers as Relayer Network
    participant Locker as Locker Contract

    Note over User,Locker: Casper → EVM (wrap)
    User->>TokenFactory: Lock native tokens
    Relayers->>Locker: Majority-signed mint approval
    Locker->>User: Wrapped tokens minted on EVM

    Note over User,Locker: EVM → Casper (unwrap)
    User->>Locker: Burn wrapped tokens
    Relayers->>TokenFactory: Majority-signed unlock approval
    TokenFactory->>User: Native tokens released on Casper

The same verification and majority-approval rules apply in both directions.

Error Handling

Common Failure Scenarios

Idempotency

All bridge operations are idempotent:

• Unique nonces prevent any transfer from being processed twice
• Re-submitting an already-processed transfer harmlessly fails
• Relayers can safely retry failed submissions without risk of double-spending

Related Pages

• Architecture Overview
• Multi-Chain Support
• Security Model