OutLayer Documentation

What is WASI?#

WASI (WebAssembly System Interface) is a standardized API that allows WebAssembly modules to interact with the outside world - read files, access environment variables, make network requests, and generate random numbers.

Think of WASI as a "syscall interface for WebAssembly" - it provides the basic building blocks your WASM code needs to do real work, like reading input data or calling external APIs, while maintaining security through sandboxing.

Supported Languages#

Any language that compiles to WASM with WASI support: Rust, C/C++, Go, AssemblyScript, and more. Rust is recommended for best tooling and ecosystem support.

WASI Preview 1 vs Preview 2#

OutLayer supports both WASI P1 and P2 standards. Choose based on your requirements:

Rule of thumb: Use P1 unless you need HTTP or advanced I/O.

WASI Interface#

OutLayer provides a minimal WASI environment with support for:

• stdin/stdout: Read JSON input data, write JSON output results
• Environment variables: Access encrypted secrets via std::env::var()
• Random numbers: Cryptographically secure random generation (WASI P1 & P2)
• HTTP requests: Make external API calls (WASI P2 only, via wasi-http-client)
• File I/O (limited): Basic file operations in sandboxed environment
• NEAR context: Access execution metadata via env vars (NEAR_SENDER_ID, NEAR_BLOCK_HEIGHT, etc.)

Host Functions (Advanced)#

OutLayer provides advanced host functions for direct NEAR RPC access from WASM. These functions enable your code to interact with the NEAR blockchain without relying on external HTTP APIs.

Available Functions

Key Security Features

• WASM provides signer: Your code passes signer_key from secrets - worker never uses its own keys
• Private RPC access: Fastnear-powered endpoints with higher rate limits and reliability
• Transaction tracking: All transactions are logged and can be verified on-chain
• TEE isolation: Signing keys remain inside TEE and never leave the secure enclave

WIT Interface Definition

Host functions are defined in worker/wit/world.wit:

package near:[email protected];

interface api {
    view: func(
        contract-id: string,
        method-name: string,
        args-json: string
    ) -> tuple<string, string>;

    call: func(
        signer-id: string,
        signer-key: string,
        receiver-id: string,
        method-name: string,
        args-json: string,
        deposit-yocto: string,
        gas: string
    ) -> tuple<string, string>;

    transfer: func(
        signer-id: string,
        signer-key: string,
        receiver-id: string,
        amount-yocto: string
    ) -> tuple<string, string>;
}

world rpc-host {
    import api;
}

Critical Requirements#

Working Examples#

We provide 9 complete, open-source examples demonstrating different WASI patterns:

Resource Considerations#

Be mindful of resource limits: instruction counts, memory usage, and execution time. Optimize your code to stay within requested limits to avoid failures and minimize costs.

• Max Instructions: 100 billion per execution (fuel metering enforced)
• Max Execution Time: 60 seconds per execution
• Max Memory: Configurable up to platform limits
• Output Size: Must be ≤900 bytes (NEAR limit)

Testing Locally#

Option 1: Test Compiler Script (Quick Compilation Test)

Use test_compiler.sh to test compilation of your GitHub repository locally without running the full worker infrastructure. This script uses the same Docker image (zavodil/wasmedge-compiler:latest with Rust 1.85) and compilation logic as the production worker.

# Test compilation for WASI Preview 1
./scripts/test_compiler.sh \
  https://github.com/zavodil/random-ark main wasm32-wasip1

# Test compilation for WASI Preview 2
./scripts/test_compiler.sh \
  https://github.com/zavodil/ai-ark main wasm32-wasip2

# Custom output file
./scripts/test_compiler.sh \
  https://github.com/user/myproject main wasm32-wasip1 myapp.wasm

# The script will:
# 1. Pull zavodil/wasmedge-compiler:latest Docker image (instant if already up to date)
# 2. Clone your repository and checkout the commit
# 3. Run cargo build with the exact same flags as worker
# 4. Optimize WASM (wasm-opt for P1, wasm-tools for P2)
# 5. Output compiled WASM with SHA256 checksum

Key features:

• Uses official Docker image from Docker Hub (no local builds needed)
• Exactly mirrors worker compiler behavior
• Supports all three targets: wasm32-wasip1, wasm32-wasip2, wasm32-wasi
• Shows compilation time, file size, and SHA256 checksum
• Configurable memory/CPU limits via environment variables

Option 2: WASI Test Runner (Full Validation)

We provide wasi-test-runner - a universal test tool that validates your WASM modules for OutLayer compatibility. It tests binary format, fuel metering, I/O handling, resource limits, JSON validation, and output size.

# Install test runner
cd wasi-examples/wasi-test-runner
cargo build --release

# Test your WASM module
./target/release/wasi-test \
  --wasm path/to/your-app.wasm \
  --input '{"test":"data"}' \
  --verbose

# Example output:
# ✓ Detected: WASI Preview 1 Module
# ✅ Execution successful!
# 📊 Fuel consumed: 456789 instructions
# 📤 Output: {"result":"success"}
# ✅ All checks passed!

What it validates:

• Binary format (WASI P1 or P2)
• Fuel metering (instruction counting)
• Input/output handling (stdin → stdout)
• Resource limits enforcement
• JSON validation
• Output size limits (<900 bytes)

Option 3: Manual Testing with wasmtime

Test directly using wasmtime:

# Install wasmtime
curl https://wasmtime.dev/install.sh -sSf | bash

# Test WASI P1 binary
echo '{"value":21}' | wasmtime your-app.wasm

# Test WASI P2 component
echo '{"prompt":"test"}' | wasmtime your-app.wasm

# Test with environment variables
echo '{"message":"test"}' | wasmtime --env SECRET=my-key your-app.wasm

Common Pitfalls#

Next Steps#

• Explore working examples with complete source code and deployment guides
• Read the complete WASI tutorial
• Clone examples: git clone https://github.com/fastnear/near-outlayer.git
• Test your WASM locally with wasmtime before deploying
• Start with random-ark or echo-ark for simple use cases
• Use ai-ark or oracle-ark for HTTPS-based applications
• Study private-dao-ark for advanced cryptography (ECIES, HKDF, Merkle trees) and privacy patterns
• Deploy captcha-ark for full-stack async human verification