@milaboratories/sandbox-runtimes

The sandbox-js-1 and sandbox-wasm-1 runtimes: the QuickJS artifact, the host wire codec, the runtime classes and their error classes.

Install

pnpm add @milaboratories/sandbox-runtimes@<exact version>

Pin the exact version; every package of this repository is released together under one version.

Exports

• SandboxJs1QuickJsRuntime, SANDBOX_JS_1 — the sandbox-js-1 runtime and its contract token.
• SandboxWasm1WebAssemblyRuntime, SANDBOX_WASM_1 — the sandbox-wasm-1 runtime and its contract token.
• The contract types Runtime, Snapshot, Instance, InstanceState, ExecutionUnit, Injection, Clock, RandomSource, RuntimeOptions, TimeLimitOptions, and Value.
• The error classes: GuestError, LimitError, ComputeTimeError, DeadlineError, MemoryLimitError, StackOverflowError, EngineTrapError, ProtocolError, ValueError, NoSuchFunctionError, ReentrantCallError, InstanceStateError.
• The wire codec: encode, decode, the frame helpers, MAX_DEPTH, MAX_FRAME_BYTES.
• Files: quickjs.wasm (the artifact), quickjs.manifest.json (its hash, pins, imports and exports), vectors.json (the wire vectors).

The Artifact

The runtime takes the artifact's bytes; resolve them from this package and read them once:

import { readFileSync } from "node:fs";
import { createRequire } from "node:module";
import { SandboxJs1QuickJsRuntime } from "@milaboratories/sandbox-runtimes";

const require = createRequire(import.meta.url);
const artifact = readFileSync(require.resolve("@milaboratories/sandbox-runtimes/quickjs.wasm"));
const runtime = new SandboxJs1QuickJsRuntime({ artifact, clock });

Every runtime of one sandbox takes the same clock. The manifest's sha256 equals runtime.describe().artifactSha256 for the artifact this package ships.

Core Modules

SandboxWasm1WebAssemblyRuntime has no artifact: a sandbox-wasm-1 unit is itself the module, compiled by the host's WebAssembly at snapshot(), so the constructor takes only the clock and, optionally, a random source:

import { SandboxWasm1WebAssemblyRuntime } from "@milaboratories/sandbox-runtimes";

const runtime = new SandboxWasm1WebAssemblyRuntime({ clock });

describe() names the host's WebAssembly engine and version with an empty artifactSha256. supports.deadline and supports.computeTime are false: time limits passed to snapshot() or call() are validated, then not enforced. A module outside the contract's shape (contracts/sandbox-wasm-1.md) is refused at snapshot() with ValueError before it is compiled.