@lifi/composer-sdk 0.2.0-staging.5 → 0.2.0

package/dist/sdk.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\n  InputSpec,\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 {\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  /** Optional LI.FI API key for authenticated access. Sent as the `x-lifi-api-key` header on every request. */\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' });\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   * 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\n/**\n * Creates a new Compose SDK instance.\n *\n * @param options - SDK configuration including the API base URL and optional fetch implementation.\n * @returns A {@link ComposeSdk} instance.\n *\n * @example\n * ```ts\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });\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      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 { client: composeClient, flow, request };\n};\n"],"mappings":"AAMA;AAAA,EACE;AAAA,OAIK;AACP,SAA6B,2BAA2B;AACxD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,gBAAsC;AAmHxC,MAAM,mBAAmB,CAAC,YAA2C;AAC1E,QAAM,gBAAgB,oBAAoB,OAAO;AAEjD,QAAM,UAAU,CACd,SACA,SAC2B;AAAA,IAC3B,MAAM;AAAA,IACN,KAAK,SAAS;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ,eAAe,IAAI;AAAA,MACnB,QAAQ,IAAI;AAAA,MACZ,aAAa,IAAI;AAAA,MACjB,UAAU,IAAI;AAAA,MACd,kBAAkB,IAAI;AAAA,MACtB,mBAAmB,IAAI;AAAA,MACvB,SAAS,IAAI;AAAA,MACb,kBAAkB,IAAI;AAAA,MACtB,wBAAwB,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,QAAM,OAAO,CACX,SACA,SACmB;AACnB,UAAM,OAAO,sBAAsB,SAAS,IAAI;AAChD,UAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,IAAI,CAAC;AAE1D,UAAM,UAAU,OACd,QACkC;AAClC,YAAM,UAAU,QAAQ,MAAM;AAC9B,YAAM,MAAM,QAAQ,SAAS,GAAG;AAChC,aAAO,cAAc,QAAQ,GAAG;AAAA,IAClC;AAEA,WAAO,OAAO,OAAO,SAAS,EAAE,QAAQ,CAAC;AAAA,EAC3C;AAEA,SAAO,EAAE,QAAQ,eAAe,MAAM,QAAQ;AAChD;","names":[]}
+{"version":3,"sources":["../src/sdk.ts"],"sourcesContent":["import type {\n  ComposeCompileRequest,\n  ComposeCompileResult,\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 {\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  /** Optional LI.FI API key for authenticated access. Sent as the `x-lifi-api-key` header on every request. */\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' });\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   * 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   * 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 and optional fetch implementation.\n * @returns A {@link ComposeSdk} instance.\n *\n * @example\n * ```ts\n * const sdk = createComposeSdk({ baseUrl: 'https://li.quest' });\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      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    request,\n    simulate: composeClient.simulate,\n  };\n};\n"],"mappings":"AAQA;AAAA,EACE;AAAA,OAIK;AACP,SAA6B,2BAA2B;AACxD;AAAA,EACE;AAAA,OAEK;AACP,SAAS,gBAAsC;AA+HxC,MAAM,mBAAmB,CAAC,YAA2C;AAC1E,QAAM,gBAAgB,oBAAoB,OAAO;AAEjD,QAAM,UAAU,CACd,SACA,SAC2B;AAAA,IAC3B,MAAM;AAAA,IACN,KAAK,SAAS;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ,eAAe,IAAI;AAAA,MACnB,QAAQ,IAAI;AAAA,MACZ,aAAa,IAAI;AAAA,MACjB,UAAU,IAAI;AAAA,MACd,kBAAkB,IAAI;AAAA,MACtB,mBAAmB,IAAI;AAAA,MACvB,SAAS,IAAI;AAAA,MACb,kBAAkB,IAAI;AAAA,MACtB,wBAAwB,IAAI;AAAA,IAC9B,CAAC;AAAA,EACH;AAEA,QAAM,OAAO,CACX,SACA,SACmB;AACnB,UAAM,OAAO,sBAAsB,SAAS,IAAI;AAChD,UAAM,UAAU,OAAO,OAAO,MAAM,iBAAiB,IAAI,CAAC;AAE1D,UAAM,UAAU,OACd,QACkC;AAClC,YAAM,UAAU,QAAQ,MAAM;AAC9B,YAAM,MAAM,QAAQ,SAAS,GAAG;AAChC,aAAO,cAAc,QAAQ,GAAG;AAAA,IAClC;AAEA,WAAO,OAAO,OAAO,SAAS,EAAE,QAAQ,CAAC;AAAA,EAC3C;AAEA,SAAO;AAAA,IACL,QAAQ;AAAA,IACR;AAAA,IACA;AAAA,IACA,UAAU,cAAc;AAAA,EAC1B;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.2.0-staging.5",
+  "version": "0.2.0",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
   "repository": {
@@ -23,7 +23,7 @@
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public"
@@ -51,11 +51,12 @@
     "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.2.0-staging.5"
+    "@lifi/compose-spec": "0.2.0"
   },
   "dependencies": {
     "abitype": "^1.2.3",
-    "effect": "^3.21.0"
+    "effect": "^3.21.0",
+    "zod": "^4.1.11"
   },
   "devDependencies": {
     "@eslint/compat": "^1.4.0",
@@ -84,6 +85,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.mock.ts",
     "!src/**/*.typecheck.ts",
-    "!dist/**/*.typecheck.*"
+    "!dist/**/*.typecheck.*",
+    "!src/examples/staged/**"
   ]
 }

package/src/client.ts

@@ -4,10 +4,16 @@ import type {
   ComposeCompileResult,
   ComposeCompileSuccessData,
   ComposeManifest,
+  SimulateRequest,
+  SimulateResult,
 } from '@lifi/compose-spec';
 
 import type { GetZapPacksOptions, ZapPackOverview } from './discovery.js';
 import { ComposeError, errorFromHttpResponse } from './errors.js';
+import {
+  parseCompilePartialEnvelope,
+  parseSimulateResult,
+} from './responseSchemas.js';
 
 // __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
@@ -78,6 +84,30 @@ export interface ComposeClient {
   readonly getZapPacks: (
     options?: GetZapPacksOptions,
   ) => Promise<readonly ZapPackOverview[]>;
+  /**
+   * Simulates a raw, pre-encoded transaction against `POST /simulate` and
+   * reports how the watched balances change and how much inner-call gas it
+   * burns.
+   *
+   * The result is a discriminated union on `status`:
+   * - `'ok'` — the simulation ran successfully; `deltas`/`gasUsed` are populated.
+   * - `'revert'` — the simulation ran but the transaction reverted on-chain. A
+   *   revert is a *successful simulation*, not a transport error, so it is
+   *   returned (HTTP 200) rather than thrown — mirroring how {@link compile}
+   *   returns `status: 'partial'` on a simulated revert.
+   * - `'error'` — the request was well-formed but the simulation could not be
+   *   set up or run (HTTP 422); `message` is intentionally generic.
+   *
+   * `bigint` amounts in the request (`value`, requirement `balance`/`allowance`)
+   * are serialised to decimal strings automatically.
+   *
+   * @param request - The raw transaction plus funding `requirements` and the
+   *   `trackedBalances` to watch.
+   * @returns A {@link SimulateResult} (`ok` / `revert` / `error`).
+   * @throws {@link ComposeError} on network failures, HTTP 400 (malformed
+   *   input), 401/403 (auth), 404, 429, and 5xx.
+   */
+  readonly simulate: (request: SimulateRequest) => Promise<SimulateResult>;
 }
 
 const bigintReplacer = (_key: string, value: unknown): unknown =>
@@ -109,22 +139,39 @@ const parsePartialBody = async (
   url: string,
 ): Promise<ComposeCompileResult> => {
   const body = await res.json().catch((_) => null);
-  if (
-    !isNonNullObject(body) ||
-    !('data' in body) ||
-    !isNonNullObject(body.data) ||
-    !('error' in body) ||
-    !isNonNullObject(body.error)
-  ) {
+  const envelope = parseCompilePartialEnvelope(body);
+  if (envelope === null) {
     throw new ComposeError(
       'UNKNOWN_ERROR',
       'Unexpected partial response format',
       { url },
     );
   }
-  const data = body.data as unknown as ComposeCompilePartialData;
-  const error = body.error as unknown as { kind: string; message: string };
-  return { ...data, status: 'partial' as const, error };
+  // `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;
+  return { ...data, status: 'partial' as const, error: envelope.error };
+};
+
+// `/simulate` is un-enveloped: the discriminated body (`{ status, ... }`) is at
+// the top level, NOT wrapped in `{ data }` like `/compose`. So this reads the
+// body directly and validates it against the simulate union rather than reusing
+// `parseBody`.
+const parseSimulateBody = async (
+  res: Response,
+  url: string,
+): Promise<SimulateResult> => {
+  const body = await res.json().catch((_) => null);
+  const result = parseSimulateResult(body);
+  if (result === null) {
+    throw new ComposeError(
+      'UNKNOWN_ERROR',
+      'Unexpected simulate response format',
+      { url },
+    );
+  }
+  return result;
 };
 
 /**
@@ -226,5 +273,33 @@ export const createComposeClient = (
     return await parseBody<readonly ZapPackOverview[]>(res, url);
   };
 
-  return { getManifest, compile, getZapPacks };
+  const simulate = async (
+    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 });
+    }
+    // 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
+    // `switch (result.status)`. Every other status is a transport error and is
+    // thrown — including HTTP 400 (malformed input, no `status` body) and any
+    // unexpected 2xx.
+    if (res.status === 200 || res.status === 422) {
+      return await parseSimulateBody(res, url);
+    }
+    const body = await res.text();
+    throw errorFromHttpResponse(res.status, body, url);
+  };
+
+  return { getManifest, compile, getZapPacks, simulate };
 };

package/src/errors.ts

@@ -1,5 +1,10 @@
 import type { ComposeErrorKind, SimulationRevert } from '@lifi/compose-spec';
 
+import {
+  parseServerErrorBody,
+  type ServerErrorBody,
+} from './responseSchemas.js';
+
 /**
  * Machine-readable error codes returned by the SDK.
  *
@@ -101,21 +106,14 @@ const STATUS_TO_CODE: ReadonlyMap<number, ComposeErrorCode> = new Map<
   [429, 'RATE_LIMITED'],
 ]);
 
-interface ServerErrorBody {
-  readonly error?: {
-    readonly kind?: string;
-    readonly message?: string;
-    readonly path?: string;
-    readonly details?: SimulationRevert;
-  };
-}
-
 const tryParseErrorBody = (body: string): ServerErrorBody | null => {
+  let json: unknown;
   try {
-    return JSON.parse(body) as ServerErrorBody;
+    json = JSON.parse(body);
   } catch {
     return null;
   }
+  return parseServerErrorBody(json);
 };
 
 /**

package/src/examples/simulateCompiledSwap.ts

@@ -0,0 +1,76 @@
+import type { SimulateResult } from '@lifi/compose-spec';
+
+import { buildSimulateRequest, materialisers, resources } from '../index.js';
+import type { ComposeSdk } from '../index.js';
+
+import { OWNER } from './config.js';
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+// 1 WETH (18 decimals).
+const ONE_WETH = 1_000_000_000_000_000_000n;
+
+/**
+ * End-to-end `/simulate` usage: compile a WETH→USDC swap, then simulate the
+ * compiled transaction to see how the signer's balances move and how much
+ * inner-call gas it burns — without broadcasting anything on-chain.
+ *
+ * Demonstrates the compile → simulate arc:
+ * - `buildSimulateRequest` lifts a `ComposeCompileResult` into a
+ *   `SimulateRequest`, supplying the fields a compiled flow cannot carry: the
+ *   target `chainId`, the `signer` (`from`), the funding `requirements`, and the
+ *   `trackedBalances` to watch.
+ * - `sdk.simulate` runs it and returns a discriminated `ok | revert | error`
+ *   result. A `revert` is a *successful simulation* whose execution reverted, so
+ *   it is returned (not thrown); only transport/auth/5xx failures throw.
+ *
+ * Unlike the pure-builder examples, this performs network I/O through the
+ * injected `sdk` (one `/compose` call, one `/simulate` call). Pass a live
+ * `createComposeSdk({ baseUrl })` to run it for real, or a mock-backed SDK in
+ * tests.
+ */
+export const simulateCompiledSwap = async (
+  sdk: ComposeSdk,
+): Promise<SimulateResult> => {
+  // Author and compile a single WETH → USDC swap on Ethereum mainnet.
+  const builder = sdk.flow(1, {
+    name: 'swap-weth-to-usdc',
+    inputs: { amountIn: resources.erc20(WETH, 1) },
+  });
+
+  builder.lifi.swap('swap', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: { resourceOut: resources.erc20(USDC, 1), slippage: 0.03 },
+  });
+
+  const compiled = await builder.compile({
+    signer: OWNER,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: ONE_WETH }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  // Lift the compiled transaction into a simulation request. The chain, signer,
+  // funding, and watched balances are NOT inferable from a compiled flow, so
+  // they are supplied here. `to`/`data`/`value` come from the compile result.
+  const request = buildSimulateRequest({
+    result: compiled,
+    chainId: 1,
+    signer: OWNER,
+    // Seed the signer with the 1 WETH the swap deposits, so the inner call has
+    // funds to pull. `bigint` amounts are serialised to decimal strings.
+    requirements: [
+      { type: 'Erc20Balance', wallet: OWNER, token: WETH, balance: ONE_WETH },
+    ],
+    // Watch the signer's WETH (spent) and USDC (received) balances; the response
+    // `deltas` come back ordered to match.
+    trackedBalances: [
+      { token: WETH, owner: OWNER },
+      { token: USDC, owner: OWNER },
+    ],
+  });
+
+  return sdk.simulate(request);
+};

package/src/examples/simulateRawTransaction.ts

@@ -0,0 +1,39 @@
+import type { SimulateRequest } from '@lifi/compose-spec';
+
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+const SENDER = '0x1111111111111111111111111111111111111111';
+const RECIPIENT = '0x2222222222222222222222222222222222222222';
+
+/**
+ * Build a representative `POST /simulate` request: a USDC transfer of 1 USDC
+ * (1_000_000 base units at 6 decimals) from `SENDER` to `RECIPIENT` on chain 1.
+ *
+ * Demonstrates:
+ * - A pre-encoded `transfer(address,uint256)` calldata literal (`data`)
+ * - Funding the sender with an `Erc20Balance` requirement so the transfer can
+ *   succeed in simulation (`bigint` amounts are accepted and serialised)
+ * - Watching both the sender's and recipient's USDC balance via `trackedBalances`
+ *
+ * Pure: returns a plain {@link SimulateRequest}, performs no network I/O. Pass
+ * it to `sdk.client.simulate(...)` / `sdk.simulate(...)` to run it.
+ */
+export const buildSimulateRawTransactionExample = (): SimulateRequest => ({
+  chainId: 1,
+  from: SENDER,
+  to: USDC,
+  // transfer(RECIPIENT, 1_000_000)
+  data: '0xa9059cbb0000000000000000000000002222222222222222222222222222222222222222000000000000000000000000000000000000000000000000000000000f4240',
+  value: 0n,
+  requirements: [
+    {
+      type: 'Erc20Balance',
+      wallet: SENDER,
+      token: USDC,
+      balance: 1_000_000n,
+    },
+  ],
+  trackedBalances: [
+    { token: USDC, owner: SENDER },
+    { token: USDC, owner: RECIPIENT },
+  ],
+});

package/src/generated/config.generated.ts

@@ -126,23 +126,139 @@ export interface CoreEmitEvent4Config {
   signature: string;
 }
 
+/**
+ * a string at most 65536 character(s) long
+ */
+export type MaxLength65536 = string;
+
 export interface CoreCallConfig {
   target: Address;
   functionSignature: string;
   callType?: 'Call' | 'ValueCall';
-  args?: Unknown[];
+  args?: (
+    | (
+        | MaxLength65536
+        | number
+        | boolean
+        | {
+            $ref: string;
+          }
+      )
+    | (
+        | (
+            | MaxLength65536
+            | number
+            | boolean
+            | {
+                $ref: string;
+              }
+          )
+        | (
+            | (
+                | MaxLength65536
+                | number
+                | boolean
+                | {
+                    $ref: string;
+                  }
+              )
+            | (
+                | (
+                    | MaxLength65536
+                    | number
+                    | boolean
+                    | {
+                        $ref: string;
+                      }
+                  )
+                | (
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )[]
+                  )[]
+              )[]
+          )[]
+      )[]
+  )[];
   approvals?: {
     spender: Address;
   }[];
 }
-export interface Unknown {
-  [k: string]: unknown;
-}
 
 export interface CoreStaticCallConfig {
   target: Address;
   functionSignature: string;
-  args?: Unknown[];
+  args?: (
+    | (
+        | MaxLength65536
+        | number
+        | boolean
+        | {
+            $ref: string;
+          }
+      )
+    | (
+        | (
+            | MaxLength65536
+            | number
+            | boolean
+            | {
+                $ref: string;
+              }
+          )
+        | (
+            | (
+                | MaxLength65536
+                | number
+                | boolean
+                | {
+                    $ref: string;
+                  }
+              )
+            | (
+                | (
+                    | MaxLength65536
+                    | number
+                    | boolean
+                    | {
+                        $ref: string;
+                      }
+                  )
+                | (
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )[]
+                  )[]
+              )[]
+          )[]
+      )[]
+  )[];
 }
 
 export interface CoreRawCallConfig {
@@ -156,7 +272,64 @@ export interface CoreInvokeConfig {
   target: Address;
   functionSignature: string;
   callType?: 'Call' | 'ValueCall';
-  args?: Unknown[];
+  args?: (
+    | (
+        | MaxLength65536
+        | number
+        | boolean
+        | {
+            $ref: string;
+          }
+      )
+    | (
+        | (
+            | MaxLength65536
+            | number
+            | boolean
+            | {
+                $ref: string;
+              }
+          )
+        | (
+            | (
+                | MaxLength65536
+                | number
+                | boolean
+                | {
+                    $ref: string;
+                  }
+              )
+            | (
+                | (
+                    | MaxLength65536
+                    | number
+                    | boolean
+                    | {
+                        $ref: string;
+                      }
+                  )
+                | (
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )[]
+                  )[]
+              )[]
+          )[]
+      )[]
+  )[];
 }
 
 export interface CoreAsResourceConfig {

package/src/generated/materialisers.generated.ts

@@ -10,7 +10,6 @@ import type {
   BalanceOfMaterialiserConfig as BalanceOfMaterialiserConfigSchema,
   CallMaterialiserConfig as CallMaterialiserConfigSchema,
   DirectDepositMaterialiserConfig as DirectDepositMaterialiserConfigSchema,
-  FlashloanMaterialiserConfig as FlashloanMaterialiserConfigSchema,
 } from './config.generated.js';
 
 export type BalanceOfMaterialiserConfig =
@@ -43,14 +42,3 @@ export const call = (config: CallMaterialiserConfig): MaterialiserInput => ({
   kind: 'call',
   ...config,
 });
-
-export type FlashloanMaterialiserConfig =
-  MaterialiserConfigOf<FlashloanMaterialiserConfigSchema>;
-
-/** Borrow tokens from a flashloan provider; amount becomes a register populated by the proxy at callback time — accepts: resource */
-export const flashloan = (
-  config: FlashloanMaterialiserConfig,
-): MaterialiserInput => ({
-  kind: 'flashloan',
-  ...config,
-});