@lifi/composer-sdk
Version:
Public Composer SDK for building and submitting flows
342 lines (316 loc) • 13.3 kB
text/typescript
import type { ComposeCompileRequest, Flow } from '@lifi/compose-spec';
import {
type ComposeSdk,
type ContinuationSettleConfig,
createComposeSdk,
materialisers,
raw,
resources,
} from '../index.js';
import type { Address } from '../types.js';
import { API_KEY, BASE_URL, RECIPIENT } from './config.js';
const ARBITRUM = 42161;
const BASE = 8453;
const ARB_USDC = '0xaf88d065e77c8cC2239327C5EDb3A432268e5831';
const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
const WETH = '0x4200000000000000000000000000000000000006';
// Request Network's ERC20FeeProxy on Base. It moves `amount` to `to` and
// `feeAmount` to `feeAddress` from the caller with `transferFrom`, and emits
// `TransferWithReferenceAndFee` with the payment reference: the event that
// marks the invoice paid.
const ERC20_FEE_PROXY = '0x1892196E80C4c17ea5100Da765Ab48c1fE2Fb814';
const VALIDITY_WINDOW_MS = 3_600_000;
/** A Request Network invoice payable in USDC on Base. */
export interface UsdcInvoice {
readonly payee: Address;
// USDC base units (6 decimals) paid to `payee`.
readonly amount: bigint;
// USDC base units paid to `feeAddress`; may be 0.
readonly fee: bigint;
readonly feeAddress: Address;
// The invoice's payment reference (8 bytes for Request Network).
readonly paymentReference: `0x${string}`;
}
// A sample invoice for the examples: 990 USDC to the payee plus a 10 USDC fee.
export const SAMPLE_INVOICE: UsdcInvoice = {
payee: RECIPIENT,
amount: 990_000_000n,
fee: 10_000_000n,
feeAddress: '0x2222222222222222222222222222222222222222',
paymentReference: '0x8c6f1d3b4a5e7c21',
};
export interface ContinuationExactInvoiceInput {
readonly owner: Address;
readonly invoice: UsdcInvoice;
// USDC base units the escrow is funded with. Must exceed
// `invoice.amount + invoice.fee`: the surplus, the settle's only outcome,
// returns to `owner`, and an outcome must commit a positive floor.
readonly usdcAmount: `${bigint}`;
}
export interface ContinuationExactSwapInvoiceInput {
readonly owner: Address;
readonly invoice: UsdcInvoice;
// WETH base units (18 decimals) swapped to USDC. The swap's guaranteed
// minimum output must exceed `invoice.amount + invoice.fee`, for the same
// reason as `usdcAmount` above.
readonly wethAmount: `${bigint}`;
}
export interface ContinuationExactIntentInvoiceInput {
readonly owner: Address;
readonly invoice: UsdcInvoice;
// Native ETH base units (18 decimals) on Arbitrum, swapped to Arbitrum
// USDC. The swap's guaranteed minimum output must cover the input the
// solver asks for the invoice total plus one unit; the rest returns to
// `owner`.
readonly ethAmount: `${bigint}`;
}
/**
* The leg every example settles: split the invoice total off the escrowed
* USDC, pay it through `ERC20FeeProxy`, and leave the surplus in the leg's
* proxy as the settle's outcome, if the settle commits one.
*
* `core.call` declares no settlement verification, so only an exact settle
* may run it. The invoice terms are constants of the leg document, so each
* argument is a `raw.literal` of the parameter's Solidity type. The leg names
* no funding amount: at fill the executor's proxy sweeps the escrowed USDC
* into `input.funding`.
*/
const buildInvoiceLeg = (sdk: ComposeSdk, invoice: UsdcInvoice): Flow => {
const leg = sdk.flow(BASE, {
name: 'pay-invoice-leg',
inputs: { funding: resources.erc20(USDC, BASE) },
});
// `head` is the invoice total; `tail`, the surplus, stays in the proxy.
const { head } = leg.core.splitAt('invoice', {
bind: { source: leg.inputs.funding },
config: { amount: `${invoice.amount + invoice.fee}` },
});
leg.core.call('pay', {
resource: head,
bind: {
tokenAddress: raw.literal('address', USDC),
to: raw.literal('address', invoice.payee),
amount: raw.literal('uint256', `${invoice.amount}`),
paymentReference: raw.literal('bytes', invoice.paymentReference),
feeAmount: raw.literal('uint256', `${invoice.fee}`),
feeAddress: raw.literal('address', invoice.feeAddress),
},
config: {
target: ERC20_FEE_PROXY,
functionSignature:
'function transferFromWithReferenceAndFee(address tokenAddress, address to, uint256 amount, bytes paymentReference, uint256 feeAmount, address feeAddress)',
// The fee proxy pulls the USDC with `transferFrom`.
approvals: [{ spender: ERC20_FEE_PROXY }],
},
});
return leg.build();
};
/**
* The exact settle config every example shares: the leg's leftover USDC
* returns to `owner` on Base, and so does the escrow if it expires unfilled.
*/
const invoiceSettleConfig = (
sdk: ComposeSdk,
owner: Address,
invoice: UsdcInvoice,
): ContinuationSettleConfig => ({
exact: true,
outcomes: [{ token: USDC, destination: owner, chainId: BASE }],
validity: { expiresAtMs: Date.now() + VALIDITY_WINDOW_MS },
provider: 'intent-factory',
refund: owner,
continuationFlow: buildInvoiceLeg(sdk, invoice),
});
/**
* Escrow USDC on Base for an exact continuation leg that pays a Request
* Network invoice, and return the surplus to the owner.
*
* Demonstrates:
* - `exact: true` on `continuation.settle`: the escrow is bound to the leg's
* compiled calldata, so the solver runs exactly those bytes and chooses
* nothing. A committed (non-exact) leg rejects `core.call`, because a
* balance cannot prove that an invoice was paid; an exact leg admits it.
* - A leg that pays a third party (`invoice.payee`), which only an exact leg
* may do: its bytes are fixed at compile time.
* - The surplus (`usdcAmount` minus the invoice total) as the outcome. The
* compile proves its floor at the escrow's funding floor, so `minAmount` is
* omitted. A surplus of 0 proves no floor, and the compile rejects it.
* - Funding from a declared input, transferred into the escrow inline by the
* user's transaction.
*
* Reading the response:
* - `settlements.settle.escrow` holds the registered escrow. `binding` holds
* what the escrow is bound to: the solver's executor (`executionTarget`),
* the compiled leg (`calldata`), its `approvals`, and the `payload` the
* settlement service hashes into `payloadHash`.
* - Inline funding means the user's `execute` transaction funds the escrow.
* Before submitting it, check that `payloadHash` is the hash of `payload`,
* for example with viem:
* `keccak256(binding.payload) === binding.payloadHash.toLowerCase()`.
* On a mismatch, do not submit.
*
* The exact-leg rules:
* - No leg node may quote off-chain or declare an expiring route:
* `lifi.swap`, `paraswap.buy`, `core.peek` and any prepared op fail
* `validation_error` at the leg node, because the bound bytes cannot be
* re-quoted at fill.
* - The settle's funding must be an ERC-20 from a declared input, an upstream
* output, or a `lifi.bridge` or `lifiIntents.order` delivery into the
* escrow: native funding fails `validation_error`.
* - The deployment must serve exact legs (an intent-factory provider
* configured with the solver's executor); elsewhere the settle fails
* `validation_error` before any registration.
*/
export const buildContinuationExactInvoiceExample = ({
owner,
invoice,
usdcAmount,
}: ContinuationExactInvoiceInput): {
flow: Flow;
request: ComposeCompileRequest;
} => {
const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
const builder = sdk.flow(BASE, {
name: 'pay-invoice',
inputs: { usdc: resources.erc20(USDC, BASE) },
});
builder.continuation.settle('settle', {
bind: { input: builder.inputs.usdc },
config: invoiceSettleConfig(sdk, owner, invoice),
});
const flow = builder.build();
// No `sweepTo`: the funding moves into the escrow, and the surplus reaches
// the owner through the settlement, never through the user's proxy.
const request = sdk.request(flow, {
signer: owner,
inputs: {
usdc: materialisers.directDeposit({ amount: usdcAmount }),
},
// The price-impact check compares the flow's input value with its output
// value. The invoice payment leaves the flow, so the check would count it
// as lost value (1,050 USDC in, a 50 USDC surplus out: 95% impact) and
// reject the compile. `0` disables the check.
maxPriceImpactBps: 0,
});
return { flow, request };
};
/**
* Pay the same USDC invoice from WETH: the user's transaction swaps WETH to
* USDC and escrows the swap output for the exact leg.
*
* Demonstrates:
* - An exact settle funded by an upstream output (`swap.amountOut`). The
* escrow's funding floor is the swap's guaranteed minimum output, and the
* leg is proven at that floor, so the minimum must exceed the invoice total.
* - The quote rule applies to the leg only. The main flow runs inside the
* user's transaction, so its `lifi.swap` may quote; the leg, bound to fixed
* bytes until the fill, may not.
*/
export const buildContinuationExactSwapInvoiceExample = ({
owner,
invoice,
wethAmount,
}: ContinuationExactSwapInvoiceInput): {
flow: Flow;
request: ComposeCompileRequest;
} => {
const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
const builder = sdk.flow(BASE, {
name: 'swap-and-pay-invoice',
inputs: { weth: resources.erc20(WETH, BASE) },
});
const swap = builder.lifi.swap('swap', {
bind: { amountIn: builder.inputs.weth },
config: { resourceOut: resources.erc20(USDC, BASE) },
});
builder.continuation.settle('settle', {
bind: { input: swap.amountOut },
config: invoiceSettleConfig(sdk, owner, invoice),
});
const flow = builder.build();
const request = sdk.request(flow, {
signer: owner,
inputs: {
weth: materialisers.directDeposit({ amount: wethAmount }),
},
// The invoice payment leaves the flow, so the price-impact check would
// count it as lost value. `0` disables the check, and with it the only
// bound on the swap's price against the market. The swap's minimum output
// bounds only slippage against its own quote. Before signing, compare
// that minimum (`settlements.settle.escrow.floor` in the response) with
// an independent WETH price.
maxPriceImpactBps: 0,
});
return { flow, request };
};
/**
* Pay the same USDC invoice on Base from ETH on Arbitrum: the user's
* transaction swaps ETH to Arbitrum USDC and opens an exact-output LI.FI
* Intents order whose solver delivers Base USDC into the escrow.
*
* Demonstrates:
* - An exact settle funded by a `lifiIntents.order` delivery: the order omits
* `destination`, the solver delivers into the escrow on Base, and the user
* signs one transaction on Arbitrum.
* - `exactAmountOut` `T`, the invoice total, and `outcomes: []`. The leg pays
* all of `T`, so nothing is left on Base and the settle commits no outcome.
* An outcome would need a positive floor, so it would cost an extra unit of
* funding that only lands on Base as dust.
* - The escrow registers at `T` itself, with no drift margin: an exact-output
* order delivers exactly `T` on both of the compile's quotes, so the leg
* compiles at `T`.
*
* Sizing the deposit:
* - The solver quotes the Arbitrum USDC input `X` it needs for exactly `T`,
* and the order pulls exactly `X`. The swap's minimum output must cover
* `X`, or the compile fails with a 422 `preparation_error` whose failed op
* is a `validation_error` naming both amounts. Deposit enough ETH for the
* swap's minimum to clear `X` with room to spare.
* - The rest of the swap output (`order.unspentIn`) returns to `owner` as
* Arbitrum USDC through `sweepTo`, in the same transaction. All slack
* (swap slippage, the solver's price, the sizing buffer) lands there, not
* on Base.
*/
export const buildContinuationExactIntentInvoiceExample = ({
owner,
invoice,
ethAmount,
}: ContinuationExactIntentInvoiceInput): {
flow: Flow;
request: ComposeCompileRequest;
} => {
const sdk = createComposeSdk({ baseUrl: BASE_URL, apiKey: API_KEY });
const builder = sdk.flow(ARBITRUM, {
name: 'intent-and-pay-invoice',
inputs: { eth: resources.native(ARBITRUM) },
});
const swap = builder.lifi.swap('swap', {
bind: { amountIn: builder.inputs.eth },
config: { resourceOut: resources.erc20(ARB_USDC, ARBITRUM) },
});
const order = builder.lifiIntents.order('order', {
bind: { amountIn: swap.amountOut },
config: {
resourceOut: resources.erc20(USDC, BASE),
exactAmountOut: `${invoice.amount + invoice.fee}`,
},
});
builder.continuation.settle('settle', {
bind: { input: order.amountOut },
config: { ...invoiceSettleConfig(sdk, owner, invoice), outcomes: [] },
});
const flow = builder.build();
const request = sdk.request(flow, {
signer: owner,
inputs: {
eth: materialisers.directDeposit({ amount: ethAmount }),
},
// Returns the order's unspent Arbitrum USDC to the owner.
sweepTo: owner,
// The invoice payment leaves the flow, so the price-impact check would
// count it as lost value. `0` disables the check; the swap is then bounded
// only by its slippage against its own quote.
maxPriceImpactBps: 0,
});
return { flow, request };
};