UNPKG

@lifi/compose-spec

Version:

Public wire-format types and schemas for Compose flows

224 lines (191 loc) • 6.96 kB
import type { SimulationRevert } from './compile.js'; import type { FlowInput, ResourceInput, SolType } from './flowSchema.js'; import type { Availability, Resource } from './resource.js'; import type { HandlePort, OpInputPort, OpOutputPort, ResourceOutputPort, ResourcePort, Shortfall, } from './zodSchemas.js'; export type { HandlePort, OpInputPort, OpOutputPort, ResourceOutputPort, ResourcePort, } from './zodSchemas.js'; export interface Port { readonly name: string; readonly type: SolType; readonly mode: 'linear' | 'copy'; readonly availability?: Availability; readonly resource?: Resource; } export const isResourceInput = (input: FlowInput): input is ResourceInput => 'resource' in input; export const flowInputType = (input: FlowInput): SolType => isResourceInput(input) ? 'uint256' : input.type; export const flowInputMode = (input: FlowInput): 'linear' | 'copy' => isResourceInput(input) ? 'linear' : 'copy'; export const flowInputResource = (input: FlowInput): Resource | undefined => isResourceInput(input) ? input.resource : undefined; export const isResourcePort = (port: OpInputPort): port is ResourcePort => port.kind === 'resource'; export const isHandlePort = ( port: OpInputPort | OpOutputPort, ): port is HandlePort => port.kind === 'handle'; export const isResourceOutputPort = ( port: OpInputPort | OpOutputPort, ): port is ResourceOutputPort => port.kind === 'resource_output'; // A resource output whose value becomes available only after the initiating // transaction settles. Absence of `availability` means `'now'`, so the check is // a direct comparison against the one non-default mode. Every site that asks // "is this port's value delivered later?" goes through here, so a rename of the // property or a new availability mode lands in one place. export const isFutureResourceOutput = ( port: OpInputPort | OpOutputPort, ): boolean => isResourceOutputPort(port) && port.availability === 'future'; export type ComposeErrorKind = | 'decode_error' | 'validation_error' | 'linearity_error' | 'resolve_error' | 'preparation_error' | 'provider_error' | 'no_route_error' | 'resolution_error' | 'resolution_rejected' | 'lowering_error' | 'empty_program' | 'simulation_error' | 'simulation_setup_error' | 'simulation_insufficient_funds' | 'simulation_gas_limit' | 'simulation_rpc_error' | 'simulation_revert' | 'subgraph_simulation_revert' | 'guard_error' | 'continuation_error' | 'compilation_error' | 'verification_error' | 'price_impact_exceeded' | 'flashloan_unauthorized' // A delivery tranche's failure; reasons in `DeliveryErrorReason`. | 'delivery_error' // The request exceeded its wall-clock budget and was cancelled mid-flight. | 'deadline_exceeded'; /** * Errors raised by compose routes outside the compile pipeline. */ export type ComposeRouteErrorKind = | 'chain_validation_error' | 'unsupported_token' // The signer is on a threat-intelligence list (zeroShadow) and may not use // the service. | 'signer_screening_rejected' | 'zero_output' | 'service_unavailable' | 'verification_unavailable' | 'deployment_check_unavailable' | 'manifest_error' | 'sdk_outdated' | 'server_outdated'; export type GenericComposeErrorKind = Exclude< ComposeErrorKind, 'preparation_error' | 'simulation_revert' | 'delivery_error' >; export interface FailedPreparedOp { readonly callId: string; readonly op: string; readonly kind: GenericComposeErrorKind; readonly message: string; readonly path?: string; readonly port?: string; readonly fix?: string; readonly shortfall?: Shortfall; } // `path` names the node the rejection is about, `port` the bound input port // when the rejection is about what that port binds, and `fix` the one action // that clears it. A `continuation.settle` authoring rejection carries `path` // and `fix`, plus `port` when it is about a bind; other `validation_error`s may // omit `fix`. A deployment or internal fault carries none of the three, because // no edit to the flow clears it. `shortfall` is present when the cause is an // amount that cannot cover what a step needs (see `ShortfallZod`). interface ComposeErrorBase { readonly message: string; readonly path?: string; readonly port?: string; readonly fix?: string; readonly shortfall?: Shortfall; } export interface PreparationComposeError extends ComposeErrorBase { readonly kind: 'preparation_error'; readonly failedOps: readonly FailedPreparedOp[]; readonly succeededOps: readonly string[]; } export interface SimulationRevertComposeError extends ComposeErrorBase { readonly kind: 'simulation_revert'; readonly details?: SimulationRevert; } // Why a delivery tranche failed: // - `floor_drift`: the second quote's `min` fell below the registered floor; // - `eta_exceeds_expiry`: the escrow expires before the delivery's ETA rule // allows; // - `quote_failed`: the second quote (to the registered escrow) failed; // `cause` is the kind of that failure and `quoted` is the first quote. export type DeliveryErrorReason = | 'floor_drift' | 'eta_exceeds_expiry' | 'quote_failed'; // `escrow` is present only when the failure came after the escrow was // registered: the escrow is then abandoned and expires unfunded, and this // record is its only trace. export interface DeliveryErrorDetails { readonly reason: DeliveryErrorReason; readonly cause?: ComposeErrorKind; readonly quoted: { readonly min: string; readonly expected: string; readonly etaSeconds?: number; }; readonly escrow?: { readonly chainId: number; readonly address: string; readonly floor: string; readonly expiresAtMs: number; }; } export interface DeliveryComposeError extends ComposeErrorBase { readonly kind: 'delivery_error'; readonly details: DeliveryErrorDetails; } export interface GenericComposeError extends ComposeErrorBase { readonly kind: GenericComposeErrorKind; readonly [key: string]: unknown; } export type ComposeError = | PreparationComposeError | SimulationRevertComposeError | DeliveryComposeError | GenericComposeError; export interface MaterialiserInputBase { readonly kind: string; } export type MaterialiserInput = MaterialiserInputBase & Record<string, unknown>; export type MaterialiserInputOf<C extends object> = MaterialiserInputBase & C; export type MaterialiserConfigOf<C extends object> = C; export const isMaterialiserInput = (s: InputSpec): s is MaterialiserInput => typeof s === 'object' && s !== null && 'kind' in s; export type InputSpec = bigint | string | MaterialiserInput; export interface PreconditionBase { readonly type: string; } export type Precondition = PreconditionBase & Record<string, unknown>; export type PreconditionOf<C extends object> = PreconditionBase & C; export type PreconditionConfigOf<C extends object> = Omit< PreconditionBase, 'type' > & C;