@seljs/runtime 1.0.0

package/dist/environment/environment.js

@@ -0,0 +1,279 @@
+import { createRuntimeEnvironment } from "@seljs/checker";
+import { normalizeContextForEvaluation } from "./context.js";
+import { CallCounter, buildContractInfoMap, executeContractCall, resolveExecutionBlockNumber, } from "./contract-caller.js";
+import { wrapError } from "./error-wrapper.js";
+import { buildExecutionReplayCache } from "./replay-cache.js";
+import { collectCalls } from "../analysis/call-collector.js";
+import { analyzeDependencies } from "../analysis/dependency-analyzer.js";
+import { planRounds } from "../analysis/round-planner.js";
+import { createLogger } from "../debug.js";
+import { MulticallBatchError, SELContractError, SELTypeError, } from "../errors/index.js";
+import { MultiRoundExecutor } from "../execution/multi-round-executor.js";
+/**
+ * Core SEL runtime that bridges CEL expression evaluation with EVM contract reads.
+ *
+ * Manages a CEL runtime extended with Solidity primitive types (uint256, address, bool, etc.),
+ * registered smart contracts whose view functions become callable in expressions, and typed
+ * variables that are supplied at evaluation time. Contract calls are automatically batched
+ * via multicall3 and executed in dependency-ordered rounds.
+ */
+const debug = createLogger("environment");
+export class SELRuntime {
+    env;
+    client;
+    schema;
+    variableTypes = new Map();
+    maxRounds;
+    maxCalls;
+    multicallOptions;
+    contractBindings;
+    codecRegistry;
+    /**
+     * Per-evaluation mutable state.
+     *
+     * These fields are set before CEL evaluation and cleared in `finally`.
+     * They exist because the contract call handler closure (created in the
+     * constructor) needs access to per-evaluation context, but CEL's
+     * `Environment.parse()` returns a function that doesn't accept extra
+     * parameters beyond the variable bindings.
+     *
+     * Thread safety: The `mutex` field serializes concurrent `evaluate()`
+     * calls, ensuring these fields are never accessed concurrently.
+     *
+     * TODO: Consider refactoring to pass an EvaluationContext object through
+     * the handler closure instead of mutating instance state. This would
+     * eliminate the need for the mutex and make the code more testable.
+     * See .omc/drafts/context-object-spike.md for preliminary analysis.
+     */
+    currentCache;
+    currentClient;
+    currentCallCounter;
+    /** Mutex to serialize concurrent evaluate() calls (protects current* fields) */
+    mutex = Promise.resolve();
+    /**
+     * Creates a new immutable SEL runtime with Solidity types pre-registered.
+     *
+     * Initializes the underlying CEL runtime, registers all Solidity primitive types,
+     * and processes any contracts and variables from the schema. After construction,
+     * the environment is fully configured and immutable.
+     *
+     * @param config - Configuration containing the SEL schema, optional viem client,
+     *   multicall settings, and CEL/execution limits (maxRounds defaults to 10, maxCalls to 100)
+     */
+    constructor(config) {
+        const limits = config.limits;
+        const celLimits = limits
+            ? {
+                maxAstNodes: limits.maxAstNodes,
+                maxDepth: limits.maxDepth,
+                maxListElements: limits.maxListElements,
+                maxMapEntries: limits.maxMapEntries,
+                maxCallArguments: limits.maxCallArguments,
+            }
+            : undefined;
+        this.maxRounds = limits?.maxRounds ?? 10;
+        this.maxCalls = limits?.maxCalls ?? 100;
+        this.multicallOptions = config.multicall;
+        this.client = config.client;
+        this.schema = config.schema;
+        // Build handler closure that captures `this` for contract execution
+        const handler = (contractName, methodName, args) => {
+            const contract = this.findContract(contractName);
+            if (!contract) {
+                throw new SELContractError(`Unknown contract "${contractName}"`, {
+                    contractName,
+                });
+            }
+            const method = contract.methods.find((m) => m.name === methodName);
+            if (!method) {
+                throw new SELContractError(`Unknown method "${contractName}.${methodName}"`, { contractName, methodName });
+            }
+            return executeContractCall(contract, method, args, {
+                executionCache: this.currentCache,
+                client: this.currentClient ?? this.client,
+                codecRegistry: this.codecRegistry,
+                callCounter: this.currentCallCounter,
+            });
+        };
+        // Create environment via unified hydration
+        const { env, contractBindings, codecRegistry } = createRuntimeEnvironment(this.schema, handler, { limits: celLimits, unlistedVariablesAreDyn: true });
+        this.env = env;
+        this.contractBindings = contractBindings;
+        this.codecRegistry = codecRegistry;
+        // Populate variableTypes from schema for normalizeContextForEvaluation
+        for (const v of this.schema.variables) {
+            this.variableTypes.set(v.name, v.type);
+        }
+    }
+    /**
+     * Type-checks an expression against registered variables and contract methods.
+     *
+     * @param expression - A CEL expression string to type-check
+     * @returns The type-check result containing validity, inferred type, and any errors
+     * @throws {@link SELTypeError} If the expression contains unrecoverable type errors
+     */
+    check(expression) {
+        try {
+            return this.env.check(expression);
+        }
+        catch (error) {
+            throw wrapError(error);
+        }
+    }
+    /**
+     * Evaluates a SEL expression, executing any embedded contract calls on-chain.
+     *
+     * When contract calls are present, the full pipeline runs:
+     * 1. Parse the expression and collect contract calls from the AST
+     * 2. Type-check against registered variables and contract methods
+     * 3. Build a dependency graph and plan execution rounds
+     * 4. Execute contract calls via multicall3 batching at a pinned block number
+     * 5. Evaluate the CEL expression with resolved contract results and context values
+     * 6. Unwrap Solidity wrapper types back to native JS values (BigInt, string, etc.)
+     *
+     * @param expression A CEL expression string
+     * @param context Variable bindings for evaluation
+     * @param options Optional client override
+     * @returns An {@link EvaluateResult} containing the value and optional execution metadata
+     * @throws {@link SELParseError} If the expression has invalid syntax
+     * @throws {@link SELTypeError} If type-checking fails
+     * @throws {@link SELContractError} If a contract call fails or no client is available
+     * @throws {@link SELEvaluationError} If CEL evaluation fails
+     */
+    async evaluate(expression, context, options) {
+        let release;
+        const prev = this.mutex;
+        this.mutex = new Promise((resolve) => {
+            release = resolve;
+        });
+        await prev;
+        try {
+            return await this.doEvaluate(expression, context, options);
+        }
+        finally {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            release();
+        }
+    }
+    planExecution(expression, evaluationContext) {
+        const parseResult = this.env.parse(expression);
+        const collectedCalls = collectCalls(parseResult.ast, {
+            get: (name) => this.findContract(name),
+        });
+        debug("evaluate: collected %d calls", collectedCalls.length);
+        const normalizedContext = Object.keys(evaluationContext).length
+            ? normalizeContextForEvaluation(evaluationContext, this.variableTypes, this.codecRegistry)
+            : undefined;
+        const executionVariables = Object.keys(evaluationContext).length
+            ? evaluationContext
+            : {};
+        const typeCheckResult = parseResult.check();
+        if (!typeCheckResult.valid) {
+            throw new SELTypeError(typeCheckResult.error?.message ?? "Type check failed", { cause: typeCheckResult.error });
+        }
+        return {
+            parseResult,
+            collectedCalls,
+            normalizedContext,
+            executionVariables,
+            typeCheckResult,
+        };
+    }
+    async executeContractCalls(collectedCalls, executionVariables, resolvedClient) {
+        debug("evaluate: calls to execute — %o", collectedCalls.map((c) => `${c.contract}.${c.method}`));
+        const graph = analyzeDependencies(collectedCalls);
+        const plan = planRounds(graph, {
+            maxRounds: this.maxRounds,
+            maxCalls: this.maxCalls,
+        });
+        const executor = new MultiRoundExecutor(resolvedClient, buildContractInfoMap(this.schema.contracts), this.multicallOptions);
+        let executionResult;
+        try {
+            executionResult = await executor.execute(plan, executionVariables, await resolveExecutionBlockNumber(resolvedClient));
+        }
+        catch (error) {
+            let failedCall = collectedCalls[0];
+            if (error instanceof MulticallBatchError) {
+                if (error.contractName && error.methodName) {
+                    const contractName = error.contractName;
+                    const methodName = error.methodName;
+                    const base = failedCall ?? {
+                        id: "",
+                        contract: contractName,
+                        method: methodName,
+                        args: [],
+                        astNode: undefined,
+                    };
+                    failedCall = {
+                        ...base,
+                        contract: contractName,
+                        method: methodName,
+                    };
+                }
+                else if (typeof error.failedCallIndex === "number") {
+                    failedCall = collectedCalls[error.failedCallIndex] ?? failedCall;
+                }
+            }
+            if (!failedCall) {
+                throw error;
+            }
+            throw new SELContractError(`Contract call failed: ${failedCall.contract}.${failedCall.method}`, {
+                cause: error,
+                contractName: failedCall.contract,
+                methodName: failedCall.method,
+            });
+        }
+        const executionMeta = executionResult.meta;
+        const executionCache = buildExecutionReplayCache(collectedCalls, executionResult.results, executionVariables, this.codecRegistry, (contract, method) => {
+            const c = this.findContract(contract);
+            const m = c?.methods.find((m) => m.name === method);
+            return m?.params.map((p) => p.type) ?? [];
+        });
+        return { executionMeta, executionCache };
+    }
+    async doEvaluate(expression, context, options) {
+        debug("evaluate: %s", expression);
+        const resolvedClient = options?.client ?? this.client;
+        try {
+            const { parseResult, collectedCalls, normalizedContext, executionVariables, typeCheckResult, } = this.planExecution(expression, context ?? {});
+            let executionMeta;
+            let executionCache;
+            if (collectedCalls.length > 0) {
+                if (!resolvedClient) {
+                    throw new SELContractError("No client provided for contract call. Provide a client in SELRuntime config or evaluate() options.", {
+                        contractName: collectedCalls[0]?.contract,
+                        methodName: collectedCalls[0]?.method,
+                    });
+                }
+                ({ executionMeta, executionCache } = await this.executeContractCalls(collectedCalls, executionVariables, resolvedClient));
+            }
+            // Set per-evaluation state for the handler closure
+            this.currentCache = executionCache;
+            this.currentClient = resolvedClient;
+            this.currentCallCounter = new CallCounter(this.maxCalls, executionMeta?.totalCalls ?? 0);
+            let result;
+            try {
+                result = await parseResult({
+                    ...normalizedContext,
+                    ...this.contractBindings,
+                });
+            }
+            finally {
+                this.currentCache = undefined;
+                this.currentClient = undefined;
+                this.currentCallCounter = undefined;
+            }
+            const value = (typeCheckResult.type
+                ? this.codecRegistry.encode(typeCheckResult.type, result)
+                : result);
+            debug("evaluate: result type=%s", typeof value);
+            return executionMeta ? { value, meta: executionMeta } : { value };
+        }
+        catch (error) {
+            throw wrapError(error);
+        }
+    }
+    findContract(name) {
+        return this.schema.contracts.find((c) => c.name === name);
+    }
+}

package/dist/environment/error-wrapper.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Wraps an unknown error into a known SEL error type.
+ * - If the error is already a SEL error, it is returned as is.
+ * - If the error is a CEL error, it is wrapped into the corresponding SEL error type.
+ * - If the error is an unknown type, it is wrapped into a generic Error.
+ *
+ * @param error The error to wrap.
+ * @returns The wrapped error.
+ */
+export declare const wrapError: (error: unknown) => Error;
+//# sourceMappingURL=error-wrapper.d.ts.map

package/dist/environment/error-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-wrapper.d.ts","sourceRoot":"","sources":["../../src/environment/error-wrapper.ts"],"names":[],"mappings":"AAaA;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,KA2B1C,CAAC"}

package/dist/environment/error-wrapper.js

@@ -0,0 +1,33 @@
+import { TypeError as CelTypeError, EvaluationError, ParseError, } from "@marcbachmann/cel-js";
+import { SELContractError, SELEvaluationError, SELParseError, SELTypeError, } from "../errors/index.js";
+/**
+ * Wraps an unknown error into a known SEL error type.
+ * - If the error is already a SEL error, it is returned as is.
+ * - If the error is a CEL error, it is wrapped into the corresponding SEL error type.
+ * - If the error is an unknown type, it is wrapped into a generic Error.
+ *
+ * @param error The error to wrap.
+ * @returns The wrapped error.
+ */
+export const wrapError = (error) => {
+    if (error instanceof SELContractError) {
+        return error;
+    }
+    if (error instanceof ParseError) {
+        return new SELParseError(error.message, { cause: error });
+    }
+    if (error instanceof EvaluationError) {
+        const cause = error.cause;
+        if (cause instanceof SELContractError) {
+            return cause;
+        }
+        return new SELEvaluationError(error.message, { cause: error });
+    }
+    if (error instanceof CelTypeError) {
+        return new SELTypeError(error.message, { cause: error });
+    }
+    if (error instanceof Error) {
+        return error;
+    }
+    return new Error(String(error));
+};

package/dist/environment/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./environment.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/environment/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/environment/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC"}

package/dist/environment/index.js

@@ -0,0 +1,2 @@
+export * from "./environment.js";
+export * from "./types.js";

package/dist/environment/replay-cache.d.ts

@@ -0,0 +1,23 @@
+import type { CollectedCall } from "../analysis/types.js";
+import type { CelCodecRegistry } from "@seljs/checker";
+/**
+ * Builds a replay cache that maps unique identifiers for contract calls to their results.
+ * This allows for efficient retrieval of results during execution replay, ensuring that the same inputs yield the same outputs without needing to re-execute the calls.
+ *
+ * @param calls An array of collected contract calls, each containing information about the contract, method, arguments, and dependencies.
+ * @param results A map of call IDs to their corresponding results, which will be used to resolve arguments that depend on previous calls.
+ * @param variables A record of variable names to their values, which will be used to resolve arguments that depend on variables.
+ */
+export declare const buildExecutionReplayCache: (calls: CollectedCall[], results: Map<string, unknown>, variables: Record<string, unknown>, codecRegistry: CelCodecRegistry, getParamTypes: (contract: string, method: string) => string[]) => Map<string, unknown>;
+/**
+ * Creates a unique identifier for a contract call based on contract name,
+ * method, and arguments.
+ *
+ * IMPORTANT: Args must be pre-encoded via codecRegistry.encode() before
+ * calling this function. The encode step normalizes types (e.g., sol_int
+ * always produces bigint, sol_address always produces string), which
+ * prevents type collisions in String() serialization. If args are NOT
+ * pre-encoded, String(42n) === String(42) would cause cache key collisions.
+ */
+export declare const createReplayCallId: (contract: string, method: string, args: unknown[]) => string;
+//# sourceMappingURL=replay-cache.d.ts.map

package/dist/environment/replay-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-cache.d.ts","sourceRoot":"","sources":["../../src/environment/replay-cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACxE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAiCvD;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GACrC,OAAO,aAAa,EAAE,EACtB,SAAS,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClC,eAAe,gBAAgB,EAC/B,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,EAAE,KAE3D,GAAG,CAAC,MAAM,EAAE,OAAO,CAsBrB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC9B,UAAU,MAAM,EAChB,QAAQ,MAAM,EACd,MAAM,OAAO,EAAE,KACb,MAIF,CAAC"}

package/dist/environment/replay-cache.js

@@ -0,0 +1,51 @@
+const resolveReplayArgs = (args, variables, results, paramTypes, codecRegistry) => args.map((arg, i) => {
+    const celType = paramTypes[i] ?? "dyn";
+    if (arg.type === "literal") {
+        return codecRegistry.encode(celType, arg.value);
+    }
+    if (arg.type === "variable") {
+        const name = arg.variableName;
+        if (!name) {
+            return undefined;
+        }
+        return codecRegistry.encode(celType, variables[name]);
+    }
+    const id = arg.dependsOnCallId;
+    if (!id) {
+        return undefined;
+    }
+    return codecRegistry.encode(celType, results.get(id));
+});
+/**
+ * Builds a replay cache that maps unique identifiers for contract calls to their results.
+ * This allows for efficient retrieval of results during execution replay, ensuring that the same inputs yield the same outputs without needing to re-execute the calls.
+ *
+ * @param calls An array of collected contract calls, each containing information about the contract, method, arguments, and dependencies.
+ * @param results A map of call IDs to their corresponding results, which will be used to resolve arguments that depend on previous calls.
+ * @param variables A record of variable names to their values, which will be used to resolve arguments that depend on variables.
+ */
+export const buildExecutionReplayCache = (calls, results, variables, codecRegistry, getParamTypes) => {
+    const replayCache = new Map();
+    for (const call of calls) {
+        const result = results.get(call.id);
+        const paramTypes = getParamTypes(call.contract, call.method);
+        const resolvedArgs = resolveReplayArgs(call.args, variables, results, paramTypes, codecRegistry);
+        const replayCallId = createReplayCallId(call.contract, call.method, resolvedArgs);
+        replayCache.set(replayCallId, result);
+    }
+    return replayCache;
+};
+/**
+ * Creates a unique identifier for a contract call based on contract name,
+ * method, and arguments.
+ *
+ * IMPORTANT: Args must be pre-encoded via codecRegistry.encode() before
+ * calling this function. The encode step normalizes types (e.g., sol_int
+ * always produces bigint, sol_address always produces string), which
+ * prevents type collisions in String() serialization. If args are NOT
+ * pre-encoded, String(42n) === String(42) would cause cache key collisions.
+ */
+export const createReplayCallId = (contract, method, args) => {
+    const argKey = args.map((arg) => String(arg)).join(",");
+    return `${contract}:${method}:${argKey}`;
+};

package/dist/environment/types.d.ts

@@ -0,0 +1,57 @@
+import type { SELSchema } from "@seljs/schema";
+import type { Address, PublicClient } from "viem";
+/**
+ * Options for multicall3 batching of contract calls.
+ *
+ * When multiple independent contract calls are executed in the same round,
+ * they are batched into a single multicall3 RPC request for efficiency.
+ */
+export interface MulticallOptions {
+    /** Maximum number of calls per multicall3 batch. Unbounded if omitted. */
+    batchSize?: number;
+    /** Custom multicall3 contract address. Defaults to the canonical deployment. */
+    address?: Address;
+}
+/**
+ * Limits for expression parsing and contract call execution.
+ *
+ * AST limits (`maxAstNodes`, `maxDepth`, `maxListElements`, `maxMapEntries`,
+ * `maxCallArguments`) are forwarded to the underlying CEL parser to constrain
+ * expression complexity.
+ *
+ * Execution limits (`maxRounds`, `maxCalls`) bound the multi-round contract
+ * execution engine. An {@link ExecutionLimitError} is thrown when exceeded.
+ */
+export interface SELLimits {
+    /** Maximum number of AST nodes allowed in a parsed expression */
+    maxAstNodes?: number;
+    /** Maximum nesting depth of the AST */
+    maxDepth?: number;
+    /** Maximum number of elements in a list literal */
+    maxListElements?: number;
+    /** Maximum number of entries in a map literal */
+    maxMapEntries?: number;
+    /** Maximum number of arguments in a single function call */
+    maxCallArguments?: number;
+    /** Maximum number of dependency-ordered execution rounds (default: 10) */
+    maxRounds?: number;
+    /** Maximum total number of contract calls across all rounds (default: 100) */
+    maxCalls?: number;
+}
+/**
+ * Configuration for creating an immutable {@link SELRuntime}.
+ *
+ * All contracts and context must be declared here — the environment
+ * cannot be mutated after construction.
+ */
+export interface SELRuntimeConfig {
+    /** SEL schema describing contracts, variables, types, functions, and macros */
+    schema: SELSchema;
+    /** Viem public client for executing on-chain contract reads */
+    client?: PublicClient;
+    /** Multicall3 batching options for contract call execution */
+    multicall?: MulticallOptions;
+    /** AST parsing and execution limits */
+    limits?: SELLimits;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/environment/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/environment/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,gFAAgF;IAChF,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACzB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,mDAAmD;IACnD,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,4DAA4D;IAC5D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAChC,+EAA+E;IAC/E,MAAM,EAAE,SAAS,CAAC;IAElB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAE7B,uCAAuC;IACvC,MAAM,CAAC,EAAE,SAAS,CAAC;CACnB"}

package/dist/environment/types.js

@@ -0,0 +1 @@
+export {};

package/dist/errors/errors.d.ts

@@ -0,0 +1,63 @@
+import { SELError, SELParseError, SELTypeError } from "@seljs/common";
+export { SELError, SELParseError, SELTypeError };
+/**
+ * Thrown when CEL expression evaluation fails.
+ * Wraps cel-js EvaluationError with additional context.
+ */
+export declare class SELEvaluationError extends SELError {
+}
+/**
+ * Thrown when contract validation or execution fails.
+ * Includes optional contract name and method name for context.
+ */
+export declare class SELContractError extends SELError {
+    readonly contractName?: string;
+    readonly methodName?: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        contractName?: string;
+        methodName?: string;
+    });
+}
+/**
+ * Thrown when a circular dependency is detected in the call dependency graph.
+ * Indicates that call A depends on call B which depends on call A (directly or transitively).
+ */
+export declare class CircularDependencyError extends SELError {
+    readonly callIds: string[];
+    constructor(message: string, options?: {
+        cause?: unknown;
+        callIds?: string[];
+    });
+}
+/**
+ * Thrown when execution limits are exceeded (maxRounds or maxCalls).
+ * Prevents infinite loops and runaway execution.
+ */
+export declare class ExecutionLimitError extends SELError {
+    readonly limitType: "maxRounds" | "maxCalls";
+    readonly limit: number;
+    readonly actual: number;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        limitType?: "maxRounds" | "maxCalls";
+        limit?: number;
+        actual?: number;
+    });
+}
+/**
+ * Thrown when a Multicall3 batch execution fails.
+ * Includes the failed call index and optional contract name/method name for context.
+ */
+export declare class MulticallBatchError extends SELError {
+    readonly failedCallIndex?: number;
+    readonly contractName?: string;
+    readonly methodName?: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        failedCallIndex?: number;
+        contractName?: string;
+        methodName?: string;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGtE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,CAAC;AAEjD;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;CAAG;AAEnD;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,QAAQ;IAC7C,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAGnC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;CAM1E;AAED;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,QAAQ;IACpD,SAAgB,OAAO,EAAE,MAAM,EAAE,CAAC;gBAGjC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE;CAKlD;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IAChD,SAAgB,SAAS,EAAE,WAAW,GAAG,UAAU,CAAC;IACpD,SAAgB,KAAK,EAAE,MAAM,CAAC;IAC9B,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAG9B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,SAAS,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC;QACrC,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KAChB;CAOF;AAED;;;GAGG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IAChD,SAAgB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzC,SAAgB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtC,SAAgB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAGnC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;KACpB;CAOF"}

package/dist/errors/errors.js

@@ -0,0 +1,63 @@
+import { SELError, SELParseError, SELTypeError } from "@seljs/common";
+// Re-export shared errors from @seljs/common
+export { SELError, SELParseError, SELTypeError };
+/**
+ * Thrown when CEL expression evaluation fails.
+ * Wraps cel-js EvaluationError with additional context.
+ */
+export class SELEvaluationError extends SELError {
+}
+/**
+ * Thrown when contract validation or execution fails.
+ * Includes optional contract name and method name for context.
+ */
+export class SELContractError extends SELError {
+    contractName;
+    methodName;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.contractName = options?.contractName;
+        this.methodName = options?.methodName;
+    }
+}
+/**
+ * Thrown when a circular dependency is detected in the call dependency graph.
+ * Indicates that call A depends on call B which depends on call A (directly or transitively).
+ */
+export class CircularDependencyError extends SELError {
+    callIds;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.callIds = options?.callIds ?? [];
+    }
+}
+/**
+ * Thrown when execution limits are exceeded (maxRounds or maxCalls).
+ * Prevents infinite loops and runaway execution.
+ */
+export class ExecutionLimitError extends SELError {
+    limitType;
+    limit;
+    actual;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.limitType = options?.limitType ?? "maxRounds";
+        this.limit = options?.limit ?? 0;
+        this.actual = options?.actual ?? 0;
+    }
+}
+/**
+ * Thrown when a Multicall3 batch execution fails.
+ * Includes the failed call index and optional contract name/method name for context.
+ */
+export class MulticallBatchError extends SELError {
+    failedCallIndex;
+    contractName;
+    methodName;
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        this.failedCallIndex = options?.failedCallIndex;
+        this.contractName = options?.contractName;
+        this.methodName = options?.methodName;
+    }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./errors.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/errors/index.js

@@ -0,0 +1 @@
+export * from "./errors.js";

package/dist/execution/index.d.ts

@@ -0,0 +1,2 @@
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/execution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAC"}

package/dist/execution/index.js

@@ -0,0 +1 @@
+export {};

package/dist/execution/multi-round-executor.d.ts

@@ -0,0 +1,17 @@
+import type { ExecutionResult } from "./types.js";
+import type { ExecutionPlan } from "../analysis/types.js";
+import type { Abi, Address, PublicClient } from "viem";
+export declare class MultiRoundExecutor {
+    private readonly client;
+    private readonly multicallOptions?;
+    private readonly contracts;
+    constructor(client: PublicClient, contracts: Map<string, {
+        abi: Abi;
+        address: Address;
+    }>, multicallOptions?: {
+        address?: Address;
+        batchSize?: number;
+    } | undefined);
+    execute(plan: ExecutionPlan, variables?: Record<string, unknown>, blockNumber?: bigint): Promise<ExecutionResult>;
+}
+//# sourceMappingURL=multi-round-executor.d.ts.map

package/dist/execution/multi-round-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multi-round-executor.d.ts","sourceRoot":"","sources":["../../src/execution/multi-round-executor.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAC;AAIvD,qBAAa,kBAAkB;IAI7B,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IALnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4B;gBAGpC,MAAM,EAAE,YAAY,EACrC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,GAAG,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,EACrC,gBAAgB,CAAC,EAAE;QACnC,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,SAAS,CAAC,EAAE,MAAM,CAAC;KACnB,YAAA;IAKW,OAAO,CACnB,IAAI,EAAE,aAAa,EACnB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACvC,WAAW,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC;CA4C3B"}