potatium/docs/INSTALLATIONSPLAN_HOMELAB.md

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.

                        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.