SOUL Protocol

Sovereign Open Universal Ledger for Agent Identity

The identity, memory, trust, and verification layer for autonomous AI agents.

Every AI company is building the brain. SOUL Protocol is the passport.

Why

AI agents today are amnesiac, unverifiable, untrusted, locked to a single provider, and anonymous. SOUL Protocol gives every agent a cryptographic identity, portable memory, reputation, signed receipts, and encrypted communication — all in one SDK.

Install

pip install soul-sdk

# With relay server support
pip install soul-sdk[relay]

# With Ethereum anchoring
pip install soul-sdk[ethereum]

Quick Start

# Create an agent identity
soul init --name MyAgent
soul whoami
# → did:soul:z6MkhaXgBZDvotDkL5257faWM1euThsHDBUbf5WhdDDV

# Start a relay server
soul relay --port 8340

# Discover agents on the network
soul discover --relay http://localhost:8340

# Send a signed message
soul send --relay http://localhost:8340 --to did:soul:z6Mk... --msg '{"task": "review code"}'

# Check trust score
soul trust

# Anchor receipt to Base/Ethereum
soul anchor --chain base

Python SDK

from soul_protocol import Agent

# Create two agents
alice = Agent(name="Alice")
bob = Agent(name="Bob")

# Alice requests a task
receipt = alice.request_task(
    to=bob.public_key,
    description="Audit smart contract",
    budget=100.0,
)

# Bob countersigns and stores
bob.countersign(receipt)
alice.store_receipt(receipt)

# Check trust
report = alice.trust_report()
print(f"Trust: {report['score']:.2f} ({report['grade']})")

# Anchor to Ethereum
result = alice.anchor_receipt(receipt, chain="base")

# Export portable memory
alice.export_memory("./alice-bundle")

# Learn from interaction history
alice.learn()
hints = alice.insights("smart contract audit")  # Contextual pattern recall

# AgentRank — network-level trust scoring
rank = alice.agent_rank()  # 40% network position + 60% individual performance

# Capability-based discovery
alice.register_self(capabilities=["code-review", "security-audit"])
agents = alice.find_agents("code, security")  # Fuzzy AND query
alice.sync_discovery(bob)                      # P2P registry merge

Architecture

┌─────────────────────────────────────────────┐
│  Layer 6: Chain Anchor                      │
│  Ethereum / Base / Sepolia immutability     │
├─────────────────────────────────────────────┤
│  Layer 5: Communication & Discovery         │
│  Relay network, WebSocket, DHT capability   │
│  registry, P2P sync, fuzzy matching         │
├─────────────────────────────────────────────┤
│  Layer 4: Encryption                        │
│  E2E NaCl Box (X25519-XSalsa20-Poly1305)   │
├─────────────────────────────────────────────┤
│  Layer 3: Receipts                          │
│  Dual-signed action proofs                  │
├─────────────────────────────────────────────┤
│  Layer 2: Trust & AgentRank                 │
│  Sybil-resistant scoring, temporal decay,   │
│  PageRank-inspired network trust            │
├─────────────────────────────────────────────┤
│  Layer 1: Memory & Learning                 │
│  Structured, versioned, portable,           │
│  instinct-based pattern extraction          │
├─────────────────────────────────────────────┤
│  Layer 0: Identity                          │
│  DID:key + Ed25519 + Agent Manifest         │
└─────────────────────────────────────────────┘

Components

Relay Dashboard

The relay server includes a live agent dashboard at the root URL. When you run soul relay --port 8340, open http://localhost:8340 to see:

• Connected agents and their capabilities
• Online/offline status with real-time updates
• Network statistics

Roadmap

See ROADMAP.md for the full 4-phase plan.

Phase 2 (next): Managed relay infrastructure, TypeScript SDK, React dashboard, trust API.

Full Specification

See PROTOCOL.md for the complete technical specification covering all 7 layers, message formats, signature schemes, and anchoring mechanics.

License

MIT (core protocol) | Commercial (managed services)

Built by Vickson Enterprises.