@lifi/compose-spec
Version:
Public wire-format types and schemas for Compose flows
166 lines (160 loc) • 7.96 kB
text/typescript
/**
* Canonical request types for the `POST /compose/route` convenience endpoint.
* Amounts accept `bigint | string` for authoring convenience; the JSON wire
* format is always a decimal string, which the SDK serialises for you.
*
* `/compose/route` trades authoring power for brevity. Instead of a full flow
* document it takes a single from/to token pair; the server plans a route for
* that pair, builds the flow with a `directDeposit` input on the caller's
* behalf, and runs it through the same compile pipeline as `POST /compose`.
* The route is the shortest admissible chain of routing-catalog edges up to an
* operator-set hop ceiling, and may begin with an aggregator swap when the
* catalog alone cannot connect the pair. Terminal hops route through
* `lifi.zap`, or `lifi.zapAsync` when the pair is reachable only
* asynchronously and the request set `allowAsyncRoutes`. The route itself is
* not disclosed: node ids are `hop0`, `hop1`, … with the terminal always
* `zap`, so `outputs['zap.amountOut']` is the terminal output at every route
* length and intermediate outputs carry `role: 'consumed'`. Its response body
* is byte-identical to that of `POST /compose` — the enveloped
* `ComposeCompileSuccessData` on HTTP 200 and `ComposeCompilePartialData` on
* HTTP 206 — so this file declares only the request shape and reuses
* `ComposeCompileResult` from `./compile.js` for the result.
*
* These are the single source of truth for the request shape, hand-authored
* here for the same reason as `./compile.ts` and `./simulate.ts` rather than
* derived from the validating schema: that schema is the Zod one in
* `@lifi/api-schemas` (`src/routes/composeRoute.ts`), a package that depends on
* this one, so importing its inferred types here would invert the dependency —
* and the public SDK ships this package as its only peer dependency, never the
* server's schema package. The two definitions are held in lockstep by a
* compile-time conformance assertion
* (`api-schemas/src/routes/composeRoute.typecheck.ts`), which fails the build
* if either side drifts.
*/
import type { SimulationPolicy } from './compile.js';
import type { ForwardTo } from './flowSchema.js';
/**
* Spend an exact amount of `fromToken`.
*
* `amount` is in the token's smallest unit. Accepts `bigint | string`; the wire
* format is a non-negative decimal string.
*/
export interface RouteAmountExact {
readonly type: 'EXACT';
readonly amount: bigint | string;
}
/**
* Spend the signer's entire `fromToken` balance, whatever it is at execution
* time.
*
* The on-chain amount is resolved by a deposit-all materialiser, so it is not
* known when the route is compiled. `simAmount` is the stand-in the server
* quotes and simulates against — make it a realistic estimate of the balance,
* because it determines the quote and the derived preconditions, not the amount
* actually moved. Accepts `bigint | string`; the wire format is a non-negative
* decimal string.
*
* Not supported when `fromToken` is the chain's native sentinel: a gas coin
* arrives via `msg.value`, so there is no on-chain balance to sweep, and the
* server rejects the combination with a `validation_error`. Use
* {@link RouteAmountExact} for native inputs.
*
* On a route that begins with an aggregator swap the swap's input amount is
* pinned to the quoted amount derived from `simAmount`: a runtime balance below
* that pinned amount reverts, and a balance above it leaves the remainder as
* `unspentIn`, which may be most of the input and which `sweepTo` receives.
* Under `EXACT` the deposit and the pinned quote are the same number, so the
* `unspentIn` output is zero and omitted; any pre-existing dust of the sold
* token in the proxy is moved to `sweepTo` by the whole-balance sweep
* independently of that output.
*/
export interface RouteAmountAll {
readonly type: 'ALL';
readonly simAmount: bigint | string;
}
/**
* How much of `fromToken` a route spends. Two variants, discriminated by
* `type`.
*/
export type RouteAmount = RouteAmountExact | RouteAmountAll;
/** Request body for `POST /compose/route`. */
export interface ComposeRouteRequest {
/** EVM chain id. Both tokens must live on this chain — routes are same-chain. */
readonly chainId: number;
/**
* Token to spend. Use the chain's native sentinel address for the gas coin
* (the zero address on EVM-native chains).
*/
readonly fromToken: string;
/** Token to receive. */
readonly toToken: string;
/** How much of `fromToken` to spend — an exact amount or the whole balance. */
readonly amount: RouteAmount;
/** Address that funds the route and, by default, owns its output. */
readonly signer: string;
/**
* Slippage tolerance in basis points. Range 0–10000. Defaults to `100` (1%)
* server-side when omitted. It is an end-to-end tolerance: the floor is the
* simulated final output of the whole route, so a multi-hop route is not
* bounded hop by hop. When the route begins with an aggregator swap the same
* value is also the swap's own tolerance, which nests inside the end-to-end
* floor rather than compounding with it.
*/
readonly slippageBps?: number;
/**
* Reject the route when its quoted price impact exceeds this many basis
* points. Range 0–10000. Omitted ⇒ the server's default of 500 bps applies;
* `0` disables the check.
*/
readonly maxPriceImpactBps?: number;
/** Opaque referrer tag forwarded to the underlying quote provider. */
readonly referrer?: string;
/**
* Owner of every asset the route leaves behind; defaults to `signer` on a
* route with no aggregator swap. Routes whose protocol mints to a named
* receiver (surfaced as `recipient: 'required'` by `GET /compose/zap-packs`)
* and asynchronous routes bind this address at mint time rather than
* transferring afterwards; otherwise the proxy's whole balance of each
* asset the route leaves is transferred here.
*
* **Required when the route includes an aggregator swap.** Such a route can
* leave an asset the caller did not plan for — the swap's unspent input —
* and this address receives it alongside the terminal output, so it must be
* named explicitly; omitting it fails with `validation_error`.
*
* Accepts an address or `{ $ref: 'context.sender' }` (which counts as
* explicit); `{ $ref: 'context.executionAddress' }` is rejected.
*/
readonly sweepTo?: ForwardTo;
/**
* `'strict'` (the default) fails the request when simulation detects a
* revert; `'allow-revert'` returns a partial result with revert diagnostics
* instead.
*/
readonly simulationPolicy?: SimulationPolicy;
/**
* Also simulate the final user-facing transaction after the structured
* simulation succeeds. Reverts honour `simulationPolicy`. Defaults to `false`.
*/
readonly simulateUserProgram?: boolean;
/**
* Filter the returned `approvals` against current on-chain allowances,
* omitting approvals that are already sufficient. Defaults to `false`.
*/
readonly checkOnChainAllowances?: boolean;
/**
* Accept a route whose output is delivered only after the initiating
* transaction settles (`delivery.when: 'future'` on the terminal output).
* Such a route obliges you to track settlement rather than treat the
* transaction as completing the job, and carries no slippage floor, so it is
* opt-in. Defaults to `false` server-side, which leaves a pair reachable
* only asynchronously rejected with `no_route_error` and guarantees every
* terminal output is `delivery.when: 'now'`.
*
* It widens reach, it is not a preference: a synchronous route wins at any
* length, so a pair with both a one-hop asynchronous edge and a longer
* synchronous route is served synchronously. Opting in never costs you a
* synchronous route.
*/
readonly allowAsyncRoutes?: boolean;
}