@lifi/composer-sdk 0.0.1-alpha

package/src/examples/callContract.ts

@@ -0,0 +1,199 @@
+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';
+
+// Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
+const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+
+export interface CallContractInput {
+  readonly owner: Address;
+  readonly amount: `${bigint}`;
+}
+
+/**
+ * Redeem shares from an ERC-4626 vault back to the underlying token.
+ *
+ * Demonstrates:
+ * - core.call with a human-readable function signature and typed args
+ * - Inline approvals via the `approvals` config (alternative to a separate core.approve)
+ * - `$handle` and `$context` argument references
+ * - Threading the `result` output into core.asResource for downstream use
+ */
+export const buildRedeemFromVault = ({
+  owner,
+  amount,
+}: CallContractInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'redeem-from-vault',
+    inputs: {
+      shares: resources.erc20(VAULT, 1),
+    },
+  });
+
+  // Redeem vault shares for the underlying USDC.
+  // - `input` binds the vault shares resource (consumed by the call)
+  // - `approvals` grants the vault allowance inline (no separate approve node needed)
+  // - `args` maps function parameters:
+  //     $handle references a bound input by name
+  //     $context references a runtime context value (e.g. the execution proxy address)
+  // - `returns (uint256)` in the signature gives typed access to `.result`
+  const redeemResult = builder.core.call('redeem', {
+    resource: builder.inputs.shares,
+    bind: {
+      shares: builder.inputs.shares,
+      receiver: builder.context.executionAddress,
+      owner: builder.context.executionAddress,
+    },
+    config: {
+      target: VAULT,
+      functionSignature:
+        'function redeem(uint256 shares, address receiver, address owner) returns (uint256)',
+      approvals: [{ spender: VAULT }],
+    },
+  });
+
+  // Graduate the raw uint256 return value to a tracked USDC resource
+  // so downstream nodes can consume it with linearity and slippage tracking.
+  builder.core.asResource('underlying', {
+    bind: { handle: redeemResult.result },
+    config: {
+      resource: resources.erc20(USDC, 1),
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      shares: materialisers.directDeposit({ amount }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};
+
+/**
+ * Claim rewards from a contract that does not consume a token resource.
+ *
+ * Demonstrates:
+ * - Resource-free core.call (no `resource` field) — routes to `core.invoke` internally
+ * - `returns (uint256)` makes `.result` available for downstream use
+ * - Graduating the raw result to a tracked resource via core.asResource
+ */
+export const buildClaimRewards = ({
+  owner,
+}: {
+  readonly owner: Address;
+}): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const REWARDS_CONTRACT = '0x1111111111111111111111111111111111111111';
+  const REWARD_TOKEN = '0x2222222222222222222222222222222222222222';
+
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'claim-rewards',
+    inputs: {},
+  });
+
+  // Claim rewards — no token consumed, no resource needed.
+  // The `returns (uint256)` clause enables typed access to `.result`.
+  const claimResult = builder.core.call('claim', {
+    bind: {},
+    config: {
+      target: REWARDS_CONTRACT,
+      functionSignature: 'function claim() returns (uint256)',
+    },
+  });
+
+  // Graduate the raw uint256 result to a tracked resource.
+  builder.core.asResource('reward-token', {
+    bind: { handle: claimResult.result },
+    config: {
+      resource: resources.erc20(REWARD_TOKEN, 1),
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {},
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};
+
+/**
+ * Wrap native ETH into WETH using a ValueCall.
+ *
+ * Demonstrates:
+ * - `callType: 'ValueCall'` to send native ETH value along with the call
+ * - Calling a void payable function (no return value — `.result` is `undefined`)
+ * - Using `core.balanceOf` to discover the minted WETH after a void call
+ */
+export const buildWrapEth = ({
+  owner,
+  amount,
+}: CallContractInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'wrap-eth',
+    inputs: {
+      ethIn: resources.native(1),
+    },
+  });
+
+  // WETH.deposit() is payable with no arguments — the ETH value sent
+  // becomes the minted WETH amount. `callType: 'ValueCall'` forwards
+  // the bound resource's value as msg.value.
+  // deposit() returns void, so .result is undefined.
+  builder.core.call('wrap', {
+    resource: builder.inputs.ethIn,
+    bind: {},
+    config: {
+      target: WETH,
+      functionSignature: 'function deposit()',
+      callType: 'ValueCall',
+    },
+  });
+
+  // deposit() is void — read the minted WETH balance to get a tracked resource.
+  builder.core.balanceOf('weth', {
+    bind: {},
+    config: {
+      token: WETH,
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      ethIn: materialisers.directDeposit({ amount }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/config.ts

@@ -0,0 +1,9 @@
+// COMPOSER_BASE_URL rather than BASE_URL to avoid collision with Vite's
+// built-in process.env.BASE_URL (set to "/" from the `base` config option).
+export const BASE_URL: string =
+  process.env['COMPOSER_BASE_URL'] ?? 'https://composer.li.quest';
+export const API_KEY: string | undefined = process.env['LIFI_API_KEY'];
+
+export const OWNER = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045';
+export const RECIPIENT = '0x1234567890abcdef1234567890abcdef12345678';
+export const PROXY = '0x2222222222222222222222222222222222222222';

package/src/examples/consolidateToEth.ts

@@ -0,0 +1,94 @@
+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';
+
+export interface ConsolidateToEthInput {
+  readonly owner: Address;
+  readonly wethAmount: `${bigint}`;
+  readonly usdcAmount: `${bigint}`;
+  readonly usdtAmount: `${bigint}`;
+  readonly daiAmount: `${bigint}`;
+}
+
+const CHAIN_ID = 1;
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
+const DAI = '0x6B175474E89094C44Da98b954EedeAC495271d0F';
+
+/**
+ * Consolidate ERC-20 token balances into native ETH on Ethereum mainnet.
+ *
+ * Demonstrates:
+ * - Multiple resource inputs swapped to native ETH (not an ERC-20 target)
+ * - resources.native() for the swap target
+ * - directDeposit materialisers with fixed amounts (no on-chain balance read)
+ */
+export const buildConsolidateToEth = ({
+  owner,
+  wethAmount,
+  usdcAmount,
+  usdtAmount,
+  daiAmount,
+}: ConsolidateToEthInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const erc20 = (token: Address) => resources.erc20(token, CHAIN_ID);
+
+  // Declare the flow with one input per ERC-20 token on Ethereum mainnet.
+  const builder = sdk.flow(CHAIN_ID, {
+    name: 'consolidate-to-eth',
+    inputs: {
+      token_weth: erc20(WETH),
+      token_usdc: erc20(USDC),
+      token_usdt: erc20(USDT),
+      token_dai: erc20(DAI),
+    },
+  });
+
+  // Swap each token → native ETH via LI.FI with shared config.
+  const swapConfig = {
+    resourceOut: resources.native(CHAIN_ID),
+    slippage: 0.03,
+  };
+
+  builder.lifi.swap('swap_token_weth', {
+    bind: { amountIn: builder.inputs.token_weth },
+    config: swapConfig,
+  });
+  builder.lifi.swap('swap_token_usdc', {
+    bind: { amountIn: builder.inputs.token_usdc },
+    config: swapConfig,
+  });
+  builder.lifi.swap('swap_token_usdt', {
+    bind: { amountIn: builder.inputs.token_usdt },
+    config: swapConfig,
+  });
+  builder.lifi.swap('swap_token_dai', {
+    bind: { amountIn: builder.inputs.token_dai },
+    config: swapConfig,
+  });
+
+  const flow = builder.build();
+
+  // Build the compile request.
+  // directDeposit materialisers transfer fixed amounts into the VM.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      token_weth: materialisers.directDeposit({ amount: wethAmount }),
+      token_usdc: materialisers.directDeposit({ amount: usdcAmount }),
+      token_usdt: materialisers.directDeposit({ amount: usdtAmount }),
+      token_dai: materialisers.directDeposit({ amount: daiAmount }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/consolidateToUsdc.ts

@@ -0,0 +1,95 @@
+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';
+
+export interface ConsolidateStablesToUsdcInput {
+  readonly owner: Address;
+  readonly usdtAmount: `${bigint}`;
+  readonly daiAmount: `${bigint}`;
+  readonly fraxAmount: `${bigint}`;
+  readonly lusdAmount: `${bigint}`;
+}
+
+const CHAIN_ID = 1;
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
+const DAI = '0x6B175474E89094C44Da98b954EedeAC495271d0F';
+const FRAX = '0x853d955aCEf822Db058eb8505911ED77F175b99e';
+const LUSD = '0x5f98805A4E8be255a32880FDeC7F6728C6568bA0';
+
+/**
+ * Consolidate blue-chip stablecoin balances into USDC on Ethereum mainnet.
+ *
+ * Demonstrates:
+ * - Multiple resource inputs (four stablecoins)
+ * - Shared swap config reused across all nodes
+ * - directDeposit materialisers with fixed amounts (no on-chain balance read)
+ */
+export const buildConsolidateStablesToUsdc = ({
+  owner,
+  usdtAmount,
+  daiAmount,
+  fraxAmount,
+  lusdAmount,
+}: ConsolidateStablesToUsdcInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const erc20 = (token: Address) => resources.erc20(token, CHAIN_ID);
+
+  // Declare the flow with one input per stablecoin on Ethereum mainnet.
+  const builder = sdk.flow(CHAIN_ID, {
+    name: 'consolidate-stables-to-usdc',
+    inputs: {
+      stable_usdt: erc20(USDT),
+      stable_dai: erc20(DAI),
+      stable_frax: erc20(FRAX),
+      stable_lusd: erc20(LUSD),
+    },
+  });
+
+  // Swap each stablecoin → USDC via LI.FI with shared config.
+  const swapConfig = {
+    resourceOut: resources.erc20(USDC, CHAIN_ID),
+    slippage: 0.03,
+  };
+
+  builder.lifi.swap('swap_stable_usdt', {
+    bind: { amountIn: builder.inputs.stable_usdt },
+    config: swapConfig,
+  });
+  builder.lifi.swap('swap_stable_dai', {
+    bind: { amountIn: builder.inputs.stable_dai },
+    config: swapConfig,
+  });
+  builder.lifi.swap('swap_stable_frax', {
+    bind: { amountIn: builder.inputs.stable_frax },
+    config: swapConfig,
+  });
+  builder.lifi.swap('swap_stable_lusd', {
+    bind: { amountIn: builder.inputs.stable_lusd },
+    config: swapConfig,
+  });
+
+  const flow = builder.build();
+
+  // Build the compile request.
+  // directDeposit materialisers transfer fixed amounts into the VM.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      stable_usdt: materialisers.directDeposit({ amount: usdtAmount }),
+      stable_dai: materialisers.directDeposit({ amount: daiAmount }),
+      stable_frax: materialisers.directDeposit({ amount: fraxAmount }),
+      stable_lusd: materialisers.directDeposit({ amount: lusdAmount }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/depositFromProxy.ts

@@ -0,0 +1,87 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import {
+  createComposeSdk,
+  guards,
+  materialisers,
+  preconditions,
+  resources,
+} from '../index.js';
+import type { Address } from '../types.js';
+
+import { BASE_URL } from './config.js';
+
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+// Aave v3 aEthUSDC receipt token on Ethereum mainnet
+const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
+
+export interface DepositFromProxyInput {
+  readonly owner: Address;
+  readonly proxyAddress: Address;
+  readonly expectedAmount: `${bigint}`;
+}
+
+/**
+ * Read tokens already on the proxy and deposit them into Aave.
+ *
+ * Demonstrates:
+ * - `balanceOf` materialiser to source input from the proxy's existing
+ *   token balance rather than transferring tokens in.
+ * - `erc20Balance` precondition to assert the expected amount is present.
+ *
+ * Why the precondition matters:
+ * `balanceOf` reads whatever balance happens to be on the proxy at
+ * execution time. Without a precondition, the flow would silently
+ * succeed with zero tokens if the expected funds never arrived (e.g.
+ * a bridge transfer that hasn't landed yet). The precondition makes
+ * the flow fail-fast with a clear error instead of executing a
+ * worthless deposit.
+ */
+export const buildDepositFromProxy = ({
+  owner,
+  proxyAddress,
+  expectedAmount,
+}: DepositFromProxyInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'deposit-from-proxy',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+    },
+  });
+
+  // Zap the USDC into Aave's aEthUSDC position.
+  builder.lifi.zap('deposit', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: {
+      resourceOut: resources.erc20(A_ETH_USDC, 1),
+    },
+    guards: [guards.slippage({ port: 'amountOut', bps: 100 })],
+  });
+
+  const flow = builder.build();
+
+  // balanceOf reads the proxy's current USDC balance as the input.
+  // The precondition guarantees at least `expectedAmount` is present —
+  // without it, a delayed bridge would cause a silent zero-value deposit.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.balanceOf({ owner: proxyAddress }),
+    },
+    preconditions: [
+      preconditions.erc20Balance({
+        wallet: proxyAddress,
+        token: USDC,
+        balance: expectedAmount,
+      }),
+    ],
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/dustSweep.ts

@@ -0,0 +1,66 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../index.js';
+
+import { BASE_URL, OWNER } from './config.js';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+const USDT = '0xdAC17F958D2ee523a2206206994597C13D831ec7';
+
+/**
+ * Split USDC 80/20, swap only the 80% portion to USDT, and sweep the
+ * remaining 20% back to the sender as dust.
+ *
+ * Demonstrates:
+ * - Dust recovery via `sweepTo`. When a flow produces leftover tokens
+ *   that are not consumed by any downstream operation, those tokens
+ *   remain on the proxy contract. `sweepTo` tells the backend to
+ *   transfer all residual token balances to the specified address
+ *   at the end of execution.
+ * - In this example the 20% USDC from the split is intentionally
+ *   unused — it becomes dust that `sweepTo` returns to the sender.
+ */
+export const buildDustSweepExample = (): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'dust-sweep',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+    },
+  });
+
+  // Split USDC 80/20.
+  // Only the 80% portion (`a`) is consumed by the swap.
+  // The 20% portion (`b`) is intentionally left unbound — it stays on
+  // the proxy as dust and gets swept back to the sender.
+  const { a } = builder.core.split('split', {
+    bind: { source: builder.inputs.amountIn },
+    config: { bps: 8000 },
+  });
+
+  // Swap only the 80% portion to USDT.
+  builder.lifi.swap('swap', {
+    bind: { amountIn: a },
+    config: {
+      resourceOut: resources.erc20(USDT, 1),
+      slippage: 0.03,
+    },
+  });
+
+  const flow = builder.build();
+
+  // `sweepTo` ensures the unused 20% USDC is transferred back to the
+  // sender rather than being left stranded on the proxy contract.
+  const request = sdk.request(flow, {
+    signer: OWNER,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: '10000000' }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/lifiSwap.ts

@@ -0,0 +1,56 @@
+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 on Ethereum mainnet via LI.FI.
+ *
+ * Demonstrates:
+ * - Simplest possible single-swap flow
+ * - directDeposit materialiser with a fixed amount
+ * - No slippage guard needed — lifi.swap's amountOut already providesMinimum
+ */
+export const buildLifiSwapExample = (): {
+  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-weth-to-usdc',
+    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.
+  // directDeposit transfers a fixed amount of WETH into the VM.
+  const request = sdk.request(flow, {
+    signer: OWNER,
+    inputs: {
+      amountIn: materialisers.directDeposit({
+        amount: '1000000000000000000',
+      }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/lifiZap.ts

@@ -0,0 +1,60 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import {
+  createComposeSdk,
+  guards,
+  materialisers,
+  resources,
+} from '../index.js';
+
+import { BASE_URL, OWNER } from './config.js';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+// Aave aEthUSDC receipt token on Ethereum mainnet
+const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
+
+/**
+ * Zap USDC into an Aave lending position on Ethereum mainnet via LI.FI.
+ *
+ * Demonstrates:
+ * - Simplest possible single-zap flow
+ * - Slippage guard on the zap output (allowed because amountOut does not providesMinimum)
+ * - directDeposit materialiser with a fixed amount
+ */
+export const buildLifiZapExample = (): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  // Declare the flow with a single USDC input on Ethereum mainnet.
+  const builder = sdk.flow(1, {
+    name: 'zap-usdc-to-aave',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+    },
+  });
+
+  // Zap USDC into Aave's aEthUSDC position via LI.FI.
+  // Slippage guard asserts the output is within 1% (100 bps) of the expected amount.
+  builder.lifi.zap('zap', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: {
+      resourceOut: resources.erc20(A_ETH_USDC, 1),
+    },
+    guards: [guards.slippage({ port: 'amountOut', bps: 100 })],
+  });
+
+  const flow = builder.build();
+
+  // Build the compile request.
+  // directDeposit transfers a fixed amount of USDC into the VM.
+  const request = sdk.request(flow, {
+    signer: OWNER,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: '1000000000' }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};