michael/potatium
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e2d0be22fda73f075ef0b35f941aa31c70fd5106
potatium/docs/GESAMTHANDBUCH.md
T

31 KiB
Raw Blame History

🥔 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:

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:

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; <LXC-IP> durch die echte Adresse ersetzen.
  3. Aus dem Verzeichnis, in dem das ZIP liegt, ausführen:
scp Potatium_Starterkit_2026-10-24.zip potatium@<LXC-IP>:/home/potatium/
ssh potatium@<LXC-IP>

Du landest nun als normaler Benutzer potatium auf dem LXC. Passwortloses SSH konfigurieren wir nach dem erfolgreichen Basischeck.

4. Archiv ins Workdir entpacken

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

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:

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

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:

ssh -L 8080:127.0.0.1:8080 potatium@<LXC-IP>

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:

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 <DEINE-GIT-SSH-URL>
git push -u origin main

<DEINE-GIT-SSH-URL> 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:

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:
Host potatium-dev
    HostName <LXC-IP>
    User potatium
    IdentityFile ~/.ssh/id_ed25519
  1. In VS Code Befehl Remote-SSH: Connect to Host... → potatium-dev.
  2. Auf dem Remote-Host Ordner /home/potatium/src/potatium öffnen.
  3. 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.
  4. 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

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

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)

  • Logo, ChatGPT-Anweisungen, Protokollentwurf, Codex-AGENTS und Roadmap archiviert.
  • 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)

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.

Reference in new issue View Git Blame Copy Permalink