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

package/src/examples/staged/aaveHealthFactorExplode.ts

@@ -0,0 +1,70 @@
+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';
+
+// Base mainnet Aave v3 Pool.
+const AAVE_V3_POOL = '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5';
+
+// 1.0 WAD (1e18) — minimum acceptable health factor.
+const MIN_HEALTH_FACTOR_WAD = '1000000000000000000';
+
+export interface AaveHealthFactorExplodeInput {
+  readonly signer: Address;
+}
+
+/**
+ * EXPLODE / DecomposeValue showcase.
+ *
+ * NOTE: currently disabled end-to-end. `aave.getHealthFactor` is in the
+ * default `DISABLED_COMPOSE_OPS` set on zap-backend because the EXPLODE
+ * opcode is not yet supported on-chain. The example still builds a valid
+ * Flow JSON (and its spec passes), but submitting the request to a backend
+ * with default config will fail at op resolution. Re-enable by unsetting
+ * `aave.getHealthFactor` in the backend's `DISABLED_COMPOSE_OPS` once
+ * contracts ship EXPLODE.
+ *
+ * Builds a minimal compose flow that:
+ * - StaticCalls `IPool.getUserAccountData(user)` on Aave v3 (Base)
+ * - Decomposes the returned 6-tuple via the EXPLODE opcode
+ * - Asserts `healthFactor >= 1.0 WAD` via `core.numericInvariant`
+ *
+ * The signer must hold an Aave v3 position on the target chain so HF > 0.
+ * Uses `allow-revert` so the compiled calldata is returned even if the
+ * assertion would fail — handy for tracing on a fork.
+ */
+export const buildAaveHealthFactorExplode = ({
+  signer,
+}: AaveHealthFactorExplodeInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(8453 /* Base */, {
+    name: 'aave-hf-explode-showcase',
+    inputs: {},
+  });
+
+  builder.aave.getHealthFactor('checkHf', {
+    bind: {},
+    config: { pool: AAVE_V3_POOL, user: signer },
+    guards: [
+      guards.coreNumericInvariant({
+        port: 'healthFactor',
+        op: 'gte',
+        threshold: MIN_HEALTH_FACTOR_WAD,
+      }),
+    ],
+  });
+
+  const flow = builder.build();
+  const request = sdk.request(flow, {
+    signer,
+    inputs: {},
+    simulationPolicy: 'allow-revert',
+  });
+
+  return { flow, request };
+};

package/src/examples/staged/aaveToMorphoDebtMigration.ts

@@ -0,0 +1,190 @@
+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';
+
+// Aave V3 on Base (pool + aWETH receipt + variable-debt USDC).
+const AAVE_V3_POOL_BASE = '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5';
+const A_BAS_WETH = '0xD4a0e0b9149BCee3C920d2E00b5dE09138fd8bb7';
+const VDEBT_BAS_USDC = '0x59dca05b6c26dbd64b5381374aAaC5CD05644C28';
+
+// Morpho Blue WETH/USDC market on Base (same parameters as the
+// `morphoBlueBorrow` / `morphoBlueRepay` examples).
+const ADAPTIVE_CURVE_IRM_BASE = '0x46415998764C29aB2a25CbeA6254146D50D22687';
+const WETH_USDC_ORACLE = '0xFEa2D58cEfCb9fcb597723c6bAE66fFE4193aFE4';
+const WETH_USDC_LLTV = '860000000000000000';
+
+const MORPHO_WETH_USDC_MARKET = {
+  loanToken: BASE_USDC,
+  collateralToken: BASE_WETH,
+  oracle: WETH_USDC_ORACLE,
+  irm: ADAPTIVE_CURVE_IRM_BASE,
+  lltv: WETH_USDC_LLTV,
+};
+
+export interface AaveToMorphoDebtMigrationInput {
+  readonly owner: Address;
+  /** WETH collateral the user posts (in smallest units). */
+  readonly collateralAmount: `${bigint}`;
+  /** USDC principal borrowed from Aave (in smallest units). */
+  readonly debtAmount: `${bigint}`;
+  /**
+   * Aave-V3 flashloan fee on `debtAmount` — equals
+   * `computeDefaultFee('aave-v3', debtAmount)` (5 bps of the principal).
+   */
+  readonly debtFlashloanFee: `${bigint}`;
+}
+
+/**
+ * Atomically provision an Aave V3 borrow position on Base and migrate it to
+ * a Morpho Blue WETH/USDC market — all in a single compose flow driven by
+ * two concurrent flashloans.
+ *
+ * Phase 1 — provision the source position on Aave V3:
+ * - User direct-deposits WETH.
+ * - `lifi.zap` supplies the WETH to Aave (WETH → aBasWETH routing edge).
+ * - `aave.borrow` mints USDC debt; the borrowed USDC stays on the proxy
+ *   and is swept back to the signer as the user's loan proceeds.
+ *
+ * Phase 2 — migrate the position to Morpho using two concurrent flashloans:
+ * - Flashloan #1 (Aave V3, USDC) bridges the Aave debt payoff before the
+ *   Morpho borrow exists.
+ * - Flashloan #2 (Balancer V2, WETH) bridges the Morpho collateral supply
+ *   before the Aave collateral is freed.
+ * - `aave.repay` clears the Aave USDC debt with flashloan #1.
+ * - `lifi.zap` withdraws the freed WETH from Aave (aBasWETH → WETH).
+ * - `morphoBlue.supplyCollateral` deposits flashloan #2's WETH into Morpho.
+ * - `morphoBlue.borrow` mints exactly `debtAmount + debtFlashloanFee` USDC
+ *   so the `borrowed` resource settles flashloan #1 with zero residual.
+ * - Two `lifi.flashloanRepay` ops settle each leg: the USDC leg from the
+ *   Morpho borrow, the WETH leg from the Aave withdrawal (Balancer V2
+ *   charges no fee, so the principal alone covers it).
+ *
+ * After execution the signer holds `debtAmount` USDC and an open Morpho
+ * Blue position (`collateralAmount` WETH collateral, `debtAmount +
+ * debtFlashloanFee` USDC debt). The Aave position is closed.
+ */
+export const buildAaveToMorphoDebtMigration = ({
+  owner,
+  collateralAmount,
+  debtAmount,
+  debtFlashloanFee,
+}: AaveToMorphoDebtMigrationInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  // Morpho borrow must equal principal + Aave-V3 flashloan fee so the
+  // `borrowed` resource exactly settles the USDC flashloan leg.
+  const morphoBorrowAmount = (
+    BigInt(debtAmount) + BigInt(debtFlashloanFee)
+  ).toString() as `${bigint}`;
+
+  const builder = sdk.flow(8453, {
+    name: 'aave-to-morpho-debt-migration',
+    inputs: {
+      initialCollateral: resources.erc20(BASE_WETH, 8453),
+      debtFlashloan: resources.erc20(BASE_USDC, 8453),
+      collateralFlashloan: resources.erc20(BASE_WETH, 8453),
+    },
+  });
+
+  // --- Phase 1: provision the Aave V3 borrow position ----------------------
+
+  // WETH → aBasWETH via the aave routing edge family (Aave V3 supply).
+  const supplyToAave = builder.lifi.zap('supply-to-aave', {
+    bind: { amountIn: builder.inputs.initialCollateral },
+    config: { resourceOut: resources.erc20(A_BAS_WETH, 8453) },
+  });
+
+  // Borrow USDC against the freshly supplied collateral. The `borrowed`
+  // resource is left unbound; request-level `sweepTo` forwards it to the
+  // signer as the user's loan proceeds.
+  builder.aave.borrow('borrow-from-aave', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL_BASE,
+      asset: BASE_USDC,
+      variableDebtToken: VDEBT_BAS_USDC,
+      amount: debtAmount,
+    },
+  });
+
+  // --- Phase 2: migrate to Morpho with two concurrent flashloans -----------
+
+  // Settle the Aave USDC debt with flashloan #1. mode: 'max' makes Aave's
+  // Pool clamp paybackAmount to userVariableDebt exactly, so any unspent
+  // flashloan principal flows through the op's residual port (swept by the
+  // request-level sweepTo).
+  builder.aave.repay('repay-aave', {
+    bind: {
+      assetIn: builder.inputs.debtFlashloan,
+      onBehalfOf: builder.context.executionAddress,
+    },
+    config: { pool: AAVE_V3_POOL_BASE, mode: 'max' },
+  });
+
+  // Withdraw the freed WETH from Aave (aBasWETH → WETH) via routing.
+  const withdrawFromAave = builder.lifi.zap('withdraw-from-aave', {
+    bind: { amountIn: supplyToAave.amountOut },
+    config: { resourceOut: resources.erc20(BASE_WETH, 8453) },
+  });
+
+  // Open the Morpho Blue position with flashloan #2's WETH.
+  builder.morphoBlue.supplyCollateral('supply-to-morpho', {
+    bind: { assetIn: builder.inputs.collateralFlashloan },
+    config: { marketParams: MORPHO_WETH_USDC_MARKET, mode: 'exact' },
+  });
+
+  // Borrow exactly principal + fee from Morpho to settle the USDC leg.
+  const morphoBorrow = builder.morphoBlue.borrow('borrow-from-morpho', {
+    bind: {},
+    config: {
+      marketParams: MORPHO_WETH_USDC_MARKET,
+      amount: morphoBorrowAmount,
+    },
+  });
+
+  // Settle the USDC flashloan leg with the Morpho borrow.
+  builder.lifi.flashloanRepay('repay-debt-flashloan', {
+    bind: { funds: morphoBorrow.borrowed },
+    config: { leg: 'debtFlashloan' },
+  });
+
+  // Settle the WETH flashloan leg with the Aave withdrawal. Balancer V2
+  // charges no fee, so the withdrawn principal alone covers the leg.
+  builder.lifi.flashloanRepay('repay-collateral-flashloan', {
+    bind: { funds: withdrawFromAave.amountOut },
+    config: { leg: 'collateralFlashloan' },
+  });
+
+  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,
+      }),
+      collateralFlashloan: materialisers.flashloan({
+        providerKind: 'balancer-v2',
+        amount: collateralAmount,
+      }),
+    },
+    // Sweep the Aave borrow proceeds (and any aave.repay residual) to the
+    // signer.
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/staged/aaveToMorphoDebtMigrationWithSwap.ts

@@ -0,0 +1,221 @@
+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';
+
+// Aave V3 on Base (pool + aWETH receipt + variable-debt USDC).
+const AAVE_V3_POOL_BASE = '0xA238Dd80C259a72e81d7e4664a9801593F98d1c5';
+const A_BAS_WETH = '0xD4a0e0b9149BCee3C920d2E00b5dE09138fd8bb7';
+const VDEBT_BAS_USDC = '0x59dca05b6c26dbd64b5381374aAaC5CD05644C28';
+
+// Morpho Blue WETH/EURC market on Base. Real listed market — borrow APY
+// ~1.02% at the time of writing vs ~5.30% on the WETH/USDC market, which is
+// what makes this migration economically interesting. Market ID:
+// 0xa9b5142fa687a24c275faf731f13b52faa9873252bb4e1cb6077aa1f412edb0b
+// (= keccak256(MarketParams) of the values below).
+const ADAPTIVE_CURVE_IRM_BASE = '0x46415998764C29aB2a25CbeA6254146D50D22687';
+const WETH_EURC_ORACLE = '0xE1bb8E5b4930eC9FeC7f7943FCF6227649F14B37';
+const WETH_EURC_LLTV = '860000000000000000';
+
+const MORPHO_WETH_EURC_MARKET = {
+  loanToken: BASE_EURC,
+  collateralToken: BASE_WETH,
+  oracle: WETH_EURC_ORACLE,
+  irm: ADAPTIVE_CURVE_IRM_BASE,
+  lltv: WETH_EURC_LLTV,
+};
+
+// Slippage budget on the EURC → USDC swap. The caller must size
+// `morphoBorrowAmount` such that the swap's slippage-adjusted minimum covers
+// `debtAmount + computeDefaultFee('aave-v3', debtAmount)`.
+const SWAP_SLIPPAGE = 0.03;
+
+export interface AaveToMorphoDebtMigrationWithSwapInput {
+  readonly owner: Address;
+  /** WETH collateral the user posts (in smallest units, 18 decimals). */
+  readonly collateralAmount: `${bigint}`;
+  /** USDC principal borrowed from Aave (6 decimals). */
+  readonly debtAmount: `${bigint}`;
+  /**
+   * EURC to borrow from Morpho (6 decimals). Must be large enough that, after
+   * the EURC → USDC swap at `SWAP_SLIPPAGE`, the swap's minimum output covers
+   * `debtAmount + computeDefaultFee('aave-v3', debtAmount)`. Caller sizes this
+   * off-chain from a live LI.FI quote, e.g.
+   *   morphoBorrowAmount =
+   *     ceil((debtAmount + aaveV3Fee) * eurcPerUsdc / (1 - slippage))
+   * Note: EUR/USD is not 1:1 — the example fixture assumes ~1.075 USD/EUR.
+   */
+  readonly morphoBorrowAmount: `${bigint}`;
+}
+
+/**
+ * Atomically migrate an Aave V3 USDC borrow on Base into the Morpho Blue
+ * WETH/EURC market — same WETH collateral, different stablecoin debt. At the
+ * time of writing Morpho's WETH/EURC borrow APY is ~1.02% vs ~5.30% on
+ * USDC-denominated WETH-collateral markets, so a long-running borrow position
+ * can be made materially cheaper by migrating the debt asset.
+ *
+ * Topology mirrors `aaveToMorphoDebtMigration`, with one extra step: after
+ * Morpho mints EURC debt, the borrow proceeds are swapped to USDC via
+ * `lifi.swap`, and the swap's `amountOut` (which carries the slippage-adjusted
+ * minimum) settles the USDC flashloan leg.
+ *
+ * Phase 1 — provision the source position on Aave V3:
+ * - User direct-deposits WETH.
+ * - `lifi.zap` supplies the WETH to Aave (WETH → aBasWETH routing edge).
+ * - `aave.borrow` mints USDC debt; the borrowed USDC is swept back to the
+ *   signer as the user's loan proceeds.
+ *
+ * Phase 2 — migrate to Morpho using two concurrent flashloans:
+ * - Flashloan #1 (Aave V3, USDC) bridges the Aave debt payoff before the
+ *   Morpho borrow + swap exists.
+ * - Flashloan #2 (Balancer V2, WETH) bridges the Morpho collateral supply
+ *   before the Aave collateral is freed.
+ * - `aave.repay` clears the Aave USDC debt with flashloan #1.
+ * - `lifi.zap` withdraws the freed WETH from Aave (aBasWETH → WETH).
+ * - `morphoBlue.supplyCollateral` deposits flashloan #2's WETH into Morpho.
+ * - `morphoBlue.borrow` mints `morphoBorrowAmount` EURC.
+ * - `lifi.swap` converts the borrowed EURC into USDC. `amountOut` is the
+ *   slippage-adjusted minimum that settles the USDC flashloan leg.
+ * - Two `lifi.flashloanRepay` ops settle each leg: the USDC leg from the swap
+ *   output, the WETH leg from the Aave withdrawal (Balancer V2 charges no
+ *   fee, so the withdrawn principal alone covers it).
+ *
+ * After execution the signer holds a Morpho Blue position with
+ * `collateralAmount` WETH collateral and `morphoBorrowAmount` EURC debt; the
+ * Aave position is closed. Any EURC dust (Morpho residual above what the swap
+ * consumed) and USDC residual from `aave.repay`'s `mode: 'max'` clamp flow
+ * back to the signer via `sweepTo`.
+ */
+export const buildAaveToMorphoDebtMigrationWithSwap = ({
+  owner,
+  collateralAmount,
+  debtAmount,
+  morphoBorrowAmount,
+}: AaveToMorphoDebtMigrationWithSwapInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(8453, {
+    name: 'aave-to-morpho-debt-migration-with-swap',
+    inputs: {
+      initialCollateral: resources.erc20(BASE_WETH, 8453),
+      debtFlashloan: resources.erc20(BASE_USDC, 8453),
+      collateralFlashloan: resources.erc20(BASE_WETH, 8453),
+    },
+  });
+
+  // --- Phase 1: provision the Aave V3 borrow position ----------------------
+
+  // WETH → aBasWETH via the aave routing edge family (Aave V3 supply).
+  const supplyToAave = builder.lifi.zap('supply-to-aave', {
+    bind: { amountIn: builder.inputs.initialCollateral },
+    config: { resourceOut: resources.erc20(A_BAS_WETH, 8453) },
+  });
+
+  // Borrow USDC against the freshly supplied collateral. The `borrowed`
+  // resource is left unbound; request-level `sweepTo` forwards it to the
+  // signer as the user's loan proceeds.
+  builder.aave.borrow('borrow-from-aave', {
+    bind: {},
+    config: {
+      pool: AAVE_V3_POOL_BASE,
+      asset: BASE_USDC,
+      variableDebtToken: VDEBT_BAS_USDC,
+      amount: debtAmount,
+    },
+  });
+
+  // --- Phase 2: migrate to Morpho with two concurrent flashloans -----------
+
+  // Settle the Aave USDC debt with flashloan #1. mode: 'max' makes Aave's
+  // Pool clamp paybackAmount to userVariableDebt exactly, so any unspent
+  // flashloan principal flows through the op's residual port (swept by
+  // request-level sweepTo).
+  builder.aave.repay('repay-aave', {
+    bind: {
+      assetIn: builder.inputs.debtFlashloan,
+      onBehalfOf: builder.context.executionAddress,
+    },
+    config: { pool: AAVE_V3_POOL_BASE, mode: 'max' },
+  });
+
+  // Withdraw the freed WETH from Aave (aBasWETH → WETH) via routing.
+  const withdrawFromAave = builder.lifi.zap('withdraw-from-aave', {
+    bind: { amountIn: supplyToAave.amountOut },
+    config: { resourceOut: resources.erc20(BASE_WETH, 8453) },
+  });
+
+  // Open the Morpho Blue position with flashloan #2's WETH.
+  builder.morphoBlue.supplyCollateral('supply-to-morpho', {
+    bind: { assetIn: builder.inputs.collateralFlashloan },
+    config: { marketParams: MORPHO_WETH_EURC_MARKET, mode: 'exact' },
+  });
+
+  // Borrow EURC at the destination's (cheaper) APR.
+  const morphoBorrow = builder.morphoBlue.borrow('borrow-from-morpho', {
+    bind: {},
+    config: {
+      marketParams: MORPHO_WETH_EURC_MARKET,
+      amount: morphoBorrowAmount,
+    },
+  });
+
+  // Swap EURC → USDC so the borrow proceeds can settle the USDC flashloan
+  // leg. `amountOut` carries `providesMinimum: true`; the caller is
+  // responsible for sizing `morphoBorrowAmount` so the slippage-adjusted
+  // minimum covers `debtAmount + aaveV3Fee(debtAmount)`.
+  const swapDebt = builder.lifi.swap('swap-borrow-to-usdc', {
+    bind: { amountIn: morphoBorrow.borrowed },
+    config: {
+      resourceOut: resources.erc20(BASE_USDC, 8453),
+      slippage: SWAP_SLIPPAGE,
+    },
+  });
+
+  // Settle the USDC flashloan leg with the swap output.
+  builder.lifi.flashloanRepay('repay-debt-flashloan', {
+    bind: { funds: swapDebt.amountOut },
+    config: { leg: 'debtFlashloan' },
+  });
+
+  // Settle the WETH flashloan leg with the Aave withdrawal. Balancer V2
+  // charges no fee, so the withdrawn principal alone covers the leg.
+  builder.lifi.flashloanRepay('repay-collateral-flashloan', {
+    bind: { funds: withdrawFromAave.amountOut },
+    config: { leg: 'collateralFlashloan' },
+  });
+
+  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,
+      }),
+      collateralFlashloan: materialisers.flashloan({
+        providerKind: 'balancer-v2',
+        amount: collateralAmount,
+      }),
+    },
+    // Sweep Aave borrow proceeds, aave.repay's residual, and any EURC / USDC
+    // dust left after the swap back to the signer.
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};