Skip to main content
This page explains the internal architecture of LI.FI Composer: how multi-step DeFi operations get compiled, simulated, and executed as a single transaction.

​
Architecture Overview

Composer transforms a user’s intent (e.g., “deposit USDC into Morpho on Base”) into an optimised, executable onchain transaction. The system has three layers:
Composer architecture flow: from user intent through the LI.FI API, eDSL compiler, and Onchain VM to atomic onchain execution

​
Core Components

​
1. Onchain VM (Execution Engine)

The Onchain VM is a smart contract deployed on supported EVM chains. It acts as a general-purpose execution engine that can:
  • Call any other onchain protocol or series 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 (same-chain)
The VM receives compiled bytecode and executes it in a single transaction, abstracting away the complexity of multi-protocol interactions. Contract address (Ethereum): 0xD214A2eB3799076791A4Cde4F0AB184A49dB832d

​
2. eDSL and Compiler

The embedded Domain-Specific Language (eDSL) is a purpose-built language for expressing contract interactions in TypeScript. When a Composer route is requested:
  1. The routing engine identifies which protocols and actions are needed
  2. The eDSL expresses these interactions as a typed program
  3. The compiler transforms this program into bytecode the Onchain VM can execute
This approach provides type safety, composability, and the ability to optimise execution paths at compile time.

​
3. Dynamic Calldata Injection

Many DeFi operations require data from a previous step. For example, depositing into a vault requires knowing the exact token amount received from a preceding swap. Composer handles this through dynamic calldata injection:
  • The compiler identifies dependencies between steps
  • At execution time, the VM automatically intercepts outputs from completed steps
  • These outputs are injected as inputs into subsequent steps
  • This happens entirely onchain, within the same transaction

​
Transaction Lifecycle

Here is the full lifecycle of a Composer transaction, from user request to onchain execution:
Composer transaction lifecycle: from quote request through route optimisation, eDSL compilation, simulation, onchain execution, and status tracking

​
Step-by-Step Breakdown

StepWhat HappensWhere
1. Quote requestDeveloper requests a quote with a vault token as toTokenClient → API
2. Route optimisationLI.FI’s routing engine finds the optimal path across DEXs, bridges, and protocolsAPI backend
3. eDSL compilationThe Composer compiler generates bytecode for the Onchain VMAPI backend
4. Pre-execution simulationThe full execution path is simulated to verify it will succeed and estimate outputsAPI backend
5. Quote responseAPI returns transactionRequest (ready-to-sign tx) plus estimated amountsAPI → Client
6. Transaction submissionUser signs and submits the transaction to the blockchainClient → Chain
7. Onchain executionThe Onchain VM executes the compiled bytecode, performing all steps atomicallyOnchain
8. ConfirmationTransaction is confirmed; vault tokens are in the user’s walletChain → Client
9. Status checkOptionally poll /status for cross-chain transfersClient → API

​
Same-Chain vs. Cross-Chain

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

​
Same-Chain Composition

Same-chain Composer flow: all steps (swap, deposit, receive vault tokens) execute atomically in a single transaction
  • Atomic execution — all steps succeed or none do
  • Single gas payment — one transaction fee
  • Instant completion — confirmed in one block
  • Simulation guarantee — if simulation passes, execution will succeed (barring extreme edge cases like mempool front-running)

​
Cross-Chain Composition

Cross-chain Composer flow: source chain transaction bridges to destination chain, where Composer executes deposit atomically
  • Two-phase execution — source chain transaction triggers a bridge, then destination chain actions execute
  • Per-phase atomicity — each phase is atomic within its chain, but the overall flow is eventually consistent
  • Bridge latency — total time depends on the bridge used (seconds to minutes)
  • Status tracking required — use /status endpoint to monitor cross-chain progress
Composer itself operates on a single chain. Cross-chain flows are achieved by combining LI.FI’s bridge routing with Composer’s onchain execution on the destination chain. This is seamless from the developer’s perspective — you make the same API call regardless of whether it’s same-chain or cross-chain.

​
Pre-Execution Simulation

One of Composer’s key safety features is pre-execution simulation. Before returning a quote, the backend:
  1. Simulates the full execution path using a fork of the current chain state
  2. Verifies all steps succeed — token swaps, approvals, deposits
  3. Calculates exact output amounts — the estimated vault tokens the user will receive
  4. Detects potential failures — insufficient liquidity, incompatible tokens, protocol-specific issues
If simulation fails, the API returns an error rather than a transaction that would revert onchain. This protects users from wasting gas on failed transactions.

​
Composer as a LI.FI Tool

In the LI.FI architecture, Composer is classified as a tool — similar to how bridges and DEX aggregators are tools. This means:
  • Composer routes appear alongside bridge and swap routes in API responses
  • The routing engine automatically selects Composer when it’s the optimal path
  • As with any LI.FI tool, integrators can use allowTools / denyTools to include or exclude Composer from their routing preferences

​
Next Steps

API Integration Guide

Step-by-step guide to integrating Composer via the REST API

Cross-Chain Patterns

Learn how to compose cross-chain DeFi operations

Error Handling

Understand failure modes and how to handle them

Supported Protocols

Full list of supported protocols and capabilities