@lifi/compose-spec
Version:
Public wire-format types and schemas for Compose flows
219 lines (186 loc) • 6.83 kB
text/typescript
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'
| '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;