# 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.