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

package/src/examples/staged/aaveBorrow.ts

@@ -1,12 +1,19 @@
 import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
-import { createComposeSdk, guards } from '../../index.js';
+import {
+  createComposeSdk,
+  guards,
+  materialisers,
+  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';
+// 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.
@@ -16,53 +23,67 @@ const MIN_HEALTH_FACTOR_WAD = '1050000000000000000';
 export interface AaveBorrowInput {
   readonly owner: Address;
   readonly recipient: Address;
-  readonly amount: `${bigint}`;
+  /** 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}`;
 }
 
 /**
- * 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.
+ * 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 proxy address must already hold supplied collateral. The borrow op
- * exposes the borrowed amount as a tracked resource so downstream nodes can
- * spend it.
+ * 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.
- * - 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.
+ *
+ * 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,
-  amount,
+  collateralAmount,
+  borrowAmount,
 }: 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: {
+      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,
+      amount: borrowAmount,
     },
   });
 
@@ -92,12 +113,15 @@ export const buildAaveBorrow = ({
 
   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,
     },
-    sweepTo: builder.context.sender,
   });
 
   return { flow, request };

package/src/examples/staged/aaveToMorphoDebtMigration.ts

@@ -2,6 +2,10 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
 import { createComposeSdk, materialisers, resources } from '../../index.js';
 import type { Address } from '../../types.js';
+import {
+  padForAaveDebtRounding,
+  trimForAaveWithdrawalRounding,
+} from '../aaveRounding.js';
 import { BASE_URL } from '../config.js';
 
 // Base mainnet token addresses.
@@ -80,10 +84,16 @@ export const buildAaveToMorphoDebtMigration = ({
 } => {
   const sdk = createComposeSdk({ baseUrl: BASE_URL });
 
+  // Both flashloan legs absorb Aave's 1-wei scaled-balance skew: the USDC
+  // leg funds a max-mode repay, the WETH leg is covered by a withdrawal.
+  const debtFlashloanAmount = padForAaveDebtRounding(debtAmount);
+  const collateralFlashloanAmount =
+    trimForAaveWithdrawalRounding(collateralAmount);
+
   // 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)
+    BigInt(debtFlashloanAmount) + BigInt(debtFlashloanFee)
   ).toString() as `${bigint}`;
 
   const builder = sdk.flow(8453, {
@@ -174,11 +184,11 @@ export const buildAaveToMorphoDebtMigration = ({
       }),
       debtFlashloan: materialisers.flashloan({
         providerKind: 'aave-v3',
-        amount: debtAmount,
+        amount: debtFlashloanAmount,
       }),
       collateralFlashloan: materialisers.flashloan({
         providerKind: 'balancer-v2',
-        amount: collateralAmount,
+        amount: collateralFlashloanAmount,
       }),
     },
     // Sweep the Aave borrow proceeds (and any aave.repay residual) to the

package/src/examples/staged/aaveToMorphoDebtMigrationWithSwap.ts

@@ -2,6 +2,10 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
 import { createComposeSdk, materialisers, resources } from '../../index.js';
 import type { Address } from '../../types.js';
+import {
+  padForAaveDebtRounding,
+  trimForAaveWithdrawalRounding,
+} from '../aaveRounding.js';
 import { BASE_URL } from '../config.js';
 
 // Base mainnet token addresses.
@@ -105,6 +109,12 @@ export const buildAaveToMorphoDebtMigrationWithSwap = ({
 } => {
   const sdk = createComposeSdk({ baseUrl: BASE_URL });
 
+  // Both flashloan legs absorb Aave's 1-wei scaled-balance skew: the USDC
+  // leg funds a max-mode repay, the WETH leg is covered by a withdrawal.
+  const debtFlashloanAmount = padForAaveDebtRounding(debtAmount);
+  const collateralFlashloanAmount =
+    trimForAaveWithdrawalRounding(collateralAmount);
+
   const builder = sdk.flow(8453, {
     name: 'aave-to-morpho-debt-migration-with-swap',
     inputs: {
@@ -205,11 +215,11 @@ export const buildAaveToMorphoDebtMigrationWithSwap = ({
       }),
       debtFlashloan: materialisers.flashloan({
         providerKind: 'aave-v3',
-        amount: debtAmount,
+        amount: debtFlashloanAmount,
       }),
       collateralFlashloan: materialisers.flashloan({
         providerKind: 'balancer-v2',
-        amount: collateralAmount,
+        amount: collateralFlashloanAmount,
       }),
     },
     // Sweep Aave borrow proceeds, aave.repay's residual, and any EURC / USDC

package/src/examples/staged/aaveToMorphoDebtMigrationWithSwapExactOut.ts

@@ -273,6 +273,10 @@ export const buildAaveToMorphoDebtMigrationWithSwapExactOut = ({
 
   const flow = builder.build();
 
+  const assumptions: Record<string, bigint> = {
+    'buy-usdc-exact.amountIn': BigInt(morphoBorrowAmount),
+  };
+
   const request = sdk.request(flow, {
     signer: owner,
     inputs: {
@@ -296,6 +300,7 @@ export const buildAaveToMorphoDebtMigrationWithSwapExactOut = ({
     // Sweep Aave borrow proceeds, aave.repay's residual, and any EURC over-repay
     // residual from the capped Morpho repay back to the signer.
     sweepTo: builder.context.sender,
+    assumptions,
   });
 
   return { flow, request };

package/src/examples/staged/flashloanRepay.ts

@@ -69,6 +69,10 @@ export const buildTrivialFlashloanRepay = ({
       }),
       feeTopUp: materialisers.directDeposit({ amount: fee }),
     },
+    // The smoke flow returns the full principal + fee to the adapter and
+    // produces no user output, so the guard sees the fee top-up as 100%
+    // loss. 0 skips the check; the user's real cost is only the provider fee.
+    maxPriceImpactBps: 0,
   });
 
   return { flow, request };

package/src/examples/staged/morphoBlueBorrow.ts

@@ -83,6 +83,10 @@ export const buildMorphoBlueBorrow = ({
     },
     // Sweep the borrowed USDC back to the signer.
     sweepTo: builder.context.sender,
+    // The WETH collateral becomes unpriced Morpho position state (no receipt
+    // token), so the default 500 bps price-impact check reads any safe borrow
+    // (LLTV caps at 86%) as a loss. 0 skips the check.
+    maxPriceImpactBps: 0,
   });
 
   return { flow, request };

package/src/examples/staged/morphoBlueRepay.ts

@@ -21,27 +21,41 @@ const WETH_USDC_MARKET = {
 
 export interface MorphoBlueRepayInput {
   readonly owner: Address;
-  readonly repayAmount: `${bigint}`;
+  /** WETH supplied as collateral for the in-flow borrow (18 dp). */
   readonly collateralAmount: `${bigint}`;
+  /** USDC borrowed against the collateral, then repaid by this flow (6 dp). */
+  readonly borrowAmount: `${bigint}`;
+  /**
+   * USDC deposited to repay the debt (6 dp). Must exceed `borrowAmount`:
+   * Morpho's share rounding can leave the debt a wei above the borrowed
+   * amount, so the `max`-mode repay needs a little headroom. The leftover
+   * surfaces on the `residual` port.
+   */
+  readonly repayAmount: `${bigint}`;
 }
 
 /**
- * Close a Morpho Blue WETH/USDC position on Base:
+ * Open and close a Morpho Blue WETH/USDC position on Base in one flow —
+ * a self-contained supplyCollateral → borrow → repay → withdrawCollateral
+ * round trip that creates the debt it retires.
  *
- * - User direct-deposits USDC (slightly over-funded to exercise the residual
- *   port).
- * - `morphoBlue.repay` with `mode: 'max'` reads the proxy's current
- *   `borrowShares` via a precursor `Morpho.position` static call and passes
- *   the share count back into `repay` to retire the debt to the wei. Any
- *   unused USDC surfaces on the `residual` Resource port.
- * - `morphoBlue.withdrawCollateral` pulls the freed WETH back to the signer's
- *   wallet.
- * - The flow sweeps both the freed WETH and the USDC residual to the signer.
+ * Demonstrates:
+ * - `morphoBlue.supplyCollateral` to post WETH (collateral is internal
+ *   position state — no receipt token).
+ * - `morphoBlue.borrow` to mint USDC debt against it.
+ * - `morphoBlue.repay` with `mode: 'max'`, which reads the proxy's current
+ *   `borrowShares` on-chain and repays in shares mode to retire the debt to
+ *   the wei. Unused USDC surfaces on the `residual` Resource port.
+ * - `morphoBlue.withdrawCollateral` to pull the freed WETH once the debt
+ *   is cleared.
+ * - `sweepTo` to return the borrowed USDC, the repay residual, and the
+ *   freed WETH to the signer.
  */
 export const buildMorphoBlueRepay = ({
   owner,
-  repayAmount,
   collateralAmount,
+  borrowAmount,
+  repayAmount,
 }: MorphoBlueRepayInput): {
   flow: Flow;
   request: ComposeCompileRequest;
@@ -51,13 +65,38 @@ export const buildMorphoBlueRepay = ({
   const builder = sdk.flow(8453, {
     name: 'morpho-blue-repay-usdc-withdraw-weth',
     inputs: {
-      assetIn: resources.erc20(BASE_USDC, 8453),
+      collateralIn: resources.erc20(BASE_WETH, 8453),
+      repayIn: resources.erc20(BASE_USDC, 8453),
+    },
+  });
+
+  // Post WETH collateral so the proxy can open the debt it will repay.
+  builder.morphoBlue.supplyCollateral('supply-collateral', {
+    bind: {
+      assetIn: builder.inputs.collateralIn,
+    },
+    config: {
+      marketParams: WETH_USDC_MARKET,
+      mode: 'exact',
+    },
+  });
+
+  // Borrow USDC against the collateral; the borrowed USDC stays on the
+  // proxy as a terminal resource and is swept back to the signer.
+  builder.morphoBlue.borrow('borrow', {
+    bind: {},
+    config: {
+      marketParams: WETH_USDC_MARKET,
+      amount: borrowAmount,
     },
   });
 
+  // Retire the just-opened debt from the deposited USDC. mode 'max' reads
+  // the live borrowShares and repays in shares mode, clearing the debt to
+  // the wei; the unused USDC surfaces on the `residual` port.
   builder.morphoBlue.repay('repay', {
     bind: {
-      assetIn: builder.inputs.assetIn,
+      assetIn: builder.inputs.repayIn,
       onBehalfOf: builder.context.executionAddress,
     },
     config: {
@@ -66,8 +105,8 @@ export const buildMorphoBlueRepay = ({
     },
   });
 
-  // The withdrawn WETH lands on the proxy; the request-level `sweepTo`
-  // pushes it (and the USDC `residual` from the repay) to the signer.
+  // The debt is cleared, so the full collateral can be withdrawn. The freed
+  // WETH lands on the proxy and is swept to the signer.
   builder.morphoBlue.withdrawCollateral('withdraw-collateral', {
     bind: {},
     config: {
@@ -81,9 +120,11 @@ export const buildMorphoBlueRepay = ({
   const request = sdk.request(flow, {
     signer: owner,
     inputs: {
-      assetIn: materialisers.directDeposit({ amount: repayAmount }),
+      collateralIn: materialisers.directDeposit({ amount: collateralAmount }),
+      repayIn: materialisers.directDeposit({ amount: repayAmount }),
     },
-    // Sweep freed WETH and the USDC residual back to the signer.
+    // Sweep the borrowed USDC, the repay residual, and the freed WETH back
+    // to the signer.
     sweepTo: builder.context.sender,
   });
 

package/src/examples/staged/registry.ts

@@ -25,7 +25,8 @@ export const STAGED_EXAMPLES: Record<string, () => ComposeCompileRequest> = {
     buildAaveBorrow({
       owner: OWNER,
       recipient: RECIPIENT,
-      amount: '1000000000',
+      collateralAmount: '1000000000',
+      borrowAmount: '500000000',
     }).request,
   'aave-hf-explode': () =>
     buildAaveHealthFactorExplode({ signer: OWNER }).request,
@@ -33,13 +34,14 @@ export const STAGED_EXAMPLES: Record<string, () => ComposeCompileRequest> = {
     buildMorphoBlueBorrow({
       owner: OWNER,
       collateralAmount: '1000000000000000000',
-      borrowAmount: '1500000000',
+      borrowAmount: '1200000000',
     }).request,
   'morpho-repay': () =>
     buildMorphoBlueRepay({
       owner: OWNER,
-      repayAmount: '1505000000',
       collateralAmount: '1000000000000000000',
+      borrowAmount: '500000000',
+      repayAmount: '501000000',
     }).request,
   'debt-rebalance': () =>
     buildAaveDebtRebalanceExactOut({
@@ -52,8 +54,8 @@ export const STAGED_EXAMPLES: Record<string, () => ComposeCompileRequest> = {
     buildAaveToMorphoDebtMigrationWithSwapExactOut({
       owner: OWNER,
       collateralAmount: '1000000000000000000',
-      debtAmount: '2000000000',
-      morphoBorrowAmount: '1950000000',
+      debtAmount: '1000000000',
+      morphoBorrowAmount: '975000000',
     }).request,
   'flashloan-repay': () =>
     buildTrivialFlashloanRepay({

package/src/examples/untypedOpWithTypedRef.ts

@@ -1,25 +1,32 @@
 import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
-import { createComposeSdk, materialisers, raw, resources } from '../index.js';
+import { createComposeSdk, raw } from '../index.js';
 import type { Address } from '../types.js';
 
 import { BASE_URL } from './config.js';
 
-const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
-// Example custom vault that the typed builder doesn't cover yet
-const CUSTOM_VAULT = '0x1111111111111111111111111111111111111111';
+// Real ERC-4626 vault (Steakhouse USDC on Ethereum mainnet) queried through
+// the untyped escape hatch.
+const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
 
 export interface UntypedOpWithTypedRefInput {
   readonly owner: Address;
 }
 
 /**
- * Insert an untyped operation node for an unsupported operation, then feed
- * its output into typed builder methods using `raw.ref<T>()`.
+ * Insert an untyped operation node, then feed its output into typed builder
+ * methods using `raw.ref<T>()`.
+ *
+ * `untypedOp` is the escape hatch for ops the installed SDK's typed surface
+ * doesn't cover — typically backend ops newer than your SDK version. The op
+ * id is passed as a plain string and its bind/config shapes are not
+ * type-checked, so the backend validates them at compile time instead.
+ *
+ * This example routes a real op (`core.staticCall`) through the untyped path
+ * so the flow compiles end-to-end; the mechanism is identical for any op id.
  *
  * Demonstrates:
- * - `builder.untypedOp()` to add a node the typed API doesn't cover
- *   (e.g. a custom vault query).
+ * - `builder.untypedOp()` to add a node the typed API doesn't cover.
  * - `raw.ref<'uint256'>()` to reference the untyped node's output in a typed
  *   `Bindable<'uint256'>` slot — the explicit type parameter is required
  *   so the compiler verifies the ref is used in a compatible slot.
@@ -35,16 +42,17 @@ export const buildUntypedOpWithTypedRef = ({
 
   const builder = sdk.flow(1, {
     name: 'untyped-op-with-typed-ref',
-    inputs: {
-      amountIn: resources.erc20(USDC, 1),
-    },
+    inputs: {},
   });
 
-  // Insert an untyped node for a custom vault query. untypedOp returns void —
+  // Insert an untyped node querying the vault. untypedOp returns void —
   // the typed builder has no knowledge of this node's outputs.
-  builder.untypedOp('vault-query', 'custom.vaultQuery', {
-    bind: { amount: { $ref: 'input.amountIn' } },
-    config: { target: CUSTOM_VAULT },
+  builder.untypedOp('vault-query', 'core.staticCall', {
+    bind: {},
+    config: {
+      target: VAULT,
+      functionSignature: 'function totalAssets() view returns (uint256)',
+    },
   });
 
   // Use raw.ref to bridge the untyped node's output into a typed operation.
@@ -60,17 +68,15 @@ export const buildUntypedOpWithTypedRef = ({
 
   // Continue with fully typed operations downstream.
   builder.core.assertGte('check-min', {
-    bind: { a: scaled.result, b: builder.inputs.amountIn },
+    bind: { a: scaled.result, b: vaultResult },
   });
 
   const flow = builder.build();
 
+  // No sweepTo: the flow reads state and asserts — it produces no resources.
   const request = sdk.request(flow, {
     signer: owner,
-    inputs: {
-      amountIn: materialisers.directDeposit({ amount: '1000000' }),
-    },
-    sweepTo: builder.context.sender,
+    inputs: {},
   });
 
   return { flow, request };

package/src/generated/config.generated.ts

@@ -55,6 +55,40 @@ export interface LifiSwapConfig {
   };
 }
 
+export interface InvariantNumericConfig {
+  op: 'gte' | 'gt' | 'lte' | 'lt' | 'eq' | 'neq';
+  threshold: IntegerStringInput;
+}
+
+export interface InvariantNumericInRangeConfig {
+  min: IntegerStringInput;
+  max: IntegerStringInput;
+}
+
+export interface InvariantGteConfig {
+  threshold: IntegerStringInput;
+}
+
+export interface InvariantGtConfig {
+  threshold: IntegerStringInput;
+}
+
+export interface InvariantLteConfig {
+  threshold: IntegerStringInput;
+}
+
+export interface InvariantLtConfig {
+  threshold: IntegerStringInput;
+}
+
+export interface InvariantEqConfig {
+  threshold: IntegerStringInput;
+}
+
+export interface InvariantNeqConfig {
+  threshold: IntegerStringInput;
+}
+
 export interface CoreBpsDownConfig {
   bps: number;
 }
@@ -76,6 +110,22 @@ export interface CoreTransferConfig {
   amount?: IntegerStringInput;
 }
 
+export interface CoreEmitEvent1Config {
+  signature: string;
+}
+
+export interface CoreEmitEvent2Config {
+  signature: string;
+}
+
+export interface CoreEmitEvent3Config {
+  signature: string;
+}
+
+export interface CoreEmitEvent4Config {
+  signature: string;
+}
+
 export interface CoreCallConfig {
   target: Address;
   functionSignature: string;