Initial commit: Potatium

docs/ARCHITEKTUR.md

@@ -0,0 +1,52 @@
+# Architekturentwurf
+
+```text
+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.