potatium/docs/ARCHITEKTUR.md

Architekturentwurf

Lokaler Browser                           Raspberry Pi / Office-PC
Web-Wallet (Keys clientseitig)            potatium-miner
       |                                      |
       +--------- signierte API Calls --------+
                                              |
                                   potatiumd API/RPC
                                              |
                     +------------------------+--------------------+
                     |       Potatium Core (Go)                     |
                     |  Transaktionen, Ledger, PoP-Registry,       |
                     |  Tickets, Ziehung, Emission, State          |
                     +------------------------+--------------------+
                                              | ABCI++
                                       CometBFT Validator
                                              | P2P
                                  weitere Validatoren (zunächst 4)

Diese Skizze ist eine Zielarchitektur, nicht bereits implementiert.

Prozess- und Verantwortungsgrenzen

• Konsens/Blockreihenfolge: CometBFT (vorläufig ausgewählt). Validierungsregeln: Potatium Core.
• Mining: leichte Hash-Aufgabe sichert Teilnahmeberechtigung, nicht die Validator-Konsensmehrheit. Die Mining-Lotterie darf nicht rückwirkend die Blockreihenfolge wählen.
• Persistenz: jeder Validator speichert seine eigene Blockchain und seinen Zustand, kein gemeinsamer Postgres-Server.
• API: nur überprüfte öffentliche Daten herausgeben, Eingaben strikt validieren. Localhost-Default und später explizite Netzfreigabe/TLS.
• Browser: Private Keys und Seeds nie als Plaintext via API übertragen. Der Server sieht nur signierte Transaktionen.

Netzwerk & Reihenfolge

1. Wallet signiert Transaktion -> Node prüft grundlegende Eigenschaften -> Mempool.
2. Validatoren legen Block fest -> Core wendet deterministische Änderungen an -> Zustand committen.
3. Registrierter Miner löst auf eine eindeutige Runde gebundenes Hash-Rätsel -> Ticket wird nach Konsens final akzeptiert.
4. Nach verbindlichem Rundenabschluss und später verifizierbarem Zufallswert wird Gewinner ermittelt und Minting über konsensvalidierten Zustandsübergang verbucht.

Offen: keine wall-clock-Zufallszahlen im konsenskritischen Code; Runden-/Endzeit soll auf Height/Finalität oder präzise finalisierten Zeitregeln basieren. Verzögerungen, Beacon-Ausfälle und Transaktionszensur explizit prüfen.

Repositorystruktur

cmd/ Programme, internal/chain Ledger, internal/transaction Formate, internal/crypto Schlüssel-/Signaturverifikation, internal/mining Proof, internal/lottery Ziehung, internal/registry Identitäten, internal/consensus ABCI, internal/storage Persistenz, internal/api RPC, web/wallet UI, tests/integration End-to-End, deploy spätere Systemkonfiguration, docs/decisions ADRs.

Bedrohungsmodell (für Designreviews)

• Erfundene Identitäten / ein PC mit vielen VMs; manuelle Registrierung schützt nur gegen unbefugte Teilnehmer.
• Schneller Miner gewinnt vor Fristende eine bessere Qualifikationschance.
• RNG/Beacon-Last-Look, Vorabkenntnis, Validator-Zensur, Ausfall oder Verzögerung.
• Replay/Double-Spend/Überlauf; State-Divergenz durch nichtdeterministische Go-Maps oder Uhrzeiten.
• Verlust / Exfiltration von Browser-Wallet-Schlüsseln; Backups, Browser-Extensions, XSS.
• Kleiner Validator-Kreis und zentrale Registry: begrenzte Dezentralität, bewusst für ein Hobby-Testnet.