From 46aca513b88e2bb8ce95789afa3cf223a9978fe6 Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Fri, 12 Jun 2026 12:12:34 +0200 Subject: [PATCH] docs: add README with project overview and quickstart Covers what Palladium Wallet is, the tech stack, build/test/run commands and current implementation status. Co-Authored-By: Claude Sonnet 4.6 --- README.md | 170 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d9ab05 --- /dev/null +++ b/README.md @@ -0,0 +1,170 @@ +# Palladium Wallet + +**An SPV desktop wallet built specifically for the Palladium (PLM) cryptocurrency** and optimized for its chain. + +Unlike generic wallets adapted to many coins, Palladium Wallet is designed around Palladium's consensus parameters — a Bitcoin-derived UTXO chain with 2-minute blocks and LWMA difficulty — and centralizes them in a single network profile. This keeps it lightweight, predictable and faithful to the chain: no client-side difficulty recalculation (trust is anchored to hardcoded checkpoints), mandatory Merkle verification on every confirmed transaction, and a network client written specifically for Palladium's indexing server. + +## Features + +- **Lightweight SPV**: syncs against an indexing server (ElectrumX-like protocol) without downloading the full chain. +- **Security**: seed and private keys encrypted on disk (AES-GCM, PBKDF2-SHA512), never in plaintext in logs or on the wire; every server response is validated with Merkle proofs + checkpoints. +- **HD wallet** (BIP39/BIP32), SegWit/wrapped/legacy addresses, watch-only from xpub. +- **PSBT-centric**: signing flows go through PSBT (offline / air-gapped / multisig). +- **Multi-network**: mainnet, testnet, regtest. +- **GUI** (Avalonia) and **CLI** on the same core. +- **Multilingual**: Italian, English, Spanish, French, Portuguese, German. + +## Architecture + +``` +PalladiumWallet.sln +├─ src/Core/ Chain/ Crypto/ Wallet/ Spv/ Net/ Storage/ (no UI dependency) +├─ src/App/ Avalonia GUI +├─ src/Cli/ CLI on the same Core +└─ tests/ xUnit +``` + +Stack: **.NET 8 + Avalonia UI + NBitcoin**. + +--- + +## Development environment + +You only need the **.NET 8 SDK**. The core and crypto are fully testable without the GUI or a real network. + +### Windows + +1. Install the .NET 8 SDK: + ```powershell + winget install Microsoft.DotNet.SDK.8 + ``` + (alternatively, the installer from ) +2. Clone the repository and restore dependencies: + ```powershell + git clone + cd PalladiumWallet + dotnet restore + ``` + +### Linux + +1. Install the .NET 8 SDK through your distro's package manager, or without root via the official script: + ```bash + curl -sSL https://dot.net/v1/dotnet-install.sh | bash -s -- --channel 8.0 + export PATH="$HOME/.dotnet:$PATH" DOTNET_ROOT="$HOME/.dotnet" + ``` + (add the two `export` lines to your `~/.bashrc` to make them permanent) +2. Clone and restore: + ```bash + git clone + cd PalladiumWallet + dotnet restore + ``` + +> The GUI uses Avalonia, which runs natively on both platforms with no extra graphics dependencies. + +--- + +## Running it + +**GUI** (with hot reload for development): +```bash +dotnet watch --project src/App +``` +or a single run: +```bash +dotnet run --project src/App +``` + +**CLI** (same core, useful for scripts and headless environments): +```bash +dotnet run --project src/Cli -- +``` +Run without arguments for the full list of commands. + +--- + +## Running tests + +Tests are the **primary verification layer** — the core logic and crypto run headless, without the GUI or a real network. + +Run the whole suite: +```bash +dotnet test +``` + +Run a single test (or a group) by name: +```bash +dotnet test --filter "FullyQualifiedName~TestName" +``` + +Run only the tests in one project: +```bash +dotnet test tests/PalladiumWallet.Tests +``` + +> Cross-implementation tests compare addresses, txids and PSBTs against reference golden vectors: a different address or txid is a blocking bug. + +--- + +## Building + +**Development build:** +```bash +dotnet build +``` + +**Windows publish** (single self-contained executable): +```bash +dotnet publish src/App -r win-x64 -p:PublishSingleFile=true --self-contained +``` + +**Linux publish** (self-contained; the AppImage is then produced with [PupNet Deploy](https://github.com/kuiperzone/PupNet-Deploy)): +```bash +dotnet publish src/App -r linux-x64 --self-contained +``` + +The application **version** is set in a single place: the `` tag in [`src/App/PalladiumWallet.App.csproj`](src/App/PalladiumWallet.App.csproj). It appears in the window title and is stamped into the published binaries. + +--- + +## User guide (quick) + +### First launch +1. On first launch, choose **where to store data** (wallet, configuration, certificates) — the default path or a folder of your choice. +2. Create a new wallet, restore from seed, or open an existing wallet. +3. If you create a wallet, **write the seed phrase down on paper**: it will not be shown again. You can protect the file with a password. + +### Main tabs +- **History** — list of transactions. *Double-click* a row to open the full detail (amount, fee, addresses, sizes, confirmations). +- **Send** — recipient + amount (or "send all"), adjustable fee; for watch-only wallets a PSBT is produced to be signed offline. +- **Receive** — next unused address, with a **QR code** and a **Copy** button. +- **Addresses** — all derived addresses with balances; click for details (keys, derivation path). +- **Contacts** — address book with labels. + +### Connection +- The status indicator at the bottom shows the connection to the **indexing server**; tapping it opens the server settings. +- Sync is SPV: it downloads only what concerns your wallet and verifies every confirmed transaction with a Merkle proof. + +### Settings and Help +- **Settings**: language, display unit (PLM / mPLM / µPLM / sat), server. +- **Help**: software information and version. + +### CLI in brief +```bash +# Wallet +dotnet run --project src/Cli -- create [--words 12|24] [--kind segwit|wrapped|legacy] [--net mainnet|testnet|regtest] [--password P] +dotnet run --project src/Cli -- restore "" [...] +dotnet run --project src/Cli -- info [--net ...] [--password P] + +# Network +dotnet run --project src/Cli -- sync [--server host[:port]] [--ssl] +dotnet run --project src/Cli -- send --to ADDRESS (--amount X | --all) [--feerate sat/vB] [--broadcast] +``` +The default wallet file is `~/.palladium-wallet//wallets/default.wallet.json` (override with `--file`). + +--- + +## License + +Released under the MIT License. See the [LICENSE](LICENSE) file.