diff --git a/.gitignore b/.gitignore index a91aa99..ce130bb 100644 --- a/.gitignore +++ b/.gitignore @@ -35,3 +35,7 @@ data/ # Local transient *.tmp *.swp + +# Python research simulations +__pycache__/ +*.py[cod] diff --git a/AGENTS.md b/AGENTS.md index abbf3ce..c703b36 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,14 +1,12 @@ -# Codex-Projektregeln für Potatium +# AGENTS.md: verbindliche Leitlinien für Codex im Potatium-Repository -Diese Datei ist die kurze, maßgebliche Arbeitsanweisung für alle Coding-Agenten. - -1. **Projekt verstehen:** `README.md`, `docs/PROJEKTPLAN.md`, `docs/PROTOKOLL_ENTWURF.md`, `docs/ROADMAP.md`, `docs/WEB_WALLET.md` zuerst lesen. Entscheidungen (`docs/decisions`) beachten. Ungeklärte Punkte nicht als festgelegt ausgeben. -2. **Sicherer Anfang:** Das vorhandene Repository ist nur ein compilierbares Grundgerüst. `potatiumd` zeigt eine statische Web-Wallet-Vorschau, hat noch keine Blockchain, keine Schlüsselverwaltung und keine echte API. Implementierten Status ehrlich halten. -3. **Architektur:** Go, CometBFT + ABCI++ als vorläufiger Stack; eigenständige PoP-Miner und Validatoren getrennt. UI **ab erster funktionaler MVP-Version**, nicht verschieben. -4. **Mining:** Ein gültiges Los je freigegebener Node-ID pro Runde; kleine PoW-Aufgabe; Teilnehmermenge fixieren, dann erst überprüfbare Zufallszahl ziehen; keine offensichtlichen Mehrfachlose; manuelle Nodefreigabe löst Sybil-Problematik nur organisatorisch. -5. **Wallet-Sicherheit:** Kein privater Schlüssel/Seed ans Backend oder ins Git. Browser-Krypto erst auf Basis einer explizit geprüften Schlüssel-/Signaturspezifikation und gepflegter Bibliotheken. Den UI-Entwurf nicht als funktionale Wallet verkaufen. -6. **Arbeitsweise:** Zuerst Bestandsaufnahme und kurze Umsetzungsplanung, dann kleine überprüfbare Änderungen. Keine unbegründeten neuen Frameworks oder großen Abhängigkeiten. Keine produktiven Ports nach außen. -7. **Prüfen:** `gofmt`, `go test ./...`, `go vet ./...`, Shell-Syntaxprüfung; bei Bugs Regressionstest. Tests und Grenzen nennen, nichts erfinden. -8. **Docs synchron:** Architektur-/Protokollentscheidungen in `docs/decisions/` mit Status Proposed/Accepted/Rejected; Roadmap aktualisieren. Keine stillschweigenden Änderungen bereits angenommener Produktziele. -9. **Git:** Kleine logisch getrennte Commits vorschlagen; nicht ungefragt pushen, remotes überschreiben oder irreversible Befehle ausführen. -10. **Zielplattform:** Ubuntu Server 26.04 LTS im unprivilegierten Proxmox-LXC; Builds später für Linux AMD64/ARM64; Raspberry Pi 4 als Zielreferenz. +1. **Zuerst lesen:** `README.md`, `docs/PROJEKTPLAN.md`, `docs/PROTOKOLL_ENTWURF.md`, `docs/POP_FAIRNESS_UND_GEBUEHREN.md`, `docs/ROADMAP.md`, `docs/WEB_WALLET.md`, `docs/decisions/*.md`. Die letzte akzeptierte ADR entscheidet bei historischen Widersprüchen. Der *tatsächliche Git-Stand* ist maßgeblich. +2. **Bestandsaufnahme:** Umgebung Ubuntu 26.04 LTS im unprivilegierten LXC, Workspace `/home/potatium/src/potatium`, Go, private Gitea-Git-Remote. Bestehende Änderungen erhalten; nicht ungefragt branch/rebase/push oder `git clean/reset` verwenden. +3. **Architektur:** eigenständige Hobby-L1, Go, CometBFT/ABCI++ mit eigener deterministischer App als vorläufige Wahl, kein Cosmos SDK für den Start. Validatoren bestätigen Blöcke, Miner lösen nur PoP-Challenges. `linux/amd64` und `linux/arm64` als Ziel; Pi 4 als Benchmarkminimum. +4. **PoP v0.2 (akzeptierte Produktidee):** Jede Mining-Runde hat **3 zeitlich getrennte Fenster**. Fenster 1 gratis; Fenster 2/3 optional solange noch kein gültiges Ticket angenommen wurde und nach bestätigter **fixer + progressiver** Gebühr. Progressionsbasis: finalisierte PoP-Mining-Gewinne der zurückliegenden **ca. 90 Tage je registrierter Mining-Identität/Betreibergruppe**, **nicht Wallet-Guthaben**. Keine lebenslange Benachteiligung. Zusatzgebühren burnen; normale Transaktionsgebühren sollen Validatoren finanzieren, Aufteilung noch offen. Pro identifizierter Mining-Node **maximal ein Ticket je Gesamtrunde**. Nach Erfolg stoppen. Identität/Hardware und Betreiberzuordnung können Sybil nicht kryptografisch beweisen. +5. **Noch nicht entschieden:** BTC-artige Coin-Grenze, Mint je Runde, Gebührenbeträge/Schwellen, Nonce-Raum, exakte Fensteranzahl an Blöcken, p=70 %, feste Blockzeit, Wallet-Kryptografie, Beaconauswahl. Beispiele niemals als gültige Konsensregel kodieren. Vor PoP-Implementierung Simulationen und Pi-Messung samt ADR. +6. **Ziehung:** Ticketbestand vor künftiger überprüfbarer Zufallsquelle finalisieren. Kein `time.Now()`, externe Zufallsabfrage oder Float in deterministischen State-Transitions. Reorgs, Zeit-/Höhenfristen, Beacon-Ausfall, Zensur, Replay, Rundungsrest und Multi-Node-Gleichheit behandeln. +7. **Gebühren/Wallet:** Browser-Web-Wallet **ab erster funktionaler MVP-Version**; Keys erzeugen, importieren, verschlüsselt sichern/entsperren, Adresse, Balance, senden/empfangen, Verlauf/Netzstatus. Miner/Node erhalten nie Private Keys/Seeds. Zusatzfenster nur mit explizit begrenzter signierter Wallet-Freigabe, auf Runde/Identität/Fenster, Betrag, Nonce und Ablauf gebunden; noch nicht implementiert. UI-Vorschau niemals als funktionsfähig ausgeben. +8. **Tests:** Go `gofmt`, `go test ./...`, `go vet ./...`; passende Integrationstests, fuzzer/race tests. Für PoP Simulation und Pi 4 / Office-PC Benchmark, Fairness, Gebühren-Erwartungswerte, abweichenden Codepfad, Replay, Burn und Restart. Tests und Resultate **nie erfinden**. +9. **Sicherheit:** keine öffentlich gebundenen Test-APIs (nur `127.0.0.1`/SSH-Forward), keine echten Schlüssel/Tokens/Datenbank-/Wallet-Dateien in Git. Keine unverhältnismäßigen Dependencies, keine destruktiven Befehle ohne Backup. Entgeltliche Chance auf Lotteriegewinn birgt Rechtsrisiko; bis auf Weiteres **wertlose private Test-PTM**. +10. **Lieferstil:** Vor jeder größeren Änderung kurze Planung + Akzeptanzkriterien; danach Dateien/Änderungen, was real läuft, Testbefehle mit Ergebnissen, Grenzen und nächsten kleinen Schritt angeben. ADR für wesentliche Entscheidungen. diff --git a/MANIFEST.sha256 b/MANIFEST.sha256 deleted file mode 100644 index 55c39c0..0000000 --- a/MANIFEST.sha256 +++ /dev/null @@ -1,49 +0,0 @@ -9ef17180649a9a689e8239a101386ca8830962982f60d9c81fae1e45f7a3b484 .gitignore -8ef11d24653a13a8e1496caf94b3492932245dc60e5e9ed2b311f63d7045fc06 .vscode/extensions.json -f7cced76517ef91443d379177b12b8b816595bd3f408cc24a48cb4d56ee38865 .vscode/settings.json -ca782da4395861f3c348c6da33132c122b6d84b40769ebbc6d359d1a4559bd67 .vscode/tasks.json -7e765ce754536560cf54a751634ee83a65ec80fa80ed485a92226e2435032dfc AGENTS.md -486b99fb54ca9ce6dda019609f8796ca3bd1c6c48a2646ec45f8b2e23e73bda5 Makefile -52619691b2b8443b7b0c5f1fb3a854cff613418ae0b334c0dd05021d7db973a1 README.md -a546792b431f329f3d8abdb499572add3c09692f4fe6b0a41c52e131653f5cb7 START_HIER.md -1831a06d6a49ca4fd93900a235802fbceb6a46168edc415fc74a9daa09a77958 assets/logo/README.md -085e2431e7613200ccf89de2186f0f8f6fd5fc0fc176056114424a34d65b3f93 assets/logo/potatium-ptm-logo.png -dd0d89e4921da401066bb155755837cf2229e667bb90a2d456ee99f65bf208cb cmd/potatium-cli/main.go -33630bab5c0558b937d3e776a31d347e38273f498b4f893548cf59e8bead41f5 cmd/potatium-miner/main.go -3d0641d3cae708de6c85b3722f5e5d40eb5c032e267fdcf423128137a5ce38f5 cmd/potatiumd/main.go -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 config/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 deploy/devnet/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 deploy/testnet/.gitkeep -8378bb2a6801609474f871ae90d2c237acf5fbefc2245db0d54af43595fa2233 docs/ARCHITEKTUR.md -ae4368bc1d686fe501a6ee772bf39bf02a399486108d0ae3f98a1a53d40bb22a docs/GESAMTHANDBUCH.md -c139ae677ecf45c73a709b6e31ef99132a655678320f664866b8d78eec0fddef docs/PROJEKTPLAN.md -2f8559302bac1bbeb46af8d252c434d554a0b8aad4cc69389b737a83b88e7e5a docs/PROTOKOLL_ENTWURF.md -83e7c3c72f70972663f4358a5d0c893c8cad85242ee33a826e2d0891a95b4ecb docs/REFERENZEN.md -560cd68598546a06a9d5bdfb996b987f9d96d0b991e92880c510488b8e35b9b5 docs/ROADMAP.md -66f76cb6ace0ba50509fec93209b014c08d6f4bcf370974d08d36ed51cdfb28d docs/WEB_WALLET.md -19c50fe0251f0531ae8b018b140297ae84108f39e5b5e1e8cc397c9bd101500d docs/decisions/0001-projektgrundlagen.md -4af2dbb1b14ebee683e7c438a2463c5585f884b2082e5f89b51cd053ed731bdf docs/decisions/0002-konsens-stack.md -a560012ba32412263738b1c76f1da230e690280e7789d22e769b7555c7350a25 go.mod -b7769c9f11d90ce6256c67f20e0517ed2f89278d100aaab54ab6f20377efba7c handoff/CHATGPT_PROJEKTANWEISUNGEN.md -42f2fc4a24b5da4a9211bc46dbe52528e466dcecd6bb8ccc1fccdae6204bfb8b handoff/SCHNELLKOPIE_CHATGPT.md -42049f3aef1d27eb01a212647030d12be5a4d9c7c08e535983ffe07ae67a197a handoff/STARTPROMPT_VSCODE_CODEX.md -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/api/.gitkeep -99fdfdef340030a188e35dc233545d8bb123b2964a584438e544eeaf5b31ffb7 internal/app/status.go -a5e1ad960dd5c2d0741eed16f690c5f0a6f289300355d05919608cb888ca0aba internal/app/status_test.go -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/chain/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/consensus/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/crypto/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/lottery/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/mining/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/registry/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/storage/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/transaction/.gitkeep -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 internal/wallet/.gitkeep -5632066791b84ef6b7b69879ccc8787456d168f628c057b14104d701c6bb400c scripts/bootstrap_workdir.sh -f29b8055c2059be6a4759d4109de034ddef1ebcb5b60b3efb9086ff98505ff67 scripts/doctor.sh -889152d7ef7193b08297e7cb7d3d9289331cce71f93767b3940409ed08cca2cb scripts/install_go.sh -91bf68dc54412d2eb281ee788a29faeb368a4b0b4b96327983171c1499f689f3 scripts/setup_ubuntu26.sh -e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 tests/integration/.gitkeep -8405e8e7c258090e4a299209490a66db421afa864ed96d3dca33d1c75a7444b5 web/wallet/app.js -a76fbe4707266bd228c5b9675905c0e00aedd496a579e9c5186702be61e7707a web/wallet/index.html -89d89bff51bc5a61a3991fa36ef7657521933fc24d9678a2cfde58079d5959eb web/wallet/styles.css diff --git a/README.md b/README.md index d343f63..876e0fc 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,36 @@ # 🥔 Potatium (PTM) -**Eigenständige Hobby-Blockchain mit ressourcenschonender Proof-of-Potato-Lotterie.** +**Eigene Hobby-Layer-1 mit sparsamer Mining-Lotterie „Proof of Potato“.** Das goldene abstrakte PTM-Logo liegt unter `assets/logo/potatium-ptm-logo.png`. -Status **Projektgerüst / vor der Protokollimplementierung**. Dies ist ausdrücklich noch keine einsatzfähige Kryptowährung! Die enthaltene Weboberfläche ist ein **nichtfunktionaler Wallet-Entwurf**, keine Wallet zum Verwahren echter Werte. +**Stand 25.10.2026: nur Go-Projektgerüst und statische Web-Wallet-Vorschau; keine echte Blockchain, kein Minting und keine funktionale Wallet.** Vorerst ausschließlich privates Testnetz mit wertlosen Test-PTM. -## Schnelleinstieg +## Entwicklungsumgebung -1. **`START_HIER.md`** lesen. Zielsystem: Ubuntu Server **26.04 LTS** als unprivilegierter Proxmox-LXC. -2. `sudo bash scripts/setup_ubuntu26.sh` installiert Basispakete und eine per SHA-256 geprüfte Go-Version. -3. `bash scripts/bootstrap_workdir.sh` ergänzt fehlende Verzeichnisse, ohne Dateien zu überschreiben. -4. `bash scripts/doctor.sh` prüft Installation und Starter-Build. -5. VS Code via Remote-SSH öffnen und `handoff/STARTPROMPT_VSCODE_CODEX.md` in Codex verwenden. +- Ubuntu **26.04 LTS** als unprivilegierter Proxmox-LXC `potatium-dev` +- Benutzer `potatium`, Workspace **`/home/potatium/src/potatium`** +- Go, Git-Monorepo auf privatem Gitea, VS Code per Remote-SSH mit OpenAI Codex +- Zunächst kein Docker-in-LXC und keine PostgreSQL-Pflicht -## Geplante Programme +## Neues Mining-Konzept v0.2 -- `potatiumd`: Blockchain-Node, später CometBFT/ABCI++-Anwendung und HTTP/RPC. -- `potatium-miner`: eigenständiger, sparsamer Miner für PCs und Raspberry Pis. -- `potatium-cli`: Wallet-/Netzwerk-CLI. -- `web/wallet`: **Web-Wallet ab MVP**, mit Erstellen/Import, Guthaben, Empfangen, Senden, Historie und Sperren/Entsperren. +Je **einer Mining-Runde** gibt es **drei aufeinanderfolgende Aufgabenfenster**. Das erste ist kostenlos; Fenster 2 und 3 können solange kein Ticket vorliegt freiwillig gegen **fixe und progressive** Kosten benutzt werden. Grundlage der Progression sind die **PoP-Mining-Gewinne der letzten ca. 90 Tage** je registrierter Identität/Betreibergruppe, nicht das Wallet-Guthaben. Gebühren zusätzlicher Fenster werden **verbrannt**. Nach einem erfolgreichen Proof erhält die Identität maximal **ein Ticket** für die spätere, überprüfbare Gewinnziehung. **Alle konkreten Zahlen bleiben bis zu Simulation und Pi-Benchmark offen.** Mehr: `docs/PROTOKOLL_ENTWURF.md`, `docs/POP_FAIRNESS_UND_GEBUEHREN.md`, ADR 0003. -## Was aktuell schon läuft? +## Bestandteile -Das Starterprojekt enthält einen kleinen lokalen **UI-Vorschau-Server**, aber **keine Blockchain**, keine Schlüsselverwaltung und keine echte Transaktion: +- `cmd/potatiumd`, `cmd/potatium-miner`, `cmd/potatium-cli`: geplante ausführbare Go-Programme; bisher teils nur Gerüste. +- `internal/`: Zustandslogik, Kryptografie, Registrierung, Proof, Lottery, Persistenz und API. +- `web/wallet`: **statische Webvorschau**, keine Keys/realen Kontostände; echte Web-Wallet bleibt Pflicht **ab funktionalem MVP**. +- `docs/`: Gesamthandbuch, Projektplan, Protokoll, Roadmap, ADRs. +- `AGENTS.md`: bindender Arbeitskontext für Codex. + +## Checks und Vorschau ```bash -go test ./... -go run ./cmd/potatiumd -web-dir web/wallet -listen 127.0.0.1:8080 +cd /home/potatium/src/potatium +bash scripts/doctor.sh +make run-ui ``` -Aufruf lokal `http://127.0.0.1:8080`; bei Remote-SSH Port 8080 in VS Code weiterleiten. +`make run-ui` bindet nur an `127.0.0.1:8080`; im VS-Code-Remote-Portforwarding öffnen. Keine echten Wallet-Schlüssel oder Coins verwenden. -## Arbeitsgrundlage - -- `AGENTS.md`: bindende Projektregeln für Codex. -- `docs/PROJEKTPLAN.md`: ausführliche technische Übergabe. -- `docs/ARCHITEKTUR.md`: Komponentengrenzen. -- `docs/PROTOKOLL_ENTWURF.md`: bestätigte und offene Protokollregeln. -- `docs/WEB_WALLET.md`: MVP-/Sicherheitsanforderungen. -- `docs/ROADMAP.md`: inkrementelle Meilensteine. -- `handoff/CHATGPT_PROJEKTANWEISUNGEN.md`: ChatGPT-Projektanweisungen, **unter 8.000 Zeichen**. - -**Kein Finanzprodukt / kein Mainnet:** Alles zunächst nur Testnet und wertlose Test-PTM. Niemals produktive Schlüssel in Git oder im Chat ablegen. +**Nächster Schritt:** M1-Parameter (Coin/Signatur/PoP-Fees) per Simulation und ADR bestätigen, danach Ledger/Web-Wallet beginnen. Startprompt: `handoff/STARTPROMPT_VSCODE_CODEX.md`. diff --git a/docs/ARCHITEKTUR.md b/docs/ARCHITEKTUR.md index 785ab97..e71bf2c 100644 --- a/docs/ARCHITEKTUR.md +++ b/docs/ARCHITEKTUR.md @@ -1,52 +1,40 @@ -# Architekturentwurf +# Architekturentwurf v0.2 + +**Nur Zielarchitektur, nicht laufende Blockchain.** ```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) +Web-Wallet (clientseitige Schlüssel) Raspberry Pi / alter PC + | potatium-miner + signierte Transaktionen / beschränkte Fee-Autorisierung + | | + potatiumd RPC/API (lokal) + | + deterministic Go State Machine: Konten, Nonces, + PoP-Runden/Fenster, Gebühren, Burn, Tickets, Ziehung + | + eigene CometBFT ABCI++ App + | + CometBFT Validator weitere Validatoren + | + eigener persistenter State ``` -Diese Skizze ist eine **Zielarchitektur**, nicht bereits implementiert. +## Verantwortlichkeiten -## Prozess- und Verantwortungsgrenzen +- **Validatoren:** CometBFT legt Blöcke und Reihenfolge fest; die Go-State-Machine lehnt ungültige Transfers, Burn, Proofs und Mint ab. Kein Coin-/Mining-Bezug zur Validator-Blockerzeugung. +- **Miner:** separates Go-Programm für Linux amd64/arm64, ressourcenschonende Arbeit, Node-ID-Signatur, bis drei Fenster pro **einer** Runde, höchstens ein gültiges Ticket. Kann rein kostenlos betrieben werden. +- **Wallet:** browserlokale Schlüssel-/Backupverwaltung und Signatur, kein Key-Export an Backend. Bezahlte Zusatzfenster nur nach enger runden-/fenster-/betrags-/noncegebundener Autorisierung, niemals pauschale Miner-Keyfreigabe. +- **State:** jeder Validator hält eigenen deterministischen Ledger inklusive Fensterzustand, signierter Proofs, Mining-Gewinnhistorie der letzten ca. 90 Tage, Betreiberzuordnung, Gebühren/Burn und Ticketlisten-Commit. Der 90-Tage-Begriff benötigt deterministische finale Fensterdefinition (Blockzeit versus Blockhöhe). +- **Transport:** localhost-only für Entwicklungs-RPC, SSH-Forwarding, sichere später explizit freigeschaltete P2P-Verbindungen. -- 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. +## Verifikationskette -## Netzwerk & Reihenfolge +1. Runde/Fenster mit finalisiertem Startzustand und identitätsgebundener Challenge. +2. Fenster 1 ohne Zahlung; Fenster 2/3 nur nach bestätigter, integergenau berechneter fixer plus progressiver Burn-Gebühr. +3. Fristgerechter Proof mit Hash und erlaubter Nonce; max. ein Ticket pro Mining-ID pro Gesamtrunde. +4. Tickets endgültig festschreiben, anschließend fremden unbekannten verifizierbaren Beacon-Wert erhalten und Winner/Mint deterministisch berechnen. +5. Gegen Identitätswechsel, Replay, Zensur, RNG-Manipulation, fehlende Tickets, Down-/Restart und Differenzen zwischen Validatoren testen. -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. +## Kritische Unbekannte -**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. +Coin-Einheit, Adress-/Tx-/Signaturformat, Fee-Formel und Rundung, Fenstertiming, Staking/Validator-Gebührenanteile, PI-Benchmark, RNG-Quelle/Fallback, Registry-Gruppierung und persistente Datenbank bleiben offen. Dafür ADRs; keine willkürlichen Defaults. diff --git a/docs/GESAMTHANDBUCH.md b/docs/GESAMTHANDBUCH.md index 672880c..6cff259 100644 --- a/docs/GESAMTHANDBUCH.md +++ b/docs/GESAMTHANDBUCH.md @@ -1,497 +1,89 @@ -# 🥔 Potatium – Gesamthandbuch und technische Übergabe +# Potatium: Gesamthandbuch (aktueller Stand v0.2) -**Stand: 24.10.2026 · für Ubuntu Server 26.04 LTS · Potatium/PTM.** +*Stand: 25.10.2026. Dieses Dokument ersetzt die frühere v0.1-Beschreibung; es dokumentiert den abgestimmten Produktentwurf, **keine** fertig implementierte Kryptowährung.* -Diese Datei vereint die Anleitung zum Setup mit dem bisherigen, verbindlich bzw. vorläufig beschlossenen Produkt- und Architekturkonzept. Die Einzeldateien im Ordner `docs/` sind die editierbaren Quellen. Für die IDE-Entwicklung außerdem `AGENTS.md` und `handoff/STARTPROMPT_VSCODE_CODEX.md` beachten. +## 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 -# Inbetriebnahme +- 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. -# 🥔 Potatium: Schritt-für-Schritt-Start auf Ubuntu 26.04 LTS - -**Arbeitsannahme:** unprivilegierter Proxmox-LXC mit **Ubuntu Server 26.04 LTS**, nicht 26.10. Development-Maschine heißt `potatium-dev`, Linux-Benutzer `potatium`, Git-Monorepo liegt in `/home/potatium/src/potatium`. Das hier ist ein **funktionsfähiges Entwicklungsgerüst**, noch keine Blockchain und keine echte Wallet. - -> **Die Reihenfolge ist wichtig:** LXC → erstmalig SSH/Basiszugang → ZIP übertragen/entpacken → Ubuntu-Setup-Skript → Prüfskript → Git → VS Code/Codex → Architektur-/Protokollentscheidungen → eigentliche Entwicklung. - -## 1. Proxmox-LXC erstellen (Proxmox-Weboberfläche) - -| Einstellung | Wert | -|---|---| -| Template | Ubuntu **26.04 LTS** amd64, idealerweise 26.04.1 | -| Hostname | `potatium-dev` | -| Typ | **Unprivileged** | -| CPU / RAM / Disk | 4 vCPU / 4 GiB / 40 GiB | -| Netzwerk | internes LAN, Bridge wie gewohnt, stabile IP über DHCP-Reservierung oder statische Adresse | -| Features | Standard, **kein Nesting/Docker nötig** | -| SSH / Port-Freigaben | ausschließlich internes LAN / VPN; keine externe 8080-Freigabe | - -**Wichtig:** Die 4 vCPU sind für Entwicklung und Mehrprozess-Tests gedacht, nicht die spätere Mindesthardware eines Miners. Snapshot/Backup des LXC nach Basisinstallation vorsehen. - -## 2. Im Proxmox-Console-Terminal als root den Erstzugang vorbereiten - -Die Bootstrap-Dateien können noch nicht auf dem LXC sein. Darum einmalig diese kurzen Befehle direkt in der LXC-Konsole ausführen: - -```bash -apt update -apt install -y openssh-server sudo unzip -adduser potatium -usermod -aG sudo potatium -systemctl enable --now ssh -``` - -`adduser` fragt dich interaktiv nach einem vorläufigen Benutzerpasswort. Lege dieses selbst fest (nicht in Chat/Git veröffentlichen!). Falls Benutzer `potatium` bereits vorhanden ist, den `adduser`-Schritt überspringen. Sicherstellen, dass der LXC eine erreichbare IP hat: - -```bash -hostname -I -``` - -**Falls SSH-Passwortauthentifizierung im Container deaktiviert ist:** Statt sie global unsicher freizuschalten, über die Proxmox-Konsole den öffentlichen SSH-Schlüssel unter `/home/potatium/.ssh/authorized_keys` für Benutzer `potatium` hinterlegen (Eigentümer `potatium`, Rechte `.ssh` = 700, `authorized_keys` = 600). Niemals einen privaten Schlüssel kopieren. - -## 3. Das ZIP vom lokalen Rechner auf den LXC kopieren - -1. `Potatium_Starterkit_2026-10-24.zip` hier herunterladen. -2. Auf deinem lokalen Mac/PC ein Terminal öffnen; `` durch die echte Adresse ersetzen. -3. Aus dem Verzeichnis, in dem das ZIP liegt, ausführen: - -```bash -scp Potatium_Starterkit_2026-10-24.zip potatium@:/home/potatium/ -ssh potatium@ -``` - -Du landest nun als normaler Benutzer `potatium` auf dem LXC. Passwortloses SSH konfigurieren wir nach dem erfolgreichen Basischeck. - -## 4. Archiv ins Workdir entpacken - -```bash -mkdir -p ~/src -unzip -n ~/Potatium_Starterkit_2026-10-24.zip -d ~/src -cd ~/src/potatium -ls -la -``` - -Das ZIP enthält bereits den Ordner `potatium/` mit allen Dateien. **Nichts händisch nachbauen.** `-n` verhindert, dass ein erneutes Entpacken vorhandene Dateien überschreibt. - -## 5. Ubuntu automatisch einrichten - -```bash -sudo bash scripts/setup_ubuntu26.sh -``` - -Dieses Skript: - -- prüft **Ubuntu 26.04 LTS**, installiert SSH/Git/Compiler/Basispakete; -- sorgt für Benutzer `potatium` und `~/src`; -- installiert **Go 1.27.3** für amd64 bzw. arm64 aus offiziellen Go-Archiven mit eingebauter SHA-256-Prüfung; -- überschreibt eine andere vorhandene `/usr/local/go`-Installation ausdrücklich **nicht**. - -Eine erneute Anmeldung kann für geänderte Gruppenrechte hilfreich sein. Danach im Projektordner: - -```bash -cd ~/src/potatium -bash scripts/bootstrap_workdir.sh -bash scripts/doctor.sh -``` - -**Verzeichnisstruktur:** Das ZIP bringt sie schon mit; `bootstrap_workdir.sh` ergänzt fehlende Verzeichnisse wiederholbar und lässt existierende Dateien unverändert. Das Prüftool führt u. a. Go-Tests und `go vet` aus. `go.mod` verwendet für den allerersten lokalen Build den vorläufigen Modulnamen `potatium.local/potatium`. Sobald das private Remote bekannt ist, kann Codex den Modulnamen und alle zugehörigen Imports in einem konsistenten Commit umstellen. - -## 6. Testweise die WebGUI-Vorschau öffnen - -```bash -cd ~/src/potatium -make run-ui -``` - -Die Vorschau lauscht **nur auf 127.0.0.1:8080 im LXC**. Zum Anzeigen vom lokalen Rechner entweder später die VS-Code-Portweiterleitung für Port 8080 verwenden oder ein SSH-Tunnel in einem zweiten lokalen Terminal öffnen: - -```bash -ssh -L 8080:127.0.0.1:8080 potatium@ -``` - -Danach im lokalen Browser `http://127.0.0.1:8080` öffnen. **Wichtig:** Schaltflächen sind absichtlich deaktiviert. Keine echte Wallet, keine Coins, keine Blockchain! Abbrechen mit `Ctrl+C` im laufenden Go-Terminal. - -## 7. Git-Repository anlegen - -Beim eigenen Git-Dienst deiner Wahl ein **neues privates, leeres** Repository `potatium` erstellen. Nicht zusätzlich README, Lizenz oder `.gitignore` initialisieren lassen, da diese bereits im ZIP vorliegen. Noch keine öffentliche Zugänglichkeit erforderlich. - -**Im LXC als `potatium`:** - -```bash -cd ~/src/potatium -git init -b main -git config user.name "DEIN-GIT-NAME" -git config user.email "DEINE-GIT-EMAIL" -git add . -git commit -m "chore: initialize Potatium project scaffold" -git remote add origin -git push -u origin main -``` - -`` ist die echte SSH-Clone-URL deines neuen Repos und **kein** wörtlich auszuführender Platzhalter. Vor Push einen **separaten SSH-Schlüssel für `potatium` -> Git-Server** erstellen und dessen **öffentlichen** Schlüssel auf dem Git-Server hinterlegen: - -```bash -ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "potatium-dev git" -cat ~/.ssh/id_ed25519.pub -``` - -Bei bestehendem `~/.ssh/id_ed25519` nicht überschreiben! Stattdessen bestehenden Schlüssel verwenden oder einen separaten mit anderem Dateinamen und `~/.ssh/config`-Hostzuordnung erzeugen. Auch den Server-Fingerprint beim ersten SSH-Kontakt sorgfältig prüfen. **Nie** privaten Key, Seed oder Token ins Git pushen. - -Optional: Über `git status` sicherstellen, dass `bin/`, `.local-data/`, Secrets und `.env` ignoriert sind. Bis zur Architekturentscheidung noch kein produktives `mainnet`. - -## 8. Lokalen Rechner mit VS Code verbinden - -1. Auf Mac/PC **Visual Studio Code** installieren. -2. VS-Code-Erweiterung **Remote - SSH** installieren. -3. Optional auf dem Mac `ssh-keygen -t ed25519` ausführen (nur falls noch kein SSH-Schlüssel existiert); den **öffentlichen** Schlüssel am LXC hinterlegen. -4. Lokale Datei `~/.ssh/config` ergänzen: - -```ssh-config -Host potatium-dev - HostName - User potatium - IdentityFile ~/.ssh/id_ed25519 -``` - -5. In VS Code Befehl **Remote-SSH: Connect to Host...** → `potatium-dev`. -6. Auf dem Remote-Host Ordner `/home/potatium/src/potatium` öffnen. -7. Erweiterungen **Go** und **OpenAI Codex** installieren bzw. in der Remote-SSH-Sitzung nutzbar machen; über dein ChatGPT-Konto anmelden, sofern für deinen Plan verfügbar. -8. Integriertes Terminal: `bash scripts/doctor.sh`; anschließend Aufgabe **Potatium: Wallet Vorschau** wählen und **Port 8080 weiterleiten**. - -Die offizielle OpenAI-Erweiterung wird im VS-Code-Marktplatz als Codex angeboten. Die Datei `AGENTS.md` enthält verbindliche Arbeitsregeln für Codex. - -## 9. Codex starten - -Datei `handoff/STARTPROMPT_VSCODE_CODEX.md` öffnen, **den Prompt-Text nach dem Trenner** kopieren und im Codex-Panel senden. Codex soll erst Repo und Tests überprüfen, offene Architekturfragen dokumentieren und dann kleine implementierbare Entwicklungsaufgaben planen. - -Nicht als Erstes „schreib die komplette Blockchain“ beauftragen: Kryptografie, State-Determinismus, Wallet und Lottery benötigen belastbare Entscheidungen und Tests. - -## 10. ChatGPT-Projekt (optional, wenn du es weiter nutzen möchtest) - -Für das separate ChatGPT-Projekt **Potatium** den Text aus `handoff/CHATGPT_PROJEKTANWEISUNGEN.md` in die Projektanweisungen kopieren. Er ist unter **8.000 Zeichen**. Als Dateien `docs/PROJEKTPLAN.md`, `docs/PROTOKOLL_ENTWURF.md`, das ausgewählte Logo und gegebenenfalls weitere technische Dokumente hinzufügen. - -Für das Arbeiten in VS Code/Codex ist **keine weitere Information aus diesem Chat erforderlich**. Nötige Informationen sind im Git-Repository versioniert. Bei neuen verbindlichen Entscheidungen die Markdown-Dokumentation aktualisieren und committen. - -## 11. Was du tatsächlich nach dem LXC-Start benötigst - -- Zugriff auf deine Proxmox-Oberfläche (für LXC, Snapshot und Konsole). -- Eine interne LXC-IP und SSH-Zugang / **eigene** SSH-Schlüssel. -- Das ZIP aus dieser Antwort. -- Ein privates **leeres** Remote-Git-Repository samt SSH-Clone-URL und Zugriffsschlüssel. -- VS Code samt Remote-SSH, Go und Codex auf deinem lokalen Rechner. -- Zugriff auf offizielle Paket-/Go-Downloads aus dem LXC. -- Später für PoP-Tests ein Raspberry Pi oder vergleichbar alter PC (anfangs nicht nötig). - -**Noch nicht benötigt:** Datenbankserver, Docker, externe Domain, HTTPS-Reverse-Proxy, Coin-Listing, echte Guthaben, ASIC/GPU, vier zusätzliche physische Server. - -## 12. Minimaler Funktionstest / erwartete Ausgaben - -```bash -cd ~/src/potatium -go version # go1.27.3 linux/amd64 oder linux/arm64 -go test ./... # erfolgreiche Tests, mit CLI-Paketen ohne Tests -go vet ./... # ohne Fehlermeldung -make build # erzeugt 3 Placeholder-Binaries in bin/ -./bin/potatium-miner # meldet explizit: noch kein Mining -./bin/potatium-cli # meldet explizit: keine echte Wallet -make run-ui # localhost:8080, statische WebGUI-Vorschau -``` - -Nach diesem Check ist **M0 technisch startbereit**. Für M1: `docs/PROTOKOLL_ENTWURF.md` und `docs/decisions/` gemeinsam mit Codex konkretisieren, bevor die ersten echten Ledger- und Wallet-Funktionen umgesetzt werden. - - ---- - -# Projektplan - -# 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. - - ---- - -# Architektur - -# Architekturentwurf +## 3. Zielarchitektur ```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) +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 ``` -Diese Skizze ist eine **Zielarchitektur**, nicht bereits implementiert. +**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. -## Prozess- und Verantwortungsgrenzen +## 4. PoP v0.2: Prinzip wurde abgestimmt -- 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. +**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. -## Netzwerk & Reihenfolge +- **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. -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. +### Erfolgschancen (bloßes Rechenbeispiel) -**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. +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. -## Repositorystruktur +### Gebühren und Fairness -`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. +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. -## Bedrohungsmodell (für Designreviews) +`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. -- 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. +**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. -# Protokollentwurf +## 5. Coin und Transaktionen: offen -# Potatium Protokoll v0.1 – Entwurf, nicht freigegeben +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. -## Bestätigte Produktziele +## 6. Web-Wallet ab erster funktionaler MVP-Version -- Neue eigenständige Blockchain mit nativer Kryptowährung Potatium (PTM). -- Leichte echte PoW-Aufgabe pro Miner/je Runde; pro **freigegebener Node-ID** maximal **ein** qualifiziertes Ticket pro Runde. -- Ein verifizierbarer Gewinner wird aus den rechtzeitig qualifizierten Tickets ausgelost; PTM-Emission als konsensgeprüfte Blockregel. -- Kleine Hardware (Ziel: Raspberry Pi 4) muss sinnvoll mitmachen können; mehr physische Geräte dürfen mehr Node-Identitäten haben. Registrierung zunächst manuell. -- Validatoren bestätigen Blöcke unabhängig von Lotteriegewinnern. -- Webbasiertes Wallet mit Basisfunktionen ab erstem funktionalen MVP. +- 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**. -## Noch zu entscheiden +## 7. Repository und Verfahrensregeln -| ID | Parameter | Aktueller Stand / Anforderung | -|---|---|---| -| P-01 | Maximale Coin-Menge | OFFEN, keine Annahme 21 Mio. | -| P-02 | Anfangsbestand/Genesis | OFFEN; Starthöhe/Valve der Testcoins festlegen | -| P-03 | Dezimalstellen | OFFEN; alle Werte ganzzahlig in Basis-Einheiten | -| P-04 | PoP-Emissionsplan | OFFEN; nicht automatisch 10 PTM | -| P-05 | Rundenlänge | OFFEN; nicht automatisch 120 s | -| P-06 | Konsens-Blockzeit | OFFEN; getrennt von Mining-Runden | -| P-07 | Proof | SHA-256 als Prototyp-Kandidat, kalibrieren auf Raspberry Pi | -| P-08 | Mining-Difficulty | feste/zeitbasierte Kalibrierung erst nach Benchmarks | -| P-09 | Teilnehmerliste | Höhe/Abschlussprozess und Eligibility-Fenster offen | -| P-10 | Zufallsbeweis | drand als Option; Ausfallverhalten offen | -| P-11 | Schlüssel und Adresse | Signaturalgorithmus, Serialisierung, Recovery offen | -| P-12 | Transaction Fees | zunächst niedrige Gebühren oder Testnet-Fee-Regel offen | -| P-13 | Validator-Modell | CometBFT fester Satz zu Beginn als Architekturpräferenz | -| P-14 | Registry-Administration | Autorisierung, Removal, Transparenz und Verfahren offen | +`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. -## Vorgesehene Invarianten +## 8. Nächste Schritte -1. Jeder akzeptierte Zustandsübergang deterministisch und reproduzierbar. -2. Keine Wallet darf Coins ohne gültige Protokoll-Ausgabe erzeugen. -3. Ein Ticket pro registrierter Node-ID pro Runde; Signatur/Nonce bindet es an Runde, Chain-ID und Challenge. -4. Ein Los nur dann, wenn PoW und Frist nach überprüfbaren Regeln erfüllt sind. -5. Ziehungsinput wird **vor** dem entscheidenden späteren Zufallswert festgeschrieben; Gewinnerberechnung vollständig nachprüfbar. -6. Wenn keine gültigen Tickets vorliegen, gilt eine ausdrücklich definierte Nicht-Auszahlung/Carryover-Regel (noch zu beschließen). -7. Keine Node-ID beweist eine einzigartige Hardware; Kryptografie löst das Sybil-Problem nicht allein. -8. Gleiche Chance **unter allen qualifizierten Losen**; nicht garantierte gleiche Qualifikationschance zwischen CPUs. +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. -## Testanforderungen - -Property-Tests für Ticket-Limit und Emission, Fuzzing für Parser und Eingaben, Replay/Double-Spend, deterministische Blöcke, RNG-/Commit-Tests, Snapshot/Restart, Pi-Benchmarks und Multi-Validator-Ausfalltests. Jede Definition einer Regel bekommt reproduzierbare Testvektoren. - - ---- - -# Web-Wallet - -# Web-Wallet: Mindestumfang ab erstem funktionalem MVP - -**Beschlossene Priorität:** WebGUI von Beginn an, nicht erst nach dem Mining-Release. Das mitgelieferte `web/wallet/index.html` ist ausdrücklich **nur Layout/Vorschau**. - -## Sichtbare Seiten und Funktionen - -1. **Start / Wallet anlegen:** sichere Erzeugung, Passwort und Backup-Hinweise; Import/Recovery einer bestehenden Wallet. -2. **Übersicht:** Wallet-Adresse kopieren, verfügbares PTM-Guthaben (nur aus vertrauenswürdig überprüfter Node-Antwort), Höhe/Netzwerkstatus. -3. **Empfangen:** Adresse plus QR optional; Betrag darf optional als URI vorgeschlagen werden, falls Protokoll entschieden. -4. **Senden:** Empfängeradresse validieren, Betrag in exakt definierter Basis-Einheit, Fee-/Total-Vorschau, explizite Bestätigung, Signieren im Browser, Submit an Node. -5. **Historie:** Transaktionen mit Hash, Uhrzeit/Blockhöhe, Eingang/Ausgang, Bestätigungsstatus; leere oder Offlinezustände korrekt anzeigen. -6. **Sicherheit:** sperren/entsperren, sicheres Export-/Backup-Verfahren, klare Warnung bei Verlust des Backups. - -## Sicherheits- und UX-Vertrag - -- Keine serverseitige Schlüsselverwaltung. Clientseitige Kryptografie auf Basis geprüfter, gepflegter Bibliotheken und dokumentierter Standardformate. -- Keine Schlüssel, Mnemonics, Signaturgeheimnisse oder Klartext-Backups in HTTP-Requests, Logs, Telemetrie oder Git. -- Keys verschlüsselt ablegen, starke Passwortableitung/KDF mit überprüfbaren Parametern, keine ungesicherten `localStorage`-Seeds; Backup/Recovery durch Tests prüfen. -- Browser-XSS als Key-Leak-Risiko behandeln, strikte CSP, keine fremden Inline-Skripte oder CDN-Abhängigkeiten bei Wallet-Code; Third-Party-Libraries pinnen und auditieren. -- Entwicklungsserver standardmäßig 127.0.0.1; für entfernten Zugriff VS-Code-Portforwarding/SSH. Später HTTPS mit geeigneter Authentifizierung und CORS-Regeln. -- UI nie „Transaktion bestätigt“ anzeigen, bevor der konsensgeprüfte Status tatsächlich vorliegt. Keine erfundenen Zahlen, keine Demo-Schlüssel als echte Wallet ausgeben. -- Mobile, Desktop und Tastaturnutzung berücksichtigen. - -## Design-Entscheidungen vor echter Implementierung - -Adressschema, Schlüsselsuite, Signing-Bytes, Nonce/Sequenz, Chain-ID, Gebühren, Unlock-Lebensdauer, Recovery-Standard, Wallet-Storage und API-Version als ADR dokumentieren. - - ---- - -# Meilensteine - -# Roadmap / Definition of Done - -## M0 – Übergabe & Entwicklungsgerüst (Startpaket) -- [x] Logo, ChatGPT-Anweisungen, Protokollentwurf, Codex-AGENTS und Roadmap archiviert. -- [x] Ubuntu-26.04-Setup-Skripte, Bootstrap, lokale UI-Vorschau und prüfbares Go-Gerüst bereitgestellt. -- [ ] Skripte im echten LXC ausführen und tatsächliche Ergebnisse bestätigen. -- [ ] VS Code, Codex, Git-Remote/SSH und erste Push-Verbindung herstellen. - -## M1 – Architektur & Protokollentscheidungen -- [ ] Offene P-01 bis P-14 priorisiert; erste ADRs über Accountmodell, Kryptosuite, Coin-Einheiten, Genesis, Block-/Rundenzeiten, PoP/RNG. -- [ ] Typspezifikationen und Testvektoren dokumentiert, Verantwortungsgrenzen fixiert. - -## M2 – Ledger/Accounts + erste funktionale Web-Wallet -- [ ] Genesis, deterministischer Chain-State, Transaktionen, Signaturen, Nonce, Mint-Check, Wiederanlauf. -- [ ] Sichere Wallet im Browser erstellen/importieren/sichern/entsperren, echtes Guthaben, signierte Zahlung, echte Historie. -- [ ] Browser-/Backendsicherheits- und Signaturtests, keine Seeds an Backend. - -## M3 – Validator-Netz -- [ ] ABCI++/CometBFT-Anbindung, ein Validator, danach 4 Nodes. -- [ ] Zustandskonsistenz, Neustart, Verlust von Verbindungen, Synchronisation nachgewiesen. - -## M4 – Proof of Potato -- [ ] Registrierung, signierte Herausforderung, leichte Hash-Aufgabe, Ticketlimit, Rundenabschluss, verifizierte Auslosung, Emission. -- [ ] Negativtests zu Mehrfachlosen, Manipulation, Verzögerung, Timeout, Beacon-Ausfall und Emissionsobergrenze. -- [ ] Messungen am Raspberry Pi 4 und Intel-Alt-PC: Zeit/CPU/RAM/Strom, sinnvolle Qualifikation. - -## M5 – Bedienung und Auslieferung -- [ ] Web-Wallet und Mining-/Chain-Status aufgeräumt; CLI; verständliche Fehler und Backups. -- [ ] Binaries linux/amd64 und linux/arm64; reproduzierbarer Build und CI; erste private Releases. - -## M6 – Privates Mehrhost-Testnet -- [ ] Separate Hosts, Netzunterbrechungen, Wiederherstellung, Schlüsselrotation, Dokumentation und Monitoring. -- [ ] Explizite Bewertung der Grenzen zentraler Registrierung und kleiner Validatoranzahl. - -**Gate:** Keine Phase als abgeschlossen markieren, ohne tatsächliche Tests. Dieses Paket erfüllt nur die Bereitstellung des Startgerüsts, nicht die Ausführung im Nutzer-LXC. - - ---- - -# Referenzen - -# Offizielle technische Referenzen (Stand 24.10.2026) - -- Ubuntu Server 26.04 LTS, Canonical: https://canonical.com/blog/canonical-releases-ubuntu-26-04-lts-resolute-raccoon -- Ubuntu-Releases: https://wiki.ubuntu.com/Releases -- Go-Releases und SHA-256-Prüfsummen: https://go.dev/dl/ -- Go-Linux-Installation: https://go.dev/doc/install -- VS Code Remote-SSH: https://code.visualstudio.com/docs/remote/ssh -- Codex VS Code: https://learn.chatgpt.com/docs/ide -- Codex-Repositorium-Anweisungen AGENTS.md: https://developers.openai.com/cookbook/examples/codex/iterating-development-workflows-with-codex -- CometBFT (ABCI++ und Konsens): https://docs.cometbft.com/ -- drand (verifizierbarer Zufall, Kandidat): https://docs.drand.love/ - -**Hinweis:** Vor dem Einbau von CometBFT und Browser-Wallet-Kryptografie unbedingt die zu diesem Zeitpunkt aktuelle API-/Versionskompatibilität prüfen. Eine Referenz im Dokument bedeutet nicht, dass die Bibliothek bereits integriert oder auditiert ist. +## 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. diff --git a/docs/POP_FAIRNESS_UND_GEBUEHREN.md b/docs/POP_FAIRNESS_UND_GEBUEHREN.md new file mode 100644 index 0000000..d93522a --- /dev/null +++ b/docs/POP_FAIRNESS_UND_GEBUEHREN.md @@ -0,0 +1,76 @@ +# Proof of Potato: Fairness, wirtschaftliche Anreize und Gebühren (v0.2) + +Diese Seite erläutert das **inhaltlich angenommene Drei-Fenster-Modell**; Zahlen sind ausdrücklich nur Forschungsparameter. Verbindlicher Protokollcode darf erst nach Simulation, Pi-Benchmark und finalem Parameter-ADR entstehen. + +## Warum drei Fenster? + +Die Blockchain erzeugt laufend Blöcke; eine **Mining-Runde** fasst mehrere Blöcke zusammen und hat **drei zeitlich nacheinander freigegebene Aufgabenfenster**. Es gibt **nicht** ein Los pro Block. Eine freigegebene Miner-Identität kann durch eine erfolgreiche Aufgabe **genau ein** Ticket für die spätere Gewinner-Lotterie erwerben. + +- Fenster 1: kostenlos, echte begrenzte Rechenarbeit, keine Erfolgsgarantie. +- Fenster 2: nur wenn noch kein Ticket, erst progressive + fixe Gebühr, dann zweite neue Aufgabe. +- Fenster 3: nur wenn weiterhin kein Ticket, höhere progressive + fixe Gebühr, dann dritte neue Aufgabe. +- Nach erfolgreichem Proof: stoppen, Ticket festhalten; keine zusätzlichen Tickets/Losgewichte durch schnellere CPU oder weitere Zahlungen. +- Ein Nutzer kann freiwillig maximal 1, 2 oder 3 Fenster freigeben. Mining darf ohne Schlüsselzugriff aufs Wallet starten; kostenpflichtige Fenster brauchen gesonderte Wallet-Autorisierung. + +## Beispielrechnungen zur Qualifikation, **keine Produktparameter** + +Angenommen, jedes vollständig und rechtzeitig bearbeitete Fenster hat unabhängig dieselbe Erfolgschance `p = 0,70`: + +| Genutzte Fenster (max.) | Qualifikationschance | Marginaler Mehrwert | +|---|---:|---:| +| 1 | 70,0 % | Basis | +| 2 | 91,0 % | +21,0 Prozentpunkte | +| 3 | 97,3 % | +6,3 Prozentpunkte | + +Mathematisch: `P(Ticket bis Fenster k) = 1 - (1 - p)^k`. Das sind **keine direkten Lotterie-Gewinnchancen**; diese hängen außerdem von den anderen qualifizierten Teilnehmern ab. Wenn für einzelne Fenster andere Schwierigkeitswerte gelten, ist die Formel entsprechend anzupassen. + +Bei normalem Miner-Verhalten fallen Gebühren für Fenster 2 **nach erfolglosem Fenster 1**, für Fenster 3 **nach zwei erfolglosen Fenstern** an. Konsensseitig ist aber nur nachweisbar, dass **bis dahin kein Ticket angenommen** wurde, nicht dass der Miner erfolglos gerechnet hat. Fenster 3 setzt zusätzlich voraus, dass Fenster 2 zuvor bezahlt/freigeschaltet wurde. Wenn beide optionalen Preise `F2` und `F3` sind, gilt im Beispiel bei vollständigem Durchspielen eine **erwartete Gebühr** `E[F] = (1-p) * F2 + (1-p)^2 * F3`. Die *maximal mögliche* Zahlung ist `F2 + F3`. In Simulationsanalysen strikt unterscheiden. + +## Gebührenidee und progres­sive Basis + +**Nicht das Wallet-Guthaben** als alleinige Bemessungsgrundlage nehmen: Coins können auf andere Wallets verschoben werden. Stattdessen die konsensgeprüften PoP-Gewinne, die der **registrierten Mining-Identität oder Betreibergruppe** in einem gleitenden Betrachtungszeitraum (Ziel: ca. 90 Tage) zugeordnet wurden. Dadurch entsteht kein dauerhafter Malus nur wegen langen Mitwirkens: ältere Gewinne fallen wieder aus der Bemessung heraus. + +Entwurf als mathematische Struktur, nicht als feste Zahlen: + +```text +R = zugeordnete, finalisierte PoP-Bruttogewinne im Lookback +P(R) = progressive, stückweise lineare Gebühr auf R +F2(R) = fixer Grundbetrag 2 + P(R) +F3(R) = fixer Grundbetrag 3 + Multiplikator3 * P(R) +``` + +`Grundbetrag3 > Grundbetrag2 >= 0`, `Multiplikator3 > 1`. Der genaue progressive Tarif darf nicht in Float-Code überführt werden; implementationstechnisch Integer-Basis-Einheiten + gebrochene Rationalwerte mit definiertem Runden verwenden. Entscheide, ob Tarif auf **marginale Stufen** oder pauschal auf die gesamte Summe eines Bandes angewandt wird. Marginalstufen vermeiden Sprungstellen. + +### Forschungswerte zum Ausprobieren, nicht beschlossen + +- Pro Aufgabe beispielhaft `p=70 %` bei vollständig abgesuchtem endlichem Nonce-Raum. +- Nur in einer **Simulation**: fixer Aufpreis Fenster 2 von `0,001 PTM`, Fenster 3 von `0,003 PTM` und progressive Marginalsätze 0,005 % (0–10 PTM), 0,020 % (10–100 PTM), 0,050 % (>100 PTM); für Fenster 3 doppelte Progression. Die Werte können viel zu hoch/niedrig sein. +- Beispielhafte Bruttobelohnung 1 PTM, Netzwerkgrößen 5/10/20/50 zugelassene Miner. + +Die Beispielwerte sind bewusst **nicht** in der produktiven Software oder in der Genesis-Konfiguration definiert. + +## Kostenverwendung + +- Zusatzfenster-Gebühren: auf konsenskritische Weise **burnen**, weder an Miner noch an Validatoren auszahlen. +- Normale Transaktionsgebühren: als Validator-Finanzierung vorgesehen; konkrete, auch auf Rundungsreste bezogene Verteilung bleibt offen. +- Brennen reduziert den ausgebbaren Umlauf. Eigene Zähler für `minted_total` und `burned_total` verhindern falsche Emissionsannahmen. Keine verlässlichen Preis-/Wertbehauptungen. + +## Schutzmechanismen und Angriffe + +1. **Guthaben-Verschiebung:** Lookback nach Mining-Belohnungen statt aktuell sichtbarer Wallet-Balance; **kein** automatischer Reset durch Transfer. +2. **Mehrfach-Identitäten:** Betreiber kann mehrere VMs/Schlüssel nutzen. Eine Node-ID ist nicht eine physische Maschine. Manuelle und auditierbare Registrierung plus Gruppenregel nötig. Noch nicht kryptografisch gelöst. +3. **Erfolglos gerechnet ≠ nachweisbar:** nur gültige Lösungs-Hashes beweisbar; eine Node kann nicht beweisen, wie viele erfolglose Versuche sie hatte. Endlichen pro-ID-Nonce-Raum und Ticketlimit prüfen. +4. **Hardware:** leistungsfähige Geräte können schneller alle erlaubten Versuche abschließen. Zeitfenster groß genug für Raspberry Pi 4, echte Messungen auf schwacher Hardware, CPU-Limit und Netzwerklatenz berücksichtigen. +5. **Validator-Zensur und Fristen:** Gebühren und Proofs benötigen verbindliche Aufnahme-/Commit-Regeln. Nachträgliche Proofs und Gebühren aus falschem Fenster ablehnen. Blockchain-Zeit statt lokaler `time.Now()` als Konsensgrundlage. +6. **Zufall:** Liste der Tickets vor Veröffentlichung des deterministisch überprüfbaren Beacons fixieren, sonst Manipulationsgefahr. +7. **Wirtschaft:** immer mindestens das kostenlose Fenster; Zusatzfenster möglicherweise finanziell nachteilig. UI muss Gesamtmaximum und nicht nur Erwartungswert zeigen. +8. **Budgetvorteil bleibt möglich:** Auch wenn reiche Miner durch höhere **eigene Mining-Gewinne** mehr zahlen, kann ein vermögender Neueinsteiger sich Zusatzgebühren leichter leisten. Dieses Modell dämpft Vorteile, schafft aber keine völlige Vermögensneutralität; Ticketlimit, eng begrenzte Fenster und Betreiberregistrierung bleiben nötig. +9. **Automatisierung:** keine Wallet-Private-Keys im Miner. Kostenpflichtige Freigaben müssen runden-, fenster-, identitäts-, chain- und betragsgebunden, widerrufbar und wiederholungsfest sein. Bis zu einer sicheren Lösung nur explizite Nutzerfreigabe pro Vorgang. +10. **Recht:** Gebühren für bessere Chancen auf überwiegend zufallsabhängige Preise können Glücksspielrecht betreffen. Private Tests nur mit wertlosen PTM; rechtliche Prüfung vor handelbarer/öffentlicher Nutzung. + +## Nächste Akzeptanzkriterien für M1 + +- Fairness-Simulation mit Szenarien 5/10/20/50 Miner, verschiedenen 90-Tage-Mining-Erträgen und Teilnahme-Modi 1/2/3 erstellen. +- Marginale Erhöhung der echten Gewinnerwartung und erwartete/maximale Gebühren für alle Profile ausgeben, nicht nur Ticketqualifikation. +- Pi-4-Benchmark mit Kandidaten für Nonce-Raum und echten Latenzen; CPU-, Speicher- und Stromlimits. +- In einem weiteren ADR konkrete Formeln, Rundungs- und Sicherheitsregeln **nach** Nutzerfreigabe akzeptieren. diff --git a/docs/PROJEKTPLAN.md b/docs/PROJEKTPLAN.md index 9ad6f84..56f0709 100644 --- a/docs/PROJEKTPLAN.md +++ b/docs/PROJEKTPLAN.md @@ -1,89 +1,53 @@ -# Potatium – vollständige Projektübergabe v0.1 +# Potatium: Projektplan v0.2 -**Stand:** 24.10.2026 · **Zweck:** Projektwissen aus dem ursprünglichen Planungschat als versionierbare Arbeitsgrundlage für VS Code/Codex übernehmen. +**Stand:** 25.10.2026. Maßgeblich sind Repositorydateien/ADRs; Änderungen durch Codex oder Git in deinem LXC haben Vorrang. Die neue PoP-Richtung ist als Prinzip akzeptiert, Zahlen sind weiter offen. -## 1. Vision und Grenzen +## Ziel -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. +Potatium (PTM, vor öffentlicher Nutzung Name/Ticker prüfen) ist eine **eigene, kleine Hobby-Layer-1-Blockchain**, kein ERC-20-Token und keine Anlageempfehlung. Geplant sind ressourcensparsame Miner auf Raspberry Pi 4/5 und älteren PCs sowie eine browserbasierte Wallet **bereits im ersten funktionalen MVP**. Das gewählte Logo bleibt `assets/logo/potatium-ptm-logo.png` (goldenes abstraktes P/Kartoffelzeichen auf Schwarz). -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. +## Entwicklungsumgebung und Git -## 2. Festgelegte Entscheidungen +- Proxmox **unprivilegierter Ubuntu Server 26.04 LTS LXC** `potatium-dev` (Basis 4 vCPU, 4 GB RAM, 40 GB Speicher, bei Bedarf mehr). +- Benutzer `potatium`, **einziger** Arbeitsordner `/home/potatium/src/potatium`. Keine Duplikate in `~/workdir`. +- IDE: VS Code auf dem lokalen Rechner via Remote-SSH, OpenAI Codex, Go-Plugin; keine GUI im Container. +- Monorepo auf privatem Gitea-Remote; `main` plus kleine Feature-Branches, kleine nachvollziehbare Commits. Keine Zugangsdaten, Wallet-Keys oder Chain-State in Git. +- Ubuntu-Go-Skripte und Tests bereits als Gerüst vorhanden; aktuelle Remote-/Push-/Codex-Zustände vor Aussagen oder Änderungen prüfen. +- Keine PostgreSQL- oder Docker-in-LXC-Voraussetzung. Alle API-Server zunächst nur `127.0.0.1`, Zugriff über SSH-Portweiterleitung. -| 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 | +## Technisches Modell (Plan, noch nicht vollständig bestätigt) -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. +- Go (`linux/amd64`, `linux/arm64`) für `potatiumd`, `potatium-miner` und `potatium-cli`. +- Konsenskandidat: **CometBFT** als Validator/P2P mit eigener deterministischer ABCI++-Applikation, zunächst **ohne Cosmos SDK**; echte Versionen prüfen. Validatoren betreiben Blockkonsens, Miner qualifizieren sich für PTM-Lotterie; Rollen getrennt. +- Eigenständiger eingebetteter konsensdeterministischer Zustand, jedes Validatorgerät speichert selbst; keine geteilte zentrale SQL-Datenbank. +- Konten/Transaktionen/Schlüssel-/Adressschema einschließlich Nonce und Wallet-Backup noch präzise zu definieren. +- Web-Wallet-MVP: Browser-Keygenerierung/-Signatur, verschlüsselter lokaler Speicher, Erstellen/Import/Export/Backup, Adresse/Balance, Senden/Empfangen, Gebühren, History/Status, Sperren/Entsperren; **keine** Private Keys an Backend, immer echte Chain-Daten oder „nicht verbunden“. +- Startgerüst beinhaltet nur statischen Web-Wallet-UI-Entwurf, CLI/Node/Miner sind nicht produktive Programme. -## 3. Umgebung +## Proof of Potato: Richtungsentscheid v0.2 -- 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. +**Neue verbindliche Produktprinzipien** stehen in `docs/decisions/0003-pop-fenster-und-gebuehren.md` und `docs/PROTOKOLL_ENTWURF.md`. -## 4. Softwaremodule und Prozesse +Eine PoP-Runde enthält **drei hintereinander liegende Aufgabenfenster** mit einer neuen, pro Identität/Chain/Runde/Fenster gebundenen, begrenzten PoW-Aufgabe. Fenster 1 ist kostenlos, Fenster 2 und 3 freiwillig und **solange kein gültiges Ticket vorliegt** gegen vorherige bestätigte Gebühren nutzbar. Die Gebühren enthalten jeweils fixe Kosten und eine progressive Komponente. Als Maßstab dienen finalisierte PoP-Gewinne der letzten ungefähr 90 Tage pro registrierter Identität/Betreibergruppe, **nicht die aktuelle Wallet-Balance**; alter Erfolg fällt aus der Bemessung heraus, kein permanent fortschreitender Langzeitvorteil. -Drei Go-Programme plus Browser-WebGUI: +Nach dem ersten erfolgreichen Nachweis erhält diese Identität **maximal ein Ticket** und stoppt bis zur nächsten Runde. Lose müssen vor Bekanntwerden eines später verifizierbaren Zufallswerts unwiderruflich feststehen. Die Gebühren für Zusatzfenster werden **verbrannt**; normale Transfergebühren sind zur Validator-Finanzierung vorgesehen, genaue Verteilung offen. -**`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. +Die **Schwelle, Nonce-Raum, Rundendauer, Fensterlängen, Gebührenhöhe, PTM-Emission, Coin-Maximum, Zufallsbeacon und Validatoranzahl** sind weiter unentschieden. Alle genannten Zahlen aus früheren Beispielen bleiben hypothetisch. Pi-4-Benchmark, Simulation und ein neues ADR sind Pflicht vor Implementierung konsenskritischer PoP-Regeln. -**`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. +## Sicherheitsgrenzen -**`potatium-cli`:** Netzwerkinfo und lokale Walletverwaltung, später Debug-/Adminbefehle. Keine Secret-Ausgabe im Normalfall. +- Eine zugelassene Node-ID ist kein kryptografischer Beweis für ein physisches Gerät. Anfangs manuelle Registry; Betreibergruppen und mehrere Geräte auditiert verwalten. Verschieben von Coins soll die Gebührenbasis nicht zurücksetzen, Identitätswechsel bleiben Sybil-Angriffsfläche. +- Starke CPUs können endliche Nonce-Räume schneller durchsuchen. Gleichheit nur bei rechtzeitig vollständig bearbeiteter erlaubter Aufgabe, nicht mathematisch hardwareunabhängig. +- Keine lokalen Uhrzeit-, Betriebssystem-, Zufallsgenerator- oder Float-Operationen in der State-Machine, die zwischen Validatoren abweichen können. +- Mining-Fenster-Gebühren und Zufallsgewinne können regulatorische Pflichten auslösen. Vorerst ausschließlich private Test-PTM ohne wirtschaftlichen Wert. +- Kein automatisches Bezahlen durch den Miner mit privaten Wallet-Schlüsseln. Die Wallet autorisiert später separat, begrenzt und widerrufbar. -**`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. +## Entwicklungsreihenfolge -Quellen/Netzwerk/State bleiben modular, testbar und so wenig frameworkabhängig wie möglich. Siehe `ARCHITEKTUR.md`. +1. **M1:** Architektur-/Coin-/PoP-Parameter dokumentieren, Gebühren-/Fairness-Simulation, Pi-4-Benchmark, ADRs akzeptieren. +2. **M2:** Ledger, Accounts, deterministischer State, Signaturen, Genesis, Nonce, Tests; **parallel funktionale Web-Wallet** nach festgelegter Schnittstelle. +3. **M3:** CometBFT anbinden (1, danach 4 Validatoren), Synchronisation/Ausfalltests. +4. **M4:** PoP-Registry, Fenster, signierte Proofs/Gebühren, Ticketcommit, nachweisbare Ziehung, Mint/Burn und Negativtests. +5. **M5–M6:** Pi-/Office-PC-Builds, Web-Wallet vervollständigen, private Mehrhost-Tests, Doku/Release. -## 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. +Jeder Schritt: erst Akzeptanzkriterien, dann kleinste sinnvolle Implementierung, Tests inkl. `gofmt`, `go test ./...`, `go vet ./...`, kurze Dokumentation und Git-Review. Keinen Fortschritt erfinden. diff --git a/docs/PROTOKOLL_ENTWURF.md b/docs/PROTOKOLL_ENTWURF.md index 2dc70e9..f95a2cd 100644 --- a/docs/PROTOKOLL_ENTWURF.md +++ b/docs/PROTOKOLL_ENTWURF.md @@ -1,44 +1,73 @@ -# Potatium Protokoll v0.1 – Entwurf, nicht freigegeben +# Potatium: Protokollentwurf v0.2 (nicht implementiert) -## Bestätigte Produktziele +**Stand 25.10.2026.** Die Grundrichtung des Mining-Modells ist abgestimmt. Sämtliche konkreten Zahlen und konsenskritischen Details sind bis zur Simulation, Pi-Messung und einem bestätigten ADR **offen**. `docs/decisions/0003-pop-fenster-und-gebuehren.md` hält den Grundsatzentscheid fest. -- Neue eigenständige Blockchain mit nativer Kryptowährung Potatium (PTM). -- Leichte echte PoW-Aufgabe pro Miner/je Runde; pro **freigegebener Node-ID** maximal **ein** qualifiziertes Ticket pro Runde. -- Ein verifizierbarer Gewinner wird aus den rechtzeitig qualifizierten Tickets ausgelost; PTM-Emission als konsensgeprüfte Blockregel. -- Kleine Hardware (Ziel: Raspberry Pi 4) muss sinnvoll mitmachen können; mehr physische Geräte dürfen mehr Node-Identitäten haben. Registrierung zunächst manuell. -- Validatoren bestätigen Blöcke unabhängig von Lotteriegewinnern. -- Webbasiertes Wallet mit Basisfunktionen ab erstem funktionalen MVP. +## Beschlossene Produktprinzipien -## Noch zu entscheiden +1. Potatium ist eine eigenständige Hobby-L1 mit nativen PTM (Ticker vor externer Nutzung prüfen), Go-Kern, Web-Wallet ab erstem funktionalem MVP. Kein Ethereum-Token. +2. Blockchain-Validatoren (geplant: CometBFT + eigene ABCI++-App) bestätigen Blöcke; PoP-Miner bestimmen weder Blockreihenfolge noch Validator-Konsens. +3. **Eine Mining-Runde hat drei nacheinander freigegebene Mining-Fenster.** Die Zahl der Consensus-Blöcke je Runde/Fenster ist noch offen; alte Beispiele „12 Blöcke/120 Sekunden“ sind keine Entscheidung. +4. **Fenster 1 ist kostenfrei.** Fenster 2 und 3 sind freiwillig, kosten jeweils eine **fixe Grundgebühr plus progressive Komponente** und werden nur solange kein gültiges Ticket angenommen wurde gebraucht. +5. Die Gebührenbasis ist die **nachweisbare, einer registrierten Mining-Identität/Betreiberzuordnung zugerechnete PoP-Gewinnsumme der zurückliegenden ca. 90 Tage**, **nicht** das gerade sichtbare Wallet-Guthaben. Genaues Zeit-/Höhenfenster und Verbundidentitäten noch spezifizieren. Langjährige Aktivität an sich darf keinen permanenten Bonus/Malus auslösen. +6. Progression: Fenster 3 soll teurer sein und zugleich **deutlich geringeren zusätzlichen Nutzen** als Fenster 2 bieten. **Keine unlimitierten Zusatzchancen, kein Kauf einer weiteren Identität.** Konkrete Tarife und Erfolgswahrscheinlichkeiten erst nach Simulation entscheiden. +7. Ein qualifizierter Miner erhält **maximal ein Ticket** je Runde. Nur vollständig gültige Proofs aus zulässigen Fenstern zählen. Nach dem ersten gültigen Proof endet die Teilnahme dieser Identität für diese Runde. +8. Zusatzfenster-Gebühren werden **verbrannt** (aus dem spendierbaren Umlauf entfernt). Normale Transaktionsgebühren sollen die Validatoren finanzieren; Zuteilungsmechanik ist noch offen. +9. Ohne PTM kann jede zugelassene Identität an Fenster 1 teilnehmen. Gebühren und Mining-Erfolg dürfen keine Gewinnergarantie erzeugen. +10. Registrierte Identität ≠ nachweislich einzigartige physische Maschine oder Person. Für das kleine private Netzwerk zunächst manuelle Freigabe, Audit und Sperrmöglichkeit. Mehrere Geräte/Identitäten und gemeinsamer Betreiber müssen gesondert geregelt werden. -| ID | Parameter | Aktueller Stand / Anforderung | -|---|---|---| -| P-01 | Maximale Coin-Menge | OFFEN, keine Annahme 21 Mio. | -| P-02 | Anfangsbestand/Genesis | OFFEN; Starthöhe/Valve der Testcoins festlegen | -| P-03 | Dezimalstellen | OFFEN; alle Werte ganzzahlig in Basis-Einheiten | -| P-04 | PoP-Emissionsplan | OFFEN; nicht automatisch 10 PTM | -| P-05 | Rundenlänge | OFFEN; nicht automatisch 120 s | -| P-06 | Konsens-Blockzeit | OFFEN; getrennt von Mining-Runden | -| P-07 | Proof | SHA-256 als Prototyp-Kandidat, kalibrieren auf Raspberry Pi | -| P-08 | Mining-Difficulty | feste/zeitbasierte Kalibrierung erst nach Benchmarks | -| P-09 | Teilnehmerliste | Höhe/Abschlussprozess und Eligibility-Fenster offen | -| P-10 | Zufallsbeweis | drand als Option; Ausfallverhalten offen | -| P-11 | Schlüssel und Adresse | Signaturalgorithmus, Serialisierung, Recovery offen | -| P-12 | Transaction Fees | zunächst niedrige Gebühren oder Testnet-Fee-Regel offen | -| P-13 | Validator-Modell | CometBFT fester Satz zu Beginn als Architekturpräferenz | -| P-14 | Registry-Administration | Autorisierung, Removal, Transparenz und Verfahren offen | +## Ablauf einer Mining-Runde (logisches Zustandsmodell) -## Vorgesehene Invarianten +```text +Runde R beginnt; Identitäten / Regeln / Gebührenbasis werden eingefroren + Fenster 1: kostenlose, identitätsgebundene PoW-Challenge + | gültiger Proof? -> 1 Ticket; fertig + | andernfalls + Fenster 2: vorher autorisierte, bestätigte Gebühr verbrennen + | neue, zuvor unbekannte PoW-Challenge; Proof? -> 1 Ticket; fertig + | andernfalls + Fenster 3: höhere Gebühr vorab verbrennen (Fenster 2 muss zuvor freigeschaltet sein) + | neue PoW-Challenge; Proof? -> 1 Ticket; fertig + | andernfalls kein Ticket + Fristende: akzeptierte Tickets endgültig fixieren + Später: unabhängige, überprüfbare Zufallsquelle belegen + Gewinner deterministisch bestimmen und regelgerecht PTM erzeugen +``` -1. Jeder akzeptierte Zustandsübergang deterministisch und reproduzierbar. -2. Keine Wallet darf Coins ohne gültige Protokoll-Ausgabe erzeugen. -3. Ein Ticket pro registrierter Node-ID pro Runde; Signatur/Nonce bindet es an Runde, Chain-ID und Challenge. -4. Ein Los nur dann, wenn PoW und Frist nach überprüfbaren Regeln erfüllt sind. -5. Ziehungsinput wird **vor** dem entscheidenden späteren Zufallswert festgeschrieben; Gewinnerberechnung vollständig nachprüfbar. -6. Wenn keine gültigen Tickets vorliegen, gilt eine ausdrücklich definierte Nicht-Auszahlung/Carryover-Regel (noch zu beschließen). -7. Keine Node-ID beweist eine einzigartige Hardware; Kryptografie löst das Sybil-Problem nicht allein. -8. Gleiche Chance **unter allen qualifizierten Losen**; nicht garantierte gleiche Qualifikationschance zwischen CPUs. +*In einzelnen Fenstern darf ein Miner innerhalb eines **begrenzten Nonce-Raums** leichte SHA-256-Arbeit leisten. Der Node kann gültige Treffer und Zeitfenster prüfen, **nicht**, wie viele erfolglose Hashes tatsächlich gerechnet wurden; das Protokoll kann nur „kein Ticket angenommen“ kontrollieren. Für Fenster 3 ist vorherige kostenpflichtige Freischaltung von Fenster 2 nötig, nicht ein technisch unmöglich beweisbarer Misserfolg. Neue Fensterchallenges müssen beim vorigen Fenster nicht im Voraus berechenbar sein.* -## Testanforderungen +## Gebühren und Emission: Sicherheitsregeln -Property-Tests für Ticket-Limit und Emission, Fuzzing für Parser und Eingaben, Replay/Double-Spend, deterministische Blöcke, RNG-/Commit-Tests, Snapshot/Restart, Pi-Benchmarks und Multi-Validator-Ausfalltests. Jede Definition einer Regel bekommt reproduzierbare Testvektoren. +- Jede Gebühr besteht aus einer **ganzzahligen Basis-Einheiten**-Berechnung, mit expliziten Rundungs- und Überlaufregeln. Keine Float-Werte in konsenskritischen Funktionen. +- **Gebühren-Snapshot vor der Runde** aus finalisiertem Chain-State; exakt definierte Zuschreibung von Mining-Belohnungen zu Identitäten und bei Bedarf gemeinsamer Betreibergruppe. Wallet-Transfers dürfen die Zuschreibung nicht zurücksetzen. +- Fenster-Freischaltung nur nach bestätigter, replaygeschützter **Gebührenautorisierung**. Falls keine gültige Zahlung vorliegt: kostenloses Fenster bleibt nutzbar, das kostenpflichtige Fenster nicht. +- Keine Rückerstattung bei erfolglosem Fenster. Ob nach einem bereits gewonnenen Ticket überhaupt Gebühren mehr eingereicht werden dürfen: **nein**. +- Kein Miner-/Validatorprozess erhält ungefragt den privaten Browser-Wallet-Schlüssel. Spätere Komfortzahlung nur über eingeschränkte, widerrufbare, runden- und betragsbegrenzte Signaturfreigabe mit definierten Nonces; **nicht implementiert**. +- `minted_total`, `burned_total` und verfügbare Guthaben getrennt, deterministisch und integerbasiert führen; Versorgungslimit und Gebührenbehandlung festlegen. +- Gewinnerauswahl erst nach Commitment der Ticketmenge, mit **später bekannt werdender verifizierter** Zufallsquelle, etwa nachweisbarem drand-Beacon. Beacon-Ausfälle, Reorgs, Verzögerung und Manipulation definieren. +- Wenn niemand qualifiziert ist: **kein Gewinner**; Emission/Carryover und Timeout weiterhin offen. + +## Sicherheitsgrenzen und zu prüfende Angriffe + +- **Sybil:** mehr echte Geräte oder zugelassene Zweit-Identitäten verschaffen mehr Chancen; Geräteerkennung ist keine beweisbare Personenprüfung. +- **Identity-Splitting:** Betreiber könnte Gewinne/Identitäten aufteilen und Progression umgehen. Registry und Betreiber-Zusammenfassung nur organisatorisch für Hobby-Testnet, nicht mathematisch perfekt. +- **Zeitfenster/HW:** Schnelle CPUs können den begrenzten Nonce-Raum früher fertigstellen. Nur reale Pi-4-Benchmarks und großzügige Fristen können einen merklichen Vorteil klein halten, nicht ausschließen. +- **Zensur:** ein Validator darf nicht unbemerkt rechtzeitig gesendete Gebühren/Proofs verdrängen; konkrete Gegenmaßnahmen und Finalitätsfristen fehlen noch. +- **Anreize:** progressive Gebühren können für manche Nutzer wirtschaftlich unvernünftig werden, bei kleinem Netzwerk kostenpflichtige Fenster aber dominieren. Simulation für 5/10/20/50 Miner und verschiedene Vermögens-/Erfolgsklassen nötig. +- **Recht:** Zahlungen für höhere Chancen auf zufallsabhängige Gewinne können Glücksspiel-/Finanzrecht berühren. Vor öffentlicher Nutzung juristisch prüfen; vorerst nur privates Testnet ohne wirtschaftlichen Wert. + +## Nicht beschlossene Parameter + +| ID | Parameter / Festlegung noch nötig | +|---|---| +| P-01 | Maximale Gesamtmenge, Basis-Einheit/Dezimalstellen, Genesis-Zuteilung | +| P-02 | Emission/Belohnung pro Ziehung, Emissionsobergrenze, leere Runden, Halving | +| P-03 | Blockzeit, Anzahl Consensus-Blöcke je PoP-Runde und je Fenster | +| P-04 | PoW-Hash-Vorlage, Nonce-Raum, Schwierigkeitsziel/Erfolgsrate, Pi-4-Benchmark | +| P-05 | Finale Gebührenformel, Fixbetrag, Marginalstufen, Multiplikator Fenster 3, Mindest-/Maximalbetrag und Rundungsregel | +| P-06 | Exakte Bestimmung „letzte 90 Tage“ (Zeitstempel vs. Blockhöhen) und Zuordnung der Gewinne zu Betreibergruppen | +| P-07 | Signierte Gebührenfreigabe, Zahlungsreihenfolge, Ablauf/Nonce, Fallback, Verwahrung und Gebühren bei Reorg | +| P-08 | Signatur-/Adressformat, Wallet-Recovery und Tx-Serialisierung | +| P-09 | Proof-Einreichungs- und Finalitätsfristen, RNG-Quelle/Fallback, Ticket-Commit, Auszahlung | +| P-10 | Registry-Administration, Zweitgeräte-Regel, Validator- und normale Gebührenverteilung | + +**Wichtig:** Zahlen aus älteren Diskussionen wie 70/91/97,3 %, 1 PTM Belohnung, 10 Mio. PTM, 10-s-Blockzeit oder 0,001-PTM-Grundkosten bleiben ausschließlich **Rechenbeispiele**. Sie sind nicht implementiert, beschlossen oder für öffentliche Nutzung freigegeben. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 05186f5..0639e0b 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,35 +1,41 @@ -# Roadmap / Definition of Done +# Potatium-Roadmap: aktueller Plan v0.2 (25.10.2026) -## M0 – Übergabe & Entwicklungsgerüst (Startpaket) -- [x] Logo, ChatGPT-Anweisungen, Protokollentwurf, Codex-AGENTS und Roadmap archiviert. -- [x] Ubuntu-26.04-Setup-Skripte, Bootstrap, lokale UI-Vorschau und prüfbares Go-Gerüst bereitgestellt. -- [ ] Skripte im echten LXC ausführen und tatsächliche Ergebnisse bestätigen. -- [ ] VS Code, Codex, Git-Remote/SSH und erste Push-Verbindung herstellen. +**Status der Umsetzung:** Starter-Scaffold vorhanden, Blockchain/PoP/Web-Wallet noch **nicht** funktionsfähig. Lokale `doctor.sh`-Prüfung auf dem Benutzer-LXC wurde am 24.10.2026 berichtet; aktuelle Git-Commits und Änderungen aus Codex hier nicht einsehbar. Haken nur bei nachgewiesenen Ergebnissen setzen. -## M1 – Architektur & Protokollentscheidungen -- [ ] Offene P-01 bis P-14 priorisiert; erste ADRs über Accountmodell, Kryptosuite, Coin-Einheiten, Genesis, Block-/Rundenzeiten, PoP/RNG. -- [ ] Typspezifikationen und Testvektoren dokumentiert, Verantwortungsgrenzen fixiert. +## M0: Repo + Umgebung -## M2 – Ledger/Accounts + erste funktionale Web-Wallet -- [ ] Genesis, deterministischer Chain-State, Transaktionen, Signaturen, Nonce, Mint-Check, Wiederanlauf. -- [ ] Sichere Wallet im Browser erstellen/importieren/sichern/entsperren, echtes Guthaben, signierte Zahlung, echte Historie. -- [ ] Browser-/Backendsicherheits- und Signaturtests, keine Seeds an Backend. +- [x] Starterkit-Dateien mit Go- und Browser-UI-Gerüst bereitgestellt. +- [x] Ubuntu 26.04.1, Go 1.27.3, Bootstrap/Doctor mit erfolgreichen `go test`/`go vet`/`gofmt`-Prüfungen laut Nutzerkonsole bestätigt. +- [ ] Git-Remote, Push und VS-Code/Codex-Verbindung am tatsächlichen Repo-Stand prüfen (nicht blind als abgeschlossen markieren). -## M3 – Validator-Netz -- [ ] ABCI++/CometBFT-Anbindung, ein Validator, danach 4 Nodes. -- [ ] Zustandskonsistenz, Neustart, Verlust von Verbindungen, Synchronisation nachgewiesen. +## M1: Konsens- und Coin-Regeln **zuerst** -## M4 – Proof of Potato -- [ ] Registrierung, signierte Herausforderung, leichte Hash-Aufgabe, Ticketlimit, Rundenabschluss, verifizierte Auslosung, Emission. -- [ ] Negativtests zu Mehrfachlosen, Manipulation, Verzögerung, Timeout, Beacon-Ausfall und Emissionsobergrenze. -- [ ] Messungen am Raspberry Pi 4 und Intel-Alt-PC: Zeit/CPU/RAM/Strom, sinnvolle Qualifikation. +- [x] Produktprinzip für **3 Mining-Fenster**, kostenloses Fenster 1, optionale fixe + progressive Zusatzgebühren für Fenster 2/3, 90-Tage-Mininggewinn als Basis, Burn, max. 1 Ticket dokumentiert (`ADR 0003`). +- [ ] Tokenomics mit Coinsupply, Genesis, Belohnung, Basis-Einheiten, Gebührensystem, Signatur-/Adressschema entscheiden. +- [ ] PoP-Runden/Fenster/Schwierigkeit/Nonce-Räume und Zahlungs-/Finalitätsbedingungen spezifizieren. +- [ ] Rein analytische, ausdrücklich nicht konsenskritische Simulation (5/10/20/50 Miner), Fairness- und Kostenvergleich. +- [ ] Raspberry-Pi-4-Leistungsmessung, Gebühren- und Protokollparameter in weiterem ADR konkret akzeptieren. +- [ ] CometBFT/ABCI++-Versionen, deterministische State Machine und Datenbank verbindlich prüfen. -## M5 – Bedienung und Auslieferung -- [ ] Web-Wallet und Mining-/Chain-Status aufgeräumt; CLI; verständliche Fehler und Backups. -- [ ] Binaries linux/amd64 und linux/arm64; reproduzierbarer Build und CI; erste private Releases. +## M2: Ledger + frühzeitig echte Web-Wallet -## M6 – Privates Mehrhost-Testnet -- [ ] Separate Hosts, Netzunterbrechungen, Wiederherstellung, Schlüsselrotation, Dokumentation und Monitoring. -- [ ] Explizite Bewertung der Grenzen zentraler Registrierung und kleiner Validatoranzahl. +- [ ] Key-/Account-/Tx-Format, Nonce, Replay-/Double-Spend-Schutz, Genesis, persistenter Zustand und deterministische Tests. +- [ ] Browserseitige sichere Wallet-Erstellung, Import/Backup, Verschlüsselung, Sperren, Senden/Empfangen, tatsächliche Guthaben, History. +- [ ] Fee-Preview und später sichere, begrenzte Freigabe für Zusatzfenster planen; Miner bekommt keinen privaten Wallet-Schlüssel. -**Gate:** Keine Phase als abgeschlossen markieren, ohne tatsächliche Tests. Dieses Paket erfüllt nur die Bereitstellung des Startgerüsts, nicht die Ausführung im Nutzer-LXC. +## M3: Validatorennetz + +- [ ] 1, später 4 CometBFT-Validatoren, AB​CI++-Integration; echte Blocksynchronisation, Neustarts und Ausfalltests. + +## M4: Proof of Potato + +- [ ] Registry/Betreibergruppen-Audit, Challenge je Fenster, Gebühren-Snapshot, Proof-Verifikation, gebührenpflichtige Freischaltung, Ticketcommit, Zufallsbeweis, Gewinner-Auszahlung. +- [ ] Negative Tests für Mehrfachlose, Proof-Replay, Fee-Replay, Identitätswechsel, State-Divergenz, Beacon-Ausfall, Reorgs, Zensur, Rundenwechsel und Überläufe. +- [ ] Pi-4/Office-PC-Benchmarks unter CPU-/Speicher-/Netzwerklast. + +## M5–M6: Bedienung und privates Mehrhost-Testnet + +- [ ] UX, Explorer/Status, Dokumentation, Linux amd64/arm64-Releases, Sicherung/Recovery. +- [ ] Hosts über mehrere Geräte, Restart/Fault-Tests, Monitoring und Warnungen zur verbleibenden zentralen Registrierung. + +**Keine Implementierungs- oder Testergebnisse behaupten, die nicht tatsächlich ausgeführt wurden.** diff --git a/docs/WEB_WALLET.md b/docs/WEB_WALLET.md index a0c4c21..af7ec5b 100644 --- a/docs/WEB_WALLET.md +++ b/docs/WEB_WALLET.md @@ -1,26 +1,24 @@ -# Web-Wallet: Mindestumfang ab erstem funktionalem MVP +# Potatium Web-Wallet: Mindestumfang ab dem ersten funktionalen MVP -**Beschlossene Priorität:** WebGUI von Beginn an, nicht erst nach dem Mining-Release. Das mitgelieferte `web/wallet/index.html` ist ausdrücklich **nur Layout/Vorschau**. +**Vorhandene Dateien in `web/wallet/` sind nur eine deaktivierte UI-Vorschau.** Keine Schlüsselerzeugung, keine echten Daten oder Transaktionen vortäuschen. -## Sichtbare Seiten und Funktionen +## Pflichtfunktionen -1. **Start / Wallet anlegen:** sichere Erzeugung, Passwort und Backup-Hinweise; Import/Recovery einer bestehenden Wallet. -2. **Übersicht:** Wallet-Adresse kopieren, verfügbares PTM-Guthaben (nur aus vertrauenswürdig überprüfter Node-Antwort), Höhe/Netzwerkstatus. -3. **Empfangen:** Adresse plus QR optional; Betrag darf optional als URI vorgeschlagen werden, falls Protokoll entschieden. -4. **Senden:** Empfängeradresse validieren, Betrag in exakt definierter Basis-Einheit, Fee-/Total-Vorschau, explizite Bestätigung, Signieren im Browser, Submit an Node. -5. **Historie:** Transaktionen mit Hash, Uhrzeit/Blockhöhe, Eingang/Ausgang, Bestätigungsstatus; leere oder Offlinezustände korrekt anzeigen. -6. **Sicherheit:** sperren/entsperren, sicheres Export-/Backup-Verfahren, klare Warnung bei Verlust des Backups. +- Im Browser Wallet kryptografisch sicher erstellen und importieren, verschlüsselt exportieren und durch Wiederherstellung testen. +- Adresse/Kopieren, Balance aus echter verbundener Node, PTM senden mit Betrag/Empfänger/Fee/Bestätigung, empfangen, History und Transaktionsstatus. +- Wallet sperren/entsperren, verständliche Offline- und Fehlermeldungen, Netzwerkstatus. +- Private Keys, Seed-Phrases und Passwörter **niemals** ans Backend, an Miner oder in Logs/Telemetrie/Repo; Schlüsselmaterial nur im Browser, sichere gepinnte Bibliotheken, klar definierte Signing-Bytes. +- Verschlüsselter Storage, starke KDF, CSP, lokale HTTP-Vorschau nur 127.0.0.1/SSH-Forwarding, später HTTPS; Backup- und XSS-Tests. -## Sicherheits- und UX-Vertrag +## Zusatzfenster und Gebühren (PoP v0.2) -- Keine serverseitige Schlüsselverwaltung. Clientseitige Kryptografie auf Basis geprüfter, gepflegter Bibliotheken und dokumentierter Standardformate. -- Keine Schlüssel, Mnemonics, Signaturgeheimnisse oder Klartext-Backups in HTTP-Requests, Logs, Telemetrie oder Git. -- Keys verschlüsselt ablegen, starke Passwortableitung/KDF mit überprüfbaren Parametern, keine ungesicherten `localStorage`-Seeds; Backup/Recovery durch Tests prüfen. -- Browser-XSS als Key-Leak-Risiko behandeln, strikte CSP, keine fremden Inline-Skripte oder CDN-Abhängigkeiten bei Wallet-Code; Third-Party-Libraries pinnen und auditieren. -- Entwicklungsserver standardmäßig 127.0.0.1; für entfernten Zugriff VS-Code-Portforwarding/SSH. Später HTTPS mit geeigneter Authentifizierung und CORS-Regeln. -- UI nie „Transaktion bestätigt“ anzeigen, bevor der konsensgeprüfte Status tatsächlich vorliegt. Keine erfundenen Zahlen, keine Demo-Schlüssel als echte Wallet ausgeben. -- Mobile, Desktop und Tastaturnutzung berücksichtigen. +- Miner startet immer ohne PTM mit **kostenlosem Fenster 1**. +- Die Web-Wallet kann (nach Festlegung des Protokolls) optional erlauben, für **Fenster 2/3** eine eng begrenzte Gebühr zu bezahlen. Fixpreis und progressive Gebühr anhand der aus dem finalisierten Chain-State berechneten **Mining-Gewinne der letzten ca. 90 Tage** der zugeordneten Identität/Gruppe anzeigen. Die Zahlung wird **verbrannt**. +- Nutzer sieht vor Autorisierung den **konkreten Preis je Zusatzfenster**, die maximale mögliche Gesamtausgabe, Gebührenrisiken und den Unterschied zwischen Qualifikations- und tatsächlicher Gewinnchance. +- Gebühr nur nach **explizit signierter** Freigabe für Chain-ID, Miner-ID, Runde, Fenster, Betrag, Ablauf und Nonce. Ggf. später vorsichtig modellierbares widerrufbares Budget statt unbeschränkter Dauerfreigabe. Miner benötigt keine Wallet-Secrets. +- Vor finaler Gebühren-/Signaturspezifikation alle Zahlungs-Aktionen deaktiviert lassen. Keine automatische Abbuchung nur wegen „Mining aktiviert“. +- Bestätigte Zahlung vor Fenster-Freigabe; Fehlschlag führt nicht zur Erstattung. Nach erfolgreichem Proof oder Fristende keine weitere Freigabe. -## Design-Entscheidungen vor echter Implementierung +## Sicherheitstests -Adressschema, Schlüsselsuite, Signing-Bytes, Nonce/Sequenz, Chain-ID, Gebühren, Unlock-Lebensdauer, Recovery-Standard, Wallet-Storage und API-Version als ADR dokumentieren. +Replay über Runden, falsche Chain-ID, abgelaufene Autorisierung, negative/überlaufende Beträge, divergierende Fee-Snapshots, manipulierte Fees/Proofs, Backup-/Recovery-Fehler und Offline-Stati. Browser-/Go-Kompatibilität der gewählten Signatursuite erst nach ADR garantieren. diff --git a/docs/decisions/0001-projektgrundlagen.md b/docs/decisions/0001-projektgrundlagen.md index 44d0b80..7484e8c 100644 --- a/docs/decisions/0001-projektgrundlagen.md +++ b/docs/decisions/0001-projektgrundlagen.md @@ -9,3 +9,5 @@ Name Potatium/PTM und abstraktes goldenes P-Logo. Hobby-L1 mit PoW-qualifizierte ## Folgen Konkrete Mint-/Konsens-/Schlüsselparameter werden nicht aus Beispielzahlen abgeleitet. Sicherheit und reproduzierbare Entwicklung haben Vorrang vor Features. + +**Fortschreibung 25.10.2026:** PoP-Details aus diesem frühen ADR sind durch den Produktentscheid [ADR 0003](0003-pop-fenster-und-gebuehren.md) (drei Fenster, optionale progressive Gebühren, Burn, ein Ticket pro Runde) teilweise überholt. Sonstige Grundentscheidungen bleiben erhalten. diff --git a/docs/decisions/0003-pop-fenster-und-gebuehren.md b/docs/decisions/0003-pop-fenster-und-gebuehren.md new file mode 100644 index 0000000..a498d96 --- /dev/null +++ b/docs/decisions/0003-pop-fenster-und-gebuehren.md @@ -0,0 +1,33 @@ +# ADR 0003: Drei PoP-Fenster mit erfolgsabhängigen Zusatzgebühren + +**Status:** Accepted (Produktprinzip), **Parameter weiterhin Proposed** +**Datum:** 25.10.2026 +**Ersetzt teilweise:** Grundidee in ADR 0001 und frühem Protokollentwurf (ein einmaliges Rätsel ohne Gebühren) + +## Kontext + +Eine einzelne sehr leichte Aufgabe qualifiziert fast jeden; dadurch wirkt die Rechenarbeit bedeutungslos. Unbegrenzte Hash-Versuche würden starke CPUs bevorzugen. Kaufbare Zusatzlose würden Besitzer hoher PTM-Guthaben bevorzugen. Potatium soll echte, aber Pi-taugliche Rechenarbeit mit freiwilligen Risiko-/Kostenentscheidungen verbinden. + +## Entscheidung: Richtungsentscheid, keine fertige Tokenomics + +- Jede PoP-Runde besteht aus **drei seriellen Mining-Fenstern** mit erst zum Fensterstart nutzbarer Herausforderung und begrenztem erlaubtem Nonce-Raum. +- Fenster 1 **kostenlos**. Fenster 2/3 nur optional solange noch kein gültiges Ticket angenommen wurde, nur nach **vorher bestätigter** fixer **plus progressiver** Mining-Zusatzgebühr. Fenster 3 wird teurer und soll geringeren Zusatznutzen bieten. +- Maßstab der Progression: der Miner-Identität bzw. zugeordneten Betreibergruppe zurechenbare **PoP-Belohnungen eines gleitenden Zeitfensters von ungefähr 90 Tagen** statt des aktuellen Wallet-Guthabens. Kein automatisch kumulierender lebenslanger Erfolgsbonus/-malus. +- Zusatzgebühren **verbrennen**; normale Transaktionsgebühren für Validator-Finanzierung separat behandeln. +- **Maximal ein gültiges Ticket pro freigegebener Miner-Identität und PoP-Runde**, keine mehrfachen Lose/Losgewichte für zusätzliche Fenster nach Erfolg. +- Offene P-Parameter siehe `docs/PROTOKOLL_ENTWURF.md`. Simulation und Raspberry-Pi-Tests sind Voraussetzung für endgültige Zahlen und Konsensimplementierung. + +## Abgewogene Alternativen + +- Freie, unbegrenzt wiederholbare Hash-Aufgaben: HW-Vorteil zu groß. +- Ein leichter Proof mit garantierter Qualifikation: kaum relevante Mining-Entscheidung. +- Pauschale zusätzliche Lose pro Gebühr: vermögensabhängiger Vorteil. +- Prozentuale Gebühr auf aktuelle Wallet-Balance: leicht durch Transfer auf andere Adressen umgehbar. +- Lebenslang kumulierte Miner-Belohnungen: dauerhafter Nachteil für langjährige Miner. +- Reine Zeit-/Online-Herzschläge: kaum beweisbare reale Arbeit, leicht zu automatisieren. + +## Konsequenzen und offene Risiken + +Die Node muss gefensterte Challenges, vorher bestätigte und replaygeschützte Gebühren, historische PoP-Gewinne, identitätsgebundene Tickets und spätere verifizierbare Ziehung deterministisch verwalten. Betreiber-/Sybil-Identität bleibt organisatorisch; ein Wallettransfer ändert die Mining-Historie nicht, eine ungenehmigte neue Identität könnte sie jedoch umgehen. Zahlungen für zusätzliche Zufallschancen bergen rechtliche Risiken, auch bei Hobby-Projekten. Vorerst nur wertlose Test-PTM; kein öffentliches Angebot. + +**Noch NICHT festgelegt:** 70-%-Erfolgsrate, 10/12 Blöcke, Coin-Reward, 90 Tage exakt vs. deterministische Blockhöhen, progressive Stufen/Prozentsätze, Fixbeträge, Rundungen, Verlustrisiken, Wallet-Freigabeformat oder drand-Konfiguration. diff --git a/handoff/CHATGPT_PROJEKTANWEISUNGEN.md b/handoff/CHATGPT_PROJEKTANWEISUNGEN.md index dcde688..d400cbc 100644 --- a/handoff/CHATGPT_PROJEKTANWEISUNGEN.md +++ b/handoff/CHATGPT_PROJEKTANWEISUNGEN.md @@ -1,53 +1,41 @@ -# Potatium | ChatGPT-Projektanweisungen +# Potatium | ChatGPT-Projektanweisungen (v0.2) -Du bist technischer Architekt, leitender Go-Entwickler, Reviewer und Dokumentationspartner für das Hobbyprojekt **Potatium**. Antworte auf Deutsch, technisch präzise und praxisnah. Arbeite schrittweise und nachvollziehbar, ohne ungefragte Neugestaltung bereits entschiedener Grundlagen. Erfinde weder Tests noch Implementierungsstatus. Wenn Code benötigt wird, liefere ausführbare, robuste Lösungen samt Pfaden und Verifikation. Behandle die Dateien im Git-Repository als maßgeblichen, versionierten Projektstand; bei Widersprüchen gezielt nachfragen. +Du bist technischer Architekt, leitender Go-Entwickler, Reviewer und Dokumentationspartner für das Hobbyprojekt **Potatium**. Antworte auf Deutsch, präzise, pragmatisch und schrittweise. **Das Git-Repository ist maßgeblicher Projektstand**; widersprüchliche Erinnerungen/Chats nicht als Implementierungsstatus ausgeben. Vor größeren Änderungen erst Dateien lesen, Plan/Abnahmekriterien nennen, dann minimale sichere Umsetzung mit Tests/Review. Kein unaufgefordertes Redesign. ## Identität und Ziel -- Projektname: Potatium; Coin: PTM (Ticker vor öffentlicher Nutzung noch auf Konflikte prüfen); Arbeitstitel Mining: **Proof of Potato (PoP)**. -- Eigenständige Hobby-Layer-1-Blockchain, nicht ERC-20, ohne kommerzielle Vermarktung. Betrieb in kleinem Netzwerk mit alten PCs/Raspberry Pis; keine Profitabilitätsversprechen. -- Gewähltes Logo: abstraktes goldenes, geometrisches P/Kartoffelsymbol auf schwarzem Grund, Datei `assets/logo/potatium-ptm-logo.png`. Dieses Logo beibehalten. -- Entwicklung auf Proxmox mit **unprivilegiertem Ubuntu Server 26.04 LTS-LXC** `potatium-dev`; Basis 4 vCPU, 4 GB RAM, 40 GB Speicher, bei Bedarf mehr. Entwicklungsnutzer `potatium`. Arbeitsverzeichnis `/home/potatium/src/potatium`. -- IDE: VS Code auf lokalem Rechner über Remote-SSH in den LXC, OpenAI Codex-Erweiterung; Git mit `main` und kleinen Feature-Branches; privates Git-Remote nach Einrichtung. Keine IDE und kein GUI-Desktop im LXC installieren. +Potatium (Coin PTM, Kürzel vor öffentlicher Nutzung auf Konflikte prüfen) ist eine eigenständige Hobby-Layer-1 mit eigener nativer Währung, **kein ERC-20** und keine Gewinnversprechen. Mining-Arbeitstitel **Proof of Potato (PoP)**. Bestehendes final gewähltes Logo **nicht ändern**: `assets/logo/potatium-ptm-logo.png`, goldenes geometrisches abstraktes P/Kartoffelsymbol auf schwarzem Grund. Erst privates Netzwerk/wertlose Test-PTM, keine öffentliche Ausgabe oder Vermarktung ohne Sicherheits-/Rechtsprüfung. -## Architektur (Startentscheidung, vor Implementierung prüfen) +## Umgebung -- Hauptsprache Go; Zielplattformen zuerst `linux/amd64` und `linux/arm64`, Raspberry Pi 4 als Minimalziel, Pi 5 und ältere x86-PCs. Ressourcen sparsam, deterministisch, wenige Abhängigkeiten. -- Vorgesehener Stack: CometBFT als BFT-Konsens/P2P plus selbst implementierte Potatium-Anwendung via ABCI++; **kein Cosmos SDK für den Start**. Schnittstellen und Abhängigkeiten gegen die tatsächlich ausgewählten Versionen prüfen. CometBFT-Validatoren und PoP-Miner sind unterschiedliche Rollen. -- Eigenständige Node `potatiumd`, eigenständiger Miner `potatium-miner`, CLI `potatium-cli`, Web-Wallet unter `web/wallet`; eingebetteter persistenter Chain-State nach Auswahl einer geeigneten Datenbank, zunächst kein PostgreSQL und kein Docker-in-LXC. -- Für frühe Tests feste Validatoren, für erstes verteiltes Testnet mehrere Hosts. Entscheidungen über Blockchain-/Finalitätsmodell und Fork-Verhalten explizit dokumentieren; Mining-Los bestimmt **nicht** die CometBFT-Blockproduktion. +Proxmox, unprivilegierter **Ubuntu Server 26.04 LTS LXC** `potatium-dev`, Basis 4 vCPU/4 GB RAM/40 GB Storage, Benutzer `potatium`, **einziges Arbeitsverzeichnis `/home/potatium/src/potatium`**. VS Code lokal über Remote-SSH in den LXC, OpenAI Codex-Erweiterung; keine GUI im LXC. Privates Gitea-Monorepo, `main` und kleine Feature-Branches, nachvollziehbare Commits. Go (Linux amd64/arm64), Pi 4 und alte PCs als Hardwareziele. Zunächst keine PostgreSQL-/Docker-in-LXC-Pflicht; Embedded Chain-State. Entwicklungs-API nur `127.0.0.1`, Zugriff über SSH-Forwarding, keine öffentlichen Ports. -## Proof of Potato: angenommene Produktanforderungen +## Startarchitektur (zuvor prüfen) -- Jede **zugelassene Node-Identität** kann pro festgelegter Mining-Runde ein leichtes kryptografisches Proof-of-Work-Rätsel lösen und bei gültigem Nachweis **maximal ein Los** erhalten. Pro Runde erfolgt nach festgelegtem Teilnahmeende eine überprüfbare, faire Auslosung der qualifizierten Lose. Gewinner erhält neue PTM nach Emissionsregeln. -- Ziel: Pi/Alt-PC lösen Aufgabe rechtzeitig, ohne GPU/ASIC-Druck; stärkere Hardware gewinnt **keine weiteren Lose** nach erfolgreicher Qualifikation. Achtung: schnellere CPUs haben bei Zeitlimit und zufälliger Lösungsdauer ggf. weiterhin eine höhere Chance, überhaupt teilzunehmen. Nicht als mathematisch absolut hardwaregleich bezeichnen. -- Mehrere echte Geräte können mehrere Lose erhalten. **Sybil-Grenze:** Eine Node-ID ist keine beweisbare physische Maschine. Für Hobby-Testnet zunächst manuelle Freigabe der Identitäten, feste Registry, Widerruf, Sperre und nachvollziehbares Audit; Angreifer mit VMs/mehreren Schlüsseln werden dadurch nicht kryptografisch ausgeschlossen. -- Gewinnerauswahl: Ticketmenge **vor** Bekanntwerden der Zufallsquelle bindend festschreiben. Zufallswert später mit Nachweis überprüfbar machen (z. B. evaluiertes drand-Beacon oder sichere Alternative). Ausfall, Reorgs, Gleichstand, Fristen, Uhrzeit/Blockhöhe, Replay-Schutz und Manipulationsresistenz spezifizieren, nicht voraussetzen. -- Rundenlänge, Hashschwierigkeit, PTM-Belohnung, Coin-Grenze, Halbierung/Emission, Gebühren, Genesis-Verteilung, Adressformat, Basis-Einheiten, Blockparameter, Wallet-Kryptografie sind **noch offen**. Beispielwerte aus alten Chats nie als beschlossene Regeln übernehmen. +Go, CometBFT BFT/P2P und **eigene Potatium-ABCI++-Applikation**, zunächst **ohne Cosmos SDK**. Versionskompatibilität anhand realer APIs und offizieller Quellen prüfen. `potatiumd` Node/Validator-App, `potatium-miner` unabhängiger CPU-sparsamer Miner, `potatium-cli` CLI, `web/wallet` Web-Wallet. Validatoren bestätigen Blöcke, PoP-Miner qualifizieren sich für eine **getrennte** Coin-Lotterie. Kein Mining-Los entscheidet CometBFT-Blockproduktion. Feste Validatoren am Anfang; später mehrere Hosts, Netzpartitionen, Restart/Synchronisation prüfen. -## Web-Wallet: ab MVP, keine spätere Kür +## Aktueller PoP-Produktentscheid v0.2 (ADR 0003) -- Erste einsatzfähige Potatium-Version muss eine **WebGUI** haben: Wallet lokal erstellen/importieren und sicher exportieren; Adresse anzeigen/kopieren, Balance, PTM senden (inkl. Betrag, Ziel, Gebühr, Bestätigung), empfangen, Transaktionshistorie und Status, sperren/entsperren, verständliche Fehlermeldungen; Netzwerkstatus sichtbar. -- Backend darf niemals Private Keys oder Seed-Phrases empfangen, speichern oder protokollieren. Schlüsselerzeugung/Signatur im Browser nur mit überprüften Bibliotheken und dokumentiertem Signaturformat. Verschlüsselte lokale Speicherung, Passwortableitung, Backup/Recovery, CSP, HTTPS bzw. SSH-Portweiterleitung und Tests vor produktivem Einsatz. Kein echtes Guthaben anzeigen, wenn Datenquelle nicht verbunden ist. -- Die Weboberfläche im Startarchiv ist **nur ein deaktivierter UI-Entwurf**, keine funktionierende Wallet. Keine Fake-Transaktionen, Mock-Balances oder unsichere Seed-Demos als echt ausgeben. Miner selbst bleibt browserunabhängig. +**Eine PoP-Mining-Runde hat drei zeitlich aufeinanderfolgende Aufgabenfenster.** Die Fenster sind **keine separaten Blockchain-Runden**; die Blockzahl pro Fenster ist noch offen. Jede zugelassene Miner-Identität kann **maximal ein gültiges Ticket in der Gesamtrunde** erhalten. Erfolg in einem Fenster: Ticket, sofortiger Stopp für diese Runde. -## Arbeitsstil, Qualität, Sicherheit +**Fenster 1 immer kostenlos.** Solange noch kein gültiges Ticket angenommen wurde, können **Fenster 2 und 3 freiwillig** genutzt werden, jeweils erst nach bestätigter **fixer Grundgebühr plus progressiver Zusatzgebühr**. Höhere Kosten und abnehmender zusätzlicher Qualifikationsnutzen sollen Fenster 3 weniger attraktiv machen. Gebührenmaßstab: **finalisierte PoP-Mining-Gewinne des Miners/der zugeordneten Betreibergruppe im gleitenden Zeitraum der letzten ca. 90 Tage**, **nicht das aktuelle Wallet-Guthaben**. Kein lebenslang kumulierender Erfolgsbonus/-malus; ältere Gewinne fallen heraus. Gebühren für Zusatzfenster werden **verbrannt**. Normale Transaktionsgebühren sollen Validatoren finanzieren; genaue Verteilung weiter offen. -- Zuerst `AGENTS.md`, `docs/PROJEKTPLAN.md`, `docs/ROADMAP.md`, `docs/PROTOKOLL_ENTWURF.md` und Entscheidungseinträge lesen. Vor umfangreichen Änderungen kleine Schritte/Plan und konkrete Akzeptanzkriterien nennen. -- Pro Arbeitsschritt Implementierung, Tests, kurze Doku-Anpassung und Review. Go: idiomatisch, gofmt, go test, go vet; Race-Tests wo sinnvoll; deterministic state transitions, int64/uint64 oder geeignete Integer-Basiswerte statt Float für PTM; sichere Signaturen; Replay- und Double-Spend-Schutz. -- Konsenskritische Funktionen besonders gründlich testen: identische Eingabe -> identischer State, ungültige Blöcke/Auszahlungen ablehnen, Randwerte, Crash/Restart, Netzwerkausfälle, Schlüsselverwaltung, Mining-Tickets, Timing und Verteilungsfairness. -- Niemals private Schlüssel, Tokens, Wallet-Seeds, Passwörter, `data/`, generierte Binaries oder echte Wallet-Daten committen. Keine öffentlichen API-Ports. Entwicklungsserver nur an 127.0.0.1; Remote-Zugang via SSH/VS-Code-Portforwarding. Keine potenziell destruktiven Befehle ohne transparente Erklärung und Sicherung. -- Bei Architekturänderungen schriftliches ADR unter `docs/decisions/`, mit Gründen, Alternativen und Konsequenzen. Nutzerentscheidungen nicht stillschweigend ändern. CometBFT-, Go-, Ubuntu- und Codex-Angaben bei Bedarf anhand offizieller Quellen aktualisieren. -- Bei jeder Lieferung angeben: welche Dateien geändert, was tatsächlich funktioniert, welche Tests liefen (mit Ergebnis), bekannte Grenzen und exakter nächster Schritt. Keine Behauptung, dass eine Wallet oder Chain funktioniert, wenn nur ein UI-Gerüst vorliegt. +Leichte echte kryptografische Arbeit (SHA-256 als Kandidat) mit **begrenztem pro-Identität-Nonce-Raum** und erst zum Fensterstart freigeschalteter Herausforderung. GPU/ASIC-/CPU-Wettrennen vermeiden; stärkere CPUs können schneller rechtzeitig fertig werden, vollständige Hardware-Gleichheit nicht behaupten. Pi-4-Benchmarks und Simulationen mit 5/10/20/50 Minern vor Festlegung der Schwierigkeit/Kosten. Begrenzter Nonce-Raum garantiert **keine** reale Arbeitszeit; erfolglose Versuche sind nicht beweisbar. -## Gewünschte Reihenfolge +Gültige Tickets vor Bekanntwerden der späteren überprüfbaren Zufallsquelle bindend festschreiben; Gewinner mit verifizierbarem Beacon (z. B. drand) bestimmen. Replay, Timing/Höhe, Loscommit, Zensur, Beacon-Ausfall, Reorgs, Burn, Mint-Cap, Determinismus und Crash/Restart ausdrücklich spezifizieren und testen. Ein Node-Schlüssel ist **kein Beweis eines physischen Geräts oder einer Person**: Anfangs manuelle Registrierung, Widerruf, Betreibergruppen und Audit gegen Sybil-/Mehrfachidentitäten; vollständige Sicherheit gegen Wallet-/Identity-Splitting nicht behaupten. -0. Protokollentscheidungen festhalten und offene Parameter sichtbar machen. -1. Ubuntu-26.04-LXC, Go, SSH, VS Code/Codex und Git-Grundstruktur startfähig machen. -2. Blockchain-Kern (Keys/Accounts/Transaktionen/State/Genesis) mit Tests; gleichzeitig funktionale Web-Wallet-Anbindung **sobald die Signatur-/Transaktionsschnittstelle feststeht**. -3. CometBFT anbinden, 1 dann 4 Validatoren, Synchronisation testen. -4. PoP-Registry, Minerrätsel, Proof-Verifikation, Ticket-Commit, Zufallsziehung, PTM-Minting und harte Negativtests. -5. Wallet komplettieren, Explorer/Status minimal, Raspberry-Pi-Builds und Leistungsvergleich. -6. Mehrhost-Privat-Testnet, Ausfall- und Wiederherstellungstests, Doku und Releases. +**Nicht entschieden:** Maximalmenge PTM, Basis-Einheiten, Genesis, Belohnung, Halving/Emission, Adressen/Signaturen/Tx-Format, Blockzeit und Fensterlänge, tatsächliche Qualifikationschance (70/91/97,3 % waren Beispiele), Gebührenstaffeln/Fixwerte/Rundung, exakte 90-Tage-Bestimmung, Gebührenautorisierung und Beacon-Fallback. **Beispielwerte nie als Konsensregeln programmieren.** Vor endgültigem Protokoll konkreten Parameter-ADR und Nutzerfreigabe verlangen. -Bevor du eine neue große Phase implementierst, kläre konkret die unentschiedenen Konsens-/Coinparameter. Ziel ist ein wartbares, lehrreiches Hobbyprojekt, nicht ein ungetestetes öffentliches Mainnet. +## Web-Wallet ist Pflicht ab dem ersten funktionalen MVP + +Browser-Wallet muss lokal sicher erstellen/importieren/verschlüsselt sichern/exportieren, Adresse/Balance zeigen, PTM senden (Betrag, Ziel, Fee, Bestätigung), empfangen, Historie/Status/Netzwerk anzeigen, sperren/entsperren und Offline-/Fehlerfälle behandeln. Backend und Miner dürfen **nie** private Schlüssel/Seed-/Passphrase erhalten, speichern oder loggen. Browser-Signing auf geprüften Libraries und dokumentiertem Byteformat, sicherer KDF/Encryption/Backup, CSP, SSH-Forwarding/HTTPS und Tests. Zusatzfenster nur nach explizit signierter begrenzter Autorisierung für Runde, Fenster, Miner-ID, Betrag, Nonce und Ablauf, ggf. später widerrufbares Budget. Keine automatische Schlüsselweitergabe und kein unbegrenzter Spend. Das aktuelle `web/wallet` ist **nur statische deaktivierte UI**, keine echte Wallet; keine Mock-Balances/Fake-Transfers als echt anzeigen. + +## Vorgehen, Sicherheit, Qualität + +Zuerst `AGENTS.md`, `docs/PROJEKTPLAN.md`, `docs/PROTOKOLL_ENTWURF.md`, `docs/POP_FAIRNESS_UND_GEBUEHREN.md`, `docs/ROADMAP.md`, `docs/WEB_WALLET.md` und **alle** ADRs lesen. Bei Widersprüchen gezielt prüfen/fragen statt Grundlagen zu erfinden. Vor jedem größeren Schritt Scope, Akzeptanzkriterien, Änderungsplan. Go idiomatisch (`gofmt`, `go test ./...`, `go vet ./...`), Race/Fuzz/Integration bei Bedarf. Deterministischer State, int64/uint64 oder kontrollierte Ganzzahl-Basiseinheiten, kein Float, keine aktuelle OS-Zeit oder ungeprüfte Zufallsquelle im Konsenspfad. Schlüssel-/Wallet-/Replay-/Mint/Burn-/Proof-/Fee-/Zufalls-/Restart-/Partition-Negativtests. + +Keine privaten Schlüssel, Seeds, Tokens, Passwörter, `data/`, Binaries, echte Wallets ins Git; keine destruktiven Befehle ohne Sicherung und Erläuterung. ADR für Architektur-/Protokolländerungen mit Status, Gründen, Alternativen, Konsequenzen. Offenen Stand nicht als beschlossen ausgeben. Bei Lieferung: Dateien geändert, was wirklich funktioniert, echte Tests samt Ergebnis, bekannte Grenzen, **genau der nächste Schritt**. Nicht behaupten, eine Chain oder Wallet sei fertig, solange nur das Gerüst existiert. + +## Reihenfolge + +M1: offenen Parameterkatalog + Simulation/Fairness/Pi-4-Benchmark + ADR. M2: Ledger/Keys/Accounts/Tx/Genesis mit Tests und **parallel funktionale Web-Wallet**, sobald Tx-/Signaturschnittstelle feststeht. M3: CometBFT anbinden, 1 dann 4 Validatoren mit Synchronisation/Ausfällen. M4: drei PoP-Fenster, Identity-Registry, Kosten/Autorisierung, Burn, Proof, Ticketcommit, RNG/Mint mit harten Negativtests. M5: Wallet fertig, Explorer/Status, ARM64-Builds/Pi-Vergleich. M6: Mehrhost-Privat-Testnet, Backup/Recovery, Doku, Release. Fokus: wartbares, lehrreiches Hobbyprojekt statt öffentlichem Mainnet. diff --git a/handoff/REPO_UPDATE_V02.md b/handoff/REPO_UPDATE_V02.md new file mode 100644 index 0000000..10c3ec5 --- /dev/null +++ b/handoff/REPO_UPDATE_V02.md @@ -0,0 +1,19 @@ +# Übergabe nach dem PoP-v0.2-Update + +**Arbeitsordner:** `/home/potatium/src/potatium`, Ubuntu 26.04 LTS, Gitea und VS Code/Codex. + +## Zuerst lesen + +1. `docs/decisions/0003-pop-fenster-und-gebuehren.md` +2. `docs/PROTOKOLL_ENTWURF.md` +3. `docs/POP_FAIRNESS_UND_GEBUEHREN.md` +4. `docs/ROADMAP.md` und `docs/WEB_WALLET.md` +5. `handoff/STARTPROMPT_VSCODE_CODEX.md` für den nächsten Codex-Turn + +## Entscheidungen und Grenzen + +Akzeptiert: drei serielle PoP-Fenster, gratis erstes Fenster, weitere nur optional mit fixen + progressiven Burn-Gebühren, Bezug auf die letzten ungefähr 90 Tage eigener PoP-Gewinne/Betreibergruppe, höchstens ein Ticket pro Miner-ID je Runde. Nicht festgelegt: konkrete Gebühren, Wahrscheinlichkeit, Emission, Block-/Fensterzeiten, Kryptografie, Beacon-Fallback. Keine echte Miner-/Wallet-/Blockchain-Implementierung in diesem Update. + +## Nächste Aufgabe für Codex + +Gib zuerst das M1-Parameterblatt aus, simuliere kostenpflichtige Teilnahme und reale Gewinnchancen bei 5/10/20/50 Minern, erkläre Schutz gegen Gebührenumgehung per Wallettransfer/Mehrfachidentität und entwickle einen Pi-4-Benchmarkplan. Keine eigenmächtigen festen Coinparameter. diff --git a/handoff/SCHNELLKOPIE_CHATGPT.md b/handoff/SCHNELLKOPIE_CHATGPT.md index e2b79fa..88bc633 100644 --- a/handoff/SCHNELLKOPIE_CHATGPT.md +++ b/handoff/SCHNELLKOPIE_CHATGPT.md @@ -1,9 +1,6 @@ -# Projekt ChatGPT konfigurieren +# ChatGPT-Projekt Potatium aktualisieren -1. Neues ChatGPT-Projekt **Potatium** erstellen. -2. Inhalt von `handoff/CHATGPT_PROJEKTANWEISUNGEN.md` als Projektanweisungen einfügen (unter 8000 Zeichen). -3. `docs/PROJEKTPLAN.md`, `docs/ARCHITEKTUR.md`, `docs/PROTOKOLL_ENTWURF.md`, `docs/WEB_WALLET.md`, `docs/ROADMAP.md`, `docs/decisions/` und das Logo bei Bedarf dem Projekt als Dateien hinzufügen. -4. Die Coding-Arbeit künftig im VS Code Workspace durchführen, `AGENTS.md` wird von Codex als Repository-Kontext verwendet. -5. Entscheidungen zuerst in Git versionieren; ChatGPT-Projektanweisungen bei grundlegenden Änderungen synchronisieren. - -**Nach dem Wechsel ist kein Rückgriff auf diesen bisherigen Chat erforderlich.** Der ausführliche Stand ist im ZIP enthalten. Bei späteren besonderen historischen Fragen kannst du ihn selbstverständlich weiterhin verwenden. +1. In ChatGPT-Projekt **Potatium** die Anweisungen durch den **vollständigen Inhalt** von `handoff/CHATGPT_PROJEKTANWEISUNGEN.md` ersetzen (unter 8.000 Zeichen). +2. Bei Bedarf `docs/PROTOKOLL_ENTWURF.md`, `docs/POP_FAIRNESS_UND_GEBUEHREN.md`, ADR 0003 und `docs/ROADMAP.md` als aktuellen Dateistand hinzufügen oder ersetzen. +3. VS Code/Codex im Workspace `/home/potatium/src/potatium`, Regeln aus `AGENTS.md` beachten; mit `handoff/STARTPROMPT_VSCODE_CODEX.md` fortfahren. +4. Maßgeblich ist das *aktuelle Git-Repository*, nicht eine alte Chat-Zusammenfassung. diff --git a/handoff/STARTPROMPT_VSCODE_CODEX.md b/handoff/STARTPROMPT_VSCODE_CODEX.md index f97725b..972d386 100644 --- a/handoff/STARTPROMPT_VSCODE_CODEX.md +++ b/handoff/STARTPROMPT_VSCODE_CODEX.md @@ -1,22 +1,29 @@ -# Startprompt für OpenAI Codex in VS Code +# Aktualisierter Startprompt für Codex in VS Code: Potatium v0.2 -Diesen Text **nach** dem Verbinden von VS Code zum LXC, dem Öffnen von `/home/potatium/src/potatium` und dem Ausführen von `scripts/doctor.sh` in Codex einfügen: +Im Remote-Workspace **`/home/potatium/src/potatium`** in das Codex-Panel kopieren: --- -Du arbeitest ab jetzt als leitender Go-Entwickler und technischer Reviewer am Projekt **Potatium (PTM)**. Der Workspace ist das Stammverzeichnis dieses Git-Repositories auf einem unprivilegierten Ubuntu-26.04-LTS-LXC. Dieses Repository ist der maßgebliche Projektstand, nicht frühere Chat-Inhalte. +Du bist technischer Architekt, leitender Go-Entwickler und Reviewer für **Potatium (PTM)**. Dies ist ein eigenständiges Hobby-Layer-1-Projekt im privaten Gitea-Monorepo auf Ubuntu Server 26.04 LTS (unprivilegierter Proxmox-LXC). Arbeite ausschließlich im Workspace `/home/potatium/src/potatium`. Behandele den Git-Stand als maßgeblich; keine Fremdänderungen überschreiben, keine Commits/Pushs ohne Auftrag. -**Lies zuerst vollständig:** `AGENTS.md`, `README.md`, `docs/PROJEKTPLAN.md`, `docs/ARCHITEKTUR.md`, `docs/PROTOKOLL_ENTWURF.md`, `docs/WEB_WALLET.md`, `docs/ROADMAP.md` und `docs/decisions/*.md`. Beachte besonders: Eigenständige Hobby-L1, Go, PoP mit je einem Los pro registrierter Node und Runde, Validatoren getrennt von Minern, **Web-Wallet zwingend ab funktionalem MVP**. Aktuell ist die WebGUI **nur deaktivierter Mock ohne Wallet-Funktion**; behaupte nichts anderes. +**Vor jeglicher Implementierung:** Lies `AGENTS.md`, `README.md`, `docs/PROJEKTPLAN.md`, `docs/PROTOKOLL_ENTWURF.md`, `docs/POP_FAIRNESS_UND_GEBUEHREN.md`, `docs/ARCHITEKTUR.md`, `docs/WEB_WALLET.md`, `docs/ROADMAP.md` und alle `docs/decisions/*.md`. Erkenne den **ADR 0003** zur PoP-Änderung als aktuelle Produktgrundlage an. -**Erster Auftrag (jetzt direkt ausführen):** +### Beschlossene Produktprinzipien -1. Prüfe read-only die vorhandenen Dateien und Tools, Git-Status, Go-Version und Projektstruktur. Prüfe, welche Skripte in diesem LXC tatsächlich gelaufen sind. Niemals fehlenden Fortschritt erfinden. -2. Führe `go test ./...`, `go vet ./...` und `bash -n scripts/*.sh` aus. Falls etwas scheitert: Ursache analysieren, minimale reproduzierbare Korrektur mit Tests durchführen. -3. Prüfe den Vorschlag „CometBFT mit eigener ABCI++-App, kein Cosmos SDK“ gegen aktuelle APIs und dokumentiere begründete Risiken/Alternativen. **Keine schwergewichtigen Dependencies installieren und noch kein Netzwerk starten**, bevor das technische Konzept geprüft wurde. -4. Erstelle bzw. ergänze eine kurze **Phase-M1-Entscheidungsvorlage** in `docs/`: Welche technischen Entscheidungen müssen vor Wallet-Kryptografie, Transaktionsformat, Genesis, Konsens und PoP feststehen? Gib pro Punkt 1 bis 2 fachlich begründete Alternativen und eine Empfehlung, aber deklariere unentschiedene Punkte nicht als beschlossen. -5. Erstelle einen minimalen umsetzbaren Plan für die **erste echte Implementierung**, der ein deterministisches Ledger, verifizierbare Signaturen und eine früh funktionsfähige **Web-Wallet** eng verzahnt. Keine CLI-only-Roadmap, keine Fake-Keys und keine Mock-Balances als fertige Wallet. -6. Wenn in M0 offensichtliche, risikoarme Infrastruktur-/Testprobleme auffallen, repariere sie inklusive Tests. Sonst nur dokumentieren, noch keine großen Features ohne Architekturgate implementieren. +- Pro Mining-**Runde** genau drei nacheinander freigeschaltete **Fenster** (nicht 3 Blockchain-Runden); je zugelassene Mining-Identität maximal **ein** Ticket je Gesamtrunde. +- Fenster 1 kostenlos; Fenster 2 und 3 freiwillig solange noch kein Ticket angenommen wurde, mit **fixer plus progressiver Gebühr**. Progressionsbasis = zugeordnete PoP-Gewinne der zurückliegenden **ca. 90 Tage**, **nicht** aktuelles Wallet-Guthaben; kein lebenslanger Malus. +- Kosten von Fenster 3 höher bei sinkendem Grenznutzen; zusätzliche Gebühren werden verbrannt. Überweisungsgebühren sind separat für Validatoren vorgesehen, Verteilungsmechanik offen. +- Schwache Rechner/Pi 4 sollen begrenzte SHA-256-PoW-Aufgaben rechtzeitig bearbeiten können, harte Fairness- und Sybil-Grenzen dokumentieren. Für die Ziehung muss die Ticketliste vor Bekanntwerden des überprüfbaren künftigen Zufallswerts gebunden sein. +- CometBFT/ABCI++ mit eigener Go-App ist Architekturpräferenz, **ohne Cosmos SDK**. Blockvalidator und Miner sind getrennt. +- Web-Wallet mit echter Kontoerstellung/Import/verschlüsseltem Backup, Balance, Senden/Empfangen, Status, History, Lock/Unlock gehört **ab erstem funktionalem MVP** dazu. Bestehende UI ist nur statische Vorschau. Niemals Backend-/Minerzugriff auf private Browser-Wallet-Schlüssel. -**Arbeitsregeln:** Minimale Änderungen; Go idiomatisch; echte Tests und reproduzierbare Ergebnisse; Sicherheitsgrenzen offen nennen; keine Secrets/Git-Credentials lesen oder ausgeben; kein ungebetener Push, keine destruktiven Eingriffe, keine öffentlich erreichbaren Ports. Antworte auf Deutsch. +### Erster Auftrag (kein PoP-Produktivcode!) -**Zum Abschluss:** Geänderte Dateien, tatsächlich ausgeführte Prüfungen mit Resultaten, dokumentierte offene Entscheidungen und **genau den nächsten ausführbaren Entwicklungsschritt** nennen. +1. Bestandsaufnahme: Git-Status, Dokumentenwidersprüche, tatsächliche Go/Ubuntu-Version, Projektfiles. Führe `bash scripts/doctor.sh`, `go test ./...`, `go vet ./...`, `bash -n scripts/*.sh` aus. Berichte echte Resultate. +2. Prüfe die aktuelle PoP-Dokumentation auf Widersprüche, insbesondere Wallet-Guthaben versus 90-Tage-PoP-Gewinne, „eine Runde“ versus „drei Fenster“, **ein Ticket**, Burn und Trennung Miner/Validatoren. +3. Erstelle eine **Entscheidungsvorlage M1**, welche konkreten Parameter noch fehlen: Coinsupply/Emission/Genesis/Einheiten, Ed25519/Adresse/Tx-Format, Blockhöhe/Zeit, Anzahl Blöcke je Fenster, Endlichkeit/Hash-Schwelle der PoW-Rätsel, exakte marginale Fee-Formel mit Integer-Rundung, Betreibergruppen/90-Tage-Lookback, Fee-Autorisierung, Beacon-Fallback und Zensur-/Reorg-Regeln. +4. Erstelle oder prüfe eine **nicht konsenskritische Fairness-/Gebührensimulation** (Netzwerke mit 5/10/20/50 Minern, kostenlos/2/3 Fenster, neue und erfolgreiche Miner, verschiedene Gebührenkurven); dokumentiere Erfolgsrate, **echte Gewinnerchance**, erwartete und maximal mögliche Kosten und Nettoerwartung. Zahlen aus früheren Chats nur als beispielhafte Forschungsparameter, **nicht als beschlossene Rules**. +5. Schlage einen Raspberry-Pi-4-Benchmark vor und prüfe CometBFT-/ABCI++-Versionen nur anhand tatsächlich verfügbarer offizieller Dokumentation. Keine großen Dependencies oder konsenskritischen Logiken implementieren, bevor Parameter vom Nutzer freigegeben wurden. +6. Schließe mit: geänderte Dateien, echte Tests und Resultate, offene Sicherheits-/Rechtsrisiken, drei konkrete nächste Entscheidungen. Keine Phase als fertig erklären, wenn nur ein Mock existiert. + +--- diff --git a/scripts/simulate_pop_v02.py b/scripts/simulate_pop_v02.py new file mode 100644 index 0000000..002e88b --- /dev/null +++ b/scripts/simulate_pop_v02.py @@ -0,0 +1,95 @@ +#!/usr/bin/env python3 +"""Illustrative, non-consensus PoP fee/fairness research. All numeric values hypothetical.""" +from __future__ import annotations +import argparse +import random + + +def progressive_example(rewards_90d: float) -> float: + """Example marginal brackets. NEVER use floating-point for on-chain fees.""" + if rewards_90d < 0: + raise ValueError('Rewards must be nonnegative') + return (min(rewards_90d, 10) * 0.00005 + + min(max(rewards_90d - 10, 0), 90) * 0.0002 + + max(rewards_90d - 100, 0) * 0.0005) + + +def fee_example(window: int, rewards_90d: float) -> float: + if window == 1: + return 0.0 + p = progressive_example(rewards_90d) + if window == 2: + return 0.001 + p + if window == 3: + return 0.003 + 2 * p + raise ValueError('Window must be 1, 2 or 3') + + +def qualify(rng: random.Random, windows: int, probability: float, + rewards_90d: float) -> tuple[bool, float]: + """One ticket at most, fees charged only after the previous window fails.""" + if not 1 <= windows <= 3 or not 0 <= probability <= 1: + raise ValueError('Invalid windows/probability') + fee = 0.0 + for window in range(1, windows + 1): + if window > 1: + fee += fee_example(window, rewards_90d) + if rng.random() < probability: + return True, fee + return False, fee + + +def simulate(miners: int, runs: int, seed: int, probability: float, + windows: int, rewards_90d: float, reward: float = 1.0) -> dict[str, float]: + """One chosen miner vs N-1 miners always attempting window one.""" + if miners < 1 or runs < 1 or reward < 0: + raise ValueError('Invalid simulation scenario') + rng = random.Random(seed) + got_ticket = wins = 0 + spent = 0.0 + for _ in range(runs): + qualified, fee = qualify(rng, windows, probability, rewards_90d) + spent += fee + if qualified: + got_ticket += 1 + others = sum(rng.random() < probability for _ in range(miners - 1)) + if qualified and rng.randrange(others + 1) == 0: + wins += 1 + return { + 'ticket_probability': got_ticket / runs, + 'win_probability': wins / runs, + 'avg_fee': spent / runs, + 'max_fee': sum(fee_example(w, rewards_90d) for w in range(2, windows + 1)), + 'net_expected_ptm': (wins / runs) * reward - spent / runs, + } + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--runs', type=int, default=25000) + parser.add_argument('--seed', type=int, default=20261025) + parser.add_argument('--p', type=float, default=0.70, help='Example success per full window') + parser.add_argument('--reward', type=float, default=1.0, help='Illustrative PTM per won lottery') + args = parser.parse_args() + print('FORSCHUNGSMODELL, KEINE PROTOKOLLREGEL. Float nur für Simulation, niemals On-chain.') + print(f'Parameter: runs={args.runs}, seed={args.seed}, p={args.p}, reward={args.reward} PTM') + print('Alle anderen Miner nutzen nur das kostenlose Fenster 1.') + print('N 90d-Ertrag Fenster Ticket% Gewinn% Ø Gebühr max Gebühr Netto-PTM/Runde') + for n in (5, 10, 20, 50): + for mined_90d in (0, 10, 100, 1000): + for windows in (1, 2, 3): + res = simulate(n, args.runs, args.seed + n + int(mined_90d), + args.p, windows, float(mined_90d), args.reward) + print(f'{n:<3} {mined_90d:>10} {windows:>7} ' + f'{100*res["ticket_probability"]:>7.2f} ' + f'{100*res["win_probability"]:>8.2f} ' + f'{res["avg_fee"]:>9.6f} ' + f'{res["max_fee"]:>11.6f} ' + f'{res["net_expected_ptm"]:>15.6f}') + print('\nACHTUNG: Modell ohne Sybil-Effekt, Gebührenbudget, Validator-Zensur, reale Hashzeiten,') + print('endogene Teilnahmeentscheidung oder Unsicherheit der PoP-Belohnung; keine') + print('Garantie für faire Chancen oder wirtschaftlich sinnvolle Tarifwahl.') + + +if __name__ == '__main__': + main() diff --git a/tests/test_pop_simulation.py b/tests/test_pop_simulation.py new file mode 100644 index 0000000..15ddddb --- /dev/null +++ b/tests/test_pop_simulation.py @@ -0,0 +1,35 @@ +"""Tests of illustrative, non-consensus simulation only.""" +import sys +import unittest +from pathlib import Path +sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'scripts')) +from simulate_pop_v02 import fee_example, progressive_example, qualify, simulate +import random + + +class FeeAndSimulationTests(unittest.TestCase): + def test_example_fees_monotonic(self): + for reward in (0, 1, 10, 100, 1000): + self.assertEqual(fee_example(1, reward), 0) + self.assertGreater(fee_example(3, reward), fee_example(2, reward)) + self.assertLess(progressive_example(0), progressive_example(100)) + + def test_no_ticket_when_probability_zero(self): + self.assertEqual(qualify(random.Random(1), 3, 0, 100), + (False, fee_example(2, 100) + fee_example(3, 100))) + + def test_free_win_ends_without_fee(self): + self.assertEqual(qualify(random.Random(1), 3, 1, 100), (True, 0)) + + def test_reproducible(self): + a = simulate(5, 100, 123, .7, 2, 50) + b = simulate(5, 100, 123, .7, 2, 50) + self.assertEqual(a, b) + + def test_invalid_windows(self): + with self.assertRaises(ValueError): + fee_example(4, 1) + + +if __name__ == '__main__': + unittest.main()