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,42 @@
# ADR 0008: Schlanker P2P-Netzzugang, On-chain-Identitäten und frühes Betreiber-Cockpit
**Datum:** 2026-10-25
**Status:** **Akzeptierte Produkt-/Betriebsentscheidung, nicht implementiert.**
**Ersetzt teilweise:** ADR 0007 (verpflichtende zentrale `potatium-network`-Registrierungs-/Bootstrap-Control-Plane). **Bestätigt ausdrücklich:** ADR 0007: 100 % PoP-Fenster-/Worker-Gebühren an On-chain-Fonds, 0 % Burn dieser Gebühren.
## Anlass
Der Projektbetreiber will keine Benutzerplattform, keine zentrale Passwort-/Wallet-Datenbank und keine überflüssigen zentralen Dienste. Gleichzeitig soll ein privates Netzwerk einsehbar und Mining-Identitäten manuell kontrollierbar sein. Die bisherige verpflichtende Registrierungs-Control-Plane aus ADR 0007 würde diese Anforderungen unnötig verkomplizieren.
## Verbindliche Entscheidung
1. **P2P-Zugang ist nicht Benutzerregistrierung.** Ein Hub bekommt lokal eine überprüfbare Chain-ID, Genesis-Prüfsumme und Seed-/Persistent-Peer-Konfiguration. Nodes synchronisieren Blockchain direkt über CometBFT. Kein `potatium-network`-Dienst, Login, zentrale SQL-Datenbank oder Online-Genehmigung für regulären Blockchain-Sync zwingend.
2. **On-chain-Mining-Registry bleibt Pflicht für PoP.** Betreiberidentität (`operator_id`), öffentliche Hub-/Worker-/Mining-Schlüssel, Betreiberzuordnung, eine registrierte Reward-Adresse, Berechtigung, Sperr-/Widerrufsstatus und Audit sind deterministisch im Chain-State. Eine lokale `node.toml` o. Ä. kann Identitäten angeben, **aber keine eigene Berechtigung herbeikonfigurieren**. Kopieren von Schlüsseln, VMs oder Wallets erzeugt nicht automatisch neue gültige Tickets.
3. **Freigaben und Sperren sind die einzigen frühen schreibenden Betreiberfunktionen.** Ein Betreiber/Worker liefert einen öffentlichen Schlüssel mit Besitznachweis; der Netzwerkbetreiber prüft Anträge/Schlüssel zunächst manuell und autorisiert On-chain-Verwaltungsaktionen mit separater geschützter Signierinstanz/CLI. Sobald ausreichend abgesichert, darf das Admin-Cockpit den Freigabe-/Sperrvorgang **auslösen**, aber die schreibende Freigabe ist nie eine reine DB-Flag-Änderung. Das genaue Signatur-/Rechteschema und die Übermittlung sind M1/M4-Protokollaufgaben. Keine pauschalen Ledger-Admin-Sonderrechte.
4. **Network Admin ab erstem lauffähigen Devnet, Hub-Cockpit parallel.** Getrennter Betreiberzugang. Das Betreiber-Cockpit liest Chain-ID, Blockhöhe, Validatoren, bestätigte Emission, verbrannte Gesamtmenge, Fondsbestand und Bewegungen, Gebühren- und Fensterparameter, Betreiber-/Mining-Registry, angemeldete IDs/Status. Keine Fake-Werte. Identitätsverwaltung zeigt den Antrags-/Genehmigungszustand, sobald der jeweilige Datenpfad existiert. Bei noch nicht implementiertem State ehrlich „nicht verfügbar“.
5. **Statuszählungen trennen:** on-chain registriert ≠ P2P-kürzlich beobachtet ≠ signiert meldend ≠ tatsächlich minend. Globales Live-Inventar ist ohne freiwillige signierte Heartbeats oder eine dedizierte Beobachtungsinfrastruktur nicht vollständig. **Optionaler Telemetrie-/Inventarspeicher** (z. B. SQLite) ist zulässig, aber keine Pflicht und nicht Konsensquelle. Datenherkunft, Messzeit und Abdeckungsgrad immer ausgeben.
6. **Hub und Worker** bleiben die zwei Teilnehmerpakete. Hub = eigenständige Full Node mit lokaler Node-/Cluster-GUI, Web-Wallet mit browserseitigen Spend-Keys und optionalem Miner. Worker = an Hub gebundener schlanker Mining-Agent mit eigenem Mining-Key, ohne Full-Chain-/Spend-Key. Gemeinsam zugelassene Betreiber-Einnahmen und -Gebühren, maximal ein Ticket je zugelassener Mining-ID und Runde. Höchstens ein kostenloser Hub-Mining-Platz je genehmigtem Betreiber; Sybil-Risiko bleibt ohne manuelle Prüfung.
7. **Fonds**: 100 % der PoP-Zusatzfenster- und Workergebühren werden dem on-chain Fonds zugeschrieben. Fondsausgaben, Tarif- und Transaktionsgebührenentscheidung weiterhin offen. Das Admin-Cockpit darf nicht eigenmächtig Fonds-PTM transferieren.
8. **Deployments:** zuerst `potatium-dev` allein mit isolierten Devnet-Prozessen; später getrennte Validatoren und nach Bedarf geschützter `ptm-admin`-LXC. Weder die Administration noch ein optionale Statussammler darf Konsens/PoP-Gültigkeit blockieren. Native VM/Pi zuerst, Docker optional später.
## Alternativen
- Pflichtdienst `potatium-network` für Anmeldung/Bootstrap/Mining: **verworfen** (unnötiger Single Point of Failure und Nutzerverwaltung).
- Nur lokale Node-Konfiguration für PoP-Rechte: **verworfen** (beliebig vermehrbare Node-/Mining-IDs).
- Volle Web-Administration ab Projektstart: **verworfen** (Signatursicherheit nicht ausreichend spezifiziert); reine Beobachtung plus begrenzte genehmigende/sperrende Aktion sobald kryptografisch korrekt.
- Zentraler Ledger/SQL-Master: **verworfen**.
## Akzeptanzbedingungen
- Hub synchronisiert über mehrere bootstrapfähige Peers, auch wenn Network Admin offline ist; authentischer Genesis-/Chain-ID-Abgleich.
- Ohne finale On-chain-Freigabe kein Ticket, Sperre wirkt ab spezifizierter Höhe; Replay/Double-Enroll/Schlüsselkopie mit Negativtests behandeln.
- Admin-Ansicht zeigt reale Supply-/Burn-/Fund-/Registry-Werte, Datenquelle, Blockhöhe, Messzeit, Stale-Zustand; nie simulierte Live-Werte.
- Signierende Admin-Schlüssel niemals im lesenden Webserver, im Hub oder Worker; signierte Admin-Aktionen auditieren.
- Operator-/Wallet-/Node-/Worker-/Validator-Schlüssel getrennt, keine privaten Wallet-Schlüssel auf Servern.
- Keine zentrale Datenbankänderung kann Guthaben, PoP-Registry, Fonds oder Validatorzustand ersetzen.
## Offene Implementierungsparameter
Kompatible CometBFT-Version, Embedded-State-DB, Ports, Go-API, Operator-Schlüsselschema, pairing/binding-Verfahren, Admin-Signaturschema, On-chain-Antragstransport, IP/Peer-Schutz, vollständige Telemetrie, Wallet-Integration, Rücksetzbarkeit des Devnets. Keine Werte durch einen Codegenerator eigenmächtig entscheiden.
**Referenzen:** `docs/NETWORK_ZUGANG_UND_IDENTITAETEN.md`, `docs/COCKPITS_UND_MONITORING.md`, `docs/INSTALLATIONSPLAN_HOMELAB.md`, `docs/POP_DYNAMIK_FONDS_AUSWERTUNG_2026-10-25.md`.