docs: update Potatium v0.6 architecture and PoP research

2026-10-25 11:45:32 +00:00
1 parent 75df8a5c0d
commit 862ccf1d03
@@ -0,0 +1,42 @@
+# ADR 0006: Validator-Infrastruktur, getrennte Datenspeicherung und Cockpits ab Devnet
+
+> **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:** Produkt-/Betriebsarchitektur akzeptiert; technische Komponenten und Ports offen
+
+## Kontext
+
+Der Projektbetreiber möchte nachvollziehen, welche Komponenten er neben Entwickler-LXC, Teilnehmer-Hubs und Workern selbst deployen muss. Gleichzeitig sollen Betreiber und Teilnehmer **vom ersten lauffähigen Devnet an** echte Statusinformationen erhalten. ADR 0005 plante Admin-Web zunächst später; das gilt für **schreibende Verwaltung**, nicht mehr für read-only Beobachtung.
+
+## Entscheidung
+
+1. Keine zentrale Blockchain- oder Coin-Datenbank. Potatium benötigt aktive **CometBFT-Validatoren**, jeweils mit eigener Potatium-ABCI++-Anwendung und eigenem lokalen Chain-/App-State. Der Network Admin ist ausdrücklich **nicht** für Konsens/Mining erforderlich.
+2. Erst ein Validator für das Devnet, danach vier mit anfangs fester, autorisierter Validatorgruppe für lokale/multihost Testnet-Tests. Initial betreibt der Projektbetreiber diese Infrastruktur. Die spätere Validatorrolle anderer Teilnehmer ist offen; Mining-Worker werden nicht automatisch Validatoren.
+3. **Potatium Hub** bleibt eine autonome Full Node inklusive Browser-Wallet, lokaler Node-GUI und optionalem Mining; Worker bleiben schlanke, gekoppelte Mining-Agenten ohne eigene Full-Chain-/Wallet-Schlüssel. Mehrere eigene Hubs können in der Teilnehmer-Clusteransicht zusammengefasst werden.
+4. **Ab dem ersten lauffähigen Devnet:** Hub-Cockpit und gesonderter **read-only Network Admin** zeigen echte Werte wie Chain-ID, Blockhöhe, Validator-/Peerstatus, Fehlerzustände. Beim initialen UI-Gerüst ohne Chain ausschließlich ehrliche „nicht verbunden“-Werte. Beide werden parallel zur Kernimplementierung iterativ erweitert, nicht auf M5/M6 verschoben.
+5. Network Admin als kleiner separater Monitoring-Dienst, im Dev-LXC zum Anfang, später optional eigene Management-VM. Optionaler Monitoring-Speicher/SQLite/Zeitreihen ist nur Beobachtung, keine Konsensabhängigkeit. Kein allgemeiner zentraler Hostagent oder öffentliches RPC als Voraussetzung.
+6. Netzwerkweite schreibende Betreiberaktionen bleiben späterer separater Admin-CLI mit gültig signierten On-chain-Autorisierungen vorbehalten. Read-only Admin erhält keine Spend-/Validator-/Operator-Admin-Schlüssel und darf weder Guthaben verändern noch Mining-Gewinner beeinflussen.
+7. Native Deployments `linux/amd64`, `linux/arm64` zuerst, Docker später optional. Dev-LXC ohne Docker, APIs zunächst loopback/SSH-Forward; Multi-Host-Verkehr nur mit dediziertem Sicherheits- und Firewall-Konzept.
+
+## Begründung
+
+Klare Trennung von Konsens, Nutzerbetrieb, Worker-Steuerung und Netzwerkbeobachtung; frühe Fehlersichtbarkeit; keine zentralisierte Coins-Datenbank oder Single Point of Failure; keine versteckte Wallet-Schlüsselübergabe. Die im Hub eingebettete Wallet gehört einem Betreiber, nicht technisch jeder Node. Mehrere Hubs/Worker können dieselbe registrierte Auszahlungsadresse verwenden.
+
+## Alternativen
+
+- Zentraler Masterserver samt SQL-Ledger: abgelehnt, widerspricht dezentrales L1-Konzept.
+- Admin-Cockpit als Voraussetzung für Blockproduktion: abgelehnt, wäre zentrale Verfügbarkeitsabhängigkeit.
+- Admin-Web vollständig erst nach M6: für **Statuslesen** abgelehnt, für sensible Schreibverwaltung weiter zurückgestellt.
+- Jeder Worker als Validator/full node: abgelehnt, Ressourcenaufwand und Rollenvermischung.
+- Jeder Hub zwangsweise Validator: abgelehnt, Full Nodes ohne Abstimmungsrecht sind zulässig.
+
+## Konsequenzen und offene technische Entscheidungen
+
+M1/M2 erhalten neue Akzeptanzkriterien für read-only Node-/Netzwerkstatus. M3 muss Validatorausfall und gleiche App-Hashes verifizieren. Die Monitoring-API und Datenbank, CometBFT-Version, Validator-Key-Verwahrung, Portkonfiguration, Metrikenaufbewahrung und Überwachungsberechtigungen werden vor Implementierung geprüft. Gebührenverwendung (Burn/Validator/Fonds) und Emissionsformeln werden **nicht** durch dieses ADR entschieden; bisherige Burn-Entscheidungen sind durch neuere Simulationen erneut in Diskussion.
+
+**Referenzen:** `docs/INFRASTRUKTUR_UND_DEPLOYMENT.md`, `docs/COCKPITS_UND_MONITORING.md`, ADR 0002/0005 und aktuelle offizielle CometBFT-Dokumentation.
+
+## Spätere Präzisierung
+
+**ADR 0007** konkretisiert: Ein zentraler `potatium-network`-Dienst **ist** für bequemen Bootstrap, Anträge und weltweites/privates Netzwerkinventar vorgesehen. Dessen off-chain Managementdatenbank widerspricht **nicht** dem in ADR 0006 abgelehnten zentralen **Coin-/Blockchain-Master**. Hub und Validatoren synchronisieren unabhängig direkt P2P. Die Gebührenverwendung für PoP-/Worker-Gebühren ist seit ADR 0007 auf **100 % On-chain-Fonds, 0 % Burn** festgelegt.
@@ -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.
@@ -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`.