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.

                 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?

CometBFT-Speicher jeder Full Node: Blöcke, Konsens-/Peer- und Indexdaten je nach Konfiguration. Unabhängig pro Instanz.
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.
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.
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.
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.

14 KiB Raw Blame History