How relaying works

What happens between POST /api/submit-tx returning a txId and your transaction landing on chain. Understanding the machinery explains the guarantees — and the failure modes you'll see in the API.

Accept fast, execute reliably

Submission and execution are decoupled. The API validates your request, writes it durably, and returns the txId immediately — typically in milliseconds. Relay workers then claim queued transactions and drive them to a terminal state. This is why submission never blocks on chain conditions, and why Submit and wait is just the same pipeline with the response held open.

Leased claims: crash-safe, no double-send

Workers claim work with a lease. A claimed transaction that isn't finished before its lease expires — say the worker died mid-flight — is reclaimed and retried safely: a transaction that already reached broadcast is not re-broadcast blindly; its status is resolved from the chain first. The invariant the design protects: at most one live broadcast per transaction.

Preflight: fail fast on certain reverts

Before spending gas, the worker simulates the call. A deterministic revert (bad calldata, failing require) short-circuits to FAILED immediately — with decoded revert info on the record — and your balance isn't charged for gas that would have burned. Only chain-state uncertainty proceeds to broadcast.

Retries and the status machine

NOT_PICKED_UP → PENDING → EXECUTED
                   │  └──▶ FAILED
                   └─────▶ NEEDS_TO_BE_RETRIED ──(backoff)──▶ PENDING

Transient trouble — RPC errors, nonce races, dropped transactions — parks the transaction in NEEDS_TO_BE_RETRIED with exponential backoff (base delay doubling per attempt) until the retry budget you set with retries is exhausted. Deterministic failures never retry.

Nonce management and fee bumping

Each relayer identity owns a strictly serialized nonce sequence — allocation, gap-repair after failed broadcasts, and resync on conflict are the relayer's problem, never yours. A broadcast that sits unmined for a configured number of blocks is fee-bumped: re-broadcast at the same nonce with at least +12.5% fees, so congestion delays you but doesn't strand you.

Regions

Relaying is region-aware: your transaction is broadcast from a relayer identity in the region your request resolved to, through RPC endpoints near it — see Region routing. Each region's identity has its own independent nonce sequence, which is why the from address of your executed transactions can differ by region.

Batching

Transactions flagged shouldBatchInMulticall are gathered briefly and executed as one atomic multicall when eligible — the mechanics and eligibility rules are on Batch transactions.