@lifi/composer-sdk 0.2.0 → 0.4.0-staging.1

package/src/errors.ts

@@ -1,4 +1,9 @@
-import type { ComposeErrorKind, SimulationRevert } from '@lifi/compose-spec';
+import type {
+  ComposeErrorKind,
+  FailedPreparedOp,
+  GenericComposeErrorKind,
+  SimulationRevert,
+} from '@lifi/compose-spec';
 
 import {
   parseServerErrorBody,
@@ -62,6 +67,17 @@ export class ComposeError extends Error {
    * backend can parse the revert reason.
    */
   readonly details?: SimulationRevert;
+  /**
+   * The prepared ops that failed, attached to `preparation_error` errors.
+   * Each entry carries the `callId` of the failing node so callers can drop
+   * the unroutable legs and resubmit a smaller flow.
+   */
+  readonly failedOps?: readonly FailedPreparedOp[];
+  /**
+   * The `callId`s of the prepared ops that succeeded, attached to
+   * `preparation_error` errors alongside {@link ComposeError.failedOps}.
+   */
+  readonly succeededOps?: readonly string[];
 
   constructor(
     code: ComposeErrorCode,
@@ -73,6 +89,8 @@ export class ComposeError extends Error {
       kind?: ComposeErrorKind;
       path?: string;
       details?: SimulationRevert;
+      failedOps?: readonly FailedPreparedOp[];
+      succeededOps?: readonly string[];
     },
   ) {
     super(message, { cause: options?.cause });
@@ -82,9 +100,21 @@ export class ComposeError extends Error {
     this.kind = options?.kind;
     this.path = options?.path;
     this.details = options?.details;
+    this.failedOps = options?.failedOps;
+    this.succeededOps = options?.succeededOps;
   }
 }
 
+/**
+ * The per-op preparation diagnostics carried by `preparation_error` responses,
+ * with both arrays known to be present. Produced by narrowing with
+ * {@link isComposePreparationError}.
+ */
+export interface ComposePreparationOps {
+  readonly failedOps: readonly FailedPreparedOp[];
+  readonly succeededOps: readonly string[];
+}
+
 /**
  * Type guard that narrows an unknown error to {@link ComposeError}.
  * @param e - The value to check.
@@ -94,6 +124,35 @@ export const isComposeError = (e: unknown): e is ComposeError =>
   e instanceof ComposeError ||
   (e instanceof Error && e.name === 'ComposeError' && 'code' in e);
 
+/**
+ * Type guard for `preparation_error` failures (HTTP 422): a mixed basket where
+ * some prepared ops failed and others succeeded. Narrows both
+ * {@link ComposeError.failedOps} and {@link ComposeError.succeededOps} to
+ * present, so callers can read them without a cast or a truthiness check.
+ *
+ * @param e - The value to check.
+ * @returns `true` if `e` is a `ComposeError` carrying per-op preparation diagnostics.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await builder.compile(run);
+ * } catch (e) {
+ *   if (isComposePreparationError(e)) {
+ *     console.error('Failed ops:', e.failedOps);
+ *     console.error('Succeeded ops:', e.succeededOps);
+ *   }
+ * }
+ * ```
+ */
+export const isComposePreparationError = (
+  e: unknown,
+): e is ComposeError & ComposePreparationOps =>
+  isComposeError(e) &&
+  e.kind === 'preparation_error' &&
+  Array.isArray(e.failedOps) &&
+  Array.isArray(e.succeededOps);
+
 const STATUS_TO_CODE: ReadonlyMap<number, ComposeErrorCode> = new Map<
   number,
   ComposeErrorCode
@@ -143,6 +202,13 @@ export const errorFromHttpResponse = (
       kind: serverError?.kind as ComposeErrorKind | undefined,
       path: serverError?.path,
       details: serverError?.details,
+      // The wire schema types `kind` as a bare string; the server only ever
+      // reports generic kinds for individual ops.
+      failedOps: serverError?.failedOps?.map((op) => ({
+        ...op,
+        kind: op.kind as GenericComposeErrorKind,
+      })),
+      succeededOps: serverError?.succeededOps,
     },
   );
 };

package/src/examples/aaveClaimRewards.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Aave v3 incentives contracts on Ethereum mainnet.
 const REWARDS_CONTROLLER = '0x8164Cc65827dcFe994AB23944CBC90e0aa80bFcb';
@@ -37,7 +37,7 @@ export const buildAaveClaimRewards = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'aave-claim-rewards',

package/src/examples/aaveRepay.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Aave v3 contracts on Ethereum mainnet.
 const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
@@ -49,7 +49,7 @@ export const buildAaveRepay = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'aave-repay-weth',

package/src/examples/aaveRepayWithATokens.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Aave v3 contracts on Ethereum mainnet.
 const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
@@ -39,7 +39,7 @@ export const buildAaveRepayWithATokens = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'aave-repay-with-atokens',

package/src/examples/aaveSetEMode.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Aave v3 contracts on Ethereum mainnet.
 const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
@@ -41,7 +41,7 @@ export const buildAaveSetEMode = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'aave-set-emode',

package/src/examples/approveAndDeposit.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
@@ -30,7 +30,7 @@ export const buildApproveAndDeposit = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'approve-and-deposit',

package/src/examples/callContract.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
 const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
@@ -31,7 +31,7 @@ export const buildRedeemFromVault = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'redeem-from-vault',
@@ -103,7 +103,7 @@ export const buildClaimRewards = ({
   const REWARDS_CONTRACT = '0x1111111111111111111111111111111111111111';
   const REWARD_TOKEN = '0x2222222222222222222222222222222222222222';
 
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'claim-rewards',
@@ -154,7 +154,7 @@ export const buildWrapEth = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'wrap-eth',

package/src/examples/config.ts

@@ -2,7 +2,10 @@
 // built-in process.env.BASE_URL (set to "/" from the `base` config option).
 export const BASE_URL: string =
   process.env['COMPOSER_BASE_URL'] ?? 'https://composer.li.quest';
-export const API_KEY: string | undefined = process.env['LIFI_API_KEY'];
+// `apiKey` is required by `createComposeSdk`/`createComposeClient`; fall back to a
+// placeholder so the examples remain runnable (against a backend that accepts it)
+// without every contributor needing a real LI.FI API key set locally.
+export const API_KEY: string = process.env['LIFI_API_KEY'] ?? 'YOUR_API_KEY';
 
 export const OWNER = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
 export const RECIPIENT = '0x1234567890abcdef1234567890abcdef12345678';

package/src/examples/consolidateToEth.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 export interface ConsolidateToEthInput {
   readonly owner: Address;
@@ -38,7 +38,7 @@ export const buildConsolidateToEth = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
   const erc20 = (token: Address) => resources.erc20(token, CHAIN_ID);
 
   // Declare the flow with one input per ERC-20 token on Ethereum mainnet.

package/src/examples/consolidateToUsdc.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 export interface ConsolidateStablesToUsdcInput {
   readonly owner: Address;
@@ -39,7 +39,7 @@ export const buildConsolidateStablesToUsdc = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
   const erc20 = (token: Address) => resources.erc20(token, CHAIN_ID);
 
   // Declare the flow with one input per stablecoin on Ethereum mainnet.

package/src/examples/depositFromProxy.ts

@@ -9,7 +9,7 @@ import {
 } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Aave v3 aEthUSDC receipt token on Ethereum mainnet
@@ -45,7 +45,7 @@ export const buildDepositFromProxy = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'deposit-from-proxy',

package/src/examples/dustSweep.ts

@@ -2,7 +2,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
 import { createComposeSdk, materialisers, resources } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
 
@@ -23,7 +23,7 @@ export const buildDustSweepExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'dust-sweep',

package/src/examples/emitCustomEvent.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
 const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
@@ -33,7 +33,7 @@ export const buildEmitCustomEvent = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'emit-custom-event',

package/src/examples/invariantChecks.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
@@ -41,7 +41,7 @@ export const buildInvariantChecks = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // One WETH resource input plus a scalar spender address.
   const builder = sdk.flow(1, {

package/src/examples/lifiSwap.ts

@@ -2,7 +2,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
 import { createComposeSdk, materialisers, resources } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
@@ -19,7 +19,7 @@ export const buildLifiSwapExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // Declare the flow with a single WETH input on Ethereum mainnet.
   const builder = sdk.flow(1, {

package/src/examples/lifiZap.ts

@@ -7,7 +7,7 @@ import {
   resources,
 } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Aave aEthUSDC receipt token on Ethereum mainnet
 const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
@@ -24,7 +24,7 @@ export const buildLifiZapExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // Declare the flow with a single USDC input on Ethereum mainnet.
   const builder = sdk.flow(1, {

package/src/examples/rawCallWithArithmetic.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Example contract address for a non-standard oracle
 const ORACLE = '0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419';
@@ -27,7 +27,7 @@ export const buildRawCallWithArithmetic = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'raw-call-with-arithmetic',

package/src/examples/readContractState.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
@@ -28,7 +28,7 @@ export const buildReadContractState = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'read-contract-state',

package/src/examples/splitAndZap.ts

@@ -7,7 +7,7 @@ import {
   resources,
 } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Aave v3 aEthUSDC receipt token on Ethereum mainnet
 const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
@@ -26,7 +26,7 @@ export const buildSplitAndZapExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'split-usdc-to-two-vaults',

package/src/examples/splitWithArithmetic.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 
@@ -29,7 +29,7 @@ export const buildSplitWithArithmetic = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'split-with-arithmetic',

package/src/examples/staged/aaveBorrow.ts

@@ -0,0 +1,128 @@
+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';
+
+// 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';
+
+// 1.05 WAD (1e18) — minimum acceptable Aave health factor after the borrow.
+// The on-chain VM reverts the run if the post-borrow HF drops below this.
+const MIN_HEALTH_FACTOR_WAD = '1050000000000000000';
+
+export interface AaveBorrowInput {
+  readonly owner: Address;
+  readonly recipient: Address;
+  /** USDC supplied as collateral so the proxy can borrow (6 dp). */
+  readonly collateralAmount: `${bigint}`;
+  /** USDC borrowed against the collateral and sent to the recipient (6 dp). */
+  readonly borrowAmount: `${bigint}`;
+}
+
+/**
+ * Supply USDC to Aave v3, borrow USDC against it, and transfer the borrowed
+ * funds to a recipient — with an on-chain health-factor guard that reverts
+ * if the post-borrow position is too thin.
+ *
+ * The in-flow supply makes the example self-contained: the borrow is backed
+ * by collateral created in the same transaction, so it simulates cleanly
+ * for a fresh proxy. Keep `borrowAmount` comfortably below the collateral's
+ * borrowing power or the health-factor guard reverts the run.
+ *
+ * Demonstrates:
+ * - `lifi.zap` to supply USDC into Aave (USDC → aEthUSDC routing edge)
+ * - `aave.borrow` with no resource input — the borrowed asset materialises
+ *   as the `borrowed` resource output.
+ * - Chaining the borrow output into a `core.transfer` to forward funds.
+ * - `aave.getHealthFactor` + `core.numericInvariant` guard asserts that
+ *   `healthFactor >= MIN_HEALTH_FACTOR_WAD` after the borrow; the run reverts
+ *   on-chain if the threshold is violated.
+ *
+ * The supplied aEthUSDC stays on the proxy: it backs the open debt, and
+ * Aave rejects aToken transfers that would break the position's health
+ * factor, so it cannot be swept while the borrow is outstanding.
+ */
+export const buildAaveBorrow = ({
+  owner,
+  recipient,
+  collateralAmount,
+  borrowAmount,
+}: AaveBorrowInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  const builder = sdk.flow(1, {
+    name: 'aave-borrow-usdc',
+    inputs: {
+      collateralIn: resources.erc20(USDC, 1),
+      recipient: 'address',
+    },
+  });
+
+  // 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) },
+  });
+
+  const borrowOut = builder.aave.borrow('borrow', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL,
+      asset: USDC,
+      variableDebtToken: VDEBT_USDC,
+      amount: borrowAmount,
+    },
+  });
+
+  // Read the post-borrow Aave health factor and assert it stays above the
+  // minimum threshold. The numericInvariant guard lowers to an on-chain
+  // `AssertRawInvariant` IR1 instruction; the run reverts if HF < threshold.
+  builder.aave.getHealthFactor('hf', {
+    bind: {},
+    config: { pool: AAVE_V3_POOL },
+    guards: [
+      guards.coreNumericInvariant({
+        port: 'healthFactor',
+        op: 'gte',
+        threshold: MIN_HEALTH_FACTOR_WAD,
+      }),
+    ],
+  });
+
+  // Forward the freshly borrowed USDC to the recipient.
+  builder.core.transfer('send-borrowed', {
+    bind: {
+      amount: borrowOut.borrowed,
+      recipient: builder.inputs.recipient,
+    },
+    config: {},
+  });
+
+  const flow = builder.build();
+
+  // No sweepTo: the aEthUSDC collateral must stay on the proxy while the
+  // debt is open — Aave blocks aToken transfers that would leave the
+  // position undercollateralized.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      collateralIn: materialisers.directDeposit({ amount: collateralAmount }),
+      recipient,
+    },
+  });
+
+  return { flow, request };
+};