Develop and Test a Service

This guide will walk you through developing a WASM component, which is the core logic of a service.

Prerequisites

1. If you haven't already, install the Rust toolchain with at least version 1.80.0. You can follow these instructions. Make sure you have followed the getting started guide before proceeding.

2. Even though we will be building a Wasm component that targets WASI Preview 2, the Rust wasm32-wasip2 build target is not quite ready yet. So we will use cargo-component to compile the wasm32-wasip1 binaries and package to use WASI Preview 2.

3. If you haven't yet, add the WASI Preview 1 target:

rustup target add wasm32-wasip1

4. Install cargo-component and wkg CLIs:

cargo install cargo-component wkg

5. Set the default registry configuration, where the lay3r:avs WIT package is published:

wkg config --default-registry wa.dev

For more information about configuration, visit the wkg docs.

Setup a New Project

1. To create an new Wasm Component for use with Layer's Wasmatic, use cargo component to scaffold a new project with a task queue trigger. Feel free to choose a different project name other than "my-task".

cargo component new --lib --target lay3r:avs/task-queue my-task && cd my-task

2. Let's do the first build to generate the src/bindings.rs file. Afterwards, you can do the familiar cargo commands such as cargo test and cargo clippy. It may be helpful to inspect src/bindings.rs during development to see the type information for producing the Wasm component.

cargo component build

3. It is helpful to add the layer-wasi crate to make outgoing HTTP requests easily. See the oracle example for more information.

cargo add --git https://github.com/Lay3rLabs/avs-toolkit layer-wasi

4. Then you can start developing your application by editing the src/lib.rs file. See the square example for more information.

Unit Testing

For running unit tests, the familiar commands will work.

cargo test

Deploying

Let's do a release build of the component:

cargo component build --release

Upload the compiled Wasm component to the Wasmatic node using the avs-toolkit-cli CLI tool (if you don't have it already, go check the chapter Rust CLI).

When doing an upload, you'll need to choose a unique name for your app, so that you can identify and test it, or remove your deployment if needed.

You'll also need to use the task address that was created when you deployed your contract. If you forgot how to access it, you can find it in the getting started guide.

avs-toolkit-cli wasmatic deploy --name <your-app-name> \
    --wasm-source ./target/wasm32-wasip1/release/my_task.wasm  \
    --testable \
    --task <TASK-ADDRESS>

Remove a Deployment

If you want to remove your deployment, you can do so via the remove command below

avs-toolkit-cli wasmatic remove --name <your-app-name>

Test Executions

You can use avs-toolkit-cli to test your component locally before you deploy, as well as after.

To test and execute locally, run the following with optional parameters for environment variables and input JSON for the app:

avs-toolkit-cli wasmatic run \
    --wasm-source ./target/wasm32-wasip1/release/my_task.wasm  \
    --envs "EXPECTED_VAR=VAL,EXPECTED_VAR1=VAL1" \
    --input '{}'

If your app uses the file system for state and you'd like to have the state available for the next local execution and available for easy inspection, provide --dir flag with the directory path for the app to store its state. For example, using ./app-data dir in the current working directory. If omitted, the app will use a temporary directory that will be cleaned up after execution completes.

avs-toolkit-cli wasmatic run \
    --wasm-source ./target/wasm32-wasip1/release/my_task.wasm  \
    --envs "EXPECTED_VAR=VAL,EXPECTED_VAR1=VAL1" \
    --input '{}' \
    --dir app-data

You can also test your component remotely after you've deployed it. This is only possible if you used the --testable flag during deployment.

The server responds with the output of the applicaton without sending the result to the chain. For the input flag, you'll use the json input expected by the WASI component you're testing.

avs-toolkit-cli wasmatic test --name <your-app-name> --input '{}'

It will parse the input as if you pushed it to the task queue and return the result (or error) to the caller.