ANTRequest's ANTwasm Specification (Version 0.0.1)

warning! This specification is unfinished. while you MAY implement it as written, the update comes in the form of a version bump.

ANT.wasm is a Brand New way to run wasm safely and securely (or that us the goal).

to use ANT.wasm you can use This Specification to insure interoperability. If you do not Like where this is going please fork.

Table Of Contents

Status of this document

this document written on Sun Mar 15 2026 is Semantic version 0.0.1. this document is self-published independently.

i am still Figuring things out. this is not final design and might be vague, impossible, or otherwise not implementable. im still seeking to bring this closer to my vision.

This Specification Depends On

This Specification uses external references

WebAssembly

As a refresher here are some concepts you need to know.

The WASM Border is the Linear Memory Wasm has. it is the only way to communicate to the Wasm program and the only way for wasm to take inputs.
WebAssembly only uses the following types. we assume everyone can use those across the WASM Border.
- f32: a float 32.
- f64: a float 64.
- i32: an int 32.
- i64: an int 64.
A Wasm Module is a Wasm File.
An Export is What the Wasm Module gives to the Edge.
An Import is What the Edge gives to the Wasm Module.

Phases

Your Wasm package is called a game. Your Game has the following phases. in order of appearance

Name	Description
Loading Phase	Here is where the Edge loads and verifies the ANT.zip. if it is marked as Untrusted the Edge MUST abort proceeding.
Initialization Phase	Here is where you Initialize your game before it runs.
game Phase	Here is where you let the player play. this is activated by calling `start_game`.

Internal Abstract Operation

It is assumed Imports and Exports are called to the invoking Wasm Module unless otherwise stated.

the notation [[Variablename]] is an internal variable type. wasm doesnt support strings so [[String]] is for the specification only is what i mean.
the notation [[%FunctionName%]] is an internal function name. they MUST NOT be exposed to any Wasm Module.
the notation $Variablename is an internal variable name used only in the internal function. they are unobservable outside it. even if they share the same name

If any of the following Invariants are violated, that is a spec bug.

`[[%StringFromBytes%]] (ptr: i32, len: i32): [[String]]`

Do the following in order

Go to ptr (inclusive) until (ptr + len) (exclusive) of the current Wasm Module's Linear Memory and take the raw bytes as $string.
Assume: $string is the UTF-8 bytes of the intended string.
If $path contains illegal UTF-8 characters return GENERIC_FAILURE (-1).
Return $string.

`[[%BytesFromString%]] (string: [[String]]): i32`

Do the following in order

Assert:: $string is encoded in UTF-8 bytes (is a MUST due to the Foundation's Global Rules).
Set $length to the length of $string in UTF-8 bytes.
If host_malloc is not exported return WASM_PORT_MISSING (-7).
Set $pointer to the result of calling host_malloc with $length.
Write the bytes of $string at $pointer (inclusive) until ($pointer + $length) (exclusive) in the current Wasm Module's Linear Memory.
Return $pointer .

`[[%LoadModule%]] (path: [[String]], Imports: [[ImportLibrary]])>: i32`

Do the following in order

If Game has Started Return GAME_IS_RUNNING_ERROR (-5).
Resolve $path using ANT.zip's Application Behavior to be $resolved.
If the above step fails return the appropriate Error Code.
If $resolved is not a valid Wasm Module, Return RESOLUTION_ERROR (-3).
Initialize and load $resolved as a Wasm Module with Imports as Imports.
If Initializing and loading fails then return RESOLUTION_ERROR (-3).
add 1 to the integer $wasmModulesLoaded.
call $resolved's exported load_module if present with ($wasmModulesLoaded as ModuleId).
Return $wasmModulesLoaded.

Basic Global Library

All Wasm Modules MUST expose or be exposed to the following functions

Name	Types	Import/Export	Description
`host_malloc`	`(bytes: i32): i32`	Export	`host_malloc` MUST return a positive number indicating a pointer (`$pointer`) on that Wasm's Linear Memory, `$pointer` until (`$pointer` + `bytes`) MUST be free for the Edge to store whatever is the Edge needs. If that fails or there isnt memory to allocate to the Edge, Return the appropriate Error Code. Info! Wasm only provides a Linear Memory. think of it as a single Uint8Array, without dictating how it stores its memory, the Edge still needs to write to that Linear Memory in order for the wasm to do stuff. that's why `host_malloc` MUST be exported, to provide a way for the Edge to ask where to write the amount of `bytes` to. Warning! for internal operations not crossing the WASM Border, please use your language's internal Memory Allocator. `host_malloc` is only fo the Edge to request memory space to write data for the Wasm Module to read.
`on_module_load`	`(ModuleId: i32): void`	Export	called when the Wasm Module is loaded via `load_module`.

Main

A Main is a wasm file that is called after a Core. it is the main function.

If we are talking about User Generated Content games, A Core is the actual Game where A Main is the core for a sharable package a user has created.

A Main MUST expose or be exposed to the following functions

Name	Types	Import/Export	Description
`load_module`	`(ptr: i32, len: i32): i32`	Import	Do the following in order If Game has Started Return `GAME_IS_RUNNING_ERROR` (-5). Set `$path` to Calling `[[%StringFromBytes%]]` giving `ptr` and `len`. If `$path` starts with `/core/` (case-insensitive), Return `PATH_RESOLUTION_ERROR` (-2). If `$path` is `/core.wasm` (case-insensitive), Return `PATH_RESOLUTION_ERROR` (-2). If `$path` is `/main.wasm` (case-insensitive), Return `PATH_RESOLUTION_ERROR` (-2). Return the result of Calling `[[%LoadModule%]]` given `$path` and (Basic Global Library as `Imports`). Info! usually called "import" in other languages, Wasm terminology already uses that word for something else. `load_module` fits as name.
`start_game`	`(): void`	Import	Do the following in order Start the Game.

Cores

A Core is a wasm file that is first called. it is the engine so games can stay self-contained within their ANT.zip. the core MUST live at "/core.wasm" (case-sensitive) ziproot path.

If we are talking about User Generated Content games, A Core is the actual Game where A Main is the core for a sharable package a user has created.

A Core MUST expose or be exposed to the following functions

Name	Types	Import/Export	Description
`load_module_core`	`(ptr: i32, len: i32): i32`	Import	Do the following in order If Game has Started Return `GAME_IS_RUNNING_ERROR` (-5). Set `$path` to Calling `[[%StringFromBytes%]]` giving `ptr` and `len`. If `$path` is `/core.wasm` (case-insensitive), Return `PATH_RESOLUTION_ERROR` (-2). If `$path` does not start with `/core/` (case-insensitive), Return `PATH_RESOLUTION_ERROR` (-2). Return the result of Calling `[[%LoadModule%]]` given `$path` and (Basic Global Library as `Imports`). Info! usually called "import" in other languages, Wasm terminology already uses that word for something else. `load_module` fits as name.
`load_main`	`(): void`	Import	Do the following in order If Game has Started Return `GAME_IS_RUNNING_ERROR` (-5). Return the result of Calling `[[%LoadModule%]]` given `"/main.wasm"` and (Basic Global Library and Main as `Imports`). Info! usually called "import" in other languages, Wasm terminology already uses that word for something else. `load_module` fits as name.

Error Codes

the following table will list the error codes as negative numbers, their canonical upper snakecase name, and their description.

Code	UPPER_CASE_NAME	Description
`-1` (Negative One)	`GENERIC_FAILURE`	A Generic Failure.
`-2` (Negative Two)	`PATH_RESOLUTION_ERROR`	A path cant be resolved due to any reason, including bt not limited to a path contains a Banned Character a path contains an upward directory indicators (`..`) or current directory indicators (`.`). a path referenced any file located outside the ZIPRoot.
`-3` (Negative Three)	`RESOLUTION_ERROR`	A Path requiring a Wasm Module, but doesnt point to a valid compilable Wasm Module.
`-4` (Negative Four)	`GAME_HASNT_STARTED_YET_ERROR`	the `start_game` function hasnt been called by the Core when the function requires the game to be started.
`-5` (Negative Five)	`GAME_IS_RUNNING_ERROR`	the `start_game` function has been called by the Corewhen the function requires the game to be in the initialization phase (before`start_game`).
`-6` (Negative Six)	`NO_MORE_MEMORY_ERROR`	The Operation requires more memory but it cant be granted
`-7` (Negative Seven)	`WASM_PORT_MISSING`	An Import or Export is missing