# 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.