@lifi/composer-sdk 0.2.0-staging.5 → 0.2.0

package/src/generated/operations.generated.ts

@@ -20,7 +20,6 @@ import type { TypedGuard } from '../types.js';
 import type {
   AaveBorrowConfig,
   AaveClaimRewardsConfig,
-  AaveGetHealthFactorConfig,
   AaveRepayConfig,
   AaveRepayWithATokensConfig,
   AaveSetEModeConfig,
@@ -47,16 +46,10 @@ import type {
   InvariantNeqConfig,
   InvariantNumericConfig,
   InvariantNumericInRangeConfig,
-  LifiFlashloanRepayConfig,
   LifiSwapConfig,
   LifiZapConfig,
-  MorphoBlueBorrowConfig,
-  MorphoBlueGetPositionConfig,
-  MorphoBlueRepayConfig,
   MorphoBlueSupplyCollateralConfig,
-  MorphoBlueSupplyConfig,
   MorphoBlueWithdrawCollateralConfig,
-  MorphoBlueWithdrawConfig,
   ParaswapBuyConfig,
 } from './config.generated.js';
 
@@ -507,13 +500,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: {
@@ -530,64 +516,6 @@ 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>[];
-}
-
 /** Route tokens into a DeFi protocol position via the edge catalog */
 export interface LifiZapArgs {
   readonly bind: {
@@ -692,45 +620,11 @@ 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'>;
 }
@@ -845,11 +739,6 @@ 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;
   };
@@ -934,11 +823,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" */
@@ -951,31 +835,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 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" */
@@ -1097,8 +956,6 @@ 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',
@@ -1201,10 +1058,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) =>
@@ -1217,36 +1070,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),
   },
   paraswap: {
     buy: (nodeId: string, args: ParaswapBuyArgs) =>

package/src/index.ts

@@ -51,6 +51,22 @@ export type {
   SimulationRevert,
   SolType,
   SweepTo,
+  SimulateRequest,
+  SimulateResult,
+  SimulateOkResult,
+  SimulateRevertResult,
+  SimulateRevertDecodeResult,
+  SimulateSetupErrorResult,
+  SimulateBalanceEntry,
+  TrackedBalance,
+  SlotFinderRequirement,
+  Erc20BalanceRequirement,
+  NativeBalanceRequirement,
+  Erc20AllowanceRequirement,
+} from '@lifi/compose-spec';
+export {
+  SIMULATE_MAX_TRACKED_BALANCES,
+  SIMULATE_MAX_REQUIREMENTS,
 } from '@lifi/compose-spec';
 export { isComposeError } from './errors.js';
 
@@ -70,6 +86,9 @@ export type { TypedFlow, FlowOptions } from './authoring/FlowBuilderCore.js';
 export type { ComposeRunInput } from './run/inputs.js';
 export { materialiser } from './run/inputs.js';
 
+export { buildSimulateRequest } from './run/simulate.js';
+export type { BuildSimulateRequestInput } from './run/simulate.js';
+
 export { createComposeSdk } from './sdk.js';
 export type { ComposeSdk, ComposeSdkOptions, FlowBuilder } from './sdk.js';
 

package/src/responseSchemas.ts

@@ -0,0 +1,143 @@
+import type { SimulateResult, SimulationRevert } from '@lifi/compose-spec';
+import z from 'zod';
+
+/**
+ * Zod-backed parsers for Compose API response bodies.
+ *
+ * Server responses are untrusted input crossing into the SDK, so the shapes the
+ * client reads back are validated here rather than asserted with `as` casts. The
+ * schemas are module-private (the package builds with `--isolatedDeclarations`,
+ * which forbids exporting un-annotated complex values); the public surface is
+ * the typed `parse*` helpers, whose explicit return types double as the contract.
+ *
+ * The simulate union is the one response the SDK fully owns and parses itself
+ * (it is un-enveloped, unlike `/compose`), so it gets a complete schema kept in
+ * lockstep with the canonical `SimulateResult` in `@lifi/compose-spec` by the
+ * compile-time assertion below — the same anchoring `@lifi/api-schemas` uses for
+ * its server-side simulate schema, so the two cannot silently drift.
+ */
+
+const balanceEntrySchema = z.object({
+  token: z.string(),
+  owner: z.string(),
+  amount: z.string(),
+});
+
+const simulateOkSchema = z.object({
+  status: z.literal('ok'),
+  block: z.number(),
+  timestamp: z.number(),
+  balancesBefore: z.array(balanceEntrySchema),
+  balancesAfter: z.array(balanceEntrySchema),
+  deltas: z.array(balanceEntrySchema),
+  gasUsed: z.string(),
+});
+
+const simulateRevertDecodeResultSchema = z.object({
+  errorCandidates: z
+    .array(
+      z.object({
+        decodedErrorSignature: z.string(),
+        decodedParams: z.array(z.string()),
+      }),
+    )
+    .optional(),
+  error: z.string().optional(),
+});
+
+const simulateRevertSchema = z.object({
+  status: z.literal('revert'),
+  block: z.number(),
+  timestamp: z.number(),
+  revertReason: z.string().optional(),
+  code: z.number().optional(),
+  rawErrorBytes: z.string().optional(),
+  decodeResult: simulateRevertDecodeResultSchema.optional(),
+});
+
+const simulateSetupErrorSchema = z.object({
+  status: z.literal('error'),
+  message: z.string(),
+});
+
+const simulateResultSchema = z.discriminatedUnion('status', [
+  simulateOkSchema,
+  simulateRevertSchema,
+  simulateSetupErrorSchema,
+]);
+
+// The type the schema actually parses out. Kept private (referencing it from an
+// exported declaration would break `--isolatedDeclarations`) and pinned to the
+// canonical `SimulateResult` inside `parseSimulateResult` below.
+type SimulateResultWire = z.infer<typeof simulateResultSchema>;
+
+/**
+ * Parses a `POST /simulate` body into a {@link SimulateResult}. Returns `null`
+ * when the body does not match the `ok`/`revert`/`error` union, letting the
+ * caller raise a transport-level error.
+ */
+export const parseSimulateResult = (body: unknown): SimulateResult | null => {
+  const parsed = simulateResultSchema.safeParse(body);
+  if (!parsed.success) return null;
+  // Pin the schema to the canonical contract in both directions, so it cannot
+  // silently drift (mirroring the conformance assertion `@lifi/api-schemas` runs
+  // on its server-side simulate schema). Assigning the inferred wire value to a
+  // `SimulateResult` checks wire→spec; `satisfies SimulateResultWire` checks
+  // spec→wire. A missing or mistyped field on either side fails to compile.
+  const result: SimulateResult = parsed.data;
+  return result satisfies SimulateResultWire;
+};
+
+/**
+ * The validated members of an HTTP 206 partial compile envelope. `data` is
+ * verified to be an object but kept untyped — compose-spec owns its full shape
+ * (`ComposeCompilePartialData`) as a hand-authored type, so the caller narrows
+ * it. `error` is fully validated.
+ */
+export interface CompilePartialEnvelope {
+  readonly data: Record<string, unknown>;
+  readonly error: { readonly kind: string; readonly message: string };
+}
+
+const compilePartialEnvelopeSchema = z.object({
+  data: z.record(z.string(), z.unknown()),
+  error: z.object({ kind: z.string(), message: z.string() }),
+});
+
+/** Parses an HTTP 206 partial compile envelope; `null` when it does not match. */
+export const parseCompilePartialEnvelope = (
+  body: unknown,
+): CompilePartialEnvelope | null => {
+  const parsed = compilePartialEnvelopeSchema.safeParse(body);
+  return parsed.success ? parsed.data : null;
+};
+
+/** Error envelope returned on non-2xx responses. */
+export interface ServerErrorBody {
+  readonly error?: {
+    readonly kind?: string;
+    readonly message?: string;
+    readonly path?: string;
+    readonly details?: SimulationRevert;
+  };
+}
+
+// `details` is passed through (`z.custom`) rather than parsed: the SDK does not
+// own the `SimulationRevert` schema and forwards the field verbatim onto
+// `ComposeError`.
+const serverErrorBodySchema = z.object({
+  error: z
+    .object({
+      kind: z.string().optional(),
+      message: z.string().optional(),
+      path: z.string().optional(),
+      details: z.custom<SimulationRevert>().optional(),
+    })
+    .optional(),
+});
+
+/** Validates an already-parsed error envelope; `null` when it does not match. */
+export const parseServerErrorBody = (json: unknown): ServerErrorBody | null => {
+  const parsed = serverErrorBodySchema.safeParse(json);
+  return parsed.success ? parsed.data : null;
+};

package/src/run/simulate.ts

@@ -0,0 +1,78 @@
+import type {
+  ComposeCompileResult,
+  SimulateRequest,
+  SlotFinderRequirement,
+  TrackedBalance,
+} from '@lifi/compose-spec';
+
+/**
+ * Input for {@link buildSimulateRequest}: a compile result plus the fields a
+ * simulation needs that a compiled flow does not carry.
+ */
+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`.
+   */
+  readonly result: ComposeCompileResult;
+  /** EVM chain id. A compile result does not carry the target chain. */
+  readonly chainId: number;
+  /**
+   * The transaction sender (`from`). A compile result does not carry the
+   * signer, so it must be supplied here.
+   */
+  readonly signer: string;
+  /**
+   * Balances to watch across the simulation. These cannot be inferred from a
+   * flow and must be supplied by the caller.
+   */
+  readonly trackedBalances: readonly TrackedBalance[];
+  /** Optional funding instructions applied before simulation. */
+  readonly requirements?: readonly SlotFinderRequirement[];
+  /** Optional block to pin the simulation to. Omitted ⇒ chain head. */
+  readonly block?: number;
+  /**
+   * Optional native value override. Defaults to the compiled
+   * `transactionRequest.value` when omitted.
+   */
+  readonly value?: bigint | string;
+}
+
+/**
+ * Assembles a {@link SimulateRequest} from a compile result and the
+ * caller-supplied chain, signer, and tracked balances. Pure: performs no
+ * network I/O, does not mutate its input, and returns a fresh object.
+ *
+ * Bridges the common case — simulate the transaction you just compiled —
+ * without coupling raw-transaction simulation to the flow builder. The
+ * `value` defaults to the compiled transaction's value unless overridden.
+ *
+ * @example
+ * ```ts
+ * const compiled = await builder.compile({ inputs: { ... }, signer: '0x1111...' });
+ * const req = buildSimulateRequest({
+ *   result: compiled,
+ *   chainId: 1,
+ *   signer: '0x1111111111111111111111111111111111111111',
+ *   trackedBalances: [{ token: '0xA0b8...', owner: '0x1111...' }],
+ * });
+ * const sim = await sdk.client.simulate(req);
+ * ```
+ */
+export const buildSimulateRequest = (
+  input: BuildSimulateRequestInput,
+): SimulateRequest => {
+  const { result, chainId, signer, trackedBalances, requirements, block } =
+    input;
+  return {
+    chainId,
+    from: signer,
+    to: result.transactionRequest.to,
+    data: result.transactionRequest.data,
+    value: input.value ?? result.transactionRequest.value,
+    block,
+    requirements,
+    trackedBalances,
+  };
+};

package/src/sdk.ts

@@ -2,6 +2,8 @@ import type {
   ComposeCompileRequest,
   ComposeCompileResult,
   InputSpec,
+  SimulateRequest,
+  SimulateResult,
 } from '@lifi/compose-spec';
 
 import {
@@ -117,6 +119,18 @@ export interface ComposeSdk {
     flow: TypedFlow<T>,
     run: ComposeRunInput<T>,
   ) => ComposeCompileRequest;
+  /**
+   * Simulates a raw, pre-encoded transaction. Thin pass-through to
+   * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`
+   * result discrimination and error behaviour. Pair with `buildSimulateRequest`
+   * to assemble the request from a compile result.
+   *
+   * @param request - The raw transaction plus funding `requirements` and
+   *   `trackedBalances`.
+   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
+   * @throws {@link ComposeError} on network, validation, or server errors.
+   */
+  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 
 /**
@@ -170,5 +184,10 @@ export const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {
     return Object.assign(builder, { compile });
   };
 
-  return { client: composeClient, flow, request };
+  return {
+    client: composeClient,
+    flow,
+    request,
+    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 { 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 });
-
-  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 };
-};