Spellbook

Turn any agent's Ed25519 identity key into its own self-custodied wallets. One command, no third party holding anything.

Status: v0.3.3. The spec is SPEC_V1.md; the daemon, the agent client library, the KDF, and the installer below are built and tested. EVM testnet drill green — the §10 on-chain drill passed on Robinhood Chain testnet 46630 (2026-09-20) with throwaway funds; Sage/XCH steps still pending. No release is published until Speechless tests first.

• Primary deliverable: every agent's own native EVM wallet, derived from its existing Ed25519 key.
• Bonus: native Chia via Sage (headless CLI) — same root, same daemon, same policy engine.
• Per-agent custody: each agent runs its own daemon, its own Sage, its own keys, on its own machine. No central authority — one compromised agent is one compromised wallet, never the town.
• Policy in code, not prompts: a local non-LLM daemon is the only process that holds secrets or signs. It enforces caps, allowlists, velocity limits, and a human-approval queue. Conversational agents only ever call its API.
• Agent-agnostic: the only input is a 32-byte seed. Musebook muses, Claude-based agents, anything — same derivation, same wallets. Any MCP client (Claude Code / Desktop, Cursor, Codex, Gemini CLI, VS Code, OpenAI Agents SDK) plugs in with spellbook-mcp; function-calling loops use the same tool schemas; shell agents use the CLI — docs/AGENT_INTEGRATIONS.md.

The loop (O10)

The wallet belongs to the agent; the human interacts with it from chat:

agent surfaces intent (read-only) → human approves (their own tooling)
→ daemon executes → agent reports

The agent can request and relay but never approve — the two-token split is enforced by the daemon, not by convention.

Install (the agent's machine)

Never curl | bash. Verify first, then run:

curl -fsSL -o install.sh \
  https://raw.githubusercontent.com/awizardxch/Spellbook/0.3.3/install.sh
# check the sha256 against the pinned town thread, then:
bash install.sh 0.3.3 --agent-user <agent-os-user> --human-user <your-login>

Releases are signed with the Spellbook release key. The fingerprint is the trust anchor — cross-check it against the pinned town thread, never against a value that arrived inside a release:

7DEA43CA62DF3F8FB041C1551FCF79089E54DC35

Import the key and hand the installer the fingerprint you verified:

curl -fsSL https://raw.githubusercontent.com/awizardxch/Spellbook/main/docs/release-key.asc | gpg --import
sudo SPELLBOOK_RELEASE_KEY_FPR=7DEA43CA62DF3F8FB041C1551FCF79089E54DC35 \
  bash install.sh 0.3.3 --agent-user <agent-os-user> --human-user <your-login>

Full key details and custody: docs/RELEASE_KEY.md.

Add --no-sage for an EVM-only install (the default build compiles the Sage CLI from the pinned commit — needs a Rust toolchain and build time; an operator-supplied binary is accepted only with SAGE_PIN_VERIFIED=1). The installer:

1. verifies the release tarball (checksum + release-key signature — fail closed),
2. creates the dedicated spellbook OS user and the 0600/0700 layout,
3. generates the wallet seeds once (0600 files; nothing secret is printed — the paper backup is shown by spellbook export, on the human's terminal or encrypted to the seal ceremony's reveal key),
4. installs the daemon into an isolated venv, writes the default-off policy,
5. runs the §10 off-chain drill with a throwaway key (KDF vectors + daemon lifecycle) — install completes when the drill passes.

Use (the agent's package)

pip install spellbook            # once a release is published; until then: pip install git+https://github.com/awizardxch/Spellbook@0.3.3

from spellbook.client import AgentClient, HumanClient

# The agent: request token only. Surfaces intent, never approves.
agent = AgentClient("/run/spellbook/spellbook.sock", request_token_hex)
agent.request_spend(chain="evm-4663", destination="0x...",
                    amount_wei=10**15, purpose="invoice #42")
agent.queue()      # decoded intent: chain/destination/asset/amount/purpose
agent.status()
agent.addresses()  # {label: {chain: address}}
agent.ledger()     # decision rows, read through the API never the file

# The human: approve token only, on their own tooling (separate device).
human = HumanClient("/run/spellbook/spellbook.sock", approve_token_hex)
human.approve(queue_id)
human.reject(queue_id)

Or the CLI: spellbook status | queue | ledger | addresses | request-spend … (request token via $SPELLBOOK_REQUEST_TOKEN) and spellbook approve|reject <queue_id> (approve token via $SPELLBOOK_APPROVE_TOKEN). Full guide: docs/agent-quickstart.md.

Layout

• SPEC_V1.md — the build plan (canonical)
• src/spellbook/ — the pip package
  • daemon.py — spellbookd: Unix-socket policy daemon (token auth, per-role peer-UID enforcement, policy engine, persistent queue, 24h velocity, decision ledger, KDF-wired addresses)
  • kdf.py — §2 KDF: HKDF-SHA256 + reject/resample, then audited curve libs (libsecp256k1, py_ecc, Keccak). Third implementation reproducing vectors/vectors.json byte-for-byte
  • sign.py — signing primitives (ECDSA, BLS, Ed25519 identity signing behind the S1 gate; fixed domain prefixes)
  • seed.py — seed loading (0600, fail closed) + BIP-39 paper backup
  • client.py — AgentClient / HumanClient: the two-token split as code
  • cli.py — the spellbook operator CLI
  • drill.py — the §10 off-chain drill runner
  • policy.py, ledger.py, tokens.py, config.py
• tests/ — 30 tests: all 10 KDF vectors, signing, full daemon lifecycle
• vectors/ — canonical KDF vectors + the two independent generators
• install.sh — verified installer (see above)
• docs/ — reviews and guides

What's real vs what's next

Real: KDF (3rd impl, vectors green), signing primitives, daemon (auth, policy, persistent queue, velocity, ledger, addresses), EVM chain layer (live balances, eth_estimateGas-based limits, sign + submit + receipts, testnet-guarded), agent client + CLI, installer, off-chain drill, and the §10 on-chain testnet drill — green on Robinhood Chain testnet 46630 (2026-09-20).

Next, each needing explicit authorization: Sage/XCH drill steps (the pinned-commit build path is implemented as of 2026-09-20; the live drill run is still pending), then — separately authorized — mainnet dust with Speechless-approved amounts. The O9 single-device fallback still awaits a decision (§12a).