docs: update Potatium v0.6 architecture and PoP research

This commit is contained in:
Michael Böhmländer committed 2026-10-25 11:45:32 +00:00
1 parent 75df8a5c0d
commit 862ccf1d03
34 files changed
+3257 -18

No files matched your search

@@ -0,0 +1,41 @@
# ADR 0007: Zentrale Network Services als Control Plane und 100 % PoP-Gebühren an On-chain-Fonds
> **Entscheidungsverlauf, Stand v0.6:** Die verpflichtende zentrale `potatium-network`-Control-Plane und ein Registrierungsportal sind durch [ADR 0008](0008-schlanker-netzzugang-admin-und-identitaeten.md) **aufgehoben**. Unverändert gelten das frühe Hub-/Network-Admin-Monitoring, die On-chain-Mining-Registry und 100 % PoP-/Worker-Gebühren für den Fonds. Historische Abschnitte unten dokumentieren den früheren Stand.
**Datum:** 2026-10-25
**Status:** Akzeptiert als Produkt-/Betriebsprinzip, **nicht implementiert**. Details zu Login, Registry-Transaktionen, Signaturformat, Fonds-Auszahlungen, Tarifen offen.
**Präzisiert:** ADR 0005/0006; **ersetzt die Burn-Verwendung für PoP-/Worker-Gebühren aus ADR 0003**, nicht dessen drei Mining-Fenster oder Ticketregeln.
## Kontext
Im privaten Potatium-Netz ist die dezentrale P2P- und Konsensinfrastruktur nicht automatisch eine bequeme Zugangsverwaltung. Neue Betreiber benötigen authentische Bootstrap-Informationen, einen Registrierungsantrag und eine nachvollziehbare manuelle Genehmigung. Der Netzwerkbetreiber braucht gleichzeitig eine vollständige registrierte Node-Liste und einen lesenden Gesamtüberblick, ohne Datenbanken als Konsensquelle einzuführen. Aggressive PoP-Gebühren-Burns entziehen der geplanten geschlossenen Hobby-Ökonomie Liquidität.
## Entscheidung
1. Zentral betriebene **Potatium Network Services** (Arbeitstitel `potatium-network`) als **Control Plane** für signierte Bootstrap-Konfiguration, Registrierungsvorgänge, Betreiber-/Geräteinventar und Telemetrie; ein geschütztes **read-only Network Admin**-Dashboard ist von Beginn des nutzbaren Devnets an Bestandteil. Für eingeschriebene Benutzer ist keine zentrale Online-Authentisierung je Blockchain-Transaktion erforderlich.
2. Der zentrale Dienst führt **keine Coin-Datenbank** und kontrolliert keine Blockproduktion. CometBFT-Validatoren und Full Nodes replizieren den maßgeblichen Ledger und genehmigte Betreiber-/Mining-Identitäten auf Chain. Eine zentrale DB darf nur Anträge, Kontaktdaten nach Minimalprinzip, Beobachtungen und Status-Caches enthalten.
3. **Authentisierung getrennt:** Wallet-Spend-Key bleibt im Browser; `operator_id`, Node-P2P-Key und Mining-/Worker-Key sind andere Schlüsselrollen. Ein Besitzer kann mehrere Hubs/Worker und eine gemeinsame registrierte Reward-Wallet verwenden. Ein Fingerprint allein erlaubt keine Registrierung. Zentraler Antrag benötigt Besitznachweis, Mining-Zulassung erst nach signiertem, finalisiertem On-chain-Verwaltungsakt. Initial manuelle Freigabe mit gesonderter CLI, kein Web-Superuser zum Ledger.
4. **Bootstrap:** `chain_id`, vertrauenswürdiger Genesis-Hash, signiertes Manifest und Seed-/Persistent-Peer-Liste; Node synchronisiert **P2P direkt**, nicht per zentraler Coin-API. Netz darf private VPN/Peer-Zulassung verwenden. Mehrere unabhängige Seed-Kontaktpunkte/Fallback sind vorzusehen.
5. **100 % der PoP-Fenster-2-/3- sowie Worker-Aktivierungsgebühren fließen an den deterministischen, On-chain gebuchten Community-Fonds; 0 % Burn für diese Kategorien.** Fondsausgaben benötigen eigene, noch zu spezifizierende Governance/Autorisierung. Normale Transaktionsgebühren bleiben separat offen. Tarife/Emission bleiben offen. `burned_total` wird nicht gelöscht, aber PoP-/Worker-Gebühren erhöhen ihn nicht. Der Fonds wird **nicht** zusätzlich zum Umlauf addiert.
6. Bereits registrierte Betreiber und Validatoren bleiben ohne zentralen Dienst funktionsfähig, solange ausreichend P2P/Quorum, Hub und Finanzierung vorhanden sind; Registrierungs-Portal und gesamtnetzweites Monitoring fallen ggf. aus. Admin-Ausfall ist **kein Chain-Stopp**.
7. Das normale Hub-UI zeigt nur das eigene Node-/Wallet-/Cluster-Inventar und freigegebene öffentliche Netzwerkdaten. Registrierte Betreiber-Geräte, Fonds-/Supply-Details, alle beobachtbaren Nodes, Host-Status und Pending-Anträge bleiben **im Betreiber-Admin**.
## Alternativen
- **Nur Peer Discovery/ohne Benutzerverzeichnis:** einfach, aber im privaten Netz unpraktische Zulassung, schlechtes Inventar und schwache Administrierbarkeit.
- **Zentraler Coin-Server mit SQL-Guthaben:** abgelehnt, unterläuft Blockchain-Finality und schafft Single Point of Failure.
- **Zentraler Login für jeden Block/Miner-Ticket:** abgelehnt, schafft unnötige Betriebsabhängigkeit und Zensurpunkt.
- **Automatische Freigabe durch Wallet-Fingerprint:** abgelehnt, Sybil-/Geräteproblem ungelöst.
- **PoP-/Worker-Gebühren weiterhin verbrennen:** gegenüber 100-%-Fonds verworfen; Burn-Forschung bleibt als Vergleich dokumentiert.
## Konsequenzen
M1: Signatur-/Registry-/Bootstrap- und Fonds-Buchungsmodell spezifizieren, den zentralen Dienst und den Local-App-Store getrennt auswählen. M2: minimalen Network Services/Bootstrap-Dienst mit echtem read-only Network Admin und Hub-Status anbinden; M3: mehrere echte Peers/Seeds und Validatoren; M4: Antrags-/Genehmigungsworkflow und on-chain PoP-Registry, Worker-Registrierung, Gebührenfonds, Negativtests. M5/M6: gesicherter Betreiberbetrieb, Monitoring-Historie, Backup, Redundanz und Recovery. Die Anmeldung/Registrierung ist **nicht gleich** Wallet-Erstellung und **nicht gleich** P2P-Handshake.
## Noch offen
Operator-Signaturschema, Challenge/Response, Portal-Sitzungen, Minimal-Personendaten/Aufbewahrung, private P2P-Netz-Zugangspolitik, exaktes Enrollment-/Revocation-Format, Verantwortlichkeiten mehrerer Admins, Governance/Fonds-Ausgaben, Backend-Technologie (SQLite möglicher Kandidat), Ports, Zertifikatserneuerung, Relaying-/NAT-Szenarien und Sybil-Grenze. Keine der offenen Entscheidungen in Code hineinraten.
**Referenz:** `docs/NETWORK_SERVICES_UND_ONBOARDING.md`, `docs/INFRASTRUKTUR_UND_DEPLOYMENT.md`, `docs/COCKPITS_UND_MONITORING.md`.
**Vertraulichkeitsgrenze:** Die Betreiber-WebGUI darf exklusiv sein; **On-chain-Fakten (Emission, Fondsbestand, Gebühren und ggf. öffentliche Registry) sind für technisch versierte Betreiber eigener Full Nodes grundsätzlich selbst abfragbar**. Ein UI-Verbot schützt keine Blockchain-Daten. Nicht-öffentliche Betreiber-Kontaktinformationen, unveröffentlichte Geräteadressen und vollständige Heartbeat-/Host-Inventare gehören ausschließlich in die geschützte Off-chain-Control-Plane. Wenn diese Daten wirklich geheim bleiben sollen, **nicht** auf eine für Full Nodes replizierte Chain schreiben.