UNPKG

@lifi/compose-spec

Version:

Public wire-format types and schemas for Compose flows

232 lines (213 loc) • 9.44 kB
import type { VerificationDescriptor } from './descriptor.js'; import type { InputSpec, Precondition } from './flow.js'; import type { Flow, ForwardTo } from './flowSchema.js'; import type { Outputs } from './output.js'; import type { Resource } from './resource.js'; import type { SettlementWire } from './zodSchemas.js'; export type SimulationPolicy = 'strict' | 'allow-revert'; export interface ComposeRun { readonly inputs: Record<string, InputSpec>; readonly preconditions?: readonly Precondition[]; readonly signer: string; readonly assumptions?: Record<string, bigint>; readonly referrer?: string; readonly maxPriceImpactBps?: number; // Sugar for `flow.epilogue.remainder`; zap-backend desugars it before the // compile. readonly sweepTo?: ForwardTo; readonly simulationPolicy?: SimulationPolicy; /** * Also simulate the final user-facing transaction. Defaults to `false`; * reverts honour `simulationPolicy` and a success is echoed back as * `userProgramSimulation`. */ readonly simulateUserProgram?: boolean; readonly checkOnChainAllowances?: boolean; } export interface ComposeCompileRequest { readonly flow: Flow; readonly run: ComposeRun; } export interface PriceImpact { readonly inputValueUsd: number; readonly outputValueUsd: number; readonly impactBps: number; readonly unpricedInputs: readonly string[]; readonly unpricedOutputs: readonly string[]; } export interface ApprovalEntry { readonly token: string; readonly spender: string; readonly amount: string; readonly transactionRequest: { readonly to: string; readonly data: string; readonly value: '0'; }; } export interface SimulationRevert { readonly code: number; readonly rawErrorBytes: string; readonly decodeResult?: { readonly errorCandidates?: readonly { readonly decodedErrorSignature: string; readonly decodedParams: readonly string[]; }[]; readonly error?: string; }; } export interface ComposeTransactionRequest { readonly to: string; readonly chainId: number; readonly data: string; readonly value: string; readonly gasLimit?: string; } // Hand-mirrored from `ComposeActionSchema`, the OpenAPI source of truth in // `@lifi/api-schemas`. Discriminated on `purpose`; the settlement-specific // actions (`fundEscrow`, `signOrder`) name their settle node. Narrow on `kind` // before reading `transactionRequest`. export type ComposeAction = | { readonly kind: 'transaction'; readonly purpose: 'approval' | 'execute'; readonly submitter: 'signer' | 'anyone'; readonly transactionRequest: ComposeTransactionRequest; } | { readonly kind: 'transaction'; readonly purpose: 'fundEscrow'; readonly submitter: 'signer' | 'anyone'; readonly transactionRequest: ComposeTransactionRequest; readonly nodeId: string; } | { readonly kind: 'typedData'; readonly purpose: 'signOrder'; readonly submitter: 'signer'; readonly nodeId: string; readonly typedData: readonly unknown[]; }; // Continuation fields shared by the success and partial-error responses, so the // two shapes cannot drift. `settlements` reuses the Zod-inferred wire type from // `zodSchemas.ts`, pinning it to the server contract. interface ComposeContinuationData { // How each `continuation.settle` node settles, keyed by node id. Absent for // a flow with no settle node. readonly settlements?: Record<string, SettlementWire>; } // One funding leg the compiled fill consumes: the resource input's name, its // token (native → zero address) and chain, and the statically resolved amount // as a decimal string (verified continuations, plan GD-8, seam C5). `nodeId` // names the `continuation.settle` node this input funds (the `settlements` / // `actions` key); absent when the input funds no settle leg (e.g. a plain // swap's input). export interface SpendEntry { readonly input: string; readonly token: string; readonly chainId: number; readonly amount: string; readonly nodeId?: string; } // The optional user-program simulation result, present only when the request // opted in via `run.simulateUserProgram` and the simulation succeeded. // Hand-mirrored from api-schemas' `ComposeUserProgramSimulationOkSchema`. export interface ComposeUserProgramSimulation { readonly status: 'ok'; readonly returnData: string; } // One advisory finding the compiler raised without failing the compile, e.g. a // tight slippage bound on a highly volatile token. Hand-mirrored from // api-schemas' `ComposeWarningSchema`. `path`, `port`, and `fix` mean what they // mean on a compile error. `kind` is an open set: a new kind ships in a patch // release, so a reader must tolerate a kind it does not know. export interface ComposeWarning { readonly kind: string; readonly message: string; readonly path?: string; readonly port?: string; readonly fix?: string; } // The solver-extractable fill (verified continuations, GD-8/GD-6, seam C5), // present on every compiled success. Hand-mirrored to api-schemas' `fill` // object (the OpenAPI source of truth; this package cannot depend on it). // `spends` is the amount the fill may spend of each funding input — the exact // amount, or the pull cap of a non-exact deposit whose realised deposit is // measured on-chain; `validUntilMs` is the fill freshness bound (earliest // prepared-node expiry) — ABSENT = no expiry. // The fill is transaction-scoped; the leg-scoped C4 verification echo lives in // the sibling `verificationByNode` record. export interface ComposeFill { readonly spends: readonly SpendEntry[]; readonly validUntilMs?: number; } // One named epilogue forward as executed: the proxy's whole balance of // `resource`, moved to `to`, as the simulation measured it. Hand-mirrored from // api-schemas' `ExecutedForwardSchema`; the SDK decodes `amount` to `bigint`. export interface ExecutedForward { readonly resource: Resource; readonly to: string; readonly amount: bigint; } // The flow's epilogue as executed. The remainder is not measured: it reports // its resolved address only, and its effect on `outputs` is a re-owned // `owner`. Absent when the flow has no epilogue (and never on a partial // result, which measured nothing). export interface ExecutedEpilogue { readonly forwards: readonly ExecutedForward[]; readonly remainder?: string; } export interface ComposeCompileSuccessData extends ComposeContinuationData { // Every linear resource output port, consumed or terminal, keyed // `<nodeId>.<portName>`, and every resource input no node spends, keyed // `input.<name>`. See `Output` for the per-entry rules. Hand-mirrored // from api-schemas' `OutputSchema` (the OpenAPI source of truth; this // package cannot depend on it); the SDK decodes the wire strings to `bigint`. readonly outputs: Outputs; readonly epilogue?: ExecutedEpilogue; // The OpenAPI source of truth documents the optionality and funding modes. readonly transactionRequest?: ComposeTransactionRequest; readonly actions?: readonly ComposeAction[]; readonly userProxy: string; readonly priceImpact?: PriceImpact; readonly approvals?: readonly ApprovalEntry[]; // The optional user-program simulation echo, present only when the request // opted in via `run.simulateUserProgram` and the simulation succeeded. readonly userProgramSimulation?: ComposeUserProgramSimulation; // GD-8 settlement-fill surface (seam C5): the solver-extractable `fill`, // present on every success response — the funding legs it consumes and the // freshness bound (absent = no expiry). readonly fill?: ComposeFill; // The C4 verification echo, keyed by the flow node that carried the // commitment (the `continuation.commitment` node on a settlement // re-submission, each committing `continuation.settle` node on // authoring-time provider verification). Present only when the compile // committed a validation program; one entry per committing node, so a // fan-out across committed settles carries several. readonly verificationByNode?: Record<string, VerificationDescriptor>; // Advisory findings in the order the compiler raised them. Absent when it // raised none; never an empty array. readonly warnings?: readonly ComposeWarning[]; } export interface ComposeCompilePartialData extends ComposeContinuationData { // Mirrors `ComposeCompileSuccessData.outputs`. A revert measured nothing, so // estimates are quotes and minimums are op-sourced. readonly outputs: Outputs; readonly transactionRequest: ComposeTransactionRequest; readonly userProxy: string; readonly simulationRevert: SimulationRevert; readonly approvals?: readonly ApprovalEntry[]; readonly actions?: readonly ComposeAction[]; // The optional user-program simulation echo, present only when the request // opted in via `run.simulateUserProgram` and the simulation succeeded. readonly userProgramSimulation?: ComposeUserProgramSimulation; // Mirrors `ComposeCompileSuccessData.warnings`: a reverted compile keeps the // warnings its compile raised. readonly warnings?: readonly ComposeWarning[]; } export type ComposeCompileResult = | (ComposeCompileSuccessData & { readonly status: 'success' }) | (ComposeCompilePartialData & { readonly status: 'partial'; readonly error: { readonly kind: string; readonly message: string }; });