potatium/docs/PROJEKTPLAN.md

# Potatium – vollständige Projektübergabe v0.1

**Stand:** 24.10.2026 · **Zweck:** Projektwissen aus dem ursprünglichen Planungschat als versionierbare Arbeitsgrundlage für VS Code/Codex übernehmen.

## 1. Vision und Grenzen

Potatium ist eine neue, eigenständige Hobby-Kryptowährung mit eigener Layer-1-Blockchain und dem Token-/Coin-Kürzel **PTM**. Name und gewähltes Logo stehen für eine bewusst kleine, ressourcenschonende Kartoffel-PC-Blockchain. Kein Token einer fremden Chain, kein ambitioniertes öffentliches Finanzprojekt, keine Spekulations- oder Renditeversprechen. Öffentliches Mainnet, Listing, Tokenverkauf und Marketing gehören **nicht** zum ursprünglichen Projektumfang.

Mining soll eine echte, leichte kryptografische Tätigkeit erfordern und nicht nur ein Online-Klick sein. Gute alte PCs und Raspberry Pis sollen teilnehmen können. Die Gewinnauswahl soll als Lotto zwischen qualifizierten Nodes geschehen, statt Rechenleistung proportional zu belohnen. Rechenleistung beeinflusst technisch weiterhin die Chance, sich rechtzeitig zu qualifizieren; das gehört zu den explizit zu messenden Grenzen.

## 2. Festgelegte Entscheidungen

| Thema | Festlegung |
|---|---|
| Produktname | Potatium |
| Kürzel | PTM, vor öffentlicher Nutzung auf Konflikte prüfen |
| Optik | ausgewähltes minimalistisches goldenes P/Kartoffelsymbol auf Schwarz (`assets/logo/potatium-ptm-logo.png`) |
| Entwicklungsplattform | Proxmox-LXC, **Ubuntu Server 26.04 LTS** (nicht Debian), unprivilegiert |
| Entwicklungszugriff | VS Code lokal über Remote SSH, mit OpenAI Codex |
| Sprache | Go |
| Git | einzelnes privates Monorepo `potatium`, Remote nach Anlegen eintragen |
| Mining | leichtes PoW-Qualifikationsrätsel und danach 1 Los je freigegebener Node-ID, separate Ziehung |
| Rollen | Block-Validatoren getrennt von Mining-Clients |
| Web-Wallet | **Teil des ersten funktionalen MVP**, nicht nachträglich |
| Datenbank | keine PostgreSQL-Pflicht; deterministischer eingebetteter Chain-State geplant |
| Container im LXC | anfangs kein Docker/Nesting |

Die genannten Beispieldaten aus der Ideensammlung (2 Minuten/Runde, 10 PTM Belohnung, 21 Millionen PTM, 4 Validatoren) **sind nicht beschlossen**. Raspberry Pi 4 ist Hardwareziel, noch keine verifizierte Benchmarkzusage.

## 3. Umgebung

- LXC-Name `potatium-dev`, Ubuntu 26.04 LTS (aktuelle LTS-Ausgabe), 4 vCPU, 4 GB RAM, 40 GB Disk als Initialgröße. Netzwerk feste Adresse/Reservierung im privaten LAN; SSH ausschließlich LAN/VPN. Bei Bedarf 8 GB RAM.
- Benutzer `potatium`, Home `/home/potatium`, Workspace `/home/potatium/src/potatium`. Keine Routineentwicklung als root.
- Installierte Basispakete: OpenSSH, sudo, Git, curl, tar, unzip, make, Compiler, Python3, ca-certificates. Go von offizieller Quelle, SHA-256-validiert; mitgeliefertes Skript ist auf verifizierte Go 1.27.3 für amd64/arm64 gesetzt.
- VS Code auf dem lokalen Rechner; Erweiterungen Remote-SSH, Go, OpenAI Codex; optional GitLens. SSH-Schlüssel und Git-Remote von Nutzer selbst anlegen.
- Bestehende Proxmox-Backupstrategie anwenden, Snapshots insbesondere vor Upgrades. Keinerlei Schlüssel in Snapshots/Backups ohne bewusstes Geheimniskonzept im späteren Testnet.

## 4. Softwaremodule und Prozesse

Drei Go-Programme plus Browser-WebGUI:

**`potatiumd`:** Node-/Validatoranwendung; CometBFT-ABCI++-Adapter für deterministische Zustandsübergänge, mempoolseitige Transaktionsprüfung, Zustands-/Blockdatenbank, RPC/API für Wallet/Explorer und Verarbeitung der PoP-Tickets und Ziehungen. CometBFT ist der *vorgesehene* Konsens, sofern API-/Kompatibilitätstest bestätigt wird. Die Chain benutzt kein Cosmos SDK für die Anfangsphase. Die Miner bestimmen nicht die Reihenfolge der CometBFT-Blöcke.

**`potatium-miner`:** eigenständiger CPU-sparsamer Prozess, Linux AMD64/ARM64. Registrierte Identität anmelden, Herausforderung pro Runde beziehen, kleines PoW lösen, genau einen gültigen Nachweis einreichen, quittieren, warten, Gewinnstatus lesen. Konfigurierbare CPU-Last / Pause, Logs, Restart und Recovery. Keine WebGUI-Pflicht auf dem Miner.

**`potatium-cli`:** Netzwerkinfo und lokale Walletverwaltung, später Debug-/Adminbefehle. Keine Secret-Ausgabe im Normalfall.

**`web/wallet`:** direkt zur ersten nutzbaren Version gehörende Oberfläche mit Wallet-Erstellen/Import/Backup, Address+QR optional, Balance, Senden, Empfangen, Historie, Lock/Unlock und Netzwerkstatus. Im gelieferten Gerüst ist lediglich eine ausdrücklich *inaktive Vorschau*. Echte Funktion benötigt vorher verbindliche Signatur-, Adress- und Transaktionsformate.

Quellen/Netzwerk/State bleiben modular, testbar und so wenig frameworkabhängig wie möglich. Siehe `ARCHITEKTUR.md`.

## 5. Protokoll-Sicherheitsgrundsätze

1. Konten und Transfers sind vollständig reproduzierbar und mit ganzzahligen **Basiseinheiten** gespeichert, niemals als `float`.
2. Jede Transaktion hat Version, Absender, Empfänger, Betrag, Gebühr, Nonce/Sequenz, Signatur und Domain-/Chain-ID gegen Replay. Genaue Formate noch festlegen.
3. Coins entstehen nur als gültige Protokollausgabe an den ermittelten Gewinner und ggf. nach weiteren später beschlossenen Regeln. Double Spend, Überlauf, unberechtigtes Minting und ungültige Signaturen abweisen.
4. PoP: Runde und Schwierigkeit deterministisch; signierte Aufgaben-/Lösungsbindung an Node-ID und Runde; maximale ein Ticket je berechtigter Node-ID; gemeinsamer Abschluss der Ticketliste **vor** Offenlegung der nächsten Ziehungszufälligkeit.
5. Auswahl verifizierbar (beispielsweise drand-Beacon); externe Abhängigkeit und Ausfälle sind ein Sicherheits- und Verfügbarkeitsrisiko. Alternative auf Sicherheitsfolgen prüfen.
6. Registry zunächst nur organisatorisch gegen Sybil; keine Hardwareerkennung versprechen. Mehrere Identitäten auf einer Maschine sind technisch möglich.
7. Logik muss bei gleicher Blockfolge auf allen Nodes exakt gleiche Ergebnisse liefern, unabhängig von Uhr, OS, CPU, Go-map-Reihenfolge oder Netzwerk-Timing.
8. Ein CometBFT-Validator-Netz mit wenigen gleich kontrollierten Validatoren ist kein gleichwertiger Ersatz für ein großes dezentrales Mainnet. Fokus zunächst Labor/Testnet.

## 6. Web-Wallet direkt ab MVP

Die Web-Wallet ist **feste Voraussetzung für den ersten brauchbaren Release**. Kein langjähriges CLI-only-Projekt. UX zunächst schlicht, responsive und ohne Fremddienste. Alle kritischen Key-Operationen müssen lokal im Browser mit geprüfter Bibliothek erfolgen, soweit Architektur dies erlaubt. Keinerlei Schlüssel, Seed oder Passwörter auf Server, in RPC-Logs oder Git. Offline-Backup/Recovery testen. Nur HTTPS bzw. zu Entwicklungszwecken 127.0.0.1 mit SSH-Portforwarding, sichere CORS-/CSP-Regeln und bestätigungspflichtiger Sende-Dialog.

Um die UI früh konkret zu machen, enthält das Repo eine **statische Platzhalteroberfläche**. Sie behauptet keine funktionierende Coin-Wallet. Erst nach finaler kryptografischer Spezifikation sind Wallet erstellen/importieren/senden aktivierbar.

## 7. Entwicklungsmethode

- Monorepo, `main` stets grundsätzlich testbar, kleine Feature-Branches und prüfbare Commits.
- `go test ./...`, `go vet ./...`, `gofmt`; Integrationstests mit mindestens zwei und später vier Validatoren; reproduzierbarer Build in Ubuntu-LXC; arm64-Builds prüfen.
- Entscheidungen zuerst schriftlich unter `docs/decisions/` erfassen, offene Parameter nicht stillschweigend festlegen.
- Code zuerst in kleinen testbaren Paketen: Typen/Units, Wallet-Signaturformat, State Machine, Genesis und Transaktionen; zeitnah Browser-UI anbinden; dann Konsens; dann Lottery.
- Jede Codex-Aufgabe: Ist-Zustand, minimale Änderung, Akzeptanzkriterien, Tests, Ergebnis, Dokumentation aktualisieren. AGENTS.md bindend.

## 8. Projektdateien

`START_HIER.md` – genaue Reihenfolge der Inbetriebnahme. `scripts/setup_ubuntu26.sh` – Systempakete und Benutzer. `scripts/install_go.sh` – verifizierte Go-Installation. `scripts/bootstrap_workdir.sh` – Verzeichnisse ergänzen. `scripts/doctor.sh` – erste Checks. `handoff/STARTPROMPT_VSCODE_CODEX.md` – direkt einsetzbarer Codex-Prompt. `handoff/CHATGPT_PROJEKTANWEISUNGEN.md` – ChatGPT-Projektanweisungen bis 8.000 Zeichen. `assets/logo/` – die **angenommene** Potatium-Logo-Datei.

## 9. Verbleibende harte Entscheidungen

- Accountmodell, Kryptografiesuite/Adressen, Seed-/Recoverystandard, Einheiten und Transaktionsformat.
- Coin-Gesamtmenge/Emission, Genesis-Zuteilung, Gebühren, Wallet-Netzwerkregeln.
- Blockzeit und Mining-Rundenlänge (beides technisch getrennte Begriffe), Schwierigkeit, Fristen, Teilnahmeverhalten, Mini-Hash-Rätsel und Benchmarks.
- Losliste committen, Zufallsbeweis, Ausfallszenarien, Gewinnerauszahlung und verfügbare Validatoren.
- Exakte Speicher-/Konsensframework-Versionen, Transport-/RPC-Protokolle.

**Hinweis zu öffentlichen Coins:** Bei öffentlichem Angebot können Regulierung und Sicherheitsprüfungen relevant werden. Bis auf Weiteres nur isolierte Entwicklungs-/Test-PTM ohne monetären Wert verwenden.