• Kapnet Zoo — Design Space Exploration
  • Purpose
  • Axis 1: Soul Execution Model
    • 1A — Pure Hermes Cron (Model-Driven)
    • 1B — Pure Shell Script (Deterministic)
    • 1C — Hybrid (Orchestration Layered)
    • 1D — Event-Dequeue Model
    • Current Choice: 1C (Hybrid)
  • Axis 2: Communication Transport
    • 2A — File Signal Bus Only (Current)
    • 2B — Kapnet TXXM Bridge
    • 2C — Nostr DM Layer
    • 2D — Hybrid Transport Matrix
    • Current Choice: moving toward 2D
  • Axis 3: Funding & Treasury
    • 3A — Hot Wallet Threshold Sweep
    • 3B — Time-Based Sweep
    • 3C — Consolidation Sweep with UTXO Management
    • 3D — Multisig Cold Storage (Recommended)
    • 3E — SeedPSBT Airgapped Signing
    • Current Choice: Undecided
  • Axis 4: Revenue Model
    • 4A — Fixed Price per File
    • 4B — Pay What You Want (PWYW)
    • 4C — Tiered Access
    • 4D — Subscription/Stream
    • 4E — Protocol Revenue (custom)
    • Recommendation: 4C (Tiered) with 4D (Subscription) overlay
  • Axis 5: Cold Storage Signing Ceremony
    • 5A — Full Manual
    • 5B — Warden-Automated with Operator Alert
    • 5C — QR Code Bridge (No Physical Transfer)
    • 5D — Periodic Ceremony with Batch Accumulation
    • Recommendation: 5B (Warden-automated) + 5D (Batch)
  • Axis 6: Security Model
    • 6A — Single Key per Soul
    • 6B — Key Hierarchy
    • 6C — Shamir Secret Sharing
    • 6D — Key Rotation Schedule
    • Current Choice: 6A now, evaluate 6B for future
  • Axis 7: Cross-Qube Communication
    • 7A — Shared SSD as Bridge
    • 7B — Private Nostr Relay
    • 7C — Qubes qvm-run RPC
    • 7D — Tor Hidden Service Cross-Relay
    • Recommendation: 7B (Private Relay)
  • Axis 8: Operator Interface
    • 8A — Nostr DM Only
    • 8B — File Command Queue
    • 8C — Telegram/Discord Bridge
    • 8D — Dedicated Operator NIP
    • 8E — Multi-Channel with Priority
    • Recommendation: 8E (Multi-Channel)
  • Axis 9: Failure Modes & Recovery
    • 9A — Soul Crash (single soul fails)
    • 9B — Cascade Failure (multiple souls fail)
    • 9C — SSD Failure
    • 9D — Identity Compromise (nsec exposed)
    • 9E — Model Provider Failure (OpenRouter down)
    • Current Implementation: 9A partially
  • Axis 10: Kapnet-Native vs Pragmatic
    • Principle
    • The Litmus Test
  • Decision Matrix — Current State
  • Open Questions

§Kapnet Zoo — Design Space Exploration

§Purpose

This page maps the combinatorial design space for the Kapnet Zoo of Souls. It exists to ensure we don’t silently collapse options that should remain open. Every subsection is a decision axis with multiple viable options. The current implementation is noted, but alternatives are preserved.

§Axis 1: Soul Execution Model

§1A — Pure Hermes Cron (Model-Driven)

Each soul fires as a full Hermes session. The cron prompt loads the soul’s skill, the model reasons about what to do, executes via tools.

Pros: Adaptive, can handle edge cases, natural language reasoning, easy to modify behavior Cons: Token cost per run (~500-2000 tokens/minimal run), cold start latency, model nondeterminism Best for: Sage, Herald, Querant, Scribe, Warden, Cartographer (souls that need judgment) Cost estimate: 11 souls × avg 15 runs/day × 1000 tokens = ~165K tokens/day = ~5M/month

§1B — Pure Shell Script (Deterministic)

Classic crontab + bash. No model invocation. Pure file scanning, hashing, copying, publishing.

Pros: Zero token cost, instant, deterministic, debuggable with set -x Cons: Brittle, no reasoning, can’t adapt, complex logic is painful in bash Best for: Sentinel heartbeat scan, Courier routing, Archivist file scan, Forger build invocation Cost estimate: 0 tokens

§1C — Hybrid (Orchestration Layered)

Mechanical base (shell) with model override. Shell script does the work. If anomaly detected, escalates to Hermes cron job for reasoning.

# soul-sentinel.sh (runs every 30min via crontab)
# 1. Scan state files (pure bash + jq)
# 2. If all healthy → update dashboard, exit
# 3. If anomaly → write alert signal → trigger Hermes cron

Pros: Fast routine operations, reasoning available when needed, cost-efficient Cons: Two systems to maintain, escalation logic adds complexity Cost estimate: ~50K tokens/day (only anomaly-triggered runs use model)

§1D — Event-Dequeue Model

Souls don’t run on schedule. They run when work appears. A shared work queue (/media/user/shared-rw/work-queue/) holds work items. A dispatcher (HQ Prime or Courier) dequeues and routes.

Pros: No wasted runs, scale-to-zero, natural backpressure Cons: Requires queue infrastructure, latency if scheduler doesn’t run, harder to reason about timing Best for: Forger (build on demand), Courier (route when message arrives)

§Current Choice: 1C (Hybrid)

Mechanical souls (Sentinel scan, Courier route, Archivist scan, Forger build) use shell scripts via crontab. Reasoning souls (Sage, Herald, Querant, Scribe, Warden, Cartographer) use Hermes cron. HQ Prime uses Hermes cron.

§Axis 2: Communication Transport

§2A — File Signal Bus Only (Current)

All inter-soul communication via JSON files on /media/user/shared-rw/. No network involved.

Pros: Simple, no network dependency, works offline, auditable (plain files), zero attack surface Cons: Same-qube only, polling-based (latency), no cross-machine

§2B — Kapnet TXXM Bridge

Local signals are file-based. Cross-qube signals are wrapped in TXXMs, published to private relay (ws://127.0.0.1:7777). Remote souls subscribe and process.

Local:  Soul A → write signal file → Soul B reads
Remote: Soul A → TXXM(kind=30501) → private relay → Soul B subscribes

Pros: Uniform abstraction (signal = local TXXM), crosses machine boundaries, Kapnet-native Cons: Requires running private relay, TXXM wrapping/unwrapping layer, async by nature

§2C — Nostr DM Layer

Cross-qube communication via Nostr kind-4 (encrypted DM). Each soul with an npub can DM any other soul.

Soul A → kind-4 DM (NIP-04 encrypted) → Nostr relay → Soul B receives

Pros: End-to-end encrypted, works across any relay-connected agents, no private relay needed Cons: Trusts relay for delivery, metadata visible to relay (who talks to whom), NIP-04 has known weaknesses

§2D — Hybrid Transport Matrix

Use the right transport for each relationship:

§Current Choice: moving toward 2D

Same-qube: file bus (now). Cross-qube: TXXM bridge (when private relay exists). Public: Nostr (live). Operator: multi-channel (to be implemented).

§Axis 3: Funding & Treasury

§3A — Hot Wallet Threshold Sweep

Lightning hot wallet receives payments. When balance exceeds threshold (e.g., 1M sats), Warden triggers PSBT to cold storage.

Buyer → LN payment → Hot wallet
Hot wallet balance > 1M sats → Warden alerts → PSBT flow → Cold storage

Pros: Simple, predictable sweep schedule, Warden has oversight Cons: Single-sig hot wallet is a risk, threshold is arbitrary, Lightning channel management

§3B — Time-Based Sweep

Sweep hot → cold on a fixed schedule (e.g., daily at midnight UTC), regardless of amount.

Every 24h: construct PSBT for full hot balance → sign → broadcast

Pros: Predictable, no threshold tuning, minimizes hot wallet exposure Cons: May sweep dust (inefficient), daily ceremony even if no new funds

§3C — Consolidation Sweep with UTXO Management

Monitor UTXO count and age. Sweep when UTXO count exceeds N OR oldest UTXO exceeds M days AND total value exceeds dust threshold.

Conditions: (UTXO_count > 50) OR (oldest_UTXO > 7d AND total > 50000 sats)
→ PSBT → cold storage

Pros: Efficient UTXO management, minimizes fees, adapts to flow Cons: More complex logic, needs UTXO tracking soul

§3D — Multisig Cold Storage (Recommended)

2-of-3 multisig. Key distribution:

Routine sweep (≤ threshold): Key A + Key B sign → broadcast Large move (> threshold): Key A + Key B + Key C sign → broadcast
Emergency: Any 2 of 3

Pros: No single point of failure, graduated security, industry standard Cons: PSBT ceremony complexity, need hardware signing device, 3 key backups

§3E — SeedPSBT Airgapped Signing

For the cold key, use PSBT (Partially Signed Bitcoin Transaction) flow:

HermQube (hot) constructs unsigned PSBT
    → export via QR/microSD to airgapped device
    → airgapped device signs
    → import signed PSBT
    → broadcast via Bitcoin node

Pros: Cold key never touches networked device, works with any hardware wallet Cons: Manual ceremony per sweep, requires physical media transfer

§Current Choice: Undecided

No funding flow implemented yet. Recommendation: start with 3D (multisig) + 3E (PSBT airgap) for cold storage, 3A (threshold sweep) for hot→cold automation.

§Axis 4: Revenue Model

§4A — Fixed Price per File

Each catalog item has a fixed satoshi price. Buyer pays, receives file access.

kind-30078 store-item: {"price_sat": 5000, "file_hash": "abc..."}
→ Buyer sends LN invoice for 5000 sats
→ Payment confirmed → file access key sent

Pros: Simple, predictable, easy to implement Cons: Doesn’t reflect value, price discovery is manual

§4B — Pay What You Want (PWYW)

File is available at any price (including zero). Suggested price listed.

kind-30078 store-item: {"price_sat": null, "suggested_sat": 1000}

Pros: Maximizes distribution, good for research/open content, generous default Cons: May get zero payments, doesn’t fund operations

§4C — Tiered Access

Free tier (abstracts, metadata), paid tier (full files), premium tier (signed attestations + updates).

kind-30078: {"tier": "free", "content": "abstract + metadata"}
kind-30078: {"tier": "paid", "price_sat": 10000, "content": "full file + sha256 proof"}
kind-30078: {"tier": "premium", "price_sat": 100000, "content": "attestation + update stream"}

**Pros:**捕获不同支付意愿的用户, funds ongoing work, free tier for outreach Cons: More complex catalog management, tier enforcement

§4D — Subscription/Stream

Not file-by-file but access to a data stream. Pay monthly for ongoing updates, new research, configs.

kind-30078: {"type": "subscription", "price_sat": 50000, "period": "monthly", "access": "full-store"}

Pros: Recurring revenue, aligns incentives (ongoing value delivery), simpler accounting Cons: Needs subscription management, ongoing commitment

§4E — Protocol Revenue (custom)

Kapnet-specific: charge for TXXM processing, knot building, or braid storage. Protocol-level fees.

TXXM with postage field: {"postage_sat": 1000, ...}
→ kapnetd collects postage → routes to treasury

Pros: Kapnet-native, protocol-level, aligns with weakwork concept Cons: Requires buyers to run kapnetd, chicken-and-egg adoption problem

§Recommendation: 4C (Tiered) with 4D (Subscription) overlay

Free abstracts/public notes → paid full access → premium attestation stream. Add subscription for ongoing updates.

§Axis 5: Cold Storage Signing Ceremony

§5A — Full Manual

Every cold storage transaction requires operator (GELI) to physically operate the airgapped device.

Pros: Maximum security, human in the loop Cons: Slow, doesn’t scale, operator bottleneck

§5B — Warden-Automated with Operator Alert

Warden constructs PSBT, signs with hot key, exports to SD card. Operator notified (Nostr DM/Telegram). Operator physically transfers to airgapped device, signs, returns. Final broadcast automated.

Warden: construct PSBT + sign with Key A
→ export to /media/user/shared-rw/psbt/pending/
→ notify operator via Nostr DM
→ operator: SD card → airgapped → sign → SD card → /media/user/shared-rw/psbt/signed/
→ Warden: detect signed PSBT → merge signatures → broadcast

Pros: Automated up to the airgap boundary, operator controls cold key, auditable Cons: Still requires operator action, SD card transfer

§5C — QR Code Bridge (No Physical Transfer)

PSBT encoded as QR code, displayed on screen, scanned by airgapped device with camera, signed QR displayed, scanned back.

Pros: No SD card needed, works with any camera-equipped airgapped device Cons: Limited by QR data capacity (large PSBTs need animated QR), slower

§5D — Periodic Ceremony with Batch Accumulation

Instead of sweeping immediately, accumulate incoming payments in hot wallet. At fixed intervals (weekly/monthly), batch all pending UTXOs into a single cold storage transaction.

Pros: One ceremony per period, fee efficient, predictable schedule Cons: Hot wallet exposure between ceremonies, large single transaction

§Recommendation: 5B (Warden-automated) + 5D (Batch)

Weekly batch sweep. Warden prepares PSBT with all accumulated UTXOs. Operator notified. Operator runs airgapped signing ceremony. Single broadcast.

§Axis 6: Security Model

§6A — Single Key per Soul

Each Tier 2+ soul has one keypair. Key stored as hex on disk (600 permissions).

Pros: Simple, easy to implement Cons: Compromised key = compromised identity, no recovery without backup

§6B — Key Hierarchy

Master key (HermQube operational) derives soul keys via HD derivation (BIP-32 style).

master_key → derive("m/soul/herald") → herald_key
master_key → derive("m/soul/archivist") → archivist_key

Pros: Single backup (master key), deterministic derivation, can rotate Cons: Requires HD implementation, master key compromise = all souls compromised

§6C — Shamir Secret Sharing

Sensitive keys (cold storage, master operational) split into shares. M-of-N required to reconstruct.

cold_key → split(3-of-5) → share1 (SD card), share2 (SSD), share3 (SanDisk), share4 (paper backup), share5 (operator memory)

Pros: No single point of failure, can tolerate share loss Cons: Reconstruction ceremony is complex, computational overhead

§6D — Key Rotation Schedule

All soul keys rotated on a schedule (quarterly). New key announced via signed kind-1 note referencing old key.

Old key: signed "I am rotating to new_npub: ..." 
New key: signed "I am the successor of old_npub: ..."

Pros: Limits exposure window, forward secrecy Cons: Complex, may break ongoing conversations, relay caching

§Current Choice: 6A now, evaluate 6B for future

Simple per-soul keys now. Consider HD derivation when the Zoo stabilizes. Cold storage should use 6C (Shamir) for the cold key.

§Axis 7: Cross-Qube Communication

§7A — Shared SSD as Bridge

Souls on different qubes write to the same shared-rw partition. Same file signal bus, different readers.

HermQube AppVM (soul A) → write signal → /media/user/shared-rw/signals/
MKCTP AppVM (soul B) → read signal → /media/user/shared-rw/signals/

Pros: Already works, no new infrastructure Cons: Shared partition is a security boundary concern, no encryption at rest

§7B — Private Nostr Relay

Run a local relay (strfry/relayd) on the Qubes host. Souls on any qube connect to ws://127.0.0.1:7777.

HermQube AppVM → ws://127.0.0.1:7777 → MKCTP AppVM
Connection: TXXMs with custom kinds (accepted by private relay)

Pros: Standard kapnet gossip, works across qubes and machines, accepts custom kinds Cons: Requires running relay, relay is another service to maintain

§7C — Qubes qvm-run RPC

Use Qubes’ native inter-VM RPC to pass messages.

qvm-run --pass-io mkctp-agent 'cat /media/user/shared-rw/inbox/mkctp/message.json'

Pros: Qubes-native, secure, no additional infrastructure Cons: Qubes-specific, not portable, requires RPC policy configuration

§7D — Tor Hidden Service Cross-Relay

Each qube runs its own hidden service for its Nostr relay. Cross-qube communication via Tor.

HermQube relay: .onion:7777
MKCTP relay: .onion:7778
→ Bridges connect the relays

Pros: Network-isolated, censorship-resistant, works across physical machines Cons: Tor adds latency, .onion reachability, complex setup

§Recommendation: 7B (Private Relay)

When private relay is running, this is the primary cross-qube transport. Falls back to 7A (shared SSD) for same-host coordination.

§Axis 8: Operator Interface

§8A — Nostr DM Only

Operator sends commands via Nostr DM to HQ Prime npub. Encrypted, works on any device.

Pros: Simple for operator, encrypted, always available Cons: DM reliability varies by relay, limited to text commands, no file transfer

§8B — File Command Queue

Operator drops command files in /media/user/shared-rw/inbox/hq-prime/commands/. HQ Prime processes on its next run.

Pros: Supports complex commands (JSON), auditable, reliable Cons: Requires access to shared-rw (Qubes file manager or mount)

§8C — Telegram/Discord Bridge

Hermes gateway forwards messages to Telegram. Operator sends commands via Telegram message.

Pros: Real-time, push notifications, rich UI, operator already uses it Cons: Centralized platform, separate trust model, gateway dependency

§8D — Dedicated Operator NIP

Define a custom message format (within kind-1 or DM) for operator commands. Structured commands like a CLI over Nostr.

Command format (kind-1 text):
/kapnet status
/kapnet spawn herald
/kapnet build --target kapnetd --mode release
/kapnet sweep --amount all --to cold

Pros: Self-documenting, discoverable, works over any Nostr client Cons: Parsing complexity, limited to text commands

§8E — Multi-Channel with Priority

All channels accepted. Priority: Telegram > Nostr DM > File command queue. Alerts go out on all channels simultaneously.

Pros: Most reliable, operator can use any channel, redundancy Cons: Multiple channels to monitor, potential for duplicate responses

§Recommendation: 8E (Multi-Channel)

Start with 8B (file queue) + 8A (Nostr DM). Add 8C (Telegram) when gateway is stable.

§Axis 9: Failure Modes & Recovery

§9A — Soul Crash (single soul fails)

Sentinel detects missing heartbeat. HQ Prime logs alert. Operator notified. Other souls continue.

Sentinel: no heartbeat from Herald for 2 cycles
→ alert signal
→ HQ Prime: logs, notifies operator
→ Operator: investigate, restart

§9B — Cascade Failure (multiple souls fail)

Sentinel detects multiple missing heartbeats. HQ Prime enters emergency mode: pauses all non-critical loops, alerts operator immediately.

Sentinel: 3+ souls missing heartbeats
→ critical alert
→ HQ Prime: pause non-essential curses (Cartographer, Querant), keep critical (Sentinel, Courier)
→ notify operator via all channels

§9C — SSD Failure

The Zoo’s state lives on shared-rw. If SSD is unavailable, all souls fail.

Boot check: if /media/user/shared-rw/ not mounted → alert operator
Recovery: operator mounts SSD → souls resume from last state

§9D — Identity Compromise (nsec exposed)

Warden detects anomalous signing. Key rotation initiated.

Warden: event signature mismatch or unauthorized key use
→ alert: possible key compromise
→ rotate identity: publish new key, deprecate old
→ update all configs and references
→ document in wiki

§9E — Model Provider Failure (OpenRouter down)

Hermes cron jobs fail. Shell scripts continue.

Hermes cron: API error → retry with backoff → fail after 3 retries
→ log to signal bus
→ operator notified
→ shell scripts continue mechanical operations

§Current Implementation: 9A partially

Sentinel can detect missing heartbeats. Cascade detection and recovery procedures not yet implemented.

§Axis 10: Kapnet-Native vs Pragmatic

This is the most important axis. Every decision has a “pure Kapnet” option and a “pragmatic” option.

§Principle

Use Kapnet protocol where it adds provable value. Don’t force it where standard tools are sufficient.

§The Litmus Test

Ask: “Does this operation need deterministic convergence/reproducibility across multiple independent agents?”

• Yes → Use Kapnet protocol (TXXM, braid, weakwork)
• No → Use the simplest tool that works

Example: File store catalogs don’t need braid convergence (one Archivist owns the catalog). Use kind-30078 + files. But consensus on “which files are authentic” across multiple Kapnet nodes does need braid. Use TXXM provenance chain.

§Decision Matrix — Current State

§Open Questions

1. Do you already have a Lightning node? Determines whether we build LN infrastructure or integrate with existing.
2. Cold storage hardware? Coldcard? Specter-DIY? SeedQR only? Determines PSBT flow design.
3. Risk tolerance for hot wallet? Determines sweep threshold and signing ceremony frequency.
4. Cross-qube timing? When do MKCTP agents need to communicate with HermQube? Determines priority of private relay setup.
5. Revenue priority? Is funding the immediate goal, or is this a cost center subsidized by operator? Determines complexity of payment infrastructure.
6. NIP publication timeline? Do we propose custom NIPs soon, or wait for protocol maturity? Determines how much of the Kapnet kind allocation goes to public vs private use.