@lifi/composer-sdk 0.10.0 → 0.12.0

package/dist/sdk.js

@@ -24,7 +24,6 @@ const createComposeSdk = (options) => {
 			signer: run.signer,
 			assumptions: run.assumptions,
 			referrer: run.referrer,
-			integratorFeeBps: run.integratorFeeBps,
 			maxPriceImpactBps: run.maxPriceImpactBps,
 			sweepTo: run.sweepTo,
 			simulationPolicy: run.simulationPolicy,

package/dist/sdk.js.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.js","names":[],"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeRouteRequest,\n  InputSpec,\n  SimulateRequest,\n  SimulateResult,\n} from '@lifi/compose-spec';\n\nimport {\n  createFlowBuilderCore,\n  type FlowBuilderCore,\n  type FlowOptions,\n  type TypedFlow,\n} from './authoring/FlowBuilderCore.js';\nimport { type ComposeClient, createComposeClient } from './client.js';\nimport type { ChainSummary } from './discovery.js';\nimport {\n  bindGeneratedOps,\n  type GeneratedOps,\n} from './generated/operations.generated.js';\nimport { buildRun, type ComposeRunInput } from './run/inputs.js';\nimport type { InputSchema } from './types.js';\n\nexport type { ComposeRunInput };\n\n/**\n * A flow builder augmented with generated operation methods and a `compile` method\n * that submits the flow to the Compose backend for compilation.\n *\n * Created via {@link ComposeSdk.flow}.\n *\n * @typeParam T - The input schema describing the flow's required inputs.\n */\nexport type FlowBuilder<T extends InputSchema = InputSchema> =\n  FlowBuilderCore<T> &\n    GeneratedOps & {\n      /**\n       * Builds the flow document from the current builder state and submits it\n       * to the Compose API for compilation.\n       *\n       * @param run - Runtime inputs, preconditions, and signer address.\n       * @returns The compiled transaction calldata and metadata.\n       * @throws {@link ComposeError} on network, validation, or server errors.\n       *\n       * @example\n       * ```ts\n       * const result = await builder.compile({\n       *   inputs: { token: materialisers.balanceOf({}) },\n       *   signer: '0xYourAddress...',\n       * });\n       * console.log(result.calldata);\n       * ```\n       */\n      readonly compile: (\n        run: ComposeRunInput<T>,\n      ) => Promise<ComposeCompileResult>;\n    };\n\n/**\n * Configuration for creating a Compose SDK instance.\n */\nexport interface ComposeSdkOptions {\n  /** Base URL of the Compose API (e.g. `\"https://li.quest\"`). */\n  readonly baseUrl: string;\n  /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */\n  readonly fetch?: typeof globalThis.fetch;\n  /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */\n  readonly apiKey: string;\n}\n\n/**\n * The top-level Compose SDK interface.\n *\n * Provides methods to build flows, compile them into executable calldata, and\n * interact with the Compose API directly.\n *\n * @example\n * ```ts\n * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';\n *\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n *\n * const builder = sdk.flow(1, {\n *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },\n * });\n *\n * builder.lifi.swap('swap1', {\n *   bind: { amountIn: builder.inputs.usdc },\n *   config: { resourceOut: resources.native(1) },\n * });\n *\n * const result = await builder.compile({\n *   inputs: { usdc: materialisers.balanceOf({}) },\n *   signer: '0xYourAddress...',\n * });\n * ```\n */\nexport interface ComposeSdk {\n  /** Low-level HTTP client for the Compose API. */\n  readonly client: ComposeClient;\n  /**\n   * Creates a new flow builder targeting the given chain.\n   * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).\n   * @param options - Flow configuration including input declarations.\n   * @returns A {@link FlowBuilder} with generated operation methods and a `compile` method.\n   * @throws Error if any resource input's `chainId` doesn't match the flow's `chainId`.\n   */\n  readonly flow: <T extends InputSchema>(\n    chainId: number,\n    options: FlowOptions<T>,\n  ) => FlowBuilder<T>;\n  /**\n   * Fetches the chains this Compose deployment supports, ascending by\n   * `chainId`. Thin pass-through to {@link ComposeClient.getChains}; see it\n   * for what \"supported\" means and for the caching caveat.\n   *\n   * Each entry pairs the `chainId` with a display `name`, so one call both\n   * gates a chain selector and labels it. Key on `chainId`; `name` is a\n   * deployment-maintained label that can change.\n   *\n   * Use it to fail fast before building a flow for a chain the server would\n   * reject.\n   *\n   * @returns The supported chains, ascending by `chainId`.\n   * @throws {@link ComposeError} on network or server errors.\n   *\n   * @example\n   * ```ts\n   * const chains = await sdk.getSupportedChains();\n   * if (!chains.some((c) => c.chainId === 8453)) {\n   *   throw new Error('Base is not supported');\n   * }\n   * for (const { chainId, name } of chains) {\n   *   console.log(`${name} (${chainId})`);\n   * }\n   * ```\n   */\n  readonly getSupportedChains: () => Promise<readonly ChainSummary[]>;\n  /**\n   * Builds a raw compile request without sending it. Useful for inspecting the\n   * request payload or submitting it through a custom transport.\n   * @param flow - A built flow document (from `builder.build()`).\n   * @param run - Runtime inputs, preconditions, and signer address.\n   * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.\n   */\n  readonly request: <T extends InputSchema>(\n    flow: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ) => ComposeCompileRequest;\n  /**\n   * Compiles a token pair on one chain into a submit-ready transaction. Thin\n   * pass-through to {@link ComposeClient.route}; see it for the short chain of\n   * catalog edges the server plans, when to prefer `flow(...).compile(...)`,\n   * the `success` / `partial` discrimination, and error behaviour. Build the\n   * `amount` with `routeAmount.exact(...)` / `routeAmount.all(...)`.\n   *\n   * @param request - The from/to token pair, amount, signer, and route options.\n   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly route: (\n    request: ComposeRouteRequest,\n  ) => Promise<ComposeCompileResult>;\n  /**\n   * Simulates a raw, pre-encoded transaction. Thin pass-through to\n   * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`\n   * result discrimination and error behaviour. Pair with `buildSimulateRequest`\n   * to assemble the request from a compile result.\n   *\n   * @param request - The raw transaction plus funding `requirements` and\n   *   `trackedBalances`.\n   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;\n}\n\n/**\n * Creates a new Compose SDK instance.\n *\n * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.\n * @returns A {@link ComposeSdk} instance.\n *\n * @example\n * ```ts\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n * ```\n */\nexport const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {\n  const composeClient = createComposeClient(options);\n\n  const request = <T extends InputSchema>(\n    flowDoc: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ): ComposeCompileRequest => ({\n    flow: flowDoc,\n    run: buildRun({\n      inputs: run.inputs as Record<string, InputSpec>,\n      preconditions: run.preconditions,\n      signer: run.signer,\n      assumptions: run.assumptions as Record<string, bigint> | undefined,\n      referrer: run.referrer,\n      integratorFeeBps: run.integratorFeeBps,\n      maxPriceImpactBps: run.maxPriceImpactBps,\n      sweepTo: run.sweepTo,\n      simulationPolicy: run.simulationPolicy,\n      simulateUserProgram: run.simulateUserProgram,\n      checkOnChainAllowances: run.checkOnChainAllowances,\n    }),\n  });\n\n  const flow = <T extends InputSchema>(\n    chainId: number,\n    opts: FlowOptions<T>,\n  ): FlowBuilder<T> => {\n    const core = createFlowBuilderCore(chainId, opts);\n    const builder = Object.assign(core, bindGeneratedOps(core));\n\n    const compile = async (\n      run: ComposeRunInput<T>,\n    ): Promise<ComposeCompileResult> => {\n      const flowDoc = builder.build();\n      const req = request(flowDoc, run);\n      return composeClient.compile(req);\n    };\n\n    return Object.assign(builder, { compile });\n  };\n\n  return {\n    client: composeClient,\n    flow,\n    getSupportedChains: composeClient.getChains,\n    request,\n    route: composeClient.route,\n    simulate: composeClient.simulate,\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;AA6LA,MAAa,oBAAoB,YAA2C;CAC1E,MAAM,gBAAgB,oBAAoB,OAAO;CAEjD,MAAM,WACJ,SACA,SAC2B;EAC3B,MAAM;EACN,KAAK,SAAS;GACZ,QAAQ,IAAI;GACZ,eAAe,IAAI;GACnB,QAAQ,IAAI;GACZ,aAAa,IAAI;GACjB,UAAU,IAAI;GACd,kBAAkB,IAAI;GACtB,mBAAmB,IAAI;GACvB,SAAS,IAAI;GACb,kBAAkB,IAAI;GACtB,qBAAqB,IAAI;GACzB,wBAAwB,IAAI;EAC9B,CAAC;CACH;CAEA,MAAM,QACJ,SACA,SACmB;EACnB,MAAM,OAAO,sBAAsB,SAAS,IAAI;EAChD,MAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,IAAI,CAAC;EAE1D,MAAM,UAAU,OACd,QACkC;GAClC,MAAM,UAAU,QAAQ,MAAM;GAC9B,MAAM,MAAM,QAAQ,SAAS,GAAG;GAChC,OAAO,cAAc,QAAQ,GAAG;EAClC;EAEA,OAAO,OAAO,OAAO,SAAS,EAAE,QAAQ,CAAC;CAC3C;CAEA,OAAO;EACL,QAAQ;EACR;EACA,oBAAoB,cAAc;EAClC;EACA,OAAO,cAAc;EACrB,UAAU,cAAc;CAC1B;AACF"}
+{"version":3,"file":"sdk.js","names":[],"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  ComposeRouteRequest,\n  InputSpec,\n  SimulateRequest,\n  SimulateResult,\n} from '@lifi/compose-spec';\n\nimport {\n  createFlowBuilderCore,\n  type FlowBuilderCore,\n  type FlowOptions,\n  type TypedFlow,\n} from './authoring/FlowBuilderCore.js';\nimport { type ComposeClient, createComposeClient } from './client.js';\nimport type { ChainSummary } from './discovery.js';\nimport {\n  bindGeneratedOps,\n  type GeneratedOps,\n} from './generated/operations.generated.js';\nimport { buildRun, type ComposeRunInput } from './run/inputs.js';\nimport type { InputSchema } from './types.js';\n\nexport type { ComposeRunInput };\n\n/**\n * A flow builder augmented with generated operation methods and a `compile` method\n * that submits the flow to the Compose backend for compilation.\n *\n * Created via {@link ComposeSdk.flow}.\n *\n * @typeParam T - The input schema describing the flow's required inputs.\n */\nexport type FlowBuilder<T extends InputSchema = InputSchema> =\n  FlowBuilderCore<T> &\n    GeneratedOps & {\n      /**\n       * Builds the flow document from the current builder state and submits it\n       * to the Compose API for compilation.\n       *\n       * @param run - Runtime inputs, preconditions, and signer address.\n       * @returns The compiled transaction calldata and metadata.\n       * @throws {@link ComposeError} on network, validation, or server errors.\n       *\n       * @example\n       * ```ts\n       * const result = await builder.compile({\n       *   inputs: { token: materialisers.balanceOf({}) },\n       *   signer: '0xYourAddress...',\n       * });\n       * console.log(result.calldata);\n       * ```\n       */\n      readonly compile: (\n        run: ComposeRunInput<T>,\n      ) => Promise<ComposeCompileResult>;\n    };\n\n/**\n * Configuration for creating a Compose SDK instance.\n */\nexport interface ComposeSdkOptions {\n  /** Base URL of the Compose API (e.g. `\"https://li.quest\"`). */\n  readonly baseUrl: string;\n  /** Optional custom `fetch` implementation. Defaults to `globalThis.fetch`. */\n  readonly fetch?: typeof globalThis.fetch;\n  /** LI.FI API key, sent as the `x-lifi-api-key` header on every request. Required — the Compose API rejects unauthenticated requests. */\n  readonly apiKey: string;\n}\n\n/**\n * The top-level Compose SDK interface.\n *\n * Provides methods to build flows, compile them into executable calldata, and\n * interact with the Compose API directly.\n *\n * @example\n * ```ts\n * import { createComposeSdk, resources, materialisers } from '@lifi/composer-sdk';\n *\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n *\n * const builder = sdk.flow(1, {\n *   inputs: { usdc: resources.erc20('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', 1) },\n * });\n *\n * builder.lifi.swap('swap1', {\n *   bind: { amountIn: builder.inputs.usdc },\n *   config: { resourceOut: resources.native(1) },\n * });\n *\n * const result = await builder.compile({\n *   inputs: { usdc: materialisers.balanceOf({}) },\n *   signer: '0xYourAddress...',\n * });\n * ```\n */\nexport interface ComposeSdk {\n  /** Low-level HTTP client for the Compose API. */\n  readonly client: ComposeClient;\n  /**\n   * Creates a new flow builder targeting the given chain.\n   * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).\n   * @param options - Flow configuration including input declarations.\n   * @returns A {@link FlowBuilder} with generated operation methods and a `compile` method.\n   * @throws Error if any resource input's `chainId` doesn't match the flow's `chainId`.\n   */\n  readonly flow: <T extends InputSchema>(\n    chainId: number,\n    options: FlowOptions<T>,\n  ) => FlowBuilder<T>;\n  /**\n   * Fetches the chains this Compose deployment supports, ascending by\n   * `chainId`. Thin pass-through to {@link ComposeClient.getChains}; see it\n   * for what \"supported\" means and for the caching caveat.\n   *\n   * Each entry pairs the `chainId` with a display `name`, so one call both\n   * gates a chain selector and labels it. Key on `chainId`; `name` is a\n   * deployment-maintained label that can change.\n   *\n   * Use it to fail fast before building a flow for a chain the server would\n   * reject.\n   *\n   * @returns The supported chains, ascending by `chainId`.\n   * @throws {@link ComposeError} on network or server errors.\n   *\n   * @example\n   * ```ts\n   * const chains = await sdk.getSupportedChains();\n   * if (!chains.some((c) => c.chainId === 8453)) {\n   *   throw new Error('Base is not supported');\n   * }\n   * for (const { chainId, name } of chains) {\n   *   console.log(`${name} (${chainId})`);\n   * }\n   * ```\n   */\n  readonly getSupportedChains: () => Promise<readonly ChainSummary[]>;\n  /**\n   * Builds a raw compile request without sending it. Useful for inspecting the\n   * request payload or submitting it through a custom transport.\n   * @param flow - A built flow document (from `builder.build()`).\n   * @param run - Runtime inputs, preconditions, and signer address.\n   * @returns A {@link ComposeCompileRequest} ready to send to the Compose API.\n   */\n  readonly request: <T extends InputSchema>(\n    flow: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ) => ComposeCompileRequest;\n  /**\n   * Compiles a token pair on one chain into a submit-ready transaction. Thin\n   * pass-through to {@link ComposeClient.route}; see it for the short chain of\n   * catalog edges the server plans, when to prefer `flow(...).compile(...)`,\n   * the `success` / `partial` discrimination, and error behaviour. Build the\n   * `amount` with `routeAmount.exact(...)` / `routeAmount.all(...)`.\n   *\n   * @param request - The from/to token pair, amount, signer, and route options.\n   * @returns A discriminated result: `status: 'success'` or `status: 'partial'`.\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly route: (\n    request: ComposeRouteRequest,\n  ) => Promise<ComposeCompileResult>;\n  /**\n   * Simulates a raw, pre-encoded transaction. Thin pass-through to\n   * {@link ComposeClient.simulate}; see it for the `ok` / `revert` / `error`\n   * result discrimination and error behaviour. Pair with `buildSimulateRequest`\n   * to assemble the request from a compile result.\n   *\n   * @param request - The raw transaction plus funding `requirements` and\n   *   `trackedBalances`.\n   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).\n   * @throws {@link ComposeError} on network, validation, or server errors.\n   */\n  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;\n}\n\n/**\n * Creates a new Compose SDK instance.\n *\n * @param options - SDK configuration including the API base URL, required API key, and optional fetch implementation.\n * @returns A {@link ComposeSdk} instance.\n *\n * @example\n * ```ts\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest', apiKey: 'YOUR_API_KEY' });\n * ```\n */\nexport const createComposeSdk = (options: ComposeSdkOptions): ComposeSdk => {\n  const composeClient = createComposeClient(options);\n\n  const request = <T extends InputSchema>(\n    flowDoc: TypedFlow<T>,\n    run: ComposeRunInput<T>,\n  ): ComposeCompileRequest => ({\n    flow: flowDoc,\n    run: buildRun({\n      inputs: run.inputs as Record<string, InputSpec>,\n      preconditions: run.preconditions,\n      signer: run.signer,\n      assumptions: run.assumptions as Record<string, bigint> | undefined,\n      referrer: run.referrer,\n      maxPriceImpactBps: run.maxPriceImpactBps,\n      sweepTo: run.sweepTo,\n      simulationPolicy: run.simulationPolicy,\n      simulateUserProgram: run.simulateUserProgram,\n      checkOnChainAllowances: run.checkOnChainAllowances,\n    }),\n  });\n\n  const flow = <T extends InputSchema>(\n    chainId: number,\n    opts: FlowOptions<T>,\n  ): FlowBuilder<T> => {\n    const core = createFlowBuilderCore(chainId, opts);\n    const builder = Object.assign(core, bindGeneratedOps(core));\n\n    const compile = async (\n      run: ComposeRunInput<T>,\n    ): Promise<ComposeCompileResult> => {\n      const flowDoc = builder.build();\n      const req = request(flowDoc, run);\n      return composeClient.compile(req);\n    };\n\n    return Object.assign(builder, { compile });\n  };\n\n  return {\n    client: composeClient,\n    flow,\n    getSupportedChains: composeClient.getChains,\n    request,\n    route: composeClient.route,\n    simulate: composeClient.simulate,\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;AA6LA,MAAa,oBAAoB,YAA2C;CAC1E,MAAM,gBAAgB,oBAAoB,OAAO;CAEjD,MAAM,WACJ,SACA,SAC2B;EAC3B,MAAM;EACN,KAAK,SAAS;GACZ,QAAQ,IAAI;GACZ,eAAe,IAAI;GACnB,QAAQ,IAAI;GACZ,aAAa,IAAI;GACjB,UAAU,IAAI;GACd,mBAAmB,IAAI;GACvB,SAAS,IAAI;GACb,kBAAkB,IAAI;GACtB,qBAAqB,IAAI;GACzB,wBAAwB,IAAI;EAC9B,CAAC;CACH;CAEA,MAAM,QACJ,SACA,SACmB;EACnB,MAAM,OAAO,sBAAsB,SAAS,IAAI;EAChD,MAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,IAAI,CAAC;EAE1D,MAAM,UAAU,OACd,QACkC;GAClC,MAAM,UAAU,QAAQ,MAAM;GAC9B,MAAM,MAAM,QAAQ,SAAS,GAAG;GAChC,OAAO,cAAc,QAAQ,GAAG;EAClC;EAEA,OAAO,OAAO,OAAO,SAAS,EAAE,QAAQ,CAAC;CAC3C;CAEA,OAAO;EACL,QAAQ;EACR;EACA,oBAAoB,cAAc;EAClC;EACA,OAAO,cAAc;EACrB,UAAU,cAAc;CAC1B;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
   "repository": {
@@ -47,7 +47,7 @@
     "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.10.0"
+    "@lifi/compose-spec": "0.12.0"
   },
   "dependencies": {
     "abitype": "^1.2.3",

package/src/authoring/raw.ts

@@ -45,24 +45,37 @@ export const ref = <T extends OutputKind>(path: string): TypedRef<T> =>
  * 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.
+ * caller supplies per run stays out of the document. Use a literal for a
+ * constant that belongs to the document itself, such as a fixed treasury
+ * address.
+ *
+ * Never use a literal for the payee of a `continuation.settle` leg
+ * (`continuationFlow`). The leg produces its outcome into its own proxy
+ * (`leg.context.executionAddress`) and names no recipient; the composer
+ * appends a settlement epilogue at commit that forwards the outcome to the
+ * provider's recipient and the residual to `refund`. A call argument inside
+ * the leg (the payee of an invoice the leg pays through `core.call`) is not
+ * that recipient and may be a literal.
+ *
+ * In a `core.call` / `core.staticCall` bind, `kind` must equal the parameter's
+ * Solidity type exactly, and `value` must encode as that type: a decimal or
+ * `0x` integer, `'true'` / `'false'`, a `0x` address (mixed case only with a
+ * valid checksum), or a `0x` hex byte string of the right length.
  *
  * @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`.
+ * @returns A {@link TypedLiteral} accepted by `Bindable<T>` slots matching `T`
+ * and by `core.call` / `core.staticCall` parameters of type `T`.
  *
  * @example
  * ```ts
  * import { raw } from '@lifi/composer-sdk';
  *
- * builder.core.transfer('deliver', {
+ * // A fixed fee to a treasury baked into the flow document.
+ * builder.core.transfer('fee', {
  *   bind: {
- *     amount: zap.amountOut,
+ *     amount: builder.inputs.fee,
  *     recipient: raw.literal('address', '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'),
  *   },
  *   config: {},

package/src/authoring/signatureArgs.ts

@@ -1,38 +1,59 @@
-import type { Ref } from '@lifi/compose-spec';
+import type { Ref, SolType } from '@lifi/compose-spec';
 import { type ParseAbiItem, parseAbiItem } from 'abitype';
 
-import type { AbiTypeToOutputKind, TypedGuard } from '../types.js';
+import type {
+  AbiTypeToOutputKind,
+  TypedGuard,
+  TypedLiteral,
+} from '../types.js';
 
 import type { CallArgs } from './FlowBuilderCore.js';
 import type { AnyRefBindable, OutputHandle, RefBindable } from './handles.js';
 import { handleToRef } from './handles.js';
 
+/**
+ * Any value a signature-derived bind slot accepts, with no per-slot type
+ * constraint: a ref-resolving bindable or a typed literal.
+ */
+type AnySignatureBindable = AnyRefBindable | TypedLiteral;
+
+// The literal arm of a signature-derived slot. A positional arg is encoded by
+// its parameter's ABI type, not by the literal's `kind`, so the kind must equal
+// that type exactly: the `bytes32` widening `Bindable<T>` applies would admit an
+// `address` literal the encoder then rejects. A parameter whose ABI type is no
+// `SolType` (a tuple, an array, `uint24`) has no literal kind to name, so its
+// slot stays ref-only.
+type SignatureLiteral<TAbiType extends string> = TAbiType extends SolType
+  ? TypedLiteral<TAbiType>
+  : never;
+
 /**
  * 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
- * `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, AnyRefBindable>` for non-literal strings.
+ * resolves to a record whose keys are the parameter names and whose values are
+ * `RefBindable<kind>`, where the kind is derived from each parameter's Solidity
+ * type via `AbiTypeToOutputKind`, or a `TypedLiteral` (`raw.literal`) of that
+ * exact Solidity type. For recognised `SolType` parameters (e.g. `uint256`,
+ * `address`, `bytes`) the slot is precisely typed; other Solidity types (e.g.
+ * tuples) accept any scalar handle and no literal.
+ * Falls back to `Record<string, AnySignatureBindable>` 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`.
+ * These slots are lowered into `config.args`, positional calldata: a ref
+ * becomes `{ $ref }` and a literal becomes its `value` string, which the
+ * backend encodes against the parameter's type.
  */
 export type SignatureBind<TSig extends string> = string extends TSig
-  ? Record<string, AnyRefBindable>
+  ? Record<string, AnySignatureBindable>
   : ParseAbiItem<TSig> extends {
         type: 'function';
         inputs: infer I extends readonly { name: string; type: string }[];
       }
     ? {
-        readonly [P in I[number] as P['name']]: RefBindable<
-          AbiTypeToOutputKind<P['type']>
-        >;
+        readonly [P in I[number] as P['name']]:
+          | RefBindable<AbiTypeToOutputKind<P['type']>>
+          | SignatureLiteral<P['type']>;
       }
-    : Record<string, AnyRefBindable>;
+    : Record<string, AnySignatureBindable>;
 
 // ---------------------------------------------------------------------------
 // Return-type inference from function signatures
@@ -139,9 +160,18 @@ export const toBindRef = (bindable: AnyRefBindable): Ref => {
   return bindable;
 };
 
+/**
+ * Converts one signature-derived bind to its positional `config.args` entry: a
+ * ref-resolving bindable becomes `{ $ref }`; a literal becomes its `value`
+ * verbatim, which the backend encodes against the parameter's ABI type (a
+ * decimal or hex integer, a hex address or byte string, `'true'`/`'false'`).
+ */
+const toPositionalArg = (bindable: AnySignatureBindable): Ref | string =>
+  'kind' in bindable ? bindable.value : toBindRef(bindable);
+
 export interface BuildCallWireFormatInput {
   readonly resource?: AnyRefBindable;
-  readonly bind: Record<string, AnyRefBindable>;
+  readonly bind: Record<string, AnySignatureBindable>;
   readonly config: Record<string, unknown>;
   readonly guards?: readonly TypedGuard[];
 }
@@ -155,13 +185,13 @@ export interface CallWireResult {
 
 /**
  * Parses a function signature from `config`, validates bind keys against it,
- * and converts named binds to positional `$ref` args.
+ * and converts named binds to positional args.
  */
 const resolvePositionalArgs = (
   label: string,
-  bind: Record<string, AnyRefBindable>,
+  bind: Record<string, AnySignatureBindable>,
   config: Record<string, unknown>,
-): Ref[] => {
+): (Ref | string)[] => {
   const functionSignature = config.functionSignature;
   if (typeof functionSignature !== 'string') {
     throw new Error(
@@ -196,7 +226,7 @@ const resolvePositionalArgs = (
         `${label}: bind value for parameter "${name}" is undefined`,
       );
     }
-    return toBindRef(bindable);
+    return toPositionalArg(bindable);
   });
 };
 
@@ -205,7 +235,7 @@ const resolvePositionalArgs = (
  * format that the backend expects:
  * - With resource: `core.call` with `bind: { input: <resourceRef> }`
  * - Without resource: `core.invoke` with `bind: {}`
- * - `config: { ...userConfig, args: [positional refs...] }`
+ * - `config: { ...userConfig, args: [positional refs and literal values...] }`
  */
 export const buildCallWireFormat = (
   args: BuildCallWireFormatInput,
@@ -226,7 +256,7 @@ export const buildCallWireFormat = (
 };
 
 export interface BuildStaticCallWireFormatInput {
-  readonly bind: Record<string, AnyRefBindable>;
+  readonly bind: Record<string, AnySignatureBindable>;
   readonly config: Record<string, unknown>;
   readonly guards?: readonly TypedGuard[];
 }

package/src/client.ts

@@ -218,6 +218,7 @@ const decodeAmount = (value: unknown, path: string, url: string): bigint => {
 // every field before writing a decoded `bigint` back over the wire string.
 interface WireAmountBody {
   outputs?: unknown;
+  epilogue?: unknown;
 }
 
 // One `Amount` as it arrives: each leaf is `unknown` until this seam has
@@ -280,14 +281,36 @@ const decodeOutputs = (data: WireAmountBody, url: string): void => {
   }
 };
 
+// `epilogue` is optional (absent without an epilogue, and on every partial);
+// when present, each named forward's `amount` is a decimal string on the wire.
+const decodeEpilogue = (data: WireAmountBody, url: string): void => {
+  const epilogue = data.epilogue;
+  if (epilogue === undefined) return;
+  if (!isNonNullObject(epilogue) || !Array.isArray(epilogue.forwards)) {
+    throw malformed('epilogue', 'is not an object with forwards', url);
+  }
+  const forwards: readonly unknown[] = epilogue.forwards;
+  forwards.forEach((forward, index) => {
+    if (!isNonNullObject(forward)) {
+      throw malformed(`epilogue.forwards[${index}]`, 'is not an object', url);
+    }
+    forward.amount = decodeAmount(
+      forward.amount,
+      `epilogue.forwards[${index}].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
+// The amount records are 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);
+  decodeEpilogue(data, url);
 };
 
 const parseBody = async <T>(res: Response, url: string): Promise<T> => {

package/src/errors.ts

@@ -1,6 +1,7 @@
 import type {
   ComposeErrorKind,
   ComposeRouteErrorKind,
+  DeliveryErrorDetails,
   FailedPreparedOp,
   GenericComposeErrorKind,
   SimulationRevert,
@@ -102,6 +103,12 @@ export class ComposeError extends Error {
    * backend can parse the revert reason.
    */
   readonly details?: SimulationRevert;
+  /**
+   * The delivery tranche's reason, first quote, and abandoned escrow,
+   * attached to `delivery_error` errors. Narrow with
+   * {@link isComposeDeliveryError}.
+   */
+  readonly delivery?: DeliveryErrorDetails;
   /**
    * The prepared ops that failed, attached to `preparation_error` errors.
    * Each entry carries the `callId` of the failing node so callers can drop
@@ -130,6 +137,7 @@ export class ComposeError extends Error {
       port?: string;
       fix?: string;
       details?: SimulationRevert;
+      delivery?: DeliveryErrorDetails;
       failedOps?: readonly FailedPreparedOp[];
       succeededOps?: readonly string[];
       sdkOutdated?: ComposeSdkOutdated;
@@ -145,6 +153,7 @@ export class ComposeError extends Error {
     this.port = options?.port;
     this.fix = options?.fix;
     this.details = options?.details;
+    this.delivery = options?.delivery;
     this.failedOps = options?.failedOps;
     this.succeededOps = options?.succeededOps;
     this.sdkOutdated = options?.sdkOutdated;
@@ -200,6 +209,19 @@ export const isComposePreparationError = (
   Array.isArray(e.failedOps) &&
   Array.isArray(e.succeededOps);
 
+/**
+ * Type guard for `delivery_error` failures (HTTP 422): a bridge delivering into
+ * a settle escrow no longer fits it. Narrows {@link ComposeError.delivery} to
+ * present. Recompile: each compile quotes and registers afresh.
+ *
+ * @param e - The value to check.
+ * @returns `true` if `e` is a `ComposeError` carrying delivery details.
+ */
+export const isComposeDeliveryError = (
+  e: unknown,
+): e is ComposeError & { readonly delivery: DeliveryErrorDetails } =>
+  isComposeError(e) && e.kind === 'delivery_error' && e.delivery !== undefined;
+
 // `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.
@@ -287,21 +309,32 @@ const tryParseErrorBody = (body: string): ServerErrorBody | null => {
 
 /**
  * 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.
+ * carries, and routes the wire `details` by kind. The version 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.
+ * A `delivery_error`'s `details` land in `delivery`; every other kind's are
+ * forwarded verbatim as `details`.
  */
-const readVersionSlots = (serverError: ServerErrorBody['error']) => ({
-  sdkOutdated:
-    serverError?.kind === 'sdk_outdated'
-      ? sdkOutdatedSchema.safeParse(serverError).data
-      : undefined,
-  serverOutdated:
-    serverError?.kind === 'server_outdated'
-      ? serverOutdatedSchema.safeParse(serverError).data
+const readKindSlots = (serverError: ServerErrorBody['error']) => {
+  const delivery = serverError?.kind === 'delivery_error';
+  return {
+    sdkOutdated:
+      serverError?.kind === 'sdk_outdated'
+        ? sdkOutdatedSchema.safeParse(serverError).data
+        : undefined,
+    serverOutdated:
+      serverError?.kind === 'server_outdated'
+        ? serverOutdatedSchema.safeParse(serverError).data
+        : undefined,
+    details: delivery
+      ? undefined
+      : (serverError?.details as SimulationRevert | undefined),
+    delivery: delivery
+      ? (serverError.details as DeliveryErrorDetails | undefined)
       : undefined,
-});
+  };
+};
 
 /**
  * Constructs a {@link ComposeError} from an HTTP error response, extracting
@@ -319,7 +352,7 @@ export const errorFromHttpResponse = (
 ): ComposeError => {
   const parsed = tryParseErrorBody(body);
   const serverError = parsed?.error;
-  const { sdkOutdated, serverOutdated } = readVersionSlots(serverError);
+  const slots = readKindSlots(serverError);
 
   return new ComposeError(
     STATUS_TO_CODE.get(status) ??
@@ -333,7 +366,7 @@ export const errorFromHttpResponse = (
       path: serverError?.path,
       port: serverError?.port,
       fix: serverError?.fix,
-      details: serverError?.details,
+      ...slots,
       // The wire schema types `kind` as a bare string; the server only ever
       // reports generic kinds for individual ops.
       failedOps: serverError?.failedOps?.map((op) => ({
@@ -341,8 +374,6 @@ export const errorFromHttpResponse = (
         kind: op.kind as GenericComposeErrorKind,
       })),
       succeededOps: serverError?.succeededOps,
-      sdkOutdated,
-      serverOutdated,
     },
   );
 };

package/src/examples/continuationBridgeSettle.ts

@@ -0,0 +1,99 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import {
+  createComposeSdk,
+  guards,
+  materialisers,
+  resources,
+} from '../index.js';
+import type { Address } from '../types.js';
+
+import { API_KEY, BASE_URL } from './config.js';
+
+const ARBITRUM = 42161;
+const BASE = 8453;
+const ARB_USDC = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';
+const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+// Aave V3 aToken for USDC on Base.
+const A_BAS_USDC = '0x4e65fE4DbA92790696d040ac24Aa414708F5c0AB';
+const VALIDITY_WINDOW_MS = 3_600_000;
+
+export interface ContinuationBridgeSettleInput {
+  readonly owner: Address;
+  // Receives the aBasUSDC position on Base; defaults to `owner`.
+  readonly recipient?: Address;
+}
+
+/**
+ * Bridge USDC from Arbitrum to Base, and escrow the bridged USDC on Base for a
+ * deferred settlement that supplies it to Aave and delivers the aBasUSDC
+ * position to the recipient.
+ *
+ * Demonstrates:
+ * - `lifi.bridge` with no `destination`: its `amountOut` funds the settle's
+ *   escrow on Base instead of landing at an address
+ * - `continuation.settle` bound to `bridge.amountOut` (delivered funding): the
+ *   bridge delivers straight into the escrow, so the user signs one
+ *   transaction on Arbitrum, and the settle must omit `funding`
+ * - `validity.expiresAtMs` at least `max(3 × the bridge ETA, 30 minutes)` away
+ * - A leg on the escrow chain (Base) that does the work the user could not do
+ *   from Arbitrum: `lifi.zap` supplies the landed USDC to Aave. The aBasUSDC
+ *   stays in the leg's proxy; the settlement epilogue the composer appends at
+ *   commit forwards it to the recipient
+ * - An outcome in a token the leg produces (aBasUSDC), not the funding token:
+ *   the zap's slippage guard proves the floor, so `minAmount` is omitted
+ */
+export const buildContinuationBridgeSettleExample = ({
+  owner,
+  recipient = owner,
+}: ContinuationBridgeSettleInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  // The leg: runs from the escrow on Base once the bridged USDC has landed.
+  // The zap supplies the USDC to Aave; the aBasUSDC it mints lands in the
+  // leg's proxy, where the settlement epilogue picks it up. The slippage guard
+  // on `amountOut` is the enforced floor the compiler commits.
+  const leg = sdk.flow(BASE, {
+    name: 'bridge-settle-leg',
+    inputs: { funding: resources.erc20(BASE_USDC, BASE) },
+  });
+  leg.lifi.zap('supply', {
+    bind: { amountIn: leg.inputs.funding },
+    config: { resourceOut: resources.erc20(A_BAS_USDC, BASE) },
+    guards: [guards.slippage({ port: 'amountOut', bps: 50 })],
+  });
+
+  // The main flow on Arbitrum: bridge to Base, then escrow the delivery.
+  const builder = sdk.flow(ARBITRUM, {
+    name: 'bridge-and-settle',
+    inputs: { amountIn: resources.erc20(ARB_USDC, ARBITRUM) },
+  });
+  const bridge = builder.lifi.bridge('bridge', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: { resourceOut: resources.erc20(BASE_USDC, BASE) },
+  });
+  builder.continuation.settle('settle', {
+    bind: { input: bridge.amountOut },
+    config: {
+      outcomes: [{ token: A_BAS_USDC, destination: recipient, chainId: BASE }],
+      validity: { expiresAtMs: Date.now() + VALIDITY_WINDOW_MS },
+      provider: 'intent-factory',
+      refund: owner,
+      continuationFlow: leg.build(),
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: '1000000000' }),
+    },
+  });
+
+  return { flow, request };
+};

package/src/examples/continuationSettle.ts

@@ -0,0 +1,113 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import {
+  createComposeSdk,
+  guards,
+  materialisers,
+  resources,
+} from '../index.js';
+import type { Address } from '../types.js';
+
+import { API_KEY, BASE_URL } from './config.js';
+
+const BASE = 8453;
+const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const WETH = '0x4200000000000000000000000000000000000006';
+// Aave V3 aToken for WETH on Base.
+const A_BAS_WETH = '0xD4a0e0b9149BCee3C920d2E00b5dE09138fd8bb7';
+const VALIDITY_WINDOW_MS = 3_600_000;
+
+export interface ContinuationSettleInput {
+  readonly owner: Address;
+  // Receives the aBasWETH position; defaults to `owner`.
+  readonly recipient?: Address;
+}
+
+/**
+ * Swap USDC to WETH on Base, then escrow the WETH for a deferred settlement
+ * whose leg supplies it to Aave and delivers the aBasWETH position to the
+ * recipient.
+ *
+ * Demonstrates:
+ * - `continuation.settle` funded by an upstream output (`swap.amountOut`)
+ * - The leg (`continuationFlow`) as an ordinary flow built with `sdk.flow`
+ *   and assigned with `leg.build()`: here one `lifi.zap` that supplies the
+ *   escrowed WETH to Aave
+ * - An outcome in the token the leg produces (aBasWETH): the zap's slippage
+ *   guard proves the floor, so `minAmount` is omitted
+ * - `refund` naming the address that receives the escrow balance on expiry
+ *   and the leg's residual (optional; defaults to the signer)
+ *
+ * The leg contract:
+ * - Exactly one input: a resource input in the funding token on the escrow
+ *   chain. The solver binds the escrow balance to it.
+ * - Produce each outcome into the leg's own proxy and end there. A zap or a
+ *   deposit mints into the proxy by default; a node that needs a receiver
+ *   binds `leg.context.executionAddress`. A funding input no node consumes
+ *   stays in the proxy as the terminal `input.<name>`. Never
+ *   pay a recipient: not `destination`, not the provider's settlement
+ *   recipient, and never `context.sender` (inside the leg that is the
+ *   settlement account, not the user). Never set the leg's own epilogue. At
+ *   commit the composer appends the settlement epilogue, which forwards each
+ *   outcome to the provider's recipient and the residual to `refund`.
+ * - Omit `funding` when the settle input is a bridge's
+ *   `amountOut` (see `continuationBridgeSettle.ts`).
+ * - `minAmount` is optional: a guard or an op floor on the outcome token
+ *   proves it, and an unconsumed funding input proves the full funding floor.
+ */
+export const buildContinuationSettleExample = ({
+  owner,
+  recipient = owner,
+}: ContinuationSettleInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  // The leg: runs from the escrow on Base once the WETH has landed there. The
+  // zap supplies the WETH to Aave; the aBasWETH it mints lands in the leg's
+  // proxy, where the settlement epilogue picks it up. The slippage guard on
+  // `amountOut` is the enforced floor the compiler commits.
+  const leg = sdk.flow(BASE, {
+    name: 'settle-leg',
+    inputs: { funding: resources.erc20(WETH, BASE) },
+  });
+  leg.lifi.zap('supply', {
+    bind: { amountIn: leg.inputs.funding },
+    config: { resourceOut: resources.erc20(A_BAS_WETH, BASE) },
+    guards: [guards.slippage({ port: 'amountOut', bps: 50 })],
+  });
+
+  // The main flow: swap USDC to WETH, then escrow the WETH for the leg.
+  const builder = sdk.flow(BASE, {
+    name: 'swap-and-settle',
+    inputs: { amountIn: resources.erc20(USDC, BASE) },
+  });
+  const swap = builder.lifi.swap('swap', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: { resourceOut: resources.erc20(WETH, BASE) },
+  });
+  builder.continuation.settle('settle', {
+    bind: { input: swap.amountOut },
+    config: {
+      outcomes: [{ token: A_BAS_WETH, destination: recipient, chainId: BASE }],
+      validity: { expiresAtMs: Date.now() + VALIDITY_WINDOW_MS },
+      provider: 'intent-factory',
+      refund: owner,
+      continuationFlow: leg.build(),
+    },
+  });
+
+  const flow = builder.build();
+
+  // No `sweepTo`: the swap output funds the escrow and the settle output is
+  // delivered by the settlement, never landing in the VM.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: '1000000000' }),
+    },
+  });
+
+  return { flow, request };
+};