@eco-incorp/sauce-compiler API

@eco-incorp/sauce-compiler is the SauceScript compiler compiled to WebAssembly: a thin wasm-bindgen marshalling layer over the Rust compiler core, with no compiler logic of its own. The core is I/O-free, so the JS host supplies a synchronous resolver. One package ships two builds of the same wasm and picks between them by exports condition.

Entry	Resolves to	Initialization
`@eco-incorp/sauce-compiler` in Node (`require` or ESM `import`)	CommonJS build that loads the wasm from disk	Nothing to await
`@eco-incorp/sauce-compiler` in browsers and bundlers	ESM build	Call the default export `init()` once before the first `compile`
`@eco-incorp/sauce-compiler/ready`	Either	`const { compile } = await ready();` initializes where needed and is a no-op otherwise
`@eco-incorp/sauce-compiler/node`, `/web`	The specific build	As above

The package ships its own TypeScript types, so a consumer does not declare them.

Reproduced from web/sauce_wasm.d.ts and web/ready.d.ts in @eco-incorp/sauce-compiler 2.3.0. The Node build shares the same declarations. The SDK’s @eco-incorp/sauce/compiler export re-exports compile and its types and adds the compact-argument codec; ready, clearFunctionCache and functionCacheStats are available only from this package.

Functions

`compile`

Compile a SauceScript program to Sauce bytecode. The option and result shapes are CompileOptions and CompileResult below. Validation, compile and resolve failures throw a JS Error. Source diagnostics include the rule that was broken, the source line and a caret under the span; option and resolver errors may have no span. A host callback’s thrown message is preserved in the chain.

export function compile(options: CompileOptions): CompileResult;

`ready`

Get the compiler, initialising the wasm if this environment needs it. The same call in Node and in the browser: the CommonJS build is already initialised by the time it resolves, and the browser build is initialised by it. Safe to call as often as you like: initialisation happens at most once, concurrent callers share the one attempt, and a failed attempt is not cached, so a retry is a real retry. The first successful source is the one used; a later one is ignored, because wasm initialisation is global to the module. At run time use Node or a bundler that supports package exports subpaths; TypeScript’s moduleResolution controls type lookup only.

import { ready } from "@eco-incorp/sauce-compiler/ready";

const { compile } = await ready();
const source = new TextEncoder().encode("function main() { return 1; }");
const { bytecode } = compile({ target: "evm", resolve: () => source });

export declare function ready(source?: WasmSource): Promise<SauceCompiler>;

`init` (default export) and `initSync`

The ESM build’s initializers. init makes a request when given a RequestInfo or URL and otherwise calls WebAssembly.instantiate directly; initSync instantiates bytes or a precompiled WebAssembly.Module. Passing the input directly rather than wrapped in an object is deprecated.

export default function __wbg_init(module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;
export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;

export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
export type SyncInitInput = BufferSource | WebAssembly.Module;

`clearFunctionCache`

Empty this WASM instance’s per-function lowering cache and reset its counters. The store persists across compile calls, is bounded and empties automatically when full. Changed source or consulted bindings invalidate reuse automatically, so clearing is for releasing cached lowerings or measuring a cold compile; it does not clear a file-content cache maintained by your resolver.

export function clearFunctionCache(): void;

`functionCacheStats`

Read the per-function IR-lowering cache’s counters, { hits, misses, inserts }, for measuring warm reuse across a route sweep. Counters are cumulative until clearFunctionCache() resets them.

export function functionCacheStats(): FnCacheStats;

Types

`SauceTarget`

The engine a program is compiled for.

export type SauceTarget = "evm" | "svm";

`ResolveModule`

Fetch a module’s bytes. A Node Buffer is a Uint8Array. Returning undefined or null means nothing at this path, which is the signal the per-target arm probe relies on to fall back to a module’s neutral arm (token.ts after token.evm.ts misses). A throw means the path names something that could not be read: it propagates rather than falling back, so a miss must not throw. Any other return type is a resolve error. A .json path is asked for either as a contract ABI or as a document the source imports as data (with { type: "json" }); both are bytes here, so serve any .json the program names.

export type ResolveModule = (path: string) => Uint8Array | undefined | null;

`ResolvePackage`

Map a bare specifier ("@sauce/token") to a path resolve accepts. undefined or null declines, falling back to using the specifier as a path; a throw means the package is not installed. importer is the resolved path of the importing module.

export type ResolvePackage = (specifier: string, importer: string) => string | undefined | null;

`CompileOptions`

Option	Type	Required	Notes from the declaration
`target`	`SauceTarget`	Yes
`resolve`	`ResolveModule`	Yes
`resolvePackage`	`ResolvePackage`	No
`entry`	`string`	No	The entry module the resolver is asked for first. Defaults to `"main.js"`.
`contracts`	`Array<[name: string, path: string]>`	No	`[name, path]` pairs declaring contracts the host holds by path. Each `path` resolves as a bare `import Name from "./path.json"` would, and emits the same bytes. The same specifier under `with { type: "json" }` reads the file as data rather than as an ABI.
`inlineContracts`	`Array<[name: string, abi: string]>`	No	`[name, abi]` pairs declaring contracts whose ABI JSON is given directly. Applied to the entry module only, exactly like `contracts`; a name colliding with a `contracts` entry, an inline `import`, another `inlineContracts` entry, or a declared function is a compile error.
`ambient`	`Array<string>`	No	Module specifiers whose exports are broadcast into every module with no `import` line. An ambient module defining `main` is a compile error. Ambient always loses to user code. A module has one namespace, so an occupied name blocks the broadcast on both channels. Two different ambient modules exporting the same name is a compile error. An absolute path, a per-target arm, a subpath, or a `.json` file is refused as a broadcast root.
`defines`	`Array<[name: string, value: string]>`	No	Compile-time parameters injected into every module as a module-scope `const`. A value is a decimal or `0x` hex integer string with an optional trailing `n` and `_` separators; a string because a define is a 256-bit word. A define overrides the module’s own `const` of that name, on both channels. It does not override a module-scope `let`, a declared function, a lookup table, a bound contract, a JSON data import’s binding, or an import’s local alias (each a compile error naming the define). The value must be assignable to the declaration’s type (only `0` or `1` reaches a `boolean`). A repeated name is an error. The name is program-wide, including packages you did not write.
`optimize`	`boolean`	No	Enable compiler optimizations (constant folding and propagation, bounded loop unrolling, scalar expression reuse, invariant tuple-read reuse, scalar helper inlining). Defaults to `true`; validation still runs when `false`.
`compactArgs`	`boolean`	No	Use compact-v1 entry arguments instead of ABI encoding. Defaults to `false`. Encode arguments with the returned `entrySchema`; ABI-encoded arguments cannot be substituted.
`cache`	`boolean`	No	The per-function lowering cache. Defaults to `true`. Memoizes each declared function’s lowering in a bounded store that empties automatically when full; changed source or consulted bindings invalidate reuse. Set `false` to bypass lookup and insertion for one compile; `clearFunctionCache()` empties the store.

export interface CompileOptions {
    target: SauceTarget;
    resolve: ResolveModule;
    resolvePackage?: ResolvePackage;
    entry?: string;
    contracts?: Array<[name: string, path: string]>;
    inlineContracts?: Array<[name: string, abi: string]>;
    ambient?: Array<string>;
    defines?: Array<[name: string, value: string]>;
    optimize?: boolean;
    compactArgs?: boolean;
    cache?: boolean;
}

`CompileResult`

bytecode is the reusable program without the caller’s argument values. isaRevision is the instruction-set compatibility identifier, independent of the npm version. entryEncoding is the encoding the program expects for entry arguments; entrySchema is present only with compact encoding and is the exact schema to pass to the compact codec. manifest is the SVM account manifest; undefined on the EVM, which has no such concept.

export interface CompileResult {
    bytecode: Uint8Array;
    isaRevision: "stack-compact-v2";
    entryEncoding: "abi-v1" | "compact-v1";
    entrySchema?: Uint8Array;
    manifest?: AccountManifest;
}

`AccountRole`

What a caller’s account must satisfy at a declared slot: the four values of Solana’s own AccountRole, so an SDK maps one onto an AccountMeta directly. It is the program author’s assertion, with the trust model of an ABI declaration: the compiler cannot know what a program invoked by CPI does with the accounts it is handed, so nothing here is inferred. A bare Account is "readonly".

export type AccountRole = "readonly" | "writable" | "readonly_signer" | "writable_signer";

`AccountEntry`

One entry in the attach contract. A slot is an Account parameter of main, read by the engine at index, carrying the source parameter’s name and the role it requires of whatever account is attached there. remaining is not an account but a position: it marks where the caller’s own variable-length accounts begin, and from is the index the first of them lands at. It appears only when the program reads that tail (svm.remainingAccount or svm.remainingAccounts), and it is always last.

export type AccountEntry =
  | { kind: "slot"; index: number; name: string; requires: AccountRole }
  | { kind: "remaining"; from: number };

`AccountManifest`

The index-to-account contract a caller attaches accounts against. SVM only.

export interface AccountManifest {
    accounts: AccountEntry[];
}

`FnCacheStats`

The per-function IR-lowering cache’s counters, from functionCacheStats().

export interface FnCacheStats {
    hits: number;
    misses: number;
    inserts: number;
}

`WasmSource` and `SauceCompiler` (from `/ready`)

What compile needs before it can run, where that differs by environment. Omit it and the browser build resolves the wasm next to its own module, which is what a bundler rewrites to an asset URL. Pass bytes or a URL when that does not apply. The Node build ignores it. Deliberately spelled without DOM types so the Node build typechecks for a consumer with no DOM lib; { href: string } is how a URL is accepted structurally. A Response still works at run time in a browser; widen it locally if you need one: ready(response as unknown as WasmSource).

export type WasmSource = ArrayBuffer | ArrayBufferView | { href: string } | string;

export interface SauceCompiler {
  compile(options: CompileOptions): CompileResult;
}

`InitOutput`

The raw wasm-bindgen instance returned by init and initSync. Consumers use compile, clearFunctionCache and functionCacheStats from the module instead of the fields on this object.

export interface InitOutput {
    readonly memory: WebAssembly.Memory;
    readonly clearFunctionCache: () => void;
    readonly compile: (a: any) => [number, number, number];
    readonly functionCacheStats: () => [number, number, number];
    // wasm-bindgen internals omitted
}

Complete example in Node

Create src/main.ts with this program:

main.ts

function main(amount: Uint256): Uint256 {
  return amount + 1;
}

Install @eco-incorp/sauce-compiler@2.3.0, then run the following with Node 24 or later. If you typecheck with tsc, install typescript and @types/node as development dependencies.

compile.ts

import { readFileSync } from "node:fs";
import { resolve } from "node:path";
import { compile } from "@eco-incorp/sauce-compiler";

const root = resolve("src");
try {
  const { bytecode } = compile({
    entry: "main.ts",
    target: "evm",
    resolve: (path) => {
      try {
        return readFileSync(resolve(root, path));
      } catch (error) {
        // A missing target-specific module lets the compiler try the neutral module.
        if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
        throw error;
      }
    },
  });
  console.log(`Compiled ${bytecode.length} bytes`);
} catch (error) {
  console.error("Compilation failed:", error);
  process.exitCode = 1;
}

Sauce SDK

@eco-incorp/sauce