docs: update Potatium v0.6 architecture and PoP research

docs/HUB_WORKER_CLUSTER.md

@@ -0,0 +1,90 @@
+# 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.
+
+```text
+                  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`](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`.