@lifi/composer-sdk 0.0.1-alpha → 0.1.0

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/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,21 @@ export interface LifiSwapConfig {
       reduceEveryMs: number;
     }[];
   };
+  exchanges?: {
+    allow?: MaxItems50;
+    deny?: MaxItems50;
+    prefer?: MaxItems50;
+  };
 }
 
-export interface LifiZapConfig {
-  resourceOut:
-    | {
-        kind: 'native';
-        chainId: Positive;
-      }
-    | {
-        kind: 'erc20';
-        token: Address;
-        chainId: Positive;
-      };
+export interface InvariantNumericConfig {
+  op: 'gte' | 'gt' | 'lte' | 'lt' | 'eq' | 'neq';
+  threshold: IntegerStringInput;
+}
+
+export interface InvariantNumericInRangeConfig {
+  min: IntegerStringInput;
+  max: IntegerStringInput;
 }
 
 export interface CoreBpsDownConfig {
@@ -74,6 +86,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;
@@ -120,22 +148,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 +509,12 @@ export type DirectDepositMaterialiserConfig =
       allowNonExact?: false;
     }
   | {
-      amount?: IntegerStringInput;
+      amount: IntegerStringInput;
       allowNonExact: true;
+    }
+  | {
+      allowNonExact: true;
+      simAmount?: string;
     };
 
 export interface CallMaterialiserConfig {
@@ -155,6 +522,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,
+});