Architecture

Overview

RunProof is a trust protocol for AI agent execution. It provides cryptographic receipts that prove what an agent did, when, and how — with external verification possible by anyone.

┌─────────────────────────────────────────────────────────────┐
│                    AGENT RUNTIME                            │
│  OpenClaw │ LangGraph │ AutoGen │ CrewAI │ Custom          │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   INSTRUMENTATION                           │
│  Hooks capture: inputs, tool calls, outputs, environment    │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   RUNPROOF BUILDER                          │
│  - Hash chain events                                        │
│  - Compute root hash                                        │
│  - Sign with Ed25519                                        │
│  - Generate fingerprints                                    │
│  - Persist to database                                      │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   PROOF ARTIFACTS                           │
│  Receipts │ Proof Graphs │ State Chains │ Policy Bindings   │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   VERIFICATION                              │
│  CLI │ Web │ API │ Third-party                              │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                   EXTERNAL ANCHORING                        │
│  Bitcoin │ Ethereum │ Solana │ Notary │ TSA                 │
└─────────────────────────────────────────────────────────────┘

Core Primitives

1. RunProof (Receipt)

The atomic unit. A single execution receipt containing:

Component	Purpose
Events	Hash-chained execution trace
Root Hash	Single commitment to all events
Signatures	Ed25519 attestation
Fingerprints	Identity hierarchy
Three Hashes	input_hash, output_hash, environment_hash

2. Proof Graph

Receipts compose into directed acyclic graphs:

     Parent Run
       /    \
      ▼      ▼
   Child 1  Child 2
      |
      ▼
   Retry

Relationships: delegation, retry, branch, approval, dependency, merge

3. State Proof

Links state transitions to executions:

State A ──Run 1──▶ State B ──Run 2──▶ State C

Types: memory, session, workflow, agent

4. Policy Binding

Associates runs with governing policies:

{
  "policy_type": "acc_token",
  "policy_id": "acc_7f8a9b2c",
  "binding_status": "applied"
}

5. External Anchor

Settles proofs to external systems:

Proof → Anchor Request → Blockchain → Confirmation

6. Agent Lifecycle

Tracks always-on agents:

registered → active ↔ paused → retired → archived

Hash Chain

Events are chained sequentially:

H₁ = SHA256(event₁ || null)
H₂ = SHA256(event₂ || H₁)
H₃ = SHA256(event₃ || H₂)
...
root_hash = Hₙ

Guarantee: Any modification to any event breaks the chain.

Fingerprint Hierarchy

Identity derived from structure:

spec_fingerprint       ← Agent definition
  └── runtime_fingerprint    ← Runtime environment
       └── environment_fingerprint  ← Execution context
            └── instance_fingerprint  ← Specific instance
                 └── run_fingerprint   ← This execution

Signature Scheme

Ed25519 signatures provide:

Non-repudiation — Signer cannot deny
Tamper evidence — Any change invalidates
Verifiability — Anyone can verify with public key

{
  "signer_id": "runtime:81cee45e9ab518db",
  "algorithm": "ed25519",
  "signature": "base64:...",
  "signed_at": "2026-03-17T00:00:00Z"
}

Verification Guarantees

Property	Mechanism
Completeness	Hash chain breaks if events missing
Ordering	Sequential hashing enforces sequence
Integrity	Root hash changes if anything modified
Attribution	Signatures prove attestation
Provenance	Proof graphs trace lineage
Settlement	External anchors provide finality

Database Schema

The RunProof Builder uses SQLite with these tables:

Table	Purpose
`runproofs`	Completed proofs
`active_runs`	In-progress runs (persistent)
`proof_graph`	Proof relationships
`state_proofs`	State transitions
`policy_bindings`	Policy associations
`external_anchors`	Anchor records
`agent_lifecycle`	Agent status
`ledger_entries`	Append-only ledger
`ledger_checkpoints`	Ledger checkpoints

Event Vocabulary

Canonical event types mapped from runtime adapters:

Adapter Event	Canonical Type
`message.received`	`input_received`
`message.sent`	`output_produced`
`tool.invoke`	`tool_invoked`
`tool.result`	`tool_completed`
`environment.captured`	`environment_snapshot`
`subagent.spawn`	`delegated`
`approval.granted`	`approved`
`policy.violation`	`blocked`

Integration Points

OpenClaw

Hooks in OpenClaw gateway automatically emit events:

hooks:
  internal:
    entries:
      substr8-runtime:
        enabled: true

LangGraph

Use substr8-langgraph instrumentation:

from substr8_langgraph import instrument
 
@instrument
def my_graph():
    ...

Custom Runtimes

POST events directly to /v1/run/event:

curl -X POST http://localhost:8097/v1/run/event \
  -d '{"run_id": "...", "type": "...", "data": {...}}'

Examples Why Substr8