@lifi/composer-sdk 0.4.0 → 0.5.0

package/src/authoring/handles.ts

@@ -1,6 +1,11 @@
-import type { Resource, StaticSolType } from '@lifi/compose-spec';
+import type {
+  BindValue,
+  Resource,
+  SolType,
+  StaticSolType,
+} from '@lifi/compose-spec';
 
-import type { OutputKind, TypedRef } from '../types.js';
+import type { OutputKind, TypedLiteral, TypedRef } from '../types.js';
 
 /**
  * A handle referencing a flow input declared in the flow's input schema.
@@ -75,16 +80,47 @@ type SlotAssignable<T extends OutputKind> = T extends 'bytes32'
     : T;
 
 /**
- * The set of values accepted by a typed bind slot.
+ * The values accepted by a typed slot that must resolve to a `$ref`:
  * - `OutputHandle<T>` / `InputHandle<T>` (same type)
  * - For `'uint256'` slots, also `'resource'`-tagged handles
  * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)
  * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)
  *
- * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`
+ * Plain `{ $ref: '...' }` objects are **not** accepted - use `raw.ref<T>()`
  * to create a typed ref when you need to reference a raw path.
  */
-export type Bindable<T extends OutputKind> =
+export type RefBindable<T extends OutputKind> =
   | OutputHandle<SlotAssignable<T>>
   | InputHandle<SlotAssignable<T>>
   | TypedRef<SlotAssignable<T>>;
+
+/**
+ * Any ref-resolving bindable, with no per-slot type constraint.
+ */
+export type AnyRefBindable = InputHandle | OutputHandle | TypedRef;
+
+/**
+ * The set of values accepted by a typed operation bind slot: everything
+ * {@link RefBindable} accepts, plus a {@link TypedLiteral} constant baked
+ * into the flow document. A `'resource'` slot rejects a literal: a token
+ * resource is not a scalar constant.
+ *
+ * Use `raw.literal<T>()` to create one.
+ */
+export type Bindable<T extends OutputKind> =
+  RefBindable<T> | LiteralBindable<SlotAssignable<T>>;
+
+// Distributes over the slot's assignable kinds and keeps the scalar ones: a
+// `'resource'` slot has no scalar arm, so its literal arm collapses to
+// `never` and a literal is rejected outright.
+type LiteralBindable<K extends OutputKind> = K extends SolType
+  ? TypedLiteral<K>
+  : never;
+
+/**
+ * Converts a bindable to the wire `bind` value it denotes: handles become
+ * `$ref` pointers, refs and literals pass through as-is.
+ */
+export const toBindValue = (
+  bindable: InputHandle | OutputHandle | TypedRef | TypedLiteral,
+): BindValue => ('_tag' in bindable ? handleToRef(bindable) : bindable);

package/src/authoring/raw.ts

@@ -1,6 +1,6 @@
-import type { AppliedGuard } from '@lifi/compose-spec';
+import type { AppliedGuard, SolType } from '@lifi/compose-spec';
 
-import type { OutputKind, TypedRef } from '../types.js';
+import type { OutputKind, TypedLiteral, TypedRef } from '../types.js';
 
 /**
  * Creates a typed `$ref` pointer for use in bind slots.
@@ -35,8 +35,43 @@ import type { OutputKind, TypedRef } from '../types.js';
  * });
  * ```
  */
-export const ref = <T extends OutputKind>(path: string): TypedRef<T> =>
-  ({ $ref: path }) as TypedRef<T>;
+export const ref = <T extends OutputKind>(path: string): TypedRef<T> => ({
+  $ref: path,
+});
+
+/**
+ * Creates a typed literal for use in bind slots: a constant baked into the
+ * flow document rather than supplied at run time.
+ *
+ * Prefer a declared flow input and `builder.inputs.<name>` — a value the
+ * caller supplies per run stays out of the document. Use a literal when the
+ * flow has no run of its own to take the value from: the `continuationFlow`
+ * of a `continuation.settle` node is stored by the settlement backend and
+ * re-run later against the deferred proceeds, so its delivery address has to
+ * be part of the committed document.
+ *
+ * @typeParam T - The Solidity type of the literal (e.g. `'address'`).
+ * @param kind - The literal's Solidity type.
+ * @param value - The literal value, as the wire format carries it: a string.
+ * @returns A {@link TypedLiteral} accepted by `Bindable<T>` slots matching `T`.
+ *
+ * @example
+ * ```ts
+ * import { raw } from '@lifi/composer-sdk';
+ *
+ * builder.core.transfer('deliver', {
+ *   bind: {
+ *     amount: zap.amountOut,
+ *     recipient: raw.literal('address', '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'),
+ *   },
+ *   config: {},
+ * });
+ * ```
+ */
+export const literal = <T extends SolType>(
+  kind: T,
+  value: string,
+): TypedLiteral<T> => ({ kind, value });
 
 /**
  * Creates a raw guard object for use in the `guards` array of an operation call.

package/src/authoring/signatureArgs.ts

@@ -3,32 +3,36 @@ import { type ParseAbiItem, parseAbiItem } from 'abitype';
 
 import type { AbiTypeToOutputKind, TypedGuard } from '../types.js';
 
-import type { AnyBindable, CallArgs } from './FlowBuilderCore.js';
-import type { Bindable, OutputHandle } from './handles.js';
+import type { CallArgs } from './FlowBuilderCore.js';
+import type { AnyRefBindable, OutputHandle, RefBindable } from './handles.js';
 import { handleToRef } from './handles.js';
 
 /**
  * Type-level extraction of named bind keys from a function signature string.
  * When `TSig` is a string literal matching a Solidity function signature,
  * resolves to a record whose keys are the parameter names and values are
- * `Bindable<kind>` where the kind is derived from each parameter's Solidity
+ * `RefBindable<kind>` where the kind is derived from each parameter's Solidity
  * type via `AbiTypeToOutputKind`. For recognised `SolType` parameters
  * (e.g. `uint256`, `address`, `uint128`) the bind slot is precisely typed;
  * for other Solidity types (e.g. tuples) the slot accepts any scalar handle.
- * Falls back to `Record<string, AnyBindable>` for non-literal strings.
+ * Falls back to `Record<string, AnyRefBindable>` for non-literal strings.
+ *
+ * These slots are lowered into `config.args`, which is positional calldata
+ * rather than a node `bind` record, so a literal is not accepted here: only
+ * values that resolve to a `$ref`.
  */
 export type SignatureBind<TSig extends string> = string extends TSig
-  ? Record<string, AnyBindable>
+  ? Record<string, AnyRefBindable>
   : ParseAbiItem<TSig> extends {
         type: 'function';
         inputs: infer I extends readonly { name: string; type: string }[];
       }
     ? {
-        readonly [P in I[number] as P['name']]: Bindable<
+        readonly [P in I[number] as P['name']]: RefBindable<
           AbiTypeToOutputKind<P['type']>
         >;
       }
-    : Record<string, AnyBindable>;
+    : Record<string, AnyRefBindable>;
 
 // ---------------------------------------------------------------------------
 // Return-type inference from function signatures
@@ -126,18 +130,18 @@ export const parseFunctionParams = (functionSignature: string): string[] => {
 };
 
 /**
- * Converts any `AnyBindable` to a `Ref` (`{ $ref: string }`).
+ * Converts a ref-resolving bindable to a `Ref` (`{ $ref: string }`).
  * Handles carry a `_tag` property and are converted via `handleToRef`;
  * `Ref` objects pass through as-is.
  */
-export const toBindRef = (bindable: AnyBindable): Ref => {
+export const toBindRef = (bindable: AnyRefBindable): Ref => {
   if ('_tag' in bindable) return handleToRef(bindable);
   return bindable;
 };
 
 export interface BuildCallWireFormatInput {
-  readonly resource?: AnyBindable;
-  readonly bind: Record<string, AnyBindable>;
+  readonly resource?: AnyRefBindable;
+  readonly bind: Record<string, AnyRefBindable>;
   readonly config: Record<string, unknown>;
   readonly guards?: readonly TypedGuard[];
 }
@@ -155,7 +159,7 @@ export interface CallWireResult {
  */
 const resolvePositionalArgs = (
   label: string,
-  bind: Record<string, AnyBindable>,
+  bind: Record<string, AnyRefBindable>,
   config: Record<string, unknown>,
 ): Ref[] => {
   const functionSignature = config.functionSignature;
@@ -222,7 +226,7 @@ export const buildCallWireFormat = (
 };
 
 export interface BuildStaticCallWireFormatInput {
-  readonly bind: Record<string, AnyBindable>;
+  readonly bind: Record<string, AnyRefBindable>;
   readonly config: Record<string, unknown>;
   readonly guards?: readonly TypedGuard[];
 }

package/src/client.ts

@@ -4,11 +4,16 @@ import type {
   ComposeCompileResult,
   ComposeCompileSuccessData,
   ComposeManifest,
+  ComposeRouteRequest,
   SimulateRequest,
   SimulateResult,
 } from '@lifi/compose-spec';
 
-import type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';
+import type {
+  ChainSummary,
+  GetZapPacksOptions,
+  ZapPackOverview,
+} from './discovery.js';
 import { ComposeError, errorFromHttpResponse } from './errors.js';
 import {
   parseCompilePartialEnvelope,
@@ -54,6 +59,28 @@ export interface ComposeClient {
    * @throws {@link ComposeError} on network, validation, or server errors.
    */
   readonly getManifest: () => Promise<ComposeManifest>;
+  /**
+   * Fetches the chains the Compose API supports, ascending by `chainId`.
+   *
+   * A chain is listed once the server confirms the VM contract is deployed on
+   * it — the same condition {@link compile}, {@link route} and
+   * {@link simulate} validate against. A chain absent from this list is
+   * rejected outright by those endpoints.
+   *
+   * The converse does not hold: a listed chain can still have no routing edge
+   * for a given token pair, which {@link route} reports as `no_route_error`.
+   * Use {@link getZapPacks} to enumerate the pairs that do route.
+   *
+   * Each entry carries a display `name` alongside its `chainId`. The name is a
+   * deployment-maintained label — render it, but key on `chainId`.
+   *
+   * The list tracks the server's chain registry, which refreshes periodically.
+   * Results are not cached by the SDK; callers should cache as appropriate.
+   *
+   * @returns The supported chains, ascending by `chainId`.
+   * @throws {@link ComposeError} on network or server errors.
+   */
+  readonly getChains: () => Promise<readonly ChainSummary[]>;
   /**
    * Submits a compile request and returns the result.
    *
@@ -69,6 +96,45 @@ export interface ComposeClient {
   readonly compile: (
     request: ComposeCompileRequest,
   ) => Promise<ComposeCompileResult>;
+  /**
+   * Compiles a token pair into a submit-ready transaction via
+   * `POST /compose/route`.
+   *
+   * A convenience path that skips flow authoring: the server builds a one-node
+   * zap flow with a `directDeposit` input from the `fromToken` / `toToken`
+   * pair and runs it through the same pipeline as {@link compile}. The
+   * response is therefore the same discriminated result — HTTP 206 under
+   * `simulationPolicy: 'allow-revert'` yields `status: 'partial'` rather than
+   * throwing, exactly as it does for {@link compile}.
+   *
+   * As of today that flow is a single zap step: one edge of the backend's
+   * routing catalog (a position entry or exit, a wrap or unwrap, a mint or
+   * burn). Enumerate the pairs it covers with {@link getZapPacks}; a pair with
+   * no edge is rejected with `kind: 'no_route_error'`. The endpoint is meant to
+   * author richer flows later, so the single-step limit is the current state of
+   * 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
+   * `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.
+   *
+   * Use {@link compile} for what the server does not author for you: several
+   * chained operations, splits, explicit preconditions, or per-op guards.
+   *
+   * `bigint` amounts in `amount` are serialised to decimal strings
+   * automatically.
+   *
+   * @param request - The from/to token pair, amount, signer, and route options.
+   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.
+   * @throws {@link ComposeError} on network, validation, or server errors —
+   *   including `NOT_FOUND` (HTTP 404) when no catalog edge covers the pair.
+   */
+  readonly route: (
+    request: ComposeRouteRequest,
+  ) => Promise<ComposeCompileResult>;
   /**
    * Fetches the available routing edges grouped by protocol.
    *
@@ -116,6 +182,67 @@ const bigintReplacer = (_key: string, value: unknown): unknown =>
 const isNonNullObject = (v: unknown): v is Record<string, unknown> =>
   typeof v === 'object' && v !== null;
 
+// 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 => {
+  if (typeof value !== 'string' || !INTEGER_STRING.test(value)) {
+    throw new ComposeError(
+      'UNKNOWN_ERROR',
+      `Malformed compose response: producedResources.${key}.simulated.${field} is ${
+        value === undefined ? 'absent' : 'not an integer string'
+      }`,
+      { url },
+    );
+  }
+  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',
+      url,
+    );
+    if (simulated.amountOutMin !== undefined) {
+      simulated.amountOutMin = decodeAmount(
+        simulated.amountOutMin,
+        key,
+        'amountOutMin',
+        url,
+      );
+    }
+  }
+};
+
 const parseBody = async <T>(res: Response, url: string): Promise<T> => {
   const body = await res.json().catch((_) => null);
   if (!isNonNullObject(body) || !('data' in body)) {
@@ -131,6 +258,7 @@ const parseCompileSuccessBody = async (
   url: string,
 ): Promise<ComposeCompileResult> => {
   const data = await parseBody<ComposeCompileSuccessData>(res, url);
+  decodeSimulatedAmounts(data, url);
   return { ...data, status: 'success' as const };
 };
 
@@ -151,6 +279,7 @@ const parsePartialBody = async (
   // 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);
   return { ...data, status: 'partial' as const, error: envelope.error };
 };
 
@@ -173,6 +302,62 @@ const parseSimulateBody = async (
   }
   return result;
 };
+// `POST /compose` and `POST /compose/route` differ only in path and request
+// shape: both return the enveloped success data on 200 and the partial
+// envelope on 206, so they share one transport.
+type ComposeTransport = {
+  readonly fetchFn: typeof fetch;
+  readonly baseHeaders: Record<string, string>;
+};
+
+const postCompile = async (
+  { fetchFn, baseHeaders }: ComposeTransport,
+  url: string,
+  request: ComposeCompileRequest | ComposeRouteRequest,
+): Promise<ComposeCompileResult> => {
+  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 });
+  }
+  if (res.status === 206) {
+    return await parsePartialBody(res, url);
+  }
+  if (!res.ok) {
+    const body = await res.text();
+    throw errorFromHttpResponse(res.status, body, url);
+  }
+  return await parseCompileSuccessBody(res, url);
+};
+
+// 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,
+  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 });
+  }
+  if (!res.ok) {
+    const body = await res.text();
+    throw errorFromHttpResponse(res.status, body, url);
+  }
+  return await parseBody<T>(res, url);
+};
 
 /**
  * Creates a low-level Compose API client.
@@ -204,50 +389,23 @@ export const createComposeClient = (
     'x-lifi-composer-sdk': SDK_VERSION,
     'x-lifi-api-key': trimmedApiKey,
   };
+  const transport: ComposeTransport = { fetchFn, baseHeaders };
 
-  const getManifest = async (): Promise<ComposeManifest> => {
-    const url = `${base}/compose/manifest`;
-    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 });
-    }
-    if (!res.ok) {
-      const body = await res.text();
-      throw errorFromHttpResponse(res.status, body, url);
-    }
-    return await parseBody<ComposeManifest>(res, url);
-  };
+  const getManifest = async (): Promise<ComposeManifest> =>
+    getJson<ComposeManifest>(transport, `${base}/compose/manifest`);
+
+  const getChains = async (): Promise<readonly ChainSummary[]> =>
+    getJson<readonly ChainSummary[]>(transport, `${base}/chains`);
 
   const compile = async (
     request: ComposeCompileRequest,
-  ): Promise<ComposeCompileResult> => {
-    const url = `${base}/compose`;
-    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 });
-    }
-    if (res.status === 206) {
-      return await parsePartialBody(res, url);
-    }
-    if (!res.ok) {
-      const body = await res.text();
-      throw errorFromHttpResponse(res.status, body, url);
-    }
-    return await parseCompileSuccessBody(res, url);
-  };
+  ): Promise<ComposeCompileResult> =>
+    postCompile(transport, `${base}/compose`, request);
+
+  const route = async (
+    request: ComposeRouteRequest,
+  ): Promise<ComposeCompileResult> =>
+    postCompile(transport, `${base}/compose/route`, request);
 
   const getZapPacks = async (
     options?: GetZapPacksOptions,
@@ -260,22 +418,10 @@ export const createComposeClient = (
       params.set('protocols', list);
     }
     const qs = params.toString();
-    const url = `${base}/compose/zap-packs${qs ? `?${qs}` : ''}`;
-    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 });
-    }
-    if (!res.ok) {
-      const body = await res.text();
-      throw errorFromHttpResponse(res.status, body, url);
-    }
-    return await parseBody<readonly ZapPackOverview[]>(res, url);
+    return getJson<readonly ZapPackOverview[]>(
+      transport,
+      `${base}/compose/zap-packs${qs ? `?${qs}` : ''}`,
+    );
   };
 
   const simulate = async (
@@ -306,5 +452,5 @@ export const createComposeClient = (
     throw errorFromHttpResponse(res.status, body, url);
   };
 
-  return { getManifest, compile, getZapPacks, simulate };
+  return { getManifest, getChains, compile, route, getZapPacks, simulate };
 };

package/src/discovery.ts

@@ -1,5 +1,5 @@
 /**
- * Types for the Compose discovery API (`GET /compose/zap-packs`).
+ * Types for the Compose discovery API (`GET /compose/zap-packs`, `GET /chains`).
  *
  * These are SDK-facing presentation types — not part of the core compile
  * contract in compose-spec. The backend response is the source of truth;
@@ -11,6 +11,23 @@
  * `"enter-position"`, `"exit-position"`, `"wrap"`, `"unwrap"`, `"mint"`, `"burn"`.
  */
 
+/**
+ * A chain the Compose deployment supports.
+ */
+export interface ChainSummary {
+  /** EVM chain ID. The stable identifier — key on this. */
+  readonly chainId: number;
+  /**
+   * Human-readable label, suitable for display in a chain selector.
+   *
+   * Maintained by the deployment rather than derived from canonical chain
+   * branding, so it can differ from a chain's marketed name and can change
+   * without notice. Never treat it as an identifier, and never match on it.
+   * A chain the deployment has no configured label for reports `Chain <id>`.
+   */
+  readonly name: string;
+}
+
 /**
  * A single routing edge representing a supported token-to-token path
  * through a DeFi protocol.
@@ -26,6 +43,19 @@ export interface ZapPackEdge {
   readonly inAmountMin?: string;
   /** Maximum input amount accepted (stringified integer), if constrained. */
   readonly inAmountMax?: string;
+  /**
+   * Recipient binding obligation. `"required"` means the zap must bind its
+   * `recipient` input. The output is externally owned, terminal, and unswept.
+   * The loose string type preserves forward compatibility with new values.
+   */
+  readonly recipient?: string;
+  /**
+   * Output availability. `"future"` means the output becomes available only
+   * after the initiating transaction settles; route via `lifi.zapAsync` with
+   * a bound recipient. Absent means the output is available synchronously.
+   * The loose string type preserves forward compatibility with new values.
+   */
+  readonly availability?: string;
 }
 
 /**