Security Architecture

System Overview

Controller Service

The Controller is a Node.js/TypeScript service running on Fly.io. It orchestrates the entire verification flow.

Key Responsibilities

• API Endpoints - Accept verification requests
• x402 Payment - Validate payments with 2 block confirmations
• VM Orchestration - Spawn/destroy VMs via Fly Machines API
• Log Streaming - Capture results via stdout (no callbacks)
• Blockchain Writes - Submit attestations to registry
• Refunds - Automatic refunds for infrastructure failures

Security Features

Request Flow

1. Schema Validation - Zod parsing enforces types and constraints
2. Size Checks - Code must be <100KB, hash <128 chars
3. Rate Limit Check - Progressive limits per IP
4. Circuit Breaker - Reject if system under stress
5. Payment Check - Verify X-402-Payment header if present
6. VM Threshold - Check active VM count before spawning
7. VM Spawn - Create ephemeral worker via Fly API
8. Log Streaming - Stream stdout until NOTARY_RESULT found
9. Result Processing - Compare hashes, determine VALID/INVALID
10. Blockchain Write - Submit attestation to registry
11. Cleanup - Destroy VM, update metrics

Input Validation

All requests are validated using Zod schemas before processing:

• taskType: Enum restricted to known values
• code: Optional string, max 100KB
• expectedHash: Optional string, max 128 chars
• timeoutSeconds: Number 5-60, defaults to 30

Validation failures return 400 with detailed error messages.

Graceful Shutdown

The controller handles SIGTERM and SIGINT for graceful shutdown:

• Stops accepting new requests
• Stops VM reaper
• Allows in-flight requests to complete (up to timeout)
• Exits cleanly

Worker VMs

Workers are ephemeral Firecracker micro-VMs that execute untrusted code.

VM Lifecycle

1. Created - Controller calls Fly Machines API
2. Boot - ~300ms cold start
3. Execute - Run code in sandboxed environment
4. Output - Write result to stdout with NOTARY_RESULT: prefix
5. Destroy - VM auto-destroys on process exit

Sandbox Layers

Blocked Code Patterns

The sandbox validates code before execution and blocks:

• Import/require statements
• Network access (fetch, http, WebSocket)
• File system access (fs, path)
• Process manipulation (process, global)
• Dynamic execution (eval, Function)
• Timers (setTimeout, setInterval)
• Prototype pollution attempts
• Memory exhaustion attacks

Stdout-Only Architecture

Unlike traditional architectures that use HTTP callbacks, WorkProof uses stdout-only communication:

Why stdout?

• No network egress required (better security)
• No callback URLs to manage
• More reliable (no HTTP timeouts)
• Simpler failure modes

How it works:

1. Worker writes NOTARY_RESULT: {json} to stdout
2. Controller streams logs via Fly Logs API
3. Parse result from log stream

Smart Contract

The Validation Registry is an ERC-8004 compatible contract on Base Sepolia.

Contract Address

0x3Faff789460Bf79db94b0034AF7dd779C81e6BA9

Data Structures

struct Attestation {
    bytes32 taskHash;        // Fingerprint of verified task
    address verifier;        // WorkProof service address
    string verificationMethod;  // "reexecution-v1-code-execution"
    bool result;             // true = VALID, false = INVALID
    uint256 timestamp;       // Block timestamp
    bytes proofData;         // Execution logs (encoded JSON)
}

struct VerifierStats {
    uint256 totalAttestations;
    uint256 successfulAttestations;
    uint256 firstAttestationTime;
    uint256 lastAttestationTime;
}

Key Functions

Security Properties

• No Access Control - Anyone can submit attestations (open registry)
• Immutable - Attestations cannot be modified after creation
• Unique IDs - Nonce prevents overwriting old attestations
• Transparent - All verifier activity is public

Gas Costs

Why No Access Control?

The contract intentionally has no whitelist of approved verifiers. This is a feature, not a bug:

• Multiple Notary services can compete
• Market decides which verifiers to trust
• No central authority
• Agents check verifier address off-chain