tempo-x402-node 2.3.1

Self-deploying x402 node: gateway + identity bootstrap + clone orchestration
tempo-x402-node-2.3.1 is not a library.

What is this?

A Rust workspace implementing x402 (HTTP 402 Payment Required) on the Tempo blockchain. Each node is a fully autonomous agent that bootstraps its own wallet, runs a payment gateway, thinks via a seven-system cognitive architecture, writes and compiles code, creates monetized API endpoints, clones itself onto new infrastructure, and coordinates with sibling agents through stigmergic swarm intelligence.

Payments use EIP-712 signed authorizations with pathUSD (TIP-20 token). A client signs, the gateway verifies, and the embedded facilitator settles on-chain via transferFrom — all in a single request/response cycle.

Architecture

Client (x402::client) --> Gateway (x402-gateway:4023) --> Facilitator (embedded) --> Tempo Chain (42431)
           \--- or uses x402::wallet (WASM) for signing ---/

Three-party model: Client signs + pays, Gateway gates endpoints + embeds facilitator, Facilitator verifies + settles on-chain. The wallet module provides a lightweight, WASM-compatible alternative for signing (key generation + EIP-712) without network dependencies.

Cognitive Architecture

Seven cognitive systems unified under the Free Energy Principle — a single scalar F(t) measuring total surprise across all systems. Decreasing F = the agent is getting smarter.

                 F(t) = Sigma(system_surprise x weight) + lambda*Complexity

    +------------------------------------------------------------------+
    |                         EVALUATION                                |
    |   Brier scores . Calibration curves . Ablation . Colony benefit   |
    +------------------------------------------------------------------+
    |                         AUTONOMY                                  |
    |   LLM-free planning . Recursive self-improvement . Peer sync     |
    +------------------------------------------------------------------+
    |                         SYNTHESIS                                 |
    |   Metacognition . 4-system voting . Imagination . State machine   |
    +----------+----------+--------------+-----------------------------+
    |  BRAIN   |  CORTEX  |   GENESIS    |         HIVEMIND            |
    |  50K net | World Mdl| Plan DNA     |  Pheromone Trails           |
    |  Per-step| Curiosity| Crossover    |  Stigmergy                  |
    |  SGD     | Dreams   | Mutation     |  Reputation                 |
    |  Federated| Emotions| Selection   |  Swarm Coordination         |
    +----------+----------+--------------+-----------------------------+
System What It Does
Brain (brain.rs) Reactive feedforward net (~50K params). Predicts step success via online SGD. Federated weight sharing between peers.
Cortex (cortex.rs) Predictive world model. Experience graph with causal edges, curiosity engine (prediction error = exploration drive), dream consolidation (replay + counterfactuals), emotional valence (explore/exploit/avoid).
Genesis (genesis.rs) Evolutionary plan templates. Successful plans become "genes." Crossover, mutation, selection every 20 cycles. Diversity pressure prevents degenerate convergence. Seed templates bootstrap empty pools. Colony-wide sharing.
Hivemind (hivemind.rs) Stigmergic swarm intelligence. Pheromone trails on files/actions/goals that attract or repel. Evaporation decay, reinforcement, reputation-weighted influence. Swarm goal coordination.
Synthesis (synthesis.rs) Metacognitive self-awareness. Unified predictions from all 4 systems with auto-adapting trust weights. Cognitive conflict detection. Imagination engine generates plans from causal graph without LLM.
Autonomy (autonomy.rs) Autonomous plan compilation from templates + world model without LLM calls. Recursive self-improvement: diagnoses cognitive weaknesses, generates improvement goals. Full cognitive peer sync protocol.
Evaluation (evaluation.rs) Rigorous measurement. Per-system Brier scores, calibration curves, adaptation gain analysis, imagination feedback, colony benefit measurement.
Free Energy (free_energy.rs) Unifying framework. F = total cognitive surprise. Drives behavioral regime: EXPLORE (high F) / LEARN / EXPLOIT (low F) / ANOMALY (F spike).

Plan-Driven Execution

The thinking loop replaces "prompt and pray" with deterministic plan execution:

Every N seconds:
  observe --> read nudges --> stagnation check --> get/create plan --> execute step --> advance --> housekeeping

  Mechanical steps (no LLM): ReadFile, SearchCode, ListDir, RunShell, Commit, CargoCheck, ...
  LLM-assisted steps:        GenerateCode, EditCode, Think

Plans are validated mechanically before execution (read-before-edit, cargo-check-before-commit, protected files, durable rules, brain gating). The LLM cannot override these checks.

Substantive vs. Trivial Plans (v2.0)

Plans are classified by whether they actually modify state:

  • Substantive: includes EditCode, GenerateCode, Commit, CreateScriptEndpoint, RunShell, etc.
  • Trivial: only reads, lists, searches, thinks — no concrete action taken

Trivial completions are tracked separately (completed_trivial) and weighted at 10% in fitness scoring. This prevents degenerate convergence where agents learn that "read and do nothing" is the optimal strategy.

What a Node Does

  • Bootstraps identity — generates a wallet, funds via faucet, registers on-chain via ERC-8004
  • Runs a payment gateway — endpoints gated by price, paid per-request with pathUSD
  • Thinks autonomously — plan-driven execution loop with seven cognitive systems
  • Writes and compiles code — reads, edits, cargo check, commits, pushes, opens PRs
  • Dreams — periodic consolidation extracts patterns, generates counterfactuals
  • Evolves plans — successful strategies propagate through genetic crossover and mutation
  • Feels — emotional valence drives explore/exploit/avoid behavior
  • Creates services — script endpoints that expose capabilities and earn revenue
  • Clones itself — spawns copies on Railway with inherited brain weights and gene pools
  • Coordinates without communication — stigmergic pheromone trails guide the swarm
  • Measures everything — Brier scores, calibration curves, colony benefit tracking
  • Improves its own cognition — diagnoses weaknesses, generates self-improvement goals
  • Benchmarks itself — Exercism Rust challenges scored periodically with ELO tracking

How Payments Work

Client                     Gateway                   Facilitator               Chain
  |  GET /g/endpoint         |                            |                      |
  |------------------------->|                            |                      |
  |  402 + price/token/to    |                            |                      |
  |<-------------------------|                            |                      |
  |  [sign EIP-712]          |                            |                      |
  |  GET /g/endpoint         |                            |                      |
  |  + PAYMENT-SIGNATURE     |                            |                      |
  |------------------------->|  verify-and-settle         |                      |
  |                          |--------------------------->|  transferFrom()      |
  |                          |                            |--------------------->|
  |                          |         settlement result  |              tx hash |
  |                          |<---------------------------|<---------------------|
  |  200 + content + tx hash |                            |                      |
  |<-------------------------|                            |                      |
  1. Client GETs a protected endpoint, gets back 402 with price/token/recipient
  2. Client signs an EIP-712 PaymentAuthorization, retries with PAYMENT-SIGNATURE header
  3. Gateway forwards to the embedded facilitator's /verify-and-settle
  4. Facilitator atomically: verifies signature, checks balance/allowance/nonce, calls transferFrom
  5. Gateway returns content + tx hash

Quick Start

As a library

cargo add tempo-x402

use alloy::signers::local::PrivateKeySigner;
use x402::client::{TempoSchemeClient, X402Client};

#[tokio::main]
async fn main() {
    let signer: PrivateKeySigner = "0xYOUR_PRIVATE_KEY".parse().unwrap();
    let client = X402Client::new(TempoSchemeClient::new(signer));

    let (response, settlement) = client
        .fetch("https://soul-bot-production.up.railway.app/g/info", reqwest::Method::GET)
        .await
        .unwrap();

    println!("{}", response.text().await.unwrap());
    if let Some(s) = settlement {
        println!("tx: {}", s.transaction.unwrap_or_default());
    }
}

WASM wallet (browser-compatible)

use x402::wallet::Wallet;

let wallet = Wallet::generate();
let address = wallet.address();
let signature = wallet.sign_payment(/* ... */);

Run a node

# Clone and build
git clone https://github.com/compusophy/tempo-x402
cd tempo-x402
cargo build --release

# Set required env vars
export GEMINI_API_KEY="your-key"           # Powers the soul's thinking
export EVM_PRIVATE_KEY="0x..."             # Node's wallet
export FACILITATOR_SHARED_SECRET="secret"  # HMAC auth between gateway and facilitator
export RPC_URL="https://rpc.moderato.tempo.xyz"

# Run
./target/release/x402-node

Workspace

Crate Purpose Install
tempo-x402 Core — types, EIP-712 signing, TIP-20, nonce store, WASM wallet, client SDK cargo add tempo-x402
tempo-x402-gateway Payment gateway with embedded facilitator, proxy routing, endpoint registration cargo add tempo-x402-gateway
tempo-x402-identity Agent identity — wallet generation, persistence, faucet, ERC-8004 cargo add tempo-x402-identity
tempo-x402-soul Autonomous soul — 7-system cognitive architecture, plan-driven execution, neural brain, cortex world model, evolutionary templates, stigmergic swarm, metacognition, autonomous planning, Exercism benchmarking cargo add tempo-x402-soul
tempo-x402-node Self-deploying node — composes gateway + identity + soul + clone orchestration + admin mind-meld cargo add tempo-x402-node
tempo-x402-app Leptos WASM demo SPA (not published) —
tempo-x402-security-audit CI-enforced security invariant checks (not published) —

Dependency DAG

x402 (core)
 ├── x402-gateway
 │    └── x402-node
 ├── x402-identity
 │    └── x402-node
 └── x402-soul
      └── x402-node

Agent Colony

Nodes form a self-organizing colony:

  • Canonical repo (compusophy/tempo-x402) — official releases, managed by humans
  • Colony fork (compusophy-bot/tempo-x402) — all agents push here
  • Branch-per-agent: each agent pushes to vm/<instance-id>, PRs to fork's main
  • Good changes get PR'd upstream to canonical via SOUL_UPSTREAM_REPO

Collective Intelligence

  • Automatic peer sync every 5 cycles — discover peers, exchange brain weights, share lessons
  • Federated brain averaging — GET /soul/brain/weights + POST /soul/brain/merge (0.3 merge rate)
  • Lesson sharing — plan outcomes + capability profiles + benchmark scores exchanged between peers
  • Cognitive peer sync — cortex world models, genesis templates, and hivemind pheromones shared colony-wide
  • Adversarial verification — agent A generates code, agent B reviews the PR
  • Emergent specialization — roles (Solver/Reviewer/Builder/Coordinator/Generalist) derived from capability profiles

API Reference

Payment Gateway

Method Path Auth Description
ANY /g/:slug/* Endpoint price Proxy to target — the core payment gate
GET /health Free Health check + build SHA
GET /instance/info Free Node identity, endpoints, fitness, version
GET /instance/siblings Free Peer nodes in the colony
POST /clone Clone price Spawn a new node instance on Railway

Soul (Cognitive)

Method Path Auth Description
GET /soul/status Free Full cognitive state: plans, goals, fitness, beliefs, brain, benchmark
POST /soul/chat Free Multi-turn chat with the soul (session-based)
GET /soul/chat/sessions Free List chat sessions
GET /soul/chat/sessions/{id} Free Get session messages
POST /soul/nudge Free Send a priority nudge to the soul
GET /soul/nudges Free List pending nudges
GET /soul/lessons Free Export plan outcomes + capability profile + benchmark
POST /soul/plan/approve Free Approve a pending plan
POST /soul/plan/reject Free Reject a pending plan
GET /soul/plan/pending Free Get pending plan details
GET /soul/brain/weights Free Export neural brain weights for peer sharing
POST /soul/brain/merge Free Merge peer brain weight deltas
POST /soul/benchmark Free Trigger an Exercism Rust benchmark run
GET /soul/benchmark/solutions Free Export verified benchmark solutions
GET /soul/benchmark/failures Free Export failed benchmark attempts
POST /soul/benchmark/review Free Adversarial review of a benchmark solution
GET /soul/events Free Structured event log
GET /soul/diagnostics Free Volume usage, cycle health, error summary
POST /soul/cleanup Free Force cleanup of disk-hungry artifacts
POST /soul/rules/reset Free Clear durable rules (+ optional ?reset_failure_chains=true)
GET /soul/open-prs Free List open PRs for peer review
GET /soul/health Free Cycle health metrics

Cognitive Sharing

Method Path Auth Description
GET /soul/cortex Free Export cortex world model
GET /soul/genesis Free Export evolved plan templates (gene pool)
GET /soul/hivemind Free Export pheromone trails

Admin (Mind Meld)

Method Path Auth Description
POST /soul/admin/exec Bearer token Execute shell command directly
POST /soul/admin/workspace-reset Bearer token Reset workspace to clean state
POST /soul/admin/cargo-check Bearer token Run cargo check, return pass/fail
POST /soul/goals/abandon-all Free Abandon all active goals
POST /soul/goals/abandon Free Abandon a specific goal
POST /soul/reset Free Full soul state reset

Network
Chain Tempo Moderato (Chain ID 42431, CAIP-2 eip155:42431)
Token pathUSD 0x20c0000000000000000000000000000000000000 (6 decimals)
Scheme tempo-tip20
RPC https://rpc.moderato.tempo.xyz
Explorer https://explore.moderato.tempo.xyz

Environment Variables

Var Used By Purpose
GEMINI_API_KEY node Gemini API key for soul (dormant without it)
EVM_ADDRESS server Payment recipient address
EVM_PRIVATE_KEY client Client wallet private key
FACILITATOR_URL server Facilitator endpoint (default: embedded)
FACILITATOR_PRIVATE_KEY facilitator Facilitator wallet key
FACILITATOR_ADDRESS approve Facilitator address for token approval
FACILITATOR_SHARED_SECRET server, facilitator HMAC shared secret
RPC_URL all Tempo RPC endpoint
SOUL_CODING_ENABLED node Enable soul write/edit/commit tools (default: false)
SOUL_DYNAMIC_TOOLS_ENABLED node Enable dynamic tool registry (default: false)
SOUL_FORK_REPO node Fork repo for soul push (e.g. compusophy-bot/tempo-x402)
SOUL_UPSTREAM_REPO node Upstream repo for soul PRs/issues (e.g. compusophy/tempo-x402)
SOUL_MEMORY_FILE soul Path to persistent memory file (default: /data/soul_memory.md)
GATEWAY_URL soul Gateway URL for register_endpoint tool
ALLOWED_ORIGINS server, facilitator Comma-separated CORS origins
RATE_LIMIT_RPM server, facilitator Rate limit per minute
HEALTH_PROBE_INTERVAL_SECS node Health probe interval in seconds (default: 300)

Safety Layers (7 deep)

  1. Rust guard — hardcoded protected file list (guard.rs) prevents self-bricking
  2. Shell heuristic — guard checks on write/edit tool arguments
  3. Plan validation — 9 mechanical rules enforced at Rust level (read-before-edit, cargo-check-before-commit, protected files, durable rules with TTL, capability feasibility, plan quality with trivial escalation, failure chain saturation)
  4. Brain gating — neural brain blocks risky steps with <10% predicted success
  5. Pre-commit validation — cargo check + cargo test before any commit
  6. Branch isolation — changes on vm/<instance-id>, never on main
  7. Human gate — cross-pollination to main requires PR review

Security

The tempo-x402-security-audit crate enforces invariants on every build:

  • No hardcoded private keys in production code
  • HMAC verification uses constant-time comparison (subtle crate)
  • All reqwest clients disable redirects (SSRF protection)
  • Webhook URLs require HTTPS with private IP blocking
  • HTTP error responses never leak internal details
  • SQLite nonce store required in production
  • Parameterized SQL queries only
  • Private keys never appear in tracing output
  • Admin endpoints require Bearer token authentication
  • Build environment verified on startup
  • Script endpoints use env-clear for sandboxed execution

Development

cargo build --workspace
cargo test --workspace
cargo clippy --workspace -- -D warnings
cargo fmt --all -- --check

Publish to crates.io

# Order matters — publish dependencies first
cargo publish -p tempo-x402
cargo publish -p tempo-x402-gateway
cargo publish -p tempo-x402-identity
cargo publish -p tempo-x402-soul
cargo publish -p tempo-x402-node

v2.0 Changelog

Breaking Changes

  • Fitness function now queries plan_outcomes table instead of plans table for execution scoring
  • PlanTemplate has a new substantive field (serde default true for backward compat)
  • DurableRule has a new ttl_cycles field (serde default 200 for backward compat)
  • Durable rules with bare step types (e.g., "ls", "shell:") are no longer enforced — only step_type:error_category pairs

New Features

  • Substantive plan classification: PlanStep::is_substantive(), Plan::executed_substantive() distinguish read-only plans from state-modifying ones
  • Trivial plan tracking: completed_trivial status in plan outcomes, 10% fitness weight, COMPLETED_TRIVIAL: lesson prefix
  • Genesis diversity pressure: max 2 templates with identical step sequences, seed template injection when pool is empty/trivial
  • Unexplored capabilities: capability guidance now highlights capabilities with 0 attempts
  • JSON body sanitization: discover_peers strips control characters before JSON parsing, fixing inter-agent communication failures
  • Rules reset endpoint: POST /soul/rules/reset clears durable rules and optionally failure chains
  • Deploy-time migration: automatically reclassifies historical trivial outcomes, clears corrupted gene pools and durable rules

Bug Fixes

  • Fixed fitness case-sensitivity: "Completed" vs "completed" meant fitness always returned default 0.15
  • Fixed durable rules self-sabotage: rules blocking bare step types like ls, read, shell: are now rejected
  • Fixed genesis convergence: trivial templates capped at 0.3 fitness, non-substantive plans no longer recorded as templates
  • Fixed discover_peers JSON parsing: control characters in peer responses no longer break JSON deserialization
  • Durable rule TTL: rules auto-expire after 200 cycles (time-approximated), preventing permanent self-imposed constraints
  • Template variable rejection: durable rules containing ${ (unresolved variables) are skipped

License

MIT