Bridge Architecture

This page describes the components of the Zink Bridge system, how they interact, and the data flow of a complete transfer.

Components

Bridge program (on-chain)

The same Zink Bridge program is deployed on both the source and destination chains. It owns all bridge state and enforces the instruction-level rules for deposits, acknowledgements, withdrawals, and cleanup. The program manages:

• Bridge accounts that store per-chain-pair configuration
• DepositTracker and WithdrawTracker accounts that record entry state and authority votes
• Token vaults that hold escrowed tokens (for Vault-mode pairs)
• Mint authority for wrapped tokens (for MintBurn-mode pairs)
• AuthProposal accounts for governance changes

The program exposes the ZinkBridgeInstructions enum with eleven instructions: AddChain, EditAuthProposal, VoteOnAuthProposal, CancelAuthProposal, CloseAuthProposal, Deposit, AckDeposit, Withdraw, AckWithdraw, and CleanupDeposit.

Bridge server (off-chain)

An HTTP server that hosts the crank loop and exposes operational endpoints. It is the primary piece of off-chain infrastructure required for the bridge to function. The server:

• Binds to a configurable address and port
• Runs the crank loop on a configurable poll interval
• Exposes /health and /metrics for observability
• Exposes admin endpoints (/kill, /crank/once) behind optional basic auth
• Holds a reference to the authority keypair for signing relay transactions

Crank loop

An in-process polling loop inside the bridge server that drives the authority side of the protocol. Each cycle it:

1. Compares source DepositTracker against destination WithdrawTracker to find unacknowledged deposits
2. Submits ack_deposit on the destination chain if work is found
3. Compares destination withdrawal state against source deposit state to find unacknowledged results
4. Submits ack_withdraw on the source chain if work is found
5. Discovers finalized-but-not-cleaned deposit entries
6. Submits cleanup_deposit for each candidate

Failed actions are retried with configurable bounded backoff (BRIDGE_CRANK_MAX_ATTEMPTS, BRIDGE_CRANK_RETRY_BACKOFF_MS). A run lock prevents concurrent crank executions.

Authority signer

The keypair registered as an authority in the Bridge account. It signs ack_deposit and ack_withdraw transactions. Each signer has a configured weight that contributes to the threshold calculation.

Vault and mint accounts

Per-token-pair accounts on each chain. In Vault mode, a PDA-owned token account holds locked tokens. In MintBurn mode, the bridge program has mint authority over a wrapped token and burns/mints as needed.

Tracker accounts

DepositTracker on the source chain and WithdrawTracker on the destination chain. These are append-only lists of entries with per-entry status tracking, authority vote maps, and finalization cursors. See State and Trackers.

Data flow

A complete transfer flows through both chains and the off-chain server:

Source Chain                     Off-chain                   Destination Chain
─────────────                    ─────────                   ─────────────────

User calls deposit
  ├─ tokens escrowed
  ├─ DepositEntry created
  │   (status: Initialized)
  │                               Server polls source
  │                               DepositTracker
  │                                     │
  │                               Detects new entry
  │                                     │
  │                               Signs ack_deposit ──────▶ WithdrawEntry created
  │                                                          (status: Voting)
  │                                                              │
  │                                                         Threshold met
  │                                                              │
  │                                                         WithdrawEntry finalized
  │                                                          (Confirmed or Rejected)
  │                                                              │
  │                                                         Anyone calls withdraw
  │                                                          (if Confirmed)
  │                                                              │
  │                               Server polls destination       │
  │                               WithdrawTracker                │
  │                                     │
  │                               Detects finalized entry
  │                                     │
  ◀──────── Signs ack_withdraw ◀────────┘
  │
  DepositEntry enters Voting
  │
  Threshold met
  │
  DepositEntry finalized
  │
  Anyone calls cleanup_deposit
  ├─ fees refunded
  └─ tokens refunded (if rejected)

Key points about this flow:

• The server never holds user funds. All escrow and release happens on-chain through program-owned accounts.
• The server's role is purely observational and transactional — it reads state and submits signed instructions.
• Two separate threshold votes occur: one on the destination chain (ack_deposit → WithdrawEntry finalization) and one on the source chain (ack_withdraw → DepositEntry finalization).
• withdraw and cleanup_deposit are permissionless. The server does not need to execute them, though the crank automates cleanup.

Deployment topology

The bridge program is deployed at the same program ID on both chains (see Overview for addresses). The bridge server runs as a Cloud Run service with a dedicated authority keypair per deployment. See Authority / Operator Flow for the recommended Cloud Run configuration and Server and Crank for environment variables.

Bridge-specific

The architecture assumes a small, known set of authorities operating dedicated server instances. It is not designed for a large permissionless validator set or decentralized relay network. The trust model is authority-based, not proof-based.