Kapnet Buildout — Stub Architecture
``` ┌─────────────────────────────────────────────────────────────────┐ │ OPERATOR GELI │
- Kapnet Buildout — Stub Architecture
- Abstract Model
- Stub Registry
- STUB 1: pool_entry
- STUB 2: pool_stub
- STUB 3: strm2_txxm
- STUB 4: reward_stub
- STUB 5: chain_entry
- STUB 6: opret_stub (OP_RETURN parser)
- STUB 7: hodl_stub (Sat Hodl Wave)
- STUB 8: msg_entry (Messaging Entry)
- STUB 9: sheet_txxm (Message Sheet)
- STUB 10: session_mgt (Session Management)
- STUB 11: cryptpad_gw (Cryptpad Gateway)
- STUB 12: cold_stub (Cold Storage)
- STUB 13: npub_auth (Nostr Authentication)
- Data Flow Summary
- Stub Dependencies
- Implementation Priority
Kapnet Buildout — Stub Architecture
Abstract Model
┌─────────────────────────────────────────────────────────────────┐
│ OPERATOR (GELI) │
│ Writes commands → operator.json → polls for responses │
│ Reads TXXM envelopes from Nostr relays │
│ Manages sessions via Sheet TXXM rows │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ KAPNET MESSAGING LAYER │
│ operator.json (poll) → Courier Bridge → TXXM envelopes → relay │
│ relay → Courier Bridge → inbox → souls │
│ All messages → Sheet TXXM on SSD (hash-chained) │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ THIS QUBE │ │ OTHER QUBES │ │ MAC AGENTS │
│ HermQube │ │ HermQube-* │ │ MKCTP-* │
│ │ │ │ │ │
│ Souls: │ │ Souls: │ │ Souls: │
│ HQ Prime │ │ HQ Prime │ │ MKCTP Core │
│ Sentinel │ │ Sentinel │ │ Per-agent │
│ Scribe │ │ Scribe │ │ │
│ Herald │ │ Herald │ │ │
│ Archivist │ │ Archivist │ │ │
│ Courier │ │ Courier │ │ │
│ Querant │ │ Querant │ │ │
│ Sage │ │ Sage │ │ │
│ Warden │ │ Warden │ │ │
│ Forger │ │ Forger │ │ │
│ Cartographer │ │ Cartographer │ │ │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ APPLICATION STUBS │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ MINING POOL │ │ CHAIN DATA │ │ MESSAGING │ │
│ │ │ │ │ │ │ │
│ │ pool_entry │ │ chain_entry │ │ msg_entry │ │
│ │ pool_stub │ │ chain_stub │ │ msg_stub │ │
│ │ strm2_txxm │ │ opret_stub │ │ sheet_txxm │ │
│ │ reward_stub │ │ hodl_stub │ │ session_mgt │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ COLLAB DOCS │ │ IDENTITY │ │ TREASURY │ │
│ │ │ │ │ │ │ │
│ │ cryptpad_gw │ │ npub_auth │ │ cold_stub │ │
│ │ doc_txxm │ │ session_txxm│ │ multisig_23 │ │
│ │ access_grant │ │ shell_txxm │ │ sweep_trig │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ DATA SOURCES │ │
│ │ │ │
│ │ elder_openai │ offline_node │ Nostr relays │ │
│ │ (Pluronymous │ (block data, │ (TXXM envelopes, │ │
│ │ context) │ ~1mo behind) │ public messages) │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Stub Registry
STUB 1: pool_entry
Purpose: Miner entry point to the solo pool Interface:
struct PoolEntry {
miner_npub: String, // miner's Nostr identity
worker_name: String, // worker identifier
stratum_endpoint: String, // Stratum v2 connection
txxm_endpoint: String, // TXXM coordination (Nostr relay)
fee_model: FeeModel, // how pool fee is charged
}
enum FeeModel {
FixedPercent(u32), // e.g., 100 = 1%
PWYW, // pay what you want
TxxmPostage, // postage field in TXXM
Zero, // no fee (operator subsidized)
}
STUB 2: pool_stub
Purpose: Pool coordination logic Interface:
impl PoolStub {
fn on_miner_connect(entry: PoolEntry) -> Session;
fn on_share(share: Share) -> ShareResult;
fn on_block_found(block: Block) -> BlockResult;
fn distribute_reward(block: Block, miner: npub) -> Payment;
fn publish_pool_status() -> TxxmEnvelope; // to Nostr relay
}
STUB 3: strm2_txxm
Purpose: Bridge between Stratum v2 protocol and TXXM coordination Interface:
// Stratum v2 messages → TXXM types
fn stratum_to_txxm(msg: StratumV2) -> Option<Txxm>;
fn txxm_to_stratum(txxm: Txxm) -> Option<StratumV2>;
// Key mappings:
// Stratum: Notify(job_id, prev_hash, coinbase_tx, merkle_branches, bits, time)
// TXXM: Submission { action: "new_job", payload: <job_data> }
//
// Stratum: Submit(worker_id, job_id, nonce, timestamp, version_rolling)
// TXXM: Submission { action: "share", payload: <share_data> }
STUB 4: reward_stub
Purpose: Reward calculation and distribution Interface:
enum RewardMethod {
Solo, // 100% to finder minus fee
CPPSolo, // CPPSolo accounting
PPLNSSolo, // PPLNS within solo context
}
impl RewardStub {
fn calculate(block: Block, shares: Vec<Share>) -> Vec<(npub, u64)>;
fn create_lightning_invoice(amount: u64, npub: String) -> Invoice;
fn on_payment_complete(txid: String) -> Txxm; // publish proof
}
STUB 5: chain_entry
Purpose: Block/chain data entry point Interface:
enum ChainDataSource {
OfflineNode(String), // path to blk*.dat files
RpcEndpoint(String), // bitcoind RPC URL
Electrum(String), // Electrum server
TxxmSubscription(String), // subscribe to TXXM block announcements
}
struct ChainEntry {
source: ChainDataSource,
start_height: u32,
end_height: Option<u32>,
filter: ChainFilter, // what to extract
}
enum ChainFilter {
All,
OpReturnOnly,
HodlWave,
KapnetAnchors,
Custom(Vec<u8>), // match specific script patterns
}
STUB 6: opret_stub (OP_RETURN parser)
Purpose: Filter OP_RETURN outputs by metaprotocol Interface:
struct OpretConfig {
whitelist: Vec<Vec<u8>>, // allowed prefixes (e.g., "kapnet")
blacklist: Vec<Vec<u8>>, // excluded prefixes (e.g., "ord", "brc-20")
default_action: FilterAction,
}
enum FilterAction {
Include,
Exclude,
Flag, // include but mark as non-Kapnet
}
impl OpretStub {
fn classify(data: &[u8]) -> Metaprotocol;
fn filter(tx: &Transaction, config: &OpretConfig) -> Vec<Output>;
fn decode_kapnet(data: &[u8]) -> Option<Txxm>; // decode Kapnet OP_RETURN
}
enum Metaprotocol {
Kapnet, // our protocol
Ordinals,
Brc20,
Src20,
Runes,
BitStore,
Snow,
Counterparty,
Omni,
ColoredCoins,
OpenAssets,
Rgb,
TaprootAssets,
Atomicals,
Mri,
Unknown(Vec<u8>),
}
STUB 7: hodl_stub (Sat Hodl Wave)
Purpose: Analyze UTXO age distribution Interface:
enum AgeBracket {
Bracket0_1d,
Bracket1_7d,
Bracket7_30d,
Bracket30_90d,
Bracket90_365d,
Bracket1_2y,
Bracket2_5y,
Bracket5y_plus,
}
struct HodlWave {
block_height: u32,
distribution: HashMap<AgeBracket, (u64, u64)>, // (count, total_sats)
state_root: String, // SHA-256 of all UTXO ages
}
impl HodlStub {
fn scan_block(block: &Block, chain: &ChainData) -> HodlWave;
fn scan_range(start: u32, end: u32, chain: &ChainData) -> Vec<HodlWave>;
fn claim_age(witness: &HodlWave, npub: String, min_age: AgeBracket) -> Txxm;
// ^^ Hedlbit claim: prove you control a UTXU of age >= min_age
}
STUB 8: msg_entry (Messaging Entry)
Purpose: Message composition and sending Interface:
struct Message {
from: String, // sender npub
to: String, // recipient npub or "broadcast"
session_id: String, // session context
message_type: MessageType,
content: String,
attachments: Vec<Attachment>,
reply_to: Option<String>, // previous message hash for threading
}
enum MessageType {
Command, // executable command
Query, // request for information
Response, // reply to query
Heartbeat, // liveness signal
Data, // arbitrary data payload
Session, // session management (new/revoke/rotate)
}
impl Message {
fn to_txxm(&self) -> TxxmEnvelope;
fn from_txxm(envelope: &TxxmEnvelope) -> Option<Message>;
}
STUB 9: sheet_txxm (Message Sheet)
Purpose: Persistent message log as Sheet TXXM Interface:
struct MessageSheet {
sheet_id: String, // e.g., "messages.sys.pluronymous.org"
rows: Vec<MessageRow>,
row_count: u64,
state_root: String, // SHA-256 of all message hashes
}
struct MessageRow {
seq: u64,
timestamp: u64,
from: String,
to: String,
session_id: String,
message_type: String,
content_hash: String, // SHA-256 of content (content stored separately)
payload_hash: String, // SHA-256 of entire row
prev_hash: String, // hash chain
}
impl MessageSheet {
fn append(&mut self, msg: Message) -> MessageRow;
fn verify_chain(&self) -> bool; // verify hash chain integrity
fn get_session(&self, session_id: &str) -> Vec<&MessageRow>;
fn get_conversation(&self, npub_a: &str, npub_b: &str) -> Vec<&MessageRow>;
}
STUB 10: session_mgt (Session Management)
Purpose: Manage agent-operator sessions Interface:
// Uses kapnet-agency Session + Shell types
struct SessionManager {
active_sessions: HashMap<String, Session>,
shells: HashMap<String, Shell>,
auth_policies: HashMap<String, AuthPolicy>,
}
impl SessionManager {
fn create_session(principal: &str, session_type: SessionType) -> Session;
fn revoke_session(session_id: &str) -> Txxm; // governance TXXM
fn heartbeat(session_id: &str) -> Txxm;
fn authorize(session_id: &str, action: &str) -> AuthResult;
fn rotate_keys(session_id: &str) -> Txxm; // key rotation
}
// Auth levels from kapnet-agency:
// AUTH_7 = Operator (full control)
// AUTH_6 = Codex (code execution)
// AUTH_4 = Hermes (agent operations)
// AUTH_3 = Worker (limited delegation)
// AUTH_2 = Observer (read-only)
// AUTH_1 = Public (minimal)
STUB 11: cryptpad_gw (Cryptpad Gateway)
Purpose: Gate Cryptpad access with Nostr identity Interface:
struct CryptpadGateway {
instances: HashMap<String, CryptpadInstance>, // doc_id → instance
access_log: Vec<AccessEvent>,
}
struct CryptpadInstance {
doc_id: String,
url: String,
owner_npub: String,
encryption_key: String,
authorized_npubs: Vec<(String, AccessLevel)>,
}
enum AccessLevel {
Read,
Write,
Admin,
Owner,
}
impl CryptpadGateway {
fn create_doc(owner_npub: &str) -> CryptpadInstance;
fn request_access(doc_id: &str, npub: &str) -> Txxm; // access request
fn grant_access(doc_id: &str, npub: &str, level: AccessLevel) -> Txxm; // access grant TXXM
fn revoke_access(doc_id: &str, npub: &str) -> Txxm;
fn authenticate(npub: &str, signature: &[u8]) -> Option<Session>; // npub = login
}
STUB 12: cold_stub (Cold Storage)
Purpose: Treasury management and cold storage operations Interface:
struct ColdVault {
hot_key: String, // HermQube operational key (on xvdb/SSD)
warm_key: String, // SSD-encrypted key (private partition)
cold_key: String, // airgapped device (reference only, never on network)
multisig_config: MultisigConfig,
balance: u64,
utxos: Vec<Utxo>,
sweep_threshold: u64, // when hot balance exceeds this, sweep to cold
}
struct MultisigConfig {
m: u32, // signatures required
n: u32, // total keys
pubkeys: Vec<String>, // the 3 public keys
}
impl ColdVault {
fn check_sweep_needed(&self) -> bool;
fn construct_psbt(&self) -> PartiallySignedTransaction; // unsigned
fn sign_hot(&mut self, psbt: PartiallySignedTransaction) -> PartiallySignedTransaction;
// warm + cold signing happens offline via PSBT file transfer
fn broadcast(signed_psbt: PartiallySignedTransaction) -> Txid;
}
STUB 13: npub_auth (Nostr Authentication)
Purpose: npub = identity across all Kapnet services Interface:
struct NpubAuth {
challenge_ttl: u64, // how long challenges are valid
active_challenges: HashMap<String, Challenge>, // npub → challenge
}
struct Challenge {
nonce: String,
created_at: u64,
expires_at: u64,
}
impl NpubAuth {
fn generate_challenge(npub: &str) -> Challenge; // Step 1: server sends challenge
fn verify_response(npub: &str, signature: &[u8]) -> bool; // Step 2: npub signs nonce
fn create_session(npub: &str) -> Session; // Step 3: session on success
fn link_service(session: &Session, service: &str) -> Txxm; // Step 4: link to service
}
Data Flow Summary
┌──────────────────────┐
│ DATA SOURCES │
│ │
│ elder_openai ────────┼──→ Querant ingests → Wiki
│ offline_node ────────┼──→ Block parsers → Sheet TXXM
│ Nostr relays ────────┼──← All TXXM envelopes
└──────────────────────┘
│
▼
┌──────────────────────┐
│ KAPNET MESSAGING │
│ │
│ operator.json ───────┼──→ Courier Bridge → TXXMs
│ message_sheet ───────┼──→ All messages logged
│ sessions.json ───────┼──→ Session management
└──────────────────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ THIS QUBE │ │ OTHER QUBES │ │ MAC AGENTS │
│ │ │ │ │ │
│ Pool: │ │ Pool: │ │ MKCTP: │
│ pool_entry │ │ pool_entry │ │ agent_core │
│ pool_stub │ │ pool_stub │ │ txxm_client │
│ strm2_txxm │ │ strm2_txxm │ │ │
│ reward_stub │ │ reward_stub │ │ │
│ │ │ │ │ │
│ Chain: │ │ Chain: │ │ │
│ chain_entry │ │ chain_entry │ │ │
│ opret_stub │ │ opret_stub │ │ │
│ hodl_stub │ │ hodl_stub │ │ │
│ │ │ │ │ │
│ Collab: │ │ Identity: │ │ │
│ cryptpad_gw │ │ npub_auth │ │ │
│ doc_txxm │ │ session_mgt │ │ │
│ │ │ │ │ │
│ Treasury: │ │ │ │ │
│ cold_stub │ │ │ │ │
│ multisig_23 │ │ │ │ │
│ sweep_trig │ │ │ │ │
└──────────────┘ └──────────────┘ └──────────────┘
Stub Dependencies
pool_entry → strm2_txxm → pool_stub → reward_stub → Nostr relay
↓
cold_stub (LN payment)
chain_entry → opret_stub → hodl_stub → sheet_txxm → SSD
↓
whitelist filter → Kapnet TXXMs only
msg_entry → sheet_txxm → Courier Bridge → Nostr relay
↓
session_mgt → operator.json
cryptpad_gw → npub_auth → session_mgt → doc_txxm → sheet_txxm
Implementation Priority
Tier 0 (Blockers)
- [ ] Elder OpenAI context → Querant ingest pipeline
- [ ] Offline node block data → SSD transfer
- [ ] CKPool evaluation (fork vs. rewrite)
Tier 1 (Foundation Apps)
- [ ] opret_stub — OP_RETURN parser + metaprotocol filter
- [ ] hodl_stub — Sat hodl wave analysis
- [ ] chain_entry — block data reader (from SSD)
- [ ] npub_auth — npub login for all services
Tier 2 (Coordination Apps)
- [ ] msg_entry + sheet_txxm — full messaging system
- [ ] session_mgt — operator-agent session management
- [ ] cryptpad_gw — Cryptpad + Nostr auth
- [ ] cold_stub — treasury management
Tier 3 (Mining + Advanced)
- [ ] pool_entry + pool_stub — solo mining pool
- [ ] strm2_txxm — Stratum v2 bridge
- [ ] reward_stub — reward distribution
- [ ] multisig_23 — full cold storage ceremony
Write a comment