Composer 101

LI.FI Composer is the onchain execution engine for multi-step DeFi flows. It lets your users complete sequences of swaps, deposits, validations, and protocol calls — on any supported EVM chain — in a single signed transaction. Behind the scenes Composer is a typed VM (Virtual Machine). From a partner’s perspective, it is the difference between asking your users to sign three to five transactions to deposit into a yield strategy and asking them to sign once.

​

Architecture

Composer turns a partner’s request — “deposit USDC into Aave on Base” (via the LI.FI API) or a typed Flow document (via the Composer API) — into a single executable on-chain transaction. The system has three modular layers:

​

1. Onchain VM

A smart contract deployed on every supported EVM chain holding the shared execution logic. Each user gets their own deterministic proxy that holds their tokens and delegatecalls the VM, so a flow runs in the user’s own balance and storage context. Invoked this way, the VM can:

• Call any other on-chain protocol or sequence of protocols.
• Pass outputs from one step as inputs to the next.
• Handle token approvals, transfers, and balance checks between steps.
• Execute the entire sequence atomically within a single chain.

The user signs one transaction addressed to their proxy (or, on the proxy’s first use, to the proxy factory, which deploys the proxy and runs the flow atomically). The proxy then delegatecalls the VM with the compiled flow as calldata. See Account model for how the proxy is derived and access-controlled. VM contract: 0xb57Ce43Be47DF611C98EB0943e5D36EBDb36cc6D — the shared logic the proxy delegatecalls, not the transaction to. Same address on every supported chain. See Addresses for the full deployment list.

​

2. eDSL and compiler

A typed embedded DSL (TypeScript) for expressing contract interactions. When Composer is invoked:

1. The routing engine identifies which protocols and actions are needed.
2. The eDSL expresses those interactions as a typed program.
3. The compiler transforms the program into bytecode the VM can execute.

This provides type safety, composability, and the ability to optimise execution paths at compile time. Validation, lowering, and policy checks all happen in this layer before any calldata is returned.

​

3. Runtime value passing

Many DeFi operations need a value that isn’t known until a previous step runs — for example, depositing the exact amount of tokens received from a preceding swap. Rather than pre-computing intermediate amounts off-chain, Composer passes one step’s outputs into the next:

• A Flow records how each call’s outputs feed later calls’ inputs (via refs).
• The VM encodes each call’s calldata at runtime, reading the concrete values produced by earlier steps and writing them into the arguments of later steps.
• This happens entirely on-chain, within the same transaction.

This is what makes a chained swap → deposit atomic without the integrator pre-computing intermediate amounts.

​

Transaction lifecycle

The Composer API (you author a Flow) and the LI.FI API integration (the backend builds one) share the same execution path:

​

Pre-execution simulation

Every Compose request is simulated end-to-end against current chain state before calldata is returned to the client. The simulator runs with overridden balances and approvals (so missing user approvals don’t fail the simulation), which lets it focus on what actually goes wrong on-chain. This catches:

• Token swaps that would slip past tolerance.
• Vault interactions that would revert (paused, capped, blacklisted).
• Insufficient pool liquidity to fill the swap size.

If simulation fails, the API returns a structured error rather than a transaction that would revert on-chain. Partners save the gas they would have wasted on a failed transaction; users avoid signing something doomed to fail. See Execution Model for the simulation step’s exact place in the pipeline, Guards for how observed values become on-chain assertions, and Error codes for the failure modes.

​

Same-chain vs. cross-chain

Composer behaves differently depending on whether the source and destination are on the same chain:

• Same-chain. All steps execute atomically inside one transaction. Simulation guarantee: if the simulation passes, execution will succeed (barring extreme edge cases like aggressive mempool front-running). One signature, one gas payment, one block.
• Cross-chain (LI.FI API integration only today). The source-chain transaction triggers a bridge; the destination-chain actions then execute. Each phase is atomic within its chain, but the overall flow is eventually consistent. Total time depends on bridge latency. Cross-chain progress is tracked via the LI.FI /status endpoint.

Composer API Flows are scoped to a single chainId per Flow today; multi-chain Flows aren’t yet exposed via the Composer API. If you need cross-chain composition, see Integrate via LI.FI API.

​

Where to go next