@lifi/composer-sdk 0.0.1-alpha

package/src/authoring/FlowBuilderCore.ts

@@ -0,0 +1,270 @@
+import type {
+  AppliedGuard,
+  Call,
+  Flow,
+  FlowInput,
+  Ref,
+  Resource,
+  SolType,
+} from '@lifi/compose-spec';
+
+import type {
+  InputDecl,
+  InputSchema,
+  OutputKind,
+  TypedGuard,
+  TypedRef,
+} from '../types.js';
+
+import type {
+  InputHandle,
+  OutputHandle,
+  ResourceInputHandle,
+} from './handles.js';
+import { handleToRef } from './handles.js';
+import { ref } from './raw.js';
+
+/**
+ * Arguments for calling an operation node in a flow.
+ */
+export interface CallArgs {
+  /** Maps parameter names to input/output handles or raw `$ref` pointers. */
+  readonly bind: Record<string, AnyBindable>;
+  /** Optional operation-specific configuration. */
+  readonly config?: object;
+  /** Optional guards (e.g. slippage checks) applied to this operation's outputs. */
+  readonly guards?: readonly TypedGuard[];
+}
+
+/**
+ * Any value that can be bound to an operation parameter: an input handle,
+ * an output handle from a previous operation, or a typed `$ref` pointer.
+ *
+ * Use `raw.ref<T>()` to create a typed ref from a raw path string.
+ */
+export type AnyBindable = InputHandle | OutputHandle | TypedRef;
+
+const toRef = (bindable: AnyBindable): Ref => {
+  if ('_tag' in bindable) return handleToRef(bindable);
+  return bindable;
+};
+
+/**
+ * Provides references to runtime context values available inside a flow.
+ * Access via `builder.context`.
+ */
+export interface ContextAccessor {
+  /** A `$ref` pointing to the transaction sender (signer) address. */
+  readonly sender: TypedRef<'address'>;
+  /** A `$ref` pointing to the on-chain execution (proxy) address. */
+  readonly executionAddress: TypedRef<'address'>;
+}
+
+type InputHandleOf<D extends InputDecl> = D extends Resource
+  ? ResourceInputHandle
+  : D extends SolType
+    ? InputHandle<D>
+    : InputHandle;
+
+/**
+ * A mapped type that converts an input schema into typed handles.
+ * Resource inputs produce {@link ResourceInputHandle}; scalar inputs produce {@link InputHandle}.
+ *
+ * @typeParam T - The flow's input schema.
+ */
+export type InputHandles<T extends InputSchema> = {
+  readonly [K in keyof T]: InputHandleOf<T[K]>;
+};
+
+/**
+ * Options for creating a new flow builder.
+ *
+ * @typeParam T - The flow's input schema.
+ */
+export interface FlowOptions<T extends InputSchema> {
+  /** Optional human-readable name for the flow. Defaults to a random UUID. */
+  readonly name?: string;
+  /** Input declarations mapping names to resource or scalar types. */
+  readonly inputs: T;
+}
+
+/**
+ * A Flow document branded with its input schema for type-safe request building.
+ *
+ * The `__inputs` field is a phantom type — it exists only at compile time for
+ * TypeScript inference and is never present at runtime.
+ */
+export type TypedFlow<T extends InputSchema = InputSchema> = Flow & {
+  readonly __inputs?: T;
+};
+
+/**
+ * Core flow builder interface providing low-level access to flow construction.
+ *
+ * For most use cases, prefer the {@link FlowBuilder} type returned by `sdk.flow()`
+ * which adds generated operation methods and a `compile` method.
+ *
+ * @typeParam T - The flow's input schema.
+ */
+export interface FlowBuilderCore<T extends InputSchema = InputSchema> {
+  /** Runtime context references (sender address, execution address). */
+  readonly context: ContextAccessor;
+  /** Typed handles for each declared flow input, used to bind inputs to operations. */
+  readonly inputs: InputHandles<T>;
+  /**
+   * Appends an untyped operation node to the flow. This is an escape hatch
+   * for operations not yet covered by the generated methods.
+   *
+   * Use `raw.ref<T>()` to reference this node's outputs in subsequent typed
+   * operations.
+   *
+   * @param id - Unique node identifier within the flow.
+   * @param op - The operation name (e.g. `"custom.vaultQuery"`).
+   * @param args - Bind map, config, and optional guards for the node.
+   * @throws Error if a node with the same `id` already exists in the flow.
+   */
+  readonly untypedOp: (
+    id: string,
+    op: string,
+    args: {
+      readonly bind: Record<string, Ref>;
+      readonly config: Record<string, unknown>;
+      readonly guards?: readonly AppliedGuard[];
+    },
+  ) => void;
+  /** Serialises the builder state into a {@link TypedFlow} document. */
+  readonly build: () => TypedFlow<T>;
+}
+
+/** Maps output port names to their output kind for compile-time and runtime validation. */
+export type OutputSpec = Record<string, OutputKind>;
+
+/** Internal interface exposed to bindGeneratedOps — not part of the public API. */
+export interface FlowBuilderInternal<
+  T extends InputSchema = InputSchema,
+> extends FlowBuilderCore<T> {
+  readonly call: <O extends OutputSpec>(
+    nodeId: string,
+    op: string,
+    args: CallArgs,
+    outputs: O,
+  ) => { readonly [K in keyof O & string]: OutputHandle<O[K]> };
+}
+
+const isResource = (decl: InputDecl): decl is Resource =>
+  typeof decl === 'object' && decl !== null && 'kind' in decl;
+
+/**
+ * Creates a new flow builder targeting the given chain.
+ *
+ * @param chainId - The EVM chain ID (e.g. `1` for Ethereum mainnet).
+ * @param options - Flow configuration including input declarations.
+ * @returns A {@link FlowBuilderInternal} instance.
+ * @internal
+ */
+export const createFlowBuilderCore = <T extends InputSchema>(
+  chainId: number,
+  options: FlowOptions<T>,
+): FlowBuilderInternal<T> => {
+  const id = options.name ?? crypto.randomUUID();
+  const flowInputs: FlowInput[] = [];
+  const nodes: Call[] = [];
+  const nodeIds = new Set<string>();
+
+  const inputHandles = {} as Record<string, InputHandle | ResourceInputHandle>;
+  for (const [name, decl] of Object.entries(options.inputs)) {
+    if (isResource(decl)) {
+      if (decl.chainId !== chainId) {
+        throw new Error(
+          `Input "${name}" has chainId ${decl.chainId} but flow targets chain ${chainId}`,
+        );
+      }
+      flowInputs.push({ name, resource: decl });
+      inputHandles[name] = { _tag: 'input', inputName: name, resource: decl };
+    } else {
+      flowInputs.push({ name, type: decl });
+      inputHandles[name] = { _tag: 'input', inputName: name };
+    }
+  }
+
+  const call = <O extends OutputSpec>(
+    nodeId: string,
+    op: string,
+    args: CallArgs,
+    outputs: O,
+  ): { readonly [K in keyof O & string]: OutputHandle<O[K]> } => {
+    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
+    nodeIds.add(nodeId);
+
+    const bind: Record<string, Ref> = {};
+    for (const [key, val] of Object.entries(args.bind)) {
+      bind[key] = toRef(val);
+    }
+
+    const node: Call = {
+      id: nodeId,
+      op,
+      bind,
+      config: (args.config ?? {}) as Record<string, unknown>,
+      ...(args.guards && args.guards.length > 0 && { guards: args.guards }),
+    };
+    nodes.push(node);
+
+    type Result = { readonly [K in keyof O & string]: OutputHandle<O[K]> };
+    return new Proxy({} as Result, {
+      get: (_target, prop): OutputHandle | undefined => {
+        if (typeof prop !== 'string' || prop === 'then') return undefined;
+        if (!(prop in outputs)) {
+          throw new Error(
+            `Op "${op}" has no output port "${prop}". Valid ports: ${Object.keys(
+              outputs,
+            ).join(', ')}`,
+          );
+        }
+        return { _tag: 'output', nodeId, portName: prop };
+      },
+    });
+  };
+
+  const untypedOp = (
+    nodeId: string,
+    op: string,
+    args: {
+      readonly bind: Record<string, Ref>;
+      readonly config: Record<string, unknown>;
+      readonly guards?: readonly AppliedGuard[];
+    },
+  ): void => {
+    if (nodeIds.has(nodeId)) throw new Error(`Duplicate node id: "${nodeId}"`);
+    nodeIds.add(nodeId);
+    const node: Call = {
+      id: nodeId,
+      op,
+      bind: args.bind,
+      config: args.config,
+      ...(args.guards && args.guards.length > 0 && { guards: args.guards }),
+    };
+    nodes.push(node);
+  };
+
+  const build = (): TypedFlow<T> => ({
+    version: 1,
+    id,
+    chainId,
+    inputs: [...flowInputs],
+    nodes: [...nodes],
+  });
+
+  const context: ContextAccessor = {
+    sender: ref<'address'>('context.sender'),
+    executionAddress: ref<'address'>('context.executionAddress'),
+  };
+
+  return {
+    context,
+    inputs: inputHandles as InputHandles<T>,
+    call,
+    untypedOp,
+    build,
+  };
+};

package/src/authoring/handles.ts

@@ -0,0 +1,81 @@
+import type { Resource } from '@lifi/compose-spec';
+
+import type { OutputKind, TypedRef } from '../types.js';
+
+/**
+ * A handle referencing a flow input declared in the flow's input schema.
+ * The phantom `__outputKind` field carries the type parameter through
+ * TypeScript's structural type system without affecting runtime shape.
+ */
+export interface InputHandle<T extends OutputKind = OutputKind> {
+  readonly _tag: 'input';
+  readonly inputName: string;
+  readonly __outputKind?: T;
+}
+
+/**
+ * An input handle for a resource (token) input, carrying the resource
+ * declaration alongside the reference.
+ */
+export interface ResourceInputHandle extends InputHandle<'resource'> {
+  readonly resource: Resource;
+}
+
+/**
+ * A handle referencing an output port of a previously declared operation node.
+ * The phantom `__outputKind` field carries the type parameter through
+ * TypeScript's structural type system without affecting runtime shape.
+ */
+export interface OutputHandle<T extends OutputKind = OutputKind> {
+  readonly _tag: 'output';
+  readonly nodeId: string;
+  readonly portName: string;
+  readonly __outputKind?: T;
+}
+
+/** Discriminated union of all handle types that can be bound to operation arguments. */
+export type AnyHandle = InputHandle | OutputHandle;
+
+/** Type guard that narrows an {@link AnyHandle} to an {@link InputHandle}. */
+export const isInputHandle = (h: AnyHandle): h is InputHandle =>
+  h._tag === 'input';
+
+/** Type guard that narrows an {@link AnyHandle} to an {@link OutputHandle}. */
+export const isOutputHandle = (h: AnyHandle): h is OutputHandle =>
+  h._tag === 'output';
+
+/**
+ * Converts a handle to a JSON `$ref` pointer used in the flow document.
+ * Input handles become `"input.<name>"`; output handles become `"<nodeId>.<port>"`.
+ */
+export const handleToRef = (h: AnyHandle): { $ref: string } => {
+  if (h._tag === 'input') {
+    if (!h.inputName) throw new Error('InputHandle has empty inputName');
+    return { $ref: `input.${h.inputName}` };
+  }
+  if (!h.nodeId) throw new Error('OutputHandle has empty nodeId');
+  if (!h.portName) throw new Error('OutputHandle has empty portName');
+  return { $ref: `${h.nodeId}.${h.portName}` };
+};
+
+/**
+ * For a bind slot expecting type T, also accept `'resource'`-tagged
+ * handles when T is `'uint256'` (resources are uint256 amounts).
+ */
+type ResourceAssignable<T extends OutputKind> = T extends 'uint256'
+  ? T | 'resource'
+  : T;
+
+/**
+ * The set of values accepted by a typed bind slot.
+ * - `OutputHandle<T>` / `InputHandle<T>` (same type)
+ * - For `'uint256'` slots, also `'resource'`-tagged handles
+ * - `TypedRef<T>` (typed context refs, subject to `ResourceAssignable`)
+ *
+ * Plain `{ $ref: '...' }` objects are **not** accepted — use `raw.ref<T>()`
+ * to create a typed ref when you need to reference a raw path.
+ */
+export type Bindable<T extends OutputKind> =
+  | OutputHandle<ResourceAssignable<T>>
+  | InputHandle<ResourceAssignable<T>>
+  | TypedRef<ResourceAssignable<T>>;

package/src/authoring/raw.ts

@@ -0,0 +1,60 @@
+import type { AppliedGuard } from '@lifi/compose-spec';
+
+import type { OutputKind, TypedRef } from '../types.js';
+
+/**
+ * Creates a typed `$ref` pointer for use in bind slots.
+ *
+ * This is an **escape hatch** for referencing values that the typed builder
+ * API doesn't cover — for example, outputs of an `untypedOp` node or custom
+ * context paths. The caller is responsible for choosing the correct type
+ * parameter; no runtime validation occurs.
+ *
+ * Prefer typed handles (`OutputHandle`, `InputHandle`) and `builder.context`
+ * whenever possible. Use `ref` only when you need to construct a `$ref` path
+ * manually and want it accepted by a `Bindable<T>` slot.
+ *
+ * @typeParam T - The output kind this ref represents (e.g. `'address'`, `'uint256'`, `'resource'`).
+ * @param path - The `$ref` path (e.g. `"context.sender"`, `"myNode.result"`).
+ * @returns A {@link TypedRef} accepted by `Bindable<T>` slots matching `T`.
+ *
+ * @example
+ * ```ts
+ * import { raw } from '@lifi/composer-sdk';
+ *
+ * // Reference an untypedOp output in a typed operation:
+ * builder.untypedOp('custom', 'some.op', {
+ *   bind: { x: { $ref: 'input.token' } },
+ *   config: {},
+ * });
+ * builder.core.add('sum', {
+ *   bind: {
+ *     a: raw.ref<'uint256'>('custom.result'),
+ *     b: someTypedHandle,
+ *   },
+ * });
+ * ```
+ */
+export const ref = <T extends OutputKind>(path: string): TypedRef<T> =>
+  ({ $ref: path }) as TypedRef<T>;
+
+/**
+ * Creates a raw guard object for use in the `guards` array of an operation call.
+ *
+ * @param kind - The guard type (e.g. `"slippage"`).
+ * @param config - Guard-specific configuration (e.g. `{ toleranceBps: 300 }`).
+ * @returns An {@link AppliedGuard} object.
+ */
+export const rawGuard = (
+  kind: string,
+  config: Record<string, unknown> = {},
+): AppliedGuard => {
+  if ('kind' in config) {
+    throw new Error(
+      `rawGuard: 'kind' must not appear in config (got "${String(
+        config.kind,
+      )}"). Pass it as the first argument instead.`,
+    );
+  }
+  return { ...config, kind };
+};

package/src/authoring/signatureArgs.ts

@@ -0,0 +1,249 @@
+import type { Ref } from '@lifi/compose-spec';
+import { type ParseAbiItem, parseAbiItem } from 'abitype';
+
+import type { AbiTypeToOutputKind, TypedGuard } from '../types.js';
+
+import type { AnyBindable, CallArgs } from './FlowBuilderCore.js';
+import type { Bindable, OutputHandle } from './handles.js';
+import { handleToRef } from './handles.js';
+
+/**
+ * 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 values are
+ * `Bindable<kind>` where the kind is derived from each parameter's Solidity
+ * type via `AbiTypeToOutputKind`. For recognised `SolType` parameters
+ * (e.g. `uint256`, `address`, `uint128`) the bind slot is precisely typed;
+ * for other Solidity types (e.g. tuples) the slot accepts any scalar handle.
+ * Falls back to `Record<string, AnyBindable>` for non-literal strings.
+ */
+export type SignatureBind<TSig extends string> = string extends TSig
+  ? Record<string, AnyBindable>
+  : ParseAbiItem<TSig> extends {
+        type: 'function';
+        inputs: infer I extends readonly { name: string; type: string }[];
+      }
+    ? {
+        readonly [P in I[number] as P['name']]: Bindable<
+          AbiTypeToOutputKind<P['type']>
+        >;
+      }
+    : Record<string, AnyBindable>;
+
+// ---------------------------------------------------------------------------
+// Return-type inference from function signatures
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 const parseFunctionParams = (functionSignature: string): string[] => {
+  const parsed = parseAbiItem(functionSignature);
+  if (parsed.type !== 'function') {
+    throw new Error(
+      `core.call: expected a function signature, got "${parsed.type}": "${functionSignature}"`,
+    );
+  }
+
+  return parsed.inputs.map((input, index) => {
+    if (!input.name) {
+      throw new Error(
+        `core.call: parameter at index ${index} in signature has no name. All parameters must be named for named binds to work.`,
+      );
+    }
+    return input.name;
+  });
+};
+
+/**
+ * Converts any `AnyBindable` to a `Ref` (`{ $ref: string }`).
+ * Handles carry a `_tag` property and are converted via `handleToRef`;
+ * `Ref` objects pass through as-is.
+ */
+export const toBindRef = (bindable: AnyBindable): Ref => {
+  if ('_tag' in bindable) return handleToRef(bindable);
+  return bindable;
+};
+
+export interface BuildCallWireFormatInput {
+  readonly resource?: AnyBindable;
+  readonly bind: Record<string, AnyBindable>;
+  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[];
+}
+
+/**
+ * Parses a function signature from `config`, validates bind keys against it,
+ * and converts named binds to positional `$ref` args.
+ */
+const resolvePositionalArgs = (
+  label: string,
+  bind: Record<string, AnyBindable>,
+  config: Record<string, unknown>,
+): Ref[] => {
+  const functionSignature = config.functionSignature;
+  if (typeof functionSignature !== 'string') {
+    throw new Error(
+      `${label}: config.functionSignature is required and must be a string`,
+    );
+  }
+
+  const paramNames = parseFunctionParams(functionSignature);
+  const paramSet = new Set(paramNames);
+  const bindKeys = Object.keys(bind);
+  const bindSet = new Set(bindKeys);
+
+  const missing = paramNames.filter((n) => !bindSet.has(n));
+  const extra = bindKeys.filter((k) => !paramSet.has(k));
+
+  if (missing.length > 0 || extra.length > 0) {
+    throw new Error(
+      `${label}: bind keys [${bindKeys.join(
+        ', ',
+      )}] do not match signature parameters [${paramNames.join(
+        ', ',
+      )}]. Missing: ${missing.join(', ') || '(none)'}. Extra: ${
+        extra.join(', ') || '(none)'
+      }.`,
+    );
+  }
+
+  return paramNames.map((name) => {
+    const bindable = bind[name];
+    if (bindable == null) {
+      throw new Error(
+        `${label}: bind value for parameter "${name}" is undefined`,
+      );
+    }
+    return toBindRef(bindable);
+  });
+};
+
+/**
+ * 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...] }`
+ */
+export const buildCallWireFormat = (
+  args: BuildCallWireFormatInput,
+): CallWireResult => {
+  const positionalArgs = resolvePositionalArgs(
+    'core.call',
+    args.bind,
+    args.config,
+  );
+  const hasResource = args.resource != null;
+
+  return {
+    op: hasResource ? 'core.call' : 'core.invoke',
+    bind: hasResource ? { input: toBindRef(args.resource) } : {},
+    config: { ...args.config, args: positionalArgs },
+    ...(args.guards && args.guards.length > 0 && { guards: args.guards }),
+  };
+};
+
+export interface BuildStaticCallWireFormatInput {
+  readonly bind: Record<string, AnyBindable>;
+  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 const buildStaticCallWireFormat = (
+  args: BuildStaticCallWireFormatInput,
+): CallArgs => {
+  const positionalArgs = resolvePositionalArgs(
+    'core.staticCall',
+    args.bind,
+    args.config,
+  );
+
+  return {
+    bind: {},
+    config: { ...args.config, args: positionalArgs },
+    ...(args.guards && args.guards.length > 0 && { guards: args.guards }),
+  };
+};