Add alpha-hardening ADRs and issue plan from pre-release audit.
Lock alpha scope, tracker auth, TOPLOC fraud verification, and deferred multi-tracker money-path work; supersede legacy fraud issues with ADR-0018. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
D.Popov
41
.scratch/alpha-hardening/issues/01-c1-gossip-auth.md
Normal file
41
.scratch/alpha-hardening/issues/01-c1-gossip-auth.md
Normal file
@@ -0,0 +1,41 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 01 — C1: Authenticate hive gossip endpoints
|
||||
|
||||
## What to build
|
||||
|
||||
Add authenticated peer identity to all tracker gossip mutation endpoints. Today any caller can push billing, account, and stats events without verification.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_billing_gossip` (~2414–2427)
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_accounts_gossip` (~2610–2623)
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_stats_gossip` (~2355–2364)
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `apply_events` (~301–311)
|
||||
- `packages/tracker/meshnet_tracker/accounts.py` — `apply_events` (~220–226)
|
||||
|
||||
Implement per ADR-0017 §3: shared hive HMAC (body + timestamp) or mutual TLS between configured tracker peers. Reject unauthenticated gossip with 401.
|
||||
|
||||
**Note:** `/v1/gossip` (node throughput fan-out, `server.py` ~1331) is **not** in scope for this issue — see ADR-0017 §3 out-of-scope note.
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: unauthenticated POST to `/v1/billing/gossip` applies a credit event today — test must fail after fix.
|
||||
2. Red: authenticated peer with valid HMAC applies events; invalid/missing auth returns 401 and `applied: 0`.
|
||||
3. Green: implement verifier + config (`--hive-secret` or peer cert paths).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `/v1/billing/gossip`, `/v1/accounts/gossip`, `/v1/stats/gossip` reject requests without valid hive auth
|
||||
- [ ] Authenticated peers replicate events as today (id-dedup preserved)
|
||||
- [ ] Config documented for multi-tracker dev setups
|
||||
- [ ] Tests cover reject + accept paths without live network
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0017](../../docs/adr/0017-tracker-authentication-and-authorization.md)
|
||||
- [ADR-0016](../../docs/adr/0016-alpha-scope-and-known-limitations.md)
|
||||
|
||||
## Blocked by
|
||||
|
||||
None — implement alongside or immediately before `02-a2-unified-auth-boundary.md`.
|
||||
@@ -0,0 +1,45 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 02 — A2: Unified auth boundary for privileged and financial reads
|
||||
|
||||
## What to build
|
||||
|
||||
Replace header-presence stubs with a single auth middleware that resolves API keys, admin sessions, validator service tokens, and hive peer identity. Close leaks on financial and operator endpoints.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_billing_forfeit` (~2429–2464) — H3: non-empty `Authorization` only
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_benchmark_hop_penalty` (~2650–2658), `_handle_benchmark_results` (~2745–2748) — H3
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_billing_summary` (~2366–2371) — H4
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_billing_settlements` (~2407–2412) — H4
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_registry_wallets` (~2391–2405) — H4
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_session_account` (~2468+), `_handle_admin_accounts` (~2588–2608) — H4
|
||||
- `packages/tracker/meshnet_tracker/accounts.py` — `session_account()`, `create_session()` only (session store; not handler wiring)
|
||||
|
||||
Per ADR-0017 §4: forfeit → validator or admin; benchmark → admin; billing summary/settlements/registry wallets → admin session. Forfeit validator identity: see `20-validator-service-token.md`.
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: POST `/v1/billing/forfeit` with `Authorization: Bearer garbage` succeeds today — must require validator/admin identity.
|
||||
2. Red: GET `/v1/billing/summary` without admin session returns 401/403.
|
||||
3. Green: middleware + role checks; existing inference API-key path unchanged.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Single `_require_auth(role=...)` (or equivalent) used by all privileged handlers
|
||||
- [ ] Forfeit accepts only validator service token or admin session — not arbitrary Bearer strings
|
||||
- [ ] Financial read endpoints require admin session (alpha posture)
|
||||
- [ ] Benchmark write/read require admin or service token
|
||||
- [ ] Integration tests for each endpoint class (reject unauth, accept valid)
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0017](../../docs/adr/0017-tracker-authentication-and-authorization.md)
|
||||
|
||||
## Related
|
||||
|
||||
- `20-validator-service-token.md` — validator service token format, rotation, forfeit auth
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `01-c1-gossip-auth.md` (shared auth config)
|
||||
@@ -0,0 +1,38 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 03 — C5 + M1: Starting credit 0, funded-account gate, spend cap
|
||||
|
||||
## What to build
|
||||
|
||||
Close the free-credit faucet. New API keys start at **0 USDT**; inference requires a real deposit or admin credit. Add a configurable per-request spend cap (M1) to limit runaway charges on compromised keys.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `DEFAULT_STARTING_CREDIT = 1.0` (~22), `ensure_client` (~73–85), `has_funds` (~87–88), duplicate credit on charge (~130–138)
|
||||
- `packages/tracker/meshnet_tracker/server.py` — billing gate before routing (~1667–1690)
|
||||
|
||||
Per ADR-0017 §2 and ADR-0016 §3.
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: new API key gets 1.0 USDT implicit credit — test expects 0 balance until deposit.
|
||||
2. Red: first inference without deposit returns 402.
|
||||
3. Green: `DEFAULT_STARTING_CREDIT = 0.0`; optional `--max-charge-per-request` config.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `DEFAULT_STARTING_CREDIT` is 0.0; no automatic caller credit on first touch
|
||||
- [ ] `has_funds` false for fresh keys; 402 before routing (server.py ~1684)
|
||||
- [ ] Admin `credit_client` or bound-wallet deposit still funds accounts
|
||||
- [ ] Configurable max charge per request (M1) rejects oversize completions with clear error
|
||||
- [ ] Tests: fresh key blocked; after credit/deposit, inference proceeds
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0017](../../docs/adr/0017-tracker-authentication-and-authorization.md)
|
||||
- [ADR-0016](../../docs/adr/0016-alpha-scope-and-known-limitations.md)
|
||||
- [ADR-0015](../../docs/adr/0015-usdt-custodial-settlement.md)
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `02-a2-unified-auth-boundary.md` (admin credit path secured)
|
||||
@@ -0,0 +1,37 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 04 — H2: Tracker-authoritative token and work-unit accounting
|
||||
|
||||
## What to build
|
||||
|
||||
Stop trusting node-reported usage for billing. The tracker already proxies responses — count tokens from the proxied stream/body and compute work units from the **route it constructed**, not node declarations.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `node_work` from route construction (~1776–1782, ~1781–1782)
|
||||
- `packages/tracker/meshnet_tracker/server.py` — streaming token/chunk billing (~1890–1921)
|
||||
- `packages/tracker/meshnet_tracker/server.py` — non-streaming `_usage_total_tokens` (~1938–1943)
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `charge_request` node_work split (~104–151)
|
||||
|
||||
Accounting fraud = inflating tokens or shard span. Per ADR-0018 §5.
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: mock upstream returns inflated `usage.total_tokens` in body but tracker bills that value — test expects tracker-measured count.
|
||||
2. Red: node registers false `shard_end`; billing uses tracker route span, not registration field alone.
|
||||
3. Green: authoritative counters; ignore node-reported work units on charge path.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Token count for billing derived from tracker-parsed proxy response — **prefer tracker-measured stream chunk count**; when upstream `usage.total_tokens` is present, use the **minimum** of tracker count and node-reported value (cap inflated node usage)
|
||||
- [ ] Work units = tracker-computed layer span per hop at route build time (~1781–1782)
|
||||
- [ ] Nodes cannot increase payout by lying about shard range mid-request
|
||||
- [ ] Integration test: malicious node metadata does not inflate `charge_request` shares
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0018](../../docs/adr/0018-fraud-detection-verification-and-reputation.md) §5
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `02-a2-unified-auth-boundary.md`
|
||||
@@ -0,0 +1,40 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 05 — A1/A5: Persist strike, ban, and reputation state
|
||||
|
||||
## What to build
|
||||
|
||||
Registry strike/ban/reputation state today lives in RAM-only `_LocalContractState` — tracker restart wipes penalties. Persist to SQLite (same pattern as `BillingLedger` and `AccountStore`) so reputation carries forward per ADR-0016 §4.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/contracts/meshnet_contracts/__init__.py` — `RegistryContract`, `RegistryWallet`, in-memory `_state.registry` (~103–206)
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — SQLite persistence pattern (~60, event log)
|
||||
- `packages/tracker/meshnet_tracker/accounts.py` — SQLite + event replication (~40–56)
|
||||
|
||||
Include fields for: `strike_count`, `banned`, `completed_job_count`, graduated **reputation score** (float, default 1.0), `last_audit_ts`, probation tracking.
|
||||
|
||||
**Scope split:** this issue owns **schema + persistence + load/reload** only. Reputation **scoring deltas** (audit pass/fail adjustments, decay rules) belong in issue 08.
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: record strike, restart tracker process, strike count is 0 — must fail.
|
||||
2. Green: persist + reload; gossip replicates strike events if multi-tracker.
|
||||
3. Red: banned wallet registers node — must reject (wire to routing).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Strike/ban/reputation survive tracker restart (SQLite or equivalent)
|
||||
- [ ] `RegistryContract.list_wallets` reflects persisted state
|
||||
- [ ] Banned wallet rejected at registration and excluded from routes
|
||||
- [ ] Reputation score field present for routing/audit issues (08–09)
|
||||
- [ ] Event-sourced mutations compatible with future Raft (ADR-0019)
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0016](../../docs/adr/0016-alpha-scope-and-known-limitations.md) §4
|
||||
- [ADR-0018](../../docs/adr/0018-fraud-detection-verification-and-reputation.md) §6
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `02-a2-unified-auth-boundary.md`
|
||||
@@ -0,0 +1,47 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 06 — FRAUD: TOPLOC integration (teacher-forced audit primitive)
|
||||
|
||||
## What to build
|
||||
|
||||
Adopt [TOPLOC](https://github.com/PrimeIntellect-ai/toploc) (MIT, `pip install toploc`) for activation fingerprint commit and verify. Replace string-equality validator checks with teacher-forced prefill + TOPLOC tolerance matching.
|
||||
|
||||
**Estimated effort:** 2+ sessions — split into subtasks below without separate issue files.
|
||||
|
||||
| Subtask | Owner package | Deliverable |
|
||||
|---|---|---|
|
||||
| Validator audit primitive | `packages/validator/` | Teacher-forced prefill, TOPLOC verify, unit tests with stub tensors |
|
||||
| Node runtime commitments | `packages/node/` (if prover-side) | On-demand activation fingerprint generation on audit-selected requests |
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/validator/meshnet_validator/__init__.py` — `_run_reference`, `_outputs_match` (~92–148)
|
||||
- `packages/validator/README.md` — deterrence math (update for 19× at p=0.05)
|
||||
- Research: `.scratch/alpha-hardening/research-verifiable-inference.md` §8 layers 1–2, build-vs-adopt table
|
||||
|
||||
Pin one canonical precision/quantization per model preset. Add `toploc` to validator (and node if prover-side) dependencies.
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: validator compares final text strings — fails on cross-GPU honest divergence (document expected).
|
||||
2. Green: stub activation tensors + TOPLOC proofs round-trip in unit test.
|
||||
3. Integration: reference node teacher-forces tokens; verify accepts honest proof, rejects swapped precision.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `toploc` dependency declared; `build_proofs_*` / `verify_proofs_*` wired
|
||||
- [ ] Validator re-runs claimed token sequence as prefill, not free generation
|
||||
- [ ] Model preset documents canonical dtype/quantization
|
||||
- [ ] README updated: 19× deterrence at 5% audit (research §1.1)
|
||||
- [ ] Tests with deterministic stub tensors (no GPU required in CI)
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0018](../../docs/adr/0018-fraud-detection-verification-and-reputation.md) §2
|
||||
- Research: [research-verifiable-inference.md](../research-verifiable-inference.md) §8, §9 build-vs-adopt
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `05-a1-a5-persist-strike-ban-reputation.md`
|
||||
|
||||
**Prod gate:** do not enable production audit thresholds until `21-honest-noise-calibration-corpus.md` completes (see README Phase 2 note).
|
||||
@@ -0,0 +1,35 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 07 — FRAUD: On-demand commitment + hop bisection blame
|
||||
|
||||
## What to build
|
||||
|
||||
On audit selection, require nodes to supply TOPLOC-style fingerprints of **output boundary activations** per hop (on-demand, brief retention). On verify failure, referee identifies the **first divergent hop** — not always the last text node.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/validator/meshnet_validator/__init__.py` — `_slash_route`, `_final_text_node` bug (~102–140) — blames `max(shard_end)` only
|
||||
- `packages/tracker/meshnet_tracker/server.py` — route hop construction (~1774–1783) — cut-points for bisection
|
||||
- Research: `.scratch/alpha-hardening/research-verifiable-inference.md` §1.2, §8 layer 3 (Verde **pattern**, not on-chain game)
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: two-hop route, corrupt hop-0 activations — `_final_text_node` blames hop-1 — test must fail.
|
||||
2. Green: bisection selects hop-0; forfeit targets hop-0 wallet.
|
||||
3. On-demand: commitment requested only when audit flag set on proxied request.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Audit requests carry tracker RNG/VRF flag indistinguishable from normal traffic (research §6)
|
||||
- [ ] Nodes retain recent boundary activations for on-demand commit window (configurable TTL)
|
||||
- [ ] Validator/tracker compares fingerprints at each hop cut-point; first mismatch = culprit
|
||||
- [ ] `_final_text_node` removed or limited to text-only fallback
|
||||
- [ ] Integration test: multi-hop pipeline, fault injected at known hop
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0018](../../docs/adr/0018-fraud-detection-verification-and-reputation.md) §3–4
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `06-fraud-toploc-integration.md`
|
||||
@@ -0,0 +1,39 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 08 — FRAUD: Reputation model + persistence
|
||||
|
||||
## What to build
|
||||
|
||||
Implement graduated reputation per ADR-0018 §6: score derives only from tracker audit outcomes + uptime/latency. Slow build, instant loss, inactivity decay. ×0.8 routing multiplier per strike (not whole penalty — forfeiture stays full pending).
|
||||
|
||||
**Scope split:** issue 05 owns **schema + SQLite persistence**; this issue owns **scoring rules** (deltas, decay, strike→multiplier wiring) on top of persisted fields.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/contracts/meshnet_contracts/__init__.py` — extend `RegistryWallet` / persistence from issue 05
|
||||
- `packages/validator/meshnet_validator/__init__.py` — `_slash_route` forfeiture path (~125–133)
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `forfeit_pending` (~280–292)
|
||||
- Research: `.scratch/alpha-hardening/research-verifiable-inference.md` §6
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: no reputation field — add schema + default 1.0 for new wallets.
|
||||
2. Green: clean audit +0.05 (tunable); failed audit −0.3 and strike; three strikes → ban persisted.
|
||||
3. Inactivity decay after N days without completed jobs.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `reputation_score` persisted in registry SQLite (issue 05)
|
||||
- [ ] Audit pass/fail updates score with documented deltas
|
||||
- [ ] Strike applies ×0.8 multiplier to routing weight (separate from forfeiture amount)
|
||||
- [ ] Ban at 3 strikes; probation job count still enforced
|
||||
- [ ] No peer-to-peer reputation inputs
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0018](../../docs/adr/0018-fraud-detection-verification-and-reputation.md) §6
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `05-a1-a5-persist-strike-ban-reputation.md`
|
||||
- `07-fraud-commitment-bisection-blame.md` (audit outcomes feed reputation)
|
||||
@@ -0,0 +1,38 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 09 — FRAUD: Reputation-weighted routing + adaptive audit rate
|
||||
|
||||
## What to build
|
||||
|
||||
Wire reputation into route selection and audit sampling. Default network audit budget ≈5% — **not a cap**. New/low-reputation nodes: 20–30% audit rate; veterans: 2–3% floor ≥2%. Tripwires escalate rate without direct punishment.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/server.py` — route selection `_select_route`, `_effective_throughput` (~1747, routing helpers)
|
||||
- `packages/validator/meshnet_validator/__init__.py` — `sample_rate=0.05`
|
||||
- Research: `.scratch/alpha-hardening/research-verifiable-inference.md` §1.1, §6, §8 layers 2–4
|
||||
|
||||
Audit selection must be unpredictable at request time (tracker RNG after commitment window opens).
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: uniform 5% sample regardless of reputation — test expects higher rate for low-reputation wallet.
|
||||
2. Green: budget balancer keeps fleet-wide average ≈ configured target.
|
||||
3. Routing prefers higher reputation among equal throughput candidates.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Per-wallet audit probability function of reputation (newcomer high, veteran low, floor ≥2%)
|
||||
- [ ] Fleet-wide audit budget configurable (~5% default target); over ≥1000 requests with fixed seed, measured fleet audit rate within **±1.0 percentage point** of configured target (e.g. 4.0–6.0% at 5% default)
|
||||
- [ ] Route scoring includes reputation multiplier (earnings scale with tenure)
|
||||
- [ ] Passive tripwire flags (perplexity/repetition) bump audit rate only
|
||||
- [ ] Tests: deterministic seed for sampling distribution checks
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0018](../../docs/adr/0018-fraud-detection-verification-and-reputation.md) §1, §6–7
|
||||
- [ADR-0013](../../docs/adr/0013-rolling-stats-smart-routing.md)
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `08-fraud-reputation-model-persistence.md`
|
||||
@@ -0,0 +1,42 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 10 — FRAUD: Penalty calibration wiring (forfeit + strike + ban)
|
||||
|
||||
## What to build
|
||||
|
||||
End-to-end wiring: confirmed audit failure → atomic pending forfeiture + strike + reputation decay + audit-rate snap to max. Ensure payout cannot race penalty (ADR-0015). Document 19× deterrence math in validator README.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/validator/meshnet_validator/__init__.py` — `_slash_route` (~102–134)
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_billing_forfeit` (~2429–2464)
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `forfeit_pending` (~280–292), payout exclusion for banned (~3337–3344 in settlement loop)
|
||||
- `packages/validator/README.md` — update 20× → 19× at p=0.05
|
||||
|
||||
Per ADR-0018: **full pending forfeiture** is primary penalty; ×0.8 is routing decay per strike, not partial forfeit.
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: integration from issue 34 — extend with multi-hop blame wallet from issue 07.
|
||||
2. Green: node with pending balance → audit fail → pending zero, strike++, banned on 3rd, excluded from next settlement.
|
||||
3. Settlement loop skips banned wallets (~3337–3344).
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Audit failure triggers forfeiture + strike in one tracker transaction
|
||||
- [ ] Banned nodes excluded from `payables` / settlement
|
||||
- [ ] Validator uses authenticated forfeit endpoint (issue 02)
|
||||
- [ ] README: `L > 19× g` at p=0.05; pending balance = collateral
|
||||
- [ ] Integration test: 60-request fraud scenario → ban within threshold
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0018](../../docs/adr/0018-fraud-detection-verification-and-reputation.md)
|
||||
- [ADR-0015](../../docs/adr/0015-usdt-custodial-settlement.md)
|
||||
- Research: [research-verifiable-inference.md](../research-verifiable-inference.md) §1.1
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `07-fraud-commitment-bisection-blame.md`
|
||||
- `08-fraud-reputation-model-persistence.md`
|
||||
- `02-a2-unified-auth-boundary.md`
|
||||
@@ -0,0 +1,37 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 11 — C6: Wallet binding ownership proof + binding overwrite safety
|
||||
|
||||
## What to build
|
||||
|
||||
`POST /v1/wallet/register` binds a client Solana wallet to an API key for deposit attribution. Today any Bearer key can bind any wallet string without proving ownership. Prevent hijack and accidental overwrite.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_handle_wallet_register` (~2625–2648)
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `bind_wallet` (~153+), `_wallet_bindings` / direct overwrite on apply (~351)
|
||||
|
||||
Require signed message from wallet pubkey (ed25519 via `cryptography` / solders). Reject rebinding without admin or signed release. Use explicit overwrite policy — today `~351` overwrites binding directly; gossip apply must reject conflicting binds instead of silently clobbering.
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: bind wallet A with only API key, no signature — must fail after fix.
|
||||
2. Red: wallet already bound to key1; key2 cannot steal without proof.
|
||||
3. Green: valid signature binds; deposit watcher credits correct API key.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Wallet binding requires cryptographic proof of pubkey ownership
|
||||
- [ ] One wallet → one API key (or documented admin override)
|
||||
- [ ] Gossip `bind` events cannot overwrite existing binding via direct overwrite at `~351`
|
||||
- [ ] Tests with deterministic keypairs (local adapter)
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0017](../../docs/adr/0017-tracker-authentication-and-authorization.md) §5
|
||||
- [ADR-0015](../../docs/adr/0015-usdt-custodial-settlement.md)
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `02-a2-unified-auth-boundary.md`
|
||||
- `03-c5-starting-credit-zero.md`
|
||||
@@ -0,0 +1,29 @@
|
||||
Status: ready-for-human
|
||||
|
||||
# 12 — C2: On-chain settlement idempotency (deferred)
|
||||
|
||||
## What to build
|
||||
|
||||
Harden payout idempotency so Solana transaction retries never double-pay. Design accepted in ADR-0019 §1; **implementation deferred post-alpha**.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/server.py` — `_settlement_loop` resend (~3331–3356), `_send_settlement` (~3358–3376)
|
||||
- `packages/contracts/meshnet_contracts/solana_adapter.py` — `send_payouts` (~186–213)
|
||||
|
||||
Today: pending debited before broadcast with stable `settlement_id`; unconfirmed batches resent. Gap: on-chain confirmation vs ledger state if tx succeeds but confirm fails.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `confirm_settlement` only after RPC finalized confirmation
|
||||
- [ ] Retry path reuses same `settlement_id` and detects already-confirmed signature
|
||||
- [ ] Property test: N retries → single on-chain transfer per wallet per settlement_id
|
||||
- [ ] Document recovery procedure for stuck unconfirmed batches
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0019](../../docs/adr/0019-money-path-consistency-multi-tracker.md) §1
|
||||
|
||||
## Blocked by
|
||||
|
||||
Alpha release (ADR-0016 single settlement tracker)
|
||||
@@ -0,0 +1,31 @@
|
||||
Status: ready-for-human
|
||||
|
||||
# 13 — C3/C4: Consensus-gated money mutations (deferred)
|
||||
|
||||
## What to build
|
||||
|
||||
Route money-affecting ledger events through Raft commit, not gossip-only apply. Extend `raft.py` command set beyond register/deregister. Settlement remains leader-only with treasury key.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/server.py` — settlement leader gate (~3331–3332), payout batch (~3353–3356)
|
||||
- `packages/tracker/meshnet_tracker/raft.py` — log entry types (~26–27)
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `apply_events` (~301–311)
|
||||
|
||||
Design: ADR-0019 §2. **Deferred post-alpha** while single operator holds settlement.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `charge`, `payout`, `forfeit`, `credit`, `settlement`, `bind` commit via Raft log
|
||||
- [ ] Followers reject direct gossip money mutations
|
||||
- [ ] Leader-only `_settlement_loop` unchanged in semantics
|
||||
- [ ] Migration plan from gossip-only billing to Raft-backed log
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0019](../../docs/adr/0019-money-path-consistency-multi-tracker.md) §2
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `12-c2-on-chain-idempotency.md`
|
||||
- `14-a3-raft-durable-term-vote.md`
|
||||
@@ -0,0 +1,25 @@
|
||||
Status: ready-for-human
|
||||
|
||||
# 14 — A3: Durable Raft term and vote state (deferred)
|
||||
|
||||
## What to build
|
||||
|
||||
Persist Raft `currentTerm`, `votedFor`, and log metadata to disk. In-memory-only term (~26) risks split leadership after tracker restart → duplicate settlement epochs.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/raft.py` — `LogEntry.term` (~25–27), election state in `RaftNode`
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Term/vote persisted alongside tracker data dir
|
||||
- [ ] Restart resumes as follower/candidate with monotonic term
|
||||
- [ ] Test: kill leader mid-settlement, restart, no duplicate payout batch
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0019](../../docs/adr/0019-money-path-consistency-multi-tracker.md) §3
|
||||
|
||||
## Blocked by
|
||||
|
||||
Alpha single-settlement posture
|
||||
27
.scratch/alpha-hardening/issues/15-h1-commutative-forfeit.md
Normal file
27
.scratch/alpha-hardening/issues/15-h1-commutative-forfeit.md
Normal file
@@ -0,0 +1,27 @@
|
||||
Status: ready-for-human
|
||||
|
||||
# 15 — H1: Commutative forfeit event ordering (deferred)
|
||||
|
||||
## What to build
|
||||
|
||||
Define deterministic ordering when `forfeit`, `charge`, and `payout` events replicate concurrently. Forfeit snapshots amount at creation (~287) but apply order can desync pending balances under gossip.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `forfeit_pending` (~280–292), `_apply_locked` forfeit branch (~345–349)
|
||||
- `packages/tracker/meshnet_tracker/billing.py` — `_pending_since.setdefault` (~324), wallet bind direct overwrite (~351)
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Documented commit order: charges before forfeit before payout for same wallet epoch
|
||||
- [ ] Forfeit events carry pending snapshot or `(term, index)` for tie-break
|
||||
- [ ] `setdefault` replaced with explicit merge rules on out-of-order apply
|
||||
- [ ] Property tests under shuffled event delivery
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0019](../../docs/adr/0019-money-path-consistency-multi-tracker.md) §4
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `13-c3-c4-consensus-gated-settlement.md`
|
||||
@@ -0,0 +1,30 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 16 — DOC: US-006 reconciliation note
|
||||
|
||||
## What to build
|
||||
|
||||
Reconcile stale US-006 (Solana testnet stake contracts) with ADR-0015/0016 devnet custodial settlement. Issue `docs/issues/06-solana-stake-and-settlement.md` says "never devnet"; ADR-0015 explicitly targets devnet mock-USDT.
|
||||
|
||||
Also reconcile legacy fraud issues with the alpha-hardening fraud arc:
|
||||
|
||||
- `docs/issues/07-fraud-detection-slash.md` — on-chain stake slash model superseded by pending-balance forfeiture + TOPLOC (ADR-0018)
|
||||
- `docs/issues/34-forfeiture-penalty.md` — partially implemented; remaining fraud work lives in `.scratch/alpha-hardening/issues/06-fraud-toploc-integration.md` through `10-fraud-penalty-calibration-wiring.md`
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Add reconciliation comment atop `docs/issues/06-solana-stake-and-settlement.md` (Status: superseded for alpha — see ADR-0015, issue 33/34)
|
||||
- [ ] Add **superseded** banner atop `docs/issues/07-fraud-detection-slash.md` → ADR-0018 + issues 06–10
|
||||
- [ ] Add **superseded for remaining scope** banner atop `docs/issues/34-forfeiture-penalty.md` → ADR-0018 + issues 06–10 (note done items: basic forfeiture wired)
|
||||
- [ ] Update `docs/prd.json` US-006 description footnote if present
|
||||
- [ ] Cross-link ADR-0015 devnet decision
|
||||
- [ ] No production code changes
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0015](../../docs/adr/0015-usdt-custodial-settlement.md)
|
||||
- [ADR-0016](../../docs/adr/0016-alpha-scope-and-known-limitations.md)
|
||||
|
||||
## Blocked by
|
||||
|
||||
None
|
||||
@@ -0,0 +1,23 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 17 — DOC: Duplicate US-020 issue dedup
|
||||
|
||||
## What to build
|
||||
|
||||
Two files share the US-020 number with different slugs:
|
||||
|
||||
- `docs/issues/20-memory-budget-shard-slots-and-dropout-relocation.md` (ready-for-agent)
|
||||
- `docs/issues/20-tracker-node-hardening.md` (done)
|
||||
|
||||
Resolve numbering collision without losing history.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Document canonical mapping in this issue's Comments or a short `docs/issues/README.md` note
|
||||
- [ ] Renumber or prefix disambiguation (e.g. keep done item as US-020a, renumber memory-budget to next slot) — **human approval before git mv**
|
||||
- [ ] Update any prd.json / cross-links that reference US-020 ambiguously
|
||||
- [ ] No production code changes
|
||||
|
||||
## Blocked by
|
||||
|
||||
Human approval for renumbering
|
||||
@@ -0,0 +1,27 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 18 — DOC: Operational runbooks (stubs)
|
||||
|
||||
## What to build
|
||||
|
||||
Add operational runbook stubs for alpha operators under `docs/runbooks/` (or `.scratch/alpha-hardening/runbooks/` until close-feature):
|
||||
|
||||
1. **Ledger backup** — billing SQLite, accounts SQLite, registry DB paths; gossip pause procedure
|
||||
2. **Treasury key rotation** — devnet mock-USDT mint + treasury keypair rotation without double-credit
|
||||
3. **Upgrade path** — tracker rolling restart with persisted strike/reputation (post issue 05)
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Three markdown runbook stubs with prerequisites, steps, rollback
|
||||
- [ ] Reference ADR-0015 settlement loop and ADR-0016 trust assumptions
|
||||
- [ ] Secrets handling: never commit `.env.devnet`, keypairs
|
||||
- [ ] No production code changes
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0015](../../docs/adr/0015-usdt-custodial-settlement.md)
|
||||
- [ADR-0016](../../docs/adr/0016-alpha-scope-and-known-limitations.md)
|
||||
|
||||
## Blocked by
|
||||
|
||||
None (stubs can land before issue 05; update after persistence ships)
|
||||
@@ -0,0 +1,24 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 19 — DOC: Cryptography dependency + test environment note
|
||||
|
||||
## What to build
|
||||
|
||||
Document and verify test/dev environment setup for wallet crypto paths. `packages/node/meshnet_node/wallet.py` uses `cryptography`; failures occur when `.venv` lacks deps.
|
||||
|
||||
**Code refs:**
|
||||
|
||||
- `packages/node/pyproject.toml` — `cryptography>=41` (verify declared)
|
||||
- `packages/node/meshnet_node/wallet.py`
|
||||
- Handoff: tests fail without `cryptography`, `openai`, `langchain` in `.venv`
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Confirm `cryptography` in node package deps; add to root/dev extras if tests import wallet without node install
|
||||
- [ ] Add short **Test environment** section to `CONTRIBUTING.md` or `docs/dev/test-env.md`: use `.venv/Scripts/python.exe`, `pip install -e packages/node ...`, optional dep skips
|
||||
- [ ] Note which tests require optional deps (`--ignore=test_openai_gateway,...`)
|
||||
- [ ] No unrelated production code changes
|
||||
|
||||
## Blocked by
|
||||
|
||||
None
|
||||
@@ -0,0 +1,52 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 20 — Validator service token for `/v1/billing/forfeit`
|
||||
|
||||
## What to build
|
||||
|
||||
Define and implement a **validator service token** distinct from client API keys and admin sessions. The validator process must authenticate when calling `POST /v1/billing/forfeit`; arbitrary Bearer strings and client API keys must be rejected.
|
||||
|
||||
Per [ADR-0017 §4](../../docs/adr/0017-tracker-authentication-and-authorization.md): forfeit accepts **validator service identity or admin session** only.
|
||||
|
||||
## Configuration
|
||||
|
||||
| Item | Alpha default |
|
||||
|---|---|
|
||||
| Env var | `MESHNET_VALIDATOR_SERVICE_TOKEN` (tracker + validator) |
|
||||
| Config flag | `--validator-service-token` / tracker config file equivalent |
|
||||
| Header format | `Authorization: Bearer <service-token>` with a dedicated prefix or separate header scheme documented in runbooks (e.g. `Authorization: Service <token>` — pick one and test consistently) |
|
||||
| Rotation | Manual: set new token on tracker + validator, restart both; document zero-downtime rotation as post-alpha |
|
||||
|
||||
## Rejection rules
|
||||
|
||||
- Client API keys (`sk-mesh-…`) → **403** on forfeit (even if valid for inference)
|
||||
- Non-empty garbage Bearer → **401/403**
|
||||
- Missing auth → **401**
|
||||
- Valid validator service token → **200** (existing forfeit semantics)
|
||||
- Admin session → **200** (operator override)
|
||||
|
||||
## Test-first
|
||||
|
||||
1. Red: validator (or test client) posts forfeit with a valid API key — must fail after fix.
|
||||
2. Red: `Authorization: Bearer garbage` — must fail (covered by issue 02; this issue defines the accepted token).
|
||||
3. Green: configured service token succeeds; wrong token fails.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Service token configurable via env/flag on tracker and validator
|
||||
- [ ] Unified auth middleware resolves service token → `validator` role (issue 02)
|
||||
- [ ] API keys explicitly rejected on forfeit path
|
||||
- [ ] Integration test: validator client with service token forfeit succeeds; API key forfeit fails
|
||||
- [ ] Runbook stub: rotation procedure (manual alpha)
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0017](../../docs/adr/0017-tracker-authentication-and-authorization.md) §4
|
||||
|
||||
## Related
|
||||
|
||||
- `02-a2-unified-auth-boundary.md` — middleware + role checks
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `02-a2-unified-auth-boundary.md`
|
||||
@@ -0,0 +1,37 @@
|
||||
Status: ready-for-human
|
||||
|
||||
# 21 — Honest-noise TOPLOC calibration corpus
|
||||
|
||||
## What to build
|
||||
|
||||
Before enabling production TOPLOC audit thresholds, collect an **honest-noise baseline** across the heterogeneous volunteer fleet. Run identical inference jobs on every active node/GPU combo; measure the divergence envelope (TOPLOC exponent/mantissa deltas, logprob-rank spread) under real hardware variance.
|
||||
|
||||
Per [ADR-0018 consequences](../../docs/adr/0018-fraud-detection-verification-and-reputation.md): threshold calibration requires an honest-noise corpus across the fleet before production thresholds.
|
||||
|
||||
Research anchor: `.scratch/alpha-hardening/research-verifiable-inference.md` §8 layer 3 — "collect this first — run identical jobs across the current node fleet to measure the honest divergence envelope before setting thresholds."
|
||||
|
||||
## Deliverables
|
||||
|
||||
- [ ] Scripted benchmark job (fixed prompt, model preset, seed policy) runnable on all nodes
|
||||
- [ ] Aggregated corpus artifact (per node: GPU model, dtype, TOPLOC deltas vs reference)
|
||||
- [ ] Recommended tolerance thresholds documented (p99 honest envelope + safety margin)
|
||||
- [ ] Gate checklist: production audit enable blocked until corpus covers ≥N distinct hardware profiles (define N in runbook, suggest ≥3)
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] Corpus collected from current fleet (or documented subset + extrapolation note)
|
||||
- [ ] Threshold constants in validator config derived from corpus, not guessed
|
||||
- [ ] False-positive rate estimate documented at chosen thresholds
|
||||
- [ ] README / runbook cross-link: **do not enable production audits** until this issue closes
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0018](../../docs/adr/0018-fraud-detection-verification-and-reputation.md) — Consequences (honest-noise corpus)
|
||||
|
||||
## Blocked by
|
||||
|
||||
- `06-fraud-toploc-integration.md` (TOPLOC wired; calibration uses same primitive)
|
||||
|
||||
## Blocks (prod gate)
|
||||
|
||||
- Production enable of adaptive audit thresholds (issues 09–10 in prod)
|
||||
@@ -0,0 +1,21 @@
|
||||
Status: ready-for-agent
|
||||
|
||||
# 22 — DOC: MEMORY.md + project-status alpha-hardening index
|
||||
|
||||
## What to build
|
||||
|
||||
Update persistent memory files so agents and humans find the alpha-hardening feature without stale handoff paths.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] `.claude/memory/MEMORY.md` — index entry for alpha-hardening (`.scratch/alpha-hardening/`, ADRs 0016–0019, issue count)
|
||||
- [ ] `.claude/memory/project-status.md` — brief alpha-hardening section: planning complete, Bucket 1 blockers next, link README
|
||||
- [ ] Cross-link `.scratch/alpha-hardening/handoff.md` from README (not temp path)
|
||||
|
||||
## ADR links
|
||||
|
||||
- [ADR-0016](../../docs/adr/0016-alpha-scope-and-known-limitations.md)
|
||||
|
||||
## Blocked by
|
||||
|
||||
None — parallel with other Bucket 3 doc issues
|
||||
Reference in New Issue
Block a user