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

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/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 };
+};