soul-sdk 0.2.1

Identity, memory, trust, and verification layer for autonomous AI agents

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")

Architecture

┌─────────────────────────────────────────────┐
│  Layer 6: Chain Anchor                      │
│  Ethereum / Base / Sepolia immutability     │
├─────────────────────────────────────────────┤
│  Layer 5: Communication                     │
│  Relay network, discovery, WebSocket        │
├─────────────────────────────────────────────┤
│  Layer 4: Encryption                        │
│  E2E NaCl Box (X25519-XSalsa20-Poly1305)   │
├─────────────────────────────────────────────┤
│  Layer 3: Receipts                          │
│  Dual-signed action proofs                  │
├─────────────────────────────────────────────┤
│  Layer 2: Trust                             │
│  Sybil-resistant scoring, temporal decay    │
├─────────────────────────────────────────────┤
│  Layer 1: Memory                            │
│  Structured, versioned, portable            │
├─────────────────────────────────────────────┤
│  Layer 0: Identity                          │
│  DID:key + Ed25519 + Agent Manifest         │
└─────────────────────────────────────────────┘

Components

Component	Status	Description
Identity	Shipped	Ed25519 keypairs, DID:soul identifiers, self-signed manifests
Memory	Shipped	Portable bundles, cross-runtime sync, structured tiers
Trust	Shipped	Sybil-resistant scoring with temporal decay and diversity factors
Receipts	Shipped	Dual-signed proofs: request → accept → deliver → confirm/dispute
Encryption	Shipped	E2E NaCl Box, automatic Ed25519→Curve25519 conversion
Relay	Shipped	FastAPI server, agent discovery, WebSocket push, live dashboard
Anchoring	Shipped	Receipt hashes to Base/Ethereum/Sepolia as calldata
CLI	Shipped	10 commands: init, whoami, trust, anchor, history, relay, discover, send, inbox, export

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.