LayerZero Lane

Stargate v2 OFT cross-chain transfer over LayerZero v2

LayerZero Lane (Stargate v2 over LayerZero v2)

Stargate is Pro (commercial) — not in the OSS build. The Stargate lane (exec.stargate.send + exec.stargate.dst_observe), its registry/admin surface, and its tooling all ship only under the commercial license and are excluded from the AGPL-3.0-or-later OSS distribution. If you are running the OSS build, the Stargate lane described below is unavailable — use the FREE USDT0 native-OFT lane (exec.usdt0.send) for LayerZero-based transfers (see USDT0 below).

What is the LayerZero Lane?

QTG’s LayerZero lane is built on Stargate v2 — a unified-liquidity bridge that uses LayerZero v2 as its underlying messaging layer. From the executor’s point of view:

• Stargate owns the liquidity pools, the sendToken() entrypoint, and the destination-side OFTReceived event.
• LayerZero v2 owns the message delivery: DVNs verify, Executor delivers, EndpointV2 routes.

The lane supports both ERC20 OFT pools (USDC, USDT) and native asset pools (ETH, AVAX, …) — the latter requires no transferFrom, just msg.value.

Operator flow: configure, approve, execute, observe, recover, stop

1. Configure the commercial Pro deployment, MG_STARGATE_ENABLED, required EVM RPC endpoints, and the approved pool/path registry.
2. Approve the movement through QTG’s normal approval controls and preserve signer identity and allowlist evidence.
3. Execute only after the route gates and quote checks pass.
4. Observe source receipt and destination OFTReceived evidence.
5. Recover from recorded intent and chain evidence; do not infer a missing broadcast as success.
6. Stop for operator review on ambiguous or failed recovery evidence.

Canonical EndpointV2

LayerZero v2 deploys EndpointV2 to the same CREATE2 address on every supported chain:

0x1a44076050125825900E736c501f859c50fE728c

QTG hardcodes this address and checks every pool’s endpoint() getter against it during onchain verification. A pool that points at a different endpoint is treated as a mismatch and rejected.

Supported EIDs (LayerZero’s per-chain “endpoint ID”, not the EVM chain ID):

EID	Chain
30101	Ethereum
30102	BNB
30106	Avalanche
30109	Polygon
30110	Arbitrum
30111	Optimism
30184	Base

The Stargate lane structure

The Stargate lane (Pro) registers two executor keys, not one:

• exec.stargate.send — the send-side action that builds and broadcasts the sendToken transaction (pre_submit_check / prepare / submit).
• exec.stargate.dst_observe — a separate destination-observe step that scans the dest chain for the OFTReceived log and resolves the node terminal.

(This differs from CCIP, where a single exec.ccip.send key owns both dispatch and observe.) Destination-side execution is still performed by the LayerZero Executor, not by QTG — exec.stargate.dst_observe only watches for the delivery event.

The contract call: sendToken

The signature actually called on the source-side pool:

sendToken(
    SendParam memory _sendParam,   // (dstEid, to, amountLD, minAmountLD, extraOptions, composeMsg, oftCmd)
    MessagingFee memory _fee,       // (nativeFee, lzTokenFee)
    address _refundAddress
)

QTG pins the canonical signature:

sendToken(
  (uint32,bytes32,uint256,uint256,bytes,bytes,bytes),
  (uint256,uint256),
  address)

The 4-byte selector is resolved at prepare time from this signature rather than stored statically, so an ABI change at the pool would be caught immediately.

For ERC20 pools

• _sendParam.amountLD is the gross amount sent.
• _sendParam.minAmountLD is the min the recipient must receive (slippage guard).
• msg.value = nativeFee only (the pool pulls tokens via transferFrom).
• Allowance check: _erc20_allowance must cover amountLD.

For native pools

• The pool consumes native value directly.
• msg.value = amountLD + nativeFee (no transferFrom).
• Balance check covers amountLD + nativeFee + gas_budget_wei.

Pre-submit gates

preflight itself is a no-op — the substantive checks live in pre_submit_check and the prepare path:

Gate	Source	Failure error_code
Pool registered	pool registry lookup (chain, asset)	PRECONDITION_POOL_NOT_REGISTERED
Pool usable (trust_tier != "unknown")	pool registry	PRECONDITION_POOL_NOT_USABLE
Preapproval not revoked (ERC20)	pool preapproval status	PRECONDITION_PREAPPROVE_REVOKED
ERC20 balance sufficient	source-chain balance read	PRECONDITION_INSUFFICIENT_BALANCE
Native balance sufficient	source-chain balance read	(native pools only)
Quote succeeds	Stargate quote	propagates RPC error
Native fee within cap	native-fee cap (% of amount)	PRECONDITION_NATIVE_FEE_EXCEEDS_CAP

The native-fee cap is a percentage of the transferred amount (default 5 = 5%). It’s the operator’s protection against a DVN/Executor fee spike that would otherwise eat into the moved value.

Onchain pool verification

Before a pool is allowed in the registry, onchain verification checks four invariants:

1. token()          == candidate asset token address  (or a native sentinel)
2. endpoint()       == the canonical LayerZero endpoint for the candidate EID
3. EndpointV2.eid() == candidate EID
4. 1 <= sharedDecimals() <= candidate token decimals

Reachability failures (unreachable, empty_code) are also rejected. The verification is mandatory before a pool enters the registry with trust_tier="trusted" — an unverified pool sits in trust_tier="unknown" and is unreachable by movements.

The sharedDecimals() check rejects 0 and any value exceeding the local token’s decimals. A misconfigured pool with sharedDecimals > localDecimals would silently truncate large transfers — this is a known LayerZero footgun and QTG refuses to use such a pool.

Destination-side detection

Stargate’s authoritative “the funds arrived” signal is the OFTReceived log on the dest pool, keyed by the lz_guid extracted from the source-side OFTSent log. The observer matches on the canonical event topic:

OFTReceived(bytes32,uint32,address,uint256)

The observer polls dst-chain logs in a bounded window — 3000 blocks lookback (widened from 1000 after a 2026-05-06 drill showed delivery latency exceeding the original window). A match by lz_guid resolves the node as COMPLETED.

ERC20 Transfer fallback

If OFTReceived indexing lags (operator-instrumented detection), the observer can fall back to scanning ordinary ERC20 Transfer events on the dest USDC contract, scoped to the configured destination_address and an amount window of expected_min_amount_received_ld ± slippage. This fallback is opt-in — without dst_pool_address, dst_asset_token_address, input_params.destination_address, and expected_min_amount_received_ld all configured, the executor emits a one-time telemetry event stargate_dst_observe.fallback_disabled and waits for OFTReceived only.

Recover: the lost-broadcast case

Stargate’s recover step has one branch that’s worth calling out explicitly:

The STARGATE_BROADCAST_LOST path requires three independent receipt reads to come back empty before the lane declares the broadcast lost. This guards against a transient RPC partition: we only conclude the tx is gone when the chain has moved past the reserved nonce and the receipt cannot be retrieved.

Provider refs

On success, the lane returns:

{
  "execution_intent_id":   "<uuid>",
  "src_chain_key":         "ethereum",
  "dst_chain_key":         "base",
  "send_tx_hash":          "0x...",
  "lz_guid":               "0x...",
  "amount_received_ld":    "...",
  "dst_pool_address":      "0x..."
}

lz_guid is the LayerZero-assigned 32-byte message identifier — the canonical cross-chain reference for postmortem, explorer lookups, and operator support.

USDT0: the FREE native-OFT lane

Stargate is not the only LayerZero application QTG supports. USDT0 is a standard LayerZero v2 native-OFT lane and ships in the AGPL-3.0-or-later OSS (Free) build — registered as exec.usdt0.send.

Stargate and USDT0 share the same base LayerZero OFT machinery: EndpointV2 verification, the OFTSent / OFTReceived log model, and the lz_guid correlation key. The split is purely licensing and liquidity model:

	USDT0 (Free)	Stargate (Pro)
License	AGPL-3.0-or-later (OSS)	Commercial (excluded from OSS)
Executor key(s)	exec.usdt0.send	exec.stargate.send + exec.stargate.dst_observe
OFT model	native OFT (token is the OFT, no liquidity pool)	unified-liquidity pools per asset
Shared base	common LayerZero OFT machinery	same base

If you only need the OSS build, USDT0 gives you a working LayerZero v2 transfer lane without any Pro dependency. Stargate adds unified liquidity (USDC/USDT/native ETH-AVAX pools) but requires the commercial license.

Why Stargate, not “raw LayerZero”?

LayerZero v2 is a messaging protocol; sending arbitrary bytes cross-chain doesn’t move value. Stargate is the OFT (Omnichain Fungible Token) application built on top — it provides unified liquidity pools per asset across chains, with sendToken/lzReceive as the user-facing API.

So when this doc says “LayerZero Lane”, what’s actually being executed is Stargate v2 on top of LayerZero v2. The “LayerZero” name applies because the messaging layer, the EndpointV2 contract, and the DVN/Executor trust model all come from LayerZero — Stargate is the asset-handling tier.

If QTG later supports a non-Stargate LayerZero application (e.g. a custom OFT), it would slot into this same lane structure: same EndpointV2 verification, same DVN/Executor trust model, different pool registry entries.

Related Docs

• Bridge Lane — the shared 4-phase pattern
• CCTP Lane — Circle’s centralized attestation alternative
• CCIP Lane — Chainlink DON + Risk Management Network
• Executor Protocol — preflight/prepare/submit/observe/recover contract
• State Machine — UNKNOWN handling and recovery flow