@lifi/composer-sdk 0.4.1 → 0.5.0

package/src/authoring/FlowBuilderCore.ts

@@ -1,9 +1,9 @@
 import type {
   AppliedGuard,
+  BindValue,
   Call,
   Flow,
   FlowInput,
-  Ref,
   Resource,
   SolType,
 } from '@lifi/compose-spec';
@@ -13,6 +13,7 @@ import type {
   InputSchema,
   OutputKind,
   TypedGuard,
+  TypedLiteral,
   TypedRef,
 } from '../types.js';
 
@@ -21,7 +22,7 @@ import type {
   OutputHandle,
   ResourceInputHandle,
 } from './handles.js';
-import { handleToRef } from './handles.js';
+import { toBindValue } from './handles.js';
 import { ref } from './raw.js';
 
 /**
@@ -37,17 +38,14 @@ export interface CallArgs {
 }
 
 /**
- * Any value that can be bound to an operation parameter: an input handle,
- * an output handle from a previous operation, or a typed `$ref` pointer.
+ * Any value that can be bound to an operation parameter: an input handle, an
+ * output handle from a previous operation, a typed `$ref` pointer, or a typed
+ * literal.
  *
- * Use `raw.ref<T>()` to create a typed ref from a raw path string.
+ * Use `raw.ref<T>()` to create a typed ref from a raw path string, and
+ * `raw.literal<T>()` to bake in a constant.
  */
-export type AnyBindable = InputHandle | OutputHandle | TypedRef;
-
-const toRef = (bindable: AnyBindable): Ref => {
-  if ('_tag' in bindable) return handleToRef(bindable);
-  return bindable;
-};
+export type AnyBindable = InputHandle | OutputHandle | TypedRef | TypedLiteral;
 
 /**
  * Provides references to runtime context values available inside a flow.
@@ -127,7 +125,7 @@ export interface FlowBuilderCore<T extends InputSchema = InputSchema> {
     id: string,
     op: string,
     args: {
-      readonly bind: Record<string, Ref>;
+      readonly bind: Record<string, BindValue>;
       readonly config: Record<string, unknown>;
       readonly guards?: readonly AppliedGuard[];
     },
@@ -196,9 +194,9 @@ export const createFlowBuilderCore = <T extends InputSchema>(
     if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
     nodeIds.add(nodeId);
 
-    const bind: Record<string, Ref> = {};
+    const bind: Record<string, BindValue> = {};
     for (const [key, val] of Object.entries(args.bind)) {
-      bind[key] = toRef(val);
+      bind[key] = toBindValue(val);
     }
 
     const node: Call = {
@@ -230,7 +228,7 @@ export const createFlowBuilderCore = <T extends InputSchema>(
     nodeId: string,
     op: string,
     args: {
-      readonly bind: Record<string, Ref>;
+      readonly bind: Record<string, BindValue>;
       readonly config: Record<string, unknown>;
       readonly guards?: readonly AppliedGuard[];
     },

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.
@@ -39,6 +39,40 @@ 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

@@ -9,7 +9,11 @@ import type {
   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,
@@ -55,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.
    *
@@ -75,9 +101,9 @@ export interface ComposeClient {
    * `POST /compose/route`.
    *
    * A convenience path that skips flow authoring: the server builds a one-node
-   * `lifi.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
+   * 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}.
    *
@@ -88,6 +114,13 @@ export interface ComposeClient {
    * 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.
    *
@@ -149,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)) {
@@ -164,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 };
 };
 
@@ -184,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 };
 };
 
@@ -240,6 +336,29 @@ const postCompile = async (
   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.
  *
@@ -272,24 +391,11 @@ export const createComposeClient = (
   };
   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,
@@ -312,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 (
@@ -358,5 +452,5 @@ export const createComposeClient = (
     throw errorFromHttpResponse(res.status, body, url);
   };
 
-  return { getManifest, compile, route, 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.