@lifi/composer-sdk 0.4.0 → 0.5.0

package/src/generated/operations.generated.ts

@@ -1,10 +1,7 @@
 // AUTO-GENERATED from manifest.json — do not edit by hand.
 // Regenerate with: yarn workspace @lifi/composer-sdk generate
 
-import type {
-  AnyBindable,
-  FlowBuilderInternal,
-} from '../authoring/FlowBuilderCore.js';
+import type { FlowBuilderInternal } from '../authoring/FlowBuilderCore.js';
 import type { Bindable, OutputHandle } from '../authoring/handles.js';
 import type {
   CoreCallResult,
@@ -38,6 +35,7 @@ import type {
   CoreSplitConfig,
   CoreStaticCallConfig,
   CoreTransferConfig,
+  FlySwapConfig,
   InvariantEqConfig,
   InvariantGtConfig,
   InvariantGteConfig,
@@ -47,6 +45,7 @@ import type {
   InvariantNumericConfig,
   InvariantNumericInRangeConfig,
   LifiSwapConfig,
+  LifiZapAsyncConfig,
   LifiZapConfig,
   MorphoBlueSupplyCollateralConfig,
   MorphoBlueWithdrawCollateralConfig,
@@ -520,11 +519,22 @@ export interface MorphoBlueWithdrawCollateralArgs {
 export interface LifiZapArgs {
   readonly bind: {
     readonly amountIn: Bindable<'resource'>;
+    readonly recipient?: Bindable<'address'>;
   };
   readonly config: LifiZapConfig;
   readonly guards?: readonly TypedGuard<'amountOut'>[];
 }
 
+/** Route tokens into a DeFi protocol position whose output becomes available after the initiating transaction settles */
+export interface LifiZapAsyncArgs {
+  readonly bind: {
+    readonly amountIn: Bindable<'resource'>;
+    readonly recipient: Bindable<'address'>;
+  };
+  readonly config: LifiZapAsyncConfig;
+  readonly guards?: readonly TypedGuard<never>[];
+}
+
 /** Exact-output (BUY) swap via the Paraswap/Velora Market API: produce exactly `exactAmountOut` of the destination token, pulling only the source needed and exposing the genuinely-unspent source as `unspentIn`. */
 export interface ParaswapBuyArgs {
   readonly bind: {
@@ -541,6 +551,15 @@ export interface CorePeekArgs {
   readonly guards?: readonly TypedGuard<'result'>[];
 }
 
+/** Swap via Fly's DexAggregator, sized at runtime: the router calldata leaves `amountIn` unset, so an upstream op's output can feed the swap without being known at plan time. Either leg may be the chain-native coin. */
+export interface FlySwapArgs {
+  readonly bind: {
+    readonly amountIn: Bindable<'resource'>;
+  };
+  readonly config: FlySwapConfig;
+  readonly guards?: readonly TypedGuard<'unspentIn'>[];
+}
+
 export interface CoreSplitOutputs {
   readonly a: OutputHandle<'resource'>;
   readonly b: OutputHandle<'resource'>;
@@ -629,6 +648,10 @@ export interface LifiZapOutputs {
   readonly amountOut: OutputHandle<'resource'>;
 }
 
+export interface LifiZapAsyncOutputs {
+  readonly amountOut: OutputHandle<'resource'>;
+}
+
 export interface ParaswapBuyOutputs {
   readonly amountOut: OutputHandle<'resource'>;
   readonly unspentIn: OutputHandle<'resource'>;
@@ -638,6 +661,11 @@ export interface CorePeekOutputs {
   readonly result: OutputHandle<'uint256'>;
 }
 
+export interface FlySwapOutputs {
+  readonly amountOut: OutputHandle<'resource'>;
+  readonly unspentIn: OutputHandle<'resource'>;
+}
+
 export type GeneratedOps = {
   readonly core: {
     /** Split a resource into two outputs by basis-point ratio — original id: "core.split" */
@@ -741,6 +769,11 @@ export type GeneratedOps = {
     readonly swap: (nodeId: string, args: LifiSwapArgs) => LifiSwapOutputs;
     /** Route tokens into a DeFi protocol position via the edge catalog — original id: "lifi.zap" */
     readonly zap: (nodeId: string, args: LifiZapArgs) => LifiZapOutputs;
+    /** Route tokens into a DeFi protocol position whose output becomes available after the initiating transaction settles — original id: "lifi.zapAsync" */
+    readonly zapAsync: (
+      nodeId: string,
+      args: LifiZapAsyncArgs,
+    ) => LifiZapAsyncOutputs;
   };
   readonly invariant: {
     /** Assert that an account holds at least a minimum token balance — original id: "invariant.balanceAtLeast" */
@@ -840,6 +873,10 @@ export type GeneratedOps = {
     /** Exact-output (BUY) swap via the Paraswap/Velora Market API: produce exactly `exactAmountOut` of the destination token, pulling only the source needed and exposing the genuinely-unspent source as `unspentIn`. — original id: "paraswap.buy" */
     readonly buy: (nodeId: string, args: ParaswapBuyArgs) => ParaswapBuyOutputs;
   };
+  readonly fly: {
+    /** Swap via Fly's DexAggregator, sized at runtime: the router calldata leaves `amountIn` unset, so an upstream op's output can feed the swap without being known at plan time. Either leg may be the chain-native coin. — original id: "fly.swap" */
+    readonly swap: (nodeId: string, args: FlySwapArgs) => FlySwapOutputs;
+  };
 };
 
 export const bindGeneratedOps = (
@@ -917,8 +954,8 @@ export const bindGeneratedOps = (
     call: <TSig extends string>(nodeId: string, args: CoreCallArgs<TSig>) => {
       const wire = buildCallWireFormat({
         resource: args.resource,
-        bind: args.bind as Record<string, AnyBindable>,
-        config: args.config as Record<string, unknown>,
+        bind: args.bind,
+        config: args.config,
         guards: args.guards,
       });
       return builder.call(nodeId, wire.op, wire, {
@@ -933,8 +970,8 @@ export const bindGeneratedOps = (
         nodeId,
         'core.staticCall',
         buildStaticCallWireFormat({
-          bind: args.bind as Record<string, AnyBindable>,
-          config: args.config as Record<string, unknown>,
+          bind: args.bind,
+          config: args.config,
           guards: args.guards,
         }),
         { result: 'uint256' } as const,
@@ -960,6 +997,10 @@ export const bindGeneratedOps = (
       builder.call(nodeId, 'lifi.zap', args, {
         amountOut: 'resource',
       } as const),
+    zapAsync: (nodeId: string, args: LifiZapAsyncArgs) =>
+      builder.call(nodeId, 'lifi.zapAsync', args, {
+        amountOut: 'resource',
+      } as const),
   },
   invariant: {
     balanceAtLeast: (nodeId: string, args: InvariantBalanceAtLeastArgs) =>
@@ -1078,4 +1119,11 @@ export const bindGeneratedOps = (
         unspentIn: 'resource',
       } as const),
   },
+  fly: {
+    swap: (nodeId: string, args: FlySwapArgs) =>
+      builder.call(nodeId, 'fly.swap', args, {
+        amountOut: 'resource',
+        unspentIn: 'resource',
+      } as const),
+  },
 });

package/src/index.ts

@@ -19,9 +19,11 @@ export type {
   OutputKind,
   TypedGuard,
   TypedRef,
+  TypedLiteral,
 } from './types.js';
 
 export type {
+  ChainSummary,
   GetZapPacksOptions,
   ZapPackEdge,
   ZapPackOverview,
@@ -36,11 +38,15 @@ export type {
   ApprovalEntry,
   Call,
   ComposeCompilePartialData,
+  ComposeAction,
+  ComposeFill,
+  ComposeFee,
+  ComposeUserProgramSimulation,
   ComposeCompileRequest,
   ComposeCompileResult,
   ComposeCompileSuccessData,
-  ComposeContinuation,
   ComposeErrorKind,
+  ComposeRouteRequest,
   ComposeTransactionRequest,
   FailedPreparedOp,
   Flow,
@@ -50,8 +56,13 @@ export type {
   Precondition,
   PreconditionConfigOf,
   PriceImpact,
+  ProducedResource,
   Ref,
   Resource,
+  RouteAmount,
+  RouteAmountAll,
+  RouteAmountExact,
+  SimulatedAmounts,
   SimulationPolicy,
   SimulationRevert,
   SolType,
@@ -83,6 +94,8 @@ export { isComposeError, isComposePreparationError } from './errors.js';
 
 export type {
   Bindable,
+  RefBindable,
+  AnyRefBindable,
   InputHandle,
   ResourceInputHandle,
   OutputHandle,
@@ -108,6 +121,7 @@ import * as materialisersMod from './generated/materialisers.generated.js';
 import * as preconditionsMod from './generated/preconditions.generated.js';
 import * as rawMod from './raw.js';
 import * as resourcesMod from './resources.js';
+import * as routeAmountMod from './routeAmount.js';
 
 /**
  * Guard factories for protecting operation outputs (e.g. slippage tolerance).
@@ -168,6 +182,24 @@ export const preconditions: typeof preconditionsMod = preconditionsMod;
  * ```
  */
 export const resources: typeof resourcesMod = resourcesMod;
+/**
+ * Amount constructors for {@link ComposeSdk.route}. Use
+ * {@link routeAmount.exact} to spend a fixed amount of the `fromToken`, and
+ * {@link routeAmount.all} to spend the signer's whole balance.
+ *
+ * @example
+ * ```ts
+ * // USDC into the Aave v3 aEthUSDC position — one routing-catalog edge.
+ * const result = await sdk.route({
+ *   chainId: 1,
+ *   fromToken: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+ *   toToken: '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c',
+ *   amount: routeAmount.exact(1_000_000n),
+ *   signer: '0xYourAddress...',
+ * });
+ * ```
+ */
+export const routeAmount: typeof routeAmountMod = routeAmountMod;
 export * from './generated/config.generated.js';
 
 /**

package/src/raw.ts

@@ -6,5 +6,5 @@
  * For most use cases, prefer the generated operation methods on {@link FlowBuilder}
  * (e.g. `builder.lifi.swap(...)`) and the typed guard/materialiser helpers.
  */
-export { rawGuard as guard, ref } from './authoring/raw.js';
+export { rawGuard as guard, literal, ref } from './authoring/raw.js';
 export { materialiser } from './run/inputs.js';

package/src/routeAmount.ts

@@ -0,0 +1,61 @@
+import type { RouteAmountAll, RouteAmountExact } from '@lifi/compose-spec';
+
+// Constructors for the `amount` member of a `ComposeRouteRequest`. The wire
+// union is discriminated by `type` and — deliberately, because the two variants
+// mean different things — names its payload field differently in each variant:
+// `amount` is the sum actually moved, `simAmount` is only a quoting stand-in for
+// a balance resolved on-chain. These helpers keep call sites from having to
+// remember which name goes with which discriminant.
+
+/**
+ * Spend an exact amount of the route's `fromToken`.
+ *
+ * @param amount - Amount in the token's smallest unit. `bigint` is serialised
+ *   to a decimal string when the request is sent.
+ * @returns The `EXACT` member of the route amount union.
+ *
+ * @example
+ * ```ts
+ * const result = await sdk.route({
+ *   chainId: 1,
+ *   fromToken: NATIVE_ETH,
+ *   toToken: WETH,
+ *   amount: routeAmount.exact(10n ** 17n), // 0.1 ETH, wrapped
+ *   signer: OWNER,
+ * });
+ * ```
+ */
+export const exact = (amount: bigint | string): RouteAmountExact => ({
+  type: 'EXACT',
+  amount,
+});
+
+/**
+ * Spend the signer's entire `fromToken` balance, resolved on-chain at execution
+ * time.
+ *
+ * Not supported when `fromToken` is the chain's native sentinel — the server
+ * rejects it. A gas coin is sent via `msg.value`, so there is no on-chain
+ * balance to sweep; use {@link exact} for native inputs.
+ *
+ * @param simAmount - A realistic estimate of that balance, in the token's
+ *   smallest unit. The server quotes and simulates against this value, so it
+ *   shapes the returned quote and preconditions — but the amount actually moved
+ *   is whatever the balance turns out to be.
+ * @returns The `ALL` member of the route amount union.
+ *
+ * @example
+ * ```ts
+ * const result = await sdk.route({
+ *   chainId: 1,
+ *   fromToken: USDC,
+ *   toToken: A_ETH_USDC,
+ *   amount: routeAmount.all(1_000_000n), // estimate: ~1 USDC on hand
+ *   signer: OWNER,
+ * });
+ * ```
+ */
+export const all = (simAmount: bigint | string): RouteAmountAll => ({
+  type: 'ALL',
+  simAmount,
+});

package/src/run/inputs.ts

@@ -54,6 +54,13 @@ export interface ComposeRunInput<T extends InputSchema = InputSchema> {
    * result with the transaction and revert diagnostics.
    */
   readonly simulationPolicy?: SimulationPolicy;
+  /**
+   * When `true`, the server also simulates the final user-facing transaction
+   * after the structured simulation succeeds; reverts honour
+   * `simulationPolicy`. On success the result is echoed back on the response as
+   * `userProgramSimulation`. Defaults to `false`.
+   */
+  readonly simulateUserProgram?: boolean;
   /**
    * When `true`, the server checks on-chain ERC-20 allowances and omits
    * approvals that are already sufficient. Defaults to `false`.
@@ -89,6 +96,21 @@ export const materialiser = (
   ...config,
 });
 
+/**
+ * Drops the keys whose value is `undefined`, so optional fields are omitted
+ * from the wire payload rather than serialized as `null`.
+ *
+ * A local copy of `pickDefined` from `@lifi/utils`: this package is published
+ * to npm and `@lifi/utils` is a private workspace package, so it cannot be a
+ * runtime dependency here.
+ */
+const pickDefined = <S extends Record<string, unknown>>(
+  obj: S,
+): Partial<{ [K in keyof S]: Exclude<S[K], undefined> }> =>
+  Object.fromEntries(
+    Object.entries(obj).filter(([, value]) => value !== undefined),
+  ) as Partial<{ [K in keyof S]: Exclude<S[K], undefined> }>;
+
 /**
  * Assembles a {@link ComposeRun} object from individual parameters.
  * Used internally by the SDK; prefer {@link ComposeRunInput} for external use.
@@ -105,24 +127,21 @@ export const buildRun = (run: {
   maxPriceImpactBps?: number;
   sweepTo?: SweepTo;
   simulationPolicy?: SimulationPolicy;
+  simulateUserProgram?: boolean;
   checkOnChainAllowances?: boolean;
 }): ComposeRun => ({
   inputs: run.inputs,
-  ...(run.preconditions?.length && { preconditions: run.preconditions }),
   signer: run.signer,
-  ...(run.assumptions && { assumptions: run.assumptions }),
-  ...(run.referrer !== undefined && { referrer: run.referrer }),
-  ...(run.integratorFeeBps !== undefined && {
+  ...pickDefined({
+    // An empty precondition list is the same as none, so drop it too.
+    preconditions: run.preconditions?.length ? run.preconditions : undefined,
+    assumptions: run.assumptions,
+    referrer: run.referrer,
     integratorFeeBps: run.integratorFeeBps,
-  }),
-  ...(run.maxPriceImpactBps !== undefined && {
     maxPriceImpactBps: run.maxPriceImpactBps,
-  }),
-  ...(run.sweepTo !== undefined && { sweepTo: run.sweepTo }),
-  ...(run.simulationPolicy !== undefined && {
+    sweepTo: run.sweepTo,
     simulationPolicy: run.simulationPolicy,
-  }),
-  ...(run.checkOnChainAllowances !== undefined && {
+    simulateUserProgram: run.simulateUserProgram,
     checkOnChainAllowances: run.checkOnChainAllowances,
   }),
 });

package/src/run/simulate.ts

@@ -12,8 +12,11 @@ import type {
 export interface BuildSimulateRequestInput {
   /**
    * A result from `builder.compile(...)` / `client.compile(...)`. Both
-   * `success` and `partial` results carry a `transactionRequest`, so either is
-   * valid input — the helper does not discriminate on `status`.
+   * `success` and `partial` results are valid input — the helper does not
+   * discriminate on `status`. A success result for an empty compiled program
+   * (a settle-only `funding: 'external'` flow) carries no
+   * `transactionRequest`; there is nothing to simulate and this helper
+   * throws — submit the result's `actions` entries directly instead.
    */
   readonly result: ComposeCompileResult;
   /** EVM chain id. A compile result does not carry the target chain. */
@@ -65,6 +68,15 @@ export const buildSimulateRequest = (
 ): SimulateRequest => {
   const { result, chainId, signer, trackedBalances, requirements, block } =
     input;
+  // A settle-only flow authored with `funding: 'external'` compiles to an
+  // empty program: the success response carries no `transactionRequest`, so
+  // there is nothing to simulate — the required submissions are the
+  // `actions` entries, submitted directly.
+  if (result.transactionRequest === undefined) {
+    throw new Error(
+      'buildSimulateRequest: the compile result has no transactionRequest (empty compiled program — a settle-only external-funding flow); submit the `actions` entries instead of simulating',
+    );
+  }
   return {
     chainId,
     from: signer,

package/src/sdk.ts

@@ -1,6 +1,7 @@
 import type {
   ComposeCompileRequest,
   ComposeCompileResult,
+  ComposeRouteRequest,
   InputSpec,
   SimulateRequest,
   SimulateResult,
@@ -13,6 +14,7 @@ import {
   type TypedFlow,
 } from './authoring/FlowBuilderCore.js';
 import { type ComposeClient, createComposeClient } from './client.js';
+import type { ChainSummary } from './discovery.js';
 import {
   bindGeneratedOps,
   type GeneratedOps,
@@ -108,6 +110,33 @@ export interface ComposeSdk {
     chainId: number,
     options: FlowOptions<T>,
   ) => FlowBuilder<T>;
+  /**
+   * Fetches the chains this Compose deployment supports, ascending by
+   * `chainId`. Thin pass-through to {@link ComposeClient.getChains}; see it
+   * for what "supported" means and for the caching caveat.
+   *
+   * Each entry pairs the `chainId` with a display `name`, so one call both
+   * gates a chain selector and labels it. Key on `chainId`; `name` is a
+   * deployment-maintained label that can change.
+   *
+   * Use it to fail fast before building a flow for a chain the server would
+   * reject.
+   *
+   * @returns The supported chains, ascending by `chainId`.
+   * @throws {@link ComposeError} on network or server errors.
+   *
+   * @example
+   * ```ts
+   * const chains = await sdk.getSupportedChains();
+   * if (!chains.some((c) => c.chainId === 8453)) {
+   *   throw new Error('Base is not supported');
+   * }
+   * for (const { chainId, name } of chains) {
+   *   console.log(`${name} (${chainId})`);
+   * }
+   * ```
+   */
+  readonly getSupportedChains: () => Promise<readonly ChainSummary[]>;
   /**
    * Builds a raw compile request without sending it. Useful for inspecting the
    * request payload or submitting it through a custom transport.
@@ -119,6 +148,21 @@ export interface ComposeSdk {
     flow: TypedFlow<T>,
     run: ComposeRunInput<T>,
   ) => ComposeCompileRequest;
+  /**
+   * Compiles a token pair on one chain — as of today a single zap step over
+   * one routing-catalog edge. Thin pass-through to
+   * {@link ComposeClient.route}; see it for the current single-step limit,
+   * when to prefer `flow(...).compile(...)`, the `success` / `partial`
+   * discrimination, and error behaviour. Build the `amount` with
+   * `routeAmount.exact(...)` / `routeAmount.all(...)`.
+   *
+   * @param request - The from/to token pair, amount, signer, and route options.
+   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.
+   * @throws {@link ComposeError} on network, validation, or server errors.
+   */
+  readonly route: (
+    request: ComposeRouteRequest,
+  ) => Promise<ComposeCompileResult>;
   /**
    * Simulates a raw, pre-encoded transaction. Thin pass-through to
    * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`
@@ -162,6 +206,7 @@ export const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {
       maxPriceImpactBps: run.maxPriceImpactBps,
       sweepTo: run.sweepTo,
       simulationPolicy: run.simulationPolicy,
+      simulateUserProgram: run.simulateUserProgram,
       checkOnChainAllowances: run.checkOnChainAllowances,
     }),
   });
@@ -187,7 +232,9 @@ export const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {
   return {
     client: composeClient,
     flow,
+    getSupportedChains: composeClient.getChains,
     request,
+    route: composeClient.route,
     simulate: composeClient.simulate,
   };
 };

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { Ref } from '@lifi/compose-spec';
+import type { LiteralBinding, Ref } from '@lifi/compose-spec';
 import {
   InputSpec,
   MaterialiserInput,
@@ -58,6 +58,25 @@ export interface TypedRef<T extends OutputKind = OutputKind> extends Ref {
   readonly __outputKind?: T;
 }
 
+/**
+ * A literal bind value carrying a phantom type parameter.
+ *
+ * The wire format accepts a constant in a bind slot as
+ * `{ kind: <solType>, value: <string> }`, alongside `$ref` pointers. Use it
+ * for a value that must be baked into the flow document rather than supplied
+ * at run time — the destination of a flow the backend stores and re-runs
+ * later (a `continuation.settle` node's `continuationFlow`) has no run to
+ * take an input from.
+ *
+ * @typeParam T - The Solidity type of the literal (e.g. `'address'`).
+ */
+export interface TypedLiteral<
+  T extends SolType = SolType,
+> extends LiteralBinding {
+  readonly kind: T;
+  readonly __outputKind?: T;
+}
+
 /**
  * An input declaration in a flow schema.
  * `Resource` values become resource inputs (token amounts);