@lifi/composer-sdk 0.4.0-staging.1 → 0.4.1

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,
@@ -20,11 +17,9 @@ import type { TypedGuard } from '../types.js';
 import type {
   AaveBorrowConfig,
   AaveClaimRewardsConfig,
-  AaveGetHealthFactorConfig,
   AaveRepayConfig,
   AaveRepayWithATokensConfig,
   AaveSetEModeConfig,
-  ContinuationAssertReadyConfig,
   CoreApproveConfig,
   CoreAsResourceConfig,
   CoreBalanceOfConfig,
@@ -48,16 +43,11 @@ import type {
   InvariantNeqConfig,
   InvariantNumericConfig,
   InvariantNumericInRangeConfig,
-  LifiFlashloanRepayConfig,
   LifiSwapConfig,
+  LifiZapAsyncConfig,
   LifiZapConfig,
-  MorphoBlueBorrowConfig,
-  MorphoBlueGetPositionConfig,
-  MorphoBlueRepayConfig,
   MorphoBlueSupplyCollateralConfig,
-  MorphoBlueSupplyConfig,
   MorphoBlueWithdrawCollateralConfig,
-  MorphoBlueWithdrawConfig,
   ParaswapBuyConfig,
 } from './config.generated.js';
 
@@ -508,13 +498,6 @@ export interface AaveSetEModeArgs {
   readonly guards?: readonly TypedGuard<never>[];
 }
 
-/** Read the current Aave v3 health factor (WAD-scaled, 1e18; type(uint256).max for users with no debt) by static-calling IPool.getUserAccountData and decomposing the returned tuple. Exposes the healthFactor element as a uint256 handle suitable for use with core.numericInvariant. */
-export interface AaveGetHealthFactorArgs {
-  readonly bind: Record<string, never>;
-  readonly config: AaveGetHealthFactorConfig;
-  readonly guards?: readonly TypedGuard<'healthFactor'>[];
-}
-
 /** Deposit the collateral asset of a Morpho Blue market on behalf of the execution proxy. mode: 'exact' pulls the input handle's amount. mode: 'all' reads the proxy's current ERC20 balance of the market's collateral token and pulls that amount, ignoring the input handle's literal value — note this pulls the proxy's total balance (including unrelated upstream residuals), not just the input port's delivery. Credits Position.collateral on the Morpho singleton; emits no return value and exposes no resource output (the collateral is non-transferable accounting state). */
 export interface MorphoBlueSupplyCollateralArgs {
   readonly bind: {
@@ -531,86 +514,26 @@ export interface MorphoBlueWithdrawCollateralArgs {
   readonly guards?: readonly TypedGuard<'collateralWithdrawn'>[];
 }
 
-/** Borrow the loan asset from a Morpho Blue market against existing collateral. Exposes the borrowed amount as a Resource and the (assetsBorrowed, sharesBorrowed) tuple as handles. */
-export interface MorphoBlueBorrowArgs {
-  readonly bind: Record<string, never>;
-  readonly config: MorphoBlueBorrowConfig;
-  readonly guards?: readonly TypedGuard<'assetsBorrowed' | 'sharesBorrowed'>[];
-}
-
-/** Repay a Morpho Blue debt position with the supplied asset. mode: 'exact' repays the input handle amount; mode: 'max' reads Position.borrowShares via a precursor static call and repays in shares mode to retire the debt to the wei. Returns any unspent residual as a Resource. */
-export interface MorphoBlueRepayArgs {
-  readonly bind: {
-    readonly assetIn: Bindable<'resource'>;
-    readonly onBehalfOf: Bindable<'address'>;
-  };
-  readonly config: MorphoBlueRepayConfig;
-  readonly guards?: readonly TypedGuard<
-    'actualRepaid' | 'sharesRepaid' | 'residual'
-  >[];
-}
-
-/** Supply the loan asset of a Morpho Blue market and receive supplyShares accounting credit. Returns the (assetsSupplied, sharesSupplied) tuple as handles and any unspent residual as a Resource. */
-export interface MorphoBlueSupplyArgs {
-  readonly bind: {
-    readonly assetIn: Bindable<'resource'>;
-  };
-  readonly config: MorphoBlueSupplyConfig;
-  readonly guards?: readonly TypedGuard<
-    'assetsSupplied' | 'sharesSupplied' | 'residual'
-  >[];
-}
-
-/** Withdraw the loan asset from a Morpho Blue supply position. mode: 'exact' withdraws the configured amount; mode: 'max' reads Position.supplyShares via a precursor static call and burns all shares to retire the supply to the wei. Exposes the withdrawn amount as a Resource. */
-export interface MorphoBlueWithdrawArgs {
-  readonly bind: Record<string, never>;
-  readonly config: MorphoBlueWithdrawConfig;
-  readonly guards?: readonly TypedGuard<
-    'assetsWithdrawn' | 'sharesWithdrawn'
-  >[];
-}
-
-/** Read a Morpho Blue Position struct via a static call on the singleton. Exposes (supplyShares, borrowShares, collateral) as handles whose kinds match the on-chain field types (uint256, uint128, uint128). */
-export interface MorphoBlueGetPositionArgs {
-  readonly bind: Record<string, never>;
-  readonly config: MorphoBlueGetPositionConfig;
-  readonly guards?: readonly TypedGuard<
-    'supplyShares' | 'borrowShares' | 'collateral'
-  >[];
-}
-
-/** Transfer principal + fee back to the LiFi flashloan adapter for one leg */
-export interface LifiFlashloanRepayArgs {
-  readonly bind: {
-    readonly funds: Bindable<'resource'>;
-    readonly feeBuffer?: Bindable<'resource'>;
-  };
-  readonly config: LifiFlashloanRepayConfig;
-  readonly guards?: readonly TypedGuard<never>[];
-}
-
-/** Assert a continuation readiness check on-chain; reverts the second leg if its proceeds have not landed */
-export interface ContinuationAssertReadyArgs {
-  readonly bind: Record<string, never>;
-  readonly config: ContinuationAssertReadyConfig;
-  readonly guards?: readonly TypedGuard<never>[];
-}
-
-/** Carries a committed continuation thunk as node metadata for the settlement echo; emits no IR1 */
-export interface ContinuationCommitmentArgs {
-  readonly bind: Record<string, never>;
-  readonly guards?: readonly TypedGuard<never>[];
-}
-
 /** Route tokens into a DeFi protocol position via the edge catalog */
 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: {
@@ -706,46 +629,16 @@ export interface AaveClaimRewardsOutputs {
   readonly claimedAmount: OutputHandle<'uint256'>;
 }
 
-export interface AaveGetHealthFactorOutputs {
-  readonly healthFactor: OutputHandle<'uint256'>;
-}
-
 export interface MorphoBlueWithdrawCollateralOutputs {
   readonly withdrawn: OutputHandle<'resource'>;
   readonly collateralWithdrawn: OutputHandle<'uint256'>;
 }
 
-export interface MorphoBlueBorrowOutputs {
-  readonly borrowed: OutputHandle<'resource'>;
-  readonly assetsBorrowed: OutputHandle<'uint256'>;
-  readonly sharesBorrowed: OutputHandle<'uint256'>;
-}
-
-export interface MorphoBlueRepayOutputs {
-  readonly actualRepaid: OutputHandle<'uint256'>;
-  readonly sharesRepaid: OutputHandle<'uint256'>;
-  readonly residual: OutputHandle<'resource'>;
-}
-
-export interface MorphoBlueSupplyOutputs {
-  readonly assetsSupplied: OutputHandle<'uint256'>;
-  readonly sharesSupplied: OutputHandle<'uint256'>;
-  readonly residual: OutputHandle<'resource'>;
-}
-
-export interface MorphoBlueWithdrawOutputs {
-  readonly withdrawn: OutputHandle<'resource'>;
-  readonly assetsWithdrawn: OutputHandle<'uint256'>;
-  readonly sharesWithdrawn: OutputHandle<'uint256'>;
-}
-
-export interface MorphoBlueGetPositionOutputs {
-  readonly supplyShares: OutputHandle<'uint256'>;
-  readonly borrowShares: OutputHandle<'uint128'>;
-  readonly collateral: OutputHandle<'uint128'>;
+export interface LifiZapOutputs {
+  readonly amountOut: OutputHandle<'resource'>;
 }
 
-export interface LifiZapOutputs {
+export interface LifiZapAsyncOutputs {
   readonly amountOut: OutputHandle<'resource'>;
 }
 
@@ -859,13 +752,13 @@ export type GeneratedOps = {
   readonly lifi: {
     /** Swap tokens via the LI.FI aggregator API — original id: "lifi.swap" */
     readonly swap: (nodeId: string, args: LifiSwapArgs) => LifiSwapOutputs;
-    /** Transfer principal + fee back to the LiFi flashloan adapter for one leg — original id: "lifi.flashloanRepay" */
-    readonly flashloanRepay: (
-      nodeId: string,
-      args: LifiFlashloanRepayArgs,
-    ) => void;
     /** 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" */
@@ -948,11 +841,6 @@ export type GeneratedOps = {
     ) => AaveClaimRewardsOutputs;
     /** Switch the executionAddress's Aave v3 eMode category. 0 disables eMode. The pool reverts if the switch would make the position unhealthy or if any open borrow is for an asset outside the target category. — original id: "aave.setEMode" */
     readonly setEMode: (nodeId: string, args: AaveSetEModeArgs) => void;
-    /** Read the current Aave v3 health factor (WAD-scaled, 1e18; type(uint256).max for users with no debt) by static-calling IPool.getUserAccountData and decomposing the returned tuple. Exposes the healthFactor element as a uint256 handle suitable for use with core.numericInvariant. — original id: "aave.getHealthFactor" */
-    readonly getHealthFactor: (
-      nodeId: string,
-      args: AaveGetHealthFactorArgs,
-    ) => AaveGetHealthFactorOutputs;
   };
   readonly morphoBlue: {
     /** Deposit the collateral asset of a Morpho Blue market on behalf of the execution proxy. mode: 'exact' pulls the input handle's amount. mode: 'all' reads the proxy's current ERC20 balance of the market's collateral token and pulls that amount, ignoring the input handle's literal value — note this pulls the proxy's total balance (including unrelated upstream residuals), not just the input port's delivery. Credits Position.collateral on the Morpho singleton; emits no return value and exposes no resource output (the collateral is non-transferable accounting state). — original id: "morphoBlue.supplyCollateral" */
@@ -965,43 +853,6 @@ export type GeneratedOps = {
       nodeId: string,
       args: MorphoBlueWithdrawCollateralArgs,
     ) => MorphoBlueWithdrawCollateralOutputs;
-    /** Borrow the loan asset from a Morpho Blue market against existing collateral. Exposes the borrowed amount as a Resource and the (assetsBorrowed, sharesBorrowed) tuple as handles. — original id: "morphoBlue.borrow" */
-    readonly borrow: (
-      nodeId: string,
-      args: MorphoBlueBorrowArgs,
-    ) => MorphoBlueBorrowOutputs;
-    /** Repay a Morpho Blue debt position with the supplied asset. mode: 'exact' repays the input handle amount; mode: 'max' reads Position.borrowShares via a precursor static call and repays in shares mode to retire the debt to the wei. Returns any unspent residual as a Resource. — original id: "morphoBlue.repay" */
-    readonly repay: (
-      nodeId: string,
-      args: MorphoBlueRepayArgs,
-    ) => MorphoBlueRepayOutputs;
-    /** Supply the loan asset of a Morpho Blue market and receive supplyShares accounting credit. Returns the (assetsSupplied, sharesSupplied) tuple as handles and any unspent residual as a Resource. — original id: "morphoBlue.supply" */
-    readonly supply: (
-      nodeId: string,
-      args: MorphoBlueSupplyArgs,
-    ) => MorphoBlueSupplyOutputs;
-    /** Withdraw the loan asset from a Morpho Blue supply position. mode: 'exact' withdraws the configured amount; mode: 'max' reads Position.supplyShares via a precursor static call and burns all shares to retire the supply to the wei. Exposes the withdrawn amount as a Resource. — original id: "morphoBlue.withdraw" */
-    readonly withdraw: (
-      nodeId: string,
-      args: MorphoBlueWithdrawArgs,
-    ) => MorphoBlueWithdrawOutputs;
-    /** Read a Morpho Blue Position struct via a static call on the singleton. Exposes (supplyShares, borrowShares, collateral) as handles whose kinds match the on-chain field types (uint256, uint128, uint128). — original id: "morphoBlue.getPosition" */
-    readonly getPosition: (
-      nodeId: string,
-      args: MorphoBlueGetPositionArgs,
-    ) => MorphoBlueGetPositionOutputs;
-  };
-  readonly continuation: {
-    /** Assert a continuation readiness check on-chain; reverts the second leg if its proceeds have not landed — original id: "continuation.assertReady" */
-    readonly assertReady: (
-      nodeId: string,
-      args: ContinuationAssertReadyArgs,
-    ) => void;
-    /** Carries a committed continuation thunk as node metadata for the settlement echo; emits no IR1 — original id: "continuation.commitment" */
-    readonly commitment: (
-      nodeId: string,
-      args: ContinuationCommitmentArgs,
-    ) => void;
   };
   readonly paraswap: {
     /** 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" */
@@ -1084,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, {
@@ -1100,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,
@@ -1123,12 +974,14 @@ export const bindGeneratedOps = (
         amountOut: 'resource',
         unspentIn: 'resource',
       } as const),
-    flashloanRepay: (nodeId: string, args: LifiFlashloanRepayArgs) =>
-      builder.call(nodeId, 'lifi.flashloanRepay', args, {}),
     zap: (nodeId: string, args: LifiZapArgs) =>
       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) =>
@@ -1227,10 +1080,6 @@ export const bindGeneratedOps = (
       } as const),
     setEMode: (nodeId: string, args: AaveSetEModeArgs) =>
       builder.call(nodeId, 'aave.setEMode', args, {}),
-    getHealthFactor: (nodeId: string, args: AaveGetHealthFactorArgs) =>
-      builder.call(nodeId, 'aave.getHealthFactor', args, {
-        healthFactor: 'uint256',
-      } as const),
   },
   morphoBlue: {
     supplyCollateral: (nodeId: string, args: MorphoBlueSupplyCollateralArgs) =>
@@ -1243,47 +1092,6 @@ export const bindGeneratedOps = (
         withdrawn: 'resource',
         collateralWithdrawn: 'uint256',
       } as const),
-    borrow: (nodeId: string, args: MorphoBlueBorrowArgs) =>
-      builder.call(nodeId, 'morphoBlue.borrow', args, {
-        borrowed: 'resource',
-        assetsBorrowed: 'uint256',
-        sharesBorrowed: 'uint256',
-      } as const),
-    repay: (nodeId: string, args: MorphoBlueRepayArgs) =>
-      builder.call(nodeId, 'morphoBlue.repay', args, {
-        actualRepaid: 'uint256',
-        sharesRepaid: 'uint256',
-        residual: 'resource',
-      } as const),
-    supply: (nodeId: string, args: MorphoBlueSupplyArgs) =>
-      builder.call(nodeId, 'morphoBlue.supply', args, {
-        assetsSupplied: 'uint256',
-        sharesSupplied: 'uint256',
-        residual: 'resource',
-      } as const),
-    withdraw: (nodeId: string, args: MorphoBlueWithdrawArgs) =>
-      builder.call(nodeId, 'morphoBlue.withdraw', args, {
-        withdrawn: 'resource',
-        assetsWithdrawn: 'uint256',
-        sharesWithdrawn: 'uint256',
-      } as const),
-    getPosition: (nodeId: string, args: MorphoBlueGetPositionArgs) =>
-      builder.call(nodeId, 'morphoBlue.getPosition', args, {
-        supplyShares: 'uint256',
-        borrowShares: 'uint128',
-        collateral: 'uint128',
-      } as const),
-  },
-  continuation: {
-    assertReady: (nodeId: string, args: ContinuationAssertReadyArgs) =>
-      builder.call(nodeId, 'continuation.assertReady', args, {}),
-    commitment: (nodeId: string, args: ContinuationCommitmentArgs) =>
-      builder.call(
-        nodeId,
-        'continuation.commitment',
-        { ...args, config: {} },
-        {},
-      ),
   },
   paraswap: {
     buy: (nodeId: string, args: ParaswapBuyArgs) =>

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,
   };
 };

package/src/examples/staged/aaveBorrow.ts

@@ -1,128 +0,0 @@
-import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
-
-import {
-  createComposeSdk,
-  guards,
-  materialisers,
-  resources,
-} from '../../index.js';
-import type { Address } from '../../types.js';
-import { API_KEY, BASE_URL } from '../config.js';
-
-// Aave v3 contracts on Ethereum mainnet.
-const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
-const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
-// Aave v3 aEthUSDC receipt token and variable-debt USDC token.
-const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
-const VDEBT_USDC = '0x72E95b8931767C79bA4EeE721354d6E99a61D004';
-
-// 1.05 WAD (1e18) — minimum acceptable Aave health factor after the borrow.
-// The on-chain VM reverts the run if the post-borrow HF drops below this.
-const MIN_HEALTH_FACTOR_WAD = '1050000000000000000';
-
-export interface AaveBorrowInput {
-  readonly owner: Address;
-  readonly recipient: Address;
-  /** USDC supplied as collateral so the proxy can borrow (6 dp). */
-  readonly collateralAmount: `${bigint}`;
-  /** USDC borrowed against the collateral and sent to the recipient (6 dp). */
-  readonly borrowAmount: `${bigint}`;
-}
-
-/**
- * Supply USDC to Aave v3, borrow USDC against it, and transfer the borrowed
- * funds to a recipient — with an on-chain health-factor guard that reverts
- * if the post-borrow position is too thin.
- *
- * The in-flow supply makes the example self-contained: the borrow is backed
- * by collateral created in the same transaction, so it simulates cleanly
- * for a fresh proxy. Keep `borrowAmount` comfortably below the collateral's
- * borrowing power or the health-factor guard reverts the run.
- *
- * Demonstrates:
- * - `lifi.zap` to supply USDC into Aave (USDC → aEthUSDC routing edge)
- * - `aave.borrow` with no resource input — the borrowed asset materialises
- *   as the `borrowed` resource output.
- * - Chaining the borrow output into a `core.transfer` to forward funds.
- * - `aave.getHealthFactor` + `core.numericInvariant` guard asserts that
- *   `healthFactor >= MIN_HEALTH_FACTOR_WAD` after the borrow; the run reverts
- *   on-chain if the threshold is violated.
- *
- * The supplied aEthUSDC stays on the proxy: it backs the open debt, and
- * Aave rejects aToken transfers that would break the position's health
- * factor, so it cannot be swept while the borrow is outstanding.
- */
-export const buildAaveBorrow = ({
-  owner,
-  recipient,
-  collateralAmount,
-  borrowAmount,
-}: AaveBorrowInput): {
-  flow: Flow;
-  request: ComposeCompileRequest;
-} => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
-
-  const builder = sdk.flow(1, {
-    name: 'aave-borrow-usdc',
-    inputs: {
-      collateralIn: resources.erc20(USDC, 1),
-      recipient: 'address',
-    },
-  });
-
-  // Supply USDC as collateral (USDC → aEthUSDC) so the proxy can borrow.
-  builder.lifi.zap('supply', {
-    bind: { amountIn: builder.inputs.collateralIn },
-    config: { resourceOut: resources.erc20(A_ETH_USDC, 1) },
-  });
-
-  const borrowOut = builder.aave.borrow('borrow', {
-    bind: {},
-    config: {
-      pool: AAVE_V3_POOL,
-      asset: USDC,
-      variableDebtToken: VDEBT_USDC,
-      amount: borrowAmount,
-    },
-  });
-
-  // Read the post-borrow Aave health factor and assert it stays above the
-  // minimum threshold. The numericInvariant guard lowers to an on-chain
-  // `AssertRawInvariant` IR1 instruction; the run reverts if HF < threshold.
-  builder.aave.getHealthFactor('hf', {
-    bind: {},
-    config: { pool: AAVE_V3_POOL },
-    guards: [
-      guards.coreNumericInvariant({
-        port: 'healthFactor',
-        op: 'gte',
-        threshold: MIN_HEALTH_FACTOR_WAD,
-      }),
-    ],
-  });
-
-  // Forward the freshly borrowed USDC to the recipient.
-  builder.core.transfer('send-borrowed', {
-    bind: {
-      amount: borrowOut.borrowed,
-      recipient: builder.inputs.recipient,
-    },
-    config: {},
-  });
-
-  const flow = builder.build();
-
-  // No sweepTo: the aEthUSDC collateral must stay on the proxy while the
-  // debt is open — Aave blocks aToken transfers that would leave the
-  // position undercollateralized.
-  const request = sdk.request(flow, {
-    signer: owner,
-    inputs: {
-      collateralIn: materialisers.directDeposit({ amount: collateralAmount }),
-      recipient,
-    },
-  });
-
-  return { flow, request };
-};