@lifi/composer-sdk 0.2.0-staging.5 → 0.3.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,28 @@ export type {
   SimulationRevert,
   SolType,
   SweepTo,
+  SimulateRequest,
+  SimulateResult,
+  SimulateOkResult,
+  SimulateRevertResult,
+  SimulateRevertDecodeResult,
+  SimulateSetupErrorResult,
+  SimulateBalanceEntry,
+  TrackedBalance,
+  SlotFinderRequirement,
+  Erc20BalanceRequirement,
+  NativeBalanceRequirement,
+  Erc20AllowanceRequirement,
+  ContinuationIntent,
+  ContinuationOutcome,
+  Check,
+  CheckComparator,
+  Phase1ArtifactWire,
+  ContinuationPlanWire,
+} from '@lifi/compose-spec';
+export {
+  SIMULATE_MAX_TRACKED_BALANCES,
+  SIMULATE_MAX_REQUIREMENTS,
 } from '@lifi/compose-spec';
 export { isComposeError } from './errors.js';
 
@@ -70,6 +92,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 {
@@ -61,8 +63,8 @@ export interface ComposeSdkOptions {
   readonly baseUrl: string;
   /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */
   readonly fetch?: typeof globalThis.fetch;
-  /** Optional LI.FI API key for authenticated access. Sent as the `x-lifi-api-key` header on every request. */
-  readonly apiKey?: string;
+  /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */
+  readonly apiKey: string;
 }
 
 /**
@@ -75,7 +77,7 @@ export interface ComposeSdkOptions {
  * ```ts
  * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';
  *
- * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });
+ * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });
  *
  * const builder = sdk.flow(1, {
  *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },
@@ -117,17 +119,29 @@ 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>;
 }
 
 /**
  * Creates a new Compose SDK instance.
  *
- * @param options - SDK configuration including the API base URL and optional fetch implementation.
+ * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.
  * @returns A {@link ComposeSdk} instance.
  *
  * @example
  * ```ts
- * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });
+ * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });
  * ```
  */
 export const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {
@@ -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,
+  };
 };