UNPKG

@lifi/composer-sdk

Version:

Public Composer SDK for building and submitting flows

153 lines • 6.71 kB
import { AbiTypeToOutputKind, TypedGuard, TypedLiteral } from "../types.js"; import { CallArgs } from "./FlowBuilderCore.js"; import { AnyRefBindable, OutputHandle, RefBindable } from "./handles.js"; import { Ref, SolType } from "@lifi/compose-spec"; import { ParseAbiItem } from "abitype"; /** * Any value a signature-derived bind slot accepts, with no per-slot type * constraint: a ref-resolving bindable or a typed literal. */ type AnySignatureBindable = AnyRefBindable | TypedLiteral; type SignatureLiteral<TAbiType extends string> = TAbiType extends SolType ? TypedLiteral<TAbiType> : never; /** * Type-level extraction of named bind keys from a function signature string. * When `TSig` is a string literal matching a Solidity function signature, * resolves to a record whose keys are the parameter names and whose values are * `RefBindable<kind>`, where the kind is derived from each parameter's Solidity * type via `AbiTypeToOutputKind`, or a `TypedLiteral` (`raw.literal`) of that * exact Solidity type. For recognised `SolType` parameters (e.g. `uint256`, * `address`, `bytes`) the slot is precisely typed; other Solidity types (e.g. * tuples) accept any scalar handle and no literal. * Falls back to `Record<string, AnySignatureBindable>` for non-literal strings. * * These slots are lowered into `config.args`, positional calldata: a ref * becomes `{ $ref }` and a literal becomes its `value` string, which the * backend encodes against the parameter's type. */ export type SignatureBind<TSig extends string> = string extends TSig ? Record<string, AnySignatureBindable> : ParseAbiItem<TSig> extends { type: "function"; inputs: infer I extends readonly { name: string; type: string; }[]; } ? { readonly [P in I[number] as P["name"]]: RefBindable<AbiTypeToOutputKind<P["type"]>> | SignatureLiteral<P["type"]>; } : Record<string, AnySignatureBindable>; /** * Describes the output type(s) of a parsed function signature as a * human-readable string for inclusion in type-level error messages. */ type DescribeOutputs<O extends readonly { type: string; }[]> = O extends readonly [{ type: infer T extends string; }] ? T : "multiple values"; /** * A string-literal type that surfaces a clear error when the user provides a * function signature whose return type is not supported by core.call. * The message is visible in IDE tooltips and compiler diagnostics. */ type UnsupportedReturnTypeError<TLabel extends string, TSig extends string> = ParseAbiItem<TSig> extends { type: "function"; outputs: infer O extends readonly { type: string; }[]; } ? `[TypeError] ${TLabel}: return type '${DescribeOutputs<O>}' is not supported — only 'uint256' or void signatures are allowed` : `[TypeError] ${TLabel}: unable to parse return type from signature`; /** * Conditional output type for `core.call` based on the function signature's * return type: * * - `returns (uint256)` → `{ result: OutputHandle }` * - No returns clause → `{ result: undefined }` * - Anything else → `{ result: "[TypeError] ..." }` (compile-time error) * * When `TSig` is a non-literal `string` (e.g. a variable, not a string * constant), the type falls back to `{ result: OutputHandle | undefined }` * so that both void and uint256 call sites remain assignable. */ export type CoreCallResult<TSig extends string> = string extends TSig ? { readonly result: OutputHandle<"uint256"> | undefined; } : ParseAbiItem<TSig> extends { type: "function"; outputs: readonly []; } ? { readonly result: undefined; } : ParseAbiItem<TSig> extends { type: "function"; outputs: readonly [{ type: "uint256"; }]; } ? { readonly result: OutputHandle<"uint256">; } : { readonly result: UnsupportedReturnTypeError<"core.call", TSig>; }; /** * Conditional output type for `core.staticCall`. staticCall always reads a * value, so void signatures are also rejected: * * - `returns (uint256)` → `{ result: OutputHandle }` * - No returns / other → `{ result: "[TypeError] ..." }` (compile-time error) */ export type StaticCallResult<TSig extends string> = string extends TSig ? { readonly result: OutputHandle<"uint256">; } : ParseAbiItem<TSig> extends { type: "function"; outputs: readonly [{ type: "uint256"; }]; } ? { readonly result: OutputHandle<"uint256">; } : ParseAbiItem<TSig> extends { type: "function"; outputs: readonly []; } ? { readonly result: `[TypeError] core.staticCall: function has no return value — staticCall requires a 'returns (uint256)' signature`; } : { readonly result: UnsupportedReturnTypeError<"core.staticCall", TSig>; }; /** * Parses a Solidity function signature and returns parameter names in order. * Delegates to abitype's runtime `parseAbiItem` — the same parser that powers * the compile-time `ParseAbiItem<TSig>` type — so runtime and type-level * parsing can never diverge. * * @throws if the signature is not a valid function signature or a parameter is unnamed */ export declare const parseFunctionParams: (functionSignature: string) => string[]; /** * Converts a ref-resolving bindable to a `Ref` (`{ $ref: string }`). * Handles carry a `_tag` property and are converted via `handleToRef`; * `Ref` objects pass through as-is. */ export declare const toBindRef: (bindable: AnyRefBindable) => Ref; export interface BuildCallWireFormatInput { readonly resource?: AnyRefBindable; readonly bind: Record<string, AnySignatureBindable>; readonly config: Record<string, unknown>; readonly guards?: readonly TypedGuard[]; } export interface CallWireResult { readonly op: "core.call" | "core.invoke"; readonly bind: Record<string, Ref>; readonly config: Record<string, unknown>; readonly guards?: readonly TypedGuard[]; } /** * Transforms the user-facing `resource` + named `bind` API into the wire * format that the backend expects: * - With resource: `core.call` with `bind: { input: <resourceRef> }` * - Without resource: `core.invoke` with `bind: {}` * - `config: { ...userConfig, args: [positional refs and literal values...] }` */ export declare const buildCallWireFormat: (args: BuildCallWireFormatInput) => CallWireResult; export interface BuildStaticCallWireFormatInput { readonly bind: Record<string, AnySignatureBindable>; readonly config: Record<string, unknown>; readonly guards?: readonly TypedGuard[]; } /** * Transforms the user-facing named `bind` API into the wire format that the * backend expects for `core.staticCall`. Same as `buildCallWireFormat` but * with no `resource` field — staticCall has no resource inputs. */ export declare const buildStaticCallWireFormat: (args: BuildStaticCallWireFormatInput) => CallArgs; export {};