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

package/src/examples/staged/registry.ts

@@ -0,0 +1,78 @@
+// Registry of staged (not-yet-prod) examples for the live runner. This is data,
+// not a runner: src/examples/run.ts imports it via a non-literal dynamic import
+// when invoked with `--staged`, so this file (which references staged definitions)
+// is never pulled into the production type-check. It IS type-checked under
+// tsconfig.staged.json (see verify:staged).
+//
+// Running these requires the SDK regenerated with `--staged`; the example:staged
+// wrapper does that and restores production afterward.
+import type { ComposeCompileRequest } from '@lifi/compose-spec';
+
+import { OWNER, RECIPIENT } from '../config.js';
+
+import { buildAaveBorrow } from './aaveBorrow.js';
+import { buildAaveDebtRebalanceExactOut } from './aaveDebtRebalanceExactOut.js';
+import { buildAaveHealthFactorExplode } from './aaveHealthFactorExplode.js';
+import { buildAaveToMorphoDebtMigration } from './aaveToMorphoDebtMigration.js';
+import { buildAaveToMorphoDebtMigrationWithSwap } from './aaveToMorphoDebtMigrationWithSwap.js';
+import { buildAaveToMorphoDebtMigrationWithSwapExactOut } from './aaveToMorphoDebtMigrationWithSwapExactOut.js';
+import { buildTrivialFlashloanRepay } from './flashloanRepay.js';
+import { buildMorphoBlueBorrow } from './morphoBlueBorrow.js';
+import { buildMorphoBlueRepay } from './morphoBlueRepay.js';
+
+export const STAGED_EXAMPLES: Record<string, () => ComposeCompileRequest> = {
+  'aave-borrow': () =>
+    buildAaveBorrow({
+      owner: OWNER,
+      recipient: RECIPIENT,
+      amount: '1000000000',
+    }).request,
+  'aave-hf-explode': () =>
+    buildAaveHealthFactorExplode({ signer: OWNER }).request,
+  'morpho-borrow': () =>
+    buildMorphoBlueBorrow({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      borrowAmount: '1500000000',
+    }).request,
+  'morpho-repay': () =>
+    buildMorphoBlueRepay({
+      owner: OWNER,
+      repayAmount: '1505000000',
+      collateralAmount: '1000000000000000000',
+    }).request,
+  'debt-rebalance': () =>
+    buildAaveDebtRebalanceExactOut({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      debtAmount: '1000000000',
+      newDebtBorrowAmount: '965000000',
+    }).request,
+  'debt-migration-swap-exact-out': () =>
+    buildAaveToMorphoDebtMigrationWithSwapExactOut({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      debtAmount: '2000000000',
+      morphoBorrowAmount: '1950000000',
+    }).request,
+  'flashloan-repay': () =>
+    buildTrivialFlashloanRepay({
+      owner: OWNER,
+      amount: '10000000000',
+      fee: '5000000',
+    }).request,
+  'debt-migration': () =>
+    buildAaveToMorphoDebtMigration({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      debtAmount: '1000000000',
+      debtFlashloanFee: '500000',
+    }).request,
+  'debt-migration-swap': () =>
+    buildAaveToMorphoDebtMigrationWithSwap({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      debtAmount: '1000000000',
+      morphoBorrowAmount: '1100000000',
+    }).request,
+};

package/src/examples/swapToRecipient.ts

@@ -17,32 +17,13 @@ export interface SwapToRecipientInput {
 }
 
 /**
-<<<<<<< HEAD
-<<<<<<< HEAD
- * Swap WETH and DAI into USDC, merge the outputs, transfer to a recipient,
-=======
- * Swap WETH and DAI into USDC, merge the outputs, transfer to the recipient,
->>>>>>> a2c178fd (chore: fix examples)
- * and verify the recipient holds the combined balance.
-=======
  * Swap WETH and DAI into USDC, merge the outputs, and deliver to a recipient.
->>>>>>> 4c49ff9b (fix: support resource bindings for handle ports)
  *
  * Demonstrates:
  * - Multiple resource inputs (two ERC-20 tokens)
  * - A handle input (recipient address as a scalar value)
  * - Chaining two swaps through a merge node
-<<<<<<< HEAD
-<<<<<<< HEAD
- * - Explicit core.transfer to send merged tokens to the recipient
- * - Copy-mode resource input on invariant.balanceAtLeast (reads without consuming)
-=======
- * - core.transfer to send merged tokens to the recipient
- * - Using invariant.balanceAtLeast with a handle input for the account
->>>>>>> a2c178fd (chore: fix examples)
-=======
  * - Using `sweepTo` with a handle input to deliver tokens to the recipient
->>>>>>> 4c49ff9b (fix: support resource bindings for handle ports)
  * - Typed request inputs inferred from the flow schema
  */
 export const buildSwapToRecipient = ({

package/src/examples/swapWithFee.ts

@@ -0,0 +1,59 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../index.js';
+
+import { BASE_URL, OWNER } from './config.js';
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+/**
+ * Swap WETH to USDC via LI.FI while collecting an integrator fee.
+ *
+ * Demonstrates:
+ * - Setting `integratorFeeBps` on the compile request (50 bps = 0.5%)
+ * - The fee is taken on the input token; the backend injects the fee transfer
+ *
+ * A non-zero `integratorFeeBps` requires the SDK to be configured with an
+ * integration-scoped API key (`apiKey`); the integration is derived from the
+ * key, not the request body.
+ */
+export const buildSwapWithFeeExample = (): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  // Declare the flow with a single WETH input on Ethereum mainnet.
+  const builder = sdk.flow(1, {
+    name: 'swap-with-fee',
+    inputs: {
+      amountIn: resources.erc20(WETH, 1),
+    },
+  });
+
+  // Swap WETH → USDC via LI.FI.
+  builder.lifi.swap('swap', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: {
+      resourceOut: resources.erc20(USDC, 1),
+      slippage: 0.03,
+    },
+  });
+
+  const flow = builder.build();
+
+  // Build the compile request with a 50 bps (0.5%) integrator fee.
+  const request = sdk.request(flow, {
+    signer: OWNER,
+    inputs: {
+      amountIn: materialisers.directDeposit({
+        amount: '1000000000000000000',
+      }),
+    },
+    integratorFeeBps: 50,
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/generated/config.generated.ts

@@ -11,6 +11,16 @@ export interface CoreSplitConfig {
  * a positive number
  */
 export type Positive = number;
+/**
+ * a string at most 64 character(s) long
+ */
+export type MaxLength64 = string;
+/**
+ * an array of at most 50 item(s)
+ *
+ * @maxItems 50
+ */
+export type MaxItems50 = MaxLength64[];
 
 export interface LifiSwapConfig {
   resourceOut:
@@ -38,19 +48,11 @@ export interface LifiSwapConfig {
       reduceEveryMs: number;
     }[];
   };
-}
-
-export interface LifiZapConfig {
-  resourceOut:
-    | {
-        kind: 'native';
-        chainId: Positive;
-      }
-    | {
-        kind: 'erc20';
-        token: Address;
-        chainId: Positive;
-      };
+  exchanges?: {
+    allow?: MaxItems50;
+    deny?: MaxItems50;
+    prefer?: MaxItems50;
+  };
 }
 
 export interface CoreBpsDownConfig {
@@ -120,22 +122,357 @@ export interface CoreAsResourceConfig {
       };
 }
 
-export interface CorePeekConfig {
-  target: Address;
-  functionSignature: string;
-  args?: string[];
+export interface AaveBorrowConfig {
+  pool: string;
+  asset: string;
+  variableDebtToken: string;
+  amount: IntegerStringInput;
+  referralId?: number;
+}
+
+export type AaveRepayConfig =
+  | {
+      pool: string;
+      mode: 'exact';
+    }
+  | {
+      pool: string;
+      mode: 'max';
+    };
+
+export interface AaveRepayWithATokensConfig {
+  pool: string;
+  asset: string;
+}
+
+export interface AaveClaimRewardsConfig {
+  rewardsController: string;
+  assets: string[];
+  reward: string;
+  amount?: IntegerStringInput;
+  to?: string;
+}
+
+/**
+ * a number between 0 and 255
+ */
+export type Between0255 = number;
+
+export interface AaveSetEModeConfig {
+  pool: string;
+  category: Between0255;
+}
+
+export interface AaveGetHealthFactorConfig {
+  pool: string;
+  user?: string;
+}
+
+export type MorphoBlueSupplyCollateralConfig =
+  | (
+      | {
+          morpho?: string;
+          onBehalfOf?: string;
+          mode: 'exact';
+          /**
+           * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+           */
+          marketId: string;
+        }
+      | {
+          morpho?: string;
+          onBehalfOf?: string;
+          mode: 'exact';
+          marketParams: {
+            loanToken: string;
+            collateralToken: string;
+            oracle: string;
+            irm: string;
+            lltv: string;
+          };
+        }
+    )
+  | (
+      | {
+          morpho?: string;
+          onBehalfOf?: string;
+          mode: 'all';
+          /**
+           * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+           */
+          marketId: string;
+        }
+      | {
+          morpho?: string;
+          onBehalfOf?: string;
+          mode: 'all';
+          marketParams: {
+            loanToken: string;
+            collateralToken: string;
+            oracle: string;
+            irm: string;
+            lltv: string;
+          };
+        }
+    );
+
+export type MorphoBlueWithdrawCollateralConfig =
+  | {
+      morpho?: string;
+      amount: IntegerStringInput;
+      onBehalfOf?: string;
+      receiver?: string;
+      /**
+       * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+       */
+      marketId: string;
+    }
+  | {
+      morpho?: string;
+      amount: IntegerStringInput;
+      onBehalfOf?: string;
+      receiver?: string;
+      marketParams: {
+        loanToken: string;
+        collateralToken: string;
+        oracle: string;
+        irm: string;
+        lltv: string;
+      };
+    };
+
+export type MorphoBlueBorrowConfig =
+  | {
+      morpho?: string;
+      amount: IntegerStringInput;
+      onBehalfOf?: string;
+      receiver?: string;
+      /**
+       * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+       */
+      marketId: string;
+    }
+  | {
+      morpho?: string;
+      amount: IntegerStringInput;
+      onBehalfOf?: string;
+      receiver?: string;
+      marketParams: {
+        loanToken: string;
+        collateralToken: string;
+        oracle: string;
+        irm: string;
+        lltv: string;
+      };
+    };
+
+export type MorphoBlueRepayConfig =
+  | (
+      | {
+          morpho?: string;
+          mode: 'exact';
+          /**
+           * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+           */
+          marketId: string;
+        }
+      | {
+          morpho?: string;
+          mode: 'exact';
+          marketParams: {
+            loanToken: string;
+            collateralToken: string;
+            oracle: string;
+            irm: string;
+            lltv: string;
+          };
+        }
+    )
+  | (
+      | {
+          morpho?: string;
+          mode: 'max';
+          /**
+           * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+           */
+          marketId: string;
+        }
+      | {
+          morpho?: string;
+          mode: 'max';
+          marketParams: {
+            loanToken: string;
+            collateralToken: string;
+            oracle: string;
+            irm: string;
+            lltv: string;
+          };
+        }
+    );
+
+export type MorphoBlueSupplyConfig =
+  | {
+      morpho?: string;
+      onBehalfOf?: string;
+      /**
+       * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+       */
+      marketId: string;
+    }
+  | {
+      morpho?: string;
+      onBehalfOf?: string;
+      marketParams: {
+        loanToken: string;
+        collateralToken: string;
+        oracle: string;
+        irm: string;
+        lltv: string;
+      };
+    };
+
+export type MorphoBlueWithdrawConfig =
+  | (
+      | {
+          morpho?: string;
+          mode: 'exact';
+          amount: IntegerStringInput;
+          onBehalfOf?: string;
+          receiver?: string;
+          /**
+           * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+           */
+          marketId: string;
+        }
+      | {
+          morpho?: string;
+          mode: 'exact';
+          amount: IntegerStringInput;
+          onBehalfOf?: string;
+          receiver?: string;
+          marketParams: {
+            loanToken: string;
+            collateralToken: string;
+            oracle: string;
+            irm: string;
+            lltv: string;
+          };
+        }
+    )
+  | (
+      | {
+          morpho?: string;
+          mode: 'max';
+          onBehalfOf?: string;
+          receiver?: string;
+          /**
+           * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+           */
+          marketId: string;
+        }
+      | {
+          morpho?: string;
+          mode: 'max';
+          onBehalfOf?: string;
+          receiver?: string;
+          marketParams: {
+            loanToken: string;
+            collateralToken: string;
+            oracle: string;
+            irm: string;
+            lltv: string;
+          };
+        }
+    );
+
+export type MorphoBlueGetPositionConfig =
+  | {
+      morpho?: string;
+      user?: string;
+      /**
+       * a string matching the pattern ^0x[0-9a-fA-F]{64}$
+       */
+      marketId: string;
+    }
+  | {
+      morpho?: string;
+      user?: string;
+      marketParams: {
+        loanToken: string;
+        collateralToken: string;
+        oracle: string;
+        irm: string;
+        lltv: string;
+      };
+    };
+
+export interface LifiFlashloanRepayConfig {
+  leg: string;
+  fee?: string;
+}
+
+export interface LifiZapConfig {
+  resourceOut:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
 }
 
+/**
+ * a non-negative number
+ */
+export type GreaterThanOrEqualTo0 = number;
 /**
  * a number between 0 and 10000
  */
 export type Between010000 = number;
 
+export interface ParaswapBuyConfig {
+  resourceOut:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
+  exactAmountOut: string;
+  srcDecimals: GreaterThanOrEqualTo0;
+  destDecimals: GreaterThanOrEqualTo0;
+  maxSlippageBps?: Between010000;
+  partner?: string;
+  partnerAddress?: string;
+  /**
+   * Integrator fee in basis points; non-negative integer string capped at 9000.
+   */
+  partnerFeeBps?: string;
+}
+
+export interface CorePeekConfig {
+  target: Address;
+  functionSignature: string;
+  args?: string[];
+}
+
 export interface SlippageGuardConfig {
   port: string;
   bps: Between010000;
 }
 
+export interface CoreNumericInvariantGuardConfig {
+  port: string;
+  op: 'gte' | 'gt' | 'lte' | 'lt' | 'eq' | 'neq';
+  threshold: IntegerStringInput;
+}
+
 export interface BalanceOfMaterialiserConfig {
   owner: Address;
 }
@@ -146,8 +483,12 @@ export type DirectDepositMaterialiserConfig =
       allowNonExact?: false;
     }
   | {
-      amount?: IntegerStringInput;
+      amount: IntegerStringInput;
       allowNonExact: true;
+    }
+  | {
+      allowNonExact: true;
+      simAmount?: string;
     };
 
 export interface CallMaterialiserConfig {
@@ -155,6 +496,11 @@ export interface CallMaterialiserConfig {
   calldata: string;
 }
 
+export interface FlashloanMaterialiserConfig {
+  providerKind: 'aave-v3' | 'erc3156' | 'balancer-v2' | 'morpho-blue';
+  amount: IntegerStringInput;
+}
+
 export interface Erc20BalancePreconditionConfig {
   wallet: Address;
   token: Address;

package/src/generated/guards.generated.ts

@@ -3,7 +3,10 @@
 
 import type { TypedGuard } from '../types.js';
 
-import type { SlippageGuardConfig } from './config.generated.js';
+import type {
+  CoreNumericInvariantGuardConfig,
+  SlippageGuardConfig,
+} from './config.generated.js';
 
 /** Assert that output amounts are within a slippage tolerance in basis points */
 export const slippage = <P extends string>(
@@ -12,3 +15,11 @@ export const slippage = <P extends string>(
   kind: 'slippage',
   ...config,
 });
+
+/** Assert a numeric (uint256) handle output of the target op satisfies a comparison against a constant threshold. Emits one IR1 binary invariant; reverts the run on violation. */
+export const coreNumericInvariant = <P extends string>(
+  config: Omit<CoreNumericInvariantGuardConfig, 'port'> & { port: P },
+): TypedGuard<P> => ({
+  kind: 'core.numericInvariant',
+  ...config,
+});

package/src/generated/materialisers.generated.ts

@@ -7,38 +7,50 @@ import type {
 } from '@lifi/compose-spec';
 
 import type {
-  BalanceOfMaterialiserConfig,
-  CallMaterialiserConfig,
-  DirectDepositMaterialiserConfig,
+  BalanceOfMaterialiserConfig as BalanceOfMaterialiserConfigSchema,
+  CallMaterialiserConfig as CallMaterialiserConfigSchema,
+  DirectDepositMaterialiserConfig as DirectDepositMaterialiserConfigSchema,
+  FlashloanMaterialiserConfig as FlashloanMaterialiserConfigSchema,
 } from './config.generated.js';
 
-export type BalanceOfMaterialiserInput =
-  MaterialiserConfigOf<BalanceOfMaterialiserConfig>;
+export type BalanceOfMaterialiserConfig =
+  MaterialiserConfigOf<BalanceOfMaterialiserConfigSchema>;
 
 /** Read the on-chain token balance of an address as the input amount — accepts: resource */
 export const balanceOf = (
-  config: BalanceOfMaterialiserInput,
+  config: BalanceOfMaterialiserConfig,
 ): MaterialiserInput => ({
   kind: 'balanceOf',
   ...config,
 });
 
-export type DirectDepositMaterialiserInput =
-  MaterialiserConfigOf<DirectDepositMaterialiserConfig>;
+export type DirectDepositMaterialiserConfig =
+  MaterialiserConfigOf<DirectDepositMaterialiserConfigSchema>;
 
 /** Deposit tokens into the VM — native via msg.value, ERC-20 via transferFrom — accepts: resource */
 export const directDeposit = (
-  config: DirectDepositMaterialiserInput,
+  config: DirectDepositMaterialiserConfig,
 ): MaterialiserInput => ({
   kind: 'directDeposit',
   ...config,
 });
 
-export type CallMaterialiserInput =
-  MaterialiserConfigOf<CallMaterialiserConfig>;
+export type CallMaterialiserConfig =
+  MaterialiserConfigOf<CallMaterialiserConfigSchema>;
 
 /** Execute an arbitrary contract call and measure the resulting token balance diff — accepts: resource */
-export const call = (config: CallMaterialiserInput): MaterialiserInput => ({
+export const call = (config: CallMaterialiserConfig): MaterialiserInput => ({
   kind: 'call',
   ...config,
 });
+
+export type FlashloanMaterialiserConfig =
+  MaterialiserConfigOf<FlashloanMaterialiserConfigSchema>;
+
+/** Borrow tokens from a flashloan provider; amount becomes a register populated by the proxy at callback time — accepts: resource */
+export const flashloan = (
+  config: FlashloanMaterialiserConfig,
+): MaterialiserInput => ({
+  kind: 'flashloan',
+  ...config,
+});