ao Wasm Loader

This module takes an ao Wasm ArrayBuffer and returns a handle function,
that given an ao-process message, will produce a result.

- Usage
- Using a File
- Using fetch
- Result Object
- Contributing
- Publish a new Version of the package

Usage

The @permaweb/ao-loader MUST receive an ArrayBuffer that contains the Wasm
to be invoked:

``js
import AoLoader from "@permaweb/ao-loader";

/ ao READ-ONLY Env Variables /
const env = {
Process: {
Id: "2",
Tags: [
{ name: "Authority", value: "XXXXXX" },
],
},
};

// Create the handle function that executes the Wasm
const handle = await AoLoader(wasmBinary, {
format: "wasm32-unknown-emscripten2",
inputEncoding: "JSON-1",
outputEncoding: "JSON-1",
memoryLimit: "524288000", // in bytes
computeLimit: 9e12.toString(),
extensions: []
});

// To spawn a process, pass null as the buffer
const result = await handle(null, {
Owner: "OWNER_ADDRESS",
Target: "XXXXX",
From: "YYYYYY",
Tags: [
{ name: "Action", value: "Ping" },
],
Data: "ping",
}, env);
`

// To evaluate a message on an existing process

`js
const options = {
format: "wasm32-unknown-emscripten2",
inputEncoding: "JSON-1",
outputEncoding: "JSON-1",
memoryLimit: "524288000", // in bytes
computeLimit: 9e12.toString(),
extensions: []
}
const handle = await AoLoader(wasmBinary, options);
const buffer = await LoadFromCache();

const result = await handle(buffer, {
Owner: "OWNER_ADDRESS",
Tags: [
{ name: "Action", value: "Balance" },
{ name: "Target", value: "vh-NTHVvlKZqRxc8LyyTNok65yQ55a_PJ1zWLb9G2JI" },
],
}, env);

saveToCache(result.Memory);
console.log(result.Output);
`

$3

You can use fs to a load a Wasm file from the local filesystem as a Node
Buffer. Since a Node Buffer implements ArrayBuffer, it can be passed
directly to the AoLoader directly!

> To get back a Node Buffer, make sure to NOT pass an encoding parameter
> to readFile

`js
import AoLoader from "@permaweb/ao-loader";
import fs from "fs";

async function main() {
const wasmBinary = fs.readFileSync("process.wasm");
const options = {
format: "wasm32-unknown-emscripten2",
inputEncoding: "JSON-1",
outputEncoding: "JSON-1",
memoryLimit: "524288000", // in bytes
computeLimit: 9e12.toString(),
extensions: []
}
const handle = AoLoader(wasmBinary, options);
const result = await handle(...);
}
`

$3

You can also use native fetch to retrieve the Wasm as an ArrayBuffer. This
is great if you're fetching a Wasm contract published on Arweave:

`js
import AoLoader from "@permaweb/ao-loader";

async function main() {
const tx_id = '...'
const wasmBinary = await fetch(https://arweave.net/${tx_id})
.then(res => res.arrayBuffer())
const options = {
format: "wasm32-unknown-emscripten2",
inputEncoding: "JSON-1",
outputEncoding: "JSON-1",
memoryLimit: "524288000", // in bytes
computeLimit: 9e12.toString(),
extensions: []
}

const handle = AoLoader(wasmBinary, options);
const result = await handle(...)
}
`

$3

The Result Object returns a Successful Result:

`
{
Output,
Messages,
Spawns,
Assignments,
GasUsed
}
`

Or an unSuccessful Result:

`
{
Error
}
`

Contributing

$3

We use a Github workflow to build and publish new version of the Loader to NPM.
To publish a new version, go to the
ao Loader workflow
and click the Run Workflow button. Provide the semver compatible version you
would like to bump to, and then click Run Workflow`. This will trigger a
Workflow Dispatch that will bump the version is the manifest files, build the module, and finally publish it to NPM