VEX Protocol (v1.7.0) — Silicon-Seal Handshake & Spec v3.1 Alignment

Governed Execution: Enforcing Trust in Autonomous AI.

VEX Protocol breaks the Self-Authorization Trap where agentic cognition proposes, authorizes, and executes actions in a monolithic silo. By cryptographically separating reasoning from authority, VEX implements a non-bypassable control-plane architecture.

🚀 Live Demo: AI News Verification on Solana - Experience VEX in action with full transparency and blockchain anchoring.

📚 Railway Deployment Guide →

---

Prerequisites

• Rust 1.75+ with Cargo package manager
• Go 1.22+ with the standard toolchain (for attest CLI)
• SQLite 3.35+ (for vex-persist & attest - handled automatically)
• OpenSSL development libraries (for HTTPS support)
• TPM 2.0 / Microsoft CNG (Required for hardware-rooted identity)
• Magpie Compiler (Required for L2 Formal Intent verification)
• Optional: API keys for LLM providers (DeepSeek, OpenAI, Mistral, Ollama)

📚 Full Installation Guide →

---

The Five Primitives of Governed Execution

Primitive	Component	Function
1. Cognition	VEX Agent	Cognitive engines that propose intent-driven actions.
2. Authority	CHORA Gate	External neutral Decision Plane governing continuation.
3. Enforcement	VEX AEM	Mandatory kernel-level gating at the CHORA-VEX boundary.
4. Attestation	Silicon Root	Hardware-rooted identity (TPM/TEE) for Proof of Origin.
5. Custody	Evidence Capsule	JCS-compliant, tamper-proof forensic archival.

---

Why VEX?

Problem	VEX Solution
Self-Authorization	Cryptographic separation of Reasoning vs. Authority
Hallucination	Red/Blue adversarial debate with consensus
Context Overflow	Bio-inspired temporal memory with smart decay
Unauditability	Merkle hash chains with tamper-evident Evidence Capsules
Governed Execution	AGCP v0.9.0 compliance for Layer 4 Control

VEX provides a verification and memory layer designed for production environments that works with any LLM provider.

📚 Full Documentation → | 🔧 API Docs (Swagger) →

---

What's New in v1.7.0 🛡️

• 🔒 Spec v3.1 Handshake — Formal synchronization with the CHORA Gate (v3.1 Runtime) and the VEX-CHORA Handshake v0.1. This enforces mandatory execution_target context binding and high-precision i64 Unix Epoch timestamps.
• 🏗️ AGCP v0.9.0 Reference Implementation — VEX kernel is now strictly aligned with the Automated Governance Control Plane (AGCP) v0.9.0 specification, synchronizing formal safety invariants for autonomous execution.
• ⚡ Hybrid ZK Proving Path — Dual-path support for SHA-256 (Bridge) and M31/Poseidon2 (Native) proving. Enables 1:1 legacy forensic interoperability while targeting sub-100ms proving latency for high-performance reasoning flows.
• 🔮 Shadow Intent STARKs — Definitive E2E flow for Shadow Intent verification via Plonky3 STARKs, enabling verifiable hidden reasoning at the TitanGate boundary.
• 🚥 Full Workspace Synchronization — All 18 crates synchronized to v1.7.0 with 100% repository-wide test success and absolute bit-parity for byte-level serialization between Rust and Python audit suites.

📊 ZK Performance: Bridge vs. Native

Metric	Bridge (SHA-256)	Native (Poseidon2 / M31)
Primary Use	Forensic Industry Standard	High-Performance Target
CPU Hashing	~11,000 ns/iter	~114,000 ns/iter
ZK Proving Cycles	High (Heavy)	Low (Lite)
Status	Production Stable	ZK-Optimized (Circle Field)

---

Quick Start

# Build
cargo build --workspace --release

# Test (85+ tests)
cargo test --workspace

# Run API server
cargo run --release -p vex-api

# CLI tools
cargo run -p vex-protocol-cli -- tools list
cargo run -p vex-protocol-cli -- tools run calculator '{"expression": "2+2"}'

# Tip: After building, use the compiled 'vex' binary directly:
# ./target/release/vex tools list

Environment Variables

# ── Database ──────────────────────────────────────────────────────────────────
# SQLite (default — single node, Railway volume)
export DATABASE_URL="sqlite:vex.db?mode=rwc"

# PostgreSQL (multi-node — Railway Managed DB, horizontal scaling)
export DATABASE_URL="postgres://user:pass@host/vex"
# On Railway, this is injected automatically when you add a Postgres plugin:
# DATABASE_URL = ${{Postgres.DATABASE_URL}}

# ── LLM Providers ─────────────────────────────────────────────────────────────
export DEEPSEEK_API_KEY="sk-..."       # Recommended: High-reasoning deepseek-r1
export OPENAI_API_KEY="sk-..."         # GPT-4o, o1-preview support
export ANTHROPIC_API_KEY="sk-..."      # Claude 3.5 Sonnet support
export MISTRAL_API_KEY="sk-..."        # Mistral Large support
export GROQ_API_KEY="gsk-..."          # Llama-3 (70b/405b) high-speed support
export OLLAMA_URL="http://localhost:11434" # Local inference bridge

# ── Reasoning Engine Config ───────────────────────────────────────────────────
export VEX_DEFAULT_PROVIDER="deepseek" # Options: deepseek, openai, anthropic, mistral, groq, ollama
export VEX_DEFAULT_MODEL="deepseek-reasoner"
export VEX_MAX_DEPTH="5"               # Max chain-of-thought search depth
export VEX_ADVERSARIAL="true"          # Enable Red/Blue adversarial debate
export VEX_LLM_TIMEOUT="60"            # Timeout in seconds for LLM responses
export VEX_DEBUG="false"               # Set to true for verbose tracing of LLM prompts

# ── Auth ──────────────────────────────────────────────────────────────────────
# Generate with: openssl rand -hex 32
export VEX_JWT_SECRET="your-32-character-secret-here"

# ── Rate Limiting (OSS Defaults — override as needed) ─────────────────────────
export VEX_DISABLE_RATE_LIMIT="true"    # Disable entirely (local stress tests)
export VEX_LIMIT_FREE="10"              # req/min for free tier (default: 10)
export VEX_LIMIT_STANDARD="100"         # req/min for standard tier (default: 100)
export VEX_LIMIT_PRO="1000"             # req/min for pro tier (default: 1000)

# ── Sidecar & Formal Verification (TitanGate) ─────────────────────────────────
export MAGPIE_BIN_PATH="/usr/local/bin/magpie" # Path to Magpie executable
export VEX_HARDWARE_ATTESTATION="true"         # Enforce silicon-rooted proofs
export VEX_DEV_MODE="false"                    # Enable stub identity for local testing

# ── Observability (OpenTelemetry) ─────────────────────────────────────────────
# Connect to any OTLP-compatible collector (Grafana, Jaeger, Datadog, etc.)
# Requires building with: cargo build --features vex-api/otel
export OTEL_EXPORTER_OTLP_ENDPOINT="http://your-collector:4317"
export OTEL_SERVICE_NAME="vex-production"
export OTEL_TRACES_SAMPLER_ARG="0.1"    # 10% sampling in production

# ── Production & Networking ───────────────────────────────────────────────────
export VEX_ENV="production"             # Enforces HTTPS & strict identity
export VEX_PORT="8080"                  # Server listening port
export VEX_TIMEOUT_SECS="30"            # API request timeout (graceful reaping)
export VEX_ENFORCE_HTTPS="false"        # Force HTTPS even in dev mode
export VEX_TLS_CERT="/path/to/cert.pem"
export VEX_TLS_KEY="/path/to/key.pem"

Start the Server

# Development (HTTP)
cargo run --release -p vex-api

# Production (HTTPS enforced)
VEX_ENV=production \
VEX_TLS_CERT=./cert.pem \
VEX_TLS_KEY=./key.pem \
cargo run --release -p vex-api

Then visit:

• API Documentation: https://localhost:8080/swagger-ui
• Health Check: https://localhost:8080/health
• Metrics: https://localhost:8080/metrics (Prometheus format)

---

┌─────────────────────────────────────────────────────────────────┐
│  vex-server    │ Production entry point (Railway, Middleware)   │
├────────────────┼────────────────────────────────────────────────┤
│  vex-sidecar   │ Silicon Boundary Proxy (Encapsulates raw -> VEP)│
│  vex-chora     │ Native Bridge to External Neutral Authority    │
│  vex-api       │ HTTPS API, JWT Auth, Tenant Rate Limiting      │
├────────────────┼────────────────────────────────────────────────┤
│  vex-router    │ Intelligent LLM Routing, Semantic Caching      │
│  vex-llm       │ Providers: DeepSeek, Mistral, OpenAI, Groq    │
│  vex-adversarial│ Red/Blue Debate, Consensus, Reflection       │
├────────────────┼────────────────────────────────────────────────┤
│  vex-runtime   │ Agent Orchestrator, Self-Correcting Genome     │
│  vex-queue     │ Async Worker Pool, Job Processing              │
├────────────────┼────────────────────────────────────────────────┤
│  vex-core      │ Agent, Genome, Merkle Tree, Evolution (Rayon) │
│  vex-hardware  │ Silicon-Rooted Identity (TPM 2.0 / CNG)        │
│  vex-algoswitch│ Runtime Algorithm Selection / Pattern Detect   │
├────────────────┼────────────────────────────────────────────────┤
│  vex-temporal  │ Episodic Memory, 5-Horizon Decay               │
│  vex-persist   │ SQLite, Audit Logs, SQLite Vector Store        │
│  vex-anchor    │ External Merkle Anchoring (File/Git/Ethereum)  │
├────────────────┼────────────────────────────────────────────────┤
│  vex-cli       │ Developer Terminal Interface & Admin Tools     │
│  vex-sidecar   │ Silicon Boundary Proxy (VEP Binary Encapsulation)│
│  vex-macros    │ Procedural Codegen for Type-Safe Evolution     │
└────────────────┴────────────────────────────────────────────────┘

---

🗺️ Trust Flow & Orchestration

VEX Protocol is the core component of a multi-layered trust model. Depending on your requirements, it can be deployed in local or cloud configurations.

1. The Governed Execution Stack (Silicon Seal)

VEX orchestrates cognitive intent, formal semantics, and hardware-rooted identity through the AGCP control plane, anchored by the CHORA Witness Network for high-performance external authority.

graph TD
    subgraph "External"
        U[User/App]
        T[External API/Tool]
    end

    subgraph "Agentic Cognition (VEX)"
        C[VEX Agent - LLM]
        M[Magpie - Intent AST]
    end

    subgraph "Governed Control Plane (AGCP v0.9.0)"
        D[Q-PAD - Detection]
        I[QILIS - Interpretability]
        R[PBSAI - Reasoning]
        G[AGCP - Policy Enforcement]
    end

    subgraph "The Silicon Seal (VEX Runtime)"
        A[Attest - TPM/TEE Identity]
        P[Plonky3 - ZK-STARK / M31 Proof]
    end

    subgraph "Authority Network (CHORA)"
        W[CHORA Gate - Merkle Anchor]
    end

    U -->|1. Intent| C
    C -->|2. Formalize| M
    M -->|3. Evaluate| D
    D -->|4. Attribute| I
    I -->|5. Consensus| R
    R -->|6. Constraint Check| G
    G -->|7. Sign| A
    A -->|8. ZK Prove| P
    P -->|9. Anchor| W
    W -->|10. Witness Receipt| G
    G -->|11. Execute Action| T
    T -->|12. Final Capsule| U

Loading

2. The Hybrid Sovereign Flow

Ideal for developers maintaining local control over keys while leveraging cloud-native persistence and neutral authority.

graph TD
    subgraph "Sovereign Enclave (Local)"
        VL[VEX - Cognition]
        AI[Attest - Identity]
    end

    subgraph "Trust Extension (Cloud)"
        VC[CHORA - External Authority]
        VP[VEX - Persist]
        VO[OTEL - Metrics]
    end

    VL -->|1. Seal| AI
    AI -->|2. Signed| VL
    VL -->|3. Witness| VC
    VL -->|4. Capsule| VP
    VL -->|5. Telemetry| VO

Loading

---

⚓ Attest (Hardware-Sealed Identity & Provenance)

The Attest sub-workspace provides the hardware-rooted identity and provenance layer for AI agents. It ensures that an agent's reasoning is cryptographically bound to its physical execution environment.

Core Capabilities:

• Silicon-Bound Identity: Keys are sealed to the hardware (TPM 2.0 on Linux, CNG on Windows). The aid:<pubkey-hash> ID is deterministically derived from the silicon.
• Verifiable Execution Receipts: Every logical decision is signed by the hardware, producing a .capsule that proves "the silicon said this."
• Quantum Undo System: Automatic filesystem snapshots before every attest exec allow for instant state rollback.
• Policy Guardrails: Real-time evaluation of agent actions against YAML-based safety rules.

Quick Start (CLI):

# Build both Rust and Go components
make build

# Initialize the security directory
./attest/attest init

# Create a hardware-sealed identity
./attest/attest agent create --name "my-agent"

📚 Full Attest Documentation →

---

🛡️ McpVanguard Integration (Cloud-Native Security Proxy)

VEX Protocol natively integrates with McpVanguard, allowing for deep security, correlation, and tool execution proxying across distributed deployments.

By configuring VEX's vex-llm module to point to an McpVanguard proxy (instead of executing MCP tools locally), you enable:

• Centralized Tool Auditing: All tool executions are logged and cryptographically signed before being routed to external services.
• Event Correlation: VEX agent reasoning states and actions uniquely correlate with McpVanguard's network intercepts.
• Agent Blackboxing: Isolate the execution context (e.g. database access, heavy computation) from the agent's core reasoning engine.

This is a critical architecture for deploying VEX in "Live Loop" scenarios where actions have real-world consequences (e.g., executing transactions or interacting with external APIs).

---

Production Features

🔐 Core Security

• Silicon-Rooted Identity: Cryptographic PCR Binding (Indices 0, 7, 11) via TPM 2.0 and Microsoft CNG.
• Formal Intent Verification: MagpieAstBuilder prevents prompt-injection by programmatically generating L2-Intent ASTs.
• Hardware-Sealed Capsules: JCS-compliant Evidence Capsules signed by silicon-sealed keys for tamper-proof provenance.
• Argon2id & Zeroize: Extreme memory safety for secrets and industry-standard salted hashing for authentication.

📊 Verifiable Observability

• Formal Verification Audit: Automated checks against Magpie IR in every pipeline run.
• Merkle Audit Chains: Tamper-evident reasoning logs with cryptographic SHA-256 hash chaining.
• Interactive Swagger & OTLP: Real-time tracing and interactive API discovery via /swagger-ui and OpenTelemetry.

🚀 Performance & Resilience

• LLM Circuit Breakers: Automatic failover and backoff guards to prevent provider cascading failures.
• Parallel Evolution: Multi-threaded agent genome processing powered by Rayon for high-throughput evolution.
• Async-First Core: Fully non-blocking tokio runtime designed for massive concurrency and low latency.

---

API Endpoints

Endpoint	Method	Description
/swagger-ui	GET	Interactive API documentation
/health	GET	Basic health check
/health/detailed	GET	Component-level health status
/.well-known/agent.json	GET	A2A agent capability card
/a2a/tasks	POST	Create inter-agent task
/a2a/tasks/{id}	GET	Query task status
/api/v1/agents	POST	Create new agent
/api/v1/agents/{id}/execute	POST	Async execution (TitanGate L1-L3) + Witness Receipt
/api/v1/jobs/{id}	GET	Query status/result of an execution job
/api/v1/jobs/{id}/stream	GET	SSE stream for real-time job updates
/api/v1/metrics	GET	JSON metrics (Admin required)
/metrics	GET	Prometheus metrics (Admin required)
/api/v1/routing/stats	GET	Real-time routing performance & cost savings

---

Testing & Quality

# Unit + integration tests
cargo test --workspace

# Property-based tests (Merkle trees)
cargo test --package vex-core -- proptests

# Benchmarks (evolution, Merkle)
cargo bench --package vex-core

# LLM integration tests (requires API key)
DEEPSEEK_API_KEY="sk-..." cargo test --package vex-llm -- --ignored

---

Documentation

Resource	Link
Full Docs	provnai.dev/docs
API Reference (Rustdoc)	provnai.dev/rustdoc
API Reference (OpenAPI)	Run server → /swagger-ui
Architecture	ARCHITECTURE.md
Railway Deployment	docs/railway-deployment.md
Roadmap	ROADMAP.md
Open Issues	OPEN_ISSUES.md
Benchmarks	BENCHMARKS.md
Contributing	CONTRIBUTING.md

---

📜 Standards & References

VEX Protocol v1.7.0 is the definitive reference implementation for Governed Execution:

• Core Specification: VEX x CHORA Joint Spec v0.3 (AGCP/TRL 6 Alignment).
• RFC 6962: Binary Merkle Tree compliance.
• JCS (RFC 8785): JSON Canonicalization Scheme for bit-parity audit trails.

---

License

Apache-2.0 — See LICENSE