docs: update Potatium v0.6 architecture and PoP research

docs/INFRASTRUKTUR_UND_DEPLOYMENT.md

@@ -0,0 +1,127 @@
+# 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.