Cross-chain flows

The Execution Model describes a flow that runs completely inside the one transaction the user signs. This page describes the one exception: a flow whose last part runs later, from an escrow. That later part usually runs on another chain, after a bridge, but it can also run on the flow’s own chain.

A plain flow runs inside one transaction on one chain. A cross-chain flow adds a second part. The source flow runs in the user’s transaction and bridges the funds into an escrow on the destination chain. Once they land, LI.FI’s settlement service runs the destination flow from the escrow and pays its gas, so the user needs no native token on the destination chain. Under the hood, a cross-chain flow is a continuation: you add one continuation.settle node to the source flow and pass it the destination flow. These pages call that node the settle node. To build one, follow Build a cross-chain flow. A continuation is not limited to cross-chain flows. The escrow can also live on the source flow’s own chain. The user’s transaction or a plain transfer from any wallet then funds it, and the destination flow runs later on that same chain. See Same-chain continuations. This page uses cross-chain terms because a bridge into an escrow is the most common case.

​

How a cross-chain flow runs

1. Compile registers an escrow. POST /compose proves the destination flow at the minimum funding and registers a fresh escrow on the destination chain with LI.FI’s settlement service. The escrow is owned by the signer and holds the terms of the run: the destination flow, the minimum received, the outcome’s destination, a spending cap, an expiry and a refund address.
2. The user signs once. The source flow runs on the source chain and bridges the funds into the escrow. The user pays gas only for this transaction.
3. The funds land. Once the balance reaches the minimum funding (escrow.floor), the escrow becomes READY. A balance below the minimum funding never starts a run.
4. The destination flow runs. LI.FI’s settlement service takes up to escrow.cap from the escrow and runs the destination flow from LI.FI’s executor. It pays the gas.
5. The outcome is checked. The settlement contract checks the minimum received on chain and forwards the outcome to destination. Leftovers go to the refund address. If the destination flow doesn’t run before expiry, or the run fails, the escrow’s balance is refunded to refund automatically, on the destination chain.

Each part is atomic on its own chain. The cross-chain flow as a whole is eventually consistent: the total time depends on the bridge and on when the destination flow runs.

​

Which cross-chain path?

The rest of this page is about the third row. If everything can happen in the user’s transaction, use a plain flow instead: a plain flow is atomic, a continuation is not. Nothing guarantees when the destination flow runs either; the fallback is a refund.

​

Who runs what

The destination flow is an ordinary flow with one input, the token the escrow receives. The settle node binds the funding, the source flow sends those funds into the escrow, and the destination flow runs from them later.

​

Funding the escrow

In a cross-chain flow the escrow is funded by delivery: the settle node’s bind.input is the future output of a lifi.bridge or a lifiIntents.order that has no destination. That op delivers straight into the escrow on its destination chain, and the user signs one transaction, on the source chain. The compiler infers the mode from the binding, so the settle node sets no funding. The minimum funding comes from the bridge’s or the order’s quote, and the funding must carry an enforced minimum. The op reference gives the exact rules. The escrow can also be funded on one chain, without a bridge; see Same-chain continuations.

​

Standard and exact destination flows

A destination flow is standard by default. Set exact: true on the settle node to make it exact. The destination flow document is the same in both cases; what the escrow commits to differs. A standard destination flow cannot express “pay this invoice”: an invoice counts as paid only when one specific call ran. An exact destination flow binds the escrow to its compiled calldata, so the escrow runs only those bytes. The response discloses them in settlements[<settle id>].binding, so you can check them before anyone funds the escrow. The op reference lists which ops a destination flow can run and the exact rules.

​

What is enforced on chain

A contract checks each of these when the destination flow runs:

• The minimum received. The settlement contract checks the outcome against the minimum received (outputs['<settle id>.output'].amount.minimum) before it forwards the outcome to destination. A run that would deliver less reverts.
• The spending cap. A run spends at most escrow.cap. See How much a run spends.
• Committed predicates. Balance and allowance invariants in the destination flow add predicates that the settlement contract checks. The compile response lists them in verificationByNode['<settle id>'].assertedPredicate.
• For exact destination flows: the bytes and the executor. Only LI.FI’s executor (binding.executionTarget) can run the escrow, and only with the payload whose hash is binding.payloadHash.

For a standard destination flow, the minimum received, the predicates, the spending cap and the refund address are part of the settlement data the escrow commits to at compile time. The calldata that runs is not.

​

What is not enforced on chain

• Leftovers in a standard destination flow. The transfer of leftovers to refund is part of the stored destination flow that LI.FI’s settlement service runs; only the minimum received is checked on chain. In an exact destination flow it is inside the bound calldata, so it runs as compiled.
• Expiry. The settlement service refuses to run the destination flow after the stored expiry; no contract checks it. Keep validity.expiresAtMs as short as the funding allows.
• Timing. Nothing guarantees when, or whether, the destination flow runs. If it does not, the escrow is refunded.
• The expected outcome. amount.estimate on the settle node’s output is never enforced. Only amount.minimum, the minimum received, is.
• fill.validUntilMs. The compile response’s deadline for submitting the user’s transaction is advisory.

​

Lifecycle

Escrow status reports each escrow’s status and owns the lifecycle. On the happy path the escrow reaches COMPLETED, and the destination flow runs at most once. A funded escrow whose destination flow does not run before expiry, or whose run fails, is refunded to refund automatically and ends REFUNDED. An escrow that never received funds has nothing to refund and stays EXPIRED.

​

Limitations

• Composer API only. Continuations, cross-chain or same-chain, are available through POST /compose, not through the LI.FI API’s /v1/quote.
• One hop. The outcome lands on the escrow’s chain. A destination flow cannot bridge and cannot contain another continuation.settle, so a cross-chain flow cannot end on a third chain. Deliver the funds into an escrow on the chain where the outcome must land, and let the destination flow run there.
• One outcome per settle node. For a second delivery, add a second settle node.
• Served chains only. See Availability.

​

Availability

Continuations, cross-chain or same-chain, are served on these 13 mainnets. No testnet is served. The settlement contract has the same address on each; see Addresses.

• A settle node whose funding chain or outcome chain is not in this list fails with validation_error before any escrow is registered.
• On Tempo and Arc, the native asset is an ERC-20 token. A native outcome on these chains must name that token instead of the zero-address native sentinel: pathUSD (0x20C0000000000000000000000000000000000000) on Tempo, USDC (0x3600000000000000000000000000000000000000) on Arc. This rule does not affect other outcomes.

​

Same-chain continuations

A continuation doesn’t need a bridge. Without one, the escrow lives on the source flow’s own chain, and the destination flow runs there later, after the user’s transaction has ended. LI.FI’s settlement service still runs it and pays its gas, and the settlement contract still checks the minimum received. Two funding modes keep a continuation on one chain: A same-chain continuation that only needs a standard destination flow is usually better as a plain flow: a plain flow runs atomically in the user’s transaction. The guide has short samples in Other ways to fund the escrow.

​

See also

• Build a cross-chain flow: step by step.
• continuation.settle: every config field, rule and error.
• Escrow status: track the escrow.