docs: update Potatium v0.6 architecture and PoP research

docs/INSTALLATIONSPLAN_HOMELAB.md

@@ -0,0 +1,150 @@
+# Potatium | Infrastrukturplan für das Homelab
+
+**Stand:** 25.10.2026  
+**Status:** Architektur- und Installationsplanung, keine Deployments nachgewiesen.  
+**Repository:** Ab Dokumentationsstand v0.6: aktueller Infrastrukturentwurf nach ADR 0008. Keine Deployments außerhalb des Entwicklungsgerüsts nachgewiesen; Ressourcen und Namen sind Planwerte.
+
+## 1. Zielbild
+
+Potatium besteht aus unabhängigen Validatoren und Full Nodes mit lokaler Blockchain-/Anwendungsdatenhaltung sowie optionalen Mining-Workern. Teilnehmer benötigen keine zentralen Konten, um die Blockchain zu synchronisieren. Für **Proof of Potato** ist jedoch eine **on-chain verwaltete Betreiber-/Mining-Registry** mit autorisierter Freigabe und Sperrung vorgesehen.
+
+```text
+                        POTATIUM-NETZWERK (privates Testnet)
+                +---------------------------------------------+
+                |  Validator 1   Validator 2                   |
+                |  Validator 3   Validator 4                   |
+                |  CometBFT + potatiumd/ABCI++ je Validator    |
+                |  Jeweils eigene Chain-DB, App-State und Keys |
+                +---------------------+-----------------------+
+                                      | P2P
+                 +--------------------+--------------------+
+                 |                                         |
+      Betreiber A: Hub A                       Betreiber B: Hub B
+      Full Node + WebGUI                       Full Node + WebGUI
+      lokale Wallet-Signatur im Browser        lokale Wallet-Signatur im Browser
+      eigener Miner optional                  eigener Miner optional
+           |         |                                 |
+       Worker 1   Worker 2                          Worker 3
+       PoP-Agent   PoP-Agent                        PoP-Agent
+
+      Netzwerk-Admin des Projektbetreibers:
+      liest Chain/Registry/Fonds/Protokollparameter, beobachtet Netz-Metriken;
+      genehmigt/sperrt Mining-Identitäten über gesondert autorisierte,
+      finalisierte On-chain-Aktionen (erst wenn Registry/Signatur existieren).
+      Admin-Ausfall stoppt nicht die Chain.
+```
+
+**Festgelegt:** Der Hub besitzt eine technische Node-Identität und bietet eine Wallet-Anbindung. Der private Wallet-Schlüssel verbleibt browserseitig und wird nicht an den Hub-/Admin-Server oder Worker übertragen. Ein Betreiber kann mehrere Hubs und Worker haben, mit einer gemeinsamen registrierten Reward-Adresse. Jeder zugelassene Hub-Miner/Worker kann ein eigenes PoP-Los pro Runde qualifizieren; Gebühren und 90-Tage-Mining-Historie werden pro Betreiber aggregiert. Ein Betreiber erhält höchstens einen kostenlos gezählten Hub-Mining-Platz, sofern das spätere Gebührenprotokoll diese Forschungsentscheidung formal übernimmt. Konkrete Gebühren und Obergrenzen sind **noch offen**.
+
+**Gebührenentscheidung:** 100 % der PoP-Fenster-/Worker-Gebühren werden auf einen On-chain-Community-Fonds gebucht, 0 % Burn dieser Gebührenarten. Normale Transaktionsgebühren und Fonds-Ausgaberegeln sind offen. `fund_balance` wird nicht zusätzlich zum Umlauf addiert.
+
+## 2. Maschinen und Ressourcen
+
+| Name/Rolle | Deploymentort | Initiales Ressourcenbudget (Schätz-/Planwert) | Software/Dienst | Daten |
+|---|---|---|---|---|
+| `potatium-dev` | Bestehender Proxmox-LXC Ubuntu 26.04, unprivilegiert | **Bereits geplante Basis:** 4 vCPU / 4 GB RAM / 40 GB | Git, Go, VS Code Remote-SSH, Test-/Simulationsskripte | Quellcode unter `/home/potatium/src/potatium`; Simulationen/Testdaten getrennt |
+| `ptm-devnet` | Anfangs weitere Prozesse im `potatium-dev`-LXC | Bestehende Ressourcen, bei Druck erweitern | 1× CometBFT + 1× Potatium-ABCI-App | eigene Test-Genesis, Chain-State, Konsensschlüssel |
+| `ptm-hub-test` | Anfangs separater Prozess im `potatium-dev`-LXC | Kein zusätzlicher LXC erforderlich, Ressourcen messen | Full Node (Nichtvalidator), Potatium-API, Hub-WebGUI, Wallet-Frontend | eigene Chain-/App-Daten; Wallet-Key nur clientseitig |
+| `ptm-admin` | Anfangs eigener Prozess im Dev-LXC; später **separater Management-LXC** | Später als Startbudget etwa 1–2 vCPU / 1–2 GB RAM / 10–20 GB, zu messen | Network-Admin-Web + lesende Datenerfassung; später autorisierte Registry-Freigaben | optional SQLite nur für Monitoring-/Audit-Historie, **kein** Ledger |
+| `ptm-val01` bis `ptm-val04` | Für frühe Tests getrennte Prozesse/VMs; später verschiedene physische Ausfallbereiche | **Pro Validator als Planwert:** ca. 2 vCPU / 2–4 GB RAM / 30–60 GB, erst Benchmarks entscheiden | CometBFT + `potatiumd`-ABCI-App | jeweils eigene Chain-DB, State, Node-/Konsensschlüssel |
+| `ptm-hub-*` | Teilnehmer-VM, Pi oder alter PC | Pi 4 als Mindestziel; konkrete Messwerte offen | Full Node + WebGUI + optional lokaler Miner | eigene Chainkopie, Node-ID, Konfiguration |
+| `ptm-worker-*` | RPi/Alt-PC/VM | leichtgewichtig; Budget erst durch echte PoP-Benchmarks | `potatium-miner` und Hub-Verbindungsconfig | nur Geräte-ID, Mining-/Pairing-Konfiguration, **keine** Chain-DB oder Wallet-Spend-Keys |
+
+**Ressourcen sind nicht als gemessene Mindestanforderungen auszugeben.** Für vier Validatoren auf einem einzelnen physischen Proxmox-Host gibt es **keine physische Redundanz**. Für einen realistischen Ausfalltest Validatoren auf getrennte physische Hosts/Standorte verteilen. CometBFT kann mit vier gleichgewichteten Validatoren einen ausgefallenen Validator tolerieren; bei zwei Ausfällen ist kein >2/3-Quorum mehr vorhanden.
+
+## 3. Komponenten je Installationspaket
+
+| Paket/Rolle | Enthält | Ohne das Paket möglich? |
+|---|---|---|
+| Hub | CometBFT-Full-Node + Potatium-App-/API, Hub-WebGUI, Browser-Wallet, optional lokaler PoP-Miner | Worker braucht seinen Hub; Hub benötigt keinen Worker |
+| Worker | PoP-Rechenagent, eigener Mining-Key, Pairing/Status | Kein vollständiger Chain-Speicher, keine Auszahlung-Wallet |
+| Validator | CometBFT mit Konsensschlüssel + Potatium-ABCI-App | Netzwerk benötigt ausreichend aktive Validatoren für neue Blöcke |
+| Network Admin | Chain-/Fonds-/Parameterübersicht, Registry-Detailansicht, Netzdiagnose; später signierte Freigaben/Sperren | Blockchain läuft ohne Admin weiter |
+
+Hub-/Worker-Pakete sind **Zielpakete**, noch keine fertig gebauten Releases. Native amd64/arm64 zuerst, optionale Docker-/Compose-Pakete später; Entwicklungs-LXC bleibt ohne Docker. Eine Validator-Node ist auch ein Node, aber nicht jede Full Node ist Validator.
+
+## 4. Phase für Phase installieren
+
+### Jetzt: Bestehenden Entwicklungs-LXC nutzen
+
+- [ ] Proxmox-LXC `potatium-dev` und SSH-Zugang prüfen (kein neuer Server nötig).
+- [ ] Ubuntu 26.04, Go-Toolchain, Git, VS Code Remote-SSH / Codex und privates Git-Remote nach aktuellem Projektstand prüfen/einrichten.
+- [ ] `/home/potatium/src/potatium` als Git-Arbeitsverzeichnis; keine Chain-Daten oder Schlüssel committen.
+- [ ] Simulationspakete außerhalb des produktiven Chain-States testen. Keine echten PTM erzeugt.
+- [ ] Netzplan, zugelassene Ports und Backupstrategie definieren.
+
+### M2: Erstes lauffähiges isoliertes Devnet
+
+- [ ] Eine Potatium-ABCI-App und CometBFT als einzelner Validator mit **eigenem Devnet-Genesis** starten.
+- [ ] Eine getrennte Hub-Full-Node mit eigener Datenhaltung und tatsächlicher Netzwerkverbindung starten.
+- [ ] Hub-WebGUI und Wallet-Basisfunktionen mit tatsächlichen Testdaten anbinden; Wallet-Key bleibt browserseitig.
+- [ ] **Read-only Network Admin von Anfang an** mit echten Statusdaten von Devnet/Hub anbinden: Chain-ID, Blockhöhe, finale Blöcke, Validatorstatus, Synchronisierung, Angebot an registrierten IDs soweit verfügbar.
+- [ ] Nicht implementierte Metriken ausdrücklich als `nicht verfügbar` kennzeichnen; keine Fake-Bestände oder Fake-Transaktionen.
+- [ ] Von Beginn an eigene Chain-ID/Genesis, Datenverzeichnisse und Secrets; Test-PTM können zurückgesetzt werden.
+
+### M3: Lokales Vier-Validatoren-Netz
+
+- [ ] Vier CometBFT+App-Instanzen mit **vier verschiedenen Validator-Schlüsseln**, eindeutigen Ports und getrennten Datenverzeichnissen.
+- [ ] Netz/State-Synchronisierung, App-Hash, 3-von-4-Quorum, Ausfälle/Neustarts testen.
+- [ ] Eine Nichtvalidator-Hub-Full-Node als echter Peer.
+- [ ] Network Admin überwacht vier Validatoren und zeigt verlässlich Quorum-/Synchronisationsdaten.
+
+### M4: Proof of Potato und Identitäten
+
+- [ ] Operator-/Mining-Registry als protokollvalidierter Chain-State.
+- [ ] Hub/Worker-Schlüssel und sichere Kopplung; eine qualifizierte Ticketberechtigung je Mining-ID und Runde.
+- [ ] **Admin-Identitätsübersicht ab Start**, autorisierte Freigabe/Sperre/Key-Rotation erst mit implementierter Registry-Signatur/Verifikation.
+- [ ] Wallet-autorisierte, begrenzte On-chain-Gebührenbudgets statt Wallet-Spend-Key auf Hub/Worker.
+- [ ] 100 % Gebührenziel On-chain-Fonds, nachvollziehbare Mint-/Supply-/Burn-/Fund-Bilanz.
+- [ ] Ein echter Worker auf Pi/Alt-PC und mindestens ein Hub-Miner.
+
+### M5/M6: Mehrhost-Privat-Testnet und später permanentes Netz
+
+- [ ] Vier Validatoren auf physisch getrennte Ausfall-Domänen, idealerweise verschiedene Hosts.
+- [ ] `ptm-admin` in eigenem geschützten Management-LXC, optional Monitoring-Historie in SQLite; keine zentrale Pflicht-DB.
+- [ ] Hub-Pakete und Worker-Pakete als native Release-Binaries; Docker nur optional später.
+- [ ] P2P-Bootstrap über signiertes/verifiziertes Netzwerkmanifest bzw. verwaltete Seed-/Persistent-Peer-Liste, **ohne** zentralen Web-Registrierungsdienst.
+- [ ] Sicherheits-/Crash-/Restore-/Langzeittests, danach getrennte Genesis/Chain-ID für dauerhaftes Netz.
+
+## 5. Network Admin: Was du sehen und ändern darfst
+
+| Daten | Quelle | Cockpit-Recht |
+|---|---|---|
+| Erzeugte PTM, Burn, Umlaufmenge, Fondsbestand | Potatium-App-State/Chain, verifizierte API | Lesen |
+| Aktive Protokollparameter, Gebühren und Runden | On-chain-Konfiguration/aktuelle Chain-Daten | Lesen |
+| Letzte Blöcke, Finalität, Validatorquorum, Peers | CometBFT RPC/Metriken, Potatium-API | Lesen |
+| Registrierte Betreiber- und Mining-IDs, Zuordnungen, Freigabe-/Widerrufstatus | On-chain-Registry | Lesen, Detailansicht |
+| Antrag/Signierte Freigabe, Sperre, Schlüsselwechsel | Validierte on-chain Verwaltungsaktion | **Gezielt erlaubte Schreibaktion** nach gesonderter Authentisierung |
+| Bekannte und „kürzlich aktive“ Hubs/Worker | On-chain-Registry + optional signierte Heartbeats | Lesen, **Verfügbarkeitsstatus mit Zeitstempel** |
+| Guthaben fremder Wallets verändern / Coins frei erzeugen / Gebühren beliebig umstellen | Keine autorisierte Funktion | **Nie** |
+
+**Globale Online-Zahl ist ohne Telemetrie nicht exakt messbar.** Eine Validator-Peer-Liste zählt nur direkt sichtbare Peers. Der Admin darf unterscheiden zwischen `registriert`, `zuletzt gesehen`, `online laut Heartbeat`, `nicht gemeldet`. Freiwillige signierte Heartbeats können an einen optionalen Monitoring-Sammler gesendet werden; dessen Ausfall darf weder Mining noch Blockchain-Betrieb stoppen.
+
+Wichtig: Emission/Fondsstatus als On-chain-Daten sind technisch von anderen Full Nodes rekonstruierbar. Nur die Admin-Oberfläche ist exklusiv; auf Chain gespeicherte Daten sind nicht allein durch UI-Rechte vertraulich.
+
+## 6. Daten und Backup
+
+**Keine zentrale Ledger-Datenbank.** Jeder Validator und jeder Full-Node-Hub hat sein eigenes CometBFT-Datenverzeichnis und seine eigene persistente Potatium-App-State-Datenbank. Auswahl der Embedded-DB (bbolt/Pebble o. ä.) steht noch aus. Das Admin-Cockpit darf optional SQLite als Monitoring-Cache nutzen, aber keine Quelle für Kontostände oder Mining-Rechte sein.
+
+Strikte Trennung für `devnet`, `testnet` und permanentes Netz inklusive Keys, Chain-IDs, Genesis, Verzeichnissen und Backups. Validator-Consensus-Key und Signierzustand besonders sichern; nicht denselben Schlüssel auf zwei aktiven Validatoren gleichzeitig einsetzen. Wallet-Seeds niemals im Server, Logs, Datenbankcache oder Git speichern. Recovery und Restarts testen, bevor echte dauerhafte Netzwerke in Betrieb genommen werden.
+
+## 7. Netzwerk-/Portkonzept
+
+CometBFT-Beispieldefaults laut Upstream-Konfiguration: P2P `26656/TCP`, RPC `127.0.0.1:26657`, ABCI-App-Verbindung `127.0.0.1:26658`, Prometheus-Metriken häufig `26660`, aber standardmäßig nicht zwingend aktiviert. **Dies sind keine verbindlichen Potatium-Ports.** Mehrere Instanzen auf einem Host brauchen pro Dienst separate Listen-Adressen/Ports.
+
+- P2P zwischen ausdrücklich erlaubten Peers im privaten Netzwerk oder über VPN und Firewall.
+- RPC, ABCI, Metrics sowie Admin-Web standardmäßig nur Loopback beziehungsweise über kontrollierte lokale Proxys/VPN-Verbindungen; niemals unnötig öffentlich.
+- Hub-GUI beispielhaft `127.0.0.1:8080`, Admin-GUI `127.0.0.1:8090` (beides **Vorschläge**, nicht implementiert).
+- Vom Arbeitsplatz aus SSH-Portforwarding, keine GUI-Desktop-Installation im LXC.
+- Kein eigenständiger Bootstrap-Dienst nötig, solange erreichbare Seed-/Persistent-Peers und eine authentische Netzwerk-Konfiguration verfügbar sind.
+
+## 8. Was noch nicht feststeht
+
+- CometBFT-/Go-Version und konkrete ABCI++-Prozesskopplung, Embedded-KV-DB, echte Hardware-Minimums.
+- Chain-IDs, feste Ports/Hostnamen, Adress-/Schlüssel-/Signaturformate, Restore-Mechanik.
+- Betreiber-ID-/Mining-ID-Freigabeprotokoll inklusive Offline-/Admin-Signatur und Auditdetails.
+- Gebührenhöhe für 1–10 Worker sowie Fenster 2/3; Ergebnisse der laufenden dynamischen PoP-Simulation stehen aus.
+- Fonds-Auszahlungsregeln und Transaktionsgebühren.
+- Telemetrie/Heartbeat-Protokoll, Datenschutz/Retention und ob SQLite benötigt wird.
+
+**Nächster Schritt:** Laufende Dynamik-/Fondssimulation auswerten, anschließend die Repo-Dokumentation (insbesondere `docs/NETWORK_SERVICES_UND_ONBOARDING.md`, ADR 0007, ROADMAP, INFRASTRUKTUR) konsistent auf die vereinfachte Architektur ohne verpflichtenden `potatium-network`-Registrierungsdienst bringen. Keine tatsächlichen Installationen oder Code-Funktionen als abgeschlossen markieren.