potatium/AGENTS.md

AGENTS.md: verbindliche Leitlinien für Codex im Potatium-Repository

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.