WASM ABI

Overview

WASM modules compiled from Rust (using cosmictron-sdk) import host functions from the Cosmictron server. These functions are provided at module load time by Wasmtime.

Host functions are organized into three import modules:

Import module	Purpose
`datastore`	Database read/write operations
`cosm`	Context: identity, timestamp, scheduling
`console`	Logging

All parameters and return values are either primitives (i32, i64) or pointers into WASM linear memory, where data is encoded in BSATN (binary format).

datastore module

`insert`

Insert a BSATN-encoded row into a table.

(func (import "datastore" "insert")
  (param $table_id i32)
  (param $row_ptr i32)
  (param $row_len i32)
  (result i32))

Returns 0 on success, non-zero error code on failure (e.g., unique constraint violation, type mismatch).

`delete_by_pk`

Delete a row by its primary key.

(func (import "datastore" "delete_by_pk")
  (param $table_id i32)
  (param $pk_ptr i32)
  (param $pk_len i32)
  (result i32))

Returns 0 on success, 1 if row not found.

`scan`

Start a full table scan. Returns an iterator handle.

(func (import "datastore" "scan")
  (param $table_id i32)
  (result i64))

Returns an i64 iterator handle. Pass to iter_next to read rows.

`index_scan`

Start a scan over an index range.

(func (import "datastore" "index_scan")
  (param $table_id i32)
  (param $index_id i32)
  (param $range_ptr i32)
  (param $range_len i32)
  (result i64))

`iter_next`

Advance an iterator and write the next row into WASM memory.

(func (import "datastore" "iter_next")
  (param $iter_handle i64)
  (param $out_ptr i32)
  (param $out_len i32)
  (result i32))

Returns bytes written, or 0 if the iterator is exhausted.

`iter_close`

Release an iterator handle.

(func (import "datastore" "iter_close")
  (param $iter_handle i64))

`table_id_from_name`

Look up a table ID by name (UTF-8 string in WASM memory).

(func (import "datastore" "table_id_from_name")
  (param $name_ptr i32)
  (param $name_len i32)
  (result i32))

cosm module

`sender_identity`

Write the current caller’s identity bytes into WASM memory.

(func (import "cosm" "sender_identity")
  (param $out_ptr i32)
  (param $out_len i32)
  (result i32))

`timestamp`

Get the current transaction timestamp (Unix microseconds).

(func (import "cosm" "timestamp")
  (result i64))

`schedule_reducer`

Schedule a reducer to run at a future time.

(func (import "cosm" "schedule_reducer")
  (param $reducer_ptr i32)
  (param $reducer_len i32)
  (param $args_ptr i32)
  (param $args_len i32)
  (param $delay_micros i64)
  (result i64))

Returns a schedule handle. Pass to cancel_reducer to cancel.

`cancel_reducer`

Cancel a scheduled reducer.

(func (import "cosm" "cancel_reducer")
  (param $handle i64))

`http_request`

Make an outbound HTTP request from a reducer.

(func (import "cosm" "http_request")
  (param $req_ptr i32)
  (param $req_len i32)
  (param $out_ptr i32)
  (param $out_len i32)
  (result i32))

The request is BSATN-encoded HttpRequest { method, url, headers, body }. The response is written to out_ptr.

console module

`log`

Write a log message.

(func (import "console" "log")
  (param $level i32)
  (param $msg_ptr i32)
  (param $msg_len i32))

Log levels: 0=trace, 1=debug, 2=info, 3=warn, 4=error.

Error codes

Code	Meaning
`0`	Success
`1`	Row not found
`2`	Unique constraint violation
`3`	Type mismatch
`4`	Table not found
`5`	Permission denied (RLS)
`6`	Fuel exhausted
`7`	Memory limit exceeded
`8`	Transaction conflict (OCC)
`9`	Invalid argument

BSATN encoding

BSATN is a compact binary encoding similar to MessagePack. Type prefixes:

Tag	Type
`0x00`	`u8`
`0x01`	`u16`
`0x02`	`u32`
`0x03`	`u64`
`0x08`	`i8`
`0x09`	`i16`
`0x0A`	`i32`
`0x0B`	`i64`
`0x10`	`bool`
`0x11`	`String` (4-byte length prefix + UTF-8)
`0x12`	`bytes` (4-byte length prefix)
`0x20`	`Option<T>` (1-byte tag: `0x00` = None, `0x01` = Some)
`0x30`	`Vec<T>` (4-byte length + elements)
`0x40`	Struct (fields in declaration order, no tags)