@lifi/composer-sdk 0.0.1-alpha → 0.1.0

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@lifi/composer-sdk",
-  "version": "0.0.1-alpha",
+  "version": "0.1.0",
   "description": "Public Composer SDK for building and submitting flows",
   "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lifinance/Yggdrasil.git",
+    "directory": "ts/packages/composer-sdk"
+  },
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.cjs",
@@ -30,20 +35,23 @@
     "build": "tsc --noEmit && tsup",
     "clean": "rm -rf dist out",
     "pack:local": "yarn build && mkdir -p out && yarn pack --out 'out/%s-%v.tgz'",
-    "generate": "tsx scripts/generate-sdk.ts",
+    "generate": "tsx scripts/generate-sdk/index.ts",
+    "generate:staged": "tsx scripts/generate-sdk/index.ts --staged",
     "test": "vitest run --config vitest.config.ts",
     "check:types": "tsc --noEmit",
     "check:sdk-drift": "vitest run --config vitest.drift.config.ts",
     "fix": "run-s fix:lint fix:prettier",
     "fix:lint": "eslint src --fix",
-    "fix:prettier": "prettier \"src/**/*.ts\" --write",
+    "fix:prettier": "prettier \"src/**/*.ts\" \"scripts/**/*.ts\" --write",
     "lint": "eslint src",
     "test:lint": "eslint src",
-    "test:prettier": "prettier \"src/**/*.ts\" --list-different",
-    "example": "tsx src/examples/run.ts"
+    "test:prettier": "prettier \"src/**/*.ts\" \"scripts/**/*.ts\" --list-different",
+    "verify:staged": "bash scripts/verify-staged.sh",
+    "example": "tsx src/examples/run.ts",
+    "example:staged": "tsx src/examples/run.ts --staged"
   },
   "peerDependencies": {
-    "@lifi/compose-spec": "0.0.1-alpha"
+    "@lifi/compose-spec": "0.1.0"
   },
   "dependencies": {
     "abitype": "^1.2.3",
@@ -76,6 +84,7 @@
     "!src/**/*.test.ts",
     "!src/**/*.mock.ts",
     "!src/**/*.typecheck.ts",
-    "!dist/**/*.typecheck.*"
+    "!dist/**/*.typecheck.*",
+    "!src/examples/staged/**"
   ]
 }

package/src/authoring/handles.ts

@@ -1,4 +1,4 @@
-import type { Resource } from '@lifi/compose-spec';
+import type { Resource, StaticSolType } from '@lifi/compose-spec';
 
 import type { OutputKind, TypedRef } from '../types.js';
 
@@ -59,23 +59,32 @@ export const handleToRef = (h: AnyHandle): { $ref: string } => {
 };
 
 /**
- * For a bind slot expecting type T, also accept `'resource'`-tagged
- * handles when T is `'uint256'` (resources are uint256 amounts).
+ * For a bind slot expecting type T, widen the set of accepted handle types:
+ * - `'bytes32'` is the raw 32-byte word type: accept any static-32-byte handle
+ *   (`uint256`/`uintN`/`address`/`bool`/`bytes32`) plus `'resource'` (a uint256
+ *   amount). At the IR1 boundary every value is a type-erased word, so any
+ *   static-32-byte handle is a sound bind for a `bytes32` payload port.
+ * - `'uint256'` keeps its existing widening to also accept `'resource'`-tagged
+ *   handles (resources are uint256 amounts).
+ * - every other type keeps exact-SolType matching.
  */
-type ResourceAssignable<T extends OutputKind> = T extends 'uint256'
-  ? T | 'resource'
-  : T;
+type SlotAssignable<T extends OutputKind> = T extends 'bytes32'
+  ? StaticSolType | 'resource'
+  : T extends 'uint256'
+    ? T | 'resource'
+    : T;
 
 /**
  * The set of values accepted by a typed bind slot.
  * - `OutputHandle<T>` / `InputHandle<T>` (same type)
  * - For `'uint256'` slots, also `'resource'`-tagged handles
- * - `TypedRef<T>` (typed context refs, subject to `ResourceAssignable`)
+ * - For `'bytes32'` slots, any static-32-byte handle (and `'resource'`)
+ * - `TypedRef<T>` (typed context refs, subject to `SlotAssignable`)
  *
  * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`
  * to create a typed ref when you need to reference a raw path.
  */
 export type Bindable<T extends OutputKind> =
-  | OutputHandle<ResourceAssignable<T>>
-  | InputHandle<ResourceAssignable<T>>
-  | TypedRef<ResourceAssignable<T>>;
+  | OutputHandle<SlotAssignable<T>>
+  | InputHandle<SlotAssignable<T>>
+  | TypedRef<SlotAssignable<T>>;

package/src/authoring/signatureArgs.ts

@@ -187,7 +187,7 @@ const resolvePositionalArgs = (
 
   return paramNames.map((name) => {
     const bindable = bind[name];
-    if (bindable == null) {
+    if (bindable === undefined) {
       throw new Error(
         `${label}: bind value for parameter "${name}" is undefined`,
       );
@@ -211,7 +211,7 @@ export const buildCallWireFormat = (
     args.bind,
     args.config,
   );
-  const hasResource = args.resource != null;
+  const hasResource = args.resource !== undefined;
 
   return {
     op: hasResource ? 'core.call' : 'core.invoke',

package/src/client.ts

@@ -201,7 +201,7 @@ export const createComposeClient = (
     options?: GetZapPacksOptions,
   ): Promise<readonly ZapPackOverview[]> => {
     const params = new URLSearchParams();
-    if (options?.protocols != null) {
+    if (options?.protocols !== undefined) {
       // Backend expects a single comma-separated value, not repeated keys.
       const raw = options.protocols;
       const list = typeof raw === 'string' ? raw : raw.join(',');

package/src/examples/aaveClaimRewards.ts

@@ -0,0 +1,80 @@
+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 incentives contracts on Ethereum mainnet.
+const REWARDS_CONTROLLER = '0x8164Cc65827dcFe994AB23944CBC90e0aa80bFcb';
+const AAVE = '0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9';
+// Receipt-token positions the proxy holds and that accrue AAVE rewards.
+const A_ETH_USDC = '0x98C23E9d8f34FEFb1B7BD6a91B7FF122F4e16F5c';
+const VDEBT_USDC = '0x72E95b8931767C79bA4EeE721354d6E99a61D004';
+
+export interface AaveClaimRewardsInput {
+  readonly owner: Address;
+  readonly recipient: Address;
+}
+
+/**
+ * Claim accrued AAVE rewards from a set of Aave v3 receipt-token positions,
+ * then forward the claimed amount to a recipient.
+ *
+ * The op surfaces the claimed AAVE as a tracked resource (`claimed`) so
+ * downstream nodes can spend or forward it. With no `amount` configured,
+ * Aave claims the full accrued balance (MaxUint256 sentinel).
+ *
+ * Demonstrates:
+ * - `aave.claimRewards` against multiple aToken/vDebt positions.
+ * - Routing the `claimed` resource output into `core.transfer`.
+ * - The `claimedAmount` handle for assertions or downstream arithmetic.
+ */
+export const buildAaveClaimRewards = ({
+  owner,
+  recipient,
+}: AaveClaimRewardsInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'aave-claim-rewards',
+    inputs: {
+      recipient: 'address',
+    },
+  });
+
+  const claimOut = builder.aave.claimRewards('claim', {
+    bind: {},
+    config: {
+      rewardsController: REWARDS_CONTROLLER,
+      assets: [A_ETH_USDC, VDEBT_USDC],
+      reward: AAVE,
+      // amount omitted → claim full accrued balance.
+      // to omitted → rewards land on the proxy (executionAddress).
+    },
+  });
+
+  // Forward the claimed AAVE to the requested recipient.
+  builder.core.transfer('forward-rewards', {
+    bind: {
+      amount: claimOut.claimed,
+      recipient: builder.inputs.recipient,
+    },
+    config: {},
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      recipient,
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/aaveRepay.ts

@@ -0,0 +1,69 @@
+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';
+
+// Aave v3 contracts on Ethereum mainnet.
+const AAVE_V3_POOL = '0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2';
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+
+export interface AaveRepayInput {
+  readonly owner: Address;
+  readonly amount: `${bigint}`;
+}
+
+/**
+ * Repay an Aave v3 variable-rate WETH debt by supplying WETH to the proxy.
+ *
+ * Aave internally caps the repay at `min(amount, outstandingDebt)`, so the
+ * op returns any unspent WETH on the `residual` resource port. The
+ * residual is swept back to the sender on completion.
+ *
+ * Demonstrates:
+ * - `aave.repay` with a resource input (the WETH used to repay).
+ * - Binding `onBehalfOf` from the runtime context — the proxy repays its
+ *   own debt position.
+ * - The `residual` port for surfacing any unused input back to the caller.
+ */
+export const buildAaveRepay = ({
+  owner,
+  amount,
+}: AaveRepayInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'aave-repay-weth',
+    inputs: {
+      assetIn: resources.erc20(WETH, 1),
+    },
+  });
+
+  builder.aave.repay('repay', {
+    bind: {
+      assetIn: builder.inputs.assetIn,
+      onBehalfOf: builder.context.executionAddress,
+    },
+    config: {
+      pool: AAVE_V3_POOL,
+      mode: 'exact',
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      assetIn: materialisers.directDeposit({ amount }),
+    },
+    // Any unspent WETH (residual) is swept back to the signer.
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

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

@@ -0,0 +1,75 @@
+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';
+
+// Example ERC-4626 vault address (Steakhouse USDC on Ethereum mainnet)
+const VAULT = '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB';
+
+export interface EmitCustomEventInput {
+  readonly owner: Address;
+}
+
+/**
+ * Emit a custom on-chain event from a compose flow.
+ *
+ * Demonstrates:
+ * - core.emitEvent2 — surfacing an arbitrary `Rebalance(address,uint256)` event
+ * - Binding mixed-type handles (an `address` context ref and a `uint256` read)
+ *   directly to the op's `bytes32` value ports — no `raw.ref` cast, because
+ *   bytes32 ports are the raw 32-byte word type and accept any static-32-byte
+ *   handle.
+ *
+ * The emitted log is a fixed VM event whose first data word is
+ * keccak256("Rebalance(address,uint256)") (a discriminator), followed by the
+ * execution address and the vault total — an indexer reads the discriminator
+ * to recognise the event and decodes the two values.
+ */
+export const buildEmitCustomEvent = ({
+  owner,
+}: EmitCustomEventInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  const builder = sdk.flow(1, {
+    name: 'emit-custom-event',
+    inputs: {},
+  });
+
+  // Read the vault's total assets at execution time — a fresh uint256 handle.
+  const vaultTotal = builder.core.staticCall('vault-total', {
+    bind: {},
+    config: {
+      target: VAULT,
+      functionSignature: 'function totalAssets() view returns (uint256)',
+    },
+  });
+
+  // Emit Rebalance(address,uint256): the executing address plus the vault total.
+  // value0 (address) and value1 (uint256) bind directly to the bytes32 ports.
+  builder.core.emitEvent2('log-rebalance', {
+    bind: {
+      value0: builder.context.executionAddress,
+      value1: vaultTotal.result,
+    },
+    config: {
+      signature: 'Rebalance(address,uint256)',
+    },
+  });
+
+  const flow = builder.build();
+
+  // No `sweepTo`: this flow only reads and emits a log — it moves no funds, so
+  // there are no proxy-held terminal resources to sweep. Specifying `sweepTo`
+  // here would fail compilation with "no ... terminal resources ... to sweep".
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {},
+  });
+
+  return { flow, request };
+};

package/src/examples/invariantChecks.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';
+
+const WETH = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2';
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+export interface InvariantChecksInput {
+  readonly owner: Address;
+  readonly spender: Address;
+  readonly amount: `${bigint}`;
+  readonly minAmountOut: `${bigint}`;
+}
+
+/**
+ * Swap WETH → USDC via LI.FI, then layer two of the newly-exposed invariant
+ * ops on the result.
+ *
+ * Demonstrates:
+ * - `invariant.numeric` asserting the swap output is at least a constant
+ *   threshold (`amountOut >= minAmountOut`) — a constant-threshold check that
+ *   needs no second on-chain value to compare against.
+ * - `invariant.allowanceAtLeast` asserting the execution proxy still permits
+ *   `spender` to move at least the swapped USDC on its behalf.
+ * - Binding a swap's `amountOut` resource handle into both a `uint256` numeric
+ *   slot and a `resource` allowance slot.
+ *
+ * Both ops compile to on-chain `AssertRawInvariant` instructions; the run
+ * reverts if either assertion is violated.
+ */
+export const buildInvariantChecks = ({
+  owner,
+  spender,
+  amount,
+  minAmountOut,
+}: InvariantChecksInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL });
+
+  // One WETH resource input plus a scalar spender address.
+  const builder = sdk.flow(1, {
+    name: 'invariant-checks',
+    inputs: {
+      amountIn: resources.erc20(WETH, 1),
+      spender: 'address',
+    },
+  });
+
+  // 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 swap produced at least `minAmountOut` USDC. The threshold is a
+  // configured constant, so this is `invariant.numeric` rather than a
+  // handle-vs-handle compare.
+  builder.invariant.numeric('min-out', {
+    bind: { value: swapOutputs.amountOut },
+    config: { op: 'gte', threshold: minAmountOut },
+  });
+
+  // Assert the execution proxy still grants `spender` an allowance of at least
+  // the swapped USDC amount.
+  builder.invariant.allowanceAtLeast('check-allowance', {
+    bind: {
+      minimumAmount: swapOutputs.amountOut,
+      owner: builder.context.executionAddress,
+      spender: builder.inputs.spender,
+    },
+  });
+
+  const flow = builder.build();
+
+  // directDeposit marks amountIn as a fixed amount of WETH pre-deposited into
+  // the VM; the spender address is supplied as a plain scalar input.
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      amountIn: materialisers.directDeposit({ amount }),
+      spender,
+    },
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};