potatium/docs/HUB_WORKER_CLUSTER.md

Potatium Hub, Worker und Cluster: Architekturentwurf v0.4

Stand: 25.10.2026 | Produktentscheidung zum Paketmodell, Gebührenparameter weiterhin offen.

Begriffe und zugesagte Eigenschaften

Objekt	Was es ist	Wallet / Schlüssel	Funktion
Betreiber / Operator (operator_id)	manuell genehmigte Berechtigungs- und Wirtschaftsgruppe	besitzt eine oder mehrere Wallet-Adressen, aber keine serverseitige Master-Seed-Verwahrung	gemeinsame 90-Tage-PoP-Gewinnhistorie und Gebührenbasis
Hub (hub_id)	vollwertige Potatium-Node mit eigener kryptografischer Node-ID und eigenem lokalen Web-Cockpit	Wallet wird im Browser eingerichtet, signiert clientseitig; Hub-Backend hat keinen Seed/Private Key	Chain-/P2P-Teilnahme je Rolle, lokale UI/API, eigener optionaler PoP-Miner, Worker-Anbindung
Worker (worker_id)	schlanke, an Hub gekoppelte Mining-Instanz, z.B. Raspberry Pi/VM/PC	eigener Geräteschlüssel, keine Geld-Wallet, keine Wallet-Seeds	Challenge prüfen, begrenzte PoW-Arbeit, Proof signieren und via Hub fristgerecht einreichen
Validator (validator_id)	CometBFT-Konsensrolle	separater Validator-Schlüssel, kein Wallet-Key	Blockchain-Blöcke finalisieren, PoP-Lose nicht auswählen/produzieren
Auszahlungsadresse	explizit am Operator registrierte Wallet-Adresse	Private Key im Wallet-Client	empfangene PoP-Belohnungen aus Hub und Workern

Ein physischer Host kann mehrere Prozesse/Instanzen mit isolierter Konfiguration, Ports, Datenverzeichnissen und eigenen Schlüsseln betreiben. Das bedeutet nicht mehrere automatisch zugelassene Mining-Lose: nur ausdrücklich registrierte Mining-IDs zählen. Eine Node-ID beweist keine eigene Hardware und ein Operator-ID-Eintrag keine einzigartige natürliche Person.

Zwei Distributionspakete, drei Oberflächen

1. Potatium Hub: autonome, vollständige Node mit Web-Wallet-Bedienung, Explorer, eigener Mining-Funktion, lokaler Status- und Worker-/Cluster-Ansicht. Ist ohne Worker funktionsfähig. Ein Hub ist nicht zwingend Validator.
2. Potatium Worker: separater ressourcensparsamer Mining-Agent ohne vollständigen Chain-State und ohne eigenständige Geld-Wallet. Über einen Hub kontrollierbar. Ohne erreichbaren Hub kann er keine rechtzeitige Proof-Übermittlung garantieren. Lokale Setup-/Diagnoseoberfläche optional, aber kein vollständiger Node-Hub.
3. Potatium Admin: spätere Betreiberverwaltung (vorerst CLI), streng getrennt von normaler Hub-/Clusterverwaltung. Admin-Tool ist kein drittes Mining-Paket und nicht zum willkürlichen Ändern von Guthaben befugt.

                  Betreiber / operator_id [Registry]
                      |       Wallet im Browser
                      |       Auszahlung an registrierte Adresse
                Potatium Hub (autonom)
               Node/Explorer/Wallet/Mining
                  /       |         \
            Worker A  Worker B  Worker C
             Gerät-ID  Gerät-ID  Gerät-ID

    P2P/ABCI++ der Full-/Validator-Nodes bleibt getrennt
       vom Hub-Worker-Mining-Kontrollkanal.

Kopplung und lokale GUI

• Hub-GUI zunächst ausschließlich 127.0.0.1:<port> und SSH-Portforwarding; mehrere lokale Hub-Instanzen nutzen getrennte Ports und Datapaths. Später private HTTPS/VPN-Zugänge mit Login; keine öffentliche Admin-/RPC-Bind-Adresse per Default.
• Worker-Kopplung mit kurzlebigem, einmaligem Enrollment-Token oder signierter Einladung, QR-Code für Komfort und anschließend gegenseitiger kryptografischer Authentifizierung. Ein Fingerprint allein ist keine Autorisierung.
• Hub prüft Registrierungsstatus, Worker-Identität, Challenge/Runde/Fenster, Signatur, Zeitfenster, Nonce-Space und Duplikate vor Weiterleitung; die ABCI++-Anwendung muss dieselben Regeln unabhängig im Konsens durchsetzen.
• Worker kann unter Freigabe widerrufen oder zwischen Hubs desselben Betreibers umgezogen werden; identischer worker_id darf in derselben Runde nicht mehrfach abrechnen/teilnehmen.
• Hub-Ausfall: Worker-Status klar als nicht erreichbar/offline kennzeichnen, keine erfundenen Proofs/Gewinne. Backup-Hub und Failover sind spätere Funktionen und dürfen Tickets nicht duplizieren.
• Hub-Cluster-Dashboard verwaltet eigene authentifizierte Hubs und Worker; es hat keine Berechtigung, fremde Betreiber zu administrieren. Kein automatisches Wallet-Key-Sharing oder API-Server mit Seed-Phrase.

Mining-Teilnahme und gemeinsame Ökonomie

• Jede genehmigte Mining-Instanz, auch ein Hub mit aktivierter PoP-Rolle, kann maximal ein Ticket pro PoP-Gesamtrunde erhalten; die bestehende 3-Fenster-Logik gilt für jede Instanz.
• Beim Betreiber werden alle PoP-Gewinne seiner Mining-IDs während des später exakt spezifizierten ~90-Tage-Zeitraums zusammengeführt. Wallet-Transfers, Wechsel der Auszahlungsadresse und Worker-Umzug setzen den Fortschritt nicht zurück.
• Ein kostenloser Hub-Mining-Platz pro Operator ist die Arbeitsregel des Konzepts. Dieser Hub wird nicht in die Worker-Gebühr eingerechnet; er unterliegt trotzdem den normalen Fenster-2-/Fenster-3-Gebühren.
• Weitere physische Hubs dürfen technisch betrieben werden (z.B. Ausfallsicherheit). Sie erzeugen keinen zweiten kostenlosen Hub-Mining-Platz. Zusätzliche Mining-Identitäten gelten bei Kosten/Quoten wie Worker-Instanzen; eine bloße GUI-/Full-Node-Instanz ohne Mining zählt nicht.
• Sämtliche vom Operator zugelassenen Worker müssen in der verbindlichen Chain-Registry diesem Betreiber zugerechnet werden. Mehrere Hubs/Walletts dürfen keine getrennten kostenlosen Betreiberidentitäten simulieren. Beim kleinen privaten Netzwerk zunächst manuelle Betreiberzulassung und Audit; kryptografische Verhinderung von Sybil-Angriffen ist damit nicht erreicht.
• Die registrierte Auszahlungsadresse erhält sämtliche Hub-/Worker-Mining-Belohnungen des Betreibers. Eine spätere Änderung braucht signierte, replay-geschützte Autorisierung und eindeutige Wirksamkeitsgrenze. Zusätzliche Wallets für normale Transfers sind möglich, verändern aber Mining-Fee- und Betreiber-Identität nicht.

Zahlungsautorisierung ohne Wallet-Seeds auf Nodes

Mininggebühren (zusätzliche Fenster und eventuell Worker-Aktivierung) sind aus demselben Betreiber-Budget zu bezahlen. Eine dauerhaft online erforderliche Freigabe ist nicht praktikabel, wenn die Seed/Private Keys ausschließlich im Browser liegen. Vorgeschlagene Lösung: zweckgebundene, on-chain verbuchte Mining-Gebührenreserve je Operator. Befüllung/Rückzahlung signiert die Browser-Wallet; die deterministische App darf daraus ausschließlich die ausdrücklich begrenzten, berechenbaren Mining- und Worker-Gebühren belasten. Zusätzlich: Zeit-/Betragsobergrenzen, Sperrung/Widerruf, Audit und sichere Restguthaben-Rückgabe. Noch keine Implementierungsentscheidung; ein alternatives begrenztes signiertes Mandat ist möglich. Niemals Miner-/Node-/Worker-Schlüssel zu Wallet-Spend-Keys machen.

Operatives Cockpit vor Admin-Web

Hub lokal: Blockhöhe, Sync, Peers, Versions- und Ressourcenstatus, Wallet-Verbindung, PoP-Runde/Fenster/Tickets/Gewinne, Gebührenhistorie/Budget, Worker-Anmeldung/Freigabe/Pause, pro Worker CPU-/Fensterlimit, Fehler, einzelne Daten des eigenen Clusters.

Cluster-Sicht: mehrere zugeordnete Hubs/Worker in einer Übersicht mit Host-Status, Versionen, Mining-Modus, zentraler (aber begrenzter) Einstellungs-/Update-Orchestrierung; keine zentralen Wallet-Seeds und keine direkte Chain-State-Manipulation. Der eigenständige Hub bleibt immer einzeln bedienbar; Cluster-Sicht ist optional.

Admin (später): separate authentifizierte Betreiber-/Validator-/Miner-Registry, Revocation, Audit, koordinierte Upgrades, Netzwerkdiagnose. Zunächst sichere CLI ab dem Zeitpunkt, an dem diese Funktionen benötigt werden.

Kostenmodell und Sicherheitslücken

Siehe WORKER_GEBUEHREN_FORSCHUNG.md. Keine finalen Beträge. Für Worker-Aktivierungen ist Zahlung/Reservierung vor der unbekannten Challenge notwendig; sonst können schnelle Geräte nur erfolgreiche Versuche bezahlen. Keine Kosten für Worker, die gar nicht zur Runde angemeldet wurden. Festlegen, wie verpasste Runden, Downtime, Replay und Wiederanmeldung bilanziert werden.

Akzeptanzkriterien vor Implementierung

• Eigenständiger Hub funktioniert ohne Worker, Worker funktioniert nur gekoppelt; getrennte Keys/Rollen, keine Seeds auf Server.
• Zwei Worker mit eigenen ID-Schlüsseln lassen sich koppeln, sperren und eindeutig demselben Betreiber zuordnen.
• Pro ID/Runde höchstens ein gültiges Ticket, unabhängig von parallelen Prozessen/Hubs; Hub selbst als Mining-ID zählt.
• Gebühren/Rewards aggregieren operator_id, nicht Wallet-Adresse oder hub_id; Identitäts-/Wallet-Wechsel resetten keine Progression.
• Zusätzlicher Hub verschafft keinen zweiten kostenlosen Slot; Registry ist manuell und auditierbar.
• Zahlungssnapshot vor dem jeweiligen Challenge-Seed; verspätete und doppelte Aktivierungen abweisen.
• Funktionsfähige UI erst bei realer API; weder Mock-Balance noch Fake-Tickets als echt anzeigen.
• Deployment native linux/amd64 / linux/arm64 zuerst, Docker später optional, kein Docker im Entwicklungs-LXC.

Status: Dieses Dokument spezifiziert eine angestrebte Produktarchitektur. Kein Teil davon ist als bereits funktionierend zu betrachten.

Ergänzung v0.5: Abgrenzung zum Netzwerk-Admin

Der Teilnehmer-Cluster in einem Hub verwaltet ausschließlich die eigenen authentifizierten Hubs/Worker und verbindet niemals fremde Wallet-Private-Keys. Potatium Network Admin ist dagegen eine separate, von Projektbeginn geplante read-only Beobachtung des gesamten erreichbaren Chain-/Validatornetzes mit optional freigegebenen Node-Metriken. Er hat keine Workersteuerung fremder Betreiber, keine zentralen Blockchain-Schreibrechte und ist keine zusätzliche Chain-Infrastruktur, deren Ausfall Blöcke stoppt. Validatorbetrieb wird anfangs vom Projektbetreiber bereitgestellt. Technische Einzelheiten: docs/INFRASTRUKTUR_UND_DEPLOYMENT.md, docs/COCKPITS_UND_MONITORING.md, ADR 0006.

Netzwerkzugang und Betreiberrechte (aktueller ADR 0008)

Hubs benötigen zum P2P-Sync kein Benutzerkonto und keinen Pflichtdienst potatium-network; die lokale Konfiguration enthält überprüfte Chain-ID/Genesis und Seed-/Peer-Adressen. Eine separat autorisierte On-chain-Registry bestimmt, welche Betreiber-/Hub-/Worker-Mining-IDs Tickets einreichen dürfen. Betreiber können mehrere Hubs/Worker und eine gemeinsame Reward-Adresse besitzen. Weitere miningfähige Hubs zählen wirtschaftlich als zusätzliche Worker, nicht als neue kostenlose Betreiberplätze; Sybil-Limit nur durch nachvollziehbare manuelle Freigabe. Im Hub werden eigene Cluster- und Wallet-Daten gezeigt, im Network Admin globale Registry-/Supply-/Fonds-/Validatorübersicht. Identitätsfreigabe/-sperre: geschützte Admin-Signatur, on-chain finalisiert; keine zentralen DB-Flags. Gebühren: 100 % On-chain-Fonds, keine PoP-Burns. Siehe ADR 0008 und docs/NETWORK_ZUGANG_UND_IDENTITAETEN.md.