@lifi/composer-sdk 0.4.1 → 0.5.1

package/src/examples/flySwap.ts

@@ -0,0 +1,167 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../index.js';
+
+import { API_KEY, BASE_URL, OWNER } from './config.js';
+
+// Base mainnet. Pendle PT-USDC, its underlying USDC, and WETH.
+const BASE = 8453;
+const PT_USDC = '0x0d18b7bab00988a442e31065e76286844809dc9a';
+const USDC = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
+const WETH = '0x4200000000000000000000000000000000000006';
+
+/**
+ * Exit a Pendle PT position and swap **all** of the proceeds to WETH on Base.
+ *
+ * ## The problem this solves
+ *
+ * Every other swap op bakes a fixed input amount into the router calldata at
+ * quote time. That is fine when you know the amount up front, and useless when
+ * you do not: a PT exit routes through an on-chain AMM quote, so it can deliver
+ * a little more or a little less than the estimate. With `lifi.swap` you must
+ * name an amount, and whatever the exit over-delivers is stranded in the proxy
+ * (or, if it under-delivers, the flow reverts).
+ *
+ * `fly.swap` is the only swap that can sit downstream of a producer whose output
+ * is not known until execution. Fly's `DexAggregator` supports a variable-input
+ * mode — the `amountIn` word is excluded from the signed quote, so leaving it
+ * unset makes the contract resolve the amount on-chain: for an erc20 input,
+ * `min(our balance, the allowance we granted)`; for a native input, whatever
+ * `msg.value` the op forwards. The op therefore swaps *all* of whatever
+ * actually arrives. Either leg may be the chain's gas coin.
+ *
+ * ## The two numbers, which are independent
+ *
+ * This is the thing to get right, because they sound alike and are not:
+ *
+ * - **`inputVarianceBps`** describes the **upstream**: how far its real output
+ *   may sit either side of the estimate, symmetrically. It is a quantity, not a
+ *   price.
+ * - **`maxSlippageBps`** is ordinary **price** protection: expected rate versus
+ *   achieved rate, sized on the pair, and completely unaffected by how much
+ *   input turns up. It is enforced on-chain as a *rate* against the input
+ *   actually consumed, so the percentage protection is identical at any size.
+ *
+ * Neither is derived from the other and neither constrains the other. A
+ * `maxSlippageBps` below `inputVarianceBps` is perfectly legitimate.
+ *
+ * ## Choosing `inputVarianceBps` (default 50 = 0.5%)
+ *
+ * The compile-time input amount is **simulated** at the current block, not
+ * guessed — the compiler runs the upstream and reads what it produced. So this
+ * field covers only simulate-to-execute drift: block delay, yield accrued in
+ * that window, and third parties moving the upstream's rate in between. Tens of
+ * basis points, not percent.
+ *
+ * Widening it is safe but not free. The bottom of the band is what the compose
+ * response publishes as `amountOutMin`, so a wider band advertises a weaker
+ * minimum to whoever consumes your quote.
+ *
+ * ## Ignore the 50% slippage in the Fly calldata
+ *
+ * If you inspect the compiled transaction you will see a 50% slippage figure
+ * where you configured 1%. That is deliberate and it is not your setting. All
+ * Fly's own `slippage` parameter does is price its `amountOutMin`, which is an
+ * absolute amount fixed at quote time and therefore cannot scale down when a
+ * legitimately smaller input arrives. The op sends a high value so that floor
+ * can never be the binding constraint, and enforces its own rate-based bound
+ * instead — which is strictly tighter for every in-band delivery. The number
+ * that protects you is `maxSlippageBps`.
+ *
+ * ## What happens outside the band
+ *
+ * With `E` the simulated exit output, `v = inputVarianceBps`:
+ *
+ *     E = 1000, v = 200 (2%), p = 100 (1%)  ->  band [980, 1020]
+ *
+ *     delivered 1020  -> consumes 1020, nothing left over   (band top)
+ *     delivered 1000  -> consumes 1000, nothing left over
+ *     delivered  980  -> consumes  980, nothing left over   (band bottom)
+ *     delivered  950  -> reverts on the op's own floor invariant
+ *     delivered 1200  -> consumes 1020; the 180 excess is swept back to you
+ *
+ * Both out-of-band outcomes are safe. The upward cap exists because Fly
+ * confiscates output above the quoted expectation rather than rejecting it, so
+ * the op never approves more than it quoted for. Note the excess only comes back
+ * if the run supplies `sweepTo` — without it the residue sits in the proxy until
+ * a later flow or an explicit `POST /compose/sweep` collects it.
+ *
+ * ## Two limitations worth knowing before you author
+ *
+ * 1. **`fly.swap` cannot sit downstream of another *prepared* op.** `lifi.zap`
+ *    (used here) and other plain ops are fine. `lifi.swap` and `paraswap.buy`
+ *    are prepared, and the compiler rejects those chains with a message about
+ *    splitting the flow across a continuation.
+ * 2. **The upstream must deliver to the proxy.** `lifi.zap` does so by
+ *    construction. An upstream that exposes its own delivery address — such as
+ *    `morphoBlue.withdraw`'s `receiver` — must have it bound to
+ *    `context.executionAddress`, or the amount it reports will diverge from what
+ *    the proxy actually holds and the op's custody assertion reverts.
+ *
+ * Demonstrates:
+ * - A variable-input swap consuming an upstream's entire, runtime-determined output
+ * - `lifi.zap` as the nondeterministic producer (a PT exit through an AMM quote)
+ * - `sweepTo`, which is what returns any out-of-band residue to the sender
+ *
+ * `fly.swap` is always registered on the backend; without `FLY_API_KEY` it uses
+ * Fly's public host.
+ *
+ * See `docs/references/fly-api.md` for the router behaviour all of this rests on.
+ */
+export const buildFlySwapExample = (): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  const builder = sdk.flow(BASE, {
+    name: 'pt-usdc-exit-swap-all-to-weth',
+    inputs: {
+      amountIn: resources.erc20(PT_USDC, BASE),
+    },
+  });
+
+  // Exit the PT position to its underlying USDC. `lifi.zap` declares no
+  // output-amount estimator, so the compiler cannot resolve the next node's
+  // input statically and instead simulates this node to read what it really
+  // produced. That simulated value is what `fly.swap` quotes against, and it is
+  // why a 50 bps band is enough.
+  const exitPt = builder.lifi.zap('exitPt', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: {
+      resourceOut: resources.erc20(USDC, BASE),
+    },
+  });
+
+  // Swap the entire exit output to WETH.
+  //
+  // No slippage guard here, and none is accepted: `amountOut` declares
+  // `providesMinimum`, so the op owns its own bound. Attaching one is a
+  // `guard_error`. The published `amountOutMin` is the op's, derived from the
+  // bottom of the input band.
+  builder.fly.swap('swapAllToWeth', {
+    bind: { amountIn: exitPt.amountOut },
+    config: {
+      resourceOut: resources.erc20(WETH, BASE),
+      // The exit is a same-block simulation, so only drift needs covering.
+      inputVarianceBps: 50,
+      // Price protection on the USDC/WETH pair, independent of the above.
+      maxSlippageBps: 100,
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: OWNER,
+    inputs: {
+      // 1 PT-USDC (6 decimals).
+      amountIn: materialisers.directDeposit({ amount: '1000000' }),
+    },
+    // Load-bearing, not boilerplate: this is what returns the unconsumed input
+    // to the sender if the exit over-delivers past the top of the band.
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/run.ts

@@ -21,6 +21,7 @@
  *   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)
+ *   fly-swap          — exit a Pendle PT position and swap ALL proceeds to WETH
  *   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
@@ -35,13 +36,15 @@
  *   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
+ *   supported-chains  — list the chains this deployment supports, and guard on them
  */
 import type {
   ComposeCompileRequest,
   ComposeRouteRequest,
 } from '@lifi/compose-spec';
 
-import { createComposeSdk } from '../sdk.js';
+import { bigintReplacer } from '../client.js';
+import { type ComposeSdk, createComposeSdk } from '../sdk.js';
 
 import { buildAaveRepay } from './aaveRepay.js';
 import { buildAaveRepayWithATokens } from './aaveRepayWithATokens.js';
@@ -53,6 +56,7 @@ import { buildConsolidateToEth } from './consolidateToEth.js';
 import { buildConsolidateStablesToUsdc } from './consolidateToUsdc.js';
 import { buildDepositFromProxy } from './depositFromProxy.js';
 import { buildDustSweepExample } from './dustSweep.js';
+import { buildFlySwapExample } from './flySwap.js';
 import { buildLifiSwapExample } from './lifiSwap.js';
 import { buildLifiZapExample } from './lifiZap.js';
 import { buildLifiZapAsyncExample } from './lifiZapAsync.js';
@@ -64,6 +68,7 @@ import {
 } from './routeTokenPair.js';
 import { buildSplitAndZapExample } from './splitAndZap.js';
 import { buildSplitWithArithmetic } from './splitWithArithmetic.js';
+import { runSupportedChainsExample } from './supportedChains.js';
 import { buildSwapAndZapExample } from './swapAndZap.js';
 import { buildSwapToRecipient } from './swapToRecipient.js';
 import { buildSwapWithAllowRevertExample } from './swapWithAllowRevert.js';
@@ -72,6 +77,9 @@ import { buildSwapWithOutputValidation } from './swapWithOutputValidation.js';
 import { buildPartialTransfer, buildTransferTokens } from './transferTokens.js';
 import { buildUntypedOpWithTypedRef } from './untypedOpWithTypedRef.js';
 
+const stringifyJson = (value: unknown) =>
+  JSON.stringify(value, bigintReplacer, 2);
+
 const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
   'aave-repay': () =>
     buildAaveRepay({
@@ -119,6 +127,7 @@ const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
   zap: () => buildLifiZapExample().request,
   'zap-async': () =>
     buildLifiZapAsyncExample({ owner: OWNER, recipient: RECIPIENT }).request,
+  'fly-swap': () => buildFlySwapExample().request,
   'swap-zap': () => buildSwapAndZapExample().request,
   'swap-check': () =>
     buildSwapWithBalanceCheck({ owner: OWNER, amount: '1000000000000000000' })
@@ -166,6 +175,12 @@ const ROUTE_EXAMPLES: Record<string, () => ComposeRouteRequest> = {
   'route-all': buildRouteAllExample,
 };
 
+// Query examples read from the API instead of building a request to compile,
+// so they take the sdk and print their own output.
+const QUERY_EXAMPLES: Record<string, (sdk: ComposeSdk) => Promise<void>> = {
+  'supported-chains': runSupportedChainsExample,
+};
+
 const run = async () => {
   const args = process.argv.slice(2);
   const useStaged = args.includes('--staged');
@@ -186,11 +201,16 @@ const run = async () => {
     examples = { ...EXAMPLES, ...stagedModule.STAGED_EXAMPLES };
   }
 
+  const queryExample = name ? QUERY_EXAMPLES[name] : undefined;
   const routeBuilder = name ? ROUTE_EXAMPLES[name] : undefined;
   const builder = name ? examples[name] : undefined;
 
-  if (!builder && !routeBuilder) {
-    const valid = [...Object.keys(examples), ...Object.keys(ROUTE_EXAMPLES)]
+  if (!builder && !routeBuilder && !queryExample) {
+    const valid = [
+      ...Object.keys(examples),
+      ...Object.keys(ROUTE_EXAMPLES),
+      ...Object.keys(QUERY_EXAMPLES),
+    ]
       .sort()
       .join(', ');
     console.error(
@@ -204,18 +224,20 @@ const run = async () => {
   }
   console.log(`Running example: ${name}`);
 
-  const request = routeBuilder ? routeBuilder() : builder!();
   const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
+  // Query examples do their own I/O and printing - there is no request to
+  // show and nothing to compile.
+  if (queryExample) {
+    console.log(`\n--- Querying ${BASE_URL} ---`);
+    await queryExample(sdk);
+    return;
+  }
+
+  const request = routeBuilder ? routeBuilder() : builder!();
+
   console.log('--- Request ---');
-  console.log(
-    JSON.stringify(
-      request,
-      (_key, value: unknown) =>
-        typeof value === 'bigint' ? value.toString() : value,
-      2,
-    ),
-  );
+  console.log(stringifyJson(request));
 
   console.log(`\n--- Compiling against ${BASE_URL} ---`);
   const result = routeBuilder
@@ -223,7 +245,7 @@ const run = async () => {
     : await sdk.client.compile(request as ComposeCompileRequest);
 
   console.log('\n--- Result ---');
-  console.log(JSON.stringify(result, null, 2));
+  console.log(stringifyJson(result));
 };
 
 run().catch((err: unknown) => {

package/src/examples/supportedChains.ts

@@ -0,0 +1,122 @@
+import type { ChainSummary } from '../discovery.js';
+import type { ComposeSdk } from '../sdk.js';
+
+/**
+ * The slice of {@link ComposeSdk} these helpers need. Depending on the one
+ * capability rather than the whole SDK keeps them testable with a two-line
+ * fake, and documents that nothing here touches the compile path.
+ */
+export type SupportedChainsSource = Pick<ComposeSdk, 'getSupportedChains'>;
+
+/**
+ * A memoised view of the supported-chain list.
+ */
+export interface SupportedChainsCache {
+  /** Supported chains, ascending by `chainId`. Fetched once, then served from memory. */
+  readonly get: () => Promise<readonly ChainSummary[]>;
+  /**
+   * Resolves when `chainId` is supported, rejects with an actionable message
+   * naming the alternatives when it is not.
+   */
+  readonly assertSupported: (chainId: number) => Promise<void>;
+  /**
+   * Display label for `chainId`, or `undefined` when the deployment does not
+   * support it. Served from the same cached fetch as {@link get}.
+   */
+  readonly nameOf: (chainId: number) => Promise<string | undefined>;
+  /** Drops the memoised list so the next {@link get} refetches. */
+  readonly refresh: () => void;
+}
+
+/**
+ * Wraps `sdk.getSupportedChains()` in a cache so a long-lived process pays for
+ * one round trip instead of one per check.
+ *
+ * The SDK deliberately does not cache the list — the backend's chain registry
+ * refreshes periodically, so the right lifetime is the caller's to choose.
+ * Chains are added rarely, so caching for the life of a request handler (or
+ * refreshing on a timer via {@link SupportedChainsCache.refresh}) is usually
+ * right.
+ *
+ * Demonstrates:
+ * - `sdk.getSupportedChains()`, the convenience accessor over `GET /chains`
+ * - Preflighting a chain so an unsupported one fails locally with a message
+ *   naming the alternatives, instead of costing a server round trip
+ * - Turning the per-chain `name` into display labels without a second lookup
+ *   or a hardcoded chain-name table
+ * - Memoising the in-flight promise, not just the settled value, so concurrent
+ *   first callers share one request
+ */
+export const createSupportedChainsCache = (
+  sdk: SupportedChainsSource,
+): SupportedChainsCache => {
+  let inFlight: Promise<readonly ChainSummary[]> | undefined;
+
+  const get = (): Promise<readonly ChainSummary[]> => {
+    // A rejected fetch must not be memoised, or one transient network blip
+    // would poison every later lookup.
+    inFlight ??= sdk.getSupportedChains().catch((err: unknown) => {
+      inFlight = undefined;
+      throw err;
+    });
+    return inFlight;
+  };
+
+  const find = async (chainId: number): Promise<ChainSummary | undefined> =>
+    (await get()).find((chain) => chain.chainId === chainId);
+
+  return {
+    get,
+    assertSupported: async (chainId: number): Promise<void> => {
+      if (await find(chainId)) return;
+      const chains = await get();
+      throw new Error(
+        `Chain ${chainId} is not supported by this Compose deployment. ` +
+          `Supported chains: ${chains
+            .map((chain) => `${chain.name} (${chain.chainId})`)
+            .join(', ')}`,
+      );
+    },
+    nameOf: async (chainId: number): Promise<string | undefined> =>
+      (await find(chainId))?.name,
+    refresh: (): void => {
+      inFlight = undefined;
+    },
+  };
+};
+
+/** Ethereum mainnet — supported by every deployment. */
+const MAINNET = 1;
+/** Not an EVM chain ID any deployment serves; stands in for a bad input. */
+const UNSUPPORTED = 999_999;
+
+/**
+ * Harness entry point: prints the live chain list with names, then shows the
+ * guard accepting a supported chain and rejecting an unsupported one.
+ */
+export const runSupportedChainsExample = async (
+  sdk: SupportedChainsSource,
+): Promise<void> => {
+  const chains = createSupportedChainsCache(sdk);
+
+  const supported = await chains.get();
+  console.log(`Supported chains (${supported.length}):`);
+  for (const { chainId, name } of supported) {
+    console.log(`  ${chainId}\t${name}`);
+  }
+
+  await chains.assertSupported(MAINNET);
+  // Served from cache: no second round trip.
+  console.log(
+    `\n${await chains.nameOf(MAINNET)} (${MAINNET}) is supported — safe to build a request.`,
+  );
+
+  await chains
+    .assertSupported(UNSUPPORTED)
+    .then(() => {
+      throw new Error(`expected chain ${UNSUPPORTED} to be rejected`);
+    })
+    .catch((err: unknown) => {
+      console.log(`\nGuard rejected as expected: ${(err as Error).message}`);
+    });
+};

package/src/generated/config.generated.ts

@@ -731,6 +731,30 @@ export interface CorePeekConfig {
   args?: string[];
 }
 
+/**
+ * a number between 0 and 3318
+ */
+export type Between03318 = number;
+/**
+ * a number between 0 and 5000
+ */
+export type Between05000 = number;
+
+export interface FlySwapConfig {
+  resourceOut:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
+  inputVarianceBps?: Between03318;
+  maxSlippageBps?: Between05000;
+}
+
 export interface SlippageGuardConfig {
   port: string;
   bps: Between010000;

package/src/generated/operations.generated.ts

@@ -35,6 +35,7 @@ import type {
   CoreSplitConfig,
   CoreStaticCallConfig,
   CoreTransferConfig,
+  FlySwapConfig,
   InvariantEqConfig,
   InvariantGtConfig,
   InvariantGteConfig,
@@ -550,6 +551,15 @@ export interface CorePeekArgs {
   readonly guards?: readonly TypedGuard<'result'>[];
 }
 
+/** Swap via Fly's DexAggregator, sized at runtime: the router calldata leaves `amountIn` unset, so an upstream op's output can feed the swap without being known at plan time. Either leg may be the chain-native coin. */
+export interface FlySwapArgs {
+  readonly bind: {
+    readonly amountIn: Bindable<'resource'>;
+  };
+  readonly config: FlySwapConfig;
+  readonly guards?: readonly TypedGuard<'unspentIn'>[];
+}
+
 export interface CoreSplitOutputs {
   readonly a: OutputHandle<'resource'>;
   readonly b: OutputHandle<'resource'>;
@@ -651,6 +661,11 @@ export interface CorePeekOutputs {
   readonly result: OutputHandle<'uint256'>;
 }
 
+export interface FlySwapOutputs {
+  readonly amountOut: OutputHandle<'resource'>;
+  readonly unspentIn: OutputHandle<'resource'>;
+}
+
 export type GeneratedOps = {
   readonly core: {
     /** Split a resource into two outputs by basis-point ratio — original id: "core.split" */
@@ -858,6 +873,10 @@ export type GeneratedOps = {
     /** Exact-output (BUY) swap via the Paraswap/Velora Market API: produce exactly `exactAmountOut` of the destination token, pulling only the source needed and exposing the genuinely-unspent source as `unspentIn`. — original id: "paraswap.buy" */
     readonly buy: (nodeId: string, args: ParaswapBuyArgs) => ParaswapBuyOutputs;
   };
+  readonly fly: {
+    /** Swap via Fly's DexAggregator, sized at runtime: the router calldata leaves `amountIn` unset, so an upstream op's output can feed the swap without being known at plan time. Either leg may be the chain-native coin. — original id: "fly.swap" */
+    readonly swap: (nodeId: string, args: FlySwapArgs) => FlySwapOutputs;
+  };
 };
 
 export const bindGeneratedOps = (
@@ -1100,4 +1119,11 @@ export const bindGeneratedOps = (
         unspentIn: 'resource',
       } as const),
   },
+  fly: {
+    swap: (nodeId: string, args: FlySwapArgs) =>
+      builder.call(nodeId, 'fly.swap', args, {
+        amountOut: 'resource',
+        unspentIn: 'resource',
+      } as const),
+  },
 });

package/src/index.ts

@@ -19,9 +19,11 @@ export type {
   OutputKind,
   TypedGuard,
   TypedRef,
+  TypedLiteral,
 } from './types.js';
 
 export type {
+  ChainSummary,
   GetZapPacksOptions,
   ZapPackEdge,
   ZapPackOverview,
@@ -29,6 +31,8 @@ export type {
 export type {
   ComposeError,
   ComposeErrorCode,
+  ComposeSdkOutdated,
+  ComposeServerOutdated,
   ComposePreparationOps,
 } from './errors.js';
 export type {
@@ -36,10 +40,13 @@ export type {
   ApprovalEntry,
   Call,
   ComposeCompilePartialData,
+  ComposeAction,
+  ComposeFill,
+  ComposeFee,
+  ComposeUserProgramSimulation,
   ComposeCompileRequest,
   ComposeCompileResult,
   ComposeCompileSuccessData,
-  ComposeContinuation,
   ComposeErrorKind,
   ComposeRouteRequest,
   ComposeTransactionRequest,
@@ -51,11 +58,13 @@ export type {
   Precondition,
   PreconditionConfigOf,
   PriceImpact,
+  ProducedResource,
   Ref,
   Resource,
   RouteAmount,
   RouteAmountAll,
   RouteAmountExact,
+  SimulatedAmounts,
   SimulationPolicy,
   SimulationRevert,
   SolType,
@@ -83,10 +92,17 @@ export {
   SIMULATE_MAX_TRACKED_BALANCES,
   SIMULATE_MAX_REQUIREMENTS,
 } from '@lifi/compose-spec';
-export { isComposeError, isComposePreparationError } from './errors.js';
+export {
+  isComposeError,
+  isComposePreparationError,
+  isComposeSdkOutdatedError,
+  isComposeServerOutdatedError,
+} from './errors.js';
 
 export type {
   Bindable,
+  RefBindable,
+  AnyRefBindable,
   InputHandle,
   ResourceInputHandle,
   OutputHandle,

package/src/raw.ts

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

package/src/responseSchemas.ts

@@ -131,6 +131,9 @@ export interface ServerErrorBody {
     readonly kind?: string;
     readonly message?: string;
     readonly path?: string;
+    readonly sdkVersion?: string;
+    readonly serverVersion?: string;
+    readonly minimumSdkVersion?: string;
     readonly details?: SimulationRevert;
     readonly failedOps?: readonly ServerFailedPreparedOp[];
     readonly succeededOps?: readonly string[];
@@ -158,6 +161,9 @@ const serverErrorBodySchema = z.object({
       kind: z.string().optional(),
       message: z.string().optional(),
       path: z.string().optional(),
+      sdkVersion: z.string().optional(),
+      serverVersion: z.string().optional(),
+      minimumSdkVersion: z.string().optional(),
       details: z.custom<SimulationRevert>().optional(),
       failedOps: z.array(failedPreparedOpSchema).readonly().optional(),
       succeededOps: z.array(z.string()).readonly().optional(),

package/src/run/inputs.ts

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