@lifi/composer-sdk 0.4.0 → 0.4.1

package/src/examples/lifiZapAsync.ts

@@ -0,0 +1,88 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../index.js';
+import type { Address } from '../types.js';
+
+import { API_KEY, BASE_URL } from './config.js';
+
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+// Aave aEthUSDC receipt token on Ethereum mainnet
+const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
+
+export interface LifiZapAsyncInput {
+  readonly owner: Address;
+  readonly recipient: Address;
+}
+
+/**
+ * Zap USDC into a DeFi position whose output settles asynchronously via LI.FI.
+ *
+ * Demonstrates:
+ * - `lifi.zapAsync`, the future-availability sibling of `lifi.zap`
+ * - Binding the required `recipient` input (the async op has no optional
+ *   recipient — the decl is non-optional, so `bind.recipient` is mandatory)
+ * - Omitting `sweepTo`: `availability: 'future'` governs custody, so the
+ *   output is delivered externally and never enters the execution VM — a
+ *   sweep would find nothing to move (custody, not amount reporting)
+ * - Amount reporting is unaffected by availability: when the async lowering
+ *   binds a terminal handle the output still reports `simulated.amountOut`,
+ *   the protocol's in-transaction expected value (an estimate; the delivered
+ *   amount arrives after settlement). `simulated.amountOutMin` appears only
+ *   when a minimum source exists — for a future output that means a floor the
+ *   edge lowering itself reported, never a user guard
+ * - No output guards: the reported value is the initiating-transaction
+ *   estimate, not the asynchronously delivered amount a guard could enforce,
+ *   so `amountOut` is excluded from the generated `TypedGuard` union
+ *   (`guards` typechecks as `TypedGuard<never>[]`) and the compiler rejects
+ *   any guard on it
+ */
+export const buildLifiZapAsyncExample = ({
+  owner,
+  recipient,
+}: LifiZapAsyncInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  // Declare the flow with a single USDC input and the recipient address input.
+  const builder = sdk.flow(1, {
+    name: 'zap-async-usdc-to-aave',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+      recipient: 'address',
+    },
+  });
+
+  // Zap USDC into an async Aave position via LI.FI.
+  // The future output is delivered to `recipient` once the initiating
+  // transaction settles; the recipient binding is required by the op.
+  builder.lifi.zapAsync('zap', {
+    bind: {
+      amountIn: builder.inputs.amountIn,
+      recipient: builder.inputs.recipient,
+    },
+    config: {
+      resourceOut: resources.erc20(A_ETH_USDC, 1),
+    },
+  });
+
+  const flow = builder.build();
+
+  // Build the compile request.
+  // directDeposit transfers a fixed amount of USDC into the VM; the recipient
+  // handle passes the delivery address as a plain string.
+  // No `sweepTo`: the async output is delivered externally to the recipient,
+  // never landing in the VM for a sweep to reach.
+  // NOTE: no production edge sets `availability: 'future'` yet, so this request
+  // resolves to a typed no_route today; it documents the intended shape.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: '1000000000' }),
+      recipient,
+    },
+  });
+
+  return { flow, request };
+};

package/src/examples/routeTokenPair.ts

@@ -0,0 +1,58 @@
+import type { ComposeRouteRequest } from '@lifi/compose-spec';
+
+import { routeAmount } from '../index.js';
+
+import { OWNER } from './config.js';
+
+const NATIVE_ETH = '0x0000000000000000000000000000000000000000';
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+
+/**
+ * Wrap 0.1 native ETH into WETH on Ethereum mainnet through
+ * `POST /compose/route`.
+ *
+ * Demonstrates:
+ * - The convenience path: a from/to token pair instead of an authored flow.
+ *   The pair resolves to the catalog's `wrap` edge, and the server authors the
+ *   zap step for it
+ * - `routeAmount.exact` for a fixed input amount (`bigint`, serialised on send)
+ * - The native sentinel address as `fromToken`
+ *
+ * Pure: returns a plain {@link ComposeRouteRequest}, performs no network I/O.
+ * Pass it to `sdk.route(...)` / `sdk.client.route(...)` to compile it.
+ */
+export const buildRouteExactExample = (): ComposeRouteRequest => ({
+  chainId: 1,
+  fromToken: NATIVE_ETH,
+  toToken: WETH,
+  amount: routeAmount.exact(100_000_000_000_000_000n), // 0.1 ETH
+  signer: OWNER,
+  slippageBps: 100,
+});
+
+/**
+ * Unwrap the signer's entire WETH balance back into native ETH on Ethereum
+ * mainnet — the catalog's `unwrap` edge.
+ *
+ * Demonstrates:
+ * - `routeAmount.all` for a balance resolved on-chain at execution time, where
+ *   the passed value is only the quoting stand-in
+ * - `sweepTo` naming the address that receives the output
+ * - `checkOnChainAllowances` so already-sufficient approvals are omitted from
+ *   the response
+ *
+ * Pure: returns a plain {@link ComposeRouteRequest}, performs no network I/O.
+ */
+export const buildRouteAllExample = (): ComposeRouteRequest => ({
+  chainId: 1,
+  fromToken: WETH,
+  toToken: NATIVE_ETH,
+  // Estimate of the balance on hand — the quote and the derived preconditions
+  // are computed against this, but the amount actually moved is the real
+  // balance at execution time.
+  amount: routeAmount.all(10n ** 18n), // ~1 WETH
+  signer: OWNER,
+  sweepTo: OWNER,
+  slippageBps: 50,
+  checkOnChainAllowances: true,
+});

package/src/examples/run.ts

@@ -20,6 +20,7 @@
  *   split-zap         — split USDC 60/40 and zap into Aave + Morpho vaults
  *   split-arithmetic  — split USDC 70/30 with arithmetic assertions
  *   zap               — zap USDC into Aave lending position
+ *   zap-async         — zap USDC into an async Aave position (future output)
  *   swap-zap          — swap WETH to USDC then zap into Aave
  *   swap-check        — swap WETH to USDC with balance check
  *   swap-recipient    — swap WETH + DAI to USDC and send to recipient
@@ -32,8 +33,13 @@
  *   transfer          — transfer full token balance to a recipient
  *   partial-transfer  — transfer a specific amount, keeping the remainder
  *   untyped-ref       — mix untypedOp with typed handles via raw.ref
+ *   route-exact       — wrap 0.1 native ETH into WETH via /compose/route
+ *   route-all         — unwrap the whole WETH balance to ETH via /compose/route
  */
-import type { ComposeCompileRequest } from '@lifi/compose-spec';
+import type {
+  ComposeCompileRequest,
+  ComposeRouteRequest,
+} from '@lifi/compose-spec';
 
 import { createComposeSdk } from '../sdk.js';
 
@@ -49,8 +55,13 @@ import { buildDepositFromProxy } from './depositFromProxy.js';
 import { buildDustSweepExample } from './dustSweep.js';
 import { buildLifiSwapExample } from './lifiSwap.js';
 import { buildLifiZapExample } from './lifiZap.js';
+import { buildLifiZapAsyncExample } from './lifiZapAsync.js';
 import { buildRawCallWithArithmetic } from './rawCallWithArithmetic.js';
 import { buildReadContractState } from './readContractState.js';
+import {
+  buildRouteAllExample,
+  buildRouteExactExample,
+} from './routeTokenPair.js';
 import { buildSplitAndZapExample } from './splitAndZap.js';
 import { buildSplitWithArithmetic } from './splitWithArithmetic.js';
 import { buildSwapAndZapExample } from './swapAndZap.js';
@@ -106,6 +117,8 @@ const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
   'split-arithmetic': () =>
     buildSplitWithArithmetic({ owner: OWNER, amount: '1000000000' }).request,
   zap: () => buildLifiZapExample().request,
+  'zap-async': () =>
+    buildLifiZapAsyncExample({ owner: OWNER, recipient: RECIPIENT }).request,
   'swap-zap': () => buildSwapAndZapExample().request,
   'swap-check': () =>
     buildSwapWithBalanceCheck({ owner: OWNER, amount: '1000000000000000000' })
@@ -146,6 +159,13 @@ const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
   'untyped-ref': () => buildUntypedOpWithTypedRef({ owner: OWNER }).request,
 };
 
+// `/compose/route` examples build a `ComposeRouteRequest` and go to
+// `sdk.route`, not `sdk.client.compile`, so they live in their own registry.
+const ROUTE_EXAMPLES: Record<string, () => ComposeRouteRequest> = {
+  'route-exact': buildRouteExactExample,
+  'route-all': buildRouteAllExample,
+};
+
 const run = async () => {
   const args = process.argv.slice(2);
   const useStaged = args.includes('--staged');
@@ -166,10 +186,13 @@ const run = async () => {
     examples = { ...EXAMPLES, ...stagedModule.STAGED_EXAMPLES };
   }
 
+  const routeBuilder = name ? ROUTE_EXAMPLES[name] : undefined;
   const builder = name ? examples[name] : undefined;
 
-  if (!builder) {
-    const valid = Object.keys(examples).join(', ');
+  if (!builder && !routeBuilder) {
+    const valid = [...Object.keys(examples), ...Object.keys(ROUTE_EXAMPLES)]
+      .sort()
+      .join(', ');
     console.error(
       `Error: ${
         name ? `unknown example "${name}"` : 'no example specified'
@@ -181,7 +204,7 @@ const run = async () => {
   }
   console.log(`Running example: ${name}`);
 
-  const request = builder();
+  const request = routeBuilder ? routeBuilder() : builder!();
   const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   console.log('--- Request ---');
@@ -195,7 +218,9 @@ const run = async () => {
   );
 
   console.log(`\n--- Compiling against ${BASE_URL} ---`);
-  const result = await sdk.client.compile(request);
+  const result = routeBuilder
+    ? await sdk.route(request as ComposeRouteRequest)
+    : await sdk.client.compile(request as ComposeCompileRequest);
 
   console.log('\n--- Result ---');
   console.log(JSON.stringify(result, null, 2));

package/src/generated/config.generated.ts

@@ -203,9 +203,14 @@ export interface CoreCallConfig {
           )[]
       )[]
   )[];
-  approvals?: {
-    spender: Address;
-  }[];
+  approvals?: (
+    | {
+        spender: Address;
+      }
+    | {
+        from: 'sender';
+      }
+  )[];
 }
 
 export interface CoreStaticCallConfig {
@@ -684,6 +689,19 @@ export interface LifiZapConfig {
       };
 }
 
+export interface LifiZapAsyncConfig {
+  resourceOut:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
+}
+
 export interface ParaswapBuyConfig {
   resourceOut:
     | {

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,
@@ -47,6 +44,7 @@ import type {
   InvariantNumericConfig,
   InvariantNumericInRangeConfig,
   LifiSwapConfig,
+  LifiZapAsyncConfig,
   LifiZapConfig,
   MorphoBlueSupplyCollateralConfig,
   MorphoBlueWithdrawCollateralConfig,
@@ -520,11 +518,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: {
@@ -629,6 +638,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'>;
@@ -741,6 +754,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" */
@@ -917,8 +935,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 +951,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 +978,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) =>

package/src/index.ts

@@ -41,6 +41,7 @@ export type {
   ComposeCompileSuccessData,
   ComposeContinuation,
   ComposeErrorKind,
+  ComposeRouteRequest,
   ComposeTransactionRequest,
   FailedPreparedOp,
   Flow,
@@ -52,6 +53,9 @@ export type {
   PriceImpact,
   Ref,
   Resource,
+  RouteAmount,
+  RouteAmountAll,
+  RouteAmountExact,
   SimulationPolicy,
   SimulationRevert,
   SolType,
@@ -108,6 +112,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 +173,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/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/sdk.ts

@@ -1,6 +1,7 @@
 import type {
   ComposeCompileRequest,
   ComposeCompileResult,
+  ComposeRouteRequest,
   InputSpec,
   SimulateRequest,
   SimulateResult,
@@ -119,6 +120,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`
@@ -188,6 +204,7 @@ export const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {
     client: composeClient,
     flow,
     request,
+    route: composeClient.route,
     simulate: composeClient.simulate,
   };
 };