Reference

Compute program interface

Keep this page open while you write a program for Compute. It says what a WebAssembly module may import and must export, when the platform calls it, and what happens when a call fails. For the steps to build and run one, see Write your first program, Run a program as a process and Wake a process on a timer or a schedule. The fields of Program and Process are on Resources.

What the module must look like

A program is a WebAssembly core module that uses the canonical ABI (the output of wit-bindgen for the interface below, without a component step). It is checked when you register it, and again by the node before it runs.

RuleValue
SizeAt most 256 KiB.
Declared memoryA maximum is required, at most 4096 pages (256 MiB).
Exportsmemory, cabi_realloc and the five handlers below.
ImportsOnly functions listed on this page, from etorm:compute/host@0.1.0 and etorm:compute/objects@0.1.0. An unknown import is refused with its name. There is no WASI: no files, sockets, environment or wall clock.
Start functionNot allowed.
Interface version0.1.0. A program that imports a function the platform lacks is refused at registration.

Functions a program can call

These are imported from etorm:compute/host@0.1.0. You can call them only while a handler runs.

FunctionBehaviour
interfaces() -> list<interface-info>One entry per interface of the process: index, name, mac (6 bytes), mtu, link-local (16 bytes) and prefix (the first 8 bytes of the VPC's IPv6 /64, if any).
send(interface, frame) -> resultQueues one Ethernet frame without FCS or VLAN tag. Frames leave when the activation ends, in order. Errors: no-such-interface, too-large(limit) (also for a frame shorter than 14 bytes), bad-source-mac, queue-full.
now() -> u64Monotonic nanoseconds. Only differences mean anything. It never goes back, also across a restore.
unix-seconds() -> u64Wall clock in seconds since the Unix epoch.
set-timer(id, at)Wakes the process with timer(id) at a value of now. Setting an id again replaces it. At most 16 timers.
cancel-timer(id)Removes a timer.
random(len) -> list<u8>Secure random bytes, at most 4096 per call.
config(key) -> option<string>A value of the process's spec.config.
log(level, message)Level 0 debug, 1 info, 2 warn, 3 error. The last 50 lines are in status.logs.
state-get() -> list<u8>The durable state, empty before the first state-set.
state-set(state) -> resultReplaces the state. Error too-large(limit) above spec.resources.stateMaxBytes. Takes effect only if the activation finishes.
report(key, value) -> resultShows a value in status.reported. The last write of a key wins and an empty value removes it. Keys are 1 to 64 bytes of A-Z a-z 0-9 _ . - (otherwise bad-key); keys and values together at most 4096 bytes (otherwise too-large). Takes effect only if the activation finishes.

Handlers the platform calls

Export each one as etorm:compute/handler@0.1.0#<name>. All five must be exported, even if your program has nothing to do in some of them. A handler that does nothing can be empty.

HandlerCalled withWhen
start(reason)0 created, 1 resumed, 2 restarted, 3 restoredOnce at the beginning of each life (below), before any other handler.
scheduled(tick)name, due (Unix seconds), missedA schedule of the process ticked. Ticks missed while the process could not run arrive as one tick with missed above 0.
timer(id)The id given to set-timerThe timer is due. It never fires early, fires once, and fires late if the process could not run in time.
frames(batch)Up to 64 frames, oldest first, each with its interface index and bytesFrames are waiting.
stop()NothingBefore the process is suspended, stopped or replaced. It has a small allowance of fuel (20 000) to save state.

What happens when a process wakes

An activation is one wake-up. The handlers that apply are called in this order: start (first activation of a life only), scheduled for each due tick, timer for each due timer, frames for each batch. A process is woken by a frame, one of its timers, one of its schedules, or its own lifecycle, and at most 100 times a second.

Limits

WhatLimit
Program module256 KiB (platform programs: 32 MiB)
Declared memory maximum4096 pages (256 MiB)
Process memory64 KiB times 2 to the power memoryPower (0 to 12, default 4 = 1 MiB; 12 = 256 MiB). A program that needs more at start-up is refused; growing past it fails the activation.
ProcessorcpuMillicores 1 to 1000 (default 100; a core is 2 000 000 000 fuel a second). A process with no allowance left waits; status.usage.throttled counts the waits. cpuShare (1 to 100, default 10) is the weight when processes compete.
StatestateMaxBytes up to 1 MiB (default 64 KiB)
Config64 entries, 16 KiB in all
Interfaces per process8
Timers per process16
Schedules per process8
Buckets per process4
Frames per handler call64
Queue per interface256 frames in each direction; a full ingress queue drops the newest frames (status.usage.framesDropped)
Frame size14 bytes to MTU + 14 (at most 1514)
Send rate per interface2000 frames a second sustained (burst 4000), 16 Mbit/s; the rest is dropped and counted
Wake-ups100 a second per process
random4096 bytes per call
report4096 bytes in all, keys up to 64 bytes

Frames a process sends and receives

When a process fails, restarts or stops

EventResult
One activation fails (trap, out-of-bounds access, memory or fuel limit, malformed return)Nothing it did is committed. The process stays Ready with condition LastActivationFailed; the error is in status.usage.lastError.
Five failures in a rowPhase Failed.
restartPolicy: Always (default) or OnFailureA Failed process starts again after 10 seconds, then 20, doubling up to 10 minutes. The new life calls start(restarted) and keeps the saved state.
restartPolicy: NeverIt stays Failed.
desiredState: Suspendedstop runs, then nothing is delivered; state and interfaces are kept. Resuming calls start(resumed); due timers fire once.
desiredState: Stoppedstop runs and the state is deleted.

Whatever goes wrong, a process cannot affect another process, the node or the network beyond its own interfaces. Its only effects are frames, state, timers, reports and log lines.

Read and write objects in a bucket

A program that imports etorm:compute/objects@0.1.0 can use the buckets named in the process's spec.buckets (up to four, in the same project). Any other bucket returns not-bound. Calls are synchronous.

FunctionBehaviour
get(bucket, key)The object, or none.
put(bucket, key, value, create-only)Writes the object. With create-only it writes only if the key does not exist and returns false if it did; otherwise it returns true.
delete(bucket, key)Deletes the object.

Keys are 1 to 1024 bytes of UTF-8, and values are up to 32 MiB. The errors are not-bound, unavailable, too-large and bad-key. Writes are not rolled back when an activation fails, so a write can outlive an activation that did not commit.

Hibernate a resident process

A resident process with spec.hibernation.bucketRef can be set to desiredState: Hibernated. Its memory, globals, state, timers and schedule positions are written as a snapshot to the bucket and the machine lets go of it. Setting Running continues it on the machine that serves its VPCs, with the same MAC and addresses, and calls start(restored). Frames that were queued are dropped, and now continues from where it was plus the time that passed. The latest snapshot is in status.snapshot. See Hibernate and resume a process.

Write the program in Rust

If you write in Rust, you do not have to use the raw interface. The etorm-guest crate wraps it for programs built for wasm32-unknown-unknown. Your program implements the Program trait (start, frames, timer, scheduled, stop, with empty defaults for the ones you leave out) and declares it with program!. Every handler gets a Cx with now, unix_seconds, send, set_timer, cancel_timer, interfaces, config, log, state, set_state, random and objects (get, put, put_new, delete). A resident process keeps the Program value between calls, and an ephemeral one gets a new value each time. The crate also builds natively with an in-memory host, so programs can be tested without a node.

The crate includes a TCP and IPv6 stack (etorm_guest::net, neighbor discovery, ICMPv6, listeners, outbound connections) driven by frames and a timer in the reserved id range 0xFFFF0000 to 0xFFFF00FF. TLS is not included. A program built with the SDK needs a declared memory maximum and a stack size that fits its memory allowance.

What the interface leaves out

Check these before you design a program around the interface.