UNPKG

@lifi/compose-spec

Version:

Public wire-format types and schemas for Compose flows

166 lines (160 loc) • 7.96 kB
/** * 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; }