refine blockchain integration and protocols
This commit is contained in:
Dobromir Popov
@@ -710,6 +710,103 @@
|
||||
"US-014",
|
||||
"US-019"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "US-031",
|
||||
"title": "31 — Billing ledger: per-token pricing, 90/10 split, pending balances",
|
||||
"description": "Tracker-side off-chain billing per ADR-0015. Each model preset has a USDT price per 1K tokens in tracker config. On request completion the tracker debits the client's API-key ledger balance and credits 90% to the serving nodes' pending balances proportional to work_units (layers × tokens), 10% to the protocol cut. Requests from API keys with insufficient balance are rejected with 402. Ledger persists in the existing tracker SQLite and replicates across the tracker hive.",
|
||||
"acceptanceCriteria": [
|
||||
"Per-model price_per_1k_tokens in tracker config with sane defaults",
|
||||
"Completed request debits client ledger: price × total_tokens / 1000",
|
||||
"90% split across serving nodes by work_units; 10% accrues to protocol_cut",
|
||||
"Insufficient balance → HTTP 402 before routing (no free work)",
|
||||
"Balances survive tracker restart (SQLite) and replicate to hive followers",
|
||||
"Unit tests: single-node route, 3-node split, exhausted balance, restart persistence"
|
||||
],
|
||||
"priority": 31,
|
||||
"status": "open",
|
||||
"notes": "Pure off-chain — no Solana calls in this story. Reuses ComputeAttribution/work_units from packages/contracts.",
|
||||
"dependsOn": [
|
||||
"US-023",
|
||||
"US-025"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "US-032",
|
||||
"title": "32 — Devnet custodial treasury: mock-USDT mint + deposit watcher",
|
||||
"description": "Real Solana adapter behind the packages/contracts boundary, custodial model per ADR-0015. A setup script creates the mock-USDT SPL mint (6 decimals) and treasury token account on devnet. Clients register a wallet pubkey against their API key; the deposit watcher polls the treasury token account and credits the sender's API-key ledger balance on confirmed USDT transfers. Mint address, RPC URL, and treasury keypair path are config (.env.devnet).",
|
||||
"acceptanceCriteria": [
|
||||
"scripts/devnet_setup.py creates mint + treasury ATA and prints .env.devnet values",
|
||||
"POST /v1/wallet/register binds client wallet pubkey to API key",
|
||||
"Deposit watcher credits ledger within one poll interval of a confirmed transfer",
|
||||
"Duplicate/replayed transactions are credited exactly once (signature dedupe)",
|
||||
"Local solana-test-validator integration test covers mint→deposit→credit flow",
|
||||
"Deterministic local adapter still works for CI without any validator"
|
||||
],
|
||||
"priority": 32,
|
||||
"status": "open",
|
||||
"notes": "Supersedes 'testnet never devnet' note in issue 06. solana-py + spl-token client libs.",
|
||||
"dependsOn": [
|
||||
"US-031"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "US-033",
|
||||
"title": "33 — Settlement loop: leader-only batched USDT payouts",
|
||||
"description": "The Raft leader runs the settlement loop per ADR-0015: pay a node when pending ≥ payout_threshold OR time since its last payout ≥ max_period, whichever fires first, with a dust floor. Payouts are batched SPL transfers treasury→node wallet on devnet. Dev defaults: period 60s, threshold ~0; prod defaults: period 24h, threshold few USDT — all dynamic config. Settlement history (tx signature, node, amount, epoch) persists and replicates.",
|
||||
"acceptanceCriteria": [
|
||||
"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 → observe node wallet USDT balance increase"
|
||||
],
|
||||
"priority": 33,
|
||||
"status": "open",
|
||||
"notes": "Mining-pool standard: threshold + max-interval, dust floor. Treasury key only on settlement-capable trackers.",
|
||||
"dependsOn": [
|
||||
"US-019",
|
||||
"US-032"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "US-034",
|
||||
"title": "34 — Hardened proof-of-work: pending-balance forfeiture penalty",
|
||||
"description": "Wire the validator's ~5% sampling to the new penalty per ADR-0015: on confirmed output divergence the node's entire pending balance is forfeited to the protocol cut, a strike is recorded, and three strikes ban the wallet (tracker rejects registration and excludes from routes). Probationary period (first N jobs unpaid) is retained as the re-entry cost. Penalty math documented: at 5% sampling, forfeiting ~a day's pending earnings ≫ 20× per-job cheat gain.",
|
||||
"acceptanceCriteria": [
|
||||
"Validator divergence → pending balance forfeited to protocol_cut in the same ledger transaction as the strike",
|
||||
"3rd strike bans wallet: registration rejected, excluded from all routes",
|
||||
"Banned wallet's unpaid pending balance is not paid out at next settlement",
|
||||
"Probation: first N jobs (default 50) accrue no pending balance; node CLI shows remaining",
|
||||
"Integration test: deliberately-bad node loses pending, accrues strikes, gets banned within 60 requests",
|
||||
"Slash/forfeiture events visible in tracker logs and settlement history"
|
||||
],
|
||||
"priority": 34,
|
||||
"status": "open",
|
||||
"notes": "No stake deposit — pending balance IS the collateral. Amends ADR-0003 penalty; sampling mechanics unchanged.",
|
||||
"dependsOn": [
|
||||
"US-031"
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "US-035",
|
||||
"title": "35 — Tracker web dashboard",
|
||||
"description": "Web dashboard served by the tracker (single-page, no build step — plain HTML/JS polling tracker HTTP endpoints). Shows: hive membership and Raft leader, node registry with health/scores/coverage map, client ledger balances, node pending balances, settlement history with devnet explorer links, strikes/bans, and rolling RPM stats. Read-only in this story; every tracker in the mesh can serve it from its replicated state.",
|
||||
"acceptanceCriteria": [
|
||||
"GET /dashboard serves the UI from any tracker (leader or follower)",
|
||||
"Panels: hive/leader, nodes+coverage, client balances, pending payouts, settlement history (with tx links), strikes/bans, RPM stats",
|
||||
"Auto-refresh ≤5s without page reload",
|
||||
"No new build toolchain — static assets embedded in the tracker package",
|
||||
"Works against a 3-tracker hive in the two-machine LAN test setup"
|
||||
],
|
||||
"priority": 35,
|
||||
"status": "open",
|
||||
"notes": "CLI dashboard already exists from US-016; this is the web counterpart. Write ops (price config, manual settle) deferred.",
|
||||
"dependsOn": [
|
||||
"US-031",
|
||||
"US-033"
|
||||
]
|
||||
}
|
||||
],
|
||||
"metadata": {
|
||||
@@ -724,4 +821,4 @@
|
||||
"blocked": "Waiting on unresolved external dependency"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user