# Potatium: Gesamtinfrastruktur, Datenhaltung und Deployment **Status: akzeptierte Ziel- und Betriebsarchitektur, nicht implementiert. Stand: 25.10.2026.** Siehe ADR 0006. Der tatsächliche Git-Stand hat Vorrang. Die konkreten CometBFT-Versionen, Datenbank, Ports, Service-Prozesse und API-Schemata sind erst bei der Implementierung verbindlich festzulegen. Alle hier genannten Namen für Deployments und Adressen sind Beispiele, keine bereits laufenden Dienste. ## Grundsatz: Kein zentraler Blockchain-Master Eine funktionierende Chain erfordert aktive CometBFT-Validatoren und die eigene deterministische Potatium-ABCI++-Anwendung. Jeder Full-/Validator-Node verwaltet lokal eine eigene konsistente Kopie der Chain beziehungsweise des Anwendungszustands. **Keine gemeinsame SQL-Datenbank, kein zentraler Coin-Server, kein Admin-Cockpit als Konsensabhängigkeit.** ```text Devnet / privates Testnet / dauerhaftes Netz (getrennte Chain-IDs) +--------------------------------------------------------------+ | VAL-1 VAL-2 VAL-3 VAL-4 | | CometBFT + Potatium-App + je eigener lokaler State | | signieren und finalisieren Blöcke per Konsens | +-----------------------------+--------------------------------+ | authentisches P2P/Chain-Protokoll +-------------------+-------------------+ | | HUB Betreiber A HUB Betreiber B Full Node + API + lokale WebGUI Full Node + API + WebGUI optional PoP-Miner optional PoP-Miner Wallet-Signatur NUR im Browser Wallet-Signatur NUR im Browser | | | Worker A1 Worker A2 Worker B1 eigener Mining-Key, keine Full-Chain, keine Wallet-Keys \\ // Read-only Network Admin (geschuetztes Monitoring) liest gesicherte Messwerte / Chainabfragen; keine Coins optional eigene Messdatenbank, NICHT Konsens-State ``` Die logische Hub-Worker-Kopplung ist **nicht** das CometBFT-P2P-Netz. Ein Hub ist eine Full Node und kann optional die Validatorrolle besitzen, aber ein normaler Worker ist weder Validator noch Full Node. Ein Betreiber kann mehrere Hubs kontrollieren; ein Hub kann ohne Worker laufen. Dasselbe physische Gerät kann technisch mehrere sauber getrennte Prozesse ausführen, ohne neue Hardwareidentitäten zu beweisen. ## Rollen, Prozesse und Eigentum | Rolle | Betreibt wer? | Binär-/Dienstkonzept | Lokale Daten | Muss online sein? | |---|---|---|---|---| | Dev-Host | Projektbetreiber | Git, Go, Tests, Devnet-Prozesse | Quellcode und *separate* Test-Chains | Nur zur Entwicklung | | Validator | Anfangs Projektbetreiber, später mögliche genehmigte Mitbetreiber | CometBFT + `potatiumd`-ABCI++-App | eigene Chain- und App-Daten, sensibler Konsensschlüssel | Für Blockproduktion benötigt: >2/3 Stimmmacht aktiv | | Hub | jeweiliger Potatium-Betreiber | CometBFT als Nichtvalidator + Potatium-Go-App/API + WebGUI + optional lokaler Miner | eigene kopierte Chain, App-State, Node-Key und lokale Hub-Config | Für eigene Wallet-Abfragen/Worker-Mining erreichbar | | Worker | jeweiliger Betreiber | schlanker `potatium-miner`-Agent, dem Hub zugeordnet | Mining-Geräteschlüssel und sichere lokale Einstellungen, **keine Chain-DB/Spend-Keys** | Nur bei Teilnahme | | Wallet | Benutzer im Browser, unabhängig von Node-Persistenz | Web-Wallet | verschlüsselte clientseitige Schlüssel, Backups in Verantwortung des Benutzers | Nein | | Network Admin (read-only) | zunächst allein Projektbetreiber | kleines Go-Observability-Backend + Browser-Ansicht; genaue Verpackung offen | Monitoring-Inventar, optionale Historie/Cache | **Nein, ohne Admin läuft Chain weiter** | | Registry-Admin (später) | berechtigter Betreiber | geschützte CLI / später getrennte Web-Admin-Aktionen | Admin-Autorisierungsnachweise, Audit | Nur für Verwaltungsänderungen | **Sicherheitsgrenzen:** `node_id`/P2P-Key, Validator-Consensus-Key, `operator_id` + Operator-Verwaltungsschlüssel, `mining_id`/Worker-Key sowie Wallet-Spend-Key sind unterschiedliche Rollen. Ein Fingerprint identifiziert einen öffentlichen Schlüssel, erteilt allein keine Berechtigung. Validatoren und Monitoring erhalten keine Wallet-Seeds. Mehrere Wallet-Adressen sind möglich, aber verändern die `operator_id`-Mining-Historie nicht. Reward-Auszahlungsadresse ist an die registrierte Betreiberidentität gebunden; Schlüssel für Wallet-Transaktionen bleiben im Browser. ## Was läuft wo? ### Stufe 0: Entwicklung und erster Devnet-Start - Bestehender Host: Proxmox, unprivilegierter Ubuntu-26.04-LXC `potatium-dev`, 4 vCPU / 4 GB RAM / 40 GB als **Startgröße**. IDE bleibt lokal via Remote-SSH. Kein Docker-in-LXC, keine Server-GUI installieren. - Repository: `/home/potatium/src/potatium`. Daten gehören **außerhalb von Git**, z. B. `/home/potatium/.local/share/potatium/devnet/` für zukünftige Devnet-States. Pfad ist ein *Vorschlag*, noch nicht implementiert. - Erst ein Validatorprozess + zugehörige Potatium-ABCI-App für den ersten echten Konsens-Test. Separat ein Hub/API/Wallet und **vom Beginn des Devnets an** Network Admin read-only; auf demselben LXC nur soweit Ressourcen reichen, Prozesse und Ports klar getrennt. - Beim allerersten UI-Gerüst ohne laufende Chain: ehrliche „nicht verbunden / keine echten Daten“-Anzeige, keine Mock-Balance oder erfundenen Blöcke. - Devnet darf nach explizitem Backup/Bestätigung zurückgesetzt werden. Ausschließlich wertlose Test-PTM, eigene Chain-ID und Genesis. ### Stufe 1: Realistisches lokales Testnetz - Vier logisch getrennte Validatoren mit eigenen Datenverzeichnissen und Konsensschlüsseln. Initial dürfen sie zu Testzwecken auf einem Host/mehreren VMs laufen, **nicht als echte physische Redundanz ausgeben**. - Hub als eigener Full-Node-Prozess (kein Validator erforderlich), Worker auf separatem Pi/Alt-PC; echtes Peer- und API-Verhalten testen. - Network Admin zeigt alle vier Validatoren, Höhen-Abweichung, letzte Finalisierung, Peer-Verbindungen, Versionen, Block-/Tx-Rate, App-Hash-Abgleich und Ausfälle. Unbekanntes/Offline getrennt anzeigen. - Test-Coins über Devnet-Genesis, später begrenztes Faucet, niemals als „echte PTM“ ausgeben. ### Stufe 2: Mehrhost-Privat-Testnet - Vier Validatoren auf **verschiedenen Ausfall-Domänen**, idealerweise getrennten Hosts (VMs können praktikable Betriebsform sein; nicht alle auf demselben Proxmox-Host). Zunächst betreibst du sie, später optional andere vertrauenswürdige Teilnehmer. Operator-Hubs laufen auf eigenen VMs/PCs; Worker nativ auf Pi/Alt-PC. - Read-only Network Admin kann auf separater kleiner Management-VM laufen. Für ein kleines Netz optional mit lokaler persistenter SQLite-Kennwert-Historie oder nur In-Memory; Datenbanktyp noch offen. **Kein** zusätzliches zentrales Chain-Backend. - Netzwerkzugriff über private, authentifizierte Verbindungen; keine öffentlichen Admin-, CometBFT-RPC-, ABCI- oder Metrics-Ports. P2P-Peers nur gezielt freischalten. Monitoring remote vorzugsweise über kontrollierte Read-only APIs/privates VPN oder Push-Metriken, nie mit pauschalen Betriebssystem-Root-Zugängen. ### Stufe 3: Dauerhaftes privates Potatium-Netz - Neue eigene Chain-ID/Genesis, dauerhafte State-Daten, dokumentierte Validator- und Backup-Strategie. Devnet und Testnet bleiben getrennt. **Keine automatische Migration/Einlösung der Test-PTM**. - Der Network Admin bleibt nur Beobachter. Registry-/Validator-Änderungen erfordern gesondert definierte, signierte Autorisierung und Konsensverarbeitung; nie freie SQL-Updates gegen den Ledger. - Native `linux/amd64` und `linux/arm64` zuerst. Docker/Compose als **optionale spätere Deployment-Form** für Hub/Worker/Admin, nicht als Pflicht und nicht innerhalb des Entwicklungs-LXC. ## Datenspeicherung: Wo ist die Datenbank? 1. **CometBFT-Speicher jeder Full Node:** Blöcke, Konsens-/Peer- und Indexdaten je nach Konfiguration. Unabhängig pro Instanz. 2. **Potatium-App-State jeder Full Node:** Konten/Nonces, Genesis, `operator_id`-/`mining_id`-Registry, Runden, Gebühren-Snapshots, Tickets, Mint/Burn-/spätere Gebührenverteilung, signaturgeschützte Status-Änderungen; deterministischer State-Hash. Eingebetteter KV-Speicher wird erst nach Vergleich (z. B. bbolt vs. Pebble) und ADR gewählt. 3. **Wallet im Browser:** verschlüsseltes lokales Key-Material, lokal signierte Transaktionen; keine Spend-Keys in 1, 2 oder Network Admin. Ein Wallet kann mehrere Hubs beobachten, aber privater Schlüssel ist nicht automatisch über Geräte/Browsersessions synchronisiert. 4. **Monitoring-Speicher:** optionaler Index/Cache/Time-Series für Metriken, Events, Node-Inventar, Alarmhistorie. Autorität ist immer die Blockchain und die echte Node-API, niemals der Monitoring-Cache. 5. **Worker-Speicher:** Geräteidentität, Hub-Kopplung, sichere Retry-/Diagnosezustände; keine vollständige Blockchain, keine Finanz-Wallet. `bbolt`, `Pebble`, `SQLite`, `Prometheus` sind **Kandidaten**, nicht ausgewählte produktive Implementierungen. Die Anwendungs-DB muss crash-/restart-sicher, atomar und zur ABCI++-Commit-Semantik passend sein. Keine Float-Mengen in Konsenszustand. ## Netzwerkkonnektivität und Beispiele | Kommunikationsweg | Zweck | Sicherheitsregel | |---|---|---| | Validator ↔ Validator | P2P, Block-/Konsensnachrichten | gezielte authentifizierte Peers; keine offen zugänglichen RPCs | | Hub ↔ Validator/Peer | P2P, State-Sync, Transaktionsverbreitung | Full Node verarbeitet eigene Chainkopie | | Wallet-Browser ↔ Hub-API | Status, Wallet-Lesen, signierte Transaktionen | Browser signiert; API erhält niemals Private Key/Seed | | Worker ↔ Hub | Challenges, Proofs, Status, Workersteuerung | signierter Worker-Key + kurzlebige Kopplung, privater Transport | | Network Admin ↔ autorisierte Nodes | Beobachtung von Status und Metriken | read-only, explizit freigegebene Daten; Ausfall darf Konsens nicht stoppen | | Betreiber Admin-CLI → Chain | später Registry-/Validator-Änderungen | getrennte autorisierte signierte On-chain-Aktionen | **Ports sind Konfigurationsdetails, nicht Identitäten.** Auf einem Host werden Prozessports und Datenverzeichnisse getrennt; Initialbetrieb bindet Management-RPCs und Cockpit an `127.0.0.1`, Zugriff per SSH-Forwarding. Echte verteilte Hosts benötigen private, authentifizierte Verbindungen und einen gezielten Firewall-Plan. Portwerte bei Implementierung mit konkreten CometBFT-Versionen dokumentieren. ## Was passiert bei Ausfällen? - **Network Admin offline:** nur Monitoring weg, Chain arbeitet unverändert weiter. - **Hub offline:** zugeordnete Worker können nicht zuverlässig melden; Wallet kann zu einem anderen vertrauenswürdigen Full-Node-Endpunkt wechseln, sofern verfügbar; keine automatischen Schlüsseltransfers. Multi-Hub-Failover für Worker bleibt offen. - **Worker offline:** nur dessen Mining-Beitrag entfällt, keine Auswirkung auf Blockkonsens. - **Validator offline:** bei 4 gleich gewichteten Validatoren toleriert die Chain einen Ausfall, bei zwei ist der notwendige >2/3-Konsens nicht erreichbar. - **App-State beschädigt/abgehängt:** lokale Nodes neu synchronisieren oder verifizierte Backups/Snapshots wiederherstellen. Dafür vor echtem Einsatz Restore-Test und keine gemeinsame DB als „Single Point of Failure“. ## Testbare Mindestkriterien - Devnet mit einer echten Validator-Instanz, bestätigtem AppHash und realem Blockfortschritt; Hub zeigt dieselbe Höhe, Network Admin bestätigt sie lesend. - Leere/ungültige Chain-Verbindung in beiden Cockpits klar gekennzeichnet, niemals Mockwerte als Echtgeld/Testcoin-Bestände. - Vier Validatoren: einer offline => weitere Finalisierung (mit genügend Stimmgewicht); zwei offline => keine Finalisierung; Neustart / App-Hash-Vergleich. - Wallet/Hub/Worker/Admin sind getrennte Sicherheitsdomänen; Schlüssel- und Datentrennung mit Negativtests belegen. - Admin-Dienst kann abgestellt werden, ohne Konsens oder Wallet-Signaturpfad zu verändern. - Keine persistente zentrale Datenbankabhängigkeit für Blockchain-Fortschritt; Snapshot-/Backup-Restore reproduzierbar. ## Offene Entscheidungen CometBFT-/Go-Version und Prozessintegration, konkrete Embedded-DB, Genesis/Chain-ID-Regeln, DB-Transaktions-/ABCI-Commit-Grenze, Validator-Anzahl und Stimmmacht im Dauernetz, Konsensschlüsselverwahrung, Monitoring-Stack, Datenaufbewahrung, API-Scope/Transport, öffentliche Knoten-Erreichbarkeit, Statusmetriken, Alert-Regeln, Gebührenempfänger und Coin-Emission. **Gebührenempfänger für PoP-/Worker-Gebühren ist durch ADR 0007 auf 100 % On-chain-Fonds festgelegt. Normale Transaktionsgebühren und Fonds-Auszahlungen sind noch offen.** ## Korrigierte Betriebsentscheidung (ADR 0008): Zentral nur die Beobachtung, wenn gewünscht **Kein verpflichtender zentraler Registrierungs-/Bootstrap-Service `potatium-network`.** Der Projektbetreiber deployt zunächst ausschließlich den bestehenden `potatium-dev`-LXC, darauf getrennte Devnet-Prozesse (CometBFT+App, synchronisierender Hub, read-only Network Admin), sobald die Implementierung existiert. Hubs nutzen lokale Chain-ID-/Genesis-/Peer-Vertrauensanker; P2P-Discovery und unabhängige Validatoren bilden die Chain. Eine signierte On-chain-Registry steuert Mining-Rechte. Optionaler Telemetrie-/Admin-History-Store ist kein Ledger/Registrierungs-Master und braucht keinen separaten SQL-Server. Sobald tatsächliche Multi-Host-Tests starten, vier Validatoren auf getrennten Hosts/VMs (physische Ausfalldomänen beachten); ein optionaler eigener `ptm-admin`-LXC ist später reine Betreiberbequemlichkeit. **Freigabe/Sperre** als einzige frühe schreibende Admin-Aktionen sind gegen validierte Registry-Regeln zu signieren und on-chain zu finalisieren, nicht per SQL/GUI direkt. **100 % der PoP-Fenster-/Worker-Gebühren gehen an den On-chain-Fonds**, 0 % Burn; Fonds-Ausgabeordnung weiterhin offen. Ausführlicher Plan: `docs/INSTALLATIONSPLAN_HOMELAB.md`; Netzwerkzugang: `docs/NETWORK_ZUGANG_UND_IDENTITAETEN.md`; Entscheidung: ADR 0008.