What are Projects?#

A Project is a container for WASM code versions with shared resources:

• Versioning: Deploy multiple versions, switch active version anytime
• Persistent Storage: Data survives version updates (same encryption key)
• Project Secrets: Secrets accessible by all versions of the project
• Storage Deposit: Pay for on-chain storage, refunded when deleted

Project ID Format#

Each project has a unique ID composed of the owner account and project name:

{owner_account_id}/{project_name}

Examples:
  alice.near/my-app
  bob.testnet/weather-bot
  mycompany.near/trading-oracle

Project names must be alphanumeric with dashes and underscores only (pattern: [a-zA-Z0-9_-]+).

Creating a Project#

Create projects via the Projects Dashboard:

1. Go to /projects
2. Click "New Project"
3. Enter project name
4. Select code source (GitHub repo or WASM URL)
5. Click "Create Project"

How Project Binding Works#

When you execute code via a project, the contract automatically binds your WASM to the project context. You don't need to declare the project in your code — the binding is enforced by the contract.

use outlayer::storage;

fn main() {
    // Storage automatically uses your project context
    // The contract passes project_uuid to the worker
    storage::set("counter", &42i64.to_le_bytes()).unwrap();

    if let Some(data) = storage::get("counter").unwrap() {
        let value = i64::from_le_bytes(data.try_into().unwrap());
        println!("Counter: {}", value);
    }
}

How it works:

• You call request_execution(Project { project_id })
• Contract looks up the project and resolves the CodeSource (GitHub or WasmUrl)
• Contract sends project_uuid to the worker
• Worker uses project_uuid for storage namespace and encryption

Project Environment Variables#

Your WASM code can access project information via environment variables:

// Access project info in your WASM code
let project_id = std::env::var("OUTLAYER_PROJECT_ID").ok();
let owner = std::env::var("OUTLAYER_PROJECT_OWNER").ok();
let name = std::env::var("OUTLAYER_PROJECT_NAME").ok();

// Example: "zavodil2.testnet/my/nested/app"
// owner = "zavodil2.testnet"
// name = "my/nested/app"  (split by first "/" only)

Storage Security Model#

How does OutLayer ensure that a malicious WASM cannot access another project's storage?

The Security Chain

Key Security Properties

Attack Scenarios (Why They Fail)

Managing Versions#

Each project can have multiple versions. The active version is used for new executions by default.

Adding a Version#

In the Projects dashboard, expand your project and click "Add Version". You can choose to make it active immediately or keep the current active version.

Switching Active Version#

Click the checkmark icon on any version to make it active. The currently active version cannot be removed.

Executing a Specific Version#

By default, executions use the active version. But you can execute any specific version using the version_key parameter. This is useful for testing new versions before making them active.

// Contract call: request_execution
{
  "code_source": {
    "Project": {
      "project_id": "alice.near/my-app",
      "version_key": "zavodil/[email protected]"  // Optional: specific version
    }
  },
  "input_data": "...",
  "resource_limits": { ... }
}

// If version_key is omitted, the active version is used

Persistent Storage#

All versions of a project share the same storage namespace. Data written by v1 is readable by v2. Storage is encrypted using the keystore TEE and isolated per user.

Project Secrets#

Secrets can be bound to a project, making them accessible by all versions. See Secrets Documentation for details on creating and managing project secrets.

Use Cases#

Best Practices#

• Use WASI Preview 2 (wasm32-wasip2) build target for storage support
• Use descriptive project names that reflect functionality
• Tag your git commits (e.g., v1.0.0) before adding versions
• Test new versions via version_key before setting as active
• Keep at least one known-good version as fallback
• Use project secrets for shared credentials instead of repo-based secrets
• Document your storage key format for data migrations
• Use key prefixes (e.g., user:alice:) for organization
• Use increment/decrement for counters instead of get+set (race-safe)
• Use set_if_absent for one-time initialization to avoid overwriting