@lifi/composer-sdk 0.5.0 → 0.6.0

package/src/client.ts

@@ -8,6 +8,12 @@ import type {
   SimulateRequest,
   SimulateResult,
 } from '@lifi/compose-spec';
+import {
+  checkCompatibility,
+  COMPOSE_VERSION_HEADER,
+  COMPOSER_SDK_VERSION_HEADER,
+  parseVersion,
+} from '@lifi/compose-spec';
 
 import type {
   ChainSummary,
@@ -23,12 +29,14 @@ import {
 // __SDK_VERSION__ is a compile-time constant injected by tsup (via `define` in tsup.config.ts)
 // and by vitest (via `define` in vitest.config.ts). Both read the version from package.json
 // at build/test time and replace this identifier with the literal string value.
-// It is sent as the `x-lifi-composer-sdk` request header so the server can identify the caller.
+// It is sent as the `COMPOSER_SDK_VERSION_HEADER` request header so the server can identify the caller.
 // Falls back to 'dev' when running via tsx without tsup substitution (e.g. the example harness).
 declare const __SDK_VERSION__: string;
 
 const SDK_VERSION: string =
   typeof __SDK_VERSION__ !== 'undefined' ? __SDK_VERSION__ : 'dev';
+// `undefined` for the `dev` sentinel, which disables the response version check.
+const SDK_VERSION_TRIPLE = parseVersion(SDK_VERSION);
 
 /**
  * Configuration for creating a low-level Compose API client.
@@ -115,11 +123,11 @@ export interface ComposeClient {
    * the server, not the shape of this contract.
    *
    * Only synchronous edges are considered unless the request sets
-   * `allowAsyncRoutes: true`, so by default every produced resource comes back
-   * `availability: 'now'` and a pair reachable only after settlement is a
+   * `allowAsyncRoutes: true`, so by default every terminal output comes back
+   * `delivery.when: 'now'` and a pair reachable only after settlement is a
    * `no_route_error`. Opting in adds the `lifi.zapAsync` fallback, which still
    * loses to a synchronous edge when the pair has one; read
-   * `producedResources[*].availability` to see which representation you got.
+   * `outputs[*].delivery.when` to see which representation you got.
    *
    * Use {@link compile} for what the server does not author for you: several
    * chained operations, splits, explicit preconditions, or per-op guards.
@@ -176,7 +184,14 @@ export interface ComposeClient {
   readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 
-const bigintReplacer = (_key: string, value: unknown): unknown =>
+/**
+ * `JSON.stringify` replacer that renders `bigint` amounts as decimal strings.
+ *
+ * The compose wire carries token amounts as decimal strings, and `bigint` has
+ * no JSON representation, so every payload this client sends goes through it.
+ * Exported so the example harness prints a request exactly as it is sent.
+ */
+export const bigintReplacer = (_key: string, value: unknown): unknown =>
   typeof value === 'bigint' ? value.toString() : value;
 
 const isNonNullObject = (v: unknown): v is Record<string, unknown> =>
@@ -185,16 +200,11 @@ const isNonNullObject = (v: unknown): v is Record<string, unknown> =>
 // Non-negative decimal integer string, as the server sends token amounts.
 const INTEGER_STRING = /^\d+$/;
 
-const decodeAmount = (
-  value: unknown,
-  key: string,
-  field: 'amountOut' | 'amountOutMin',
-  url: string,
-): bigint => {
+const decodeAmount = (value: unknown, path: string, url: string): bigint => {
   if (typeof value !== 'string' || !INTEGER_STRING.test(value)) {
     throw new ComposeError(
       'UNKNOWN_ERROR',
-      `Malformed compose response: producedResources.${key}.simulated.${field} is ${
+      `Malformed compose response: ${path} is ${
         value === undefined ? 'absent' : 'not an integer string'
       }`,
       { url },
@@ -203,46 +213,83 @@ const decodeAmount = (
   return BigInt(value);
 };
 
-// `simulated.amountOut` / `.amountOutMin` are declared `bigint` on
-// `SimulatedAmounts` (the domain truth: `compose-core` produces real bigints)
-// but arrive as decimal strings on the wire (the backend stringifies them).
-// Decode at this seam so a consumer reading the declared type gets the value
-// the type promises. A resource without `simulated` is left untouched; a
-// `simulated` claiming a missing or non-numeric amount is a contract violation
-// and surfaces as a `ComposeError` rather than `NaN` / `BigInt(undefined)`.
-const decodeSimulatedAmounts = (data: unknown, url: string): void => {
-  if (!isNonNullObject(data)) return;
-  const resources = data.producedResources;
-  if (!isNonNullObject(resources)) return;
-  for (const key of Object.keys(resources)) {
-    const resource = resources[key];
-    if (!isNonNullObject(resource)) continue;
-    const simulated = resource.simulated;
-    if (simulated === undefined) continue;
-    if (!isNonNullObject(simulated)) {
-      throw new ComposeError(
-        'UNKNOWN_ERROR',
-        `Malformed compose response: producedResources.${key}.simulated is not an object`,
-        { url },
-      );
-    }
-    simulated.amountOut = decodeAmount(
-      simulated.amountOut,
-      key,
-      'amountOut',
+// The two records this seam reads out of a compile-family response body. Each
+// is `unknown` because the seam is what establishes its shape: it validates
+// every field before writing a decoded `bigint` back over the wire string.
+interface WireAmountBody {
+  outputs?: unknown;
+}
+
+// One `Amount` as it arrives: each leaf is `unknown` until this seam has
+// checked it, and is overwritten in place with the decoded `bigint`.
+interface WireAmount {
+  estimate?: unknown;
+  minimum?: unknown;
+}
+
+const malformed = (path: string, what: string, url: string): ComposeError =>
+  new ComposeError(
+    'UNKNOWN_ERROR',
+    `Malformed compose response: ${path} ${what}`,
+    { url },
+  );
+
+// Decode one `Estimate` / `Minimum` leaf in place: `{ basis, value }` with
+// `value` a decimal string on the wire and a `bigint` on `Amount`.
+const decodeAmountLeaf = (
+  amount: WireAmount,
+  field: 'estimate' | 'minimum',
+  path: string,
+  url: string,
+): void => {
+  const leaf = amount[field];
+  if (leaf === undefined) return;
+  if (!isNonNullObject(leaf)) {
+    throw malformed(`${path}.${field}`, 'is not an object', url);
+  }
+  leaf.value = decodeAmount(leaf.value, `${path}.${field}.value`, url);
+};
+
+// `outputs` is REQUIRED on every compile-family body and is the record a
+// caller reads amounts from, so its structure is checked here — the body is
+// cast, not schema-parsed — before each `value` leaf becomes a `bigint`.
+const decodeOutputs = (data: WireAmountBody, url: string): void => {
+  const outputs = data.outputs;
+  if (!isNonNullObject(outputs)) {
+    throw malformed(
+      'outputs',
+      outputs === undefined ? 'is absent' : 'is not an object',
       url,
     );
-    if (simulated.amountOutMin !== undefined) {
-      simulated.amountOutMin = decodeAmount(
-        simulated.amountOutMin,
-        key,
-        'amountOutMin',
+  }
+  for (const key of Object.keys(outputs)) {
+    const entry = outputs[key];
+    if (!isNonNullObject(entry)) {
+      throw malformed(`outputs.${key}`, 'is not an object', url);
+    }
+    const amount = entry.amount;
+    if (!isNonNullObject(amount)) {
+      throw malformed(
+        `outputs.${key}.amount`,
+        amount === undefined ? 'is absent' : 'is not an object',
         url,
       );
     }
+    decodeAmountLeaf(amount, 'estimate', `outputs.${key}.amount`, url);
+    decodeAmountLeaf(amount, 'minimum', `outputs.${key}.amount`, url);
   }
 };
 
+// THE decode seam for a compile-family response body: every amount the wire
+// renders as a decimal string becomes the `bigint` its declared type promises.
+// The amount record is handled here so the body is narrowed once — a
+// non-object body is not this function's error to raise, since the enveloping
+// parse already rejected it.
+const decodeWireAmounts = (data: unknown, url: string): void => {
+  if (!isNonNullObject(data)) return;
+  decodeOutputs(data, url);
+};
+
 const parseBody = async <T>(res: Response, url: string): Promise<T> => {
   const body = await res.json().catch((_) => null);
   if (!isNonNullObject(body) || !('data' in body)) {
@@ -258,7 +305,7 @@ const parseCompileSuccessBody = async (
   url: string,
 ): Promise<ComposeCompileResult> => {
   const data = await parseBody<ComposeCompileSuccessData>(res, url);
-  decodeSimulatedAmounts(data, url);
+  decodeWireAmounts(data, url);
   return { ...data, status: 'success' as const };
 };
 
@@ -278,8 +325,8 @@ const parsePartialBody = async (
   // `data` is validated as an object by the schema; compose-spec owns its full
   // shape as a hand-authored type, so we narrow it here rather than re-declaring
   // that type as a schema. `error` is fully validated — no cast needed.
-  const data = envelope.data as unknown as ComposeCompilePartialData;
-  decodeSimulatedAmounts(data, url);
+  const data = envelope.data as ComposeCompilePartialData;
+  decodeWireAmounts(data, url);
   return { ...data, status: 'partial' as const, error: envelope.error };
 };
 
@@ -310,22 +357,92 @@ type ComposeTransport = {
   readonly baseHeaders: Record<string, string>;
 };
 
-const postCompile = async (
+// A patch bump is additive and a minor bump is breaking, so a 200 from a
+// backend behind this SDK cannot be trusted: the newer flow this SDK authored
+// may have compiled under the server's older semantics without raising an
+// error. This covers the deploy window where the SDK is published to npm ahead
+// of the backend rollout. Only the compile-family POSTs are checked; discovery
+// GETs stay reachable from a mismatched SDK, as on the server. An absent header
+// (a pre-gate backend, a header-stripping proxy) is accepted, mirroring the
+// server's pass-through of a compile that carries no version header.
+const assertServerVersion = (res: Response, url: string): void => {
+  const serverVersion = res.headers.get(COMPOSE_VERSION_HEADER);
+  if (serverVersion === null || SDK_VERSION_TRIPLE === undefined) return;
+  const serverTriple = parseVersion(serverVersion);
+  if (serverTriple === undefined) return;
+
+  const compatibility = checkCompatibility(SDK_VERSION_TRIPLE, serverTriple);
+  if (compatibility === 'compatible') return;
+
+  const versions = { sdkVersion: SDK_VERSION, serverVersion };
+  if (compatibility === 'sdk_outdated') {
+    throw new ComposeError(
+      'VALIDATION_ERROR',
+      `composer-sdk ${SDK_VERSION} is older than the compose contract served at ${url} (${serverVersion}); upgrade @lifi/composer-sdk and @lifi/compose-spec`,
+      {
+        status: res.status,
+        url,
+        kind: 'sdk_outdated',
+        sdkOutdated: {
+          ...versions,
+          minimumSdkVersion: `${serverTriple.major}.${serverTriple.minor}.0`,
+        },
+      },
+    );
+  }
+  throw new ComposeError(
+    'VALIDATION_ERROR',
+    `composer-sdk ${SDK_VERSION} targets a newer compose contract than the server at ${url} serves (${serverVersion}); pin @lifi/composer-sdk and @lifi/compose-spec to ${serverVersion} or wait for the server rollout`,
+    {
+      status: res.status,
+      url,
+      kind: 'server_outdated',
+      serverOutdated: versions,
+    },
+  );
+};
+
+type SendInit =
+  | { readonly method: 'GET' }
+  | { readonly method: 'POST'; readonly body: unknown };
+
+// GETs on this API carry no body; POSTs carry a JSON one with `bigint` amounts
+// rendered as decimal strings.
+const requestInit = (
+  baseHeaders: Record<string, string>,
+  init: SendInit,
+): RequestInit =>
+  init.method === 'GET'
+    ? { method: 'GET', headers: { ...baseHeaders } }
+    : {
+        method: 'POST',
+        headers: { ...baseHeaders, 'Content-Type': 'application/json' },
+        body: JSON.stringify(init.body, bigintReplacer),
+      };
+
+// One fetch path for every route: maps transport failures to `NETWORK_ERROR`.
+// The response version check is not here — only the compile-family POSTs gate
+// on it (see `postCompile`); discovery GETs and `/simulate` are ungated.
+const send = async (
   { fetchFn, baseHeaders }: ComposeTransport,
   url: string,
-  request: ComposeCompileRequest | ComposeRouteRequest,
-): Promise<ComposeCompileResult> => {
-  let res: Response;
+  init: SendInit,
+): Promise<Response> => {
   try {
-    res = await fetchFn(url, {
-      method: 'POST',
-      headers: { ...baseHeaders, 'Content-Type': 'application/json' },
-      body: JSON.stringify(request, bigintReplacer),
-    });
+    return await fetchFn(url, requestInit(baseHeaders, init));
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     throw new ComposeError('NETWORK_ERROR', message, { cause: err });
   }
+};
+
+const postCompile = async (
+  transport: ComposeTransport,
+  url: string,
+  request: ComposeCompileRequest | ComposeRouteRequest,
+): Promise<ComposeCompileResult> => {
+  const res = await send(transport, url, { method: 'POST', body: request });
+  assertServerVersion(res, url);
   if (res.status === 206) {
     return await parsePartialBody(res, url);
   }
@@ -339,19 +456,10 @@ const postCompile = async (
 // Every enveloped GET on this API behaves identically: no body, no query
 // semantics of its own, `{ data }` on success, an error envelope otherwise.
 const getJson = async <T>(
-  { fetchFn, baseHeaders }: ComposeTransport,
+  transport: ComposeTransport,
   url: string,
 ): Promise<T> => {
-  let res: Response;
-  try {
-    res = await fetchFn(url, {
-      method: 'GET',
-      headers: { ...baseHeaders },
-    });
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    throw new ComposeError('NETWORK_ERROR', message, { cause: err });
-  }
+  const res = await send(transport, url, { method: 'GET' });
   if (!res.ok) {
     const body = await res.text();
     throw errorFromHttpResponse(res.status, body, url);
@@ -386,7 +494,7 @@ export const createComposeClient = (
 
   const baseHeaders: Record<string, string> = {
     Accept: 'application/json',
-    'x-lifi-composer-sdk': SDK_VERSION,
+    [COMPOSER_SDK_VERSION_HEADER]: SDK_VERSION,
     'x-lifi-api-key': trimmedApiKey,
   };
   const transport: ComposeTransport = { fetchFn, baseHeaders };
@@ -428,17 +536,7 @@ export const createComposeClient = (
     request: SimulateRequest,
   ): Promise<SimulateResult> => {
     const url = `${base}/simulate`;
-    let res: Response;
-    try {
-      res = await fetchFn(url, {
-        method: 'POST',
-        headers: { ...baseHeaders, 'Content-Type': 'application/json' },
-        body: JSON.stringify(request, bigintReplacer),
-      });
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      throw new ComposeError('NETWORK_ERROR', message, { cause: err });
-    }
+    const res = await send(transport, url, { method: 'POST', body: request });
     // Only 200 (carries `ok`/`revert`) and 422 (carries the `error` member of
     // the union) have a discriminated body. 422 is deliberately intercepted
     // here (not thrown as VALIDATION_ERROR) so callers get one exhaustive

package/src/errors.ts

@@ -1,9 +1,11 @@
 import type {
   ComposeErrorKind,
+  ComposeRouteErrorKind,
   FailedPreparedOp,
   GenericComposeErrorKind,
   SimulationRevert,
 } from '@lifi/compose-spec';
+import z from 'zod';
 
 import {
   parseServerErrorBody,
@@ -32,6 +34,24 @@ export type ComposeErrorCode =
   | 'NOT_FOUND'
   | 'UNKNOWN_ERROR';
 
+/** Version details returned when the backend rejects an outdated SDK. */
+export interface ComposeSdkOutdated {
+  readonly sdkVersion: string;
+  readonly serverVersion: string;
+  readonly minimumSdkVersion: string;
+}
+
+/**
+ * Version details attached when the SDK is ahead of the backend it reached.
+ * Raised by the backend's version gate, or by the SDK itself when the
+ * `x-lifi-composer-version` response header names an older contract than the
+ * one this SDK was built against.
+ */
+export interface ComposeServerOutdated {
+  readonly sdkVersion: string;
+  readonly serverVersion: string;
+}
+
 /**
  * Error class for all failures originating from the Compose SDK or API.
  *
@@ -58,7 +78,7 @@ export class ComposeError extends Error {
   /** The request URL that produced the error. */
   readonly url?: string;
   /** Server-provided error kind for finer-grained classification. */
-  readonly kind?: ComposeErrorKind;
+  readonly kind?: ComposeErrorKind | ComposeRouteErrorKind;
   /** JSON-pointer path to the field that caused a validation error. */
   readonly path?: string;
   /**
@@ -78,6 +98,10 @@ export class ComposeError extends Error {
    * `preparation_error` errors alongside {@link ComposeError.failedOps}.
    */
   readonly succeededOps?: readonly string[];
+  /** Version details attached only to `sdk_outdated` errors. */
+  readonly sdkOutdated?: ComposeSdkOutdated;
+  /** Version details attached only to `server_outdated` errors. */
+  readonly serverOutdated?: ComposeServerOutdated;
 
   constructor(
     code: ComposeErrorCode,
@@ -86,11 +110,13 @@ export class ComposeError extends Error {
       status?: number;
       url?: string;
       cause?: unknown;
-      kind?: ComposeErrorKind;
+      kind?: ComposeErrorKind | ComposeRouteErrorKind;
       path?: string;
       details?: SimulationRevert;
       failedOps?: readonly FailedPreparedOp[];
       succeededOps?: readonly string[];
+      sdkOutdated?: ComposeSdkOutdated;
+      serverOutdated?: ComposeServerOutdated;
     },
   ) {
     super(message, { cause: options?.cause });
@@ -102,6 +128,8 @@ export class ComposeError extends Error {
     this.details = options?.details;
     this.failedOps = options?.failedOps;
     this.succeededOps = options?.succeededOps;
+    this.sdkOutdated = options?.sdkOutdated;
+    this.serverOutdated = options?.serverOutdated;
   }
 }
 
@@ -153,6 +181,69 @@ export const isComposePreparationError = (
   Array.isArray(e.failedOps) &&
   Array.isArray(e.succeededOps);
 
+// `isComposeError` accepts a structurally-similar error by name, so an error
+// raised by a *second* copy of this package in the dependency tree reaches the
+// guard below without its `sdkOutdated` field being type-guaranteed. Parse it.
+const sdkOutdatedSchema = z.object({
+  sdkVersion: z.string(),
+  serverVersion: z.string(),
+  minimumSdkVersion: z.string(),
+});
+
+/**
+ * Narrows an outdated-SDK rejection to its required version details.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await builder.compile(run);
+ * } catch (e) {
+ *   if (isComposeSdkOutdatedError(e)) {
+ *     console.error(`Upgrade to at least ${e.sdkOutdated.minimumSdkVersion}`);
+ *     return;
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const isComposeSdkOutdatedError = (
+  e: unknown,
+): e is ComposeError & { readonly sdkOutdated: ComposeSdkOutdated } =>
+  isComposeError(e) &&
+  e.kind === 'sdk_outdated' &&
+  sdkOutdatedSchema.safeParse(e.sdkOutdated).success;
+
+const serverOutdatedSchema = z.object({
+  sdkVersion: z.string(),
+  serverVersion: z.string(),
+});
+
+/**
+ * Narrows a server-behind-SDK rejection to its required version details.
+ *
+ * This is the deploy-window error: the SDK on npm is ahead of the backend that
+ * answered. Pin the SDK to the server's `major.minor`, or wait for the rollout.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await builder.compile(run);
+ * } catch (e) {
+ *   if (isComposeServerOutdatedError(e)) {
+ *     console.error(`Server serves ${e.serverOutdated.serverVersion}`);
+ *     return;
+ *   }
+ *   throw e;
+ * }
+ * ```
+ */
+export const isComposeServerOutdatedError = (
+  e: unknown,
+): e is ComposeError & { readonly serverOutdated: ComposeServerOutdated } =>
+  isComposeError(e) &&
+  e.kind === 'server_outdated' &&
+  serverOutdatedSchema.safeParse(e.serverOutdated).success;
+
 const STATUS_TO_CODE: ReadonlyMap<number, ComposeErrorCode> = new Map<
   number,
   ComposeErrorCode
@@ -175,6 +266,24 @@ const tryParseErrorBody = (body: string): ServerErrorBody | null => {
   return parseServerErrorBody(json);
 };
 
+/**
+ * Extracts the version triple an `sdk_outdated` or `server_outdated` envelope
+ * carries. The slots reuse the same schemas the type guards narrow with. Zod
+ * strips keys the schema does not declare, so the parsed value is exactly the
+ * triple; a partial payload fails the parse and yields `undefined` rather than
+ * a half-populated object.
+ */
+const readVersionSlots = (serverError: ServerErrorBody['error']) => ({
+  sdkOutdated:
+    serverError?.kind === 'sdk_outdated'
+      ? sdkOutdatedSchema.safeParse(serverError).data
+      : undefined,
+  serverOutdated:
+    serverError?.kind === 'server_outdated'
+      ? serverOutdatedSchema.safeParse(serverError).data
+      : undefined,
+});
+
 /**
  * Constructs a {@link ComposeError} from an HTTP error response, extracting
  * structured error details from the response body when available.
@@ -191,6 +300,7 @@ export const errorFromHttpResponse = (
 ): ComposeError => {
   const parsed = tryParseErrorBody(body);
   const serverError = parsed?.error;
+  const { sdkOutdated, serverOutdated } = readVersionSlots(serverError);
 
   return new ComposeError(
     STATUS_TO_CODE.get(status) ??
@@ -199,7 +309,8 @@ export const errorFromHttpResponse = (
     {
       status,
       url,
-      kind: serverError?.kind as ComposeErrorKind | undefined,
+      kind: serverError?.kind as
+        ComposeErrorKind | ComposeRouteErrorKind | undefined,
       path: serverError?.path,
       details: serverError?.details,
       // The wire schema types `kind` as a bare string; the server only ever
@@ -209,6 +320,8 @@ export const errorFromHttpResponse = (
         kind: op.kind as GenericComposeErrorKind,
       })),
       succeededOps: serverError?.succeededOps,
+      sdkOutdated,
+      serverOutdated,
     },
   );
 };

package/src/examples/flySwap.ts

@@ -54,14 +54,14 @@ const WETH = '0x4200000000000000000000000000000000000006';
  * 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
+ * response publishes as the output's `amount.minimum`, so a wider band
  * 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
+ * Fly's own `slippage` parameter does is price its minimum-out floor, 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
@@ -137,7 +137,7 @@ export const buildFlySwapExample = (): {
   //
   // 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
+  // `guard_error`. The published `amount.minimum` is the op's, derived from the
   // bottom of the input band.
   builder.fly.swap('swapAllToWeth', {
     bind: { amountIn: exitPt.amountOut },

package/src/examples/lifiZapAsync.ts

@@ -21,15 +21,16 @@ export interface LifiZapAsyncInput {
  * - `lifi.zapAsync`, the future-availability sibling of `lifi.zap`
  * - Binding the required `recipient` input (the async op has no optional
  *   recipient — the decl is non-optional, so `bind.recipient` is mandatory)
- * - Omitting `sweepTo`: `availability: 'future'` governs custody, so the
+ * - Omitting `sweepTo`: a future delivery governs custody, so the
  *   output is delivered externally and never enters the execution VM — a
  *   sweep would find nothing to move (custody, not amount reporting)
- * - Amount reporting is unaffected by availability: when the async lowering
- *   binds a terminal handle the output still reports `simulated.amountOut`,
- *   the protocol's in-transaction expected value (an estimate; the delivered
- *   amount arrives after settlement). `simulated.amountOutMin` appears only
- *   when a minimum source exists — for a future output that means a floor the
- *   edge lowering itself reported, never a user guard
+ * - Amount reporting is unaffected by delivery timing: when the async lowering
+ *   binds a terminal handle the output still reports an `amount.estimate`
+ *   (`basis: 'simulated'`), the protocol's in-transaction expected value (the
+ *   delivered amount arrives after settlement, when `delivery.when` is
+ *   `'future'`). An `amount.minimum` appears only when a minimum source
+ *   exists — for a future output that means a floor the edge lowering itself
+ *   reported, never a user guard
  * - No output guards: the reported value is the initiating-transaction
  *   estimate, not the asynchronously delivered amount a guard could enforce,
  *   so `amountOut` is excluded from the generated `TypedGuard` union

package/src/examples/run.ts

@@ -43,6 +43,7 @@ import type {
   ComposeRouteRequest,
 } from '@lifi/compose-spec';
 
+import { bigintReplacer } from '../client.js';
 import { type ComposeSdk, createComposeSdk } from '../sdk.js';
 
 import { buildAaveRepay } from './aaveRepay.js';
@@ -76,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({
@@ -233,14 +237,7 @@ const run = async () => {
   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
@@ -248,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/swapAndZap.ts

@@ -20,6 +20,13 @@ const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
  * - Chaining a swap into a zap by threading output handles
  * - The swap's amountOut feeds directly into the zap's amountIn
  * - Slippage guard on the zap output (swap output has providesMinimum)
+ *
+ * Reading the result of compiling this flow:
+ * - `result.outputs['swap.amountOut']` has `role: 'consumed'` (the zap consumes
+ *   it); `consumedBy` is `'zap'` and `amount.minimum` is the swap floor the
+ *   router enforces on the intermediate USDC.
+ * - `result.outputs['zap.amountOut']` has `role: 'terminal'`; its
+ *   `amount.minimum` carries the guard floor set above.
  */
 export const buildSwapAndZapExample = (): {
   flow: Flow;