Installation#

Add the crate to your Cargo.toml:

[dependencies]
outlayer = "0.1"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

Published at crates.io/crates/outlayer. Build with the wasm32-wasip2 target:

rustup target add wasm32-wasip2
cargo build --target wasm32-wasip2 --release

When Do You Need the SDK?#

In short: if your WASI app needs persistent storage or structured access to execution context, use the SDK. For stateless computation (like API calls, random numbers, weather data), you can use plain Rust with stdin/stdout.

Environment Module (outlayer::env)#

Access execution context: who called you, what input they sent, and environment variables (including secrets).

Caller Context#

use outlayer::env;

// Who initiated the execution
let signer = env::signer_account_id();     // e.g., Some("alice.near")
let predecessor = env::predecessor_account_id(); // e.g., Some("token.near")
let tx_hash = env::transaction_hash();
let request_id = env::request_id();

Input / Output#

use outlayer::env;
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct Request { action: String }

#[derive(Serialize)]
struct Response { result: String }

fn main() {
    // Read JSON input from stdin
    let req: Request = match env::input_json() {
        Ok(Some(r)) => r,
        _ => return env::output_string("No valid input"),
    };

    // Write JSON output to stdout
    env::output_json(&Response {
        result: format!("Got action: {}", req.action),
    }).ok();
}

Environment Variables#

Secrets stored via the dashboard are injected as environment variables. You can read them with env::var() or std::env::var():

// SDK helper
let api_key = outlayer::env::var("OPENAI_API_KEY");

// Standard library (also works)
let api_key = std::env::var("OPENAI_API_KEY").ok();

Storage Module (outlayer::storage)#

Persistent encrypted key-value storage that survives across executions. Storage is automatically isolated per caller — alice.near cannot read bob.near's data.

Basic Operations#

use outlayer::storage;

// String convenience methods
storage::set_string("greeting", "hello")?;
let val = storage::get_string("greeting")?; // Some("hello")

// JSON convenience methods
storage::set_json("config", &my_config)?;
let config: MyConfig = storage::get_json("config")?.unwrap();

// Binary data
storage::set("data", &bytes)?;
let data = storage::get("data")?;

// Check existence and delete
if storage::has("key") {
    storage::delete("key");
}

// List keys by prefix
let keys = storage::list_keys("user:")?;

// Clear all data for current caller
storage::clear_all()?;

Atomic Operations#

For concurrent-safe operations (e.g., counters, voting):

// Atomic counter
let new_count = storage::increment("visits", 1)?;  // Returns new value
let new_count = storage::decrement("credits", 10)?;

// Insert only if key doesn't exist (mutex-like)
let inserted = storage::set_if_absent("lock", b"held")?;

// Compare-and-swap
let (success, old) = storage::set_if_equals(
    "version", b"v1", b"v2"
)?;

Worker Storage (Shared Across Users)#

Worker storage is shared across all callers and accessible only from within the WASI module. Use it for global state like price feeds, configuration, or cached data.

// Encrypted worker storage (default)
storage::set_worker("cache:key", &data)?;
let cached = storage::get_worker("cache:key")?;

// Public (unencrypted) worker storage — readable by other projects
storage::set_worker_with_options("oracle:ETH", &price, Some(false))?;

// Read public data from another project
let price = storage::get_worker_from_project(
    "oracle:ETH",
    Some("p0000000000000042"),  // target project UUID
)?;

Version Migration#

When upgrading your WASM binary, data from the previous version is accessible via its hash:

// Read data from a previous version
let old_data = storage::get_by_version("key", "abc123...")?;

// Clean up old version data after migration
storage::clear_version("abc123...")?;

Examples Using the SDK#

Minimal Project Template#

Cargo.toml#

[package]
name = "my-outlayer-app"
version = "0.1.0"
edition = "2021"

[[bin]]
name = "my-outlayer-app"
path = "src/main.rs"

[dependencies]
outlayer = "0.1"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"

[profile.release]
opt-level = "s"
lto = true
strip = true

src/main.rs#

use outlayer::{env, storage};
use serde::{Deserialize, Serialize};

#[derive(Deserialize)]
struct Request {
    action: String,
}

#[derive(Serialize)]
struct Response {
    count: i64,
    message: String,
}

fn main() {
    let req: Request = match env::input_json() {
        Ok(Some(r)) => r,
        _ => return env::output_string("No valid input"),
    };

    match req.action.as_str() {
        "increment" => {
            let count = storage::increment("counter", 1)
                .unwrap_or(0);
            env::output_json(&Response {
                count,
                message: format!("Counter incremented by {}",
                    env::signer_account_id().unwrap_or_default()),
            }).ok();
        }
        "get" => {
            let val = storage::get_string("counter")
                .ok().flatten()
                .and_then(|s| s.parse::<i64>().ok())
                .unwrap_or(0);
            env::output_json(&Response {
                count: val,
                message: "Current count".into(),
            }).ok();
        }
        _ => env::output_string("Unknown action"),
    }
}

# Build
cargo build --target wasm32-wasip2 --release

# Output: target/wasm32-wasip2/release/my-outlayer-app.wasm

API Reference#

outlayer::env#

outlayer::storage#

Storage Types Overview#