commit e2d0be22fda73f075ef0b35f941aa31c70fd5106 Author: Michael Böhmländer Date: Sat Oct 24 21:01:13 2026 +0000 Initial commit: Potatium diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a91aa99 --- /dev/null +++ b/.gitignore @@ -0,0 +1,37 @@ +# Go outputs +/bin/ +/dist/ +*.exe +*.test +*.out +/coverage/ +*.prof + +# Node/frontend (if introduced later) +node_modules/ +/web/dist/ + +# Workspace, databases, chain state and secrets +.local-data/ +data/ +*.db +*.sqlite +*.sqlite3 +*.wallet +*.keystore +*.pem +*.key +*.seed +.env +.env.* +!.env.example +*.log + +# Editors / OS +.DS_Store +.idea/ +.vscode/*.local.json + +# Local transient +*.tmp +*.swp diff --git a/.vscode/.gitkeep b/.vscode/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..70ef784 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,8 @@ +{ + "recommendations": [ + "ms-vscode-remote.remote-ssh", + "golang.go", + "openai.chatgpt", + "eamodio.gitlens" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..7259bb0 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "editor.formatOnSave": true, + "go.useLanguageServer": true, + "files.exclude": {"**/.DS_Store": true} +} diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..ba1a4b8 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,8 @@ +{ + "version": "2.0.0", + "tasks": [ + {"label": "Potatium: Tests", "type": "shell", "command": "go test ./...", "group": "test", "problemMatcher": []}, + {"label": "Potatium: Build", "type": "shell", "command": "make build", "group": "build", "problemMatcher": []}, + {"label": "Potatium: Wallet Vorschau", "type": "shell", "command": "make run-ui", "isBackground": true, "problemMatcher": []} + ] +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..abbf3ce --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,14 @@ +# Codex-Projektregeln für Potatium + +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. diff --git a/MANIFEST.sha256 b/MANIFEST.sha256 new file mode 100644 index 0000000..55c39c0 --- /dev/null +++ b/MANIFEST.sha256 @@ -0,0 +1,49 @@ +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/Makefile b/Makefile new file mode 100644 index 0000000..22bceec --- /dev/null +++ b/Makefile @@ -0,0 +1,25 @@ +.PHONY: help fmt test vet build run-ui doctor + +help: + @printf 'Targets: fmt test vet build run-ui doctor\n' + +fmt: + gofmt -w cmd internal + +test: + go test ./... + +vet: + go vet ./... + +build: + mkdir -p bin + go build -o bin/potatiumd ./cmd/potatiumd + go build -o bin/potatium-miner ./cmd/potatium-miner + go build -o bin/potatium-cli ./cmd/potatium-cli + +run-ui: + go run ./cmd/potatiumd -web-dir web/wallet -listen 127.0.0.1:8080 + +doctor: + bash scripts/doctor.sh diff --git a/README.md b/README.md new file mode 100644 index 0000000..d343f63 --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# 🥔 Potatium (PTM) + +**Eigenständige Hobby-Blockchain mit ressourcenschonender Proof-of-Potato-Lotterie.** + +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. + +## Schnelleinstieg + +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. + +## Geplante Programme + +- `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. + +## Was aktuell schon läuft? + +Das Starterprojekt enthält einen kleinen lokalen **UI-Vorschau-Server**, aber **keine Blockchain**, keine Schlüsselverwaltung und keine echte Transaktion: + +```bash +go test ./... +go run ./cmd/potatiumd -web-dir web/wallet -listen 127.0.0.1:8080 +``` + +Aufruf lokal `http://127.0.0.1:8080`; bei Remote-SSH Port 8080 in VS Code weiterleiten. + +## 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. diff --git a/START_HIER.md b/START_HIER.md new file mode 100644 index 0000000..2494de7 --- /dev/null +++ b/START_HIER.md @@ -0,0 +1,199 @@ +# 🥔 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`. **Dies ist der einzige verbindliche Projektpfad; ein zweites `workdir` wird nicht genutzt.** 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 +# Bereits angelegtes Git-Verzeichnis beibehalten; andernfalls neu initialisieren: +test -d .git || git init -b main +git branch -M main +git config user.name "DEIN-GIT-NAME" +git config user.email "DEINE-GIT-EMAIL" +# Der SSH-Host-Alias "gitea" wurde bereits getestet. +if git remote get-url origin >/dev/null 2>&1; then + git remote set-url origin git@gitea:michael/potatium.git +else + git remote add origin git@gitea:michael/potatium.git +fi +# Vorher prüfen, dass keine privaten Schlüssel oder Secrets enthalten sind: +git status --short +git add . +git diff --cached --stat +git commit -m "chore: initialize Potatium project scaffold" +git push -u origin main +``` + +`` ist die echte SSH-Clone-URL deines neuen Repos und **kein** wörtlich auszuführender Platzhalter. Wenn noch kein Git-SSH-Schlüssel existiert, vor dem Push einen separaten Schlüssel erzeugen und dessen öffentlichen Teil 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. diff --git a/assets/logo/.gitkeep b/assets/logo/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/assets/logo/README.md b/assets/logo/README.md new file mode 100644 index 0000000..694e59c --- /dev/null +++ b/assets/logo/README.md @@ -0,0 +1,5 @@ +# Potatium-Logo + +`potatium-ptm-logo.png`: **vom Nutzer gewählte abstrakte PTM-Variante** (goldenes P / Kartoffelform auf Schwarz), unverändert aus der Unterhaltung übernommen. Das vorherige Wappen-/Königskartoffel-Motiv ist ausdrücklich **nicht** die finale Wahl. + +Als Raster-PNG in 1254×1254 px vorhanden. Nicht automatisch eine Vektordatei oder transparent; SVG wird erst nach echter Nachzeichnung benötigt. Vor öffentlicher Markennutzung Namens-/Zeichenkollisionen prüfen. diff --git a/assets/logo/potatium-ptm-logo.png b/assets/logo/potatium-ptm-logo.png new file mode 100644 index 0000000..c24146c Binary files /dev/null and b/assets/logo/potatium-ptm-logo.png differ diff --git a/cmd/potatium-cli/.gitkeep b/cmd/potatium-cli/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/cmd/potatium-cli/main.go b/cmd/potatium-cli/main.go new file mode 100644 index 0000000..f33cb0a --- /dev/null +++ b/cmd/potatium-cli/main.go @@ -0,0 +1,7 @@ +package main + +import "fmt" + +func main() { + fmt.Println("potatium-cli: development scaffold only; no wallet or transactions exist yet") +} diff --git a/cmd/potatium-miner/.gitkeep b/cmd/potatium-miner/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/cmd/potatium-miner/main.go b/cmd/potatium-miner/main.go new file mode 100644 index 0000000..a84ed4b --- /dev/null +++ b/cmd/potatium-miner/main.go @@ -0,0 +1,7 @@ +package main + +import "fmt" + +func main() { + fmt.Println("potatium-miner: development scaffold only; mining is NOT implemented") +} diff --git a/cmd/potatiumd/.gitkeep b/cmd/potatiumd/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/cmd/potatiumd/main.go b/cmd/potatiumd/main.go new file mode 100644 index 0000000..5fd3b7c --- /dev/null +++ b/cmd/potatiumd/main.go @@ -0,0 +1,54 @@ +package main + +import ( + "encoding/json" + "flag" + "fmt" + "log" + "net" + "net/http" + "os" + "time" + + "potatium.local/potatium/internal/app" +) + +func main() { + webDir := flag.String("web-dir", "web/wallet", "directory containing static wallet design preview") + listen := flag.String("listen", "127.0.0.1:8080", "loopback address for development preview") + flag.Parse() + + host, _, err := net.SplitHostPort(*listen) + if err != nil || (host != "127.0.0.1" && host != "localhost" && host != "::1") { + fmt.Fprintln(os.Stderr, "refusing non-loopback listener; use SSH port forwarding") + os.Exit(2) + } + if _, err := os.Stat(*webDir + "/index.html"); err != nil { + log.Fatalf("web-dir must contain index.html: %v", err) + } + + mux := http.NewServeMux() + mux.HandleFunc("GET /api/v1/status", func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json; charset=utf-8") + w.Header().Set("Cache-Control", "no-store") + if err := json.NewEncoder(w).Encode(app.CurrentStatus()); err != nil { + log.Printf("status encoding failed: %v", err) + } + }) + mux.Handle("/", http.FileServer(http.Dir(*webDir))) + protected := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("X-Content-Type-Options", "nosniff") + w.Header().Set("X-Frame-Options", "DENY") + w.Header().Set("Referrer-Policy", "no-referrer") + w.Header().Set("Cache-Control", "no-store") + w.Header().Set("Content-Security-Policy", "default-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; connect-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'") + mux.ServeHTTP(w, r) + }) + server := &http.Server{ + Addr: *listen, + Handler: protected, + ReadHeaderTimeout: 5 * time.Second, + } + log.Printf("Potatium UI preview (NO CHAIN / NO WALLET) at http://%s", *listen) + log.Fatal(server.ListenAndServe()) +} diff --git a/config/.gitkeep b/config/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/deploy/devnet/.gitkeep b/deploy/devnet/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/deploy/testnet/.gitkeep b/deploy/testnet/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/ARCHITEKTUR.md b/docs/ARCHITEKTUR.md new file mode 100644 index 0000000..785ab97 --- /dev/null +++ b/docs/ARCHITEKTUR.md @@ -0,0 +1,52 @@ +# Architekturentwurf + +```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) +``` + +Diese Skizze ist eine **Zielarchitektur**, nicht bereits implementiert. + +## Prozess- und Verantwortungsgrenzen + +- 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. + +## Netzwerk & Reihenfolge + +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. + +**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. diff --git a/docs/GESAMTHANDBUCH.md b/docs/GESAMTHANDBUCH.md new file mode 100644 index 0000000..672880c --- /dev/null +++ b/docs/GESAMTHANDBUCH.md @@ -0,0 +1,497 @@ +# 🥔 Potatium – Gesamthandbuch und technische Übergabe + +**Stand: 24.10.2026 · für Ubuntu Server 26.04 LTS · Potatium/PTM.** + +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. + +--- + +--- + +# Inbetriebnahme + +# 🥔 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 + +```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) +``` + +Diese Skizze ist eine **Zielarchitektur**, nicht bereits implementiert. + +## Prozess- und Verantwortungsgrenzen + +- 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. + +## Netzwerk & Reihenfolge + +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. + +**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. + + +--- + +# Protokollentwurf + +# Potatium Protokoll v0.1 – Entwurf, nicht freigegeben + +## Bestätigte Produktziele + +- 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. + +## Noch zu entscheiden + +| 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 | + +## Vorgesehene Invarianten + +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. + +## 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. + diff --git a/docs/PROJEKTPLAN.md b/docs/PROJEKTPLAN.md new file mode 100644 index 0000000..9ad6f84 --- /dev/null +++ b/docs/PROJEKTPLAN.md @@ -0,0 +1,89 @@ +# 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. diff --git a/docs/PROTOKOLL_ENTWURF.md b/docs/PROTOKOLL_ENTWURF.md new file mode 100644 index 0000000..2dc70e9 --- /dev/null +++ b/docs/PROTOKOLL_ENTWURF.md @@ -0,0 +1,44 @@ +# Potatium Protokoll v0.1 – Entwurf, nicht freigegeben + +## Bestätigte Produktziele + +- 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. + +## Noch zu entscheiden + +| 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 | + +## Vorgesehene Invarianten + +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. + +## 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. diff --git a/docs/REFERENZEN.md b/docs/REFERENZEN.md new file mode 100644 index 0000000..5aeac89 --- /dev/null +++ b/docs/REFERENZEN.md @@ -0,0 +1,13 @@ +# 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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..05186f5 --- /dev/null +++ b/docs/ROADMAP.md @@ -0,0 +1,35 @@ +# 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. diff --git a/docs/WEB_WALLET.md b/docs/WEB_WALLET.md new file mode 100644 index 0000000..a0c4c21 --- /dev/null +++ b/docs/WEB_WALLET.md @@ -0,0 +1,26 @@ +# 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. diff --git a/docs/decisions/.gitkeep b/docs/decisions/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/decisions/0001-projektgrundlagen.md b/docs/decisions/0001-projektgrundlagen.md new file mode 100644 index 0000000..44d0b80 --- /dev/null +++ b/docs/decisions/0001-projektgrundlagen.md @@ -0,0 +1,11 @@ +# ADR 0001: Projektgrundlagen + +Status: **Accepted** (Produkt- und Entwicklungsziele, Stand 24.10.2026) + +## Entscheidung + +Name Potatium/PTM und abstraktes goldenes P-Logo. Hobby-L1 mit PoW-qualifizierter Ein-Los-Lotterie; Raspberry Pi/Alt-PC als Teilnehmer. Go als Kernsprache, ein Monorepo, Ubuntu 26.04 LTS im Proxmox-LXC, VS Code/Remote SSH/Codex, Web-Wallet ab funktionalem MVP. Separate Validator- und Miner-Rollen. Zunächst kleines, privates Testnetz. + +## Folgen + +Konkrete Mint-/Konsens-/Schlüsselparameter werden nicht aus Beispielzahlen abgeleitet. Sicherheit und reproduzierbare Entwicklung haben Vorrang vor Features. diff --git a/docs/decisions/0002-konsens-stack.md b/docs/decisions/0002-konsens-stack.md new file mode 100644 index 0000000..47e663f --- /dev/null +++ b/docs/decisions/0002-konsens-stack.md @@ -0,0 +1,15 @@ +# ADR 0002: CometBFT + eigene ABCI++-App (Kandidat) + +Status: **Proposed**, nicht endgültig validiert. + +## Vorschlag + +CometBFT übernimmt BFT-Konsens und P2P; Potatium implementiert Zustandsmaschine und PoP-Mining-Lotterie selbst in Go via ABCI++. Kein Cosmos SDK für den Prototyp. PoP entscheidet ausschließlich Coin-Verteilung, nicht Block-Proposer. + +## Alternativen + +Eigener Konsens von Grund auf, Cosmos SDK oder bestehende L1-Fork. Jede Variante hat unterschiedliche Wartungs-/Sicherheitskosten. + +## Prüfaufgaben + +Konkrete CometBFT-Version, ABCI++-APIs, Abhängigkeiten, Validatorzahl, Zustandsinitialisierung und Upgrade-Verfahren in einem kleinen technischen Spike validieren, bevor die Wahl als Accepted markiert wird. diff --git a/go.mod b/go.mod new file mode 100644 index 0000000..7d90327 --- /dev/null +++ b/go.mod @@ -0,0 +1,3 @@ +module potatium.local/potatium + +go 1.23.0 diff --git a/handoff/CHATGPT_PROJEKTANWEISUNGEN.md b/handoff/CHATGPT_PROJEKTANWEISUNGEN.md new file mode 100644 index 0000000..dcde688 --- /dev/null +++ b/handoff/CHATGPT_PROJEKTANWEISUNGEN.md @@ -0,0 +1,53 @@ +# Potatium | ChatGPT-Projektanweisungen + +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. + +## 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. + +## Architektur (Startentscheidung, vor Implementierung prüfen) + +- 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. + +## Proof of Potato: angenommene Produktanforderungen + +- 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. + +## Web-Wallet: ab MVP, keine spätere Kür + +- 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. + +## Arbeitsstil, Qualität, Sicherheit + +- 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. + +## Gewünschte Reihenfolge + +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. + +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. diff --git a/handoff/SCHNELLKOPIE_CHATGPT.md b/handoff/SCHNELLKOPIE_CHATGPT.md new file mode 100644 index 0000000..e2b79fa --- /dev/null +++ b/handoff/SCHNELLKOPIE_CHATGPT.md @@ -0,0 +1,9 @@ +# Projekt ChatGPT konfigurieren + +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. diff --git a/handoff/STARTPROMPT_VSCODE_CODEX.md b/handoff/STARTPROMPT_VSCODE_CODEX.md new file mode 100644 index 0000000..f97725b --- /dev/null +++ b/handoff/STARTPROMPT_VSCODE_CODEX.md @@ -0,0 +1,22 @@ +# Startprompt für OpenAI Codex in VS Code + +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: + +--- + +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. + +**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. + +**Erster Auftrag (jetzt direkt ausführen):** + +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. + +**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. + +**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. diff --git a/internal/api/.gitkeep b/internal/api/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/app/.gitkeep b/internal/app/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/app/status.go b/internal/app/status.go new file mode 100644 index 0000000..b3f0c4b --- /dev/null +++ b/internal/app/status.go @@ -0,0 +1,21 @@ +package app + +// Status reports real capabilities, not planned ones. The starter project is +// not yet a blockchain, and it must not be presented as a functional wallet. +type Status struct { + Project string `json:"project"` + Phase string `json:"phase"` + ChainReady bool `json:"chain_ready"` + WalletReady bool `json:"wallet_ready"` + MiningReady bool `json:"mining_ready"` +} + +func CurrentStatus() Status { + return Status{ + Project: "Potatium", + Phase: "scaffold", + ChainReady: false, + WalletReady: false, + MiningReady: false, + } +} diff --git a/internal/app/status_test.go b/internal/app/status_test.go new file mode 100644 index 0000000..bb91b12 --- /dev/null +++ b/internal/app/status_test.go @@ -0,0 +1,10 @@ +package app + +import "testing" + +func TestScaffoldDoesNotClaimFeatures(t *testing.T) { + state := CurrentStatus() + if state.ChainReady || state.WalletReady || state.MiningReady { + t.Fatal("starter must not claim blockchain, wallet or mining are ready") + } +} diff --git a/internal/chain/.gitkeep b/internal/chain/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/consensus/.gitkeep b/internal/consensus/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/crypto/.gitkeep b/internal/crypto/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/lottery/.gitkeep b/internal/lottery/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/mining/.gitkeep b/internal/mining/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/registry/.gitkeep b/internal/registry/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/storage/.gitkeep b/internal/storage/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/transaction/.gitkeep b/internal/transaction/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/internal/wallet/.gitkeep b/internal/wallet/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/scripts/bootstrap_workdir.sh b/scripts/bootstrap_workdir.sh new file mode 100755 index 0000000..5705ddf --- /dev/null +++ b/scripts/bootstrap_workdir.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +# Idempotent. Called from any location; optional argument: project root. +set -Eeuo pipefail +DEFAULT_ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd) +ROOT=${1:-$DEFAULT_ROOT} +if [[ ! -d "$ROOT" ]]; then + echo "Project root does not exist: $ROOT" >&2; exit 1 +fi +if [[ $EUID -eq 0 ]]; then echo 'Run as regular user potatium, not root.' >&2; exit 1; fi +if [[ ! -f "$ROOT/AGENTS.md" || ! -f "$ROOT/README.md" ]]; then + echo "Refusing to scaffold unrelated directory: missing AGENTS.md/README.md in $ROOT" >&2; exit 1 +fi +DIRS=( + cmd/potatiumd cmd/potatium-miner cmd/potatium-cli + internal/app internal/chain internal/consensus internal/transaction + internal/crypto internal/wallet internal/mining internal/lottery + internal/registry internal/storage internal/api + web/wallet tests/integration config deploy/devnet deploy/testnet + docs/decisions assets/logo .vscode +) +for d in "${DIRS[@]}"; do + mkdir -p "$ROOT/$d" + if [[ ! -e "$ROOT/$d/.gitkeep" ]]; then : > "$ROOT/$d/.gitkeep"; fi +done +mkdir -p "$ROOT/.local-data" "$ROOT/bin" +printf 'Project directories verified in %s\n' "$ROOT" +printf 'Existing files are never replaced. Local data and bin/ are Git-ignored.\n' diff --git a/scripts/doctor.sh b/scripts/doctor.sh new file mode 100755 index 0000000..7879f15 --- /dev/null +++ b/scripts/doctor.sh @@ -0,0 +1,32 @@ +#!/usr/bin/env bash +# Non-destructive checks. Run from unpacked Potatium repository as normal user. +set -Eeuo pipefail +ROOT=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd) +cd "$ROOT" +printf '=== Potatium development environment ===\n' +if [[ -r /etc/os-release ]]; then + # shellcheck disable=SC1091 + . /etc/os-release + echo "OS: ${PRETTY_NAME:-unknown}" + [[ "${ID:-}" == ubuntu && "${VERSION_ID:-}" == '26.04' ]] || echo 'WARN: Expected Ubuntu 26.04 LTS.' +fi +printf 'User: %s\nProject: %s\n' "$(id -un)" "$ROOT" +for p in go git bash curl; do + if ! command -v "$p" >/dev/null 2>&1; then echo "MISSING: $p" >&2; exit 1; fi +done +go version +git --version +if [[ -d .git ]]; then git status --short; else echo 'NOTE: Git repo not initialized yet (normal before git init).'; fi +echo '=== Shell syntax ===' +for f in scripts/*.sh; do bash -n "$f"; done +echo 'OK: shell syntax' +echo '=== Go formatting ===' +UNFORMATTED=$(gofmt -l cmd internal 2>/dev/null || true) +if [[ -n "$UNFORMATTED" ]]; then echo "Go files not gofmt-clean:"; echo "$UNFORMATTED"; exit 1; fi +printf 'OK: gofmt\n=== Go tests ===\n' +go test ./... +printf '=== Go vet ===\n' +go vet ./... +printf '=== Web wallet scaffold ===\n' +test -s web/wallet/index.html && echo 'OK: web/wallet/index.html exists (static preview only)' +printf '\nSUCCESS: development scaffold checks passed; blockchain/wallet NOT implemented.\n' diff --git a/scripts/install_go.sh b/scripts/install_go.sh new file mode 100755 index 0000000..7425482 --- /dev/null +++ b/scripts/install_go.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +# Verified Go installation for Potatium (Ubuntu 26.04 LTS); run as root. +set -Eeuo pipefail +if [[ $EUID -ne 0 ]]; then echo "Run as root: sudo bash scripts/install_go.sh" >&2; exit 1; fi +GO_VERSION="1.27.3" +case "$(dpkg --print-architecture)" in + amd64) ARCH=amd64; SHA256='65efbc80fdc1fa2cd2631cad5b481777a68e8725f34e89f50fc6ac714e379b40';; + arm64) ARCH=arm64; SHA256='a06e99309dbcbdca1a8ccd2282c3ee146e55930886e26b4f1193269587165f49';; + *) echo 'Only Ubuntu amd64 and arm64 supported by this installer' >&2; exit 1;; +esac +ARCHIVE="go${GO_VERSION}.linux-${ARCH}.tar.gz" +if [[ -x /usr/local/go/bin/go ]]; then + EXISTING=$(/usr/local/go/bin/go version) + if [[ "$EXISTING" == "go version go${GO_VERSION} "* ]]; then + echo "Already installed: $EXISTING"; exit 0 + fi + echo "Existing /usr/local/go detected: $EXISTING. Stop. Manually assess upgrade first." >&2 + exit 1 +fi +if [[ -e /usr/local/go ]]; then + echo '/usr/local/go already exists. Refusing to overwrite.' >&2; exit 1 +fi +TEMP=$(mktemp -d) +trap 'rm -rf "$TEMP"' EXIT +printf 'Downloading verified Go %s for linux/%s\n' "$GO_VERSION" "$ARCH" +curl --fail --location --show-error --silent --retry 3 \ + "https://go.dev/dl/${ARCHIVE}" -o "$TEMP/${ARCHIVE}" +printf '%s %s\n' "$SHA256" "$TEMP/${ARCHIVE}" | sha256sum --check --status || { + echo 'Checksum mismatch. Aborted.' >&2; exit 1; +} +tar -xzf "$TEMP/${ARCHIVE}" -C "$TEMP" +# Install a fresh tree, never unpack on top of an existing installation. +mv "$TEMP/go" /usr/local/go +cat > /etc/profile.d/potatium-go.sh <<'ENDPATH' +export PATH="/usr/local/go/bin:$HOME/go/bin:$PATH" +ENDPATH +ln -sfn /usr/local/go/bin/go /usr/local/bin/go +ln -sfn /usr/local/go/bin/gofmt /usr/local/bin/gofmt +/usr/local/go/bin/go version diff --git a/scripts/setup_ubuntu26.sh b/scripts/setup_ubuntu26.sh new file mode 100755 index 0000000..4f3e0ae --- /dev/null +++ b/scripts/setup_ubuntu26.sh @@ -0,0 +1,31 @@ +#!/usr/bin/env bash +# Re-runnable setup for an unprivileged Ubuntu Server 26.04 LTS Proxmox LXC. +set -Eeuo pipefail +if [[ $EUID -ne 0 ]]; then echo 'Run via sudo or as root.' >&2; exit 1; fi +# shellcheck disable=SC1091 +source /etc/os-release +if [[ "${ID:-}" != ubuntu || "${VERSION_ID:-}" != "26.04" ]]; then + echo "This script is intended for Ubuntu 26.04 LTS; detected ${PRETTY_NAME:-unknown}. Aborted." >&2 + exit 1 +fi +if [[ $(uname -m) != x86_64 && $(uname -m) != aarch64 ]]; then + echo 'Use amd64 or arm64 Ubuntu LXC.' >&2; exit 1 +fi +export DEBIAN_FRONTEND=noninteractive +apt-get update +apt-get install -y --no-install-recommends \ + ca-certificates curl git openssh-server sudo unzip zip \ + build-essential make python3 jq tar rsync +if ! id potatium >/dev/null 2>&1; then + adduser --disabled-password --gecos '' potatium + echo 'Created user potatium without password. Set up SSH public key for login.' +fi +usermod -aG sudo potatium +install -d -o potatium -g potatium -m 0755 /home/potatium/src +if command -v systemctl >/dev/null 2>&1; then systemctl enable --now ssh; fi +SCRIPT_DIR=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd) +bash "$SCRIPT_DIR/install_go.sh" +echo +printf 'Setup complete. User: potatium | Source dir: /home/potatium/src | Go: ' +/usr/local/go/bin/go version +printf 'Next: configure SSH key, unpack ZIP, bash scripts/bootstrap_workdir.sh, bash scripts/doctor.sh.\n' diff --git a/tests/integration/.gitkeep b/tests/integration/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/web/wallet/.gitkeep b/web/wallet/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/web/wallet/app.js b/web/wallet/app.js new file mode 100644 index 0000000..5963f84 --- /dev/null +++ b/web/wallet/app.js @@ -0,0 +1,15 @@ +'use strict'; +// Status only. This preview never generates keys or sends transactions. +(async () => { + try { + const response = await fetch('/api/v1/status', { cache: 'no-store' }); + if (!response.ok) return; + const data = await response.json(); + document.getElementById('phase').textContent = `Phase: ${data.phase ?? 'unbekannt'}`; + document.getElementById('chain').textContent = data.chain_ready ? 'Verfügbar' : 'Nicht implementiert'; + document.getElementById('wallet').textContent = data.wallet_ready ? 'Verfügbar' : 'Nicht implementiert'; + document.getElementById('mining').textContent = data.mining_ready ? 'Verfügbar' : 'Nicht implementiert'; + } catch (_) { + document.getElementById('phase').textContent = 'Server offline'; + } +})(); diff --git a/web/wallet/index.html b/web/wallet/index.html new file mode 100644 index 0000000..6d0869f --- /dev/null +++ b/web/wallet/index.html @@ -0,0 +1,24 @@ + + + + + + + Potatium Wallet | Vorschau + + + + +
+
P

Potatium

PTM Wallet · Entwickler-Vorschau

Nicht verbunden
+
Design-Prototyp, keine echte Wallet. Blockchain, Schlüsselverwaltung, Mining und Überweisungen sind noch nicht implementiert. Bitte keine echten Werte verwenden.
+
+
Guthaben
— PTM

Keine Wallet verbunden

+

Meine Wallet

Wallet erstellen oder importieren

Verschlüsselung und Transaktionssignatur werden erst nach Protokollentscheidungen umgesetzt.

+

Letzte Transaktionen

Noch keine Transaktionen vorhanden.

Nach der Anbindung werden Bestätigung und Blockhöhe angezeigt.

+

Netzwerkstatus

Blockchain
Nicht implementiert
Wallet-Funktion
Nicht implementiert
Mining
Nicht implementiert
+
+ +
+ + diff --git a/web/wallet/styles.css b/web/wallet/styles.css new file mode 100644 index 0000000..d588374 --- /dev/null +++ b/web/wallet/styles.css @@ -0,0 +1,22 @@ +:root { color-scheme: dark; font-family: Inter, system-ui, -apple-system, Segoe UI, sans-serif; background:#0d1118; color:#f0f1f3 } +* { box-sizing: border-box } +body { margin: 0; min-height: 100vh; background: radial-gradient(circle at 50% -20%,#25251b,transparent 55%),#0d1118 } +.shell { max-width: 1030px; margin: 0 auto; padding: 34px 20px 30px } +.top,.brand,.actions { display:flex;align-items:center;gap:14px } +.top { justify-content:space-between; margin-bottom:30px } +.coin { display:grid;place-items:center;width:54px;height:54px;border-radius:16px;background:linear-gradient(140deg,#ffe187,#bc7925);font-size:32px;font-weight:850;color:#25200f } +h1 { font-size:1.65rem; margin:0; letter-spacing:-.025em } h2 { margin:0 0 18px;font-size:1.15rem } +.brand p { color:#a3aab6; font-size:.83rem;margin:3px 0 0 } +.pill { background:#242b35;color:#bfc5ce;padding:8px 11px;border-radius:999px;font-size:.76rem } +.warning { border:1px solid #aa8540; border-radius:15px; background:#2c261b;color:#f8de9a; padding:17px 19px;line-height:1.65;margin-bottom:20px } +.grid { display:grid;grid-template-columns:1fr 1fr;gap:18px } +.panel { min-height:235px; padding:25px;border:1px solid #29323c;background:linear-gradient(150deg,#1b222b,#171c23);border-radius:20px } +.hero { background:linear-gradient(150deg,#2c2a20,#192128) } +.eyebrow { color:#a7a7a0;font-size:.88rem }.balance { margin:14px 0 0;font-size:3.5rem;font-weight:750;letter-spacing:-.03em }.balance small {font-size:1.1rem;color:#eec36b} +p,.muted { color:#a5adbb }.actions { margin-top:24px;flex-wrap:wrap } +button {background:#ecc16c;color:#262019;border:0;border-radius:10px;padding:11px 14px;font-size:.9rem;font-weight:700;margin:3px 7px 3px 0} +button.secondary {background:#434956;color:#f2f2f2} button:disabled {opacity:.42;cursor:not-allowed} +.hint { font-size:.77rem;line-height:1.6;margin-top:19px } .empty {text-align:center;border:1px dashed #46515f;border-radius:12px;padding:37px 14px;color:#a5adbb } +dl {display:grid;grid-template-columns:1fr 1fr;gap:17px 10px} dt {color:#a5adbb} dd {margin:0;text-align:right;color:#f1ce83} +footer {color:#77808d;font-size:.8rem;text-align:center;padding-top:40px} +@media(max-width:720px) {.grid{grid-template-columns:1fr}.top{align-items:flex-start}.pill{white-space:nowrap}.balance{font-size:3rem} }