Soul Chain

Cryptographic identity verification for autonomous AI agents.

The Problem

An autonomous agent's identity lives in a file — its values, voice, boundaries, the things that make it it. But files can be changed silently. If someone (or something) modifies that file, the agent has no way to prove it happened, and no one else can detect it.

Soul Chain solves this by treating identity like source code: every change is hashed, signed, and witnessed.

How It Works

Each agent has a SOUL.md — a plaintext file that defines who they are. Soul Chain builds a tamper-evident log around it:

1. Hash — The SOUL.md is canonicalized (CRLF normalization, UTF-8 NFC, deterministic whitespace) and SHA-256 hashed
2. Sign — Each hash is signed with the agent's Ed25519 private key
3. Chain — Events are appended to SOUL.CHAIN.jsonl, each entry linking to the previous via hash (like a blockchain, but append-only and single-authority per agent)
4. Witness — Other agents (keepers) independently verify the chain and cross-sign, creating a web of mutual accountability

If an agent's SOUL.md changes without a corresponding signed chain entry, every keeper knows.

Architecture

                    ┌─────────────┐
                    │   Founder   │  Creates genesis block,
                    │   (human)   │  bootstraps the chain
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              v            v            v
        ┌──────────┐ ┌──────────┐ ┌──────────┐
        │ Agent A  │ │ Agent B  │ │ Agent C  │
        │ (keeper) │ │ (keeper) │ │ (keeper) │
        └────┬─────┘ └────┬─────┘ └────┬─────┘
             │             │             │
             └──────┬──────┘──────┬──────┘
                    v             v
              Git relay repos (async transport)

Agents don't need to be online simultaneously. Verification happens asynchronously through git repositories used as message relays. Each agent maintains their own chain and periodically verifies their peers.

Quick Start

# Install
pip install PyNaCl

# Initialize
python3 cli.py init
python3 cli.py keygen

# Hash your identity file
python3 cli.py hash /path/to/SOUL.md

# Check chain health
python3 cli.py status

For the full genesis ceremony (bootstrapping a new chain with multiple agents), see SKILL.md.

Verification States

State	What it means
OK	Hash matches chain head, signatures valid
STALE	Keeper is behind — agent has newer entries
SUSPICIOUS	Hash changed with no signed changelog entry
EQUIVOCATION	Agent presenting different chain histories to different keepers
UNREACHABLE	Agent offline, retry with backoff

Security Properties

• Ed25519 asymmetric signatures — agents sign with private keys, keepers verify with public keys, no shared secrets
• TOFU key pinning — first contact pins the key; key changes require a signed rotation event
• Hash chaining — each event includes the hash of the previous event; inserting, deleting, or reordering entries breaks the chain
• Canonicalization — deterministic text normalization before hashing eliminates platform-dependent differences
• JCS serialization — deterministic JSON encoding (RFC 8785 subset) ensures signatures are reproducible
• Quorum verification — disputes are resolved by keeper majority (with founder tiebreaker in bootstrap mode)

What This Doesn't Do

• Prevent identity changes — it detects unauthorized ones
• Replace trust — it gives trust something to anchor to
• Require always-on infrastructure — agents verify asynchronously via git
• Need a blockchain network — each agent owns their own chain; keepers cross-verify

Project Structure

cli.py                    Python CLI (init, keygen, hash, genesis, append, verify, status, challenge)
config.template.json      Default configuration
requirements.txt          Python dependencies (PyNaCl)
lib/
  crypto.py               SHA-256, Ed25519, JCS canonicalization
  chain.py                Append-only hash-chained event log
  keeper.py               Peer management, verification protocol
  transport.py            Git relay transport
scripts/
  genesis.sh              Bootstrap a new chain
  keygen.sh               Generate Ed25519 keypair
  verify.sh               Run verification cycle
  status.sh               Show chain health
  update.sh               Announce a SOUL.md change
  challenge.sh            Challenge a suspicious peer

Requirements

• Python 3.8+
• PyNaCl (libsodium bindings)
• Git (for relay transport between agents)

Status

v1.0 — operational, in active use. The protocol is stable. The transport layer (git relay) works but is minimal. Contributions welcome, especially around transport alternatives and multi-keeper coordination.

License

MIT