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

package/src/examples/aaveRepayWithATokens.ts

@@ -0,0 +1,81 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import {
+  createComposeSdk,
+  materialisers,
+  preconditions,
+  resources,
+} from '../index.js';
+import type { Address } from '../types.js';
+
+import { BASE_URL } from './config.js';
+
+// Aave v3 contracts on Ethereum mainnet.
+const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
+
+export interface AaveRepayWithATokensInput {
+  readonly owner: Address;
+  readonly proxyAddress: Address;
+  readonly expectedATokenBalance: `${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.
+ *
+ * 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).
+ */
+export const buildAaveRepayWithATokens = ({
+  owner,
+  proxyAddress,
+  expectedATokenBalance,
+}: AaveRepayWithATokensInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'aave-repay-with-atokens',
+    inputs: {
+      aTokenIn: resources.erc20(A_ETH_USDC, 1),
+    },
+  });
+
+  builder.aave.repayWithATokens('repay-atokens', {
+    bind: { aTokenIn: builder.inputs.aTokenIn },
+    config: {
+      pool: AAVE_V3_POOL,
+      asset: USDC,
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      aTokenIn: materialisers.balanceOf({ owner: proxyAddress }),
+    },
+    preconditions: [
+      preconditions.erc20Balance({
+        wallet: proxyAddress,
+        token: A_ETH_USDC,
+        balance: expectedATokenBalance,
+      }),
+    ],
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/aaveSetEMode.ts

@@ -0,0 +1,68 @@
+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';
+
+// Aave v3 contracts on Ethereum mainnet.
+const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
+
+// Mainnet ETH-correlated eMode category. Categories are per-pool; check
+// `Pool.getEModeCategoryData(id)` on the target chain before reusing this id.
+const ETH_CORRELATED_CATEGORY = 1;
+
+export interface AaveSetEModeInput {
+  readonly owner: Address;
+}
+
+/**
+ * Switch the executionAddress's Aave v3 eMode category.
+ *
+ * eMode is a per-user setting on the pool that allows higher LTV when both
+ * collateral and debt are correlated assets (e.g. ETH-LSTs, stablecoins).
+ * The setting persists across transactions until changed again.
+ *
+ * Demonstrates:
+ * - `aave.setEMode` as a side-effecting op with no resource inputs or outputs.
+ * - The op's category is validated at request-validation time against the
+ *   protocol's uint8 range. Per-pool category existence (Ethereum has 40+
+ *   categories, Base has 15+, Arbitrum 10+; new ones are added by governance)
+ *   is verified at simulation time, not in the schema.
+ *
+ * Real flows typically combine this op with `aave.supply` + `aave.borrow` of
+ * correlated assets. The reset call (`category: 0`) is intentionally omitted —
+ * leaving eMode on persists the leveraged position past the tx, and resetting
+ * to 0 after a high-LTV borrow would revert with a sub-1 health factor.
+ */
+export const buildAaveSetEMode = ({
+  owner,
+}: AaveSetEModeInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'aave-set-emode',
+    inputs: {},
+  });
+
+  builder.aave.setEMode('enter-eth-emode', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL,
+      category: ETH_CORRELATED_CATEGORY,
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {},
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/run.ts

@@ -8,12 +8,16 @@
  *   LIFI_API_KEY=your-key COMPOSER_BASE_URL=https://composer.li.quest yarn example <name>
  *
  * Available examples:
+ *   aave-repay        — repay an Aave v3 WETH debt by supplying WETH
+ *   aave-repay-atoken — repay an Aave v3 USDC debt by burning proxy aTokens
+ *   aave-claim        — claim AAVE rewards and forward to a recipient
  *   approve-deposit   — approve vault allowance then deposit USDC
  *   consolidate       — consolidate ERC-20 balances to USDC
  *   consolidate-eth   — consolidate ERC-20 balances to native ETH
  *   deposit-proxy     — deposit tokens already on the proxy into Aave
  *   dust-sweep        — split USDC 80/20 and sweep leftover dust
  *   swap              — swap WETH to USDC via LI.FI
+ *   swap-fee          — swap WETH to USDC with a 50 bps integrator fee
  *   split-zap         — split USDC 60/40 and zap into Aave + Morpho vaults
  *   split-arithmetic  — split USDC 70/30 with arithmetic assertions
  *   zap               — zap USDC into Aave lending position
@@ -35,6 +39,9 @@ import type { ComposeCompileRequest } from '@lifi/compose-spec';
 
 import { createComposeSdk } from '../sdk.js';
 
+import { buildAaveClaimRewards } from './aaveClaimRewards.js';
+import { buildAaveRepay } from './aaveRepay.js';
+import { buildAaveRepayWithATokens } from './aaveRepayWithATokens.js';
 import { buildApproveAndDeposit } from './approveAndDeposit.js';
 import {
   buildClaimRewards,
@@ -56,11 +63,22 @@ import { buildSwapAndZapExample } from './swapAndZap.js';
 import { buildSwapToRecipient } from './swapToRecipient.js';
 import { buildSwapWithAllowRevertExample } from './swapWithAllowRevert.js';
 import { buildSwapWithBalanceCheck } from './swapWithBalanceCheck.js';
+import { buildSwapWithFeeExample } from './swapWithFee.js';
 import { buildSwapWithOutputValidation } from './swapWithOutputValidation.js';
 import { buildPartialTransfer, buildTransferTokens } from './transferTokens.js';
 import { buildUntypedOpWithTypedRef } from './untypedOpWithTypedRef.js';
 
 const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
+  'aave-repay': () =>
+    buildAaveRepay({ owner: OWNER, amount: '500000000000000000' }).request,
+  'aave-repay-atoken': () =>
+    buildAaveRepayWithATokens({
+      owner: OWNER,
+      proxyAddress: PROXY,
+      expectedATokenBalance: '1000000000',
+    }).request,
+  'aave-claim': () =>
+    buildAaveClaimRewards({ owner: OWNER, recipient: RECIPIENT }).request,
   'approve-deposit': () =>
     buildApproveAndDeposit({ owner: OWNER, amount: '1000000000' }).request,
   consolidate: () =>
@@ -87,6 +105,7 @@ const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
     }).request,
   'dust-sweep': () => buildDustSweepExample().request,
   swap: () => buildLifiSwapExample().request,
+  'swap-fee': () => buildSwapWithFeeExample().request,
   'split-zap': () => buildSplitAndZapExample().request,
   'split-arithmetic': () =>
     buildSplitWithArithmetic({ owner: OWNER, amount: '1000000000' }).request,
@@ -133,17 +152,35 @@ const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
 };
 
 const run = async () => {
-  const name = process.argv[2];
-  const builder = name ? EXAMPLES[name] : undefined;
+  const args = process.argv.slice(2);
+  const useStaged = args.includes('--staged');
+  const name = args.find((arg) => arg !== '--staged');
+
+  // Staged examples live under examples/staged/ and reference not-yet-prod
+  // definitions, so they are deliberately excluded from this production file's
+  // type-check. With --staged, pull their registry in via a NON-LITERAL dynamic
+  // import (kept `any` to tsc, so the staged files are not dragged into the
+  // production program). Requires the SDK to have been regenerated with
+  // `yarn generate --staged` first, so the staged ops/materialisers exist at
+  // runtime; run `yarn generate` afterwards to restore the production surface.
+  let examples: Record<string, () => ComposeCompileRequest> = EXAMPLES;
+  if (useStaged) {
+    const stagedModule = (await import(
+      `${import.meta.dirname}/staged/registry.js`
+    )) as { STAGED_EXAMPLES: Record<string, () => ComposeCompileRequest> };
+    examples = { ...EXAMPLES, ...stagedModule.STAGED_EXAMPLES };
+  }
+
+  const builder = name ? examples[name] : undefined;
 
   if (!builder) {
-    const valid = Object.keys(EXAMPLES).join(', ');
+    const valid = Object.keys(examples).join(', ');
     console.error(
       `Error: ${
         name ? `unknown example "${name}"` : 'no example specified'
       }\n` +
         `Valid examples: ${valid}\n` +
-        `Usage: COMPOSER_BASE_URL=https://composer.li.quest yarn example <name>`,
+        `Usage: COMPOSER_BASE_URL=https://composer.li.quest yarn example [--staged] <name>`,
     );
     process.exit(1);
   }

package/src/examples/staged/aaveBorrow.ts

@@ -0,0 +1,104 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, guards } from '../../index.js';
+import type { Address } from '../../types.js';
+import { BASE_URL } from '../config.js';
+
+// Aave v3 contracts on Ethereum mainnet.
+const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+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;
+  readonly amount: `${bigint}`;
+}
+
+/**
+ * Borrow USDC against existing Aave v3 collateral and transfer it to a recipient,
+ * with an on-chain health-factor guard that reverts if the post-borrow position
+ * is too thin.
+ *
+ * The proxy address must already hold supplied collateral. The borrow op
+ * exposes the borrowed amount as a tracked resource so downstream nodes can
+ * spend it.
+ *
+ * Demonstrates:
+ * - `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.
+ * - The `debtBalance` handle reports the post-borrow variable-debt balance
+ *   for the proxy.
+ * - `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.
+ */
+export const buildAaveBorrow = ({
+  owner,
+  recipient,
+  amount,
+}: AaveBorrowInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  // The flow takes no resource inputs — Aave hands us the borrowed asset.
+  const builder = sdk.flow(1, {
+    name: 'aave-borrow-usdc',
+    inputs: {
+      recipient: 'address',
+    },
+  });
+
+  const borrowOut = builder.aave.borrow('borrow', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL,
+      asset: USDC,
+      variableDebtToken: VDEBT_USDC,
+      amount,
+    },
+  });
+
+  // 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();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      recipient,
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/staged/aaveDebtRebalanceExactOut.ts

@@ -0,0 +1,301 @@
+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';
+
+// Base mainnet token addresses.
+const BASE_WETH = '0x4200000000000000000000000000000000000006';
+const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+// Circle EURC on Base (6 decimals).
+const BASE_EURC = '0x60a3E35Cc302bFA44Cb288Bc5a4F316Fdb1adb42';
+
+// Token decimals for the Paraswap BUY (raw-address requests require them).
+const EURC_DECIMALS = 6;
+const USDC_DECIMALS = 6;
+
+// Aave V3 on Base: pool + WETH aToken + variable-debt tokens for the old (USDC)
+// and new (EURC) debt assets. The variable-debt token only feeds aave.borrow
+// (to read the post-borrow debt balance); aave.repay infers the asset from its
+// bound input resource. Verified live against Pool.getReserveData on Base.
+const AAVE_V3_POOL_BASE = '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5';
+const A_BAS_WETH = '0xD4a0e0b9149BCee3C920d2E00b5dE09138fd8bb7';
+const VDEBT_BAS_USDC = '0x59dca05b6c26dbd64b5381374aAaC5CD05644C28';
+const VDEBT_BAS_EURC = '0x03D01595769333174036832e18fA2f17C74f8161';
+
+// Aave V3 flashloan premium (FLASHLOAN_PREMIUM_TOTAL) = 5 bps of principal.
+// Mirrors the builtins package's `computeDefaultFee('aave-v3', amount)`,
+// inlined so the example stays free of compose-internals imports (the SDK must
+// not cross the manifest boundary into the builtins package). Override if the
+// pool's premium has changed on-chain.
+const AAVE_V3_FEE_BPS = 5n;
+const BPS_DENOMINATOR = 10_000n;
+const computeAaveV3Fee = (principal: bigint): bigint =>
+  (principal * AAVE_V3_FEE_BPS) / BPS_DENOMINATOR;
+
+// Source-cap slippage on the EURC → USDC BUY, in basis points. This bounds how
+// much extra EURC Augustus may pull above the quoted source before refunding.
+// `newDebtBorrowAmount` must exceed the resulting `maxAmountIn`.
+const DEFAULT_MAX_SLIPPAGE_BPS = 100; // 1%
+
+export interface AaveDebtRebalanceExactOutInput {
+  readonly owner: Address;
+  /**
+   * WETH collateral used to seed the position (in smallest units, 18 decimals).
+   * In production the position already exists and this seed step is omitted —
+   * the collateral is never touched by the rebalance itself.
+   */
+  readonly collateralAmount: `${bigint}`;
+  /**
+   * Outstanding USDC debt to rebalance away from (6 decimals). The flashloan is
+   * sized to this; in production size it just above the live debt so the capped
+   * repay clears it after accrued interest.
+   */
+  readonly debtAmount: `${bigint}`;
+  /**
+   * EURC to borrow as the *new* debt (6 decimals). Sized as a *generous upper
+   * bound* — large enough that the exact-output BUY can always produce
+   * `debtAmount + aaveV3Fee` USDC even after `maxSlippageBps` of source slippage
+   * (i.e. `newDebtBorrowAmount > maxAmountIn`). The BUY pulls only what it needs;
+   * the unspent EURC is repaid straight back into the freshly-minted EURC debt,
+   * so the *net* new debt is the original USDC debt (in EURC terms) plus only
+   * the slippage/fee actually consumed — NOT the full upper bound.
+   * Note: EUR/USD is not 1:1 — size off a live BUY quote, e.g.
+   *   newDebtBorrowAmount ≈ ceil((debtAmount + aaveV3Fee) * eurcPerUsdc * (1 + slippage))
+   */
+  readonly newDebtBorrowAmount: `${bigint}`;
+  /** Optional source-cap slippage on the BUY, in bps (default 100 = 1%). */
+  readonly maxSlippageBps?: number;
+  /** Optional integrator label for analytics / fee capture. */
+  readonly partner?: string;
+  /** Optional fee recipient; required to actually receive a partner fee. */
+  readonly partnerAddress?: Address;
+  /** Optional fixed partner fee in bps (e.g. '50' = 0.5%); needs partnerAddress. */
+  readonly partnerFeeBps?: string;
+}
+
+/**
+ * Atomically **rebalance** (debt-swap) an Aave V3 position on Base from USDC
+ * debt into EURC debt — same protocol, same WETH collateral, only the debt
+ * *token* changes — using a native **exact-output** (Paraswap/Velora BUY) swap.
+ *
+ * This is the single-protocol "debt switch" pattern productised by Aave's
+ * `ParaSwapDebtSwapAdapter` and DeFi Saver's "Debt Switch": flashloan/borrow the
+ * new debt slightly over a cap, exact-out-swap to produce exactly the old debt
+ * owed, repay the old debt, then repay the leftover new asset back into the
+ * freshly-created new debt so lasting debt = only what was consumed. Contrast
+ * with `aaveToMorphoDebtMigrationWithSwapExactOut.ts`, which *migrates* the whole
+ * position across protocols (Aave → Morpho) and therefore needs a second
+ * flashloan to move the collateral; here the collateral never moves, so a single
+ * flashloan of the old debt token suffices.
+ *
+ * Why rebalance USDC → EURC: at the time of writing EURC's Base Aave V3 variable
+ * borrow APR (~3.87%) sits below USDC's (~4.28%), and a EUR-based borrower may
+ * also want the liability denominated in EUR to match income/assets (removing
+ * USD/EUR FX risk on the debt). The reward is the APR delta over the holding
+ * period; the cost is the Aave flashloan premium plus the realised swap
+ * slippage on the consumed notional only.
+ *
+ * Phase 1 — provision the starting position on Aave V3 (illustrative; omit in
+ * production where the position already exists):
+ * - User direct-deposits WETH.
+ * - `lifi.zap` supplies the WETH to Aave (WETH → aBasWETH routing edge).
+ * - `aave.borrow` mints the USDC debt being rebalanced; the borrowed USDC is
+ *   swept back to the signer as the user's existing loan proceeds.
+ *
+ * Phase 2 — rebalance USDC debt → EURC debt with one flashloan:
+ * - Flashloan (Aave V3, USDC) bridges the old-debt payoff before the new debt
+ *   exists.
+ * - `aave.repay(mode: 'max')` clears the USDC debt with the flashloan; Aave's
+ *   Pool clamps to the outstanding debt exactly, any cap residual is swept.
+ * - `aave.borrow` mints a *capped* (generously over-sized) `newDebtBorrowAmount`
+ *   of EURC against the same, still-supplied WETH collateral.
+ * - `paraswap.buy` buys *exactly* `debtAmount + aaveV3Fee` USDC with the borrowed
+ *   EURC, pulling only the EURC needed. `amountOut` is the exact figure that
+ *   settles the USDC flashloan leg; `unspentIn` is the refunded, unspent EURC.
+ * - `lifi.flashloanRepay` settles the USDC leg from `buy.amountOut` (no
+ *   feeBuffer: `amountOut == principal + fee` by construction).
+ * - `aave.repay(mode: 'max')` repays the unspent EURC (`buy.unspentIn`) straight
+ *   back into the freshly-minted EURC debt, unwinding the borrow buffer. Any
+ *   genuine over-repay surfaces through the repay op's `residual`, swept to the
+ *   signer.
+ *
+ * After execution the signer holds the same WETH collateral on Aave V3 with EURC
+ * debt equal to the original USDC debt (in EUR terms) plus only the consumed
+ * slippage/fee; the USDC debt is closed.
+ */
+export const buildAaveDebtRebalanceExactOut = ({
+  owner,
+  collateralAmount,
+  debtAmount,
+  newDebtBorrowAmount,
+  maxSlippageBps = DEFAULT_MAX_SLIPPAGE_BPS,
+  partner,
+  partnerAddress,
+  partnerFeeBps,
+}: AaveDebtRebalanceExactOutInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  // The USDC the BUY must produce: the flashloan principal plus the Aave V3
+  // flashloan premium. This is exactly what settles the debt flashloan leg.
+  const exactUsdcOut = (
+    BigInt(debtAmount) + computeAaveV3Fee(BigInt(debtAmount))
+  ).toString() as `${bigint}`;
+
+  const builder = sdk.flow(8453, {
+    name: 'aave-debt-rebalance-usdc-to-eurc-exact-out',
+    inputs: {
+      initialCollateral: resources.erc20(BASE_WETH, 8453),
+      // Single flashloan: the old (USDC) debt token. No collateral flashloan is
+      // needed because the WETH collateral never leaves Aave.
+      debtFlashloan: resources.erc20(BASE_USDC, 8453),
+    },
+  });
+
+  // --- Phase 1: provision the starting Aave V3 USDC borrow -----------------
+
+  // WETH → aBasWETH via the aave routing edge family (Aave V3 supply). The
+  // supplied collateral is never withdrawn — it backs the new EURC debt — so
+  // the aBasWETH output is intentionally left unconsumed AND unswept: it is the
+  // user's resulting collateral position and must stay on the (persistent,
+  // per-user) proxy. This is why the flow does NOT set a blanket `sweepTo`
+  // (which would try to transfer the aToken out and revert, since collateral
+  // backing an open debt cannot be moved); instead we explicitly transfer only
+  // the genuinely-loose tokens below.
+  builder.lifi.zap('supply-collateral', {
+    bind: { amountIn: builder.inputs.initialCollateral },
+    config: { resourceOut: resources.erc20(A_BAS_WETH, 8453) },
+  });
+
+  // Borrow the USDC debt being rebalanced. The proceeds are the user's loan;
+  // they remain as the proxy's residual USDC and are forwarded to the signer at
+  // the end of the flow (see `payout-borrow-proceeds`).
+  builder.aave.borrow('borrow-usdc-debt', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL_BASE,
+      asset: BASE_USDC,
+      variableDebtToken: VDEBT_BAS_USDC,
+      amount: debtAmount,
+    },
+  });
+
+  // --- Phase 2: rebalance USDC debt → EURC debt ----------------------------
+
+  // Settle the USDC debt with the flashloan. mode: 'max' makes Aave's Pool
+  // clamp paybackAmount to the outstanding debt exactly; unspent flashloan
+  // principal flows through the op's residual port (swept).
+  builder.aave.repay('repay-usdc-debt', {
+    bind: {
+      assetIn: builder.inputs.debtFlashloan,
+      onBehalfOf: builder.context.executionAddress,
+    },
+    config: { pool: AAVE_V3_POOL_BASE, mode: 'max' },
+  });
+
+  // Borrow a capped (generously over-sized) EURC amount against the same WETH
+  // collateral, now that the USDC debt is cleared. The over-borrow is
+  // intentional and is unwound below.
+  const borrowEurc = builder.aave.borrow('borrow-eurc-debt', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL_BASE,
+      asset: BASE_EURC,
+      variableDebtToken: VDEBT_BAS_EURC,
+      amount: newDebtBorrowAmount,
+    },
+  });
+
+  // Exact-output BUY: produce EXACTLY `exactUsdcOut` USDC from the borrowed
+  // EURC, pulling only the EURC needed and refunding the rest to the proxy
+  // (surfaced as `unspentIn`). `amountOut` is the exact figure that settles the
+  // USDC flashloan leg.
+  const buyUsdc = builder.paraswap.buy('buy-usdc-exact', {
+    bind: { amountIn: borrowEurc.borrowed },
+    config: {
+      resourceOut: resources.erc20(BASE_USDC, 8453),
+      exactAmountOut: exactUsdcOut,
+      srcDecimals: EURC_DECIMALS,
+      destDecimals: USDC_DECIMALS,
+      maxSlippageBps,
+      ...(partner !== undefined ? { partner } : {}),
+      ...(partnerAddress !== undefined ? { partnerAddress } : {}),
+      ...(partnerFeeBps !== undefined ? { partnerFeeBps } : {}),
+    },
+  });
+
+  // Settle the USDC flashloan leg with the exact BUY output. No feeBuffer:
+  // `amountOut == principal + fee` by construction.
+  builder.lifi.flashloanRepay('repay-debt-flashloan', {
+    bind: { funds: buyUsdc.amountOut },
+    config: { leg: 'debtFlashloan' },
+  });
+
+  // Unwind the over-borrow: repay the proxy's FULL residual EURC back into the
+  // freshly-minted EURC debt, so the new debt equals exactly the EURC the swap
+  // consumed. We read the live EURC balance rather than binding `buy.unspentIn`:
+  // unspentIn is only Augustus's refund (cap − used), but the proxy ALSO still
+  // holds the headroom we over-borrowed above the swap cap (borrow − cap), which
+  // Augustus never pulled. The live balance captures both, leaving zero idle.
+  // mode: 'exact' pulls precisely this balance (Aave clamps to min(balance,
+  // debt)); mode: 'max' would pass type(uint256).max and try to pull the whole
+  // outstanding debt, far exceeding the residual on the proxy, and revert.
+  const eurcResidual = builder.core.balanceOf('read-eurc-residual', {
+    bind: {},
+    config: { token: BASE_EURC },
+  });
+  builder.aave.repay('repay-eurc-remainder', {
+    bind: {
+      assetIn: eurcResidual.balance,
+      onBehalfOf: builder.context.executionAddress,
+    },
+    config: { pool: AAVE_V3_POOL_BASE, mode: 'exact' },
+  });
+
+  // Forward the genuinely-loose token — the residual USDC loan proceeds — to the
+  // signer. We read the proxy's LIVE USDC balance rather than the fixed borrowed
+  // amount: Aave's `mode: 'max'` USDC-debt repay overshoots the borrow by up to
+  // 1 wei (ray-math round-trip), so the proxy ends a wei short of `borrowed` —
+  // transferring a fixed amount would revert "transfer amount exceeds balance".
+  // The live balance always moves exactly what is there.
+  //
+  // We deliberately do NOT use a blanket `sweepTo`: the only other proxy-held
+  // balance is the aBasWETH collateral position, which cannot be transferred
+  // while the EURC debt is open (Aave's finalizeTransfer reverts). The position
+  // therefore stays on the persistent per-user proxy; we move out only the USDC.
+  const usdcResidual = builder.core.balanceOf('read-usdc-residual', {
+    bind: {},
+    config: { token: BASE_USDC },
+  });
+  builder.core.transfer('payout-borrow-proceeds', {
+    bind: {
+      amount: usdcResidual.balance,
+      recipient: builder.context.sender,
+    },
+    config: {},
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      initialCollateral: materialisers.directDeposit({
+        amount: collateralAmount,
+      }),
+      debtFlashloan: materialisers.flashloan({
+        providerKind: 'aave-v3',
+        amount: debtAmount,
+      }),
+    },
+    // No blanket `sweepTo`: the resulting aBasWETH collateral position stays on
+    // the proxy (it backs the open EURC debt and cannot be moved). The loose
+    // USDC proceeds are forwarded via the explicit `payout-borrow-proceeds`
+    // transfer above.
+  });
+
+  return { flow, request };
+};