potatium/README.md

<p align="center">
  <img src="assets/logo/potatium-ptm-logo.png" alt="Potatium PTM Logo: goldenes geometrisches P auf Schwarz" width="180" />
</p>

<h1 align="center">🥔 Potatium (PTM)</h1>

<p align="center"><strong>Eine eigenständige Hobby-Blockchain mit Proof of Potato.</strong><br />
Ressourcenarm · Raspberry-Pi-tauglich · lokal kontrollierte Web-Wallet · privates Testnetz</p>

> **Projektstatus, 25.10.2026:** Entwicklungsgerüst und statische Web-Wallet-Vorschau vorhanden. Eine funktionsfähige Chain, echte PTM-Transaktionen, PoP-Mining, Sammlerstücke oder eine Börse sind **noch nicht implementiert**. Kein Anlageprodukt, kein Kursversprechen. Ausschließlich private, nicht einlösbare Test-PTM.

## Was ist Potatium?

Potatium soll eine **eigene Layer-1-Blockchain in Go** werden, kein ERC-20-Token. Ein kleines privates Netzwerk aus alten PCs und Raspberry Pis betreibt die Chain. Vorgesehen sind **CometBFT / ABCI++** mit einer eigenen deterministischen Anwendung, zunächst ohne Cosmos SDK; die tatsächlichen Versionen und Architekturdetails werden vor Implementierung geprüft.

- **PTM:** Coin für Überweisungen, Mining-Belohnungen und später interne Anwendungen.
- **Proof of Potato (PoP):** Miner lösen leichte, begrenzte Rechenaufgaben. Validatoren produzieren und bestätigen die Blockchain-Blöcke, PoP-Miner nicht.
- **Web-Wallet ab funktionalem MVP:** Schlüssel und Signaturen bleiben im Browser; die API bekommt niemals Seed oder Private Key.
- **Keine reale Wertzusage:** PTM ist ein Hobby-/Testnet-Coin ohne garantierte Einlösung in Geld oder andere Kryptowährungen.

## Infrastruktur: Wer betreibt was?

**Die Blockchain braucht Validatoren, aber keinen zentralen Coin-Server.** Anfangs betreibt der Projektbetreiber einen Validator im Devnet, anschließend vier getrennte Validatoren im Testnet. Jeder Validator speichert Blockchain-/App-State **lokal** und stimmt über gültige Blöcke ab. **Normale Hub-Full-Nodes prüfen die Chain ohne Validator-Stimmrecht**; Worker sind schlanke PoP-Miner am Hub. Eine browserseitige Wallet gehört logisch zum Betreiber und bleibt ohne Export ihrer privaten Schlüssel aus Hub/Worker heraus.

| Bestandteil | Betrieb | Zweck |
|---|---|---|
| `potatium-dev` | Projektbetreiber (Ubuntu-LXC) | Git/Go/Tests; zunächst isoliertes Devnet + lokale Früh-Cockpits |
| 1 → 4 Validatoren | Zunächst Projektbetreiber; später ggf. zugelassene weitere Betreiber | CometBFT-Blockkonsens, je eigener State und Schlüssel |
| **Potatium Hub** | Teilnehmer auf VM/Pi/PC, nativ zuerst | Full Node, echte Browser-Wallet, lokale GUI, eigenes Mining, eigene Worker und Clusteransicht |
| **Potatium Worker** | Teilnehmer auf Pi/Alt-PC/VM | Signierter Mining-Agent, keine Full-Chain, keine Geld-Wallet |
| **Potatium Network Admin (read-only)** | Projektbetreiber, anfangs im LXC, später separate Management-VM möglich | Chain-/Validator-/Netzwerküberwachung; keine Coins kontrollieren |

**Benutzer-Hub und lesender Network Admin gehören schon zum ersten funktionalen Devnet**, mit verifizierten Daten und ehrlichen Offline-Zuständen. Die vollständige Operator-/Validator-Administration per Web kommt später; zunächst geschützte signierte Admin-CLI, sobald benötigt. Die bestehenden UI-Dateien sind noch Entwürfe, keine echte Chain/Wallet. Der Network Admin ist **keine zentrale Instanz, die für die Chain laufen muss**.

Details: [Gesamtinfrastruktur & Deployment](docs/INFRASTRUKTUR_UND_DEPLOYMENT.md) · [Cockpits & Monitoring](docs/COCKPITS_UND_MONITORING.md) · [ADR 0006](docs/decisions/0006-validator-infrastruktur-und-cockpits-ab-devnet.md).

## Proof of Potato: aktueller Produktentwurf

Eine Mining-Runde enthält **drei aufeinanderfolgende Aufgabenfenster**. Fenster 1 ist für zugelassene Miner kostenlos. Wer noch kein gültiges Ticket hat, kann Fenster 2 und 3 gegen **fixe und progressive Gebühren** freischalten. Maßstab für die Progression sind zurechenbare **PoP-Gewinne eines gleitenden Zeitraums von ungefähr 90 Tagen**, nicht die aktuelle Wallet-Balance. Gebühren aus Zusatzfenstern und zusätzlichen Workern fließen nach ADR 0007 **zu 100 % in einen On-chain-Community-Fonds statt in den Burn**; die konkreten Gebührenhöhen sind offen. Pro freigegebener Mining-Identität wird **höchstens ein Ticket je Gesamtrunde** akzeptiert. Nach Abschluss bestimmt eine später überprüfbare Zufallsquelle den Gewinner.

Die exakten Gebühren, Erfolgswahrscheinlichkeiten, Fensterlängen, Emissionsregeln und Coinparameter sind **noch nicht beschlossen**. Simulationen wie „Balanced + Low“ sind ausschließlich Forschungsmodelle. Details: [PoP-Fairness und Gebühren](docs/POP_FAIRNESS_UND_GEBUEHREN.md), [Protokollentwurf](docs/PROTOKOLL_ENTWURF.md) und [ADR 0003](docs/decisions/0003-pop-fenster-und-gebuehren.md).

## Roadmap

Die Statusangaben trennen **bereitgestellte Gerüste**, **offene Entscheidungen** und **noch nicht begonnene Funktionen**. Ein erfolgreiches `go test` für das Gerüst beweist keine funktionierende Blockchain.

| Phase | Ziel | Status |
|:--|:--|:--|
| **M0 · Entwicklungsbasis** | Ubuntu-LXC, Go, Git, VS Code, Node-/Miner-/Wallet-Gerüste | 🟡 Gerüst vorhanden; Git-/Remote-Stand separat verifizieren |
| **M1 · Protokoll und Ökonomie** | Coin-/Transaktionsregeln, PoP-Gebühren, Simulationen, Pi-4-Benchmark, ADRs | 🟡 In Planung und Forschung |
| **M2 · Chain-Kern + echte Web-Wallet** | Konten, Signaturen, Transfers, persistenter State; Wallet lokal erstellen/importieren, senden/empfangen | ⬜ Offen |
| **M3 · Konsensnetz** | CometBFT, zunächst 1, dann 4 Validatoren, Synchronisation und Ausfalltests | ⬜ Offen |
| **M4 · Proof of Potato** | Registry, 3 Fenster, Gebühren/Fonds, Tickets, überprüfbare Ziehung, Reward, Negativtests | ⬜ Offen |
| **M5 · Bedienung & Hardware** | Wallet fertigstellen, Status/Explorer, Linux amd64/arm64, Raspberry-Pi-Benchmarks | ⬜ Offen |
| **M6 · Privates Testnet** | Mehrhost-Betrieb, Recovery, Sicherheit, Dokumentation, Test-Releases | ⬜ Offen |
| **F1 · Digitale Sammlerstücke** | Einzigartige/limitierte interne Gegenstände, Ownership, Sammlung in der Wallet | 💡 Zukunftsidee |
| **F2 · PTM-Marktplatz** | Sammlerstücke in PTM anbieten, kaufen und zwischen Nutzern übertragen | 💡 Zukunftsidee |
| **F3 · Interne Asset-Börse** | Fiktive, interne Assets in PTM handeln; Orderbuch, Kurse, Charts, Historie, Portfolio | 💡 Zukunftsidee |
| **F4 · Börsenlabor** | Optional getrennter Paper-Trading-Modus, Indikatoren, Auswertungen und Szenarien | 💡 Zukunftsidee |

**Die Zukunftsphasen F1–F4 beginnen ausdrücklich erst, wenn die Kern-Chain inklusive Wallet und privatem Testnet zuverlässig funktioniert.** Es gibt keinen beschlossenen Termin und keine Implementierungszusage. Die vollständige [Roadmap](docs/ROADMAP.md) und die [Zukunftsvision für das interne Ökosystem](docs/ZUKUNFT_OEKOSYSTEM.md) beschreiben die Abhängigkeiten und offenen Fragen.

## Später: Was kann man mit PTM anfangen?

Die Coin-Nutzung soll langfristig **über Mining-Gebühren hinausgehen**. Vorgesehen sind als mögliche spätere Erweiterungen digitale Kartoffel-Sammlerstücke und ein interner Marktplatz mit PTM als Zahlungsmittel. Danach könnte eine kleine **interne Handelsplattform** entstehen, auf der man fiktive Assets handeln und Kursentwicklungen, Orders, Handelsvolumen und Portfolios verfolgen kann, ohne dass PTM in Euro oder externe Kryptowährungen umtauschbar sein muss.

Interne Marktpreise wären **PTM-Preise aus tatsächlich abgeschlossenen internen Trades**, keine behaupteten Euro-Werte. Ein möglicher Lern-/Paper-Trading-Modus wäre klar von echter interner PTM-Buchführung getrennt. Keine Sammlerstücke, Assets oder gekauften Funktionen sollen zusätzliche PoP-Lose oder unbegrenzte Mining-Vorteile verschaffen.

## Repository und Entwicklung

| Pfad | Zweck |
|:--|:--|
| `cmd/potatiumd`, `cmd/potatium-miner`, `cmd/potatium-cli` | Geplante Go-Programme, derzeit Gerüste |
| `internal/` | Künftige App-, Ledger-, Mining- und Konsenslogik |
| `web/wallet/` | Derzeit **statische UI-Vorschau**, keine funktionale Wallet |
| `docs/` | Protokoll, Projektplan, Roadmap, Zukunftsvision und Entscheidungen |
| `assets/logo/potatium-ptm-logo.png` | **Ausgewähltes unverändertes Projektlogo** |
| `AGENTS.md` | Arbeitsregeln für Codex |

Entwicklungsumgebung: unprivilegierter Ubuntu-26.04-LXC `potatium-dev`, Benutzer `potatium`, Repository unter `/home/potatium/src/potatium`, VS Code via Remote-SSH und Codex. Testserver ausschließlich auf `127.0.0.1`.

```bash
cd /home/potatium/src/potatium
bash scripts/doctor.sh
make run-ui   # Nur statische lokale Web-Wallet-Vorschau
```

Nicht mit echten Schlüsseln oder Guthaben experimentieren. `data/`, Seeds, Passwörter, Zugangsdaten und generierte Binaries gehören nicht in Git.

**Nächster Schritt:** M1-Protokollparameter sauber festlegen und PoP-Simulation mit Raspberry-Pi-Messungen abgleichen, bevor konsenskritischer Code entsteht. [Projektplan](docs/PROJEKTPLAN.md) · [Gesamthandbuch](docs/GESAMTHANDBUCH.md) · [Codex-Startprompt](handoff/STARTPROMPT_VSCODE_CODEX.md).

## Hub und Worker: Geräte im Potatium-Cluster

Potatium wird in **zwei geplanten Installationspaketen** betrieben. Der **Hub** ist eine autonome Full-Node mit eigenem Web-Cockpit, clientseitig verwalteter Wallet und optionalem PoP-Mining; er funktioniert ohne zusätzliche Geräte. **Worker** sind schlanke, an einen Hub gekoppelte Mining-Instanzen (Pi/VM/Alt-PC) mit eigenem Geräteschlüssel, aber **ohne eigene Coin-Wallet oder vollständige Chain**. Im Hub können eigene Worker und später mehrere berechtigte Hubs gemeinsam beobachtet/verwaltet werden. Hub-/Cluster-UX hat Vorrang vor der separaten Admin-WebGUI.

Jeder zugelassene Hub-Miner und jeder Worker kann pro PoP-Runde jeweils maximal ein Ticket erzeugen. Die PTM-Belohnungen werden der gemeinsamen registrierten **Betreiber-Auszahlungsadresse** gutgeschrieben. Gebühren und Mining-Gewinne der letzten ca. 90 Tage werden **je Betreiber, nicht je Wallet oder Hub** zusammengefasst. Ein Hub-Mining-Platz pro Betreiber bleibt von zusätzlichen Worker-Gebühren ausgenommen; weitere kostenlose Hub-Mining-Plätze durch Splitten sind nicht erlaubt. **Tarife und Worker-Obergrenze sind noch offen**, siehe [Hub/Worker-Architektur](docs/HUB_WORKER_CLUSTER.md), [Worker-Gebührenforschung](docs/WORKER_GEBUEHREN_FORSCHUNG.md) und [ADR 0005](docs/decisions/0005-hub-worker-cluster-und-betreiber.md).

**Roadmap-Erweiterung:** M1 konkretisiert Operator-Registry und Cluster-Gebührenforschung; M2 liefert den **lokalen Hub und die funktionierende Browser-Wallet**, M3 beobachtbare Full-/Validator-Nodes, M4 gekoppelte Worker und echtes Mining, M5 Cluster-Cockpit und ARM64-Auslieferung, M6 Mehrhost-/Failover-Tests. Frühere Roadmap-Status bleiben unverändert; **nichts davon ist bereits als laufende Chain implementiert**.

## Netzwerkzugang und Netzwerk-Admin (ADR 0008)

**Keine zentrale Benutzerplattform erforderlich:** Hubs verbinden sich über lokal überprüfte Chain-ID, Genesis-Prüfsumme und CometBFT-Seed-/Persistent-Peers direkt mit der Blockchain. Es gibt **keinen verpflichtenden** `potatium-network`-Registrierungs-/Bootstrap-Server und **keine zentrale Coin-DB**. Ein optionaler Statussammler gehört nur zur Telemetrie.

**On-chain-Mining-Registry statt Benutzerkonto:** Zugelassene Betreiber- und Mining-IDs werden durch protokollautorisierte, signierte Freigaben/Sperren gepflegt. Ein lokaler Node-Fingerprint ist ohne Besitznachweis und Freigabe keine Mining-Berechtigung. Ein Hub bleibt autonom, Worker hängen an ihrem Hub; die gemeinsame browserseitige Wallet dient als Auszahlungsziel, private Spend-Keys bleiben lokal im Browser.

**Nur für den Netzwerkbetreiber:** Getrenntes Network-Admin-Cockpit **ab erstem funktionsfähigem Devnet**, mit echter Block-/Validator-/Supply-/Burn-/Fonds-/Gebühren-/Registry-Sicht und transparentem Status für registrierte, beobachtete und aktiv minende Nodes. Frühe schreibende Funktionen sind **ausschließlich autorisierte Identitätsfreigabe und -sperre** über eine getrennte sichere Signaturkomponente, nach der entsprechenden M4-Implementierung. Die übrige Admin-Ansicht bleibt lesend. On-chain-Zahlen sind technisch für Full-Node-Betreiber nachvollziehbar, auch wenn der Admin-Bildschirm nur dem Betreiber zur Verfügung steht.

**Betrieb:** Anfangs nur `potatium-dev` mit getrennten Devnet-/Hub-/Admin-Prozessen; später vier Validatoren und optional ein geschützter `ptm-admin`-LXC. Kein Admin-Server ist Voraussetzung für Konsens. [Installationsplan](docs/INSTALLATIONSPLAN_HOMELAB.md) · [Netz/Identitäten](docs/NETWORK_ZUGANG_UND_IDENTITAETEN.md) · [Cockpits](docs/COCKPITS_UND_MONITORING.md) · [ADR 0008](docs/decisions/0008-schlanker-netzzugang-admin-und-identitaeten.md).

## PoP-Gebührenforschung (Stand 25.10.2026)

Die aktuelle **36-Läufe-Langzeitsimulation** mit dynamischen Worker-Entscheidungen und hypothetischen Fonds-Ausschüttungen ist dokumentiert: [Auswertung](docs/POP_DYNAMIK_FONDS_AUSWERTUNG_2026-10-25.md) · [Vergleichs-CSV](docs/research/po_p_dynamic_20261025_comparison.csv). Ein 5×-Gebührenmodell reduziert die Zahl aktiver Zusatzworker in diesem Szenario deutlich, jedoch können trotz 0 % Burn **bis zu 70 %** der erzeugten PTM im Fonds gebunden sein. Daraus werden **keine endgültigen Gebühren, Workergrenzen oder Fonds-Auszahlungsregeln** abgeleitet. Die einzige entschiedene Gebührenverwendung bleibt **100 % PoP-Fenster-/Workergebühren zum On-chain-Fonds, 0 % Burn dieser Kategorien**. Alle Simulationen sind Forschung, keine funktionierende Blockchain.