tasks

docs/adr/0002-dual-token-payment-model.md

@@ -0,0 +1,11 @@
+# Dual token payment model: own token for nodes, SOL/USDC for clients
+
+Clients pay in SOL or USDC — familiar, easy to buy, no new token required. Node operators stake and earn our native Solana L2 token, which creates speculative upside for early contributors and a staking mechanism for fraud prevention (slashing). The two are decoupled: client payments are auto-converted to partially fund token rewards; clients never need to hold or know about our token.
+
+Using SOL alone would give node operators no early-adopter upside ("why run my GPU for market-rate SOL?"), killing the viral growth mechanic. Launching a token-only system requires clients to acquire our token, adding friction that kills adoption. The dual model solves both.
+
+## Considered Options
+
+- **SOL only**: simplest, no token launch risk, but no node incentive beyond spot market rates
+- **Own token only**: maximum node incentive, but clients must acquire it — high friction
+- **Own token (stake/rewards) + SOL/USDC (client pay)**: clean separation of concerns, chosen

docs/adr/0003-optimistic-fraud-detection.md

@@ -0,0 +1,14 @@
+# Optimistic trust with stake slashing and strike-based bans
+
+All inference responses are trusted by default. Validators re-run a random sample (~5%) of requests on reference nodes and compare outputs. Nodes that fail are slashed (stake reduced). Enough strikes result in a permanent on-chain ban.
+
+New wallets must complete N jobs without earning (probationary period) to raise the economic cost of re-entering after a ban — a banned node can't just create a new wallet and immediately cheat again; it must fund a new stake and contribute N free jobs first.
+
+zkML (zero-knowledge proofs of inference) would give cryptographic guarantees but is 1000–10000× slower than inference for large models and is not production-ready. Redundant execution consensus (Gensyn's approach) gives stronger guarantees but costs 2–3× compute per request. TEE (trusted hardware attestation) is cryptographically strong but excludes most consumer GPUs, defeating the viral GPU-sharing goal. Optimistic + slash is the pragmatic choice that ships and can be calibrated economically.
+
+## Considered Options
+
+- **zkML**: cryptographically perfect, not production-ready for large models in 2025
+- **Redundant consensus**: strong guarantees, 2-3× compute cost per request
+- **TEE attestation**: strong guarantees, excludes consumer GPUs
+- **Optimistic + slash + strike ban**: chosen — ships, works, economically tunable

docs/adr/0004-hybrid-tracker.md

@@ -0,0 +1,11 @@
+# Hybrid tracker: centralized routing + P2P gossip, Solana as source of truth
+
+The tracker runs as a centralized service (we operate it) for fast, optimizable inference routing and node scoring. Nodes also gossip state via a lightweight P2P layer so the network degrades gracefully if the tracker is unavailable. Critically, Solana smart contracts are the authoritative source for stake balances, slash events, strike counts, and bans — the tracker can read this state but cannot modify it, preventing us from manipulating payouts even if we control the routing layer.
+
+A pure DHT (like Petals uses) makes latency-aware routing and ban enforcement significantly harder to implement correctly. A purely centralized tracker is a single point of failure and a regulatory target. The hybrid gives us fast routing now with a clear path to decentralization as the network scales.
+
+## Considered Options
+
+- **Pure DHT**: resilient, harder to build good routing and enforce bans
+- **Centralized only**: simple, single point of failure, we could manipulate payouts
+- **Hybrid (centralized + P2P gossip, Solana authoritative)**: chosen

docs/adr/0005-shard-distribution.md

@@ -0,0 +1,5 @@
+# HuggingFace bootstrap + P2P propagation for shard distribution
+
+When the tracker assigns a node a new shard, the node downloads it from HuggingFace (or our seed servers as fallback). Once downloaded, the node joins the P2P shard swarm for that shard and seeds to other nodes that need it. Popular shards propagate virally; new shards bootstrap from HF.
+
+This mirrors how BitTorrent works in practice: a seed server provides the first copy, P2P takes over distribution as the swarm grows. Having nodes bring their own weights (manual download) makes tracker-driven shard rebalancing impossible — you can't instruct a node to switch shards if it doesn't have the weights. Pure P2P with no bootstrap source means the first node for any shard has nowhere to download from.

docs/adr/0006-openai-compatible-api.md

@@ -0,0 +1,7 @@
+# OpenAI-compatible REST API as the primary client interface
+
+The gateway exposes an OpenAI-compatible REST API (`/v1/chat/completions`, `/v1/models`, etc.) so any existing application using the OpenAI SDK can switch to our network by changing one line (`base_url`). LangChain, LlamaIndex, Open WebUI, and thousands of other tools work immediately with zero code changes.
+
+A `meshnet` SDK wraps the OpenAI-compatible interface and exposes network-specific controls: wallet top-up, redundancy level, node selection hints, cost estimates, and streaming earnings. Clients who don't need these features never interact with the SDK.
+
+A custom-protocol-only API would require every adopter to rewrite their existing LLM integrations, killing day-one adoption.