neuron-tai/docs/adr/0019-money-path-consistency-multi-tracker.md

ADR-0019: Money-path consistency (multi-tracker)

Status: Accepted (design); implementation deferred post-alpha

Context

ADR-0015 assumes a single settlement tracker with Raft-replicated ledger events. The hive already gossips billing, accounts, and stats between trackers. When multiple trackers participate, several money-path races appear:

• Settlement retries may double-pay if idempotency keys diverge from on-chain reality.
• Any tracker follower can apply forfeit / charge events — fine under one trusted operator, dangerous with adversarial peers.
• Raft term/vote state is in-memory — restart can duplicate leadership epochs.
• forfeit events are not commutative with charge/payout ordering under concurrent replication.

Alpha ships with one settlement-capable tracker (ADR-0016). This ADR records the accepted multi-tracker design so Bucket 2 issues do not block alpha while preventing silent architectural drift.

Decisions

1. Settlement idempotency (C2)

• Every on-chain payout batch carries a stable settlement_id already debiting pending before broadcast (server.py ~3353–3356, _send_settlement ~3358).
• Required hardening: solana_adapter.send_payouts (~186–213) and the settlement loop must treat the Solana transaction signature as the idempotency anchor — retries reuse the same settlement_id; confirmed signatures must never spawn a second debit.
• Deposit watcher already uses deposit-<sig> event ids — extend the same pattern to payouts.

2. Consensus-gated money mutations (C3/C4)

Money-affecting events (charge, payout, forfeit, credit, settlement, bind) must commit through Raft (or successor consensus), not best-effort gossip alone:

• Only the Raft leader appends money commands to the replicated log.
• Followers apply committed entries in order; gossip becomes a transport, not the source of truth.
• Settlement signing remains leader-only and treasury-key-bearing (ADR-0015).

Shard-assignment commands already use Raft (raft.py); extend the log command set.

3. Durable Raft metadata (A3)

Persist currentTerm, votedFor, and log index to disk (raft.py ~26 — today term lives only in memory). Without this, restart can elect split leaders and duplicate settlement epochs.

4. Commutative forfeit semantics (H1)

Define explicit ordering rules when replicating forfeit vs charge/payout:

• Forfeit amount is snapshotted at event creation time (billing.py ~287).
• Apply forfeit after pending balance reflects all prior committed charges in the same epoch, or use signed pending snapshots in the event payload.
• setdefault on _pending_since (~324) and wallet bindings (~351) must not resurrect stale state on out-of-order apply — use last-writer-wins with (term, index) tie-break.

5. Alpha posture

Item	Alpha	Post-alpha
Single treasury holder	Required	Optional multi-sig
Gossip-authenticated billing	Required (ADR-0017)	Superseded by Raft commit for money
On-chain idempotency	Best-effort resend	Hard guarantee (C2)
Consensus-gated settlement	Leader check only (~3331)	Full Raft gate (C3/C4)

Consequences

• Bucket 2 issues in .scratch/alpha-hardening/ are tracked but not alpha-blocking.
• Implementing C3/C4 before alpha would delay release without security benefit while only one operator runs settlement.
• When enabling third-party settlement trackers, all four hardening items must ship together — partial deployment is worse than single-tracker alpha.

Related

• ADR-0015 (settlement loop, pending collateral)
• ADR-0016 (single settlement tracker for alpha)
• ADR-0017 (gossip auth prerequisite)
• Issues: 12-c2-on-chain-idempotency.md through 15-h1-commutative-forfeit.md