@lifi/composer-sdk 0.2.0-staging.5 → 0.3.0

package/src/examples/rawCallWithArithmetic.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Example contract address for a non-standard oracle
 const ORACLE = '0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419';
@@ -27,7 +27,7 @@ export const buildRawCallWithArithmetic = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'raw-call-with-arithmetic',

package/src/examples/readContractState.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
@@ -28,7 +28,7 @@ export const buildReadContractState = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'read-contract-state',

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/splitAndZap.ts

@@ -7,7 +7,7 @@ import {
   resources,
 } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Aave v3 aEthUSDC receipt token on Ethereum mainnet
 const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
@@ -26,7 +26,7 @@ export const buildSplitAndZapExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'split-usdc-to-two-vaults',

package/src/examples/splitWithArithmetic.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 
@@ -29,7 +29,7 @@ export const buildSplitWithArithmetic = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'split-with-arithmetic',

package/src/examples/swapAndZap.ts

@@ -7,7 +7,7 @@ import {
   resources,
 } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 // Aave aEthUSDC receipt token on Ethereum mainnet
@@ -25,7 +25,7 @@ export const buildSwapAndZapExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // Declare the flow with a single WETH input on Ethereum mainnet.
   const builder = sdk.flow(1, {

package/src/examples/swapToRecipient.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
@@ -35,7 +35,7 @@ export const buildSwapToRecipient = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // Declare the flow on Ethereum mainnet with two token inputs and one address input.
   const builder = sdk.flow(1, {

package/src/examples/swapWithAllowRevert.ts

@@ -2,7 +2,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
 import { createComposeSdk, materialisers, resources } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 
@@ -25,7 +25,7 @@ export const buildSwapWithAllowRevertExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'swap-weth-to-usdc-allow-revert',
@@ -70,7 +70,7 @@ export const buildSwapWithAllowRevertExample = (): {
  * but demonstrates the branching pattern callers should use.
  */
 export const handleCompileResult = async (): Promise<void> => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     inputs: { amountIn: resources.erc20(WETH, 1) },

package/src/examples/swapWithBalanceCheck.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
@@ -29,7 +29,7 @@ export const buildSwapWithBalanceCheck = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // Declare the flow with a single WETH input on Ethereum mainnet.
   const builder = sdk.flow(1, {

package/src/examples/swapWithFee.ts

@@ -2,7 +2,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 
 import { createComposeSdk, materialisers, resources } from '../index.js';
 
-import { BASE_URL, OWNER } from './config.js';
+import { API_KEY, BASE_URL, OWNER } from './config.js';
 
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
@@ -22,7 +22,7 @@ export const buildSwapWithFeeExample = (): {
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   // Declare the flow with a single WETH input on Ethereum mainnet.
   const builder = sdk.flow(1, {

package/src/examples/swapWithOutputValidation.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
@@ -31,7 +31,7 @@ export const buildSwapWithOutputValidation = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'swap-with-output-validation',

package/src/examples/transferTokens.ts

@@ -3,7 +3,7 @@ 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';
+import { API_KEY, BASE_URL } from './config.js';
 
 const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
 
@@ -31,7 +31,7 @@ export const buildTransferTokens = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'transfer-usdc',
@@ -79,7 +79,7 @@ export const buildPartialTransfer = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'partial-transfer-usdc',

package/src/examples/untypedOpWithTypedRef.ts

@@ -3,7 +3,7 @@ import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
 import { createComposeSdk, raw } from '../index.js';
 import type { Address } from '../types.js';
 
-import { BASE_URL } from './config.js';
+import { API_KEY, BASE_URL } from './config.js';
 
 // Real ERC-4626 vault (Steakhouse USDC on Ethereum mainnet) queried through
 // the untyped escape hatch.
@@ -38,7 +38,7 @@ export const buildUntypedOpWithTypedRef = ({
   flow: Flow;
   request: ComposeCompileRequest;
 } => {
-  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
 
   const builder = sdk.flow(1, {
     name: 'untyped-op-with-typed-ref',

package/src/generated/config.generated.ts

@@ -3,8 +3,13 @@
 
 import type { Address, IntegerStringInput } from '../types.js';
 
+/**
+ * a number between 0 and 10000
+ */
+export type Between010000 = number;
+
 export interface CoreSplitConfig {
-  bps: number;
+  bps: Between010000;
 }
 
 /**
@@ -89,12 +94,17 @@ export interface InvariantNeqConfig {
   threshold: IntegerStringInput;
 }
 
+/**
+ * a non-negative number
+ */
+export type NonNegative = number;
+
 export interface CoreBpsDownConfig {
-  bps: number;
+  bps: NonNegative;
 }
 
 export interface CoreBpsUpConfig {
-  bps: number;
+  bps: NonNegative;
 }
 
 export interface CoreApproveConfig {
@@ -126,23 +136,139 @@ 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 {
@@ -156,7 +282,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 {
@@ -461,6 +644,33 @@ export interface LifiFlashloanRepayConfig {
   fee?: string;
 }
 
+export type ContinuationAssertReadyConfig =
+  | {
+      kind: 'erc20BalanceGte';
+      chainId: Positive;
+      token: StartsWith0X;
+      owner: StartsWith0X;
+      minAmount: string;
+    }
+  | {
+      kind: 'nativeBalanceGte';
+      chainId: Positive;
+      owner: StartsWith0X;
+      minAmount: string;
+    }
+  | {
+      kind: 'call';
+      chainId: Positive;
+      to: StartsWith0X;
+      calldata: StartsWith0X;
+      comparator: 'gte' | 'eq' | 'lte';
+      value: string;
+    };
+/**
+ * a string starting with "0x"
+ */
+export type StartsWith0X = string;
+
 export interface LifiZapConfig {
   resourceOut:
     | {
@@ -474,15 +684,6 @@ export interface LifiZapConfig {
       };
 }
 
-/**
- * a non-negative number
- */
-export type GreaterThanOrEqualTo0 = number;
-/**
- * a number between 0 and 10000
- */
-export type Between010000 = number;
-
 export interface ParaswapBuyConfig {
   resourceOut:
     | {
@@ -495,8 +696,8 @@ export interface ParaswapBuyConfig {
         chainId: Positive;
       };
   exactAmountOut: string;
-  srcDecimals: GreaterThanOrEqualTo0;
-  destDecimals: GreaterThanOrEqualTo0;
+  srcDecimals: NonNegative;
+  destDecimals: NonNegative;
   maxSlippageBps?: Between010000;
   partner?: string;
   partnerAddress?: string;

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,
-});