@lifi/composer-sdk 0.0.1-alpha

package/src/examples/swapWithAllowRevert.ts

@@ -0,0 +1,119 @@
+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 with `simulationPolicy: 'allow-revert'`.
+ *
+ * Demonstrates:
+ * - Opting into partial results when simulation detects a revert
+ * - The `ComposeCompileResult` discriminated union (`status: 'success' | 'partial'`)
+ * - Inspecting `simulationRevert` diagnostics on a partial result
+ * - Using `checkOnChainAllowances` to filter already-sufficient approvals
+ *
+ * When the compiled transaction reverts in simulation:
+ * - Default (`simulationPolicy: 'strict'`): the API returns HTTP 422 and the SDK throws.
+ * - With `simulationPolicy: 'allow-revert'`: the API returns HTTP 206 and the SDK returns
+ *   a partial result containing the transaction (without `gasLimit`) and revert diagnostics.
+ *   The caller can inspect the revert reason and decide whether to submit anyway.
+ */
+export const buildSwapWithAllowRevertExample = (): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'swap-weth-to-usdc-allow-revert',
+    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 flow = builder.build();
+
+  // Pass simulationPolicy and checkOnChainAllowances in the run inputs.
+  // 'allow-revert' tells the backend to return a partial result instead of
+  // a 422 error when the transaction reverts in simulation.
+  const request = sdk.request(flow, {
+    signer: OWNER,
+    inputs: {
+      amountIn: materialisers.directDeposit({
+        amount: '1000000000000000000',
+      }),
+    },
+    sweepTo: builder.context.sender,
+    simulationPolicy: 'allow-revert',
+    checkOnChainAllowances: true,
+  });
+
+  return { flow, request };
+};
+
+/**
+ * Shows how to handle the `ComposeCompileResult` discriminated union
+ * returned by `sdk.client.compile()`.
+ *
+ * This function is illustrative — it cannot run without a live backend,
+ * but demonstrates the branching pattern callers should use.
+ */
+export const handleCompileResult = async (): Promise<void> => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    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 result = await builder.compile({
+    signer: OWNER,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: '1000000000000000000' }),
+    },
+    simulationPolicy: 'allow-revert',
+  });
+
+  if (result.status === 'success') {
+    // Full success — transactionRequest includes gasLimit.
+    const { transactionRequest, userProxy, producedResources } = result;
+    void transactionRequest;
+    void userProxy;
+    void producedResources;
+    return;
+  }
+
+  // Partial result — simulation reverted but a transaction is still available.
+  // transactionRequest omits gasLimit; the caller must estimate gas themselves.
+  const { transactionRequest, simulationRevert, error } = result;
+  void transactionRequest;
+
+  // Inspect the revert reason.
+  void simulationRevert.code;
+  void simulationRevert.rawErrorBytes;
+  if (simulationRevert.decodeResult?.errorCandidates) {
+    for (const candidate of simulationRevert.decodeResult.errorCandidates) {
+      void candidate.decodedErrorSignature;
+      void candidate.decodedParams;
+    }
+  }
+
+  // The error envelope from the server.
+  void error.kind; // e.g. 'simulation_revert'
+  void error.message; // human-readable description
+};

package/src/examples/swapWithBalanceCheck.ts

@@ -0,0 +1,73 @@
+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';
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+export interface SwapWithBalanceCheckInput {
+  readonly owner: Address;
+  readonly amount: `${bigint}`;
+}
+
+/**
+ * Swap WETH to USDC via LI.FI, then assert the execution contract holds
+ * at least the swapped amount.
+ *
+ * Demonstrates:
+ * - Using builder.context.executionAddress to reference the VM contract
+ * - invariant.balanceAtLeast as a post-swap safety check
+ * - No hardcoded contract address — the context provides it at compile time
+ */
+export const buildSwapWithBalanceCheck = ({
+  owner,
+  amount,
+}: SwapWithBalanceCheckInput): {
+  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-balance-check',
+    inputs: {
+      amountIn: resources.erc20(WETH, 1),
+    },
+  });
+
+  // Swap WETH → USDC via LI.FI.
+  const swapOutputs = builder.lifi.swap('swap', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: {
+      resourceOut: resources.erc20(USDC, 1),
+      slippage: 0.03,
+    },
+  });
+
+  // Assert the VM execution contract holds at least the swapped USDC amount.
+  // builder.context.executionAddress resolves to the contract at compile time.
+  builder.invariant.balanceAtLeast('check-usdc', {
+    bind: {
+      minimumAmount: swapOutputs.amountOut,
+      account: builder.context.executionAddress,
+    },
+  });
+
+  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 }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/swapWithOutputValidation.ts

@@ -0,0 +1,125 @@
+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';
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+export interface SwapWithOutputValidationInput {
+  readonly owner: Address;
+  readonly amount: `${bigint}`;
+  readonly expectedOut: `${bigint}`;
+}
+
+/**
+ * Swap WETH to USDC, then validate the output amount against computed
+ * slippage bounds.
+ *
+ * Demonstrates:
+ * - core.bpsDown / core.bpsUp to compute lower and upper bounds
+ * - core.subtract / core.add for threshold arithmetic
+ * - All seven assertion ops for output validation
+ */
+export const buildSwapWithOutputValidation = ({
+  owner,
+  amount,
+  expectedOut: _expectedOut,
+}: SwapWithOutputValidationInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'swap-with-output-validation',
+    inputs: {
+      amountIn: resources.erc20(WETH, 1),
+    },
+  });
+
+  // Swap WETH → USDC.
+  const swapOutputs = builder.lifi.swap('swap', {
+    bind: { amountIn: builder.inputs.amountIn },
+    config: {
+      resourceOut: resources.erc20(USDC, 1),
+      slippage: 0.03,
+    },
+  });
+
+  // Compute slippage bounds from the expected output.
+  // Lower bound: expectedOut * (10000 - 300) / 10000 (3% slippage down)
+  const lowerBound = builder.core.bpsDown('lower-bound', {
+    bind: { value: swapOutputs.amountOut },
+    config: { bps: 9700 },
+  });
+
+  // Upper bound: expectedOut * (10000 + 100) / 10000 (1% above expected)
+  const upperBound = builder.core.bpsUp('upper-bound', {
+    bind: { value: swapOutputs.amountOut },
+    config: { bps: 10100 },
+  });
+
+  // Derive a margin value: upper - lower
+  const margin = builder.core.subtract('margin', {
+    bind: { a: upperBound.result, b: lowerBound.result },
+  });
+
+  // Sanity check: lower + margin should reconstruct the gap
+  const reconstructed = builder.core.add('reconstructed', {
+    bind: { a: lowerBound.result, b: margin.result },
+  });
+
+  // Validate: output >= lower bound
+  builder.core.assertGte('check-gte-lower', {
+    bind: { a: swapOutputs.amountOut, b: lowerBound.result },
+  });
+
+  // Validate: output <= upper bound
+  builder.core.assertLte('check-lte-upper', {
+    bind: { a: swapOutputs.amountOut, b: upperBound.result },
+  });
+
+  // Validate: output falls within [lower, upper] range
+  builder.core.assertInRange('check-range', {
+    bind: {
+      value: swapOutputs.amountOut,
+      min: lowerBound.result,
+      max: upperBound.result,
+    },
+  });
+
+  // Validate: upper bound > lower bound
+  builder.core.assertGt('check-upper-gt-lower', {
+    bind: { a: upperBound.result, b: lowerBound.result },
+  });
+
+  // Validate: lower bound < upper bound (inverse check)
+  builder.core.assertLt('check-lower-lt-upper', {
+    bind: { a: lowerBound.result, b: upperBound.result },
+  });
+
+  // Validate: reconstructed gap equals upper - lower identity
+  builder.core.assertEqual('check-reconstruction', {
+    bind: { a: reconstructed.result, b: upperBound.result },
+  });
+
+  // Validate: lower and upper bounds are distinct
+  builder.core.assertNotEqual('check-bounds-distinct', {
+    bind: { a: lowerBound.result, b: upperBound.result },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/transferTokens.ts

@@ -0,0 +1,123 @@
+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';
+
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+export interface TransferTokensInput {
+  readonly owner: Address;
+  readonly recipient: Address;
+  readonly amount: `${bigint}`;
+}
+
+/**
+ * Transfer ERC-20 tokens from the proxy to an arbitrary recipient.
+ *
+ * Demonstrates:
+ * - `core.transfer` to move tokens to a recipient address
+ * - Binding a scalar handle input (`recipient`) alongside a resource input
+ * - Optionally specifying a partial transfer amount via `config.amount`
+ *   (omit to transfer the full balance)
+ * - The `transferred` and `remainder` output ports
+ */
+export const buildTransferTokens = ({
+  owner,
+  recipient,
+  amount,
+}: TransferTokensInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'transfer-usdc',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+      recipient: 'address',
+    },
+  });
+
+  // Transfer the full input amount to the recipient.
+  // The `transferred` port tracks what was sent; `remainder` tracks what's left.
+  builder.core.transfer('send', {
+    bind: {
+      amount: builder.inputs.amountIn,
+      recipient: builder.inputs.recipient,
+    },
+    config: {},
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount }),
+      recipient,
+    },
+  });
+
+  return { flow, request };
+};
+
+/**
+ * Transfer a partial amount, keeping the remainder in the proxy.
+ *
+ * Demonstrates:
+ * - `config.amount` to transfer a specific sub-amount
+ * - Using the `remainder` output port for subsequent operations
+ */
+export const buildPartialTransfer = ({
+  owner,
+  recipient,
+  amount,
+}: TransferTokensInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'partial-transfer-usdc',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+      recipient: 'address',
+    },
+  });
+
+  // Transfer a fixed 0.5 USDC (500000 base units at 6 decimals);
+  // the remainder stays on the proxy for subsequent operations.
+  const out = builder.core.transfer('send-half', {
+    bind: {
+      amount: builder.inputs.amountIn,
+      recipient: builder.inputs.recipient,
+    },
+    config: { amount: '500000' },
+  });
+
+  // Use the remainder in a swap.
+  builder.lifi.swap('swap-remainder', {
+    bind: { amountIn: out.remainder },
+    config: {
+      resourceOut: resources.native(1),
+      slippage: 0.03,
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount }),
+      recipient,
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/untypedOpWithTypedRef.ts

@@ -0,0 +1,77 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, raw, resources } 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';
+
+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>()`.
+ *
+ * Demonstrates:
+ * - `builder.untypedOp()` to add a node the typed API doesn't cover
+ *   (e.g. a custom vault query).
+ * - `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.
+ * - Mixing untyped and typed nodes in the same flow.
+ */
+export const buildUntypedOpWithTypedRef = ({
+  owner,
+}: UntypedOpWithTypedRefInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'untyped-op-with-typed-ref',
+    inputs: {
+      amountIn: resources.erc20(USDC, 1),
+    },
+  });
+
+  // Insert an untyped node for a custom vault query. 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 },
+  });
+
+  // Use raw.ref to bridge the untyped node's output into a typed operation.
+  // The type parameter <'uint256'> tells the compiler this ref produces a
+  // uint256, so it's accepted by Bindable<'uint256'> slots.
+  const vaultResult = raw.ref<'uint256'>('vault-query.result');
+
+  // Feed the raw result into typed arithmetic — the compiler checks that
+  // vaultResult (typed as uint256) is compatible with the uint256 bind slot.
+  const scaled = builder.core.multiply('scale', {
+    bind: { a: vaultResult, b: vaultResult },
+  });
+
+  // Continue with fully typed operations downstream.
+  builder.core.assertGte('check-min', {
+    bind: { a: scaled.result, b: builder.inputs.amountIn },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount: '1000000' }),
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/generated/config.generated.ts

@@ -0,0 +1,174 @@
+// AUTO-GENERATED from manifest.json — do not edit by hand.
+// Regenerate with: yarn workspace @lifi/composer-sdk generate
+
+import type { Address, IntegerStringInput } from '../types.js';
+
+export interface CoreSplitConfig {
+  bps: number;
+}
+
+/**
+ * a positive number
+ */
+export type Positive = number;
+
+export interface LifiSwapConfig {
+  resourceOut:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
+  slippage?: number;
+  timing?: {
+    swapStepTimingStrategies?: {
+      strategy: 'minWaitTime';
+      minWaitTimeMs: number;
+      startingExpectedResults: number;
+      reduceEveryMs: number;
+    }[];
+    routeTimingStrategies?: {
+      strategy: 'minWaitTime';
+      minWaitTimeMs: number;
+      startingExpectedResults: number;
+      reduceEveryMs: number;
+    }[];
+  };
+}
+
+export interface LifiZapConfig {
+  resourceOut:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
+}
+
+export interface CoreBpsDownConfig {
+  bps: number;
+}
+
+export interface CoreBpsUpConfig {
+  bps: number;
+}
+
+export interface CoreApproveConfig {
+  spender: Address;
+}
+
+export interface CoreBalanceOfConfig {
+  token: Address;
+  owner?: Address;
+}
+
+export interface CoreTransferConfig {
+  amount?: IntegerStringInput;
+}
+
+export interface CoreCallConfig {
+  target: Address;
+  functionSignature: string;
+  callType?: 'Call' | 'ValueCall';
+  args?: Unknown[];
+  approvals?: {
+    spender: Address;
+  }[];
+}
+export interface Unknown {
+  [k: string]: unknown;
+}
+
+export interface CoreStaticCallConfig {
+  target: Address;
+  functionSignature: string;
+  args?: Unknown[];
+}
+
+export interface CoreRawCallConfig {
+  target: Address;
+  calldata: string;
+  callType?: 'Call' | 'StaticCall' | 'ValueCall' | 'DelegateCall';
+  resultType?: string;
+}
+
+export interface CoreInvokeConfig {
+  target: Address;
+  functionSignature: string;
+  callType?: 'Call' | 'ValueCall';
+  args?: Unknown[];
+}
+
+export interface CoreAsResourceConfig {
+  resource:
+    | {
+        kind: 'native';
+        chainId: Positive;
+      }
+    | {
+        kind: 'erc20';
+        token: Address;
+        chainId: Positive;
+      };
+}
+
+export interface CorePeekConfig {
+  target: Address;
+  functionSignature: string;
+  args?: string[];
+}
+
+/**
+ * a number between 0 and 10000
+ */
+export type Between010000 = number;
+
+export interface SlippageGuardConfig {
+  port: string;
+  bps: Between010000;
+}
+
+export interface BalanceOfMaterialiserConfig {
+  owner: Address;
+}
+
+export type DirectDepositMaterialiserConfig =
+  | {
+      amount: IntegerStringInput;
+      allowNonExact?: false;
+    }
+  | {
+      amount?: IntegerStringInput;
+      allowNonExact: true;
+    };
+
+export interface CallMaterialiserConfig {
+  target: Address;
+  calldata: string;
+}
+
+export interface Erc20BalancePreconditionConfig {
+  wallet: Address;
+  token: Address;
+  balance: IntegerStringInput;
+}
+
+export interface NativeBalancePreconditionConfig {
+  wallet: Address;
+  balance: IntegerStringInput;
+}
+
+export interface Erc20AllowancePreconditionConfig {
+  owner: Address;
+  spender: Address;
+  token: Address;
+  allowance: IntegerStringInput;
+}

package/src/generated/guards.generated.ts

@@ -0,0 +1,14 @@
+// AUTO-GENERATED from manifest.json — do not edit by hand.
+// Regenerate with: yarn workspace @lifi/composer-sdk generate
+
+import type { TypedGuard } from '../types.js';
+
+import type { SlippageGuardConfig } from './config.generated.js';
+
+/** Assert that output amounts are within a slippage tolerance in basis points */
+export const slippage = <P extends string>(
+  config: Omit<SlippageGuardConfig, 'port'> & { port: P },
+): TypedGuard<P> => ({
+  kind: 'slippage',
+  ...config,
+});