> ## Documentation Index
> Fetch the complete documentation index at: https://jephalabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Bridge Lane

> Shared pattern across CCTP, CCIP, and LayerZero/Stargate bridge executors

# Bridge Lane

"Bridge Lane" is QTG's umbrella for any **on-chain cross-chain movement** — moving value from one EVM chain to another through a third-party messaging or transfer protocol. The lane has a separate implementation per protocol, but they all follow the **same four-phase pattern**.

## The four-phase pattern

```mermaid theme={null}
flowchart LR
    SRC["①Submit on source<br/>(burn / lock / OFT send)"] --> ATT["②Off-chain attest<br/>or verify"]
    ATT --> DST["③Receive on dest<br/>(mint / release / lzReceive)"]
    DST --> FIN["④Finality<br/>confirmations ≥ required"]

    style SRC fill:#ffccbc
    style ATT fill:#fff9c4
    style DST fill:#c8e6c9
    style FIN fill:#bbdefb
```

Every supported bridge maps onto this skeleton; what differs is **who attests** in phase 2 and **how the destination is unlocked** in phase 3.

| Phase                      | CCTP                                      | CCIP                                                              | LayerZero / Stargate (Pro)                    |
| -------------------------- | ----------------------------------------- | ----------------------------------------------------------------- | --------------------------------------------- |
| ①Submit on source          | `depositForBurn()` on USDC TokenMessenger | `ccipSend()` on CCIP Router (payload built by sidecar)            | `sendToken()` on Stargate OFT pool            |
| ②Off-chain attest / verify | Circle IRIS attestation poll              | Chainlink DON + Risk Management Network (`committed` → `blessed`) | DVN(s) verify, Executor delivers              |
| ③Receive on dest           | `receiveMessage()` mint                   | Off-ramp `executeMessage`                                         | `lzReceive()` on dest OFT pool                |
| ④Finality                  | block-confirmations probe                 | block-confirmations probe                                         | block-confirmations probe + `OFTReceived` log |

<Note>
  **Stargate / LayerZero is Pro (commercial), not in the OSS build.** The Stargate lane and its admin surface ship only under the commercial license and are excluded from the AGPL-3.0-or-later OSS distribution. The OSS build's LayerZero option is the FREE USDT0 native-OFT lane (`exec.usdt0.send`) — see [LayerZero Lane](/concepts/bridges/layerzero-lane#usdt0-the-free-native-oft-lane).
</Note>

<Info>
  The four-phase split is **not bookkeeping** — it is enforced by the executor protocol. Each phase is a node in the movement plan, dispatched and observed independently. If phase 3 succeeds but phase 4 stalls, the orchestrator can resume from phase 4 without re-burning or re-minting.
</Info>

## What changes between bridges

The bridges differ along three axes operators actually care about:

### 1. Trust anchor

* **CCTP** trusts **Circle**. A single attestation signed by Circle's IRIS service authorizes the mint. Centralized, fast, narrowly scoped (USDC only).
* **CCIP** trusts the **Chainlink DON** plus an independent **Risk Management Network** (ARM). The protocol status field exposes the intermediate stages (`committed`, `blessed`, `cursed`) so observers can distinguish "DON consensus reached" from "ARM has finished its independent check."
* **LayerZero / Stargate** trusts a configurable set of **DVNs** (Decentralized Verifier Networks) plus an **Executor** role. Pool deployments are verified onchain to point at the canonical LayerZero v2 EndpointV2 address shared by all supported chains.

### 2. Asset scope

| Bridge         | Native asset support      | Tokens supported                               |
| -------------- | ------------------------- | ---------------------------------------------- |
| CCTP           | No                        | USDC only                                      |
| CCIP           | No                        | Any token registered in the CCIP lane registry |
| Stargate (Pro) | Yes (native ETH/AVAX/...) | USDC, USDT, ETH OFT pools                      |

### 3. Operator gating

Every bridge has a different **approved-lane** mechanism that prevents a movement from being dispatched on an unaudited route:

* **CCTP** — explicit `destination_caller` field on the burn TX. The mint can only be called by that address; QTG triple-validates `signer_address == destination_caller == caller specified at burn`. See [CCTP Lane](/concepts/bridges/cctp-lane).
* **CCIP** — admin-approved row in the CCIP lane registry keyed on `(source_chain_selector, dest_chain_selector, token_address)`. Each row carries `status`, `trust_tier`, and `registry_version`; the registry version is checked for **drift between prepare and submit** so a registry rotation cannot silently change which router signs. See [CCIP Lane](/concepts/bridges/ccip-lane).
* **Stargate (Pro)** — pool registry with `trust_tier` (rejects `unknown`) and `preapproval_status` (rejects `revoked` for ERC20). Each pool's `endpoint()`, `eid()`, and `sharedDecimals()` are verified onchain against the canonical LayerZero endpoint before use. See [LayerZero Lane](/concepts/bridges/layerzero-lane).

## Idempotency: every bridge handles "submitted but not confirmed"

Bridges are the part of the system most exposed to **partial failure**: a transaction may be on-chain but not yet visible to the orchestrator, or a destination-side event may arrive out of order. Every bridge lane's `recover` step implements the same shape:

```mermaid theme={null}
flowchart TD
    R["recover(ctx)"] --> Q{"Do we have<br/>a src tx hash?"}
    Q -->|no| F1["FAILED:<br/>pre-broadcast crash"]
    Q -->|yes| R2{"Is dst event<br/>visible yet?"}
    R2 -->|yes| OK["COMPLETED<br/>(idempotent: same dst event<br/>resolves repeated calls)"]
    R2 -->|no, but src tx<br/>is confirmed| W["UNKNOWN<br/>(retry observe)"]
    R2 -->|src tx never landed,<br/>nonce was burned| F2["FAILED:<br/>BROADCAST_LOST"]

    style F1 fill:#ffcdd2
    style F2 fill:#ffcdd2
    style OK fill:#c8e6c9
    style W fill:#fff9c4
```

The destination-side event is **the authoritative source of truth**:

* CCTP: contract reverts with `"already processed"` on duplicate `receiveMessage()` — recover interprets the revert as `COMPLETED`.
* CCIP: terminal status strings (`executed_success`, `executed_failure`, `cursed`) come from the off-ramp; once seen, the intent never re-runs.
* Stargate: dst-chain `OFTReceived(bytes32 guid, ...)` log keyed by `lz_guid` is the canonical "the funds landed" signal.

## Pre-broadcast crash protection

All three bridges write a **pre-broadcast intent row** before the signing call. If the worker crashes between sign and broadcast, the next observer sees an intent in `PREPARED` state with no `send_tx_hash` and **does not retry blindly** — it transitions the row to a terminal `*_PRE_BROADCAST_CRASH` status (e.g. `CCIP_PRE_BROADCAST_CRASH`, `STARGATE_PRE_BROADCAST_CRASH`). The status change is guarded by a row-level UPDATE with `expected_status`, so two recovery workers competing on the same row cannot double-spend the nonce.

<Warning>
  This guard relies on the **reserved nonce being the same one used in the signed payload**. The nonce is allocated under a Postgres advisory lock, then frozen into the payload hash. Any drift between the nonce in the DB and the nonce in the broadcast tx is treated as a fatal error.
</Warning>

## Signed-recipient invariant (validated == signed)

Every on-chain send lane enforces a single fund-safety invariant: the recipient (and, where applicable, the source) **re-derived from the actual signed artifact** must equal the **allowlist-validated authority**. This closes the gap between "what the operator approved" and "what the signer actually signed" — a malicious or misconfigured prepare step cannot redirect funds to an address that passed the allowlist check only on paper.

The invariant is enforced at **two points**:

1. **Prepare-time** — intent-only resolvers pin the recipient/source from the validated intent before signing.
2. **Submit/broadcast-time** — the raw signed legacy tx is RLP-decoded and the recipient/target/source re-derived from it (Gateway re-hashes the EIP-712 burn-intent digest), then compared to the validated authority.

Any mismatch is **fail-closed**: a fatal movement error drives the node to `FAILED` rather than broadcasting. Codes: `SIGNED_RECIPIENT_MISMATCH`, `SIGNED_SOURCE_MISMATCH`, `SIGNED_TARGET_MISMATCH`, `SIGNED_TX_DECODE_FAILED`, `EIP712_DIGEST_MISMATCH`, `MISSING_PREPARED_PAYLOAD`.

On-chain action types split into two enforcement classes:

* **Destination-only** (source is signer-bound, so only the destination is checked): `stargate_send`, `usdt0_send`, `lighter_secure_withdraw`.
* **Strict source + destination** (both addresses checked): `cctp_burn` / `cctp_mint`, `gateway_*`, `ccip_send`, `evm_erc20_transfer`.

<Warning>
  CCIP now participates in the submit-time signed-artifact invariant even though its payload is built by an out-of-process sidecar. Before the sidecar broadcasts, QTG decodes the signed legacy transaction, pins router, destination chain selector, receiver, token, amount, native fee, signer identity, and source chain id against the trusted intent, and fails closed on mismatch.
</Warning>

## Why a sidecar for CCIP?

CCIP is the only bridge in this set whose **prepare/submit/observe** flow runs through an out-of-process sidecar over HTTP. The sidecar hosts the Chainlink TypeScript SDK and serves three jobs:

1. Build a canonical `ccipSend` payload from the high-level intent.
2. Decode `CCIPSendRequested` event logs.
3. Poll the SDK's message status and return a normalized status string.

This keeps the Python codebase free of the heavyweight Chainlink dependency while preserving full reconciliation power (every sidecar call returns provenance fields that QTG persists into its own intent row).

CCTP and Stargate, in contrast, are pure in-process: the necessary calldata, ABI encoding, and log decoding are small enough to live inside the QTG runtime.

## Observability surface

Every bridge intent surfaces the same canonical provider refs back to the movement layer:

```
{
  "execution_intent_id":   "<uuid>",
  "source_chain_selector": "<chain key>",
  "dest_chain_selector":   "<chain key>",
  "send_tx_hash":          "0x...",
  "message_id" | "lz_guid": "0x...",
  "last_status":           "<protocol-specific>"
}
```

The `last_status` value is the **raw protocol status string** (e.g. CCIP `executed_success`, Stargate `OFT_RECEIVED`), not a QTG-normalized state. The normalization happens inside the lane (status mapping for CCIP, the dst-log scanner for Stargate), so operators always have the unfiltered protocol signal available for postmortem.

## Choosing a bridge

For the most-common QTG paths:

| If you want to move...                                                                | ...prefer                                                                                                                            |
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| USDC between two well-supported Circle chains (Ethereum, Base, Arbitrum, OP, Polygon) | CCTP — narrowest trust assumption, lowest fee                                                                                        |
| A non-USDC token, or a USDC route Circle doesn't yet support                          | CCIP — broadest token coverage, DON + ARM trust                                                                                      |
| Native ETH/AVAX, or an OFT-wrapped asset, or a route where speed matters              | Stargate (Pro) — unified liquidity, faster finality on common pairs (commercial build only; OSS uses USDT0 native-OFT for LayerZero) |

The three pages below cover each lane in detail:

* [CCTP Lane](/concepts/bridges/cctp-lane) — Circle's burn-attest-mint
* [CCIP Lane](/concepts/bridges/ccip-lane) — Chainlink DON + Risk Management Network
* [LayerZero Lane](/concepts/bridges/layerzero-lane) — Stargate v2 OFT (Pro) + USDT0 native-OFT (Free)