PalladiumWallet/CHANGELOG.md

Changelog

Technical changelog for PalladiumWallet. Format loosely follows Keep a Changelog; entries are grouped by subsystem rather than strictly by date, since 0.9.0 is the first release and covers the full history from the initial commit.

[1.1.0] — 2026-07-19

Adds a pure address-only watch-only mode (Core + CLI + App wizard + Send PSBT export), makes SPV sync render balance/history progressively instead of blocking on full Merkle verification, and fixes several Android sync-reconnect bugs found by testing the previous fix on a large wallet.

Added

• Pure watch-only wallets from one or more plain addresses, no extended key or private key material at all (unlike existing xpub/WIF imports, which can still derive/hold key material): WalletDocument.WatchAddresses
  • WalletLoader.NewFromAddresses, ScriptKind inferred from the address via DerivationPaths.KindFor, CLI restore-address command, and a matching setup-wizard step. TransactionFactory already refused to sign for any IsWatchOnly account, so the new address-only accounts inherit that guarantee for free.
• Send flow: base64 PSBT export box + copy button and a visible warning banner for watch-only accounts, so the unsigned PSBT built from a watch-only wallet can actually be taken elsewhere to sign (previously only the CLI printed it).
• Chinese (Simplified) as a 7th UI language (Loc.Strings/Languages); the Settings language picker is a hand-written RadioButton list, not generated from Loc.Languages, so IsLangZh was added to MainWindowViewModel.Settings.cs and MainView.axaml too.
• New mainnet checkpoint at height 475124 (ChainProfiles).

Changed

• SPV sync now renders balance/history as soon as transaction downloads finish instead of blocking on every historical Merkle proof — critical on mobile, where proof-checking can take much longer than the download. Proofs keep verifying in the background and each transaction's Verified flag catches up progressively; header ranges are fetched in batches (blockchain.block.headers) instead of one call per header. Coin selection (UtxoSpendability.IsSpendable) still refuses to spend a UTXO until its Merkle proof is actually checked, regardless of confirmation count — a server fabricating a confirmed balance can get it displayed early but never spent before the forgery is caught. The disk cache only ever persists the fully-verified end state. UI surfaces the new PendingVerificationSats/SpendableSats split with a "verifying..." badge.
• ElectrumClient's in-flight request cap (MaxInFlight, previously a hardcoded 32) is now an optional ConnectAsync parameter, since different indexing servers tolerate different concurrency before throttling.

Performance

• Checkpoint-anchoring state (_anchoredUpTo) is now persisted across sync sessions via SyncCache instead of being re-walked and re-verified from scratch on every app restart, even when the header bytes were already cached on disk — this dominated reconnect time on large wallets.

Fixed

• TransactionFactory.Build: sending a large amount from a wallet with many small UTXOs could produce a transaction over the standard 100 KvB relay limit, previously surfaced only as a cryptic Transaction's size is too high error after everything else had already succeeded. UTXOs are now ordered largest-first with a binary search for the smallest spendable prefix, naturally preferring big coins over dust; NBitcoin's own oversized-selection case is now recognized and translated into a clear, actionable error instead of being read as "insufficient funds".
• Android: a connection killed silently while the phone was locked (Doze, radio suspend, NAT timeout) still reported IsConnected == true because TcpClient.Connected only reflects the last known socket state, and the keep-alive ping's failure was swallowed by an empty catch — sync kept retrying on a dead socket instead of reconnecting. Fixed across two passes:
  • A failed keep-alive ping now tears down the client and reconnects; OnPause/OnResume on the Android activity force an immediate health check on resume instead of waiting for the 20s timer (itself liable to be suspended during Doze).
  • The keep-alive ping had no timeout, so a half-open TCP connection (the common outcome of a longer Doze suspend) left it awaiting a response that never arrives, so the teardown path was never reached — bounded to 8s, plus a re-entrancy guard against overlapping ticks.
  • Resume checking bailed out whenever a sync was already in progress, leaving a lock/unlock during an active sync hung indefinitely; it now cancels the stuck sync and tears down the dead client instead.
  • WalletSynchronizer.ExportCaches persisted raw transaction bytes only for already-verified transactions, discarding anything downloaded but not yet proof-verified when a sync was interrupted — forcing a full re-download on every resume of a large wallet. Confirmed txids are now tracked at download time, independent of verification status.
• Wizard/overlay TextBoxes (wizard steps, private-key prompt, wallet info overlay) shrank the whole panel when clicked into empty: their HorizontalAlignment="Center" + MaxWidth containers sized from content DesiredSize, and PlaceholderText only contributes to that measurement while empty and unfocused. Switched to HorizontalAlignment="Stretch", which sizes from the available arrange rect (clamped by MaxWidth) regardless of focus/placeholder state.
• Help overlay's Donate tab is now gated behind IsWalletOpen, like the rest of the wallet-only UI — it requires an open wallet to send from, so showing it earlier was a dead end.

Documentation

• USERGUIDE.md: documents why initial sync scales with transaction count rather than wallet age (one Merkle-proof round trip per confirmed transaction, no batching in the Electrum-style protocol), why later syncs are fast (cache persists proofs/headers/anchoring state), and warns against using this wallet as a mining payout address (many small transactions measurably slow sync).
• SECURITY.md: documents address-only watch-only wallets, and adds multisig to the explicit "known limitations" list (unsupported — derivation for it throws, not just unimplemented UI).
• README.md reconciled with current repo state: 7 UI languages (was 6, missing Chinese Simplified), watch-only described as xpub and address-only (was xpub-only), multisig no longer overclaimed as a working PSBT flow, CLI quick-reference includes restore-address and servers, links the new USERGUIDE.md.

[1.0.0] — 2026-07-09

First stable release. Closes the last open security gap from 0.9.x (header trust was not actually anchored to any checkpoint), fixes several crash paths found by a new fuzzing harness, and adds OP_RETURN/coinbase-tag decoding to the transaction detail view.

Security

• WalletSynchronizer.AnchorToCheckpointAsync: header trust is now actually anchored to ChainProfiles.Mainnet.Checkpoints (24 real [height, hash, bits] checkpoints pulled from a fully-synced node, every 20,000 blocks plus one near tip). Previously the checkpoint array was empty and the methods meant to enforce it (MatchesCheckpoint/IsValidChild) were never called — on this LWMA chain, where PoW can't be recomputed client-side, a malicious or eclipsing server could hand back any internally-consistent header for a Merkle proof with nothing tying it to the real chain. For every header used in a Merkle proof, the intervening headers are now downloaded back to the nearest checkpoint and verified as an unbroken prev-hash chain terminating in that checkpoint's exact hash (memoized per sync session). Testnet/Regtest remain unanchored (no node available to source checkpoints from); a missing checkpoint is a no-op, not a failure.
• New fuzzing harness (tests/PalladiumWallet.Fuzz, SharpFuzz-based): one target per untrusted-input parser (header, Merkle proof, peer list, wallet file, mnemonic/key/address/amount), each encoding that parser's documented error contract. Found and fixed:
  • Bip39.TryParse threw NotSupportedException on text resembling no wordlist instead of failing gracefully.
  • ElectrumApi.ParsePeers threw on any server.peers.subscribe response shape other than the expected [ip, hostname, [features...]], and on a JSON string containing invalid UTF-8.
  • EncryptedFile.Decrypt let a tampered/corrupted wallet file escape as raw JsonException/FormatException/ArgumentNullException instead of the documented WrongPasswordException/InvalidDataException contract; worse, the PBKDF2 iteration count was read from the (attacker-controlled) container with no upper bound — a tampered file demanding e.g. 2³¹ iterations would hang the wallet on open. Iteration count is now clamped to 10,000,000.
  • CertificatePinStore.Load: a corrupted pin file blocked every SSL connection until manually deleted; now falls back to first-contact TOFU like ServerRegistry already did.
  • The seed corpus (incl. a regression input per fixed finding) replays inside dotnet test via FuzzCorpusTests, so a fix can't silently regress.
• SECURITY.md corrected: PBKDF2 parameters (600,000 iterations / 16-byte salt, not the pre-hardening 100,000 / 32-byte), a stale file reference, and disclosure of the AI-assisted testing methodology used (adversarial fake-server simulation, property-based fuzzing, targeted security review) as a complement to, not a replacement for, independent review.

Added

• Transaction detail view now decodes OP_RETURN output payloads (UTF-8, or hex if the bytes aren't valid text — multiple OP_RETURN outputs in one tx are each decoded independently) and coinbase scriptSig pool tags (e.g. /slush/, extracted as printable-ASCII runs amid the binary BIP34 height/extranonce). Both were previously dropped entirely — discarded once no destination address could be derived from the script.
• Help overlay: "User guide" button next to "Report a bug", linking to USERGUIDE.md on GitHub.
• USERGUIDE.md: full end-user reference for GUI and CLI (wizard flows, script types, fees, gap limit, TOFU cert pinning, CLI commands) with the exact numbers the software enforces.

Fixed

• Send/Donate/Sync/Wizard view models wrote status/error strings directly in Italian regardless of the active language; routed through Loc with the missing keys added. CertificatePinMismatchException no longer bakes an Italian message into .Message — it exposes Host/Port for the UI to translate.
• CLI (src/Cli/Program.cs) printed all output in Italian regardless of the code/docs-are-English-only policy; translated every user-facing string and comment.

Testing

• Test suite expanded from 307 to 392 tests, closing coverage gaps in: checkpoint-anchoring (including the memoization and non-generic-retry branches), the PoW-checked branch of BlockHeaderInfo.IsValidChild (never run since every profile sets SkipPowValidation), all 8 BIP-39 wordlist languages plus the empty-input guard, SLIP-132 rejection of malformed/corrupted keys, TransactionFactory's standardness-policy rejection, ImportedKeyAccount's fund-safety fallbacks, WalletLoader's defensive branches for corrupted files, PalladiumNetworks.For/INetworkSet, AppPaths' full data-root precedence chain (via new internal override seams), UpdateChecker end-to-end via a stub-transport seam, and ElectrumClient's multi-segment response dispatch.
• OP_RETURN/coinbase-tag decoding covered: UTF-8 text, binary fallback to hex, multiple OP_RETURN outputs in one tx, pool-tag extraction, and the absence of false positives on standard outputs/inputs.

Documentation

• AGENTS.md/CLAUDE.md re-synced (had drifted) and reformatted from dense prose to scannable bullet lists; a stale SECURITY.md file reference fixed.
• README.md test-coverage section and SECURITY.md updated to describe the checkpoint anchoring and fuzzing guarantees actually enforced now.

[0.9.1] — 2026-07-02

Testing

• Test suite expanded from 239 to 307 tests; Core line coverage raised from ~50% to ~92% (branch coverage from ~41% to ~79%).
• In-process fake ElectrumX server (tests/.../Net/FakeElectrumServer.cs): a real loopback TCP socket speaking newline-delimited JSON-RPC 2.0, optionally TLS with a self-signed certificate, with per-method handlers and call counters — exercises the network stack against real socket code instead of mocks.
• New end-to-end coverage for previously untested network/SPV code: ElectrumClient (request pipelining, error mapping, notifications, disconnection, cancellation, TLS/TOFU handshake), WalletSynchronizer (gap-limit scanning, UTXO/history reconstruction, unconfirmed/immature balances, busy-retry, disk-cache reuse, and the security-critical path where a lying server fails Merkle verification and the sync aborts), TransactionInspector (fee calculation, mine/theirs attribution, RBF, coinbase handling), CertificatePinStore (TOFU pin/match/mismatch/reset), ServerRegistry peer discovery, and UpdateChecker tag parsing.
• TransactionFactory: added coverage for legacy/P2SH/segwit destinations, multi-UTXO selection, dust change absorbed into the fee, and a golden txid anchoring the PSBT signing path (deterministic via RFC 6979).
• Property-based tests extended: SLIP-132 roundtrip for every script kind and network, WalletDocument JSON roundtrip with arbitrary labels/contacts, Scripthash cross-checked against an independent SHA-256 computation.
• update-version.sh: single script to bump the version across the project ahead of a release tag.

Fixed

• CertificatePinStore.Load: a corrupted pin file threw and blocked every SSL connection until the user manually deleted it; now falls back to first-contact TOFU, same as ServerRegistry already did for its own file.
• EncryptedFile.IsEncrypted: threw on valid JSON with a non-object root (e.g. a bare number or array) or on invalid UTF-16 input, instead of returning false. Both bugs were found by the expanded property tests.

Documentation

• README.md: "Running tests" section rewritten with a per-area coverage table, the coverage-measurement command, and a description of the fake ElectrumX server.
• CLAUDE.md/AGENTS.md kept in sync, pointing future work at extending the fake ElectrumX server instead of mocking ElectrumClient (not an interface, by design).

[0.9.0] — 2026-07-02

First release. SPV wallet (Sparrow-style) for the Palladium (PLM) network — Bitcoin-derived UTXO chain — targeting desktop (Windows/Linux) and Android from a single Avalonia UI codebase on .NET 10 + NBitcoin.

Core — Chain

• Network profiles and consensus constants centralized in Core/Chain (ChainProfiles/PalladiumNetworks): address prefixes, BIP32 headers, bech32 HRP, genesis, ports, coin_type 746 — selectable per network (mainnet/testnet/regtest), no scattered magic numbers.
• LWMA difficulty / 2-minute blocks: SPV cannot recompute LWMA retargeting, so PoW validation is skipped and trust is anchored to hardcoded checkpoints instead.

Core — Crypto

• HD key derivation: BIP32/39/84, HD accounts, SLIP-132 extended key serialization.
• Address types: P2PKH, P2SH-P2WPKH, and P2TR (Taproot/BIP86).
• IWalletAccount abstraction with WIF/xpub/xprv keystore import (including watch-only accounts from public material only).

Core — Net

• Custom ElectrumClient: JSON-RPC 2.0 client for the ElectrumX-like indexing server, with TLS support and TOFU certificate pinning.
• ServerRegistry: bootstrap server list, peer discovery, persisted last-used server, fallback resolution for --server.
• Batched writes, zero-allocation reads, bounded in-flight requests for network throughput.
• Fix: allow changing the indexing server at any time, including during an active sync.

Core — Spv

• Header sync with Merkle proof verification and scripthash subscriptions against hardcoded checkpoints (no full PoW recomputation, per the chain profile above).
• Per-address balance and transaction-count aggregation in sync results.
• Electrum-style continuous updates: incremental, parallelized sync across address chains, with a persistent header cache.
• Fix: resilient sync — history discovery via GetHistory, transaction caching, automatic reconnect fallback.

Core — Storage

• Versioned, encrypted JSON wallet file (WalletDocument) with dedicated persistence and loader layer.
• WalletLock: prevents concurrent access to the same wallet file; acquired before load and before close (fixed a race where it wasn't).
• XDG-compliant data paths (AppPaths) with per-platform override seam used by the Android head; English as default UI language.
• Contacts list (name + address) persisted in WalletDocument.
• Documented caveat: WalletStore.Save writes plaintext JSON when the wallet is unencrypted — seed/keys are only ever encrypted-at-rest when the user opts into a password.

Core — Wallet

• Coin selection, PSBT-centric transaction factory, and wallet loader.
• Confirmation-threshold enforcement before spending UTXOs; immature (coinbase) balance surfaced separately from confirmed balance; pending mempool balance shown, with unconfirmed UTXOs excluded from spending by default.
• Fix: reject amounts with sub-satoshi precision.

App — Avalonia UI (shared, src/App)

• Single shared MainView (UserControl) hosted by MainWindow on desktop and as the single-view root on Android; single MainWindowViewModel (CommunityToolkit.Mvvm), later split into partial files by area (Wizard/Settings/Sync/Send/Contacts/Receive/...).
• Step-by-step setup wizard (replacing a single-form panel), including a first-run data-location step, multi-wallet chooser, confirm-password and encrypt toggle, and dedicated flows for creating a wallet vs. importing from xpub/xprv/WIF.
• In-app overlay pattern for details/settings/help (IsXxxOpen flags, no OS windows) replacing earlier nested submenus and a separate AddressInfoWindow: server settings, app settings (language/unit), wallet info (xpub, password-gated seed reveal), address detail (password-gated private key reveal), transaction detail with full on-chain data (inputs/outputs, no truncation), and a Help overlay (Info/Donate tabs).
• Connection-status indicator in the bottom bar; connect-before-wallet-open flow; persisted last-used server; server discovery split into its own always-usable button; mainnet hardcoded (network selector removed for the first release).
• Localization: Loc key → 6-language dictionary (it/en/es/fr/pt/de) with live language switching.
• Receive: QR code generation and copy-to-clipboard for the receive address.
• Android: QR code scanner for the Send address field.
• Centralized design system (color tokens, gradient hero, SVG tab icons); responsive layout for portrait mobile, unified tab bar (desktop + mobile), two-column desktop layout for Send/Receive; various mobile-only fixes (tab bar sizing/indicator overlap, text overflow, full-screen server overlay on mobile).
• App version shown in window title and Help overlay, read from the single <Version> source in the App csproj.
• In-app update check: compares the running version against the latest GitHub release tag on startup and shows an overlay with the new tag when one is available (best-effort — silent on network/parse failure).
• In-app bug-report button (Help overlay) opening a pre-filled GitHub issue template; issue/PR templates completed.

Android head (src/App.Android)

• Architecture split: shared UI library (src/App) + src/App.Desktop + src/App.Android heads from the same source (refactor(arch)), each carrying only the per-platform entry point and packages.
• App logo as launcher icon.
• Persistent release-signing keystore workflow (docker/keystore/generate-keystore.sh, git-ignored output): every release APK is signed with the same key so installing a newer build updates a previous install in place instead of requiring an uninstall. versionCode derived from <Version> instead of a fixed constant.

CLI (src/Cli)

• Commands: create/restore/restore-xpub/info, sync/send/servers/reset-certs, newseed/addresses.
• servers command, info --addresses, and registry-based fallback resolution for --server.

Build & Distribution

• Docker-based reproducible build system (docker/build.sh + docker/Dockerfile.*): pinned toolchain (.NET 10 SDK, JDK, Android SDK), builds Windows/Linux single-file executables and a signed Android APK without any SDK installed on the host.
• Android release signing wired into build_android (see Android head above): requires the persistent keystore, prompts for its passwords at build time, mounts it read-only into the build container.

Testing

• Unit test coverage across all Core modules, later expanded to 209 tests.
• Property-based tests via CsCheck (PropertyTests.cs), bringing total coverage to 218 tests; dedicated WalletLock concurrency tests.

Documentation

• README.md (project overview, quickstart, reproducible builds), CLAUDE.md (codebase guidance for AI tooling, kept in sync with the multi-head architecture and .NET 10 migration), SECURITY.md (threat model and SPV trust assumptions), coding-agent guide.
• Code comments translated to English project-wide, per the language policy (Italian conversation, English code/docs).