PalladiumWallet/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Cos'è questo progetto

Wallet desktop SPV (stile Sparrow) per la criptovaluta Palladium (PLM), una catena UTXO derivata da Bitcoin. Solo Windows e Linux, niente mobile. Lightning è esplicitamente escluso dal primo rilascio (§11 del blueprint).

La fonte di verità è blueprint.md: specifica completa con parametri di consenso verificati contro il nodo, algoritmi, protocollo di rete e sequenza di costruzione. Prima di implementare qualsiasi funzionalità, leggere la sezione corrispondente del blueprint. La sequenza di costruzione da seguire è quella del §16 (profilo rete → crypto/chiavi → persistenza → rete → SPV → transazioni → GUI → hardware/multisig).

Stack

.NET 8 + Avalonia UI + NBitcoin (§19 del blueprint). Struttura della solution:

PalladiumWallet.sln
├─ src/Core/   Chain/ Crypto/ Wallet/ Spv/ Net/ Storage/  (nessuna dipendenza UI)
├─ src/App/    Avalonia UI
├─ src/Cli/    CLI sullo stesso Core
└─ tests/      xUnit

Regola di dipendenza non negoziabile: App e Cli dipendono solo da Core; la GUI parla solo con l'Application API, mai direttamente con rete o crittografia. Core non conosce la UI.

Comandi

Il .NET 8 SDK è installato in ~/.dotnet (via dotnet-install.sh, senza root): nelle shell non interattive serve export PATH="$HOME/.dotnet:$PATH" DOTNET_ROOT="$HOME/.dotnet" prima dei comandi dotnet.

• Build: dotnet build
• Test (headless, è il livello principale di verifica): dotnet test
• Singolo test: dotnet test --filter "FullyQualifiedName~NomeTest"
• CLI contro testnet/regtest: dotnet run --project src/Cli -- <comando>
• GUI con hot reload: dotnet watch --project src/App
  • Su questa macchina (WSL2 con WSLg) la finestra appare direttamente sul desktop Windows: niente X server o librerie da installare, è già tutto verificato funzionante.
• Publish Windows: dotnet publish -r win-x64 -p:PublishSingleFile=true --self-contained
• Publish Linux: dotnet publish -r linux-x64 --self-contained (poi AppImage via PupNet Deploy)

La logica core e la crypto si testano senza GUI né rete reale; la GUI serve solo per rifinire l'interfaccia (§19.7).

Comandi CLI principali (src/Cli)

create/restore/restore-xpub/info per i wallet; sync/send/reset-certs contro il server di indicizzazione (--server host:porta [--ssl]); newseed/addresses come strumenti. Eseguire senza argomenti per l'usage completo. Il file wallet di default è ~/.palladium-wallet/<rete>/wallets/default.wallet.json (sovrascrivibile con --file).

Architettura — punti che richiedono più file per essere capiti

• Livelli (§2): GUI → Application API → Dominio wallet → SPV/Sync → Rete → Crittografia → Persistenza. Ogni livello dipende solo verso il basso.
• Profilo di rete (§3): tutte le costanti di catena (prefissi indirizzi, header BIP32, HRP bech32, genesi, porte, coin_type 746) vanno centralizzate in Core/Chain via NetworkBuilder e selezionabili per rete (mainnet/testnet/regtest). Nessun magic number sparso nel codice.
• LWMA / skip PoW (§3, §7): la catena usa difficoltà LWMA con blocchi da 2 minuti; un client SPV non può ricalcolarla, quindi skip_pow_validation = true e la fiducia è ancorata ai checkpoint hardcoded (§7.3). Questo strato è custom: NBitcoin assume il retargeting di Bitcoin.
• Cosa fornisce NBitcoin vs cosa è custom (§19.2): NBitcoin copre rete custom, BIP32/39, indirizzi, transazioni, PSBT, firma, encoding, hashing — non reimplementarli. Va scritto a mano: client JSON-RPC del server di indicizzazione (protocollo ElectrumX-like, §10) con pool, TLS pinning TOFU e proxy/Tor; sincronizzazione SPV con verifica Merkle (§7.4); validazione header/checkpoint; coin selection e fee policy; file wallet JSON cifrato versionato.
• PSBT-centrico (§6.5): ogni flusso di firma passa per PSBT (offline, air-gapped, multisig, hardware).
• Le porte di default (50001/50002) sono del server di indicizzazione, non la porta P2P del nodo (2333): il wallet SPV parla solo col server di indicizzazione.
• Stato implementato (passi 1–7 del §16): Core/Chain profili rete; Core/Crypto BIP39/32/SLIP-132/HdAccount; Core/Storage file wallet JSON v1 + AES-GCM (PBKDF2-SHA512) + percorsi dati; Core/Net ElectrumClient (JSON-RPC newline su TCP/TLS, TOFU in server-certs.json); Core/Spv scripthash, verifica Merkle obbligatoria su ogni tx confermata, sincronizzazione con gap limit; Core/Wallet TransactionFactory (RBF on, send-all, PSBT per watch-only) e WalletLoader (doc→account). GUI Avalonia a pannello unico in MainWindowViewModel. Mancano (TODO §16 passi 8-9): multisig, hardware wallet, coin control UI, fee ETA/mempool, RBF/CPFP UI, header chain completa su disco, pool multi-server, proxy/Tor.

Regole di lavoro

• Test cross-implementazione obbligatori (§16): ad ogni passo confrontare indirizzi, txid e PSBT con un wallet di riferimento (golden vectors). Un indirizzo o txid diverso è un bug bloccante.
• Sicurezza (§17): seed e chiavi private mai in chiaro su disco, mai nei log, mai in rete; ogni risposta dei server va validata con prove di Merkle + checkpoint; watch-only realmente read-only.
• Le funzionalità marcate (opzionale) nel blueprint possono essere rimandate ma vanno comunque considerate nella progettazione.