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

package/src/examples/run.ts

@@ -10,14 +10,13 @@
  * 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
+ *   aave-emode        — switch the proxy's Aave v3 eMode category
  *   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
@@ -29,7 +28,6 @@
  *   raw-call          — query a contract with raw calldata + arithmetic
  *   read-state        — read on-chain state via peek, staticCall, balanceOf
  *   redeem            — redeem ERC-4626 vault shares via core.call
- *   claim             — claim rewards from a contract (resource-free call)
  *   wrap-eth          — wrap native ETH into WETH via ValueCall
  *   transfer          — transfer full token balance to a recipient
  *   partial-transfer  — transfer a specific amount, keeping the remainder
@@ -39,15 +37,11 @@ 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 { buildAaveSetEMode } from './aaveSetEMode.js';
 import { buildApproveAndDeposit } from './approveAndDeposit.js';
-import {
-  buildClaimRewards,
-  buildRedeemFromVault,
-  buildWrapEth,
-} from './callContract.js';
+import { buildRedeemFromVault, buildWrapEth } from './callContract.js';
 import { API_KEY, BASE_URL, OWNER, PROXY, RECIPIENT } from './config.js';
 import { buildConsolidateToEth } from './consolidateToEth.js';
 import { buildConsolidateStablesToUsdc } from './consolidateToUsdc.js';
@@ -63,22 +57,25 @@ 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,
+    buildAaveRepay({
+      owner: OWNER,
+      collateralAmount: '1000000000',
+      borrowAmount: '100000000000000000',
+      repayAmount: '101000000000000000',
+    }).request,
   'aave-repay-atoken': () =>
     buildAaveRepayWithATokens({
       owner: OWNER,
-      proxyAddress: PROXY,
-      expectedATokenBalance: '1000000000',
+      collateralAmount: '1000000000',
+      borrowAmount: '500000000',
     }).request,
-  'aave-claim': () =>
-    buildAaveClaimRewards({ owner: OWNER, recipient: RECIPIENT }).request,
+  'aave-emode': () => buildAaveSetEMode({ owner: OWNER }).request,
   'approve-deposit': () =>
     buildApproveAndDeposit({ owner: OWNER, amount: '1000000000' }).request,
   consolidate: () =>
@@ -105,7 +102,6 @@ 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,7 +129,6 @@ const EXAMPLES: Record<string, () => ComposeCompileRequest> = {
   redeem: () =>
     buildRedeemFromVault({ owner: OWNER, amount: '1000000000000000000' })
       .request,
-  claim: () => buildClaimRewards({ owner: OWNER }).request,
   'wrap-eth': () =>
     buildWrapEth({ owner: OWNER, amount: '1000000000000000000' }).request,
   transfer: () =>
@@ -190,7 +185,14 @@ const run = async () => {
   const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   console.log('--- Request ---');
-  console.log(JSON.stringify(request, null, 2));
+  console.log(
+    JSON.stringify(
+      request,
+      (_key, value: unknown) =>
+        typeof value === 'bigint' ? value.toString() : value,
+      2,
+    ),
+  );
 
   console.log(`\n--- Compiling against ${BASE_URL} ---`);
   const result = await sdk.client.compile(request);

package/src/examples/simulateCompiledSwap.ts

@@ -0,0 +1,76 @@
+import type { SimulateResult } from '@lifi/compose-spec';
+
+import { buildSimulateRequest, materialisers, resources } from '../index.js';
+import type { ComposeSdk } from '../index.js';
+
+import { OWNER } from './config.js';
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+// 1 WETH (18 decimals).
+const ONE_WETH = 1_000_000_000_000_000_000n;
+
+/**
+ * End-to-end `/simulate` usage: compile a WETH→USDC swap, then simulate the
+ * compiled transaction to see how the signer's balances move and how much
+ * inner-call gas it burns — without broadcasting anything on-chain.
+ *
+ * Demonstrates the compile → simulate arc:
+ * - `buildSimulateRequest` lifts a `ComposeCompileResult` into a
+ *   `SimulateRequest`, supplying the fields a compiled flow cannot carry: the
+ *   target `chainId`, the `signer` (`from`), the funding `requirements`, and the
+ *   `trackedBalances` to watch.
+ * - `sdk.simulate` runs it and returns a discriminated `ok | revert | error`
+ *   result. A `revert` is a *successful simulation* whose execution reverted, so
+ *   it is returned (not thrown); only transport/auth/5xx failures throw.
+ *
+ * Unlike the pure-builder examples, this performs network I/O through the
+ * injected `sdk` (one `/compose` call, one `/simulate` call). Pass a live
+ * `createComposeSdk({ baseUrl })` to run it for real, or a mock-backed SDK in
+ * tests.
+ */
+export const simulateCompiledSwap = async (
+  sdk: ComposeSdk,
+): Promise<SimulateResult> => {
+  // Author and compile a single WETH → USDC swap on Ethereum mainnet.
+  const builder = sdk.flow(1, {
+    name: 'swap-weth-to-usdc',
+    inputs: { amountIn: resources.erc20(WETH, 1) },
+  });
+
+  builder.lifi.swap('swap', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: { resourceOut: resources.erc20(USDC, 1), slippage: 0.03 },
+  });
+
+  const compiled = await builder.compile({
+    signer: OWNER,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: ONE_WETH }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  // Lift the compiled transaction into a simulation request. The chain, signer,
+  // funding, and watched balances are NOT inferable from a compiled flow, so
+  // they are supplied here. `to`/`data`/`value` come from the compile result.
+  const request = buildSimulateRequest({
+    result: compiled,
+    chainId: 1,
+    signer: OWNER,
+    // Seed the signer with the 1 WETH the swap deposits, so the inner call has
+    // funds to pull. `bigint` amounts are serialised to decimal strings.
+    requirements: [
+      { type: 'Erc20Balance', wallet: OWNER, token: WETH, balance: ONE_WETH },
+    ],
+    // Watch the signer's WETH (spent) and USDC (received) balances; the response
+    // `deltas` come back ordered to match.
+    trackedBalances: [
+      { token: WETH, owner: OWNER },
+      { token: USDC, owner: OWNER },
+    ],
+  });
+
+  return sdk.simulate(request);
+};

package/src/examples/simulateRawTransaction.ts

@@ -0,0 +1,39 @@
+import type { SimulateRequest } from '@lifi/compose-spec';
+
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+const SENDER = '0x1111111111111111111111111111111111111111';
+const RECIPIENT = '0x2222222222222222222222222222222222222222';
+
+/**
+ * Build a representative `POST /simulate` request: a USDC transfer of 1 USDC
+ * (1_000_000 base units at 6 decimals) from `SENDER` to `RECIPIENT` on chain 1.
+ *
+ * Demonstrates:
+ * - A pre-encoded `transfer(address,uint256)` calldata literal (`data`)
+ * - Funding the sender with an `Erc20Balance` requirement so the transfer can
+ *   succeed in simulation (`bigint` amounts are accepted and serialised)
+ * - Watching both the sender's and recipient's USDC balance via `trackedBalances`
+ *
+ * Pure: returns a plain {@link SimulateRequest}, performs no network I/O. Pass
+ * it to `sdk.client.simulate(...)` / `sdk.simulate(...)` to run it.
+ */
+export const buildSimulateRawTransactionExample = (): SimulateRequest => ({
+  chainId: 1,
+  from: SENDER,
+  to: USDC,
+  // transfer(RECIPIENT, 1_000_000)
+  data: '0xa9059cbb0000000000000000000000002222222222222222222222222222222222222222000000000000000000000000000000000000000000000000000000000f4240',
+  value: 0n,
+  requirements: [
+    {
+      type: 'Erc20Balance',
+      wallet: SENDER,
+      token: USDC,
+      balance: 1_000_000n,
+    },
+  ],
+  trackedBalances: [
+    { token: USDC, owner: SENDER },
+    { token: USDC, owner: RECIPIENT },
+  ],
+});

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,23 +110,155 @@ 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;
+}
+
+/**
+ * a string at most 65536 character(s) long
+ */
+export type MaxLength65536 = string;
+
 export interface CoreCallConfig {
   target: Address;
   functionSignature: string;
   callType?: 'Call' | 'ValueCall';
-  args?: Unknown[];
+  args?: (
+    | (
+        | MaxLength65536
+        | number
+        | boolean
+        | {
+            $ref: string;
+          }
+      )
+    | (
+        | (
+            | MaxLength65536
+            | number
+            | boolean
+            | {
+                $ref: string;
+              }
+          )
+        | (
+            | (
+                | MaxLength65536
+                | number
+                | boolean
+                | {
+                    $ref: string;
+                  }
+              )
+            | (
+                | (
+                    | MaxLength65536
+                    | number
+                    | boolean
+                    | {
+                        $ref: string;
+                      }
+                  )
+                | (
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )[]
+                  )[]
+              )[]
+          )[]
+      )[]
+  )[];
   approvals?: {
     spender: Address;
   }[];
 }
-export interface Unknown {
-  [k: string]: unknown;
-}
 
 export interface CoreStaticCallConfig {
   target: Address;
   functionSignature: string;
-  args?: Unknown[];
+  args?: (
+    | (
+        | MaxLength65536
+        | number
+        | boolean
+        | {
+            $ref: string;
+          }
+      )
+    | (
+        | (
+            | MaxLength65536
+            | number
+            | boolean
+            | {
+                $ref: string;
+              }
+          )
+        | (
+            | (
+                | MaxLength65536
+                | number
+                | boolean
+                | {
+                    $ref: string;
+                  }
+              )
+            | (
+                | (
+                    | MaxLength65536
+                    | number
+                    | boolean
+                    | {
+                        $ref: string;
+                      }
+                  )
+                | (
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )[]
+                  )[]
+              )[]
+          )[]
+      )[]
+  )[];
 }
 
 export interface CoreRawCallConfig {
@@ -106,7 +272,64 @@ export interface CoreInvokeConfig {
   target: Address;
   functionSignature: string;
   callType?: 'Call' | 'ValueCall';
-  args?: Unknown[];
+  args?: (
+    | (
+        | MaxLength65536
+        | number
+        | boolean
+        | {
+            $ref: string;
+          }
+      )
+    | (
+        | (
+            | MaxLength65536
+            | number
+            | boolean
+            | {
+                $ref: string;
+              }
+          )
+        | (
+            | (
+                | MaxLength65536
+                | number
+                | boolean
+                | {
+                    $ref: string;
+                  }
+              )
+            | (
+                | (
+                    | MaxLength65536
+                    | number
+                    | boolean
+                    | {
+                        $ref: string;
+                      }
+                  )
+                | (
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )
+                    | (
+                        | MaxLength65536
+                        | number
+                        | boolean
+                        | {
+                            $ref: string;
+                          }
+                      )[]
+                  )[]
+              )[]
+          )[]
+      )[]
+  )[];
 }
 
 export interface CoreAsResourceConfig {

package/src/generated/materialisers.generated.ts

@@ -10,7 +10,6 @@ import type {
   BalanceOfMaterialiserConfig as BalanceOfMaterialiserConfigSchema,
   CallMaterialiserConfig as CallMaterialiserConfigSchema,
   DirectDepositMaterialiserConfig as DirectDepositMaterialiserConfigSchema,
-  FlashloanMaterialiserConfig as FlashloanMaterialiserConfigSchema,
 } from './config.generated.js';
 
 export type BalanceOfMaterialiserConfig =
@@ -43,14 +42,3 @@ 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,
-});