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

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/aaveRepay.ts

@@ -7,29 +7,44 @@ import { BASE_URL } from './config.js';
 
 // Aave v3 contracts on Ethereum mainnet.
 const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+// Aave v3 aEthUSDC receipt token and variable-debt WETH token.
+const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
+const VDEBT_WETH = '0xeA51d7853EEFb32b6ee06b1C12E6dcCA88Be0fFE';
 
 export interface AaveRepayInput {
   readonly owner: Address;
-  readonly amount: `${bigint}`;
+  /** USDC supplied as collateral so the proxy can borrow WETH (6 dp). */
+  readonly collateralAmount: `${bigint}`;
+  /** WETH borrowed against the collateral (18 dp). */
+  readonly borrowAmount: `${bigint}`;
+  /**
+   * WETH deposited to repay the debt (18 dp). Must exceed `borrowAmount`:
+   * Aave's scaled-balance rounding can leave the debt 1 wei above the
+   * borrowed amount, so the `max`-mode repay needs a little headroom.
+   */
+  readonly repayAmount: `${bigint}`;
 }
 
 /**
- * Repay an Aave v3 variable-rate WETH debt by supplying WETH to the proxy.
- *
- * Aave internally caps the repay at `min(amount, outstandingDebt)`, so the
- * op returns any unspent WETH on the `residual` resource port. The
- * residual is swept back to the sender on completion.
+ * Supply USDC to Aave v3, borrow WETH against it, then repay the WETH borrow —
+ * a self-contained supply → borrow → repay round trip.
  *
  * Demonstrates:
- * - `aave.repay` with a resource input (the WETH used to repay).
- * - Binding `onBehalfOf` from the runtime context — the proxy repays its
- *   own debt position.
- * - The `residual` port for surfacing any unused input back to the caller.
+ * - `lifi.zap` to supply USDC into Aave (USDC → aEthUSDC routing edge)
+ * - `aave.borrow` to mint variable WETH debt against the supplied collateral
+ * - `aave.repay` (mode: 'max') funded by a fresh WETH deposit, clearing the
+ *   debt exactly so the collateral is freed
+ * - `sweepTo` to return all leftover proxy-held resources (the freed
+ *   aEthUSDC collateral, the borrowed WETH, and the repay residual) to the
+ *   sender
  */
 export const buildAaveRepay = ({
   owner,
-  amount,
+  collateralAmount,
+  borrowAmount,
+  repayAmount,
 }: AaveRepayInput): {
   flow: Flow;
   request: ComposeCompileRequest;
@@ -39,18 +54,40 @@ export const buildAaveRepay = ({
   const builder = sdk.flow(1, {
     name: 'aave-repay-weth',
     inputs: {
-      assetIn: resources.erc20(WETH, 1),
+      collateralIn: resources.erc20(USDC, 1),
+      repayIn: resources.erc20(WETH, 1),
+    },
+  });
+
+  // Supply USDC as collateral (USDC → aEthUSDC) so the proxy can borrow.
+  builder.lifi.zap('supply', {
+    bind: { amountIn: builder.inputs.collateralIn },
+    config: { resourceOut: resources.erc20(A_ETH_USDC, 1) },
+  });
+
+  // Borrow WETH against the collateral; the borrowed WETH stays on the
+  // proxy as a terminal resource and is swept back to the sender.
+  builder.aave.borrow('borrow', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL,
+      asset: WETH,
+      variableDebtToken: VDEBT_WETH,
+      amount: borrowAmount,
     },
   });
 
+  // Repay the just-opened WETH debt from the deposited WETH. mode 'max'
+  // passes type(uint256).max so Aave clamps to the outstanding debt exactly
+  // — required to clear the borrow flag and free the collateral for sweeping.
   builder.aave.repay('repay', {
     bind: {
-      assetIn: builder.inputs.assetIn,
+      assetIn: builder.inputs.repayIn,
       onBehalfOf: builder.context.executionAddress,
     },
     config: {
       pool: AAVE_V3_POOL,
-      mode: 'exact',
+      mode: 'max',
     },
   });
 
@@ -59,9 +96,11 @@ export const buildAaveRepay = ({
   const request = sdk.request(flow, {
     signer: owner,
     inputs: {
-      assetIn: materialisers.directDeposit({ amount }),
+      collateralIn: materialisers.directDeposit({ amount: collateralAmount }),
+      repayIn: materialisers.directDeposit({ amount: repayAmount }),
     },
-    // Any unspent WETH (residual) is swept back to the signer.
+    // Once the debt is cleared, sweep the freed aEthUSDC collateral, the
+    // borrowed WETH, and the repay residual back to the sender.
     sweepTo: builder.context.sender,
   });
 

package/src/examples/aaveRepayWithATokens.ts

@@ -1,11 +1,6 @@
 import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
-import {
-  createComposeSdk,
-  materialisers,
-  preconditions,
-  resources,
-} from '../index.js';
+import { createComposeSdk, materialisers, resources } from '../index.js';
 import type { Address } from '../types.js';
 
 import { BASE_URL } from './config.js';
@@ -13,32 +8,33 @@ import { BASE_URL } from './config.js';
 // Aave v3 contracts on Ethereum mainnet.
 const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+// Aave v3 aEthUSDC receipt token and variable-debt USDC token.
 const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
+const VDEBT_USDC = '0x72E95b8931767C79bA4EeE721354d6E99a61D004';
 
 export interface AaveRepayWithATokensInput {
   readonly owner: Address;
-  readonly proxyAddress: Address;
-  readonly expectedATokenBalance: `${bigint}`;
+  /** USDC supplied as collateral, minting the aUSDC burned by the repay (6 dp). */
+  readonly collateralAmount: `${bigint}`;
+  /** USDC borrowed against the collateral, then repaid by this flow (6 dp). */
+  readonly borrowAmount: `${bigint}`;
 }
 
 /**
- * Repay an Aave v3 variable-rate USDC debt by burning aToken collateral
- * already held by the proxy (no fresh asset transfer required).
- *
- * The aTokens are sourced from the proxy's existing balance via the
- * `balanceOf` materialiser. The `erc20Balance` precondition fails fast
- * if the expected aTokens haven't landed on the proxy yet.
+ * Supply USDC to Aave v3, borrow USDC against it, then repay the debt by
+ * burning the supplied aUSDC directly — no fresh asset transfer required.
  *
  * Demonstrates:
- * - `aave.repayWithATokens` with the aToken as the resource input.
- * - `balanceOf` materialiser to consume proxy-held aTokens directly.
- * - `erc20Balance` precondition to guard against silent zero-value repays.
- * - The `residual` port returns any aTokens not burned (when debt < input).
+ * - `lifi.zap` to supply USDC into Aave (USDC → aEthUSDC routing edge)
+ * - `aave.borrow` to mint variable USDC debt against the supplied collateral
+ * - `aave.repayWithATokens` to clear the debt by burning the aUSDC collateral
+ * - `sweepTo` to return the borrowed USDC and the unburned aUSDC to the
+ *   sender once the debt is cleared
  */
 export const buildAaveRepayWithATokens = ({
   owner,
-  proxyAddress,
-  expectedATokenBalance,
+  collateralAmount,
+  borrowAmount,
 }: AaveRepayWithATokensInput): {
   flow: Flow;
   request: ComposeCompileRequest;
@@ -48,12 +44,32 @@ export const buildAaveRepayWithATokens = ({
   const builder = sdk.flow(1, {
     name: 'aave-repay-with-atokens',
     inputs: {
-      aTokenIn: resources.erc20(A_ETH_USDC, 1),
+      collateralIn: resources.erc20(USDC, 1),
+    },
+  });
+
+  // Supply USDC as collateral (USDC → aEthUSDC); the aUSDC is burned below.
+  const supplyOut = builder.lifi.zap('supply', {
+    bind: { amountIn: builder.inputs.collateralIn },
+    config: { resourceOut: resources.erc20(A_ETH_USDC, 1) },
+  });
+
+  // Borrow USDC against the supplied collateral to open a debt position.
+  builder.aave.borrow('borrow', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL,
+      asset: USDC,
+      variableDebtToken: VDEBT_USDC,
+      amount: borrowAmount,
     },
   });
 
+  // Repay the USDC debt by burning the aUSDC collateral directly. The aToken
+  // input exceeds the debt, so Aave clamps the payback to the outstanding
+  // debt exactly — clearing the borrow flag and freeing the rest for the sweep.
   builder.aave.repayWithATokens('repay-atokens', {
-    bind: { aTokenIn: builder.inputs.aTokenIn },
+    bind: { aTokenIn: supplyOut.amountOut },
     config: {
       pool: AAVE_V3_POOL,
       asset: USDC,
@@ -65,15 +81,10 @@ export const buildAaveRepayWithATokens = ({
   const request = sdk.request(flow, {
     signer: owner,
     inputs: {
-      aTokenIn: materialisers.balanceOf({ owner: proxyAddress }),
+      collateralIn: materialisers.directDeposit({ amount: collateralAmount }),
     },
-    preconditions: [
-      preconditions.erc20Balance({
-        wallet: proxyAddress,
-        token: A_ETH_USDC,
-        balance: expectedATokenBalance,
-      }),
-    ],
+    // Once the debt is cleared, sweep the borrowed USDC and the unburned
+    // aUSDC collateral back to the sender.
     sweepTo: builder.context.sender,
   });
 

package/src/examples/aaveRounding.ts

@@ -0,0 +1,42 @@
+/**
+ * Helpers for Aave v3's scaled-balance rounding.
+ *
+ * Aave v3 does not store balances directly. Every aToken / variable-debt
+ * balance is kept as scaled shares and converted on each access using the
+ * market's live index (RAY = 1e27 precision):
+ *
+ * - write:  shares = amount.rayDiv(index)   — round half-up to 1 ray-wei
+ * - read:   balance = shares.rayMul(index)  — round half-up to 1 wei
+ *
+ * The write+read round trip therefore drifts by up to ~index/RAY wei in
+ * either direction — about 1 wei while the index is below ~2e27, which
+ * holds for all current Aave v3 markets. Concretely, in the same block:
+ *
+ * - a debt opened with `borrow(x)` can read back as `x + 1` wei, and
+ * - collateral supplied with `supply(x)` can read back as `x - 1` wei.
+ *
+ * The drift direction depends on how the amount aligns with the index
+ * remainder, and the index accrues every block — so a simulation that
+ * passes with exact amounts at block N can still revert on-chain at block
+ * N+k. Any flow that settles an exact amount against a same-block Aave
+ * readback (flashloan legs, exact transfers) must budget the worst case:
+ *
+ * - `padForAaveDebtRounding` — for amounts that must *cover* a same-block
+ *   debt readback, e.g. a flashloan principal funding a max-mode repay.
+ * - `trimForAaveWithdrawalRounding` — for amounts that must be *covered
+ *   by* a same-block balance readback, e.g. a flashloan leg repaid from
+ *   an Aave withdrawal.
+ *
+ * The over- or under-shoot wei surface as residual/dust and are swept.
+ */
+
+/** Worst-case same-block readback drift for indices below ~2e27. */
+export const AAVE_SAME_BLOCK_SKEW_WEI = 1n;
+
+export const padForAaveDebtRounding = (amount: `${bigint}`): `${bigint}` =>
+  (BigInt(amount) + AAVE_SAME_BLOCK_SKEW_WEI).toString() as `${bigint}`;
+
+export const trimForAaveWithdrawalRounding = (
+  amount: `${bigint}`,
+): `${bigint}` =>
+  (BigInt(amount) - AAVE_SAME_BLOCK_SKEW_WEI).toString() as `${bigint}`;

package/src/examples/aaveSetEMode.ts

@@ -61,7 +61,6 @@ export const buildAaveSetEMode = ({
   const request = sdk.request(flow, {
     signer: owner,
     inputs: {},
-    sweepTo: builder.context.sender,
   });
 
   return { flow, request };

package/src/examples/config.ts

@@ -6,4 +6,4 @@ export const API_KEY: string | undefined = process.env['LIFI_API_KEY'];
 
 export const OWNER = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
 export const RECIPIENT = '0x1234567890abcdef1234567890abcdef12345678';
-export const PROXY = '0x2222222222222222222222222222222222222222';
+export const PROXY = '0x0921afa7ab4895814f6130fd85aea549c345a109';

package/src/examples/emitCustomEvent.ts

@@ -0,0 +1,75 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk } from '../index.js';
+import type { Address } from '../types.js';
+
+import { BASE_URL } from './config.js';
+
+// Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
+const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
+
+export interface EmitCustomEventInput {
+  readonly owner: Address;
+}
+
+/**
+ * Emit a custom on-chain event from a compose flow.
+ *
+ * Demonstrates:
+ * - core.emitEvent2 — surfacing an arbitrary `Rebalance(address,uint256)` event
+ * - Binding mixed-type handles (an `address` context ref and a `uint256` read)
+ *   directly to the op's `bytes32` value ports — no `raw.ref` cast, because
+ *   bytes32 ports are the raw 32-byte word type and accept any static-32-byte
+ *   handle.
+ *
+ * The emitted log is a fixed VM event whose first data word is
+ * keccak256("Rebalance(address,uint256)") (a discriminator), followed by the
+ * execution address and the vault total — an indexer reads the discriminator
+ * to recognise the event and decodes the two values.
+ */
+export const buildEmitCustomEvent = ({
+  owner,
+}: EmitCustomEventInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'emit-custom-event',
+    inputs: {},
+  });
+
+  // Read the vault's total assets at execution time — a fresh uint256 handle.
+  const vaultTotal = builder.core.staticCall('vault-total', {
+    bind: {},
+    config: {
+      target: VAULT,
+      functionSignature: 'function totalAssets() view returns (uint256)',
+    },
+  });
+
+  // Emit Rebalance(address,uint256): the executing address plus the vault total.
+  // value0 (address) and value1 (uint256) bind directly to the bytes32 ports.
+  builder.core.emitEvent2('log-rebalance', {
+    bind: {
+      value0: builder.context.executionAddress,
+      value1: vaultTotal.result,
+    },
+    config: {
+      signature: 'Rebalance(address,uint256)',
+    },
+  });
+
+  const flow = builder.build();
+
+  // No `sweepTo`: this flow only reads and emits a log — it moves no funds, so
+  // there are no proxy-held terminal resources to sweep. Specifying `sweepTo`
+  // here would fail compilation with "no ... terminal resources ... to sweep".
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {},
+  });
+
+  return { flow, request };
+};

package/src/examples/invariantChecks.ts

@@ -0,0 +1,96 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../index.js';
+import type { Address } from '../types.js';
+
+import { BASE_URL } from './config.js';
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+export interface InvariantChecksInput {
+  readonly owner: Address;
+  readonly spender: Address;
+  readonly amount: `${bigint}`;
+  readonly minAmountOut: `${bigint}`;
+}
+
+/**
+ * Swap WETH → USDC via LI.FI, then layer two of the newly-exposed invariant
+ * ops on the result.
+ *
+ * Demonstrates:
+ * - `invariant.gte` asserting the swap output is at least a constant threshold
+ *   (`amountOut >= minAmountOut`) — the per-comparison shorthand for
+ *   `invariant.numeric` with `{ op: 'gte' }`, so the comparison lives in the op
+ *   name and the config is just `{ threshold }`.
+ * - `invariant.allowanceAtLeast` asserting the execution proxy still permits
+ *   `spender` to move at least the swapped USDC on its behalf.
+ * - Binding a swap's `amountOut` resource handle into both a `uint256` numeric
+ *   slot and a `resource` allowance slot.
+ *
+ * Both ops compile to on-chain `AssertRawInvariant` instructions; the run
+ * reverts if either assertion is violated.
+ */
+export const buildInvariantChecks = ({
+  owner,
+  spender,
+  amount,
+  minAmountOut,
+}: InvariantChecksInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  // One WETH resource input plus a scalar spender address.
+  const builder = sdk.flow(1, {
+    name: 'invariant-checks',
+    inputs: {
+      amountIn: resources.erc20(WETH, 1),
+      spender: 'address',
+    },
+  });
+
+  // Swap WETH → USDC via LI.FI.
+  const swapOutputs = builder.lifi.swap('swap', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: {
+      resourceOut: resources.erc20(USDC, 1),
+      slippage: 0.03,
+    },
+  });
+
+  // Assert the swap produced at least `minAmountOut` USDC. The threshold is a
+  // configured constant, so this is a numeric (not handle-vs-handle) compare;
+  // `invariant.gte` is the shorthand that bakes the comparison into the op id.
+  builder.invariant.gte('min-out', {
+    bind: { value: swapOutputs.amountOut },
+    config: { threshold: minAmountOut },
+  });
+
+  // Assert the execution proxy still grants `spender` an allowance of at least
+  // the swapped USDC amount.
+  builder.invariant.allowanceAtLeast('check-allowance', {
+    bind: {
+      minimumAmount: swapOutputs.amountOut,
+      owner: builder.context.executionAddress,
+      spender: builder.inputs.spender,
+    },
+  });
+
+  const flow = builder.build();
+
+  // directDeposit marks amountIn as a fixed amount of WETH pre-deposited into
+  // the VM; the spender address is supplied as a plain scalar input.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount }),
+      spender,
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};