potatium/docs/GESAMTHANDBUCH.md

# Potatium: Gesamthandbuch (aktueller Stand v0.2)

*Stand: 25.10.2026. Dieses Dokument ersetzt die frühere v0.1-Beschreibung; es dokumentiert den abgestimmten Produktentwurf, **keine** fertig implementierte Kryptowährung.*

## 1. Ziel und Identität

**Potatium (PTM)** ist eine eigenständige Hobby-Layer-1-Blockchain. Das Symbol ist das gewählte abstrakte goldene P/Kartoffellogo auf schwarzem Grund: `assets/logo/potatium-ptm-logo.png`. Der Mining-Arbeitstitel lautet **Proof of Potato (PoP)**. Raspberry Pi 4 und alte Büro-PCs sollen mit kleinen echten kryptografischen Aufgaben teilnehmen können, ohne GPU-/ASIC-Wettrüsten. Es gibt keine Absicht zu ICO, Börsenlisting oder Renditeversprechen. Nur wertlose private Test-PTM verwenden, bis Sicherheit und rechtliche Fragen geklärt sind.

## 2. Entwicklungsstand und Umgebung

- Fertig ist das **Projektgerüst** mit Go-Paketen, `doctor.sh`, lokaler statischer Wallet-Vorschau und Documentation; **keine** echte Blockchain, Wallet-Funktion, Miner-/Validatorlogik.
- Nutzer meldete erfolgreichen `scripts/bootstrap_workdir.sh`/`scripts/doctor.sh` unter Ubuntu 26.04.1, Go 1.27.3, Git 2.53.0 mit `go test ./...`, `go vet ./...` und Syntaxprüfung. Zustand des tatsächlichen Gitea-Repos/Codex-Fortschritts muss vor Änderungen eingesehen werden.
- Infrastruktur: unprivilegierter Proxmox-Ubuntu-26.04-LTS-LXC `potatium-dev`, 4 vCPU, 4 GB RAM, 40 GB Disk initial. Benutzer `potatium`, **verbindlicher Workdir `/home/potatium/src/potatium`**.
- IDE: VS Code lokal über Remote-SSH + Go/Codex. Git-Monorepo (privates Gitea), keine IDE/kein Docker-in-LXC erforderlich.

## 3. Zielarchitektur

```text
Browser Web-Wallet (lokales Signing, nur signierte Tx an API)
                  |                       Raspberry Pi/Alt-PC
          Potatium RPC/API <-------------- potatium-miner
                  |
   Go State Machine: Accounts, Transfers, PoP, Mint/Burn, Gebühren
                  |
      ABCI++ Anwendung (eigene Go-Implementierung)
                  |
        CometBFT Validator / P2P Netzwerk
                  |
    weitere Validatoren mit je eigener Datenbank
```

**CometBFT + ABCI++ ohne Cosmos SDK** ist eine bewusst gewählte Startpräferenz, noch gegen aktuelle APIs zu verifizieren. PoP-Miner erzeugen keine CometBFT-Blöcke. Weitere Programme: `potatiumd` (Node), `potatium-miner` (eigener Miner), `potatium-cli` (CLI), `web/wallet` (Web-GUI). Erst ein lokales Testnet, dann ein privates Mehrhost-Testnet; keine öffentlichen API-Ports.

## 4. PoP v0.2: Prinzip wurde abgestimmt

**Eine Mining-Runde ist nicht ein Blockchain-Block.** Sie enthält **drei hintereinander freigegebene Fenster**. Die genaue Block-/Zeitplanung ist noch offen. Erst zum Fensterstart wird die zugehörige Rechen-Challenge nutzbar; Belege sind an Chain-ID, Fenster, Runde und Miner-ID gebunden.

- **Fenster 1:** Jeder zugelassene Miner darf kostenlos eine kurze, wirklich zu lösende PoW-Aufgabe mit endlichem zulässigen Nonce-Raum bearbeiten.
- **Fenster 2:** Wenn der Miner noch keinen Proof gefunden hat, darf er nach bestätigter Zahlung **fix + progressiv** eine neue unabhängige Herausforderung bearbeiten.
- **Fenster 3:** Ohne bisheriges Ticket und nach Freischaltung von Fenster 2 kann er für höhere fixe und progressive Kosten eine dritte neue Aufgabe bearbeiten.
- **Ein Ticket pro freigegebener Mining-Identität je Runde maximal.** Nach einem erfolgreichen Proof ist Schluss; weitere Zahlungen/Hochleistung bringen kein weiteres Ticket. Keine Garantie auf ein Ticket nach drei Versuchen.
- **Spätere Ziehung:** Die akzeptierte Ticketmenge wird zuerst bindend festgeschrieben; nach Kenntnis einer späteren überprüfbaren Zufallsquelle (drand als Kandidat) bestimmt jeder Validator denselben Gewinner und nur der regelkonforme Mint ist erlaubt.

### Erfolgschancen (bloßes Rechenbeispiel)

Bei völlig unabhängigen vollständigen Fenstern mit je `p = 70 %` auf einen gültigen Hash beträgt `P(mindestens ein Erfolg)` nach 1/2/3 Fenstern 70 / 91 / 97,3 %. Der Mehrwert nimmt ab (+21 bzw. +6,3 Prozentpunkte). Dies ist **nicht** die finale Gewinnauslosung und **kein beschlossener Schwierigkeitswert**. Tatsächliche Pi-/Desktop-Zeit, Cache, Netz und Einreichungsfristen beeinflussen die praktische Chance.

### Gebühren und Fairness

Die abgelehnte Idee „Gebühr pro aktuellem Wallet-Guthaben“ lässt sich durch Wegüberweisen von PTM manipulieren. **Stattdessen:** gebührenrelevant sind die PoP-Gewinne der **zugeordneten Mining-Identität/Betreibergruppe** über ein gleitendes Fenster von ungefähr **90 Tagen**. Langjährige Miner haben keinen lebenslangen Malus; alte Gewinne fallen mit der Zeit heraus.

`Fenster 2 = Basisbetrag2 + Progressive(90-Tage-Ertrag)`; `Fenster 3 = Basisbetrag3 + stärkerer progressiver Anteil`. **Alle exakten Prozentsätze, Stufen, Beträge und Rundungsregeln sind offen**. Bei Erfolg in Fenster 1 oder 2 fallen spätere Gebühren nicht an; Zusatzgebühren im Misserfolgsfall werden nicht erstattet.

**Zusatzgebühren werden verbrannt**, normale Überweisungsgebühren sollen die Validatoren finanzieren (Aufteilungsregeln noch offen). Mining funktioniert kostenlos mit 0 PTM über Fenster 1. Die Wallet gibt kostenpflichtige Fenster einzeln oder per eng begrenzter, widerrufbarer Autorisierung frei. Der Miner erhält niemals Browser-Wallet-Secrets.

### Wichtige Grenzen

- **Sybil-Problem:** eine kryptografische Node-ID beweist keine eigene physische Maschine oder Person. Anfangs manuell freigegebene Registrierungsidentitäten und Betreiberzuordnung. Mehrfachidentitäten müssen organisatorisch kontrolliert werden.
- **Kein Nachweis erfolgloser Arbeit:** Validatoren sehen gültige Hash-Treffer, nicht echte CPU-Minuten ohne Treffer. Endliche Nonce-Räume begrenzen erlaubte Treffer pro Identität.
- **Hardware:** schnellere Rechner sind früher fertig; beim Pi 4 müssen endliche Aufgaben in ihrem Fenster zuverlässig bearbeitbar sein. Vollkommene Hardwaregleichheit lässt sich nicht beweisen.
- **Zufall/Zensur:** Validatoren könnten Aufnahme von Proofs/Gebühren behindern, Beacon-Ausfall kann Ziehung verzögern. Fristen und Fallback vor Mainnet präzisieren.
- **Budget:** Gebühren für zusätzliche zufallsabhängige Chancen sind kein harmloses Detail, mögliche Glücksspiel-/Finanzrechtsfolgen. Vorläufig ausschließlich Privat-/Testnet ohne echten Wert.

## 5. Coin und Transaktionen: offen

Coin-Menge, Genesis-Verteilung, kleinste Einheit/Dezimalstellen, Belohnung, Halbierungen/Emission, Standardgebühren, Blockzeit, RNG-Beacon, Signatur-/Adressformat und Datenbank müssen **vor konsenskritischem Code** entschieden werden. Zahlen aus Chat-Beispielen (`10 Mio`, `1 PTM je Runde`, `12 Blöcke`, `10 Sekunden`, Gebührenstaffel oder `70 %`) nicht als Default übernehmen. Saldos ausschließlich in ganzen Basis-Einheiten, Replay-Schutz mit Nonce, Signatur und Chain-ID, deterministische Aufträge.

## 6. Web-Wallet ab erster funktionaler MVP-Version

- Wallet lokal und sicher erstellen/importieren/verschlüsselt exportieren und entsperren/sperren.
- Korrekte PTM-Adresse anzeigen/kopieren, Balance/Netzwerkverbindung, PTM senden inkl. Fee-Preview und Bestätigung, empfangen, Verlauf mit echtem Tx-Status.
- Privater Schlüssel und Seed **niemals** an API, Node, Miner oder Logs; Browser-signierte Transfers; sichere, getestete Kryptobibliotheken und eindeutig definierte signierbare Bytes.
- Für kostenpflichtige Fenster: gültigen Gebührenmaßstab, Spend-Limit, Maximalpreis und explizite Freigabe anzeigen. Solange die sichere Autorisierung nicht implementiert ist: Zusatzfenster deaktiviert.
- Keine erfundenen Guthaben, Fake-Transaktionen oder als sicher deklarierte ungetestete Wallet-Demos. Aktuelles `web/wallet` ist **nur statisches UI-Gerüst**.

## 7. Repository und Verfahrensregeln

`AGENTS.md` ist Codex-Leitlinie; `docs/PROJEKTPLAN.md`, `docs/PROTOKOLL_ENTWURF.md`, `docs/POP_FAIRNESS_UND_GEBUEHREN.md`, `docs/ROADMAP.md` und `docs/decisions/` sind der aktuelle Stand. Git-Branches klein halten, Änderungen nicht ungefragt pushen oder echte Schlüssel committen. Alle wichtigen Protokollentscheidungen als ADR mit Gründen, Alternativen und Folgen; die letzte akzeptierte ADR hat Vorrang gegenüber älteren Entwurfsbeispielen.

## 8. Nächste Schritte

1. Update anwenden und Repo-Änderungen prüfen, testen, committen.
2. Mit Codex den **M1-Parameterblock** bearbeiten: Tokenomics und Tx-Signaturen, dann Gebühren-/Fairness-Simulation für mindestens 5/10/20/50 Miner samt Erwartungswert/Kosten, Benchmark auf Pi 4.
3. Finale konsenskritische Regeln einzeln per ADR bestätigen, erst dann implementieren.
4. Ledger und funktionale Web-Wallet **parallel**, danach CometBFT-Integration und PoP-Logik.

## 9. Nicht vorspiegeln

Ein sauberes Go-Gerüst und eine HTML-Oberfläche sind **noch keine nutzbare Blockchain oder Wallet**. Der neue Gebührenentwurf ist **dokumentiert und simulationsbedürftig**, nicht implementiert.

## 10. Langfristige PTM-Nutzung: Sammlerstücke und virtuelle Handelsplätze (Vision)

Die im Oktober 2026 ergänzte Vision sieht **nach stabiler Kern-Chain und Web-Wallet** digitale Sammelobjekte (F1), einen in PTM abgewickelten internen Marktplatz (F2), eine Handelsoberfläche für fiktive interne Assets mit Orderbuch, Kursen, Charts und Portfolios (F3) und optional einen strikt getrennten Paper-Trading-Modus (F4) vor. Diese Szenarien sollen PTM einen internen Nutzwert geben. Sie begründen **keinen externen Euro-Kurs**, keine Börsenlistung und keine Anlage- oder Renditeaussage.

Asset-Kauf, Sammelgegenstände oder Bestandshöhen dürfen die PoP-Lotterie nicht zusätzlich bevorteilen. Die technischen Details (Assetmodell, Emission, Marktdaten, atomare Trades, Ordermatching, Gebühren und Schutz gegen Wash Trading) sind absichtlich offen. Keine Funktionen sind implementiert. Maßgeblich: `docs/ZUKUNFT_OEKOSYSTEM.md`, `docs/ROADMAP.md` und ADR 0004. Die Arbeiten an M1–M6 behalten Vorrang.