@lifi/composer-sdk 0.3.0 → 0.4.0-staging.1

package/src/examples/staged/manualRelayContinuation.ts

@@ -0,0 +1,161 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import {
+  type ContinuationIntent,
+  type ContinuationOutcome,
+  createComposeSdk,
+  raw,
+  resources,
+} from '../../index.js';
+import type { Address } from '../../types.js';
+import { API_KEY, BASE_URL } from '../config.js';
+
+// USDC on Ethereum mainnet (6 decimals). Matches the funding input, the
+// committed outcome token, and the second-leg balance read below.
+const USDC = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
+
+// The self-serve settlement provider's registry name. This literal must match
+// `MANUAL_RELAY_PROVIDER_NAME` in the compose-builtins package
+// (ts/packages/compose-builtins/src/providers/manualRelay/provider.ts); that
+// package is not an SDK dependency, so it is inlined here rather than imported.
+const MANUAL_RELAY_PROVIDER = 'manual-relay';
+
+export interface ManualRelayContinuationInput {
+  /** The transaction signer for leg 1. */
+  readonly owner: Address;
+  /** Where the committed outcome is delivered — the user's own custody. */
+  readonly recipient: Address;
+  /** Funding amount for leg 1, in USDC smallest units (6 decimals). */
+  readonly amount: `${bigint}`;
+  /** Minimum USDC (smallest units) the outcome commits to delivering. */
+  readonly minAmountOut: `${bigint}`;
+  /** Unix-epoch milliseconds after which the continuation is no longer valid. */
+  readonly expiresAtMs: number;
+}
+
+/**
+ * Manual-relay (self-serve) deferred settlement — the two-leg continuation model.
+ *
+ * A `continuation.settle` node splits one intent into two legs. Leg 1 funds the
+ * settlement and commits to an outcome; leg 2 is a second flow the caller
+ * re-submits later, once the committed proceeds have actually landed. The
+ * `manual-relay` provider performs no I/O and funds no escrow — the funds stay
+ * in the user's own custody between the legs, and the caller ("relays") the
+ * second leg itself. That makes it the simplest provider to author against and
+ * the right one for a self-serve integration.
+ *
+ * Why `untypedOp`:
+ * - `continuation.settle` has no generated `builder.*` method: it is a
+ *   provider-dependent factory op (`createContinuationSettleOp`), registered at
+ *   server wiring rather than emitted into the static manifest the SDK is
+ *   generated from, so it never appears on the typed builder surface. It is
+ *   authored through the `untypedOp` escape hatch: the op id is a plain string
+ *   and its `bind`/`config` are validated by the backend at compile time rather
+ *   than by the TypeScript surface.
+ * - The funding resource is wired via `bind.input` (a resource ref); the delivery
+ *   address via `bind.destination` (an address ref), which becomes the produced
+ *   future resource's owner.
+ * - `config` is a `ContinuationIntent`. This example imports `ContinuationIntent`
+ *   and `ContinuationOutcome` from the SDK's own re-exports (`../../index.js`) to
+ *   type the config even though the op itself is untyped — the authoring types
+ *   ship publicly even while the op is staged.
+ *
+ * The committed terms:
+ * - `outcomes` — one or more `{ token, minAmount, destination, chainId }` promises.
+ *   The manual-relay provider supports exactly one outcome per settle node; model
+ *   multiple deliveries as multiple `continuation.settle` nodes.
+ * - `validity.expiresAtMs` — after this the continuation cannot be settled.
+ * - `provider` — the settlement mechanism, selected by name (`manual-relay` here).
+ * - `continuationFlow` — the inline second leg. The provider embeds the readiness
+ *   `check` into it as a pre-execution on-chain assertion before returning it, so a
+ *   premature re-submission reverts instead of running on stale balances.
+ *
+ * How to CONSUME the compile response (leg 1):
+ * - `continuations` — the list of settle nodes that produced a deferred outcome.
+ * - `phase1ByNode.<node>` — what the caller must do to fund leg 1. For manual-relay
+ *   this is `{ kind: 'none' }`: nothing to sign or fund now, the funds stay in the
+ *   user's custody. (Other providers may return `kind: 'transaction'` or `signables`.)
+ * - `continuationPlans.<node>` — `{ chainId, validity, check, nextFlow }`. Poll the
+ *   `check` (an `erc20BalanceGte` predicate here) until it passes, then re-submit
+ *   `nextFlow` verbatim through the normal `/compose` pipeline. `nextFlow` already
+ *   has the readiness check compiled in as an on-chain assertion, so an early
+ *   re-submission reverts safely rather than executing on stale state.
+ */
+export const buildManualRelayContinuation = ({
+  owner,
+  recipient,
+  amount,
+  minAmountOut,
+  expiresAtMs,
+}: ManualRelayContinuationInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  // The inline second leg. Authored as an ordinary flow via the builder; the
+  // provider will prepend the readiness assertion to it before returning it in
+  // `continuationPlans`. Here it simply reads the delivered proceeds — a real
+  // integration would deposit them into a vault, repay a loan, etc.
+  const secondLeg = sdk.flow(1, {
+    name: 'manual-relay-continuation-leg2',
+    inputs: {},
+  });
+  secondLeg.core.balanceOf('read-proceeds', {
+    bind: {},
+    config: { token: USDC, owner: recipient },
+  });
+  const continuationFlow: Flow = secondLeg.build();
+
+  // The committed outcome: at least `minAmountOut` USDC delivered to `recipient`
+  // on mainnet. `ContinuationOutcome` is the SDK-re-exported authoring type.
+  const outcome: ContinuationOutcome = {
+    token: USDC,
+    minAmount: minAmountOut,
+    destination: recipient,
+    chainId: 1,
+  };
+
+  const config: ContinuationIntent = {
+    outcomes: [outcome],
+    validity: { expiresAtMs },
+    provider: MANUAL_RELAY_PROVIDER,
+    continuationFlow,
+  };
+
+  const builder = sdk.flow(1, {
+    name: 'manual-relay-continuation-leg1',
+    inputs: {
+      usdc: resources.erc20(USDC, 1),
+      destination: 'address',
+    },
+  });
+
+  // `continuation.settle` has no generated method (it is staged), so it is added
+  // via untypedOp. `bind.input` carries the funding resource; `bind.destination`
+  // carries the delivery address. Both are plain `$ref` pointers into the flow's
+  // declared inputs — untypedOp takes wire-format refs, so `raw.ref` builds them.
+  builder.untypedOp('settle', 'continuation.settle', {
+    bind: {
+      input: raw.ref<'resource'>('input.usdc'),
+      destination: raw.ref<'address'>('input.destination'),
+    },
+    config,
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      usdc: amount,
+      destination: recipient,
+    },
+    // A deferred settle's output is a future resource with no spot value at
+    // simulation time, so the price-impact guard would register it as 100%
+    // impact. 0 disables the guard for this deferred-settlement flow.
+    maxPriceImpactBps: 0,
+  });
+
+  return { flow, request };
+};

package/src/examples/staged/morphoBlueBorrow.ts

@@ -0,0 +1,93 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../../index.js';
+import type { Address } from '../../types.js';
+import { API_KEY, BASE_URL } from '../config.js';
+
+// Morpho Blue WETH/USDC market on Base (chainId 8453).
+// The Morpho singleton address (0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb)
+// is the default `morpho` config field and is read from compose-builtins.
+const ADAPTIVE_CURVE_IRM_BASE = '0x46415998764C29aB2a25CbeA6254146D50D22687';
+const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const BASE_WETH = '0x4200000000000000000000000000000000000006';
+const WETH_USDC_ORACLE = '0xFEa2D58cEfCb9fcb597723c6bAE66fFE4193aFE4';
+const WETH_USDC_LLTV = '860000000000000000'; // 0.86e18
+
+const WETH_USDC_MARKET = {
+  loanToken: BASE_USDC,
+  collateralToken: BASE_WETH,
+  oracle: WETH_USDC_ORACLE,
+  irm: ADAPTIVE_CURVE_IRM_BASE,
+  lltv: WETH_USDC_LLTV,
+};
+
+export interface MorphoBlueBorrowInput {
+  readonly owner: Address;
+  readonly collateralAmount: `${bigint}`;
+  readonly borrowAmount: `${bigint}`;
+}
+
+/**
+ * Open a leveraged-borrow position on the Base Morpho Blue WETH/USDC market.
+ *
+ * - `morphoBlue.supplyCollateral` debits the proxy's WETH and credits
+ *   `Morpho.position(WETH_USDC_MARKET_ID, proxy).collateral`. There is no
+ *   receipt token — collateral is non-transferable accounting state.
+ * - `morphoBlue.borrow` mints debt shares against that collateral and
+ *   transfers USDC to the proxy. The borrowed asset is exposed as the
+ *   `borrowed` Resource port for downstream nodes.
+ * - The flow sweeps the borrowed USDC back to the signer's wallet via
+ *   `sweepTo` on the request.
+ */
+export const buildMorphoBlueBorrow = ({
+  owner,
+  collateralAmount,
+  borrowAmount,
+}: MorphoBlueBorrowInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  const builder = sdk.flow(8453, {
+    name: 'morpho-blue-borrow-weth-usdc',
+    inputs: {
+      assetIn: resources.erc20(BASE_WETH, 8453),
+    },
+  });
+
+  builder.morphoBlue.supplyCollateral('supply-collateral', {
+    bind: {
+      assetIn: builder.inputs.assetIn,
+    },
+    config: {
+      marketParams: WETH_USDC_MARKET,
+      mode: 'exact',
+    },
+  });
+
+  builder.morphoBlue.borrow('borrow', {
+    bind: {},
+    config: {
+      marketParams: WETH_USDC_MARKET,
+      amount: borrowAmount,
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      assetIn: materialisers.directDeposit({ amount: collateralAmount }),
+    },
+    // Sweep the borrowed USDC back to the signer.
+    sweepTo: builder.context.sender,
+    // The WETH collateral becomes unpriced Morpho position state (no receipt
+    // token), so the default 500 bps price-impact check reads any safe borrow
+    // (LLTV caps at 86%) as a loss. 0 skips the check.
+    maxPriceImpactBps: 0,
+  });
+
+  return { flow, request };
+};

package/src/examples/staged/morphoBlueRepay.ts

@@ -0,0 +1,132 @@
+import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
+
+import { createComposeSdk, materialisers, resources } from '../../index.js';
+import type { Address } from '../../types.js';
+import { API_KEY, BASE_URL } from '../config.js';
+
+// Morpho Blue WETH/USDC market on Base (chainId 8453).
+const ADAPTIVE_CURVE_IRM_BASE = '0x46415998764C29aB2a25CbeA6254146D50D22687';
+const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+const BASE_WETH = '0x4200000000000000000000000000000000000006';
+const WETH_USDC_ORACLE = '0xFEa2D58cEfCb9fcb597723c6bAE66fFE4193aFE4';
+const WETH_USDC_LLTV = '860000000000000000';
+
+const WETH_USDC_MARKET = {
+  loanToken: BASE_USDC,
+  collateralToken: BASE_WETH,
+  oracle: WETH_USDC_ORACLE,
+  irm: ADAPTIVE_CURVE_IRM_BASE,
+  lltv: WETH_USDC_LLTV,
+};
+
+export interface MorphoBlueRepayInput {
+  readonly owner: Address;
+  /** WETH supplied as collateral for the in-flow borrow (18 dp). */
+  readonly collateralAmount: `${bigint}`;
+  /** USDC borrowed against the collateral, then repaid by this flow (6 dp). */
+  readonly borrowAmount: `${bigint}`;
+  /**
+   * USDC deposited to repay the debt (6 dp). Must exceed `borrowAmount`:
+   * Morpho's share rounding can leave the debt a wei above the borrowed
+   * amount, so the `max`-mode repay needs a little headroom. The leftover
+   * surfaces on the `residual` port.
+   */
+  readonly repayAmount: `${bigint}`;
+}
+
+/**
+ * Open and close a Morpho Blue WETH/USDC position on Base in one flow —
+ * a self-contained supplyCollateral → borrow → repay → withdrawCollateral
+ * round trip that creates the debt it retires.
+ *
+ * Demonstrates:
+ * - `morphoBlue.supplyCollateral` to post WETH (collateral is internal
+ *   position state — no receipt token).
+ * - `morphoBlue.borrow` to mint USDC debt against it.
+ * - `morphoBlue.repay` with `mode: 'max'`, which reads the proxy's current
+ *   `borrowShares` on-chain and repays in shares mode to retire the debt to
+ *   the wei. Unused USDC surfaces on the `residual` Resource port.
+ * - `morphoBlue.withdrawCollateral` to pull the freed WETH once the debt
+ *   is cleared.
+ * - `sweepTo` to return the borrowed USDC, the repay residual, and the
+ *   freed WETH to the signer.
+ */
+export const buildMorphoBlueRepay = ({
+  owner,
+  collateralAmount,
+  borrowAmount,
+  repayAmount,
+}: MorphoBlueRepayInput): {
+  flow: Flow;
+  request: ComposeCompileRequest;
+} => {
+  const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
+
+  const builder = sdk.flow(8453, {
+    name: 'morpho-blue-repay-usdc-withdraw-weth',
+    inputs: {
+      collateralIn: resources.erc20(BASE_WETH, 8453),
+      repayIn: resources.erc20(BASE_USDC, 8453),
+    },
+  });
+
+  // Post WETH collateral so the proxy can open the debt it will repay.
+  builder.morphoBlue.supplyCollateral('supply-collateral', {
+    bind: {
+      assetIn: builder.inputs.collateralIn,
+    },
+    config: {
+      marketParams: WETH_USDC_MARKET,
+      mode: 'exact',
+    },
+  });
+
+  // Borrow USDC against the collateral; the borrowed USDC stays on the
+  // proxy as a terminal resource and is swept back to the signer.
+  builder.morphoBlue.borrow('borrow', {
+    bind: {},
+    config: {
+      marketParams: WETH_USDC_MARKET,
+      amount: borrowAmount,
+    },
+  });
+
+  // Retire the just-opened debt from the deposited USDC. mode 'max' reads
+  // the live borrowShares and repays in shares mode, clearing the debt to
+  // the wei; the unused USDC surfaces on the `residual` port.
+  builder.morphoBlue.repay('repay', {
+    bind: {
+      assetIn: builder.inputs.repayIn,
+      onBehalfOf: builder.context.executionAddress,
+    },
+    config: {
+      marketParams: WETH_USDC_MARKET,
+      mode: 'max',
+    },
+  });
+
+  // The debt is cleared, so the full collateral can be withdrawn. The freed
+  // WETH lands on the proxy and is swept to the signer.
+  builder.morphoBlue.withdrawCollateral('withdraw-collateral', {
+    bind: {},
+    config: {
+      marketParams: WETH_USDC_MARKET,
+      amount: collateralAmount,
+    },
+  });
+
+  const flow = builder.build();
+
+  const request = sdk.request(flow, {
+    signer: owner,
+    inputs: {
+      collateralIn: materialisers.directDeposit({ amount: collateralAmount }),
+      repayIn: materialisers.directDeposit({ amount: repayAmount }),
+    },
+    // Sweep the borrowed USDC, the repay residual, and the freed WETH back
+    // to the signer.
+    sweepTo: builder.context.sender,
+  });
+
+  return { flow, request };
+};

package/src/examples/staged/registry.ts

@@ -0,0 +1,89 @@
+// Registry of staged (not-yet-prod) examples for the live runner. This is data,
+// not a runner: src/examples/run.ts imports it via a non-literal dynamic import
+// when invoked with `--staged`, so this file (which references staged definitions)
+// is never pulled into the production type-check. It IS type-checked under
+// tsconfig.staged.json (see verify:staged).
+//
+// Running these requires the SDK regenerated with `--staged`; the example:staged
+// wrapper does that and restores production afterward.
+import type { ComposeCompileRequest } from '@lifi/compose-spec';
+
+import { OWNER, RECIPIENT } from '../config.js';
+
+import { buildAaveBorrow } from './aaveBorrow.js';
+import { buildAaveDebtRebalanceExactOut } from './aaveDebtRebalanceExactOut.js';
+import { buildAaveHealthFactorExplode } from './aaveHealthFactorExplode.js';
+import { buildAaveToMorphoDebtMigration } from './aaveToMorphoDebtMigration.js';
+import { buildAaveToMorphoDebtMigrationWithSwap } from './aaveToMorphoDebtMigrationWithSwap.js';
+import { buildAaveToMorphoDebtMigrationWithSwapExactOut } from './aaveToMorphoDebtMigrationWithSwapExactOut.js';
+import { buildTrivialFlashloanRepay } from './flashloanRepay.js';
+import { buildManualRelayContinuation } from './manualRelayContinuation.js';
+import { buildMorphoBlueBorrow } from './morphoBlueBorrow.js';
+import { buildMorphoBlueRepay } from './morphoBlueRepay.js';
+
+export const STAGED_EXAMPLES: Record<string, () => ComposeCompileRequest> = {
+  'aave-borrow': () =>
+    buildAaveBorrow({
+      owner: OWNER,
+      recipient: RECIPIENT,
+      collateralAmount: '1000000000',
+      borrowAmount: '500000000',
+    }).request,
+  'aave-hf-explode': () =>
+    buildAaveHealthFactorExplode({ signer: OWNER }).request,
+  'morpho-borrow': () =>
+    buildMorphoBlueBorrow({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      borrowAmount: '1200000000',
+    }).request,
+  'morpho-repay': () =>
+    buildMorphoBlueRepay({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      borrowAmount: '500000000',
+      repayAmount: '501000000',
+    }).request,
+  'debt-rebalance': () =>
+    buildAaveDebtRebalanceExactOut({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      debtAmount: '1000000000',
+      newDebtBorrowAmount: '965000000',
+    }).request,
+  'debt-migration-swap-exact-out': () =>
+    buildAaveToMorphoDebtMigrationWithSwapExactOut({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      debtAmount: '1000000000',
+      morphoBorrowAmount: '975000000',
+    }).request,
+  'flashloan-repay': () =>
+    buildTrivialFlashloanRepay({
+      owner: OWNER,
+      amount: '10000000000',
+      fee: '5000000',
+    }).request,
+  'debt-migration': () =>
+    buildAaveToMorphoDebtMigration({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      debtAmount: '1000000000',
+      debtFlashloanFee: '500000',
+    }).request,
+  'debt-migration-swap': () =>
+    buildAaveToMorphoDebtMigrationWithSwap({
+      owner: OWNER,
+      collateralAmount: '1000000000000000000',
+      debtAmount: '1000000000',
+      morphoBorrowAmount: '1100000000',
+    }).request,
+  'manual-relay-continuation': () =>
+    buildManualRelayContinuation({
+      owner: OWNER,
+      recipient: RECIPIENT,
+      amount: '1000000',
+      minAmountOut: '990000',
+      expiresAtMs: 1900000000000,
+    }).request,
+};

package/src/generated/materialisers.generated.ts

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