neuron-tai/docs/issues/33-settlement-loop.md

Status: done

33 — Settlement loop: leader-only batched USDT payouts

What to build

The on-chain settlement loop per ADR-0015, following the mining-pool standard: pay a node when pending ≥ payout_threshold OR time_since_last_payout ≥ max_period, whichever fires first, with a dust floor so no payout is smaller than it is worth.

Only the current Raft leader runs the loop; followers replicate the ledger but never sign. The treasury keypair is loaded only on settlement-capable trackers. Payouts are batched SPL transfers treasury → node wallets on devnet.

Config (all dynamic, so the period can grow with volume): dev defaults period=60s, threshold≈0 so every run is verifiable on-chain; prod defaults period=24h, threshold=a few USDT.

Settlement history (settlement id, tx signature, node wallet, amount, timestamp) persists in SQLite, replicates across the hive, and is queryable over HTTP. Retries are idempotent by settlement id — a failed or timed-out transaction never double-pays.

Acceptance criteria

• Only the Raft leader settles; followers never sign (asserted in a 3-tracker test)
• Trigger: pending ≥ threshold OR elapsed ≥ max_period; dust floor respected
• Batched SPL transfers land on devnet; pending balances zeroed atomically with recorded tx signature
• Failed/timeout transactions retry without double-pay (idempotent by settlement id)
• Settlement history queryable via tracker HTTP endpoint
• End-to-end devnet test: fund client → run inference → node wallet USDT balance increases

Blocked by

• 19-binary-data-plane-and-peer-weight-transfer.md
• 32-devnet-treasury-deposits.md