151 lines
14 KiB
Markdown
151 lines
14 KiB
Markdown
# 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.
|