evscript and compile

This page is the signature-level reference for the script entry point and the compiler entry point. For the narrative introduction, see writing scripts; for the compiled artifact returned by compile, see the artifact reference.

import { namedArg, compile, evscript, t } from '@maxencerb/evs';

evscript()

declare function evscript<
  const name extends string,
  const args extends ArgsInput, // ArgInput | readonly ArgInput[]; ArgInput = EvsType | ArgSpec
  ret extends Record<string, ReturnValue>, // each value: Expr | Tuple | MutArray
>(
  def: { name: name; args?: args },
  body: (s: ScriptBuilder, ...args: ArgHandles<NormalizeArgs<args>>) => ScriptReturn<ret>,
  opts?: { locations?: boolean }, // default true: capture source locations
): EvsScript<name, NormalizeArgs<args>, ret>;

evscript records a script: it runs body exactly once, at recording time, against a ScriptBuilder and captures every builder call into a frozen IR. The callback must return the value produced by s.return(...) — returning anything else (or not calling s.return at all) throws EvsTypeError.

Args are declared as t.* types or namedArg(name, type) wrappers — a single declarator or a readonly list — and arrive as positional parameters after s. A scalar arg arrives as an Expr, a TupleType arg as a Tuple handle. args is optional; a zero-arg script omits it. A lone declarator is sugar for a one-element list (args: t.uint256 ≡ args: [t.uint256]). A namedArg labels the arg in the viem args tuple; a bare arg keeps the positional arg0/arg1/… name. The const type parameters mean inline args need no as const.

import { evscript, t } from '@maxencerb/evs';

const double = evscript(
  { name: 'double', args: [t.uint256] },
  (s, x) => s.return({ doubled: x.mul(2n) }),
);

const compiled = double.compile(); // sugar for compile(double)

The relevant type helpers (all exported):

Type	Meaning
ArgInput	EvsType | ArgSpec — one declarator: a bare type or a namedArg.
ArgsInput	ArgInput | readonly ArgInput[] — the accepted args input.
NormalizeArgs<a>	Normalizes to readonly ArgSpec[] (a lone declarator → a one-element list).
ArgHandle<t>	t extends TupleType ? Tuple<t> : Expr<t> — one arg’s body handle.
ArgHandles<specs>	The positional handle tuple spread into the body after s, labeled by arg name.

Recording-time validation (each violation throws EvsTypeError with the call-site location):

• def.name must be a non-empty identifier (/^[A-Za-z_]\w*$/).
• def.args, when present, must be a single declarator (a bare EvsType or a namedArg) or a readonly list of them. A namedArg labels its input in the generated ABI; a bare arg is auto-named arg{i} (the names are positional labels; viem infers args positionally regardless). Duplicate arg names are rejected (ABI_SHAPE).
• Every arg type must be a valid EvsType — a word/dynamic type, an array (a scalar array, a one-level nested array T[][], or a tuple[]), or a TupleType (struct/tuple). Shapes outside the supported set — tuple[][], deeper-than-[][] nesting, fixed T[N] — throw with code UNSUPPORTED_V0.
• body must be a function.

Everything the builder itself can throw during recording is catalogued in diagnostics.

The locations option

opts.locations (default true) controls source-location capture during recording. When enabled, every recorded statement stores a SourceLoc parsed from a stack trace, which powers error messages, sourceMap, explainRevert, and diagnostics. Pass { locations: false } to skip the per-statement stack capture (faster recording; locations in errors and the source map become null):

import { evscript, t } from '@maxencerb/evs';

const fast = evscript(
  { name: 'fast', args: [t.uint256] },
  (s, x) => s.return({ x }),
  { locations: false },
);

compile has its own independent locations option (below) for the emitted source map.

EvsScript

The value returned by evscript. It is frozen; ir is deep-frozen.

import type {
  ArgSpec,
  CompiledEvsScript,
  CompileOptions,
  ReturnValue,
  ScriptAbi,
  ScriptIr,
} from '@maxencerb/evs';

interface EvsScript<
  name extends string = string,
  args extends readonly ArgSpec[] = readonly ArgSpec[],
  ret extends Record<string, ReturnValue> = Record<string, ReturnValue>,
> {
  readonly name: name;
  readonly ir: ScriptIr; // frozen, JSON-serializable
  readonly abi: ScriptAbi<name, args, ret>; // literal-typed value, exists pre-compile
  compile(options?: CompileOptions): CompiledEvsScript<name, args, ret>; // sugar for compile()
}

• name — the literal script name; becomes the ABI function name.
• args — the normalized readonly ArgSpec[] of argument specs (the type param, not a runtime field): each { name, type } carries the surfaced arg name (a namedArg name, or the arg{i} fallback for a bare arg) and its type.
• ir — the recorded program. Serialize it with serializeIr or run it with the interpret oracle without compiling; see testing scripts.
• abi — the literal-typed ScriptAbi (one view function plus the two evs error entries). It exists before you compile, so viem type inference works without any artifact. See the artifact reference for its shape.
• compile(options?) — identical to the free-standing compile(script, options).

namedArg() and ArgSpec

import type { ArgType, EvsType } from '@maxencerb/evs';

interface ArgSpec<name extends string = string, type extends ArgType = ArgType> {
  readonly name: name;
  readonly type: type;
}

declare function namedArg<const name extends string, const type extends EvsType>(
  name: name,
  type: type,
): ArgSpec<name, type>;

namedArg names one top-level arg/param so the name surfaces in the resulting type — usable consistently in both a script’s args and an s.fn’s params. Anywhere a bare t.* type is accepted, a namedArg(...) is too. A named script arg surfaces as a labeled element in the viem args tuple ([token: 0x…] instead of [arg0: 0x…]); a named s.fn param surfaces as a labeled callback parameter ((token) => …). A bare (unnamed) arg keeps the positional arg0/arg1/… fallback name. namedArg validates at the call site and returns a frozen object:

• name must match /^[A-Za-z_]\w*$/; otherwise EvsTypeError with the call-site location.
• type is any EvsType — a word type, string, bytes, an array, or a composite t.struct/t.tuple (a named struct arg arrives as a Tuple handle, exactly like a bare one). Only top-level args are named as a whole; nested composite fields are named via t.struct. Deferred Solidity shapes (fixed-size T[N] arrays) throw EvsTypeError with code UNSUPPORTED_V0; malformed inputs throw TYPE_MISMATCH. Note s.fn params remain word/string-typed — a composite param is rejected when the fn is defined (see functions).

import { evscript, namedArg, t } from '@maxencerb/evs';

const token = namedArg('token', t.address);
const token: ArgSpec<"token", "address">
const fees = namedArg('fees', t.array(t.uint24)); // ArgSpec<'fees', 'uint24[]'>
const amount = namedArg('amount', 'uint128'); // raw type strings work everywhere t.* does

// composite types can be named too — the callback receives a Tuple handle
const MarketParams = t.struct({ loanToken: t.address, lltv: t.uint256 });
const position = evscript(
  { name: 'position', args: [namedArg('marketParams', MarketParams)] },
  (s, marketParams) => s.return({ loan: marketParams.loanToken.get() }),
);
void [token, fees, amount, position];

Used in a script’s args, the name flows into the ABI input and surfaces as the viem args label — hover the inferred Args type below (a bare arg would read arg0/arg1 instead):

import { evscript, namedArg, t } from '@maxencerb/evs';
import type { ReadContractParameters } from 'viem';

const balance = evscript(
  { name: 'balance', args: [namedArg('token', t.address), namedArg('holder', t.address)] },
  (s, token, holder) => s.return({ token, holder }), // body params are labeled `token`, `holder`
);

// viem labels the call args with your names — `token`/`holder`, not `arg0`/`arg1`:
type Args = ReadContractParameters<typeof balance.abi, 'balance'>['args'];
type Args = readonly [token: `0x${string}`, holder: `0x${string}`]
void balance;

Note

TypeScript tuple/parameter labels are cosmetic — they improve autocomplete and hover but are not part of type identity. The name is also carried, observably, in the script’s ABI input name (and the IR), which is what viem derives the args tuple label from.

For script arguments, declaration order is still load-bearing: the args list order is the type-level order, the runtime encode order, and the ABI inputs order — call sites stay viem-native positional (args: [pool, fee]). The full type vocabulary lives in the types reference.

compile()

import type { ArgSpec, CompiledEvsScript, CompileOptions, EvsScript, ReturnValue, ScriptIr } from '@maxencerb/evs';

declare function compile<
  s extends { readonly name: string; readonly ir: ScriptIr; readonly abi: readonly unknown[] },
>(
  script: s,
  options?: CompileOptions,
): s extends EvsScript<
  infer n extends string,
  infer a extends readonly ArgSpec[],
  infer r extends Record<string, ReturnValue>
>
  ? CompiledEvsScript<n, a, r>
  : never;

compile turns a recorded script into a CompiledEvsScript. The pipeline: validate the IR, lower to assembler nodes, run the peephole hook, assemble with the mandatory verifiers, enforce the EIP-170 size cap, and merge site information into the source map. Stage-by-stage detail is in how it works.

The constraint is structural ({ name, ir, abi }) rather than s extends EvsScript — a deliberate, recorded deviation so that every concrete script is assignable; the result type is exactly CompiledEvsScript with the script’s literal type parameters preserved.

Failure modes:

• EvsCompileError with code EVM_VERSION for an unknown evmVersion string.
• EvsCompileError with code COMPILE_LIMIT when the runtime bytecode exceeds the EIP-170 limit of 24,576 bytes; the message includes a per-region size breakdown (dispatcher, body, fns, tails, data segments).
• EvsTypeError when the value passed is not a script object.

import { compile, evscript } from '@maxencerb/evs';
import type { EvsDiagnostic } from '@maxencerb/evs';

const whoami = evscript({ name: 'whoami', args: [] }, (s) => s.return({ me: s.env('caller') }));

const warnings: EvsDiagnostic[] = [];
const compiled = compile(whoami, {
  evmVersion: 'paris', // pre-Shanghai target
  onDiagnostic: (d) => warnings.push(d), // ENV_FRAME_DEPENDENT lands here
});

CompileOptions

import type { AsmNode, EvmVersion, EvsDiagnostic } from '@maxencerb/evs';

interface CompileOptions {
  evmVersion?: EvmVersion; // 'paris' | 'shanghai' | 'cancun'
  peephole?: (nodes: readonly AsmNode[]) => AsmNode[];
  onDiagnostic?: (d: EvsDiagnostic) => void;
  locations?: boolean;
}

Option	Default	Effect
evmVersion	'cancun'	Target opcode set ('paris', 'shanghai', or 'cancun'). Anything else throws EvsCompileError (EVM_VERSION). See EVM targets.
peephole	identity	Optimizer seam: transforms the assembler node stream before layout. No optimizer ships in v0. The mandatory verifiers run on the hook’s output.
onDiagnostic	no-op	Receives every compile-time warning (LOOP_ALLOCATION, LARGE_FRAME, ENV_FRAME_DEPENDENT). evs never logs; without a callback, diagnostics are silently dropped.
locations	true	Whether source locations are carried into the emitted source map.

The compiled artifact exposes the fully resolved options as options: Readonly<Required<CompileOptions>> — defaults filled in. Diagnostic codes and their meaning are documented in diagnostics.

Note

onDiagnostic is the only channel for warnings. If you compile a script that reads s.env('caller') or s.env('address') without a callback, you will not see the ENV_FRAME_DEPENDENT warning — wire it up in development. Why it matters: execution modes.