@lifi/composer-sdk 0.6.1 → 0.6.3

package/README.md

@@ -1,34 +1,22 @@
 # @lifi/composer-sdk
 
-TypeScript SDK for building and submitting LI.FI Compose flows.
+TypeScript SDK for building LI.FI Compose flows and compiling them into submit-ready transactions.
+
+Full documentation: [docs.li.fi/composer](https://docs.li.fi/composer/overview). SDK API reference: [SDK API](https://docs.li.fi/composer/composer-api/reference/sdk-api.md).
 
 ## Install
 
-`@lifi/compose-spec` is a peer dependency and must be installed alongside the SDK at the same version (they are versioned in lockstep).
+`@lifi/compose-spec` is a peer dependency. Install it at exactly the same version as the SDK; the two are versioned in lockstep. Node.js 24 or later is required.
 
 ```bash
 npm install @lifi/composer-sdk @lifi/compose-spec
 ```
 
-## Upgrading to 0.3.0
-
-**Breaking:** `apiKey` is now required on `createComposeSdk()`.
-
-The Compose API has always rejected unauthenticated requests, but `apiKey` was typed as optional, so omitting it compiled and only failed on the first request. It is now a required `string`, and a missing or blank value throws a `ComposeError` (`VALIDATION_ERROR`) at construction time — including for plain-JavaScript callers that bypass the type check.
-
-```diff
--const sdk = createComposeSdk({ baseUrl: 'https://composer.li.quest' });
-+const sdk = createComposeSdk({
-+  baseUrl: 'https://composer.li.quest',
-+  apiKey: process.env.LIFI_API_KEY!,
-+});
-```
-
-Create a key at [portal.li.fi](https://portal.li.fi).
+`apiKey` is required (create one at [portal.li.fi](https://portal.li.fi)). A missing or blank key throws a `ComposeError` with code `VALIDATION_ERROR` when you call `createComposeSdk()`, including from plain JavaScript that skips the type check. It has been required since 0.3.0.
 
 ## Quick start
 
-Swap WETH to USDC, then zap the USDC into an Aave lending position — all in a single transaction.
+Swap WETH to USDC, then zap the USDC into an Aave lending position, in one transaction.
 
 ```ts
 import {
@@ -43,13 +31,12 @@ const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c'; // Aave aEthUSDC
 const OWNER = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
 
-// Create the SDK pointed at the Compose API.
 const sdk = createComposeSdk({
   baseUrl: 'https://composer.li.quest',
-  apiKey: process.env.LIFI_API_KEY!, // required
+  apiKey: process.env.LIFI_API_KEY!,
 });
 
-// Build a two-step flow on Ethereum mainnet.
+// A flow on Ethereum mainnet with one token input.
 const builder = sdk.flow(1, {
   name: 'swap-and-zap-weth-to-aave',
   inputs: {
@@ -57,7 +44,7 @@ const builder = sdk.flow(1, {
   },
 });
 
-// Step 1: Swap WETH → USDC via LI.FI.
+// Step 1: swap WETH to USDC via LI.FI.
 const swapOutputs = builder.lifi.swap('swap', {
   bind: { amountIn: builder.inputs.amountIn },
   config: {
@@ -66,8 +53,8 @@ const swapOutputs = builder.lifi.swap('swap', {
   },
 });
 
-// Step 2: Zap the swapped USDC into Aave.
-// The swap's amountOut handle threads directly into the zap's amountIn.
+// Step 2: zap the swapped USDC into Aave. The swap's amountOut handle
+// feeds the zap's amountIn directly.
 builder.lifi.zap('zap', {
   bind: { amountIn: swapOutputs.amountOut },
   config: {
@@ -78,7 +65,6 @@ builder.lifi.zap('zap', {
 
 const flow = builder.build();
 
-// Compile the flow into transaction calldata.
 const request = sdk.request(flow, {
   signer: OWNER,
   inputs: {
@@ -87,87 +73,108 @@ const request = sdk.request(flow, {
     }),
   },
   sweepTo: builder.context.sender,
-  // Opt into partial results. Without this, the default 'strict' policy
-  // throws a ComposeError (HTTP 422) when simulation detects a revert,
-  // and the `partial` branch below is never reached.
+  // Opt into partial results. Under the default 'strict' policy a simulated
+  // revert throws a ComposeError instead, and the `partial` branch is unreachable.
   simulationPolicy: 'allow-revert',
 });
 
 const result = await sdk.client.compile(request);
 
 if (result.status === 'success') {
-  // Full success — transactionRequest includes gasLimit.
+  // transactionRequest includes gasLimit.
   console.log(result.transactionRequest);
 
-  // What the flow produced, one entry per output port. The zap's output is
-  // terminal (nothing downstream spends it), so it carries the owner it is
-  // delivered to; the swap's output is `role: 'consumed'` by the zap.
+  // One entry per output port. Nothing downstream spends the zap's output, so
+  // it is terminal and carries its owner. The swap's output is `consumed` by the zap.
   const position = result.outputs['zap.amountOut'];
   if (position?.role === 'terminal') {
     console.log(position.owner, position.amount.estimate?.value);
   }
 } else {
-  // result.status === 'partial' — simulation reverted.
-  // Transaction is still available but without gasLimit.
+  // status === 'partial': simulation reverted. The transaction is still
+  // returned, without gasLimit.
   console.log(result.simulationRevert);
 }
 ```
 
+`builder.compile(run)` is shorthand for `sdk.client.compile(sdk.request(builder.build(), run))`.
+
 ## Core concepts
 
-**Flows and operations** — A flow is a sequence of on-chain operations. You declare inputs, chain operations together, and the backend compiles everything into a single transaction. Operations are namespaced (e.g., `builder.lifi.swap`, `builder.core.split`).
+**Flows and operations**: a flow is an ordered list of on-chain operations. You declare inputs, chain operations, and the backend compiles everything into one transaction. Operations are namespaced, e.g. `builder.lifi.swap` and `builder.core.split`. Each call takes a node id that must be unique in the flow.
 
-**Resources** — `resources.erc20(address, chainId)` and `resources.native(chainId)` describe the tokens flowing through your operations. They carry chain and address metadata used for routing and validation.
+**Resources**: `resources.erc20(address, chainId)` and `resources.native(chainId)` describe the tokens flowing through the flow. A resource input must be on the flow's chain.
 
-**Handles** — Operations produce typed output handles (e.g. `OutputHandle<'resource'>`, `OutputHandle<'uint256'>`) that you bind to downstream inputs. The type system enforces compatibility at compile time — a resource handle can flow into a `uint256` slot (since resources are amounts), but an `address` handle cannot.
+**Handles**: operations return typed output handles, e.g. `OutputHandle<'resource'>` or `OutputHandle<'uint256'>`, which you bind to downstream inputs. TypeScript enforces the port types. A resource handle fits a `uint256` slot (resources are amounts), but an `address` handle does not.
 
-**Runtime inputs (materialisers)** — Materialisers resolve input values at execution time rather than at build time. `directDeposit` is exact by default when you provide an amount; pass `allowNonExact: true` to permit capped ERC-20 deposits or deposit-all behavior. `balanceOf` reads the wallet's current balance; `call` measures a balance delta after an arbitrary contract call.
+**Runtime inputs (materialisers)**: a materialiser tells the backend how to fund a flow input when the transaction executes.
 
-**Preconditions** — Expected on-chain state at execution time: `erc20Balance` and `nativeBalance` assert wallet holdings, `erc20Allowance` asserts token approvals.
+- `directDeposit({ amount })` pulls exactly `amount`.
+- `directDeposit({ amount, allowNonExact: true })` permits a capped ERC-20 deposit of up to `amount`; `directDeposit({ allowNonExact: true })` deposits with no on-chain cap (ERC-20 only).
+- `balanceOf({ owner })` reads a current balance.
+- `call({ target, calldata })` measures the balance delta after an arbitrary contract call.
 
-**Guards** — Protect against slippage and other runtime conditions. Applied per-operation via the `guards` field.
+**Preconditions**: on-chain state the backend assumes when it simulates, e.g. a balance the signer will hold at execution time. The factories are `erc20Balance`, `nativeBalance`, and `erc20Allowance`.
 
-**Outputs** — A compile result carries `outputs`, a record keyed `'<nodeId>.<portName>'` holding every resource output the flow produces. Each entry is `role: 'terminal'` (delivered to `owner`, with `delivery.when` telling you whether it lands with this transaction) or `role: 'consumed'` (spent by the node named in `consumedBy`), so narrow on `role` before reading either field. `amount.estimate` and `amount.minimum` are both optional: an estimate is absent when nothing measured or quoted the port, and a minimum is absent when no floor is enforced. `terminalOutputs(result.outputs)` narrows the record to the terminal entries. Full field reference: [docs/sdk-interface.md](./docs/sdk-interface.md#outputs).
+**Guards**: runtime checks on an operation's output, attached through its `guards` field. `guards.slippage({ port, bps })` floors an output at `bps` below its simulated amount. The `port` argument is typed against the ports a guard can protect. For example, `lifi.swap`'s `amountOut` already carries the aggregator's own floor, so it rejects a slippage guard at compile time.
 
-## API surface
+**Outputs**: a compile result carries `outputs`, keyed `'<nodeId>.<portName>'`, with one entry per resource output. An entry is either:
+
+- `role: 'terminal'`: delivered to `owner`. `delivery.when` says whether it lands with this transaction (`'now'`) or later (`'future'`).
+- `role: 'consumed'`: spent by the node named in `consumedBy`.
+
+Narrow on `role` before reading those fields. `amount.estimate` and `amount.minimum` are both optional. An absent minimum means no floor is enforced; there is no `0` default. `terminalOutputs(result.outputs)` keeps only the terminal entries.
 
-**SDK factory**
+## API surface
 
-- `createComposeSdk({ baseUrl, apiKey, fetch? })` — creates the SDK instance
+**SDK**
 
-**Flow building**
+- `createComposeSdk({ baseUrl, apiKey, fetch? })`: `baseUrl` must be an HTTP(S) URL. A trailing slash is stripped.
+- `sdk.flow(chainId, { inputs, name? })`: returns a `FlowBuilder`. `name` defaults to a random UUID.
+- `builder.<namespace>.<operation>(nodeId, { bind, config, guards? })`: adds a node and returns one typed handle per output port.
+- `builder.untypedOp(nodeId, op, { bind, config, guards? })`: escape hatch for ops without a typed method. Returns `void`; reference its outputs with `raw.ref<T>(path)`.
+- `builder.build()`: returns the `Flow` document.
+- `builder.compile(run)`: builds, then compiles.
+- `sdk.request(flow, run)`: builds a `ComposeCompileRequest` from a flow and a `ComposeRunInput`.
+- `sdk.route(request)`: compiles a token pair without authoring a flow. See [Routing a token pair](#routing-a-token-pair).
+- `sdk.simulate(request)`: simulates a raw transaction. See [Simulating a raw transaction](#simulating-a-raw-transaction).
+- `sdk.getSupportedChains()`: same as `sdk.client.getChains()`.
 
-- `sdk.flow(chainId, options)` — creates a `FlowBuilder`
-- `builder.<namespace>.<operation>(id, { bind, config })` — adds an operation, returns typed `OutputHandle<T>` per port
-- `builder.untypedOp(id, op, args)` — escape hatch for operations not in the manifest (returns `void`; use `raw.ref<T>()` to reference its outputs)
-- `builder.build()` — produces a `Flow` document
-- `sdk.request(flow, { signer, inputs, preconditions, sweepTo, ... })` — builds a compile request
+**`sdk.client` (HTTP)**
 
-**HTTP client**
+- `compile(request)`: `POST /compose`. Returns a `ComposeCompileResult` with `status: 'success'` or `status: 'partial'`.
+- `route(request)`: `POST /compose/route`. Returns the same union.
+- `getManifest()`: `GET /compose/manifest`, the live operation registry.
+- `getChains()`: `GET /chains`. Returns `readonly ChainSummary[]` (`{ chainId, name }`), ascending by `chainId`.
+  - A chain is listed once the VM contract is confirmed deployed on it. `compile`, `route`, and `simulate` validate against the same condition, so they reject an unlisted chain. A listed chain can still have no routing edge for a given pair.
+  - `name` is a display label that can change, so key on `chainId`. A chain with no configured label reports `Chain <id>`.
+- `getZapPacks(options?)`: `GET /compose/zap-packs`. Returns the routing edges grouped by protocol as `ZapPackOverview[]`. Filter with `{ protocols: 'aave' }` or an array. See [Discovering routable pairs](#discovering-routable-pairs).
+- `simulate(request)`: `POST /simulate`.
 
-- `sdk.client.compile(request)` — sends the flow to the backend and returns a `ComposeCompileResult` (discriminated union: `status: 'success'` or `status: 'partial'`)
-- `sdk.client.getManifest()` — fetches the operation manifest
-- `sdk.client.getChains()` / `sdk.getSupportedChains()` — fetches the chains this deployment supports as `readonly ChainSummary[]` (`{ chainId, name }`), ascending by `chainId`. A chain is listed once the VM contract is confirmed deployed on it, which is the same condition `compile`, `route` and `simulate` validate against — so a chain missing from this list is rejected by those methods. The converse does not hold: a listed chain can still have no routing edge for a given pair, reported by `route` as `no_route_error`. `name` is a display label maintained by the deployment, so render it but key on `chainId`; a chain with no configured label reports `Chain <id>`. The list tracks the backend's chain registry, which refreshes periodically, and is not cached by the SDK.
-- `sdk.client.getZapPacks(options?)` — fetches the available routing edges grouped by protocol, returning `ZapPackOverview[]`. The catalog is dynamic and is not cached by the SDK. Filter through `GetZapPacksOptions`. An edge with `recipient: 'required'` requires the zap's `recipient` binding, delivers the output externally, and produces an output that cannot be chained or swept. An edge with `availability: 'future'` produces an output that settles only after the initiating transaction; `route` compiles it for you, and on the authoring path it needs `lifi.zapAsync` with a bound `recipient`. Delivery timing governs custody only — a future output still reports an `amount.estimate` (`basis: 'simulated'`, an in-transaction estimate; the delivered amount arrives after settlement), with an `amount.minimum` present only when a minimum source applied. The catalog publishes no settlement duration: a deferred output's ETA rides on the compile result as each future terminal output's `delivery.etaSeconds` in `outputs` (expected seconds until the proceeds land, present only on a `delivery.when: 'future'` output and only when the protocol publishes an estimate; absence means unknown, not zero).
-- `sdk.client.simulate(request)` / `sdk.simulate(request)` — simulates a raw, pre-encoded transaction and returns a `SimulateResult` (discriminated union: `status: 'ok' | 'revert' | 'error'`). See [Simulating a raw transaction](#simulating-a-raw-transaction).
-- `sdk.client.route(request)` / `sdk.route(request)` — compiles a single from/to token pair on one chain via `POST /compose/route`, returning the same `ComposeCompileResult` as `compile()`. See [Routing a token pair](#routing-a-token-pair).
+The SDK caches none of these responses.
 
 **Helpers**
 
-- `resources.erc20(address, chainId)` / `resources.native(chainId)` — resource constructors
-- `guards.*` — guard factories (e.g., slippage)
-- `materialisers.*` — materialiser factories (directDeposit, balanceOf, call)
-- `preconditions.*` — precondition factories (erc20Balance, nativeBalance, erc20Allowance)
-- `raw.ref<T>(path)` — create a typed `$ref` pointer for use in bind slots (escape hatch for `untypedOp` outputs)
-- `raw.guard(kind, config?)` / `raw.materialiser(kind, config?)` — low-level factories for guards and materialisers
-- `buildSimulateRequest({ result, chainId, signer, trackedBalances, requirements?, block?, value? })` — assembles a `SimulateRequest` from a compile result (pure, no I/O)
-- `routeAmount.exact(amount)` / `routeAmount.all(simAmount)` — amount constructors for `sdk.route(...)`
+- `resources.erc20(address, chainId)` / `resources.native(chainId)`.
+- `guards.slippage`, `guards.coreNumericInvariant`.
+- `materialisers.directDeposit`, `materialisers.balanceOf`, `materialisers.call`.
+- `preconditions.erc20Balance`, `preconditions.nativeBalance`, `preconditions.erc20Allowance`.
+- `raw.ref<T>(path)`, `raw.literal(kind, value)`, `raw.guard(kind, config?)`, `raw.materialiser(kind, config?)`: low-level constructors for cases the typed helpers do not cover.
+- `routeAmount.exact(amount)` / `routeAmount.all(simAmount)`: amount constructors for `route`.
+- `buildReachability(packs, { maxHops?, allowAsyncRoutes? })`: the pairs `route` can connect (pure, no I/O).
+- `buildSimulateRequest(...)`: turns a compile result into a `SimulateRequest` (pure, no I/O).
+- `terminalOutputs(outputs)`.
+- `isComposeError`, `isComposePreparationError`, `isComposeSdkOutdatedError`, `isComposeServerOutdatedError`: type guards. `ComposeError` is exported as a type only, so narrow with these rather than `instanceof`.
 
 ## Routing a token pair
 
-Authoring a flow is the general path: you decide the operations and how they chain. `sdk.route(...)` is the shortcut for the case where the backend can decide for you — you hand it a from/to token pair, an amount, and a signer, and it returns the same submit-ready `ComposeCompileResult` that `compile()` returns.
+`sdk.route(...)` is the shortcut for when the backend can choose the operations. You pass a from/to token pair on one chain, an amount, and a signer. It returns the same `ComposeCompileResult` that `compile()` does.
+
+The backend plans the shortest chain of routing-catalog edges for the pair: entering or exiting a protocol position, a wrap or unwrap, a mint or burn. The route can be up to the server's hop ceiling (2 by default). The chain may open with one `lifi.swap` when the input has to be sold first; the swap counts as a hop, so at the default ceiling it precedes at most one catalog edge. That swap only targets a hub token or the underlying of the next deposit, so `route` is not a general swap aggregator.
 
-As of today the backend authors a single zap step for that pair: one edge of its routing catalog — entering or exiting a protocol position, a wrap or unwrap, a mint or burn. It is not a swap aggregator, so a pair with no catalog edge (WETH to USDC, for instance) comes back as `no_route_error`. The endpoint is meant to author more complex flows in future releases, so read the single-step limit as where the server is today rather than as the boundary of the API.
+- Node ids are `hop0`, `hop1`, … and the last node is always `zap`, so the delivered output is `result.outputs['zap.amountOut']`.
+- Every intermediate step settles inside the proxy in the same transaction. Only the last step may pay out to a recipient, or land after settlement (only with `allowAsyncRoutes`).
+- A route that opens with a swap requires `sweepTo`, because the swap can leave unspent input in the proxy. Omitting it fails with `validation_error`.
 
 ```ts
 import { createComposeSdk, routeAmount } from '@lifi/composer-sdk';
@@ -180,73 +187,103 @@ const sdk = createComposeSdk({
 const result = await sdk.route({
   chainId: 1,
   fromToken: '0x0000000000000000000000000000000000000000', // native ETH
-  toToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH — a `wrap` edge
+  toToken: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH, a `wrap` edge
   amount: routeAmount.exact(100_000_000_000_000_000n), // 0.1 ETH
   signer: '0xYourAddress...',
   slippageBps: 100,
 });
 
 if (result.status === 'success') {
-  console.log(result.transactionRequest); // to, data, value, gasLimit
+  console.log(result.transactionRequest); // to, chainId, data, value, gasLimit
 }
 ```
 
 ### Discovering routable pairs
 
-The catalog is dynamic — protocols, chains, and token blacklists move — so discover pairs instead of hardcoding them:
+The catalog changes as protocols, chains, and token blacklists move, so discover pairs instead of hardcoding them. `getZapPacks` lists single edges; `route` chains them. `buildReachability` computes the chained closure locally, using the planner's rule:
 
 ```ts
-const packs = await sdk.client.getZapPacks({ protocols: 'aave' });
+import { buildReachability } from '@lifi/composer-sdk';
 
-for (const pack of packs) {
-  for (const edge of pack.edges) {
-    console.log(pack.protocol, edge.type, edge.in.address, '->', edge.out.address);
-  }
+const packs = await sdk.client.getZapPacks();
+const reach = buildReachability(packs);
+
+reach.canRoute(aUsdc, yvUsdc); // aUSDC -> USDC -> yvUSDC: true
+for (const pair of reach.routableFrom(aUsdc)) {
+  console.log(pair.in.address, '->', pair.out.address, `(${pair.hops} hops)`);
 }
 ```
 
-Every edge is one routable pair: `edge.in` and `edge.out` are the `fromToken` and `toToken` of a `route` call on `edge.in.chainId`, and `inAmountMin` / `inAmountMax` bound the amount when the protocol constrains it. Two edge fields change how you call `route`:
+`pair.in` and `pair.out` are the `fromToken` and `toToken` of a `route` call on `pair.in.chainId`. The rule the helper applies, and the server enforces:
 
-- **`recipient: 'required'`** — the protocol mints to a named receiver, so set `sweepTo` when the output should not land with the signer.
-- **`availability: 'future'`** — the output only exists once the transaction settles. `route` skips these unless you pass `allowAsyncRoutes: true`, so by default a pair reachable only this way is a `no_route_error` and every terminal output delivers now (`delivery.when: 'now'`). Opt in and `sweepTo` names the future output's owner, no slippage floor is applied, and you must track settlement rather than treat the transaction as completing the job. A synchronous edge still wins whenever the pair has one, so read each terminal output's `delivery.when` in `result.outputs` to know which representation you got.
+- Every edge except the last must leave its output in the proxy for the next edge to consume. An edge with `recipient: 'required'` or `availability: 'future'` can only be the last hop.
+- The last edge must be synchronous, unless you pass `allowAsyncRoutes: true` to both `buildReachability` and `route`.
+- A route never visits the same token twice and never exceeds `maxHops`.
 
-### Amounts
+The helper can overstate or miss what `route` accepts in a few ways:
+
+- `maxHops` defaults to 2, the deployment default. The server reports its effective value in `no_route_error` `details.maxHops`; pass that value if it differs.
+- The helper cannot check `inAmountMin` / `inAmountMax` on an intermediate hop without an amount. A reported pair is routable structurally, just as a listed edge is.
+- The server drops blacklisted tokens as intermediates, so a reported pair can still return `no_route_error`.
+- Routes that open with a `lifi.swap` depend on what the aggregator can sell, so the helper does not report them.
 
-The `amount` field is a discriminated union with two variants, built by `routeAmount`:
+Two edge fields change how you call `route`:
 
-- **`routeAmount.exact(amount)`** — spend exactly `amount` of `fromToken`, in its smallest unit. Use this when you know the figure.
-- **`routeAmount.all(simAmount)`** — spend the signer's whole `fromToken` balance, resolved on-chain at execution time. `simAmount` is only an estimate: the quote, the price impact, and the returned approvals are computed against it, but the amount actually moved is the real balance when the transaction lands. Pass your best estimate of the balance — a wildly wrong figure produces a poor quote. Not supported for a native `fromToken`: a gas coin arrives via `msg.value`, so there is no balance to sweep, and the server rejects the request.
+- **`recipient: 'required'`**: the protocol mints to a named receiver. Set `sweepTo` when the output should not land with the signer.
+- **`availability: 'future'`**: the output only exists once the transaction settles, and `route` uses such an edge only with `allowAsyncRoutes: true`. Once opted in:
+  - `sweepTo` names the future output's owner.
+  - No slippage floor applies.
+  - You must track settlement.
+  - A synchronous route still wins whenever one exists, so read each terminal output's `delivery.when`.
 
-Both accept a `bigint` or a decimal string. `bigint` values are serialised for you.
+  A future output still reports `amount.estimate` (`basis: 'simulated'`, the in-transaction estimate). The catalog carries no settlement time. The compile result carries it as `delivery.etaSeconds` on a future terminal output; that field is absent when the protocol publishes no estimate, and absence means unknown, not zero.
+
+### Amounts
+
+- **`routeAmount.exact(amount)`**: spend exactly `amount` of `fromToken`, in its smallest unit.
+- **`routeAmount.all(simAmount)`**: spend the signer's whole `fromToken` balance, read on-chain at execution time.
+  - The quote, price impact, and returned approvals are computed against `simAmount`. The transaction moves the real balance, so pass a realistic estimate.
+  - Not supported for a native `fromToken`: a gas coin arrives via `msg.value`, so there is no balance to sweep.
+
+Both accept a `bigint` or a decimal string.
 
 ### Options
 
-`sdk.route(...)` shares its optional fields with the authoring path, and the server applies the same defaults. Omit a field to take the default; the SDK sends only what you set.
+The SDK sends only the fields you set. The server applies the defaults.
 
-- **`slippageBps`** — tolerance in basis points. Defaults to `100` (1%).
-- **`maxPriceImpactBps`** — reject the route if the priced impact exceeds this. No cap by default.
-- **`integratorFeeBps`** — your fee, in basis points, taken from the input amount before the route executes. Requires an integration-scoped `apiKey`; a non-zero value without one is rejected.
-- **`referrer`** — attribution string passed to the routing provider.
-- **`sweepTo`** — address that receives the output and any leftover dust. Accepts a literal address or `{ $ref: 'context.sender' }`. Defaults to the signer.
-- **`checkOnChainAllowances`** — when `true`, the server reads current allowances and omits approvals that are already sufficient. Defaults to `false`.
-- **`simulationPolicy`** — `'strict'` (default) or `'allow-revert'`, exactly as on the authoring path. See [Simulation policy and partial results](#simulation-policy-and-partial-results).
-- **`simulateUserProgram`** — when `true`, additionally simulates the final user-facing transaction after the structured simulation succeeds. Defaults to `false`.
-- **`allowAsyncRoutes`** — when `true`, accept a route whose output arrives only after the initiating transaction settles. Defaults to `false`, which leaves such a pair a `no_route_error` and guarantees every terminal output delivers now (`delivery.when: 'now'`). Set it only if you track settlement and can live without a slippage floor.
+- **`slippageBps`**: default `100` (1%). An end-to-end tolerance on the route's final output, not a per-hop one.
+- **`maxPriceImpactBps`**: reject the route when its priced impact exceeds this. Default `500`; `0` disables the check.
+- **`integratorFeeBps`**: your fee, taken from the input amount. Range 0 to 9000, default `0`. A non-zero value requires an integration-scoped `apiKey`.
+- **`referrer`**: opaque tag forwarded to the underlying quote provider.
+- **`sweepTo`**: owner of everything the route leaves behind. An address or `{ $ref: 'context.sender' }`; `context.executionAddress` is rejected. Defaults to the signer, except that a route with a swap requires it.
+- **`checkOnChainAllowances`**: omit approvals that current allowances already cover. Default `false`.
+- **`simulationPolicy`**: `'strict'` (default) or `'allow-revert'`. See [Simulation policy and partial results](#simulation-policy-and-partial-results).
+- **`simulateUserProgram`**: also simulate the final user-facing transaction after the structured simulation succeeds. Default `false`.
+- **`allowAsyncRoutes`**: accept a route whose output arrives after the transaction settles. Default `false`, which guarantees every terminal output is `delivery.when: 'now'`.
 
 ### When to author a flow instead
 
-`route` gives you one server-authored step. Reach for `sdk.flow(...)` when you need anything it does not express: several operations chained together, splitting one input across several destinations, guards on intermediate outputs, explicit preconditions, arithmetic, or funding from proxy-held balances. Swapping WETH to USDC and then depositing the USDC into Aave is a flow; depositing USDC straight into Aave is a route. An asynchronous position (`availability: 'future'`) as the destination is a route once you pass `allowAsyncRoutes: true` — the server picks `lifi.zapAsync` for you — but authoring the flow yourself is still the way to combine it with other steps.
+Use `sdk.flow(...)` for anything `route` cannot express:
+
+- a chain you choose yourself, or one longer than the hop ceiling
+- one input split across several destinations
+- guards on intermediate outputs
+- explicit preconditions or arithmetic
+- funding from proxy-held balances
+- combining an asynchronous position with other steps
+
+For example, swapping WETH to USDC and depositing the USDC into Aave is a route when the planner can connect it, and a flow when you want to control the swap or add steps.
 
 ### Errors
 
-`route` maps failures the same way `compile` does — see [Error handling](#error-handling). Two are specific to this path:
+`route` maps failures like `compile` does (see [Error handling](#error-handling)). Two outcomes are specific to it:
 
-- **`NOT_FOUND`** with `kind: 'no_route_error'` — the backend has no routing edge for the pair on that chain. `sdk.client.getZapPacks()` reports which edges exist.
-- **`VALIDATION_ERROR`** — the pair is routable but the request is rejected, for example a price impact above `maxPriceImpactBps`, or a simulation revert under the default `'strict'` policy.
+- **`NOT_FOUND`** with `kind: 'no_route_error'`: the planner cannot connect the pair within `details.maxHops` edges. `details.searchTruncated` reports whether the search hit its work bound.
+- **`VALIDATION_ERROR`**: the pair connects but the request is rejected. Examples: price impact above `maxPriceImpactBps`, or a simulated revert under `'strict'`.
 
 ## Simulation policy and partial results
 
-By default, the Compose backend simulates the compiled transaction and returns an error (HTTP 422) if simulation detects a revert. You can opt into receiving a **partial result** instead by passing `simulationPolicy: 'allow-revert'`:
+The backend simulates every compiled transaction. Under the default `simulationPolicy: 'strict'`, a revert throws a `ComposeError` with code `VALIDATION_ERROR` (HTTP 422). With `'allow-revert'` you get a **partial result** (HTTP 206) instead:
 
 ```ts
 const result = await builder.compile({
@@ -256,57 +293,35 @@ const result = await builder.compile({
 });
 
 if (result.status === 'success') {
-  // Simulation succeeded. transactionRequest includes gasLimit.
-  const tx = result.transactionRequest;
-  console.log(tx.gasLimit); // string
+  console.log(result.transactionRequest?.gasLimit); // string
 } else {
-  // result.status === 'partial'
-  // Simulation reverted, but a transaction is still available (without gasLimit).
+  // status === 'partial': the transaction is returned without gasLimit;
+  // estimate gas yourself.
   console.log(result.error.kind); // 'simulation_revert'
-  console.log(result.error.message); // human-readable revert description
+  console.log(result.error.message);
 
-  // Revert diagnostics
   const revert = result.simulationRevert;
-  console.log(revert.code); // e.g. 3
-  console.log(revert.rawErrorBytes); // raw ABI-encoded error
-
-  // Decoded error candidates (when available)
-  if (revert.decodeResult?.errorCandidates) {
-    for (const c of revert.decodeResult.errorCandidates) {
-      console.log(c.decodedErrorSignature, c.decodedParams);
-    }
+  console.log(revert.code, revert.rawErrorBytes);
+  for (const c of revert.decodeResult?.errorCandidates ?? []) {
+    console.log(c.decodedErrorSignature, c.decodedParams);
   }
 
-  // The transactionRequest is still usable — the caller must estimate gas themselves.
   const tx = result.transactionRequest;
   console.log(tx.to, tx.data, tx.value);
 }
 ```
 
-The `simulationPolicy` field accepts two values:
-
-- `'strict'` (default) — revert causes a thrown `ComposeError` with code `VALIDATION_ERROR`
-- `'allow-revert'` — revert returns a partial result with `status: 'partial'`
-
-You can also pass `checkOnChainAllowances: true` to have the server filter the returned `approvals` array against current on-chain allowances, omitting approvals that are already sufficient:
-
-```ts
-const result = await builder.compile({
-  signer: OWNER,
-  inputs: { amountIn: materialisers.balanceOf({ owner: OWNER }) },
-  checkOnChainAllowances: true,
-});
-```
+Pass `checkOnChainAllowances: true` to have the server drop entries from `approvals` that current on-chain allowances already cover.
 
 ## Simulating a raw transaction
 
-`sdk.client.simulate(...)` (and the `sdk.simulate(...)` pass-through) answer a question the compile pipeline does not: _if I send this exact transaction, how do specific token balances change and how much gas does it burn?_ It takes a raw, pre-encoded transaction (a `to`, hex `data`, optional native `value`), funds a sender, runs it in one `eth_call`, and reports the watched balances before/after, their signed deltas, and the inner-call gas.
+`sdk.client.simulate(...)` (and `sdk.simulate(...)`) answers a question compile does not: if I send this exact transaction, how do specific balances change, and how much gas does it burn? It takes a pre-encoded transaction (`to`, hex `data`, optional `value`). It funds the sender as `requirements` describe, runs the transaction in one `eth_call`, and reports the watched balances before and after, their signed deltas, and the inner-call gas.
 
 ```ts
 import { createComposeSdk } from '@lifi/composer-sdk';
 
 const sdk = createComposeSdk({
-  baseUrl: 'https://li.quest',
+  baseUrl: 'https://composer.li.quest',
   apiKey: process.env.LIFI_API_KEY!,
 });
 
@@ -315,13 +330,13 @@ const result = await sdk.client.simulate({
   from: '0x1111111111111111111111111111111111111111',
   to: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC
   data: '0xa9059cbb...', // pre-encoded transfer calldata
-  value: 0n, // bigint accepted; serialised to "0"
+  value: 0n,
   requirements: [
     {
       type: 'Erc20Balance',
       wallet: '0x1111111111111111111111111111111111111111',
       token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
-      balance: 1_000_000n, // bigint accepted
+      balance: 1_000_000n,
     },
   ],
   trackedBalances: [
@@ -338,25 +353,27 @@ const result = await sdk.client.simulate({
 
 switch (result.status) {
   case 'ok':
-    // Successful simulation.
     console.log(result.gasUsed, result.deltas);
     break;
   case 'revert':
-    // The simulation ran but the transaction reverted on-chain — NOT an error.
+    // The simulation ran and the transaction reverted. Not an error.
     console.log(result.revertReason, result.decodeResult);
     break;
   case 'error':
-    // The request was well-formed but the simulation could not be set up/run.
+    // Well-formed request, but the simulation could not be set up or run.
     console.log(result.message);
     break;
 }
 ```
 
-`requirements` is the funding-instruction union (`Erc20Balance`, `NativeBalance`, `Erc20Allowance`); use the zero address as a `trackedBalances` `token` to watch native balance. Amount fields accept `bigint` (serialised to decimal strings) or strings. The caps `SIMULATE_MAX_TRACKED_BALANCES` and `SIMULATE_MAX_REQUIREMENTS` (both `40`) are exported for reference.
+- `requirements` entries are `Erc20Balance`, `NativeBalance`, or `Erc20Allowance`. Use the zero address as a `trackedBalances` token to watch the native balance.
+- Amount fields accept `bigint` or decimal strings.
+- `SIMULATE_MAX_TRACKED_BALANCES` and `SIMULATE_MAX_REQUIREMENTS` (both `40`) are exported.
+- A `revert` is returned, not thrown. Only transport failures and HTTP 400/401/403/404/429/5xx throw `ComposeError`.
+- `gasUsed` is inner-call execution gas only; it excludes the 21000 base cost and calldata gas.
+- EOA-only behaviour, such as `msg.sender == tx.origin` checks, is not simulated faithfully, because the call runs through injected VM bytecode rather than a real EOA.
 
-Unlike `compile`, a `revert` is returned (not thrown): a revert is a _successful simulation_ whose execution reverted. Only transport failures and HTTP 400/401/403/404/429/5xx throw `ComposeError`.
-
-To simulate a transaction you just compiled, `buildSimulateRequest(...)` assembles the request without re-typing the transaction fields. `chainId` and `signer` are required (a compile result carries neither), and `trackedBalances`/`requirements` cannot be inferred from a flow:
+To simulate a transaction you just compiled, `buildSimulateRequest(...)` fills in the transaction fields from the compile result. A compile result carries neither `chainId` nor `signer`, so pass both. Nothing in a flow says which balances to watch, so pass `trackedBalances` and any `requirements` too. It throws when the result has no single `transactionRequest` (a flow funded by an external action); submit that result's `actions` instead.
 
 ```ts
 import { buildSimulateRequest } from '@lifi/composer-sdk';
@@ -376,13 +393,11 @@ const req = buildSimulateRequest({
 const sim = await sdk.client.simulate(req);
 ```
 
-Two caveats from the endpoint: `gasUsed` is the inner-call execution gas only (it excludes the 21000 base tx cost and calldata gas), and EOA-only behaviour (e.g. `msg.sender == tx.origin` checks) is not faithfully simulated because the call runs through injected VM bytecode rather than a real EOA. See [`docs/references/simulate-endpoint.md`](../../../docs/references/simulate-endpoint.md) for the full contract.
-
-Two runnable examples cover both paths: [`src/examples/simulateRawTransaction.ts`](src/examples/simulateRawTransaction.ts) builds a raw `SimulateRequest` directly, and [`src/examples/simulateCompiledSwap.ts`](src/examples/simulateCompiledSwap.ts) shows the end-to-end compile → `buildSimulateRequest` → `simulate` arc.
+Runnable versions: [`src/examples/simulateRawTransaction.ts`](src/examples/simulateRawTransaction.ts) and [`src/examples/simulateCompiledSwap.ts`](src/examples/simulateCompiledSwap.ts).
 
 ## Error handling
 
-All SDK errors are thrown as `ComposeError` with a `code` property:
+HTTP and transport failures are thrown as a `ComposeError`. Builder mistakes (a duplicate node id, a missing output port) throw a plain `Error` at the call site. Narrow with `isComposeError`:
 
 ```ts
 import { isComposeError } from '@lifi/composer-sdk';
@@ -391,13 +406,26 @@ try {
   const result = await sdk.client.compile(request);
 } catch (err) {
   if (isComposeError(err)) {
-    console.error(err.code, err.message);
-    // Codes: VALIDATION_ERROR, SERVER_ERROR, RATE_LIMITED, NETWORK_ERROR, ...
+    console.error(err.code, err.status, err.kind, err.message);
+    console.error(err.path, err.port, err.fix); // when the server names a location or a fix
   }
 }
 ```
 
-A `preparation_error` (HTTP 422) means some prepared ops failed while others succeeded — a mixed basket with an unroutable leg. Narrow with `isComposePreparationError` to read which ops failed, then drop those `callId`s from the flow and resubmit:
+| `code`             | HTTP status | Typical cause                                                   |
+| ------------------ | ----------- | --------------------------------------------------------------- |
+| `VALIDATION_ERROR` | 400, 422    | Malformed or rejected flow or request, simulated revert, guard  |
+| `UNAUTHENTICATED`  | 401         | Missing or invalid API key                                      |
+| `FORBIDDEN`        | 403         | The server refuses the request                                  |
+| `NOT_FOUND`        | 404         | `no_route_error`                                                |
+| `RATE_LIMITED`     | 429         | Too many requests                                               |
+| `SERVER_ERROR`     | 5xx         | Backend failure or a dependency temporarily unavailable        |
+| `NETWORK_ERROR`    | none        | The request never got a response                                |
+| `UNKNOWN_ERROR`    | other       | Unexpected status                                               |
+
+`kind` is the backend's finer-grained classification, e.g. `simulation_revert`, `guard_error`, or `price_impact_exceeded`. When `kind` is `simulation_revert`, `err.details` has the same shape as `result.simulationRevert`.
+
+A `preparation_error` (HTTP 422) means some prepared ops (ops that fetch external quotes at compile time, such as `lifi.swap`) failed while others succeeded, e.g. a mixed basket with one unroutable leg. Narrow with `isComposePreparationError`, drop the failed node ids from the flow, and resubmit:
 
 ```ts
 import { isComposePreparationError } from '@lifi/composer-sdk';
@@ -409,72 +437,68 @@ try {
     for (const op of err.failedOps) {
       console.error(op.callId, op.op, op.kind, op.message);
     }
-    // Prepared ops that succeeded. Both arrays list prepared ops only, so
-    // retry by removing the `failedOps` callIds from the original flow.
+    // Only the prepared ops that succeeded, not the rest of the flow. To retry,
+    // remove the failedOps callIds from the original flow.
     console.error('prepared ok:', err.succeededOps);
   }
 }
 ```
 
-See [`docs/sdk-interface.md`](docs/sdk-interface.md#per-op-preparation-failures) for the full error surface.
+**Version mismatch.** `compile` and `route` fail with `kind: 'sdk_outdated'` when this SDK is older than the oldest version the backend serves. They fail with `kind: 'server_outdated'` when the SDK is newer than the backend in any version component, which happens between an npm release and the backend rollout. Both come back as `VALIDATION_ERROR`. `isComposeSdkOutdatedError(err)` exposes `err.sdkOutdated.minimumSdkVersion`; `isComposeServerOutdatedError(err)` exposes `err.serverOutdated.serverVersion`. On `server_outdated`, pin both packages to the server's version or wait for the rollout.
 
 ## Examples
 
-The `src/examples/` directory contains complete working examples:
-
-- **lifiSwap** — Single token swap (WETH to USDC)
-- **lifiZap** — Swap into a DeFi position
-- **lifiZapAsync** — Zap into a position whose output settles after the initiating transaction (future availability)
-- **swapAndZap** — Multi-step: swap then deposit
-- **splitAndZap** — Split a resource and zap each portion into a different vault
-- **splitWithArithmetic** — Split then verify with add/subtract/assertEqual assertions
-- **dustSweep** — Split and partially use tokens, sweep leftover dust back to sender
-- **depositFromProxy** — Read tokens already on the proxy via `balanceOf`, with a precondition guard
-- **approveAndDeposit** — Approve a vault, deposit, and graduate shares via `asResource`
-- **consolidateToUsdc** — Consolidate multiple tokens into USDC
-- **consolidateToEth** — Consolidate multiple tokens into ETH
-- **swapToRecipient** — Swap and send to a different address
-- **swapWithBalanceCheck** — Swap with balance precondition
-- **swapWithOutputValidation** — Swap with computed slippage bounds using bpsDown/bpsUp/assertInRange
-- **rawCallWithArithmetic** — Query a contract with pre-encoded calldata, then scale with multiply/divide
-- **readContractState** — Compare peek (compile-time), staticCall (execution-time), and balanceOf (resource)
-- **swapWithAllowRevert** — Swap with `simulationPolicy: 'allow-revert'` and handle the `ComposeCompileResult` discriminated union
-- **swapWithFee** — Swap while collecting an integrator fee via `integratorFeeBps` (requires an integration-scoped `apiKey`)
-- **transferTokens** — Transfer ERC-20 tokens from the proxy to an arbitrary recipient
-- **callContract** — Call an arbitrary contract (ERC-4626 redeem; reward claim) without a dedicated typed op
-- **aaveRepay** — Repay an Aave v3 variable-rate debt, sweeping the unspent residual back to the sender
-- **aaveRepayWithATokens** — Repay Aave v3 debt by burning aToken collateral already held by the proxy
-- **aaveClaimRewards** — Claim accrued Aave rewards and forward the claimed amount to a recipient
-- **aaveSetEMode** — Switch the proxy's Aave v3 eMode category
-- **untypedOpWithTypedRef** — Insert an untyped operation node via `untypedOp`, then bridge its output into typed operations using `raw.ref<T>()`
-- **routeTokenPair** — Compile a from/to token pair via `sdk.route(...)`, with both the `exact` and `all` amount variants
-- **supportedChains** — Cache `sdk.getSupportedChains()`, then preflight a chain and label it from the response's `name`, so an unsupported one fails locally with a message naming the alternatives
+Each file in `src/examples/` is a complete flow:
+
+- **lifiSwap**: single token swap (WETH to USDC)
+- **lifiZap**: swap into a DeFi position
+- **lifiZapAsync**: zap into a position whose output settles after the initiating transaction
+- **swapAndZap**: swap, then deposit
+- **splitAndZap**: split a resource and zap each part into a different vault
+- **splitWithArithmetic**: split, then check with add/subtract/assertEqual
+- **dustSweep**: split, use part of the tokens, sweep the rest back to the sender
+- **depositFromProxy**: spend tokens already on the proxy via `balanceOf`, with a precondition
+- **approveAndDeposit**: approve a vault, deposit, and turn the shares into a resource via `asResource`
+- **consolidateToUsdc** / **consolidateToEth**: consolidate several tokens into one
+- **swapToRecipient**: swap and send to another address
+- **swapWithBalanceCheck**: swap with a balance precondition
+- **swapWithOutputValidation**: swap with computed bounds via bpsDown/bpsUp/assertInRange
+- **invariantChecks**: swap, then assert the output with `invariant.gte` and an allowance with `invariant.allowanceAtLeast`
+- **rawCallWithArithmetic**: query a contract with pre-encoded calldata, then scale the result
+- **readContractState**: compare `peek` (compile time), `staticCall` (execution time), and `balanceOf` (resource)
+- **emitCustomEvent**: emit a custom event with `core.emitEvent2`; `bytes32` ports accept any static 32-byte handle
+- **swapWithAllowRevert**: handle both branches of `ComposeCompileResult` under `'allow-revert'`
+- **swapWithFee**: collect an integrator fee via `integratorFeeBps` (requires an integration-scoped `apiKey`)
+- **transferTokens**: transfer ERC-20 tokens from the proxy to any recipient
+- **callContract**: call an arbitrary contract (ERC-4626 redeem, reward claim) without a typed op
+- **flySwap**: on Base, exit a Pendle PT via `lifi.zap`, then swap all proceeds to WETH with `fly.swap`
+- **aaveRepay**: repay Aave v3 variable debt and sweep the unspent residual to the sender
+- **aaveRepayWithATokens**: repay Aave v3 debt by burning aTokens held by the proxy
+- **aaveClaimRewards**: claim Aave rewards and forward them to a recipient
+- **aaveSetEMode**: switch the proxy's Aave v3 eMode category
+- **untypedOpWithTypedRef**: add a node with `untypedOp`, then use its output in typed ops via `raw.ref<T>()`
+- **routeTokenPair**: `sdk.route(...)` with both the `exact` and `all` amount variants
+- **supportedChains**: cache `sdk.getSupportedChains()`, then fail an unsupported chain locally with a message naming the alternatives
+- **simulateRawTransaction** / **simulateCompiledSwap**: raw and compiled simulation
 
 ## Staging channel
 
-Some operations exist on the Compose backend but are deliberately held back from the default SDK — for example an op whose required contract changes are not yet live on production. These **staged** operations are published on a separate npm dist-tag, `staging`:
+Some operations run on the backend but are held back from the default SDK, for example because their contract changes are not live in production yet. These **staged** operations are published on the `staging` npm dist-tag:
 
 ```bash
 npm install @lifi/composer-sdk@staging @lifi/compose-spec@staging
 ```
 
-The `staging` build includes the not-yet-public operations in its typed surface (e.g. `lifi.flashloanRepay`), so you can author flows against them with full type-checking. The default install (`@lifi/composer-sdk`, the `latest` dist-tag) never exposes them.
-
-A staged operation only runs if the backend you point at actually has it enabled. The SDK has no default backend — you supply one per instance:
+The `staging` build types the staged operations (e.g. `lifi.flashloanRepay`). The default install never exposes them. A staged operation only runs on a backend that has it enabled, so point `baseUrl` at one:
 
 ```ts
 const sdk = createComposeSdk({
-  baseUrl: '<staging-backend-url>', // a backend that has the staged ops enabled
+  baseUrl: '<staging-backend-url>',
   apiKey: process.env.LIFI_API_KEY!,
 });
 ```
 
-Calling a staged operation against a backend that does not have it enabled fails at runtime as a service-level error; the typed surface being present does not guarantee backend availability.
-
-The channel and the backend URL are independent:
-
-- The `staging` **channel** is durable — it is a permanent property of `main`, and which operations it carries rotates over time as ops graduate to `latest`.
-- The `baseUrl` is **per-environment and disposable** — it is a runtime argument, not a build-time property, so the same staging build can target whichever backend currently has the ops enabled.
+Against a backend without the operation, the call fails at runtime; having the types does not mean the backend supports the operation. The channel is permanent, and its contents rotate as ops graduate to `latest`. The backend URL is a runtime argument, so one staging build can target whichever backend has the ops enabled.
 
 ## License