davide/PalladiumWallet
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: davide/PalladiumWallet:data-dev
davide/PalladiumWallet:main davide/PalladiumWallet:data-dev
davide/PalladiumWallet:1.2.0 davide/PalladiumWallet:1.1.0 davide/PalladiumWallet:1.0.0 davide/PalladiumWallet:0.9.1 davide/PalladiumWallet:0.9.0
..
compare: davide/PalladiumWallet:1.2.0
davide/PalladiumWallet:main davide/PalladiumWallet:data-dev
davide/PalladiumWallet:1.2.0 davide/PalladiumWallet:1.1.0 davide/PalladiumWallet:1.0.0 davide/PalladiumWallet:0.9.1 davide/PalladiumWallet:0.9.0
164 Commits
data-dev .. 1.2.0
Author SHA1 Message Date
davide 5d5ed094a0 chore: release 1.2.0
CI / Test (ubuntu-latest) (push) Canceled after 0s
Details
CI / Test (windows-latest) (push) Canceled after 0s
Details
CI / Fuzz smoke (address) (push) Canceled after 0s
Details
CI / Fuzz smoke (bip39) (push) Canceled after 0s
Details
CI / Fuzz smoke (coinamount) (push) Canceled after 0s
Details
CI / Fuzz smoke (encfile) (push) Canceled after 0s
Details
CI / Fuzz smoke (header) (push) Canceled after 0s
Details
CI / Fuzz smoke (merkle) (push) Canceled after 0s
Details
CI / Fuzz smoke (peers) (push) Canceled after 0s
Details
CI / Fuzz smoke (slip132) (push) Canceled after 0s
Details
CI / Fuzz smoke (walletdoc) (push) Canceled after 0s
Details
CI / Docs checks (push) Canceled after 0s
Details 
Bump version to 1.2.0 (Android versionCode 5) and write the 1.2.0 changelog.
 2026-11-03 21:54:03 +01:00
davide ed8de06609 test: wait for verified history rows before asserting on them 
The funded-wallet ViewModel tests only waited for the history row to
appear, but the Merkle proof can complete after sync reports idle. On the
slower Windows runner the assertions on Verified and the spend tests (which
need verified UTXOs) raced it and failed. Wait for the row to be verified.
 2026-11-03 21:19:36 +01:00
davide 9010ebce59 feat(spv): cross-check recent headers with a witness server 
Blocks above the newest checkpoint cannot be anchored, so the header from
the primary server is now compared with the one from a second server taken
from the hardcoded bootstrap list. A disagreement at 3+ blocks of depth
aborts the sync; a shallower one leaves the proof unverified until the next
sync; with no reachable witness behaviour is unchanged. A bounded
proof-of-work check was evaluated and rejected. See ADR 0042.
 2026-11-03 15:29:29 +01:00
davide 305f22ed0e feat(app): flag transactions above the newest checkpoint as not anchored 
Blocks mined after the newest hardcoded checkpoint cannot be chained to it,
so only the Merkle proof against the server's header backs them. The
history list and the transaction detail now show a 'not anchored' label
for those transactions. Informational only: spending is not blocked.
See ADR 0041.
 2026-11-03 15:11:06 +01:00
davide 24368a07b5 test: run async UI test bodies to completion 
Avalonia's Dispatch(Func<Task>) returns at the first real await, so the
assertions after it never ran and async ViewModel tests passed vacuously.
UiSession.Run now drives the body to completion while pumping the
dispatcher. The test profile has no checkpoints, since the fake chains use
tiny heights that the real mainnet checkpoints would try to anchor.
 2026-11-03 15:11:06 +01:00
davide a08e972c4c docs: state that the GUI is mainnet-only 
The README advertised mainnet, testnet and regtest without saying that
only the CLI can use the test networks, which also ship without bootstrap
servers or checkpoints.
 2026-11-03 14:58:56 +01:00
davide 4e3d93e167 fix(spv): anchor headers up to a checkpoint above them 
With proof of work skipped, chaining headers from a checkpoint up to a
transaction's block proves nothing: a server can fabricate a header and
fake headers after a real checkpoint. The header must now hash-chain up to
the nearest checkpoint at or above its height, whose hash is hardcoded.
This also anchors heights below the first checkpoint. The cached anchor
state is renamed AnchoredDownTo and caches without it are re-verified
once. Blocks above the newest checkpoint remain a documented limit.
See ADR 0040.
 2026-11-03 14:52:29 +01:00
davide c8ba2294f2 feat(app): suggest fee rates from the server and enforce the relay fee 
After connecting, the Send tab offers Fast/Normal/Economy rates from the
server's fee estimates (never below the relay fee, implausible values
ignored). A manual rate below the relay fee is refused before building and
a fee above 1% of the amount is flagged in the preview. See ADR 0039.
 2026-11-03 14:33:32 +01:00
davide 92fd783658 feat(cli): read the wallet password from env, stdin or a prompt 
The password no longer has to be a command-line argument: it can come from
--password-env, --password-stdin or a no-echo prompt (--password still works
but warns). Plaintext storage is now an explicit opt-in (--no-encryption)
instead of the result of a forgotten flag. See ADR 0038.
 2026-11-03 14:21:58 +01:00
davide eca4d4ac0c fix(app): validate contact addresses when saving 
Adding a contact now checks the address against the wallet's network and
rejects duplicates; whitespace in a pasted address is removed. Before, any
string was stored and the error only surfaced at send time.
 2026-11-03 14:15:03 +01:00
davide 06d1f59c2b fix(app): derive an address private key only when revealed 
Address rows and the address detail sheet no longer carry the WIF of
every listed address for the whole session. The key is derived after the
password gate and dropped when hidden, when the sheet closes or when the
wallet closes. See ADR 0037.
 2026-11-03 14:10:58 +01:00
davide 8bcee27c23 feat(spv): verify the chain identity of a server on connect 
After the handshake the wallet checks server.features genesis_hash and,
when the profile has checkpoints, the header at the highest checkpoint
not above the server's tip (mainnet shares Bitcoin's genesis, so the
checkpoint is what tells the chains apart). A server on another chain is
refused with WrongChainException and the next candidate is tried. Used by
the GUI, peer discovery, the CLI and the server probe. See ADR 0036.
 2026-11-03 14:01:34 +01:00
davide 77f00d1b4e test: raise the thread pool minimum to avoid starvation 
Property tests saturate the pool while network tests wait on continuations,
so a loopback handshake could exceed its timeout and fail the run
intermittently. A higher floor removes the starvation.
 2026-11-03 13:52:49 +01:00
davide 65c515bf7a fix(net): cap the length of a server line 
A hostile server could stream an endless line with no newline and exhaust
the client's memory. A single reply is now capped at 16 MiB (configurable
via maxLineBytes in ConnectAsync); on excess the connection fails with
InvalidDataException. See ADR 0035.
 2026-11-03 13:52:49 +01:00
davide 3be761d97e fix(net): bound every request with a timeout 
A server that stops answering without closing the socket left a running
sync waiting forever. Requests now fail with TimeoutException after 30 s
(10 s for the handshake, both configurable in ConnectAsync) and the
connection is marked dead so the app reconnects. See ADR 0034.
 2026-11-03 12:18:39 +01:00
davide cb551efce4 fix: parse fee rate with the invariant culture 
On Italian/German systems "1.5" was read as 15 sat/vB. The Send form,
the Donate form and the CLI now share CoinAmount.TryParseFeeRate
(invariant culture, '.' or ',' as decimal separator, range (0, 1000]).
Donate and the CLI report an invalid rate instead of silently using 1.
 2026-11-03 12:15:27 +01:00
davide d431996ddc docs: describe the extended test strategy 
ADR 0033, ADR 0032 update, README test section, agent rules and
changelog entry.
 2026-11-03 11:45:43 +01:00
davide d85c1e39ce ci: gate Core coverage and exclude test tooling from the report 
Coverage settings exclude the fuzz harness, server probe and test assembly;
CI fails if Core drops below 95% lines or 88% branches. The gitignore no
longer swallows tests/coverage.runsettings.
 2026-11-03 11:45:43 +01:00
davide 530b7feaa5 test(app): add headless ViewModel, CLI and localization tests 
ViewModels run on Avalonia.Headless: wizard flows, password and file-lock
handling, seed and private-key reveal gating, contacts, settings, sync and
send against the fake server. The CLI entry point is invoked in-process
end to end. Localization checks cover the 7 languages, placeholders and
keys used in sources. Internal seams (UpdateCheck, ProfileOverride) keep
the tests offline.
 2026-11-03 11:45:43 +01:00
davide 54d07f8e92 test(core): cover error paths, boundaries and concurrency 
Empty header range during checkpoint anchoring, send-all limits, SyncCache
roundtrip, corrupted config, derivation edge cases, spendability
boundaries, unit formatting, loader errors, in-flight cap, disposal under
load and wallet-lock contention. Also raises the synchronizer partial-result
timeouts so they hold under load.
 2026-11-03 11:45:43 +01:00
davide cb93927d15 fix(net): fail fast on a dead Electrum connection instead of hanging 
After a protocol error (e.g. a malformed line) the read loop ended but
the client still reported IsConnected and later requests waited forever
for a response that could never arrive. The read loop now marks the
connection closed before failing pending requests, and RequestAsync
throws IOException on a closed connection. Adds regression tests and a
raw-line helper to the fake server.
 2026-11-03 11:45:43 +01:00
davide 9c0a408c49 docs: record CI in ADR 0032 and mention it in README and agent rules 
Also update docs-as-code to reflect that the docs check now runs in CI.
 2026-11-03 09:49:51 +01:00
davide 928cb31cdf ci: run tests, fuzz smoke and docs checks on GitHub Actions 
Offline test suite on Ubuntu and Windows, a random-input fuzz smoke per
parser target, and docs/check-docs.sh on every push to main and PR.
 2026-11-03 09:49:51 +01:00
davide aec68ea047 docs(agents): require docs and ADR updates with every feature change 
Mirrored in CLAUDE.md and AGENTS.md per the sync rule.
 2026-11-03 09:45:51 +01:00
davide b292590cdc docs: add docs-as-code process and one ADR per feature 
docs/docs-as-code.md defines the workflow; docs/adr holds 31 ADRs
(retroactive, reconstructed from code and changelog) with a template and
index. docs/check-docs.sh validates ADR structure, index, cited code
paths, relative links and CLAUDE.md/AGENTS.md sync.
 2026-11-03 09:45:51 +01:00
davide ce8d777c63 chore: point repository URLs to palladium-coin/palladium-wallet 
Update checker, in-app issue/guide links, issue template config and
README clone instructions now use the new repository.
 2026-11-03 09:45:51 +01:00
davide 42e8dfdb63 test: add ServerProbe tool and opt-in live server test 
ServerProbe is a read-only conformance/health checker for Electrum
protocol servers (Fulcrum, ElectrumX): handshake/TLS, features and
genesis, header linkage, Merkle proof vs header root, fees, latency.
LiveServerTests runs it from dotnet test when PALLADIUM_TEST_SERVERS is
set. Also ignore .claude/, apk/aab and local.properties.
 2026-11-03 09:34:34 +01:00
davide 8ac4a05c44 feat(docker): add linux-arm64 reproducible build target 
Cross-published via the existing x64 desktop image (self-contained
publish doesn't need ARM hardware), for Raspberry Pi and other
64-bit ARM boards.
 2026-07-26 11:05:16 +02:00
davide 0d541d0fe3 chore(release): bump version to 1.1.0 
Fills in the CHANGELOG.md entry for the watch-only address-only import
mode, progressive Merkle verification, transaction size-limit fix, and
Android sync-reconnect fixes since 1.0.0, and bumps <Version>/versionCode
across the App and Android head csproj files ahead of the tag.
 2026-07-19 17:59:56 +02:00
davide 7057905d94 fix(ui): hide Donate tab in Help until a wallet is open 
The tab requires an open wallet to send from, so showing it before
one is loaded led to a dead end. Gate it behind IsWalletOpen, same as
the other wallet-only UI.
 2026-07-19 17:46:34 +02:00
davide 51f1af8786 fix(ui): stop wizard/overlay TextBoxes from resizing on focus 
Width-capped containers (wizard steps, private-key prompt, wallet info
overlay) used HorizontalAlignment="Center" with MaxWidth, which sizes
the panel from its content's DesiredSize. Since PlaceholderText only
contributes to that measurement while a TextBox is empty and
unfocused, clicking into an empty field shrank the whole panel.

Switch to HorizontalAlignment="Stretch": Avalonia's ArrangeCore sizes
Stretch from the available arrange rect (clamped by MaxWidth) instead
of DesiredSize, and centers the result exactly like Center alignment
does when MaxWidth caps it — so the box stays a fixed width regardless
of focus/placeholder state, on both desktop and Android.
 2026-07-19 17:44:01 +02:00
davide 4cd5fab736 fix(sync): bound keep-alive ping and resume a sync stuck on lock/unlock 
Three issues surfaced by testing the previous lock/unlock reconnect fix
on Android with a large wallet:

- The keep-alive ping had no timeout, so a "half-open" TCP connection
  (remote end gone with no FIN/RST ever delivered, the common outcome
  of Doze/mobile-radio suspend after a longer lock) left it awaiting a
  response that never arrives — the failure path that tears the dead
  client down was never reached. Bound the ping to 8s and added a
  re-entrancy guard so overlapping 20s ticks can't pile up concurrent
  reconnect attempts while one is stuck.

- CheckConnectionOnResumeAsync bailed out whenever a sync was already
  in progress, so a lock/unlock during an active sync (which has no
  per-request timeout of its own) left it hung indefinitely instead of
  recovering. It now cancels the stuck sync and tears down the dead
  client, marking the interruption as self-inflicted (_resumeRecovering)
  so the UI shows "reconnecting" and restarts immediately instead of a
  transient error message.

- WalletSynchronizer.ExportCaches persisted raw transaction bytes only
  for already-verified transactions, discarding anything downloaded but
  not yet through Merkle-proof verification when a sync was interrupted
  mid-way — forcing a full re-download of a large wallet's transactions
  on every resume instead of resuming straight into proof verification.
  Track confirmed txids at download time (_confirmedTxids), independent
  of verification status, and export/preload against that instead.

Also unified the three sync progress messages onto one template
reporting against the sync's total transaction/proof counts rather than
this session's download count, so a resumed sync immediately shows
"transactions n/n" instead of a misleading "0/0" before jumping into
proof verification.
 2026-07-19 17:43:31 +02:00
davide 94a474fe41 fix(sync): recover connection after Android screen lock/unlock 
TcpClient.Connected only reflects the last known socket state, so a
connection killed silently while the phone was locked (Doze, mobile
radio suspend, NAT timeout) still reported IsConnected == true. The
keep-alive ping's failure was swallowed by an empty catch, so the
stale "connected" state never cleared and sync kept retrying on a
dead socket instead of reconnecting.

Treat a failed keep-alive ping as a disconnect (tear down the client
and reconnect), and add OnPause/OnResume to the Android activity to
force an immediate health check on resume instead of waiting for the
20s timer, which may itself be suspended during Doze.
 2026-07-19 16:01:18 +02:00
davide bbed21e820 docs: reconcile README/SECURITY with current repo state 
README.md was out of date after several recent features: it listed 6
UI languages (missing Chinese Simplified), described watch-only as
xpub-only (address-only import also exists), overclaimed multisig as a
working PSBT flow (derivation for it actually throws — not
implemented), and its CLI quick-reference omitted restore-address and
servers. Also links the new USERGUIDE.md, previously unreferenced from
README.

SECURITY.md's "known limitations" list didn't mention multisig is
unsupported, worth stating explicitly since it's fund-safety adjacent.
 2026-07-19 12:59:15 +02:00
davide 06f512e2f7 docs(userguide): document first-sync timing and warn against mining payouts 
Explains 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) and why it's slower on mobile,
plus why later syncs are fast (cache persists proofs/headers/anchoring
state). Advises against using this wallet as a mining payout address:
the many small transactions typical of payouts make sync noticeably
slower (observed ~2 minutes past 5,000 transactions).
 2026-07-19 12:59:02 +02:00
davide 5bb94c071f Merge branch 'watch-only' 
Adds a pure address-only watch-only wallet mode (Core + CLI + App wizard
+ Send UI), on top of the existing xpub/xprv/WIF import flows which are
unchanged. TransactionFactory already refuses to sign for any IsWatchOnly
account, so the new address-only accounts inherit that guarantee for free.
 2026-07-19 12:44:51 +02:00
davide 11b6a9a9ab docs(security): document address-only watch-only wallets 
Keeps the key-management section of the threat model accurate for the
new restore-address / pure address import path (SECURITY.md must stay
in sync with any change to key/seed handling per project convention).
 2026-07-19 12:39:52 +02:00
davide 9b00002e39 feat(app): label watch-only send flow and export unsigned PSBT 
Send already refused to enable Confirm for watch-only accounts (Signed
false), but the App had no way to get the resulting PSBT out to sign
elsewhere — only the CLI printed it. Adds a base64 PSBT box + copy button
in the Send summary card, and a visible warning banner explaining the
wallet cannot sign, on both desktop and mobile layouts.
 2026-07-19 12:39:28 +02:00
davide f0fb5bfcc6 feat(app): add watch-address import step to setup wizard 
New wizard flow mirroring the existing xpub/WIF import steps: paste one
or more plain addresses (no key material at all) and go straight to the
password step, since there is no derivation and no script-type ambiguity
to resolve for a fixed address list.
 2026-07-19 12:38:58 +02:00
davide 9fa5440ae5 feat(cli): add restore-address command for pure address watch-only 
Parallels restore-xpub but for one or more plain addresses with no
extended key and no private key — output is explicitly labelled
"cannot sign" since the resulting wallet can never produce a signed tx.
 2026-07-19 12:38:11 +02:00
davide 214abd2892 feat(core): support pure watch-only address import 
Adds a WalletDocument.WatchAddresses field and WalletLoader.NewFromAddresses
to build an ImportedKeyAccount with no private key at all (unlike xpub/WIF
imports, which can still derive/hold key material). ScriptKind is inferred
from the address itself via a new DerivationPaths.KindFor helper. Signing
already refuses to run for any IsWatchOnly account (TransactionFactory), so
this only had to wire up construction/reload of the new account shape.
 2026-07-19 12:37:31 +02:00
davide 6d05a88073 perf(net): make ElectrumClient's in-flight request cap configurable 
MaxInFlight was a hardcoded constant (32); different indexing servers
tolerate different levels of request concurrency before throttling, so
expose it as an optional ConnectAsync parameter instead of requiring a
recompile to tune initial-sync throughput against a given server.
 2026-07-19 12:16:18 +02:00
davide d9dd05aa52 perf(spv): persist checkpoint-anchoring state across sync sessions 
_anchoredUpTo tracked which heights were already proven to hash-chain
back to a checkpoint, but only in memory: every app restart re-walked
and re-verified the whole header chain from the checkpoint even when
the header bytes themselves were already cached on disk, dominating
reconnect time on large wallets. Round-trip it through SyncCache like
the other sync caches (RawTxHex/VerifiedAt/BlockHeaders).
 2026-07-19 12:16:00 +02:00
davide b6440484c1 feat(app): add Chinese (Simplified) as a 7th UI language 
Translate every key in Loc.Strings and register "zh" in Loc.Languages
/LanguageNames. Wire it into the Settings language picker, which is a
hand-written RadioButton list (not generated from Loc.Languages), so
add IsLangZh to MainWindowViewModel and the matching button in
MainView.axaml. Update CLAUDE.md/AGENTS.md language count and note the
non-dynamic picker to avoid the same gap next time.
 2026-07-18 12:06:31 +02:00
davide 1a4fefadc3 fix(wallet): keep transactions under the standard 100 KvB relay limit 
Sending a large amount from a wallet with many small UTXOs could
produce a transaction over the standard relay size limit, surfaced
only as a cryptic "Invalid transaction: Transaction's size is too
high" from builder.Verify() after everything else had already
succeeded — with no way for the user to recover other than manually
picking fewer coins.

Build() now orders spendable UTXOs largest-first and binary-searches
the smallest prefix of them that produces a valid transaction, so it
naturally prefers big coins over dust and avoids the limit whenever a
smaller input set can cover the amount. NBitcoin's own coin selector
already refuses to assemble a combination over the size cap and
reports it via NotEnoughFundsException with a distinctive message
rather than ever handing back an oversized transaction, so that case
is now recognized and translated into a clear, actionable error
instead of being read as "insufficient funds".
 2026-07-17 19:44:41 +02:00
davide 3460e53b4f feat(spv): verify Merkle proofs progressively, gate spendability on it 
Balance/history now render as soon as tx downloads finish instead of
blocking on every historical Merkle proof, critical for mobile where
proof-checking can take much longer than the download itself. Proofs
continue to be checked in the background and each tx's Verified flag
catches up progressively; header ranges are now fetched in batches
(blockchain.block.headers) instead of one call per header to keep this
fast over high-latency links.

Coin selection (UtxoSpendability.IsSpendable) refuses to spend a UTXO
until its Merkle proof is actually checked, regardless of confirmation
count, so a server that fabricates 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 of a sync.

UI surfaces the new PendingVerificationSats/SpendableSats split with a
"verifying..." badge, and the sync save now runs off the UI thread to
avoid freezing on slower hardware.
 2026-07-17 19:43:18 +02:00
davide feb765663c chore(chain): add mainnet checkpoint at height 475124 2026-07-17 15:14:24 +02:00
davide 322ce8f305 chore(release): bump version to 1.0.0 
Fills in the CHANGELOG.md entry for the checkpoint-anchoring security fix,
fuzzing infrastructure and its findings, OP_RETURN/coinbase-tag decoding,
and localization fixes since 0.9.1 (see previous commits), and bumps
<Version>/versionCode across the App and Android head csproj files ahead
of the tag.
 2026-07-17 14:02:52 +02:00
davide 077835a30b feat(wallet): decode OP_RETURN payloads and coinbase pool tags in tx details 
Transaction detail view silently dropped OP_RETURN messages and coinbase
scriptSig text (e.g. pool tags), since TransactionInspector discarded
scriptPubKey/scriptSig bytes once no destination address could be derived.
Each output/input is decoded independently, so multiple OP_RETURN outputs
in one tx are all shown.
 2026-07-09 08:35:39 +02:00
davide 663460d62e feat(ui): add user guide button to help overlay 
Adds a "User guide" button next to "Report a bug" in the Help > Info
tab, linking to USERGUIDE.md on GitHub via the same Launcher pattern
used for bug reports and release pages.
 2026-07-07 22:35:19 +02:00
davide be818a50a8 docs: tighten CLAUDE.md/AGENTS.md formatting for scannability 
Convert dense prose paragraphs to bullet lists (Commands, Architecture,
GUI conventions, Working rules) and trim redundant wording; no content
removed. Both files kept in sync per the header sync rule.
 2026-07-07 22:29:46 +02:00
davide 6f4ae679e5 docs: document fuzzing infrastructure and its security guarantees 
Sync AGENTS.md/CLAUDE.md with the fuzzing workflow, add a README section
pointing to tests/PalladiumWallet.Fuzz, and record in SECURITY.md the two
guarantees the fuzz suite enforces: a bounded PBKDF2 iteration count on read
and a typed InvalidDataException for any malformed encrypted container.
 2026-07-07 22:06:45 +02:00
davide cdede17683 feat(fuzz): add SharpFuzz-based fuzzing for untrusted-input parsers 
New tests/PalladiumWallet.Fuzz project: one target per parser that
consumes untrusted input (block headers, Merkle proofs, peer lists,
wallet files, user-pasted mnemonics/keys/addresses/amounts), each
encoding the parser's documented error contract - any exception beyond
that contract is a finding, reported as a crash.

Three ways to run: the seed corpus (with regression inputs for every
crash found so far, including the two fixed in prior commits) replays
automatically inside dotnet test via FuzzCorpusTests, so a fixed
contract violation can't silently return; a built-in random-mutation
mode needs no external tooling (dotnet run -- <target> --random N);
and fuzz.sh drives real coverage-guided campaigns via afl++ +
SharpFuzz instrumentation for pre-release or post-parser-change runs.
 2026-07-07 22:05:38 +02:00
davide a264669151 fix(storage): EncryptedFile.Decrypt must reject malformed containers cleanly 
A tampered or corrupted wallet file could reach Decrypt with broken
JSON, missing fields, invalid base64, or a wrong nonce/tag size, all of
which previously escaped as raw JsonException/FormatException/
ArgumentNullException instead of the documented WrongPasswordException/
InvalidDataException contract. Worse, the iteration count is read
straight from the (attacker-controlled) container with no upper bound:
a tampered file demanding e.g. 2^31 PBKDF2 iterations would hang the
wallet at open - a DoS via a file the user merely tries to open. Now
every malformed shape maps to InvalidDataException and the iteration
count is clamped to a sane maximum (10,000,000, well above the current
600,000 default).
 2026-07-07 22:05:08 +02:00
davide d9c75eaec2 fix(net): ParsePeers must tolerate any JSON shape from the server 
server.peers.subscribe is attacker-controlled data: ParsePeers assumed
the standard [ip, hostname, [features...]] shape and threw on anything
else (non-array response, wrong element types), and GetString() on a
JSON string containing invalid UTF-8 bytes threw InvalidOperationException
instead of failing to parse — both found by fuzzing. Any unexpected
shape or unparseable string now degrades to "no usable data" instead of
propagating an exception into the sync/discovery path.
 2026-07-07 21:52:00 +02:00
davide c868c17505 fix(crypto): Bip39.TryParse must not throw on unrecognisable text 
Wordlist.AutoDetect lands on NBitcoin's internal "Unknown" language for
text resembling no wordlist and throws NotSupportedException instead
of failing gracefully — found by fuzzing the restore-mnemonic input.
TryParse now treats that (and the same failure mode from the Mnemonic
constructor) as "not a valid mnemonic", consistent with every other
rejection path.
 2026-07-07 21:51:31 +02:00
davide d8917fbd9a docs: sync test-coverage description with the expanded suite 
README's "what the suite covers" table and the CLAUDE.md/AGENTS.md test
seam notes were written before this round of coverage work (checkpoint
anchoring, PoW branch, wordlists, corrupted-key rejection, the
UpdateChecker/AppPaths seams, ...). Updated both to describe what is
actually tested now, including the two new internal seams so future
contributors reach for them instead of re-inventing or skipping
coverage of UpdateChecker/AppPaths.
 2026-07-07 16:26:35 +02:00
davide 413392f608 test(storage): exercise AppPaths' full data-root precedence chain 
DefaultDataRoot, the pointer-file location and the portable-mode root
all read machine-global locations (APPDATA, AppContext.BaseDirectory),
so the override→portable→pointer→default precedence in DataRoot/
IsDataLocationConfigured was previously untestable beyond the override
case. Added three internal overrides (BootstrapDirOverride,
PortableBaseOverride, DefaultRootOverride) as sandboxing seams, and a
new AppPathsResolutionTests class covering every precedence branch:
default-only, portable-beats-pointer, pointer-beats-default, a blank
pointer falling back to default, "already has data" counting as
configured, and override beating everything. Both AppPaths test
classes share the "AppPaths" xUnit collection since this state is
static.
 2026-07-07 16:26:20 +02:00
davide 970253cbbe test(net): exercise UpdateChecker.CheckAsync end-to-end via a stub transport 
CheckAsync built its own HttpClient inline, so nothing beyond tag
parsing was testable without hitting the real GitHub API. Added an
internal CheckAsync(currentVersion, HttpMessageHandler, ct) overload
(the public method now delegates to it) as a seam for a stub handler,
and tests for the full best-effort matrix: newer/equal/older/unparseable
tag, missing html_url, HTTP error status, malformed JSON, a thrown
HttpRequestException, and an unparseable local version — all of which
must resolve to null or the correct LatestRelease, never throw.
 2026-07-07 16:26:06 +02:00
davide 31012ce825 test(net): cover ElectrumClient's multi-segment response dispatch 
DispatchLine's ArrayPool-copy path (for a JSON-RPC line spanning
multiple PipeReader segments) only ran for small responses in existing
tests, which stay single-segment. A 256 KB fake response forces the
multi-segment branch and verifies the payload still arrives intact.
 2026-07-07 16:25:50 +02:00
davide a46f5e6638 test(wallet): cover WalletLoader's defensive branches for corrupted files 
ToAccount's InvalidDataException paths (corrupted mnemonic/xprv/xpub,
a document with no key material at all) and the equivalent guards in
NewFromXpub/NewFromXprv/NewFromWif had no coverage — these are the
checks that turn a damaged wallet file into a clear error instead of
an unhandled exception or, worse, a silently wrong account.
 2026-07-07 16:25:37 +02:00
davide 61ed0c0ed0 test(chain): cover PalladiumNetworks.For and the INetworkSet plumbing 
The out-of-range throw in For(NetKind) and the entire
PalladiumNetworkSet class (CryptoCode, the three network getters,
GetNetwork including its throw for an unrecognised ChainName) had no
coverage.
 2026-07-07 16:25:23 +02:00
davide 9097ca4abc test(crypto): cover Bip39 empty input and all 8 wordlist languages 
TryParse's empty/whitespace/null guard had no test, and ToWordlist's
language map was only exercised for English and Spanish even though
USERGUIDE §2.1 documents all 8 languages as supported on restore.
Also covers the ArgumentOutOfRangeException for a language outside
the enum.
 2026-07-07 16:25:10 +02:00
davide 2ed8c04064 test(crypto): cover Slip132 rejection of malformed and corrupted keys 
TryDecodePublic/TryDecodePrivate return false on several inputs that
weren't exercised: well-formed Base58Check with a payload that isn't
78 bytes, and a correct SLIP-132 header with a corrupted key body
(bad pubkey point prefix / bad private-key padding byte) — both must
fail cleanly inside the try/catch, not throw.
 2026-07-07 16:24:56 +02:00
davide 56135c29f8 test(wallet): cover TransactionFactory's standardness-policy rejection 
builder.Verify's failure branch (the safety net right before a signed
tx would be returned to the caller) had no test: an absurd fee rate
now proves the "Invalid transaction: ..." path fires instead of
silently returning a policy-violating transaction.
 2026-07-07 16:24:42 +02:00
davide 5d74038aad test(wallet): cover ImportedKeyAccount edge cases and fund-safety fallbacks 
Empty entry list rejection, GetPublicKey boundaries (mirroring the
existing GetPrivateKey tests), and explicit assertions that change and
out-of-range indices always fall back to the first imported address —
never to an address the wallet doesn't hold keys for.
 2026-07-07 16:24:28 +02:00
davide db5b65ca0d test(spv): cover checkpoint-anchoring memoization and the non-generic retry path 
Two branches of WalletSynchronizer had no coverage: the early-return in
AnchorToCheckpointAsync when a range is already memoized (a second sync
with a tx below the previously-anchored height must not re-walk the
header chain), and the void RetryOnBusyAsync overload used by the
transaction-download tasks (only the generic <T> overload, exercised by
get_history, had a test).
 2026-07-07 16:24:11 +02:00
davide 45f7b1401e test(spv): cover the PoW-checked branch of BlockHeaderInfo.IsValidChild 
Every configured ChainProfile sets SkipPowValidation=true, so the
hash<=target branch (taken only when a future profile disables the
skip) had never run in the suite. Added a genesis-hash-satisfies-target
case and a tampered-bits case that pushes the target below the hash.
 2026-07-07 16:23:58 +02:00
davide e349a80ddc feat(spv): anchor header trust to hardcoded mainnet checkpoints 
ChainProfiles.Mainnet.Checkpoints was an empty array with a "populate
before release" TODO, and even BlockHeaderInfo.MatchesCheckpoint()/
IsValidChild() — the methods meant to enforce it — were never called
anywhere in WalletSynchronizer. So on this LWMA chain, where PoW can't
be recomputed client-side (SkipPowValidation), a malicious or
eclipsing server could hand back any internally-consistent 80-byte
header for a Merkle proof: nothing tied it to the real Palladium
chain.

Populated Mainnet.Checkpoints with 24 real [height, hash, bits]
checkpoints (every 20,000 blocks + one near tip), pulled via RPC from
a fully-synced palladiumd. Testnet/Regtest are left empty (no node
available to verify against, and WalletSynchronizer already treats a
missing checkpoint as a no-op, so this is safe, just unanchored).

Added WalletSynchronizer.AnchorToCheckpointAsync: for every header
used in a Merkle proof, downloads the intervening headers back to the
nearest checkpoint at or below that height and verifies an unbroken
prev-hash chain terminating in the checkpoint's exact hash, finally
wiring up the previously-dead MatchesCheckpoint/IsValidChild. Verified
ranges are memoized in-memory per sync session to avoid re-walking.

Updated SECURITY.md and USERGUIDE.md to describe what is actually
enforced now (previously the guide deliberately avoided promising
checkpoint anchoring, since the array was empty).
 2026-07-07 15:12:17 +02:00
davide 69be42aba0 docs(cli): translate console output and comments to English 
The CLI printed all wallet/sync/send output, error messages and usage
text in Italian by design; per the project's language policy (code,
comments and docs are English-only, Italian is reserved for user
conversation) this was a design mismatch, not a documented feature.
Translated every user-facing string and the file's Italian comments,
and updated USERGUIDE.md §17 to match.
 2026-07-07 14:46:08 +02:00
davide af2fdcc894 fix(gui): route runtime status messages through Loc instead of hardcoded Italian 
Send/Donate/Sync/Wizard view models wrote status/error strings
directly in Italian ("Importo non valido.", "Errore: …", the TLS
pin-mismatch message, …), so a user running the app in English/German/
etc. still saw them in Italian despite the 6-language Loc system
covering the rest of the UI.

Added the missing Loc keys and routed every occurrence through
Loc.Tr(...). CertificatePinMismatchException (Core) no longer bakes an
Italian message into .Message; it now exposes Host/Port so the UI can
translate it, with an English fallback for any exception type the UI
doesn't specifically handle. Also drops the now-stale USERGUIDE.md
caveat about a few messages staying in Italian regardless of language.
 2026-07-07 14:45:43 +02:00
davide 1f4421ae16 docs: add end-user guide covering GUI and CLI 
Full reference for every user-facing behavior (wizard flows, script
types, fees, gap limit, TOFU cert pinning, CLI commands) with the
exact numbers the software enforces, so users don't have to guess or
read the source to understand a rule.
 2026-07-07 14:44:48 +02:00
davide b304996ff5 docs(security): correct PBKDF2 iteration count and salt size 
SECURITY.md still documented the pre-hardening parameters (100,000
iterations, 32-byte salt); the code has used 600,000 iterations and a
16-byte salt (EncryptedFile.DefaultIterations) since the encryption
upgrade, with the count itself stored in the file container for
forward compatibility.
 2026-07-07 14:24:43 +02:00
davide c75e3921aa docs: sync AGENTS.md with CLAUDE.md and fix stale references 
AGENTS.md had drifted from CLAUDE.md (ASCII dashes instead of em-dashes,
missing recent updates); both now carry identical content except for the
header, with an explicit rule to keep them in sync on future edits. Also
documents update-version.sh as the release workflow, the per-feature
partial-class split of MainWindowViewModel, UpdateChecker, and fixes a
reference to a nonexistent Core/Spv/MerkleVerifier.cs (the real file is
MerkleProof.cs) in SECURITY.md.
 2026-07-02 23:45:53 +02:00
davide 50d8e7f21a docs(security): disclose AI-assisted testing methodology 
Documents the concrete techniques used (adversarial fake-server simulation
of a lying indexing server, property-based fuzzing, targeted security code
review) rather than a generic "AI-reviewed" claim, and states explicitly
that this complements rather than replaces independent security review.
 2026-07-02 23:38:25 +02:00
davide 15978bf564 chore(release): bump version to 0.9.1 
Fills in the CHANGELOG.md entry for the test-suite expansion and bug fixes
since 0.9.0 (see previous commits), and bumps <Version>/versionCode across
the App and Android head csproj files ahead of the tag.
 2026-07-02 23:25:48 +02:00
davide 31aabd0856 docs: document expanded test coverage and the fake ElectrumX server 
README's "Running tests" section now lists what each test area covers and
how to measure coverage; CLAUDE.md/AGENTS.md point future work at extending
the fake ElectrumX server instead of mocking ElectrumClient (it isn't an
interface, by design).
 2026-07-02 23:21:54 +02:00
davide 56ce1d4259 test: extend wallet/storage/property coverage and fix nullable warnings 
- AppPaths: data-root resolution, per-network paths, wallet file listing.
- TransactionFactory: legacy/P2SH/segwit destinations, multi-UTXO selection,
  dust change absorbed into fee, and a golden txid for the PSBT signing path
  (RFC 6979 makes it deterministic; the builder's own output shuffling for
  privacy makes anchoring the vector at the top-level Build() unreliable).
- PropertyTests: Slip132 roundtrip for every script kind and network,
  WalletDocument JSON roundtrip with arbitrary labels/contacts, Scripthash
  cross-checked against an independent SHA-256 computation.
- StorageTests: regression cases for the IsEncrypted fix.
- Removed CS8602/CS8604 nullable warnings from existing address/loader tests.
 2026-07-02 23:21:25 +02:00
davide 448f7dc65d test: cover network/SPV layer end to end (was previously untested) 
ElectrumClient, WalletSynchronizer, TransactionInspector, CertificatePinStore
and peer discovery went from 0% coverage to close to full coverage, all
against the fake ElectrumX server:

- ElectrumClient: request/response correlation under load, server errors,
  notifications, disconnection, cancellation, SSL handshake with TOFU pinning.
- 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 must abort.
- TransactionInspector: fee calculation from resolved inputs, mine/theirs
  attribution, RBF flag, coinbase handling, degraded paths when a previous
  transaction can't be resolved.
- CertificatePinStore: TOFU pin/match/mismatch/reset, corrupted-file fallback.
- ServerRegistry: peer discovery and persistence via DiscoverAsync.
- UpdateChecker: release-tag parsing and semver comparison.
 2026-07-02 23:21:01 +02:00
davide e8ff99a768 test: add in-process fake ElectrumX server for network-layer testing 
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. Lets ElectrumClient, WalletSynchronizer, TransactionInspector, and
CertificatePinStore be exercised against the same code paths used in
production instead of being mocked.

Also exposes UpdateChecker's tag-parsing logic internally so its version
comparison can be tested without a real GitHub API call.
 2026-07-02 23:20:32 +02:00
davide 27231c8eec fix(core): stop corrupted state from permanently breaking SSL and wallet loading 
CertificatePinStore.Load threw on a corrupted pin file, blocking every SSL
connection until the user manually deleted it; EncryptedFile.IsEncrypted
threw on valid JSON with a non-object root or invalid UTF-16 instead of
returning false. Both now degrade gracefully. Found by property-based tests
while extending the test suite.
 2026-07-02 23:19:46 +02:00
davide eb7ec9e835 chore: add update-version.sh to bump version across the project 
Prompts for the new version and updates the App csproj Version (single
source of truth), mirrors it into the Android head's
ApplicationDisplayVersion, bumps the Android versionCode, and stubs a
new CHANGELOG.md entry.
 2026-07-02 22:21:19 +02:00
davide f0fb3fe05d docs: link CHANGELOG.md and require updating it on new version tags 
CLAUDE.md: add a working rule to update CHANGELOG.md whenever <Version> is
bumped for a new release tag. README.md: add a Changelog section pointing
to it, and fix a stale claim that release signing "is not set up yet" for
Android — it now is, via docker/build.sh android and the persistent
keystore (docker/keystore/).
 2026-07-02 22:01:35 +02:00
davide 3f26f52f8b docs: add CHANGELOG.md for 0.9.0 
Technical changelog covering the full history from the initial commit,
grouped by subsystem (Core/Chain, Crypto, Net, Spv, Storage, Wallet, App UI,
Android, CLI, Build, Testing, Docs) rather than raw commit order, since this
is the first release.
 2026-07-02 22:01:17 +02:00
davide cb3ff714d9 feat(android): sign release builds with the persistent keystore 
build_android now requires the keystore generated by the previous commit,
prompts for its passwords at build time, and signs the APK with it instead
of an ephemeral debug key auto-generated per container run — that was the
actual cause of every release needing a manual uninstall to update. Also
derives versionCode from <Version> instead of leaving it fixed at 1, so
version ordering stays monotonic across releases.

Docs (docker/README.md, CLAUDE.md) updated to match the new signing flow.
 2026-07-02 21:54:23 +02:00
davide d0037747b5 chore(android): add persistent release-signing keystore generator 
An Android APK's signature identifies the app to the OS; a new build must
carry the same one as the last install or Android refuses it as an update.
generate-keystore.sh creates the keystore once, interactively, and refuses
to run again once one exists to avoid ever changing it by accident. The
resulting file is git-ignored — it's a secret that must live outside the
repo, backed up separately.
 2026-07-02 21:53:56 +02:00
davide 34b4313a36 feat(app): check GitHub releases on startup and prompt for updates 
Compares the running assembly version against the latest GitHub release
tag on every app launch (desktop and Android) and shows an in-app
overlay with the new version tag when one is available. Best-effort:
network/parse failures are silent, matching the app's existing
non-blocking startup checks.
 2026-07-02 21:33:18 +02:00
davide 2d017231eb chore(github): complete issue/PR templates and wire in-app bug report to them 
Add a feature request template and a config.yml (blank issues disabled,
security reports routed to SECURITY.md) alongside the existing bug report
template, plus a PR template with a checklist matching the project's
security rules. Point the app's "Report a bug" button at the new GitHub
template now that the repo is hosted there instead of the old self-hosted
tracker.
 2026-07-02 21:22:42 +02:00
davide e7797017f6 feat(gui): split server discovery into its own always-usable button 
Previously the server settings overlay had only "Connect and sync" and
"Reset certs" — peer discovery had no button and only ran implicitly
when reopening the dialog while connected. Add a dedicated "Sincronizza"
button wired to DiscoverServersCommand, and make it work even without
an active connection by opening a short-lived connection to a candidate
server just to query its peer list, then closing it without touching
the wallet's connection state.
 2026-07-02 19:24:16 +02:00
davide 6c24a8bb46 feat(wallet): surface immature balance separately from confirmed 
Extract confirmation-threshold logic into UtxoSpendability (shared by
TransactionFactory and WalletSynchronizer) and use it to compute
ImmatureSats, so coinbase/under-confirmed amounts are shown separately
from spendable balance in the GUI and CLI instead of being lumped into
"confirmed".
 2026-07-02 18:24:33 +02:00
davide 9aecdb1aaa feat(wallet): enforce confirmation thresholds before spending UTXOs 
Coinbase outputs require COINBASE_MATURITY + 1 = 121 confirmations before
they can be spent. The consensus rule (palladiumcore tx_verify.cpp) is
nSpendHeight - nHeight >= 120; the +1 adds one block of safety margin,
matching the Qt wallet (wallet.cpp: COINBASE_MATURITY+1). Regular UTXOs
require MinConfirmations (6 on mainnet, 1 on testnet/regtest — wallet
policy, no consensus rule).

Changes:
- ChainProfile: add CoinbaseMaturity and MinConfirmations fields
- ChainProfiles: mainnet CoinbaseMaturity=120 / MinConfirmations=6;
  testnet/regtest inherit 120, override MinConfirmations=1
- PalladiumNetworks: align NBitcoin Consensus.CoinbaseMaturity to 120
- CachedUtxo: add IsCoinbase flag (ElectrumX listunspent does not expose
  this; derived from Transaction.IsCoinBase on the raw tx)
- WalletSynchronizer: set IsCoinbase during local UTXO reconstruction
- TransactionFactory.Build: add tipHeight param; filter by threshold;
  error reports reason (immature coinbase with X/121 counter, under-
  confirmed regulars with best-seen count, mempool amounts)
- All Build() call sites updated (App, Donate, CLI)
- Two new tests: coinbase maturity boundary (119→220 tip) and mainnet
  min-conf boundary (5→6 confirmations)
 2026-07-02 16:25:42 +02:00
davide 2be43d3177 fix(sync): allow server change at any time, even during an active sync 
When IsSyncing and the user requests a different server, cancel the
running CancellationTokenSource instead of silently ignoring the click.
OperationCanceledException is caught separately (not an error), and
ConnectAndSync restarts automatically with the new server after the
cancelled task unwinds.

The "Connect" button no longer has IsEnabled="{Binding !IsSyncing}":
it is always clickable, and clicking it with the same server sets
_resyncRequested as before. CancellationToken is now passed to both
ElectrumClient.ConnectAsync and WalletSynchronizer.SyncOnceAsync.
 2026-07-02 14:56:58 +02:00
davide ef60ec0330 loc: expand About description to include non-custodial and local security details 
All six languages updated: the one-liner was replaced with a two-sentence
description that names the network (PLM), the lightweight SPV design,
the non-custodial model, and the local encryption guarantee.
 2026-07-02 12:29:38 +02:00
davide 567c0de501 docs: document reproducible builds and fix Windows publish command 
README.md: add "Reproducible builds (Docker)" section at the top of
Building, explaining why it matters for a wallet (auditable toolchain,
no drift between releases, anyone can verify binaries from source).
Fix the manual Windows publish command to include
IncludeNativeLibrariesForSelfExtract=true — the previous command produced
an exe that silently failed to start because Avalonia's native DLLs were
left outside it.

CLAUDE.md: document docker/ in the project tree, promote ./docker/build.sh
as the primary release path, record the two non-obvious gotchas (native
libs flag for single-file desktop; XA5207 / API level coupling for Android).
 2026-07-02 10:45:57 +02:00
davide 6a5daa0c18 feat(build): add Docker-based reproducible build system 
Adds docker/ with two Dockerfiles and a build.sh interactive script that
builds all three release targets (Windows exe, Linux binary, Android APK)
inside pinned Docker containers — no SDK required on the host.

Key design decisions:
- Source mounted read-only; build runs on an in-container copy so bin/obj
  never pollute the working tree.
- NuGet packages cached in a named Docker volume (plm-nuget-cache) across
  runs to avoid re-downloading on each build.
- Single-file desktop publishes use IncludeNativeLibrariesForSelfExtract so
  Avalonia's native libs (Skia, HarfBuzz, ANGLE) are embedded — without this
  flag the exe/binary silently fails to start.
- Android Dockerfile pins platform API 36 (dictated by the .NET 10 android
  workload, error XA5207 if mismatched) and bakes the full Android SDK +
  workload into the image layer.
- Artifacts are chown'd back to the host user so dist/ files are never
  owned by root.

All three targets verified end-to-end from a clean docker system prune -a:
Windows PE32+ exe (103 MB), Linux single-file binary launches on this host,
Android APK installs and renders UI on API-34 x86_64 emulator.
 2026-07-02 10:45:43 +02:00
davide 4d730d7860 feat(ui): add bug report button in Help and GitHub issue template 
Adds a "Report a bug" / "Segnala un bug" button (6 languages) in
Help → Info that opens the issue tracker in the system browser via
TopLevel.Launcher (cross-platform: desktop + Android).
URL points to the current self-hosted repo; a TODO comment marks
the constant for easy update once the project moves to GitHub.

Adds .github/ISSUE_TEMPLATE/bug_report.yml — GitHub issue form with
structured fields for version, platform, network, repro steps,
expected behavior, and logs.
 2026-06-24 15:41:37 +02:00
davideandClaude Sonnet 4.6 068d85e0e2 feat(ui): show full tx inputs/outputs in detail overlay without truncation 
Input rows switch to a two-line layout (full prev-txid:index on the first
line, address + amount on the second) so nothing is cut by a fixed 160px
column. Output address column gets TextWrapping instead of TextTrimming.
Overlay grows to MaxWidth=660/MaxHeight=800 for better desktop use; the
same XAML wraps naturally on narrow mobile screens.
Removes the Shorten() helper that was masking input references.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-24 15:37:43 +02:00
davide 1f857ddf52 refactor(ui): remove SPV badge from tx detail and history 
SPV is the only verification method the wallet uses, so showing it as a
badge adds no information — if a transaction appears confirmed, it has
already passed Merkle verification.

- Remove the SPV chip from the transaction detail overlay
- Remove the Verificata column from the history list (desktop and mobile)
- Drop VerifiedText property from TransactionDetailsViewModel
- Drop the Verificata field from HistoryRow
- Remove the orphaned tx.verified loc key
 2026-06-22 00:02:47 +02:00
davide 2953ba35ba refactor(ui): remove redundant "Open wallet from file" menu item 
The wizard already covers opening existing wallets; a separate file-picker
entry in the menu duplicates that flow without adding value. Remove the menu
item, its click handler, the OpenFromPath VM method, and the loc key.
 2026-06-21 22:46:23 +02:00
davide c0193ae440 feat(ui): add Quit to File menu; hide Wallet item when no wallet is open 
- File → Esci (separator + Quit at the bottom) calls IClassicDesktopStyleApplicationLifetime.Shutdown()
- Wallet menu item and mobile button now use IsVisible instead of IsEnabled:
  they disappear entirely on the wizard/setup screen and reappear once a
  wallet is open, avoiding a confusing greyed-out entry
 2026-06-21 22:34:59 +02:00
davide affeaccae8 feat(ui): password-gated private key reveal in address detail overlay 
Replace the direct private-key display in the address detail overlay with a
two-step reveal flow:

- Unencrypted wallet: clicking Show reveals the WIF key immediately.
- Encrypted wallet: clicking Show opens a modal password-prompt overlay; the
  key is displayed only if the entered password matches the wallet file
  password; a wrong password shows an inline error without closing the prompt.

Hiding the key (Hide button) clears the revealed state. Closing the address
overlay or opening a different one always resets both the reveal state and
the password prompt, so no sensitive material lingers between sessions.
 2026-06-21 22:28:33 +02:00
davide 4a97172346 feat(ui): Wallet menu overlay — info, xpub, and password-protected seed reveal 
Add a Wallet menu item (between File and Settings) that opens an in-app
overlay showing wallet metadata: file name, network, type (HD seed / xprv /
WIF / watch-only), script kind, derivation path, master fingerprint, and
account xpub.

Includes a seed section: if the wallet has no seed, a note is shown; if it
has one and is unencrypted the seed is revealed directly; if encrypted the
user must enter the wallet file password before the mnemonic is displayed.
The revealed seed is shown in a danger-coloured bordered box with a warning.
Closing the overlay (backdrop, Close button, or Esc) always clears the
password input and hides the seed.

Also adds the private-key password-prompt overlay and its localization keys
(shared UI scaffolding used by the following commit).
 2026-06-21 22:27:55 +02:00
davide 5d6ff07f0b docs(agents): add coding agent guide 2026-06-21 20:56:31 +02:00
davide c5290a1796 feat(ui): persist last server and split connection status text 
- AppConfig stores LastServerHost/Port/UseSsl; restored on next launch
  so the wallet reconnects to the last-used server instead of defaulting
  to the first bootstrap entry
- Added ConnectionStatusShort for the status bar (short label only);
  ConnectionStatus retains the full "Connesso a ip:porta" shown in the
  server settings overlay
 2026-06-18 19:34:41 +02:00
davide 227ec62d53 feat(ui): simplify server panel — remove TLS/Discover, show full address in status 
- Removed TLS checkbox (SSL still used internally, just not exposed in UI)
- Removed "Discover servers" button (discovery now runs automatically on panel open)
- ConnectionStatus now includes host:port when connected ("Connesso a ip:porta")
- Replaced status ellipse+text with a single TextBlock
 2026-06-18 19:29:33 +02:00
davide fa9d9b12f1 docs(claude): remove obsolete blueprint refs and progress tracker 
Implementation is complete; the blueprint.md file no longer exists in the
repo. Drop the dead reference, all §X section markers, the "Implementation
state" progress block, and the TODO list. General rules (role, language
policy, architecture invariants, working rules) are preserved unchanged.
 2026-06-17 14:04:22 +02:00
davide 96b6a7e291 feat(ui): Help overlay with Info/Donate tabs, fixed dimensions 
Help button now shows a fixed-size two-tab overlay:

Info tab: app name + version, one-line description, thin separator,
  © 2026 Davide Grilli — MIT License, Built with .NET 10 · Avalonia 12 · NBitcoin.

Donate tab: dev address (plm1qdq3…) read-only display, free amount
  input, prepare-preview row, confirm-and-broadcast button.

Overlay dimensions are stable across tabs and between desktop/mobile:
- TabControl Height=320 (fixed, never resizes on tab switch)
- HorizontalAlignment=Stretch + MaxWidth=440 on the card (always fills
  available width; previously Center caused the card to shrink to content
  width, which differed between Info and Donate)
- Each tab content wrapped in ScrollViewer for safe overflow handling

New MainWindowViewModel.Donate.cs: PrepareDonate / ConfirmDonate /
ResetDonate (called on overlay close). Six-language Loc keys added for
all donate strings.
 2026-06-17 09:01:06 +02:00
davideandClaude Sonnet 4.6 b13b66160c feat(ui): donate tab in Help overlay 
Help button now shows a two-tab overlay:
- Info: existing about/version content
- Donate: donate flow to the dev address (plm1qdq3…) with free amount
  input, prepare preview, and confirm-and-broadcast button

New MainWindowViewModel.Donate.cs partial: DonateAmount / DonatePreview
/ HasPendingDonate observable properties, PrepareDonateCommand (builds
the tx with hardcoded dev address via the existing TransactionFactory),
ConfirmDonateCommand (broadcasts and syncs). Donate state is reset on
overlay close. Six-language Loc keys added (help.tab.info/donate,
donate.desc/dev.address/amount/prepare/confirm).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-17 08:40:02 +02:00
davide 9744619eb4 fix(ui): mobile tab bar — uniform sizing, indicator overlap, spacing 
- UniformGrid Columns="5" on TabStrip so all 5 tabs always stay on one
  row on Android (Rows="1" alone did not auto-calculate columns at
  measure time on the Android Avalonia renderer)
- Contacts tab header was using hardcoded FontSize=13/Width=24/Spacing=4
  instead of the TabFontSize/TabIconSize/TabSpacing ViewModel bindings,
  making it visually larger than the other four tabs on mobile
- ContentPresenter Margin="0,0,0,4" in Controls.axaml pushes the tab
  header content above the 2 px selection indicator, which is drawn at
  the absolute bottom of the template Panel and was overlapping the label
- TabItem horizontal padding 4→8 px and TabSpacing 2→4 for both
  desktop and mobile to give more breathing room between tab items
 2026-06-17 08:17:56 +02:00
davide 5d2d0ad312 feat(ui): two-column desktop layout for Send/Receive, fixed window size 
Send tab: Recipient and Amount cards side-by-side on desktop using a
two-column Grid, making full use of the available window width.
Summary card and action buttons remain full-width below both columns.
Mobile retains the original vertical stack.

Receive tab: QR card on the left (auto-width), address card expands
to fill the right column on desktop — standard fintech wallet pattern.
Mobile retains QR above, address below.

Window enlarged to 1020×680 (from 900×620) and fixed with CanResize=False;
Min/Max dimensions match so the resize handle never appears.
 2026-06-16 15:04:10 +02:00
davide 3d5a226a5a docs: translate all code comments to English (language policy) 
Translate every Italian /// XML doc comment, <!-- --> XAML comment, and
// inline comment to English across all source files (Core, App, tests).
Add the language policy to CLAUDE.md (conversation Italian; all code
and docs English). Update one test assertion that checked an Italian
exception message that was also translated.
 2026-06-16 14:40:11 +02:00
davideandClaude Opus 4.8 4b82a0852c feat(ui): restructure transaction details + clearer coinbase identification 
Transaction details overlay redesigned from a flat 12-row grid into a
scannable layout: a header with the net amount in focus plus SPV/status
badges, then three labeled cards (Overview, Amounts & fees, Technical
details), with inputs/outputs as carded rows. Adds a .section heading
style and tx.sect.* localization keys (6 languages).

Coinbase transactions are now explicitly identified: an amber "Coinbase"
badge in the header, and the misleading "From: —" / "coinbase —" replaced
with "Newly generated (mining)" (localized). Exposes IsCoinbase on the
details view model; no consensus/logic change, presentation only.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-16 10:21:50 +02:00
davide 41eb1bb788 feat(ui): centralized design system — blue/green tokens, gradient hero, SVG tab icons 
Replace raw Fluent defaults + inline hex with a semantic design system,
themed for both light/dark (follows system variant).

- Styles/Theme.axaml: semantic brushes (surface/text/border/status) per
  variant via ThemeDictionaries; override Fluent SystemAccentColor to brand
  blue (#2563EB) and ControlCornerRadius=8; blue->indigo balance gradient.
- Styles/Controls.axaml: reusable classes (card, balance-hero, chip, ghost),
  type scale (amount with tabular figures, mono, h1, label), button/input
  polish, tab selected-in-blue, list hover/selected tints, card hover-lift.
- MainView: balance shown as gradient hero card; dashboard tabs use Material
  SVG Path icons (Fill tracks TabItem selection) instead of Unicode glyphs;
  all hardcoded colors (LimeGreen/IndianRed/Orange/Gray/#99000000) and
  generic Fluent surface brushes mapped to semantic tokens; app background,
  stronger modal scrim, status bar top border.

Palette derived from the logo (blue=trust, green=money). Build clean, app
starts with no binding errors.
 2026-06-16 10:08:39 +02:00
davide 5ff2075a45 perf(spv): incremental discovery, parallel chains, persistent header cache 
Speed up wallet synchronization, especially re-syncs of large wallets:

- Incremental address discovery: known indices from the previous sync
  (NextReceiveIndex/NextChangeIndex) are fetched in a single parallel
  burst instead of sequential gap-limit rounds, cutting round-trips from
  O(used/gapLimit) to ~O(1). Receive and change chains scan in parallel.
- Merge tx download and Merkle verification into one parallel phase
  (no barrier between them); the per-call semaphore is dropped in favor
  of the transport-level in-flight gate.
- Persist verified block headers (SyncCache.BlockHeaders, height -> hex):
  immutable once stored, so blockchain.block.header round-trips for
  already-verified proofs are eliminated on later syncs.
- RetryOnBusyAsync with exponential backoff around server calls, treating
  -101/-102 and "server busy"/"excessive resource usage" as transient.

Wire the new PreloadCaches/ExportCaches signatures through the desktop
view model and the CLI sync command.
 2026-06-16 09:27:48 +02:00
davideandClaude Opus 4.8 38e0f0a52e perf(net): batched writes, zero-alloc reads, bounded in-flight requests 
Rework the ElectrumClient transport to cut latency and allocations
during sync:

- Channel-based single-reader write loop: drains the whole queue into a
  single WriteAsync+FlushAsync, replacing the _writeLock that forced one
  flush per message. N queued requests now travel in one TCP segment.
- PipeReader read loop parsing via Utf8JsonReader over pooled spans: no
  StreamReader/ReadLineAsync and no intermediate string per response.
- TcpClient.NoDelay = true: no Nagle wait on small packets.
- Concurrency gate (SemaphoreSlim, MaxInFlight=32) in RequestAsync:
  caps requests in flight to the server without serializing writes,
  avoiding floods (-101/-102) and connection drops on wallets with large
  history.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
 2026-06-16 09:27:40 +02:00
davide 14ae39c5aa feat(ui): wallet name field in creation wizard 
The last wizard step (password) now shows an optional name field.
The name becomes the filename: <name>.wallet.json in the wallets
directory. Invalid filename characters are replaced with '_'.

If left empty, the existing auto-name logic applies (default.wallet.json,
wallet-2.wallet.json, …). If the chosen name already exists the wizard
shows an error instead of overwriting.

The name field is visually separated from the encryption section by a
distinct background panel and a horizontal divider.
 2026-06-15 15:05:53 +02:00
davide 3054a9baaa fix(spv): resilient sync — GetHistory discovery, tx cache, auto-connect fallback 
Three interrelated fixes for sync reliability on large wallets:

1. Prevent -101 "excessive resource usage":
   ScanChainAsync uses GetHistoryAsync for discovery instead of
   SubscribeScripthashAsync. Subscriptions are limited to the gap window
   only (≤ 2×gapLimit addresses), so the session subscription count stays
   constant regardless of wallet history size — eliminating -101 on
   wallets with 1000+ historical addresses.

2. Persist and resume tx cache across sessions and disconnects:
   WalletSynchronizer gains ExportCaches() and PreloadCaches(). On every
   successful sync (and on partial failure) the downloaded raw tx hex and
   verified Merkle heights are written to SyncCache.RawTxHex/VerifiedAt
   in the wallet file. On reconnect or app restart the new synchronizer
   is pre-populated from disk so only new transactions are downloaded.
   _synchronizer is always nulled on reconnect (new client = new instance)
   while caches survive via the wallet file.

3. Auto-connect with multi-server fallback and retry:
   ConnectAndSync iterates BuildServerCandidates() (current server first,
   then all KnownServers in order) and stops at the first that responds.
   _autoReconnect and _syncFailed are set in OpenLoaded() so the keepalive
   timer (20 s) retries automatically on any failure — connection error,
   -101 mid-download, or timeout. PersistPartialTxCache() saves whatever
   was downloaded so each retry resumes from its checkpoint.
 2026-06-15 14:23:31 +02:00
davide 4dc37f1b42 feat(ui): wizard flows for xpub/xprv and WIF import 
Add two new import paths to the setup wizard:

- "Importa xpub / xprv": accepts any SLIP-132 key (xpub/ypub/zpub or
  xprv/yprv/zprv), auto-detects script type from the version prefix,
  and saves a watch-only or fully-spendable HD account accordingly.

- "Importa chiave WIF": accepts one or more WIF private keys (one per
  line), goes through script-type selection, and saves an ImportedKeyAccount.

WizardFlowKind enum (New, Restore, ImportXkey, ImportWif) governs which
steps are shown; WizardBack() updated for all four flows. OpenLoaded()
updated to accept IWalletAccount and display wallet kind tags
(watch-only / imported) in the network info line.

Localization keys added for all six languages (it/en/es/fr/pt/de).
ViewModel._account changed from HdAccount? to IWalletAccount?.
 2026-06-15 14:23:08 +02:00
davide 47b6064964 feat(wallet): IWalletAccount abstraction and WIF/xpub/xprv keystore import types 
Introduce IWalletAccount interface to abstract HD, imported-xprv, WIF,
and watch-only account types. HdAccount implements the interface; the
new ImportedKeyAccount handles lists of WIF keys with fixed addresses
(no gap scanning, change returns to first address).

WalletLoader gains three factory methods:
- NewFromXpub: watch-only from SLIP-132 xpub/ypub/zpub
- NewFromXprv: spendable from SLIP-132 xprv/yprv/zprv
- NewFromWif: spendable from one or more WIF private keys

WalletDocument gains optional AccountXprv and WifKeys fields; AccountPath
and AccountXpub become nullable (absent for WIF wallets). IsWatchOnly
updated to cover all non-signing wallet kinds.

TransactionFactory and CLI OpenWallet() updated to IWalletAccount.
12 new unit tests in ImportedKeyAccountTests cover factory round-trips,
address derivation, and watch-only detection.
 2026-06-15 14:20:13 +02:00
davide 002c854497 feat(wallet): add P2PKH, P2SH-P2WPKH, and P2TR (Taproot/BIP86) address types 
- ScriptKind.Taproot (BIP86, purpose 86', P2WPKH → witness v1 bech32m plm1p)
  derivation wired in DerivationPaths and ChainProfiles (xprv/xpub headers,
  no SLIP-132 standard for P2TR); NBitcoin ScriptPubKeyType.TaprootBIP86
- Wizard step StepScriptType inserted between passphrase and password: 4 radio
  buttons (Legacy / Wrapped SegWit / Native SegWit★ / Taproot), localized in
  6 languages; CreateOrRestore now uses SelectedScriptKind instead of hardcoded
  NativeSegwit; back navigation updated accordingly
- BIP86 golden-vector tests (Bip86TaprootTests): output key verified against
  official Bitcoin BIP86 addresses, plm1p prefix asserted
 2026-06-15 12:03:52 +02:00
davide 8b960458ee feat(ui): server overlay full-screen on mobile, larger touch targets 
On mobile the server settings panel now fills the entire screen
(no MaxWidth/MaxHeight/Margin constraints, no rounded corners) using
a desktop-only Border.desktop-overlay style so inline values never
fight the style system. Input font sizes increased (11→13/15px),
known-server list taller (200→300px) and server hostname larger (13→15px).
Desktop layout unchanged.
 2026-06-15 10:59:12 +02:00
davide 1b784a6c73 fix(ui): prevent text overflow on mobile 
UnconfirmedText (pending/unconfirmed balance) now wraps instead of
clipping horizontally. Contact name in mobile list gets CharacterEllipsis
trimming for arbitrarily long user-defined names.
 2026-06-15 10:58:42 +02:00
davide 200c12651b feat(ui): hardcode mainnet, remove network selector 
Drop the mainnet/testnet/regtest ComboBox from the wizard and fix
Net to always return NetKind.Mainnet. Core profiles and CLI --net
flag are untouched; the wallet file still records the network name.
 2026-06-15 10:35:40 +02:00
davide 5f983ca84e feat(ui): replace emoji camera button with vector path icon 
Uses a Material Design outline camera path (body + lens) inside a Viewbox
so the icon scales cleanly and inherits the theme foreground color.
 2026-06-15 10:25:46 +02:00
davide 53ecd701c0 feat(ui): unified tab bar with icons on desktop and mobile 
Replace the mobile-only custom bottom Grid nav bar with a single styled
TabStrip that works the same on both platforms: icon + label headers,
gray background, UniformGrid for equal-width columns.
Also adds the 📷 scan button in the Send address field (visible on mobile,
triggers ScanQrCommand wired in the previous commit).
 2026-06-15 10:19:41 +02:00
davide bfee0dde03 feat(android): QR code scanner for Send address field 
Camera2 + ZXing.Net 0.16.9 activity (ScannerActivity) that captures JPEG
frames at ~2.5 fps and decodes QR codes without Xamarin dependencies.
Result is returned to MainActivity via OnActivityResult/TaskCompletionSource.
PlatformServices.ScanQrAsync seam wires Android head to shared App layer;
ScanQrCommand in the Send ViewModel strips BIP21 URI scheme/query parameters.
CAMERA permission and uses-feature added to AndroidManifest.
 2026-06-15 10:19:29 +02:00
davide 8476eeb247 feat(android): add app logo as launcher icon 
Generate mipmap ic_launcher.png at all standard densities (mdpi→xxxhdpi)
from logo.png, cropped to bounding box and scaled to 88% of the tile on
a white background (legacy fallback for API < 26).

For API 26+ provide an adaptive icon (ic_launcher.xml / ic_launcher_round.xml)
with white background and a foreground PNG where the logo occupies 56% of
the 108dp canvas — within the safe zone, fully visible on every launcher
shape without clipping.
 2026-06-15 08:49:54 +02:00
davide 1914d9462b feat(ui): replace mobile tab strip with custom full-width nav bar 
Avalonia's TabStrip ignores HorizontalAlignment overrides when placed at
Bottom, causing the items to cluster left. Replace it with a dedicated
Grid (ColumnDefinitions="*,*,*,*,*") that guarantees 5 equal columns
across the full width. The built-in TabStrip is hidden on mobile; buttons
in the custom bar call SelectTabCommand to drive SelectedTabIndex on the
TabControl.
 2026-06-15 08:49:44 +02:00
davide 4c0edde4f7 feat(ui): mobile polish — tab bar icons, server overlay, status text 
Tab bar: replace plain Header strings with icon+label StackPanels
(≡ ↑ ↓ ⊙ ⊕); style TabStrip with UniformGrid so all five tabs share
the full width equally; center content and add touch padding. Icons
are visible only on mobile (IsMobile binding); desktop keeps text only.

Server settings overlay: dual layout for host/port/TLS input (vertical
on mobile: host full-width, port+TLS side by side) and for action
buttons (stacked full-width on mobile). Known-server list item shows
host on one line and tcp/ssl ports on the line below on mobile.

Connection status bar: simplify to "connesso" / "non connesso" —
remove the "a host:port" suffix from the connected state and
consolidate all disconnected/error/cert-changed states to conn.none.
 2026-06-14 22:05:30 +02:00
davide cfc48ff86f feat(ui): responsive layout for portrait mobile (Android) 
Add IsMobile property and BoolToTabPlacementConverter; wire
TabStripPlacement to move tabs to the bottom on mobile (standard
Android pattern). Hide the desktop menu bar on mobile and expose
Settings/Help via a compact header row instead.

Replace fixed-width multi-column grids with dual desktop/mobile
templates in History, Addresses and Contacts lists; adapt Send,
Receive and the add-contact form for narrow screens. Remove hard-coded
Width from all five overlays (560–640 px) in favour of MaxWidth +
Margin="16" so they never overflow a 360 px screen; add ScrollViewer
to Address info, Server settings and Settings overlays.

Desktop layout is unchanged: all differences are gated on the
IsMobile/IsDesktop bool, which is a platform constant (false on desktop).
 2026-06-14 19:54:11 +02:00
davide bb9819ec96 docs: document CsCheck property-based tests in README and CLAUDE.md 2026-06-13 22:09:52 +02:00
davide 8cdbd70966 test: add property-based tests with CsCheck (218 total) 
9 property tests covering:
- CoinAmount: TryParseIn/TryParseCoins never throw on arbitrary strings;
  FormatIn→TryParseIn roundtrip holds for any sats in [0, MaxSupply];
  parsed results always ≥ 0
- EncryptedFile: Encrypt→Decrypt roundtrip for any plaintext/password;
  wrong password always raises WrongPasswordException (never other exceptions);
  IsEncrypted never throws
- MerkleProof: every leaf in a randomly generated tree verifies against its root
  (1–16 leaves, covers odd/even/single at every position); foreign txid never
  verifies and never crashes
 2026-06-13 22:09:02 +02:00
davide ee0b73dd52 test: expand coverage to 209 tests across all core modules 
Added tests for CoinAmount (all units, comma decimal, sub-satoshi rejection,
overflow, unknown unit ArgumentException, roundtrip), Storage (nonce/salt
uniqueness per encrypt, atomic write, WalletLock acquire/release/stale-file),
WalletLoader (NewFromMnemonic, passphrase isolation, watch-only, invalid
inputs, ProfileOf), SPV/Merkle (single tx, odd/even counts, altered proof,
empty list), and Chain (unknown NetKind, distinct profiles, port constants).
 2026-06-13 21:59:51 +02:00
davide a8d48bedad docs: add SECURITY.md with threat model and SPV trust assumptions 
Covers: what the wallet protects against (AES-GCM at rest, Merkle SPV
verification, TLS TOFU pinning) and what it does not (compromised OS,
eclipse attacks, traffic analysis). Documents key/seed management,
encryption parameters, TLS pinning behaviour, backup guidance, and
known v1 limitations (no Tor, no coin control, no hardware wallet).
 2026-06-13 21:15:41 +02:00
davide 5d061c6f21 docs(storage): document plaintext save caveat on WalletStore.Save 
The password parameter accepts null, which saves the wallet in plaintext.
The XML doc comment now makes explicit that this is only acceptable when
the user has explicitly opted out of encryption with a UI warning shown.
 2026-06-13 21:15:28 +02:00
davide 2ddc0f920c refactor(app): split MainWindowViewModel into partial files by area 
1300-line monolith → 7 focused files (max 359 lines each):
  MainWindowViewModel.cs         core fields, constructor, lifecycle
  MainWindowViewModel.Wizard.cs  setup wizard and wallet open/close flows
  MainWindowViewModel.Settings.cs language, unit, overlay flags
  MainWindowViewModel.Sync.cs    server config, connection, sync loop
  MainWindowViewModel.Send.cs    send panel
  MainWindowViewModel.Contacts.cs contact management
  MainWindowViewModel.Receive.cs balance display, QR, addresses, tx details

No behaviour change, no XAML change, 127/127 tests pass.
 2026-06-13 21:15:07 +02:00
davide 58645bd7a7 fix(storage): acquire wallet lock before load and before CloseWallet 
Three improvements to WalletLock integration:

1. OpenExisting acquires the lock before decrypting the file — no point
   attempting a potentially expensive PBKDF2 derivation for a wallet
   already held by another instance.

2. OpenFromPath acquires the lock before CloseWallet — if the new wallet
   is unavailable, the current session stays intact instead of being
   silently destroyed.

3. OpenLoaded now receives an already-acquired WalletLock from the caller
   instead of acquiring it internally; TryAcquireWalletLock is removed.
   Callers that fail to open (wrong password, I/O error) dispose the lock
   in their catch blocks.

Also fix CoinAmount.Of() to throw ArgumentException for unknown units
instead of silently falling back to PLM.
 2026-06-13 20:50:22 +02:00
davide 008e9c395a fix(wallet): reject amounts with sub-satoshi precision 
Replace the silent (long) cast with an explicit fractional check:
if value * factor has a non-zero remainder, TryParseIn/TryParseCoins
return false. The caller already shows "Importo non valido." to the
user, so no UI change is needed.

Covers TryParseIn (all units) and TryParseCoins. Adds CoinAmountTests
with valid and invalid cases including the triggering example (1.9 sat).
 2026-06-13 20:39:08 +02:00
davide 70cce640aa test(storage): add WalletLock unit tests 
Covers acquire/release, double-acquire returning null, and
re-acquire after dispose.
 2026-06-13 20:34:21 +02:00
davide 0f8a764a44 feat(storage): add WalletLock to prevent concurrent wallet access 
Introduces an exclusive file lock (FileShare.None on wallet.json.lock)
held for the duration of a wallet session. A second instance trying to
open the same file receives null from TryAcquire and sees a localized
error message; UnauthorizedAccessException (OS permission issues)
propagates separately so the UI can show a distinct message.
The .lock file is deleted on Dispose (best-effort); the real guard is
the open FileStream, which the OS releases automatically on crash.
 2026-06-13 20:34:06 +02:00
davide d66490b6be docs: update CLAUDE.md 2026-06-13 20:15:28 +02:00
davide b00c5821f2 refactor(app): clear status bar during wizard steps 
Remove the wizard-step status messages (welcome, password info,
seed instructions, etc.) — the XAML headings for each step already
communicate context. StatusMessage is now reserved for actionable
feedback (errors, sync progress, connection state).
 2026-06-12 16:16:37 +02:00
davide 658fcdbced docs: update CLAUDE.md and README for multi-head architecture and .NET 10 
CLAUDE.md: reflect Desktop+Android split, net10.0, updated build/run
commands (src/App.Desktop instead of src/App), note blueprint is now
reference-only not binding.

README: update project paths, publish commands and quickstart for the
new structure.
 2026-06-12 16:06:24 +02:00
davide e94eaf7700 refactor(arch): split App into shared library + Desktop + Android heads 
The Avalonia UI code (App, Views, ViewModels, Localization, Assets) now
lives in src/App as a plain library (no OutputType). Two thin heads
reference it:

- src/App.Desktop/ — WinExe, Avalonia.Desktop, hosts MainView in a
  MainWindow; carries Program.cs and app.manifest (moved from src/App)
- src/App.Android/ — net10.0-android, Avalonia.Android, MainActivity/
  MainApplication; targets API 23+, EmbedAssembliesIntoApk=true so the
  apk is self-contained for sideloading

All event handlers and TopLevel-dependent calls (file picker, clipboard,
folder picker) moved from MainWindow.axaml.cs into the new shared
MainView.axaml.cs (UserControl), using TopLevel.GetTopLevel(this) so
they work on both platforms. Esc/Back key handling is also in MainView.
MainWindow becomes a thin shell that hosts MainView.

Framework bump: all projects move to net10.0; Cli and Tests follow.
 2026-06-12 16:06:46 +02:00
davide a9ded6497a chore: add MIT license (copyright 2026 Davide Grilli) 2026-06-12 12:12:36 +02:00
davideandClaude Sonnet 4.6 46aca513b8 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 <noreply@anthropic.com>
 2026-06-12 12:12:34 +02:00
davide 6c01d7e6bd docs(claude): add CLAUDE.md with codebase guidance for AI tooling 
Documents stack, dependency rules, build commands, architecture
decisions and current implementation status for Claude Code.
 2026-06-12 12:13:06 +02:00
davide 3cffba6e98 chore(git): track CLAUDE.md and blueprint.md 
These files document the project for both contributors and AI tooling;
they belong in version control alongside the code they describe.
 2026-06-12 12:12:14 +02:00
davide 865daa137d feat(app): version in window title and Help overlay 
- csproj: add <Version>0.9.0</Version> as single source of truth
- AppVersion reads Major.Minor.Build from the assembly; WindowTitle
  exposes "Palladium Wallet 0.9.0" bound to Window.Title
- Menu Help → in-app overlay (same pattern as settings/server overlays)
  showing app name, version and a short description; backdrop tap and
  Esc close it
- i18n: menu.help, help.title, help.info in all 6 languages
 2026-06-12 12:01:25 +02:00
davide 4735490759 feat(app): transaction detail overlay with full on-chain data 
Double-clicking a history row opens an in-app overlay (same pattern as
address/server/settings overlays) that shows all available data for a
transaction. The overlay appears immediately with a spinner; data is
fetched from the server in the background and rendered once ready.
Backdrop tap and Esc close it; a pending fetch is cancelled.

New Core type — TransactionInspector (Core/Wallet/):
- FetchAsync() downloads the raw tx, all parent txs (parallel requests,
  one round-trip instead of N sequential), and the block header
- Reconstructs inputs (amounts, addresses, is-mine), outputs, fee,
  virtual size, RBF flag, block timestamp, confirmations

New App types:
- TransactionDetails record: full parsed data (fee, net, I/O lists,
  counterparty addresses, coinbase detection…)
- TransactionDetailsViewModel: pre-formats all strings in the current
  locale and unit (status, date, signed amounts, sat/vB rate…)
- TxIoRow record: one row in the input/output tables
- MineColorConverter: bool → brush (MediumSeaGreen for own addresses)

ViewModel changes:
- ShowTransactionDetailsAsync / CloseTransactionDetailsCommand
- BuildTransactionDetailsAsync (also public for future RBF/CPFP use)
- CancellationTokenSource so opening a new tx cancels the previous fetch
- All server work runs on Task.Run to keep the UI thread free

XAML: history rows get DoubleTapped handler, Hand cursor, hint label,
txid now uses TextTrimming instead of SelectableTextBlock.

i18n: 24 new tx.* / history.hint keys in all 6 languages.
 2026-06-12 11:48:33 +02:00
davideandClaude Sonnet 4.6 4c7e8696cb feat(app): copy-to-clipboard button for receive address 
Adds a "Copy" button next to the receive address in the Receive tab.
Uses Avalonia's Clipboard API (async, code-behind) and calls
NotifyAddressCopied() to show the existing addr.copied status message.
New i18n key receive.copy in all 6 languages.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-12 10:47:01 +02:00
davide 7727dbfddc feat(app): replace placeholder icon with Palladium Wallet logo 
Add logo.png (source) and logo.ico (multi-size: 256/128/64/48/32/16)
generated with Pillow. Remove avalonia-logo.ico (Avalonia template
placeholder). Update MainWindow.axaml Icon and csproj ApplicationIcon
to point to the new files.
 2026-06-12 10:40:29 +02:00
davide 58b86ad1af feat(app): QR code for receive address 
Adds QRCoder 1.8.0 and generates a PNG QR code in-memory each time
the receive address changes (OnReceiveAddressChanged). The bitmap is
displayed in the Receive tab inside a white-background border with
pixel-perfect scaling (BitmapInterpolationMode=None). Previous bitmap
is disposed to avoid memory leaks.
 2026-06-12 10:21:18 +02:00
davide 7f2759b2fc feat(app): multi-wallet chooser, confirm-password, encrypt toggle 
Multi-wallet (§8):
- AppPaths.WalletFiles(net) enumerates all *.wallet.json in the wallets
  dir; WizardStartOpen shows a chooser step when more than one is found
- New StepChooseWallet + ChooseWalletCommand; Back from StepOpen returns
  to chooser (or to StepStart when only one wallet)
- WalletFileEntry record for the chooser ItemsControl

Password step (Electrum style):
- ConfirmPasswordInput: password must be typed twice before creating
- EncryptWallet checkbox (default true); when unchecked, password is
  null (plaintext file) with an explicit warning
- Validation: empty password with encryption on → msg.password.required;
  mismatch → msg.password.mismatch
- ConfirmPasswordInput cleared on wallet open and wizard back

AppPaths:
- DefaultDataRoot() is now platform-aware: %APPDATA%\PalladiumWallet on
  Windows, ~/.palladium-wallet on Linux/macOS (matches §8 convention)
- Legacy root fallback removed (no prior releases to migrate from)

i18n: wiz.choose.title, wiz.password.confirm, wiz.password.encrypt,
wiz.password.encrypt.hint, msg.choose.wallet, msg.password.required,
msg.password.mismatch — all 6 languages
 2026-06-12 10:13:17 +02:00
davide a8a97f09b7 feat(app): connect to server before wallet open, status in bottom bar 
- ConnectAndSync() no longer bails early when no wallet is open:
  connection is established immediately after the wizard completes
  (Electrum-style), sync starts only once an account is available
- KeepAlive tick no longer requires IsWalletOpen so the connection is
  maintained and auto-reconnected at all times
- WalletSynchronizer is lazily created on first sync (not on connect)
  to avoid a null-ref guard on _synchronizer
- Connection status indicator (dot + text) moved from wallet header to
  the status bar (always visible); tapping it still opens the server
  settings overlay
- Menu "Rete" removed: Discover and ResetCerts are inside the server
  settings overlay; redundant top-level menu entry eliminated
- "Server" button in settings overlay is no longer gated on IsWalletOpen
 2026-06-12 10:13:04 +02:00
davide f3bf4cf94a feat(app): first-run data location wizard step 
On first launch (no data yet, no portable dir, no pointer file),
the wizard now shows a new step-0 screen asking where to store
wallets, config and certificates.

AppPaths changes:
- DefaultDataRoot() → ~/.PalladiumWallet (home, always writable)
- IsDataLocationConfigured() → true when portable / override / pointer
  already written / legacy or default already has data
- ConfigureDataLocation(root) writes a bootstrap pointer file and
  creates the directory
- DataRoot() resolution order: override → portable → pointer → legacy
  (has data) → default

ViewModel: new StepDataLocation step, UseDefaultDataLocationCommand,
ApplyDataLocation(root) (also called from View's folder picker).

View: new wizard panel with description, default-path display, two
buttons (use default / choose folder); folder picker via
StorageProvider.OpenFolderPickerAsync.

Loc: add wiz.data.* keys (6 languages); fix fallback language "it"→"en";
update test assertion accordingly.
 2026-06-12 09:25:04 +02:00
davide 87e1c82610 feat(app): connection status indicator opens server settings on tap 
The green/red dot + status text in the wallet header is now tappable:
opens the server settings overlay directly. Added Hand cursor and
tooltip (server title) to signal interactivity.
Status text uses SystemAccentColor instead of Gray.
 2026-06-12 09:24:57 +02:00
davide 51c87a7dc9 refactor(app): replace nested settings submenu with in-app overlay 
The Impostazioni menu now opens a single overlay (same pattern as
address/server overlays) instead of nested OS popup menus, which are
slow to respond under WSLg.

The overlay groups language (RadioButton) and unit (RadioButton) in one
panel, with a button to open the server overlay. Esc and backdrop tap
close it. OpenServerSettings() closes the settings overlay first so the
two overlays never stack.
 2026-06-12 09:09:31 +02:00
davide 28cb4ce6ae feat(app): server settings as in-app overlay, split host/port fields 
- Moves server configuration from the wallet panel into an overlay
  (Impostazioni → Server), same pattern as the address detail overlay
- Splits the single "host:port" text box into separate Host and Port
  fields; port changes auto-toggle the TLS checkbox when the typed
  port matches a known SSL/TCP port, and vice-versa
- Adds DisconnectAsync() so changing server/TLS reconnects to the new
  endpoint instead of reusing the old socket
- Adds i18n keys (IT/EN/ES/FR/PT/DE) for the new overlay
- Removes the server row from the main wallet panel; connection status
  indicator (green/red dot) is now shown in the wallet header
 2026-06-12 09:02:19 +02:00
davide cf6e2d7654 refactor(app): replace AddressInfoWindow with in-app overlay 
The address detail panel is now rendered as a modal overlay inside
MainWindow instead of a separate top-level Window, avoiding the
create/destroy cost of a dialog and working better under WSLg.

Backdrop tap and Esc both close the overlay.
 2026-06-12 08:22:30 +02:00
davide fe320584eb feat(app): navbar restructure, contacts tab and address info window 
- Reorder tabs: Storico / Invia / Ricevi / Indirizzi / Contatti
- Invia: ComboBox to quick-fill recipient from saved contacts
- Contatti: new tab to add/remove contacts (name + address), persisted
  to the wallet file via WalletDocument.Contacts
- Indirizzi: clicking any address (left or right click) opens a modal
  window with derivation path, public key and private key as selectable
  text (no copy button needed — user selects and copies manually);
  AddressRow now carries PubKey, PrivKey, DerivPath pre-computed
- AddressInfoWindow: new Window with SelectableTextBlock per field,
  private key section hidden for watch-only wallets
- Loc: adds tab.contacts, addr.*, contacts.*, send.from.contact keys
  in all 6 languages
 2026-06-11 21:39:36 +02:00
davide 6fe31964e1 feat(storage): add contacts list to WalletDocument 
Adds StoredContact class and a Contacts list to WalletDocument so the
address book survives app restarts inside the encrypted wallet file.
 2026-06-11 21:39:18 +02:00
davideandClaude Sonnet 4.6 8ab8bbd8b3 feat(storage): XDG-compliant paths and default language English 
AppPaths: use Environment.SpecialFolder.ApplicationData for all platforms
  - Windows  → %APPDATA%\PalladiumWallet  (unchanged)
  - Linux    → ~/.config/PalladiumWallet  (XDG standard, was ~/.palladium-wallet)
  - macOS    → ~/Library/Application Support/PalladiumWallet

AppConfig: change default language from "it" to "en" for new installs.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-11 18:41:47 +02:00
davideandClaude Sonnet 4.6 71a604c8a5 feat(i18n): add ES, FR, PT, DE languages and fix live switching 
Add Spanish, French, Portuguese, German translations to all UI strings.

Fix language switching in Avalonia compiled bindings: instead of firing
PropertyChanged("Item[]") on a singleton (which Avalonia ignores when the
object reference is unchanged), Loc.SwitchTo() now creates a new Loc
instance for the selected language and replaces both Loc.Instance and the
ViewModel's _loc field. OnPropertyChanged("Loc") then forces Avalonia to
re-evaluate all {Binding Loc[key]} bindings with the new instance.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
 2026-06-11 18:41:31 +02:00
225 changed files with 21072 additions and 2519 deletions
Expand all files Collapse all files

No files matched your search

.github/ISSUE_TEMPLATE/bug_report.yml
+80
View File
@@ -0,0 +1,80 @@
name: Bug Report
description: Report a problem with Palladium Wallet
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to report a bug.
Please fill in every section — incomplete reports are hard to reproduce and may be closed.
- type: input
id: version
attributes:
label: Wallet version
description: Shown in Help → Info (e.g. `1.0.0`).
placeholder: "1.0.0"
validations:
required: true
- type: dropdown
id: platform
attributes:
label: Platform
options:
- Windows
- Linux
- Android
validations:
required: true
- type: textarea
id: description
attributes:
label: What happened?
description: Describe the bug clearly and concisely. What did you see? What did you expect?
placeholder: "When I click … the wallet shows … instead of …"
validations:
required: true
- type: textarea
id: steps
attributes:
label: Steps to reproduce
description: Numbered steps that reliably trigger the bug.
placeholder: |
1. Open the wallet
2. Go to …
3. Click …
4. Observe …
validations:
required: true
- type: textarea
id: expected
attributes:
label: Expected behavior
description: What should have happened instead?
validations:
required: true
- type: textarea
id: logs
attributes:
label: Logs / error messages
description: |
Paste any error dialogs, crash messages, or stack traces.
Leave blank if none.
render: text
validations:
required: false
- type: checkboxes
id: checklist
attributes:
label: Before submitting
options:
- label: I searched existing issues and this is not a duplicate
required: true
- label: I reproduced this on the latest available version
required: false
.github/ISSUE_TEMPLATE/config.yml
+5
View File
@@ -0,0 +1,5 @@
blank_issues_enabled: false
contact_links:
- name: Security vulnerability
url: https://github.com/palladium-coin/palladium-wallet/security/policy
about: Please report security vulnerabilities privately, not as a public issue. See SECURITY.md.
.github/ISSUE_TEMPLATE/feature_request.yml
+55
View File
@@ -0,0 +1,55 @@
name: Feature Request
description: Suggest an idea or improvement for Palladium Wallet
labels: ["enhancement"]
body:
- type: markdown
attributes:
value: |
Thanks for taking the time to suggest an improvement.
- type: textarea
id: problem
attributes:
label: Problem
description: What problem are you trying to solve? Is it related to something you find missing or frustrating?
placeholder: "I'm always frustrated when …"
validations:
required: true
- type: textarea
id: solution
attributes:
label: Proposed solution
description: Describe what you'd like to happen.
validations:
required: true
- type: textarea
id: alternatives
attributes:
label: Alternatives considered
description: Any alternative solutions or workarounds you've considered.
validations:
required: false
- type: dropdown
id: platform
attributes:
label: Affected platform(s)
multiple: true
options:
- Windows
- Linux
- Android
- CLI
- All
validations:
required: false
- type: checkboxes
id: checklist
attributes:
label: Before submitting
options:
- label: I searched existing issues and this is not a duplicate
required: true
.github/PULL_REQUEST_TEMPLATE.md
+26
View File
@@ -0,0 +1,26 @@
## Summary
<!-- What does this PR change and why? -->
## Related issue
<!-- Closes #... (if applicable) -->
## Type of change
- [ ] Bug fix
- [ ] New feature
- [ ] Refactor / cleanup
- [ ] Documentation
- [ ] Build / CI
## Testing
<!-- How was this verified? e.g. `dotnet test`, manual run on Windows/Linux/Android, golden-vector comparison -->
## Checklist
- [ ] `dotnet test` passes
- [ ] No seed/private key material logged or persisted in plaintext (if touching Crypto/Wallet/Storage)
- [ ] Server responses still validated with Merkle + checkpoints (if touching Spv/Net)
- [ ] Code/comments/commit messages are in English
.github/workflows/ci.yml
+98
View File
@@ -0,0 +1,98 @@
name: CI
on:
push:
branches: [main]
pull_request:
# Cancel superseded runs of the same branch/PR.
concurrency:
group: ci-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
env:
DOTNET_NOLOGO: true
DOTNET_CLI_TELEMETRY_OPTOUT: true
jobs:
test:
name: Test (${{ matrix.os }})
runs-on: ${{ matrix.os }}
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, windows-latest]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: 10.0.x
# Build/test only the test project and what it references (Core, Fuzz, ServerProbe):
# the Android head needs a workload and SDK that CI does not provision.
- name: Restore
run: dotnet restore tests/PalladiumWallet.Tests
- name: Build
run: dotnet build tests/PalladiumWallet.Tests --no-restore -c Release
# Offline and deterministic: unit, property-based (CsCheck), fuzz-corpus replay and the
# in-process FakeElectrumServer tests. LiveServerTests is a no-op without
# PALLADIUM_TEST_SERVERS, so no third-party server is contacted.
- name: Test
run: >
dotnet test tests/PalladiumWallet.Tests --no-build -c Release
--settings tests/coverage.runsettings
--logger "trx;LogFileName=test-results.trx"
--collect:"XPlat Code Coverage"
--results-directory TestResults
--blame-hang-timeout 5m --blame-hang-dump-type none
# Coverage gate (Ubuntu only, one report is enough): fails the job if Core drops below the
# thresholds. App and Cli are reported but not gated yet.
- name: Coverage gate
if: matrix.os == 'ubuntu-latest'
shell: bash
run: |
report=$(ls TestResults/*/coverage.cobertura.xml | head -1)
python3 tests/check-coverage.py "$report" PalladiumWallet.Core:95:88 PalladiumWallet.App PalladiumWallet.Cli
- name: Upload test results
if: always()
uses: actions/upload-artifact@v4
with:
name: test-results-${{ matrix.os }}
path: TestResults
retention-days: 14
fuzz-smoke:
name: Fuzz smoke (${{ matrix.target }})
runs-on: ubuntu-latest
timeout-minutes: 10
strategy:
fail-fast: false
matrix:
target: [header, merkle, slip132, bip39, address, coinamount, walletdoc, encfile, peers]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with:
dotnet-version: 10.0.x
# Random-input smoke run of each untrusted-input parser; any escaping exception fails the job.
# The coverage-guided campaign (afl++) stays a manual step, see tests/PalladiumWallet.Fuzz/fuzz.sh.
- name: Fuzz ${{ matrix.target }}
run: dotnet run -c Release --project tests/PalladiumWallet.Fuzz -- ${{ matrix.target }} --random 20000
docs:
name: Docs checks
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v4
- name: Check docs
run: ./docs/check-docs.sh
.gitignore
+13
View File
@@ -24,6 +24,7 @@ packages/
TestResults/
coverage/
coverage.*
!tests/coverage.runsettings
*.coverage
*.coveragexml
*.trx
@@ -74,6 +75,8 @@ temp/
*.key
*.pfx
*.p12
*.keystore
*.jks
secrets/
# Wallet data and local runtime state
@@ -91,3 +94,13 @@ settings.local.json
# Local agent/tooling metadata
.agents/
.codex/
.claude/
# Android packages and local SDK config
*.apk
*.aab
local.properties
# Fuzzing artifacts (tests/PalladiumWallet.Fuzz)
findings/
crash-*.bin
AGENTS.md
+111
View File
@@ -0,0 +1,111 @@
# AGENTS.md
This file provides guidance to coding agents (OpenAI Codex and others following the AGENTS.md convention) when working with code in this repository.
> **Sync rule:** `CLAUDE.md` (read by Claude Code) carries the same content as this file, differing only in this header block. Any edit here must be mirrored there in the same commit.
## Role
Operate as an **expert in cryptocurrencies and cryptography**: reason with domain rigor about UTXO consensus, HD key derivation (BIP32/39/SLIP-132), signature schemes and scripts (P2PKH/P2SH/P2WPKH, PSBT), address encoding (base58/bech32), Merkle/SPV proofs, and at-rest encryption. When a choice touches cryptographic correctness or fund safety, judge it through that lens and flag known risks (nonce reuse, missing validation, exposed keys/seed, wrong fee/coin-selection, unverified server responses). Explain trade-offs with technical precision; never take for granted what hasn't been verified.
## Language policy
- **Conversation with the user**: Italian.
- **Code, comments, commit messages, documentation files**: English only.
## How to assist
Before implementing any requested change, judge whether it makes sense and say so plainly. Useful and consistent with the project → proceed. Useless, redundant, already covered elsewhere, or likely to degrade the code → say so with a short rationale and propose the better alternative (or doing nothing). No automatic agreement — an honest opinion is worth more than blind execution.
After implementing a **new feature**, propose the tests needed for proper coverage (unit tests for the new logic, edge cases, error paths; property-based tests where invariants apply; integration tests against `FakeElectrumServer` if network/SPV code is involved; a fuzz target if a new untrusted-input parser was added) — don't just write the feature and stop there.
## What it is
SPV wallet (Sparrow-style) for the **Palladium (PLM)** cryptocurrency, a Bitcoin-derived UTXO chain. Targets desktop (Windows/Linux) and Android from the same source. Lightning is excluded from the first release.
## Stack and structure
.NET 10 + Avalonia UI 12 + NBitcoin.
```
src/Core/ Chain/ Crypto/ Wallet/ Spv/ Net/ Storage/ (no UI dependency)
src/App/ shared Avalonia UI library (App, Views, ViewModels, Loc, Assets)
src/App.Desktop/ desktop head (WinExe): Program.cs, app.manifest, .ico → runnable
src/App.Android/ Android head (net10.0-android): MainApplication/MainActivity → apk
src/Cli/ CLI on the same Core tests/ xUnit
docs/ docs-as-code process + ADRs (one per feature), checked by docs/check-docs.sh
docker/ reproducible release builds (build.sh + pinned Dockerfiles) → dist/
```
- The Avalonia UI lives **once** in `src/App` (a library); the two heads only carry the per-platform entry point and packages.
- `MainView` (UserControl) is the shared root, hosted by `MainWindow` on desktop and as the single-view root on Android.
- **Non-negotiable dependency rule:** `App`/`Cli` depend only on `Core`; the UI reaches network/cryptography only through the wallet domain, never directly. `Core` knows nothing about the UI.
## Commands
.NET 10 SDK lives in `~/.dotnet10` — in non-interactive shells, before any `dotnet` command run
`export PATH="$HOME/.dotnet10:$PATH" DOTNET_ROOT="$HOME/.dotnet10"`.
- **Build:** `dotnet build`
- **Test** (headless, primary verification layer): `dotnet test`
- Single test: `dotnet test --filter "FullyQualifiedName~TestName"`
- Property-based tests (CsCheck, `PropertyTests.cs`) run in the same command, ~30s
- Coverage: `dotnet test tests/PalladiumWallet.Tests --settings tests/coverage.runsettings --collect:"XPlat Code Coverage"` (coverlet, Cobertura XML); CI gates `Core` with `tests/check-coverage.py` (95% lines / 88% branches)
- ViewModel tests are headless (`Avalonia.Headless` via `UiSession`, xunit 2) and CLI tests invoke the real entry point in-process: tests under `tests/PalladiumWallet.Tests/App/` that touch process-wide state (`AppPaths`, `Loc`, `Console`, `MainWindowViewModel.UpdateCheck`/`ProfileOverride`) go in xUnit collection `"AppPaths"`; never let a test reach GitHub or a real indexing server
- Test tree mirrors `src/Core` (`Chain/ Crypto/ Net/ Spv/ Storage/ Wallet/`) — put new tests in the folder matching the code under test
- Network/SPV code (`ElectrumClient`, `WalletSynchronizer`, `TransactionInspector`, TOFU pinning): test against the in-process fake server `tests/PalladiumWallet.Tests/Net/FakeElectrumServer.cs` (loopback TCP + optional TLS, per-method handlers, call counters) — extend that, don't mock the client (it isn't an interface, by design)
- Two `internal` test seams (via `InternalsVisibleTo`) sandbox the remaining externals: `UpdateChecker.CheckAsync` takes an optional `HttpMessageHandler` (never hit GitHub from a test); `AppPaths.BootstrapDirOverride`/`PortableBaseOverride`/`DefaultRootOverride` redirect the machine-global path locations (tests using them share xUnit collection `"AppPaths"` because that state is static)
- **Live server probe** (`tests/PalladiumWallet.ServerProbe`): read-only conformance/health check for real Electrum/Fulcrum/ElectrumX servers (`dotnet run --project tests/PalladiumWallet.ServerProbe -- --server host:port --ssl`, or `--registry`). Also runnable from `dotnet test` via env vars: `PALLADIUM_TEST_SERVERS=host:port,… [PALLADIUM_TEST_SSL=1] [PALLADIUM_TEST_NET=…] dotnet test --filter LiveServer` (no-op when unset, so the default run stays offline)
- **Fuzzing** (`tests/PalladiumWallet.Fuzz`, SharpFuzz): one target per untrusted-input parser (`header merkle slip132 bip39 address coinamount walletdoc encfile peers`), each encoding that parser's error contract — any other escaping exception is a finding
- Seed corpus (incl. regression inputs for past findings) replays inside `dotnet test` via `FuzzCorpusTests`
- Quick smoke without tooling: `dotnet run --project tests/PalladiumWallet.Fuzz -- <target> --random 50000`
- Coverage-guided campaign: `tests/PalladiumWallet.Fuzz/fuzz.sh <target>` (needs afl++ + the SharpFuzz.CommandLine tool)
- After fixing a finding: add the crashing input to `SeedCorpus` in the fuzz project's `Program.cs` and regenerate with `--make-seeds Corpus`
- **GUI hot reload:** `dotnet watch --project src/App.Desktop` (on WSL2/WSLg the window shows on the Windows desktop, no graphics dependencies to install)
- **CLI:** `dotnet run --project src/Cli -- <command>` (no args → usage)
- **CI** (`.github/workflows/ci.yml`, ADR 0032): on every push to `main` and every PR it runs the offline test suite on Ubuntu and Windows, a fuzz smoke per parser target, and `docs/check-docs.sh`. Keep `dotnet test tests/PalladiumWallet.Tests` green locally first; the Android head is deliberately not built in CI
- **Release binaries (all 3 targets):** `./docker/build.sh [windows|linux|android|all]` — reproducible Docker builds (toolchain pinned in `docker/Dockerfile.*`, no SDK needed on host), artifacts in `dist/`, version taken from the App csproj (details in `docker/README.md`)
- Single-file desktop publish needs `-p:IncludeNativeLibrariesForSelfExtract=true` or Avalonia's native libs (Skia/HarfBuzz/ANGLE) stay outside the exe and it silently fails to start
- Android workload dictates the SDK API level — error XA5207 → bump `ANDROID_SDK_PLATFORM` in `Dockerfile.android`
- Android release builds need a persistent signing keystore, generated once with `docker/keystore/generate-keystore.sh` (never commit it, see `docker/keystore/README.md`) — without it every build gets a random signature and users must uninstall to update instead of updating in place
- **Manual publish:** `dotnet publish src/App.Desktop -r win-x64|linux-x64 -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true --self-contained` (AppImage via PupNet Deploy is a future step, no pupnet.conf yet)
**Android (apk):** needs the `android` workload (`dotnet workload install android`), a JDK (`JAVA_HOME`), and the Android SDK (`ANDROID_HOME`, or pass `-p:AndroidSdkDirectory=...`; a plain solution-level `dotnet build` needs it too).
- Provision once: `dotnet build src/App.Android -t:InstallAndroidDependencies -p:AndroidSdkDirectory=$HOME/android-sdk -p:AcceptAndroidSDKLicenses=true`
- Debug apk: `JAVA_HOME=<jdk> dotnet build src/App.Android -c Debug -t:SignAndroidPackage -p:AndroidSdkDirectory=$HOME/android-sdk` → `src/App.Android/bin/Debug/net10.0-android/*-Signed.apk`
- Head is an app, not a library (`<OutputType>Exe</OutputType>`); min SDK 23 (AndroidX requirement)
**CLI** (`src/Cli`): `create`/`restore`/`restore-xpub`/`info`; `sync`/`send`/`servers`/`reset-certs` (`--server host:port [--ssl]`); `newseed`/`addresses`. Default wallet file `~/.palladium-wallet/<network>/wallets/default.wallet.json` (`--file` to change it).
## Architecture (points that require reading multiple files)
- **Layers:** GUI → wallet domain → SPV/Sync → Network → Cryptography → Persistence; each layer depends only downward.
- **Network profile:** all chain constants (address prefixes, BIP32 headers, bech32 HRP, genesis, ports, coin_type 746) **centralized in `Core/Chain`** (`ChainProfiles`/`PalladiumNetworks`), selectable per network (mainnet/testnet/regtest). No scattered magic numbers.
- **LWMA / skip PoW:** LWMA difficulty, 2-minute blocks; an SPV client cannot recompute it → `SkipPowValidation = true`, trust anchored to **hardcoded checkpoints**. This is a custom layer: NBitcoin assumes Bitcoin's retargeting.
- **NBitcoin vs custom:** NBitcoin covers the custom network, BIP32/39, addresses, transactions, PSBT, signing, encoding, hashing — **do not reimplement these**. Hand-written custom code: JSON-RPC client for the indexing server (ElectrumX-like); SPV sync with Merkle verification; header/checkpoint validation; coin selection and fee policy; versioned encrypted JSON wallet file.
- **PSBT-centric:** every signing flow goes through PSBT (offline/air-gapped/multisig/hardware).
- **Ports:** 50001/50002 = indexing server (what the SPV wallet talks to), **not** the node's P2P port (2333).
## GUI conventions (`src/App`)
- **Shared `MainView` + heads:** the whole UI is a single `MainView` (UserControl), working both as a desktop window's content and as Android's single-view root.
- Top-level APIs (file/folder picker, clipboard) are reached via `TopLevel.GetTopLevel(this)` since a UserControl doesn't expose them.
- `MainWindowViewModel.IsDesktop` (from `OperatingSystem.IsAndroid()`) hides filesystem-only features (open-from-file; the data-location wizard step auto-skips on Android because the head sets `AppPaths.OverrideDataRoot`).
- **Single ViewModel** `MainWindowViewModel` (CommunityToolkit.Mvvm: `[ObservableProperty]`, `[RelayCommand]`); `Core` is driven directly from here.
- Split into **partial classes by feature** (`MainWindowViewModel.Send.cs`, `.Receive.cs`, `.Sync.cs`, `.Settings.cs`, `.Wizard.cs`, `.Contacts.cs`, `.Update.cs`, …): new feature logic goes in the matching partial (or a new one), not in the main file.
- **In-app overlays, not OS windows:** details (address, transaction), settings, and help are full-screen `Border`s gated by an `IsXxxOpen` flag, not separate `Window`s — instant open/close, mobile-friendly, and popups/top-levels are slow on WSLg.
- Pattern: bool property + Open/Close commands + backdrop handler and Esc key in `MainView`'s code-behind; overlay close buttons bind via `$parent[UserControl]` (not `$parent[Window]`, absent on mobile).
- Heavy network work runs off the UI thread (`Task.Run`) so the overlay never freezes.
- **Localization:** `Localization/Loc.cs`, key→7 languages dictionary (it/en/es/fr/pt/de/zh); in XAML `{Binding Loc[key]}`, in C# `Loc.Tr("key")`. On language change the `Loc` instance is replaced. The language picker in the Settings overlay (`MainView.axaml`) is a hand-written list of `RadioButton`s bound to `IsLangXx` properties in `MainWindowViewModel.Settings.cs` — it does **not** read `Loc.Languages` dynamically, so a new language needs a button + property added there too, not just a dictionary column.
- **App version:** single source is `<Version>` in `src/App/PalladiumWallet.App.csproj`, read at runtime (`MainWindowViewModel.AppVersion`) and shown in the title. `Core/Net/UpdateChecker.cs` compares it against the latest GitHub release on startup; `MainWindowViewModel.Update.cs` prompts the user if newer.
- **Storage paths:** `Core/Storage/AppPaths` resolves data locations; `AppPaths.OverrideDataRoot` (top priority) is the per-platform seam — the Android head sets it to the app sandbox (`Context.FilesDir`), desktop leaves it null.
## Working rules
- **Cross-implementation tests:** compare addresses, txids, and PSBTs against a reference wallet (golden vectors). A different address or txid is a blocking bug.
- **Security:** seed and private keys never in plaintext on disk/logs/network; every server response validated with Merkle + checkpoints; watch-only truly read-only. `SECURITY.md` is the published threat model (SPV trust boundaries, encryption parameters, key handling) — any change to crypto, SPV validation, or key/seed handling must keep it accurate in the same commit.
- **Docs stay in sync (docs-as-code):** whenever a feature is added or an existing one changes, update the documentation in the same commit — `docs/` (see `docs/docs-as-code.md`), plus `README.md`, `USERGUIDE.md`, `SECURITY.md` and `CHANGELOG.md` where affected.
- Every new feature gets an ADR in `docs/adr/` (from `docs/adr/template.md`, listed in `docs/adr/README.md`); a changed decision gets a new ADR that supersedes the old one, never a rewrite of an Accepted ADR
- Run `./docs/check-docs.sh` before committing; it must pass (ADR numbering/structure, index, cited code paths, links, CLAUDE.md/AGENTS.md sync)
- **Releases:** `./update-version.sh` (interactive) updates `<Version>` in the App csproj (single source), mirrors `ApplicationDisplayVersion` in the Android head, increments `ApplicationVersion` (Android versionCode, **must strictly increase** or users can't update in place), and stubs a `CHANGELOG.md` entry
- Fill in the changelog entry before/with the tag — it's the technical record of what shipped, not optional bookkeeping — then commit and tag manually
CHANGELOG.md
+544
View File
@@ -0,0 +1,544 @@
# Changelog
Technical changelog for PalladiumWallet. Format loosely follows
[Keep a Changelog](https://keepachangelog.com/en/1.0.0/); 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.2.0] — 2026-11-03
Hardens SPV verification (header anchoring fix, recent-block witness cross-check, chain identity
check on connect), makes the network layer fail fast on dead or hostile servers, adds server fee
presets and safer CLI password handling, and fixes a Windows-visible sync race. Also adds a
linux-arm64 build target, CI on GitHub Actions and a much larger automated test suite.
### Documentation
- Docs-as-code process: `docs/` with one ADR per feature, checked by `docs/check-docs.sh`;
the extended test strategy is documented.
- README: the multi-network claim now states that the GUI is mainnet-only and that testnet/regtest
(CLI only) need an explicit `--server`.
### Added
- `linux-arm64` reproducible desktop build target (`./docker/build.sh linux-arm64`), cross-published
from the x64 image, for Raspberry Pi and other 64-bit ARM boards.
- CI on GitHub Actions (ADR 0032): offline test suite on Ubuntu and Windows, fuzz smoke per parser
target and docs checks, on every push to `main` and every PR.
- `tests/PalladiumWallet.ServerProbe`: read-only conformance/health check for real
Electrum/Fulcrum/ElectrumX servers, also runnable from `dotnet test` via environment variables.
- Recent blocks (above the newest checkpoint, which cannot be anchored) are now cross-checked with
a second server: the header at the same height must be identical. The witness is taken only from
the hardcoded bootstrap servers, one extra pinned connection opened on demand. A disagreement at
3+ blocks of depth aborts the sync; a shallower one leaves the proof unverified until the next
sync (possible reorganisation); with no reachable witness behaviour is unchanged. A bounded
proof-of-work check was evaluated and rejected (see ADR 0042).
- History rows and the transaction detail now flag a confirmed transaction in a block above the
newest hardcoded checkpoint as **not anchored** (orange label with an explanatory tooltip).
Such a block cannot be chained to a checkpoint (ADR 0040), so only the Merkle proof against the
server's header backs it; the flag makes the reduced guarantee visible. Not shown on
testnet/regtest, which have no checkpoints. See ADR 0041.
- Fee presets from the server: after connecting, the Send tab offers Fast, Normal and Economy
rates from `blockchain.estimatefee` (2, 6 and 24 blocks) and shows them with the relay fee;
Normal is preselected unless the user already typed a rate. Estimates are converted from
PLM/kB to sat/vB, never go below the relay fee, and implausible values are ignored; without
an estimate the manual field and the 1 sat/vB default remain. A manual rate below the relay
fee is refused before building, and a fee above 1% of the amount sent is flagged in the
preview. Applies to Send and Donate. See ADR 0039.
### Changed
- **CLI (behaviour change):** the wallet password no longer has to be a command-line argument.
It can come from `--password-env NAME`, `--password-stdin`, or a no-echo terminal prompt
(with a confirmation when creating); with no terminal and no password the command fails
instead of hanging. `--password P` still works but prints a warning on stderr (shell history,
process list). Plaintext storage is now an explicit opt-in: `create`/`restore*` without a
password and without `--no-encryption` fail, where before they silently wrote the seed
unencrypted. Scripts that relied on omitting `--password` must add `--no-encryption`.
### Security
- **SPV header anchoring fixed (important).** The chain of headers used to be walked *from* the
nearest checkpoint below a transaction's height *up to* it. With proof of work skipped
(LWMA), that proves nothing: a malicious server could fabricate a header for the block of a
fake transaction and chain fake headers after a real checkpoint, and every link would pass.
The anchor now goes the other way: the header must hash-chain *up to* the nearest checkpoint
at or above its height, whose hash is hardcoded, which cannot be forged. This also covers
blocks below the first checkpoint (heights < 20,000), which were previously unanchored. Blocks
above the newest checkpoint still have nothing to anchor to (only the Merkle proof is
checked): add a recent checkpoint at each release. A wallet cache from an older version is
re-verified once (its "verified" claims are not trusted); headers and transactions are
reused. See ADR 0040.
- Private keys are no longer precomputed for every address in the UI. Address rows and the
address detail sheet carry only public data and derivation coordinates; the WIF is derived
when the user reveals it (after the password) and dropped when hidden, when the sheet closes
or when the wallet closes. Before, the WIF of every listed address sat in UI-bound strings for
the whole session.
### Fixed
- **Sync result overwritten by a stale partial snapshot.** At the end of a sync the final verified
snapshot was applied only after `await`ing the wallet save; a partial (not yet verified)
snapshot still queued on the UI thread could run during that await, replace the cache and be
displayed instead, leaving transactions shown as unverified after a completed sync. The run is
now finalised and applied before the save. Deterministically visible on Windows, where the save
really yields.
- Adding a contact now validates the address for the wallet's network and rejects duplicates
(case-insensitive); whitespace and line breaks in a pasted address are removed. Before, any
string was saved and the error only appeared at send time. Contacts already stored with an
invalid address still load and display.
- The wallet now verifies the chain identity of a server right after connecting: the
`genesis_hash` from `server.features` must match the profile and, on mainnet (which shares
Bitcoin's genesis), the header at the highest checkpoint not above the server's tip must match
the hardcoded one. A server on another chain is refused with an explicit message and the next
known server is tried. Applies to the GUI, peer discovery, the CLI and the server probe.
- `ElectrumClient`: a single server reply is now capped at 16 MiB (`maxLineBytes` in
`ConnectAsync`). A hostile server could stream an endless line with no newline and exhaust the
client's memory; the connection now fails with `InvalidDataException` as soon as the cap is
exceeded.
- `ElectrumClient`: every request is now bounded (30 s, 10 s for the handshake; configurable in
`ConnectAsync`). A server that stops answering without closing the socket made a running sync
wait forever; now the request fails with `TimeoutException`, the connection is marked dead
(`Disconnected` is raised, pending and later requests fail fast) and the app reconnects.
- Fee rate parsing no longer depends on the system culture: on Italian/German systems `1.5`
was read as `15` sat/vB (10x the intended fee). The Send form, the Donate form and the CLI
`--feerate` now share `CoinAmount.TryParseFeeRate` (invariant culture, `.` or `,` as decimal
separator, no thousands separators, range (0, 1000] sat/vB). Donate and the CLI no longer
silently fall back to 1 sat/vB on an invalid value: they report an error.
- `ElectrumClient`: after a protocol error (e.g. a malformed line from the server) the read
loop died but the client kept reporting `IsConnected == true`, and any later request waited
forever for a response that could never arrive. The read loop now marks the connection dead
before failing the pending requests, and `RequestAsync` fails fast with `IOException` on a
dead connection.
### Testing
- Headless ViewModel tests (Avalonia.Headless, no display): wizard flows, password/lock handling,
seed and private-key reveal gating, contacts, settings, sync and send against the fake server.
- In-process end-to-end CLI tests (create/restore/info/sync/send against the fake server).
- Localization consistency tests (7 languages, placeholders, keys used in sources exist).
- Error-path tests for `Core` (empty header range during anchoring, send-all limits, `SyncCache`
roundtrip, derivation edge cases, corrupted config), concurrency tests (in-flight cap, disposal
under load, wallet-lock contention).
- Coverage settings (`tests/coverage.runsettings`) and a coverage gate in CI (`Core`: 95% lines /
88% branches); thread pool minimum raised in tests to avoid starvation; async UI test bodies are
now driven to completion (they previously passed vacuously).
- Test seams: `MainWindowViewModel.UpdateCheck` and `MainWindowViewModel.ProfileOverride`
(internal) so ViewModel tests never reach GitHub or a real indexing server.
## [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 `TextBox`es (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).
CLAUDE.md
+89 -36
View File
@@ -2,57 +2,110 @@
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Cos'è questo progetto
> **Sync rule:** `AGENTS.md` (read by other coding agents) carries the same content as this file, differing only in this header block. Any edit here must be mirrored there in the same commit.
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).
## Role
**La fonte di verità è [blueprint.md](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).
Operate as an **expert in cryptocurrencies and cryptography**: reason with domain rigor about UTXO consensus, HD key derivation (BIP32/39/SLIP-132), signature schemes and scripts (P2PKH/P2SH/P2WPKH, PSBT), address encoding (base58/bech32), Merkle/SPV proofs, and at-rest encryption. When a choice touches cryptographic correctness or fund safety, judge it through that lens and flag known risks (nonce reuse, missing validation, exposed keys/seed, wrong fee/coin-selection, unverified server responses). Explain trade-offs with technical precision; never take for granted what hasn't been verified.
## Stack
## Language policy
.NET 8 + Avalonia UI + NBitcoin (§19 del blueprint). Struttura della solution:
- **Conversation with the user**: Italian.
- **Code, comments, commit messages, documentation files**: English only.
## How to assist
Before implementing any requested change, judge whether it makes sense and say so plainly. Useful and consistent with the project → proceed. Useless, redundant, already covered elsewhere, or likely to degrade the code → say so with a short rationale and propose the better alternative (or doing nothing). No automatic agreement — an honest opinion is worth more than blind execution.
After implementing a **new feature**, propose the tests needed for proper coverage (unit tests for the new logic, edge cases, error paths; property-based tests where invariants apply; integration tests against `FakeElectrumServer` if network/SPV code is involved; a fuzz target if a new untrusted-input parser was added) — don't just write the feature and stop there.
## What it is
SPV wallet (Sparrow-style) for the **Palladium (PLM)** cryptocurrency, a Bitcoin-derived UTXO chain. Targets desktop (Windows/Linux) and Android from the same source. Lightning is excluded from the first release.
## Stack and structure
.NET 10 + Avalonia UI 12 + NBitcoin.
```
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
src/Core/ Chain/ Crypto/ Wallet/ Spv/ Net/ Storage/ (no UI dependency)
src/App/ shared Avalonia UI library (App, Views, ViewModels, Loc, Assets)
src/App.Desktop/ desktop head (WinExe): Program.cs, app.manifest, .ico → runnable
src/App.Android/ Android head (net10.0-android): MainApplication/MainActivity → apk
src/Cli/ CLI on the same Core tests/ xUnit
docs/ docs-as-code process + ADRs (one per feature), checked by docs/check-docs.sh
docker/ reproducible release builds (build.sh + pinned Dockerfiles) → dist/
```
**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.
- The Avalonia UI lives **once** in `src/App` (a library); the two heads only carry the per-platform entry point and packages.
- `MainView` (UserControl) is the shared root, hosted by `MainWindow` on desktop and as the single-view root on Android.
- **Non-negotiable dependency rule:** `App`/`Cli` depend only on `Core`; the UI reaches network/cryptography only through the wallet domain, never directly. `Core` knows nothing about the UI.
## Comandi
## Commands
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`.
.NET 10 SDK lives in `~/.dotnet10` — in non-interactive shells, before any `dotnet` command run
`export PATH="$HOME/.dotnet10:$PATH" DOTNET_ROOT="$HOME/.dotnet10"`.
- 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)
- **Build:** `dotnet build`
- **Test** (headless, primary verification layer): `dotnet test`
- Single test: `dotnet test --filter "FullyQualifiedName~TestName"`
- Property-based tests (CsCheck, `PropertyTests.cs`) run in the same command, ~30s
- Coverage: `dotnet test tests/PalladiumWallet.Tests --settings tests/coverage.runsettings --collect:"XPlat Code Coverage"` (coverlet, Cobertura XML); CI gates `Core` with `tests/check-coverage.py` (95% lines / 88% branches)
- ViewModel tests are headless (`Avalonia.Headless` via `UiSession`, xunit 2) and CLI tests invoke the real entry point in-process: tests under `tests/PalladiumWallet.Tests/App/` that touch process-wide state (`AppPaths`, `Loc`, `Console`, `MainWindowViewModel.UpdateCheck`/`ProfileOverride`) go in xUnit collection `"AppPaths"`; never let a test reach GitHub or a real indexing server
- Test tree mirrors `src/Core` (`Chain/ Crypto/ Net/ Spv/ Storage/ Wallet/`) — put new tests in the folder matching the code under test
- Network/SPV code (`ElectrumClient`, `WalletSynchronizer`, `TransactionInspector`, TOFU pinning): test against the in-process fake server `tests/PalladiumWallet.Tests/Net/FakeElectrumServer.cs` (loopback TCP + optional TLS, per-method handlers, call counters) — extend that, don't mock the client (it isn't an interface, by design)
- Two `internal` test seams (via `InternalsVisibleTo`) sandbox the remaining externals: `UpdateChecker.CheckAsync` takes an optional `HttpMessageHandler` (never hit GitHub from a test); `AppPaths.BootstrapDirOverride`/`PortableBaseOverride`/`DefaultRootOverride` redirect the machine-global path locations (tests using them share xUnit collection `"AppPaths"` because that state is static)
- **Live server probe** (`tests/PalladiumWallet.ServerProbe`): read-only conformance/health check for real Electrum/Fulcrum/ElectrumX servers (`dotnet run --project tests/PalladiumWallet.ServerProbe -- --server host:port --ssl`, or `--registry`). Also runnable from `dotnet test` via env vars: `PALLADIUM_TEST_SERVERS=host:port,… [PALLADIUM_TEST_SSL=1] [PALLADIUM_TEST_NET=…] dotnet test --filter LiveServer` (no-op when unset, so the default run stays offline)
- **Fuzzing** (`tests/PalladiumWallet.Fuzz`, SharpFuzz): one target per untrusted-input parser (`header merkle slip132 bip39 address coinamount walletdoc encfile peers`), each encoding that parser's error contract — any other escaping exception is a finding
- Seed corpus (incl. regression inputs for past findings) replays inside `dotnet test` via `FuzzCorpusTests`
- Quick smoke without tooling: `dotnet run --project tests/PalladiumWallet.Fuzz -- <target> --random 50000`
- Coverage-guided campaign: `tests/PalladiumWallet.Fuzz/fuzz.sh <target>` (needs afl++ + the SharpFuzz.CommandLine tool)
- After fixing a finding: add the crashing input to `SeedCorpus` in the fuzz project's `Program.cs` and regenerate with `--make-seeds Corpus`
- **GUI hot reload:** `dotnet watch --project src/App.Desktop` (on WSL2/WSLg the window shows on the Windows desktop, no graphics dependencies to install)
- **CLI:** `dotnet run --project src/Cli -- <command>` (no args → usage)
- **CI** (`.github/workflows/ci.yml`, ADR 0032): on every push to `main` and every PR it runs the offline test suite on Ubuntu and Windows, a fuzz smoke per parser target, and `docs/check-docs.sh`. Keep `dotnet test tests/PalladiumWallet.Tests` green locally first; the Android head is deliberately not built in CI
- **Release binaries (all 3 targets):** `./docker/build.sh [windows|linux|android|all]` — reproducible Docker builds (toolchain pinned in `docker/Dockerfile.*`, no SDK needed on host), artifacts in `dist/`, version taken from the App csproj (details in `docker/README.md`)
- Single-file desktop publish needs `-p:IncludeNativeLibrariesForSelfExtract=true` or Avalonia's native libs (Skia/HarfBuzz/ANGLE) stay outside the exe and it silently fails to start
- Android workload dictates the SDK API level — error XA5207 → bump `ANDROID_SDK_PLATFORM` in `Dockerfile.android`
- Android release builds need a persistent signing keystore, generated once with `docker/keystore/generate-keystore.sh` (never commit it, see `docker/keystore/README.md`) — without it every build gets a random signature and users must uninstall to update instead of updating in place
- **Manual publish:** `dotnet publish src/App.Desktop -r win-x64|linux-x64 -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true --self-contained` (AppImage via PupNet Deploy is a future step, no pupnet.conf yet)
La logica core e la crypto si testano senza GUI né rete reale; la GUI serve solo per rifinire l'interfaccia (§19.7).
**Android (apk):** needs the `android` workload (`dotnet workload install android`), a JDK (`JAVA_HOME`), and the Android SDK (`ANDROID_HOME`, or pass `-p:AndroidSdkDirectory=...`; a plain solution-level `dotnet build` needs it too).
- Provision once: `dotnet build src/App.Android -t:InstallAndroidDependencies -p:AndroidSdkDirectory=$HOME/android-sdk -p:AcceptAndroidSDKLicenses=true`
- Debug apk: `JAVA_HOME=<jdk> dotnet build src/App.Android -c Debug -t:SignAndroidPackage -p:AndroidSdkDirectory=$HOME/android-sdk` → `src/App.Android/bin/Debug/net10.0-android/*-Signed.apk`
- Head is an app, not a library (`<OutputType>Exe</OutputType>`); min SDK 23 (AndroidX requirement)
## Comandi CLI principali (src/Cli)
**CLI** (`src/Cli`): `create`/`restore`/`restore-xpub`/`info`; `sync`/`send`/`servers`/`reset-certs` (`--server host:port [--ssl]`); `newseed`/`addresses`. Default wallet file `~/.palladium-wallet/<network>/wallets/default.wallet.json` (`--file` to change it).
`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`).
## Architecture (points that require reading multiple files)
## Architettura — punti che richiedono più file per essere capiti
- **Layers:** GUI → wallet domain → SPV/Sync → Network → Cryptography → Persistence; each layer depends only downward.
- **Network profile:** all chain constants (address prefixes, BIP32 headers, bech32 HRP, genesis, ports, coin_type 746) **centralized in `Core/Chain`** (`ChainProfiles`/`PalladiumNetworks`), selectable per network (mainnet/testnet/regtest). No scattered magic numbers.
- **LWMA / skip PoW:** LWMA difficulty, 2-minute blocks; an SPV client cannot recompute it → `SkipPowValidation = true`, trust anchored to **hardcoded checkpoints**. This is a custom layer: NBitcoin assumes Bitcoin's retargeting.
- **NBitcoin vs custom:** NBitcoin covers the custom network, BIP32/39, addresses, transactions, PSBT, signing, encoding, hashing — **do not reimplement these**. Hand-written custom code: JSON-RPC client for the indexing server (ElectrumX-like); SPV sync with Merkle verification; header/checkpoint validation; coin selection and fee policy; versioned encrypted JSON wallet file.
- **PSBT-centric:** every signing flow goes through PSBT (offline/air-gapped/multisig/hardware).
- **Ports:** 50001/50002 = indexing server (what the SPV wallet talks to), **not** the node's P2P port (2333).
- **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.
## GUI conventions (`src/App`)
## Regole di lavoro
- **Shared `MainView` + heads:** the whole UI is a single `MainView` (UserControl), working both as a desktop window's content and as Android's single-view root.
- Top-level APIs (file/folder picker, clipboard) are reached via `TopLevel.GetTopLevel(this)` since a UserControl doesn't expose them.
- `MainWindowViewModel.IsDesktop` (from `OperatingSystem.IsAndroid()`) hides filesystem-only features (open-from-file; the data-location wizard step auto-skips on Android because the head sets `AppPaths.OverrideDataRoot`).
- **Single ViewModel** `MainWindowViewModel` (CommunityToolkit.Mvvm: `[ObservableProperty]`, `[RelayCommand]`); `Core` is driven directly from here.
- Split into **partial classes by feature** (`MainWindowViewModel.Send.cs`, `.Receive.cs`, `.Sync.cs`, `.Settings.cs`, `.Wizard.cs`, `.Contacts.cs`, `.Update.cs`, …): new feature logic goes in the matching partial (or a new one), not in the main file.
- **In-app overlays, not OS windows:** details (address, transaction), settings, and help are full-screen `Border`s gated by an `IsXxxOpen` flag, not separate `Window`s — instant open/close, mobile-friendly, and popups/top-levels are slow on WSLg.
- Pattern: bool property + Open/Close commands + backdrop handler and Esc key in `MainView`'s code-behind; overlay close buttons bind via `$parent[UserControl]` (not `$parent[Window]`, absent on mobile).
- Heavy network work runs off the UI thread (`Task.Run`) so the overlay never freezes.
- **Localization:** `Localization/Loc.cs`, key→7 languages dictionary (it/en/es/fr/pt/de/zh); in XAML `{Binding Loc[key]}`, in C# `Loc.Tr("key")`. On language change the `Loc` instance is replaced. The language picker in the Settings overlay (`MainView.axaml`) is a hand-written list of `RadioButton`s bound to `IsLangXx` properties in `MainWindowViewModel.Settings.cs` — it does **not** read `Loc.Languages` dynamically, so a new language needs a button + property added there too, not just a dictionary column.
- **App version:** single source is `<Version>` in `src/App/PalladiumWallet.App.csproj`, read at runtime (`MainWindowViewModel.AppVersion`) and shown in the title. `Core/Net/UpdateChecker.cs` compares it against the latest GitHub release on startup; `MainWindowViewModel.Update.cs` prompts the user if newer.
- **Storage paths:** `Core/Storage/AppPaths` resolves data locations; `AppPaths.OverrideDataRoot` (top priority) is the per-platform seam — the Android head sets it to the app sandbox (`Context.FilesDir`), desktop leaves it null.
- **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.
## Working rules
- **Cross-implementation tests:** compare addresses, txids, and PSBTs against a reference wallet (golden vectors). A different address or txid is a blocking bug.
- **Security:** seed and private keys never in plaintext on disk/logs/network; every server response validated with Merkle + checkpoints; watch-only truly read-only. `SECURITY.md` is the published threat model (SPV trust boundaries, encryption parameters, key handling) — any change to crypto, SPV validation, or key/seed handling must keep it accurate in the same commit.
- **Docs stay in sync (docs-as-code):** whenever a feature is added or an existing one changes, update the documentation in the same commit — `docs/` (see `docs/docs-as-code.md`), plus `README.md`, `USERGUIDE.md`, `SECURITY.md` and `CHANGELOG.md` where affected.
- Every new feature gets an ADR in `docs/adr/` (from `docs/adr/template.md`, listed in `docs/adr/README.md`); a changed decision gets a new ADR that supersedes the old one, never a rewrite of an Accepted ADR
- Run `./docs/check-docs.sh` before committing; it must pass (ADR numbering/structure, index, cited code paths, links, CLAUDE.md/AGENTS.md sync)
- **Releases:** `./update-version.sh` (interactive) updates `<Version>` in the App csproj (single source), mirrors `ApplicationDisplayVersion` in the Android head, increments `ApplicationVersion` (Android versionCode, **must strictly increase** or users can't update in place), and stubs a `CHANGELOG.md` entry
- Fill in the changelog entry before/with the tag — it's the technical record of what shipped, not optional bookkeeping — then commit and tag manually
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 Davide Grilli
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
PalladiumWallet.sln
+149 -50
View File
@@ -1,50 +1,149 @@
Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17
VisualStudioVersion = 17.0.31903.59
MinimumVisualStudioVersion = 10.0.40219.1
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{84E60614-5042-48EC-B349-290FB0CA7BA8}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.Core", "src\Core\PalladiumWallet.Core.csproj", "{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.App", "src\App\PalladiumWallet.App.csproj", "{13EE9780-5810-4229-BFCF-6003172534DD}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.Cli", "src\Cli\PalladiumWallet.Cli.csproj", "{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{FDF1822C-58D6-4B35-93EA-6A85E1292933}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.Tests", "tests\PalladiumWallet.Tests\PalladiumWallet.Tests.csproj", "{C7E79E8E-B1DE-4053-9FB4-853814766CE0}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Release|Any CPU = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
EndGlobalSection
GlobalSection(ProjectConfigurationPlatforms) = postSolution
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Debug|Any CPU.Build.0 = Debug|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Release|Any CPU.ActiveCfg = Release|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Release|Any CPU.Build.0 = Release|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Debug|Any CPU.Build.0 = Debug|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Release|Any CPU.ActiveCfg = Release|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Release|Any CPU.Build.0 = Release|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Debug|Any CPU.Build.0 = Debug|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Release|Any CPU.ActiveCfg = Release|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Release|Any CPU.Build.0 = Release|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Debug|Any CPU.Build.0 = Debug|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Release|Any CPU.ActiveCfg = Release|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Release|Any CPU.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(NestedProjects) = preSolution
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{13EE9780-5810-4229-BFCF-6003172534DD} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{C7E79E8E-B1DE-4053-9FB4-853814766CE0} = {FDF1822C-58D6-4B35-93EA-6A85E1292933}
EndGlobalSection
EndGlobal
Microsoft Visual Studio Solution File, Format Version 12.00
# Visual Studio Version 17
VisualStudioVersion = 17.0.31903.59
MinimumVisualStudioVersion = 10.0.40219.1
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{84E60614-5042-48EC-B349-290FB0CA7BA8}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.Core", "src\Core\PalladiumWallet.Core.csproj", "{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.App", "src\App\PalladiumWallet.App.csproj", "{13EE9780-5810-4229-BFCF-6003172534DD}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.Cli", "src\Cli\PalladiumWallet.Cli.csproj", "{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{FDF1822C-58D6-4B35-93EA-6A85E1292933}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.Tests", "tests\PalladiumWallet.Tests\PalladiumWallet.Tests.csproj", "{C7E79E8E-B1DE-4053-9FB4-853814766CE0}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.App.Desktop", "src\App.Desktop\PalladiumWallet.App.Desktop.csproj", "{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.App.Android", "src\App.Android\PalladiumWallet.App.Android.csproj", "{BCC5BE4A-B909-4043-B0FB-B5A839349578}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.Fuzz", "tests\PalladiumWallet.Fuzz\PalladiumWallet.Fuzz.csproj", "{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Core", "Core", "{BF9B33E3-314A-3621-C1F0-AFD074692421}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "PalladiumWallet.ServerProbe", "tests\PalladiumWallet.ServerProbe\PalladiumWallet.ServerProbe.csproj", "{4CB51620-11B7-47E9-9971-A999E49D1CE1}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Debug|x64 = Debug|x64
Debug|x86 = Debug|x86
Release|Any CPU = Release|Any CPU
Release|x64 = Release|x64
Release|x86 = Release|x86
EndGlobalSection
GlobalSection(ProjectConfigurationPlatforms) = postSolution
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Debug|Any CPU.Build.0 = Debug|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Debug|x64.ActiveCfg = Debug|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Debug|x64.Build.0 = Debug|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Debug|x86.ActiveCfg = Debug|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Debug|x86.Build.0 = Debug|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Release|Any CPU.ActiveCfg = Release|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Release|Any CPU.Build.0 = Release|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Release|x64.ActiveCfg = Release|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Release|x64.Build.0 = Release|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Release|x86.ActiveCfg = Release|Any CPU
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978}.Release|x86.Build.0 = Release|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Debug|Any CPU.Build.0 = Debug|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Debug|x64.ActiveCfg = Debug|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Debug|x64.Build.0 = Debug|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Debug|x86.ActiveCfg = Debug|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Debug|x86.Build.0 = Debug|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Release|Any CPU.ActiveCfg = Release|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Release|Any CPU.Build.0 = Release|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Release|x64.ActiveCfg = Release|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Release|x64.Build.0 = Release|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Release|x86.ActiveCfg = Release|Any CPU
{13EE9780-5810-4229-BFCF-6003172534DD}.Release|x86.Build.0 = Release|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Debug|Any CPU.Build.0 = Debug|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Debug|x64.ActiveCfg = Debug|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Debug|x64.Build.0 = Debug|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Debug|x86.ActiveCfg = Debug|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Debug|x86.Build.0 = Debug|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Release|Any CPU.ActiveCfg = Release|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Release|Any CPU.Build.0 = Release|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Release|x64.ActiveCfg = Release|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Release|x64.Build.0 = Release|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Release|x86.ActiveCfg = Release|Any CPU
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416}.Release|x86.Build.0 = Release|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Debug|Any CPU.Build.0 = Debug|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Debug|x64.ActiveCfg = Debug|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Debug|x64.Build.0 = Debug|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Debug|x86.ActiveCfg = Debug|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Debug|x86.Build.0 = Debug|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Release|Any CPU.ActiveCfg = Release|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Release|Any CPU.Build.0 = Release|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Release|x64.ActiveCfg = Release|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Release|x64.Build.0 = Release|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Release|x86.ActiveCfg = Release|Any CPU
{C7E79E8E-B1DE-4053-9FB4-853814766CE0}.Release|x86.Build.0 = Release|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Debug|Any CPU.Build.0 = Debug|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Debug|x64.ActiveCfg = Debug|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Debug|x64.Build.0 = Debug|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Debug|x86.ActiveCfg = Debug|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Debug|x86.Build.0 = Debug|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Release|Any CPU.ActiveCfg = Release|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Release|Any CPU.Build.0 = Release|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Release|x64.ActiveCfg = Release|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Release|x64.Build.0 = Release|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Release|x86.ActiveCfg = Release|Any CPU
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7}.Release|x86.Build.0 = Release|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Debug|Any CPU.Build.0 = Debug|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Debug|x64.ActiveCfg = Debug|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Debug|x64.Build.0 = Debug|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Debug|x86.ActiveCfg = Debug|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Debug|x86.Build.0 = Debug|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Release|Any CPU.ActiveCfg = Release|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Release|Any CPU.Build.0 = Release|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Release|x64.ActiveCfg = Release|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Release|x64.Build.0 = Release|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Release|x86.ActiveCfg = Release|Any CPU
{BCC5BE4A-B909-4043-B0FB-B5A839349578}.Release|x86.Build.0 = Release|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Debug|Any CPU.Build.0 = Debug|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Debug|x64.ActiveCfg = Debug|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Debug|x64.Build.0 = Debug|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Debug|x86.ActiveCfg = Debug|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Debug|x86.Build.0 = Debug|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Release|Any CPU.ActiveCfg = Release|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Release|Any CPU.Build.0 = Release|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Release|x64.ActiveCfg = Release|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Release|x64.Build.0 = Release|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Release|x86.ActiveCfg = Release|Any CPU
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C}.Release|x86.Build.0 = Release|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Debug|Any CPU.Build.0 = Debug|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Debug|x64.ActiveCfg = Debug|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Debug|x64.Build.0 = Debug|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Debug|x86.ActiveCfg = Debug|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Debug|x86.Build.0 = Debug|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Release|Any CPU.ActiveCfg = Release|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Release|Any CPU.Build.0 = Release|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Release|x64.ActiveCfg = Release|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Release|x64.Build.0 = Release|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Release|x86.ActiveCfg = Release|Any CPU
{4CB51620-11B7-47E9-9971-A999E49D1CE1}.Release|x86.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
EndGlobalSection
GlobalSection(NestedProjects) = preSolution
{A7D0EF95-B206-4646-99DD-1D2BBB7AF978} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{13EE9780-5810-4229-BFCF-6003172534DD} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{D1AE035A-6DAC-46F4-90FB-F1AE2A79D416} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{C7E79E8E-B1DE-4053-9FB4-853814766CE0} = {FDF1822C-58D6-4B35-93EA-6A85E1292933}
{A5D1DD48-7485-43F0-BFE3-2F645EC4D1E7} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{BCC5BE4A-B909-4043-B0FB-B5A839349578} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{BC5932E5-E6F7-42A2-AC39-697C9A737A3C} = {FDF1822C-58D6-4B35-93EA-6A85E1292933}
{BF9B33E3-314A-3621-C1F0-AFD074692421} = {84E60614-5042-48EC-B349-290FB0CA7BA8}
{4CB51620-11B7-47E9-9971-A999E49D1CE1} = {FDF1822C-58D6-4B35-93EA-6A85E1292933}
EndGlobalSection
EndGlobal
README.md
+402
View File
@@ -0,0 +1,402 @@
# Palladium Wallet
**An SPV wallet built specifically for the Palladium (PLM) cryptocurrency** and optimized for its chain. Runs on desktop (Windows/Linux) and Android from a single shared codebase.
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 or from plain addresses (no key material at all).
- **PSBT-centric**: signing flows go through PSBT (offline / air-gapped); watch-only wallets export an unsigned PSBT for offline signing. Multisig script kinds are defined in the network profile but not yet implemented (planned, see `Core/Crypto/DerivationPaths.cs`).
- **Multi-network**: mainnet, testnet, regtest in the core and the CLI (`--net`); the GUI works on mainnet only. Testnet and regtest ship without bootstrap servers or checkpoints, so pass `--server host:port`.
- **Cross-platform**: desktop (Windows/Linux) and Android share one Avalonia UI; a **CLI** runs on the same core.
- **Multilingual**: Italian, English, Spanish, French, Portuguese, German, Chinese (Simplified).
## Architecture
```
PalladiumWallet.sln
├─ src/Core/ Chain/ Crypto/ Wallet/ Spv/ Net/ Storage/ (no UI dependency)
├─ src/App/ shared Avalonia UI library (Views, ViewModels, Loc, Assets)
├─ src/App.Desktop/ desktop head (Windows/Linux) → runnable
├─ src/App.Android/ Android head → apk
├─ src/Cli/ CLI on the same Core
└─ tests/ xUnit
```
The UI is written **once** in `src/App`; the desktop and Android heads only add the per-platform
entry point and packages.
Stack: **.NET 10 + Avalonia UI 12 + NBitcoin**.
---
## Development environment
For desktop and the CLI you only need the **.NET 10 SDK**. The core and crypto are fully testable without the GUI or a real network.
### Windows
1. Install the .NET 10 SDK:
```powershell
winget install Microsoft.DotNet.SDK.10
```
(alternatively, the installer from <https://dotnet.microsoft.com/download/dotnet/10.0>)
2. Clone the repository and restore dependencies:
```powershell
git clone https://github.com/palladium-coin/palladium-wallet.git
cd PalladiumWallet
dotnet restore
```
### Linux
1. Install the .NET 10 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 10.0 --install-dir "$HOME/.dotnet10"
export PATH="$HOME/.dotnet10:$PATH" DOTNET_ROOT="$HOME/.dotnet10"
```
(add the two `export` lines to your `~/.bashrc` to make them permanent)
2. Clone and restore:
```bash
git clone https://github.com/palladium-coin/palladium-wallet.git
cd PalladiumWallet
dotnet restore
```
> The GUI uses Avalonia, which runs natively on Windows and Linux with no extra graphics dependencies.
### Android (additional setup)
Building the apk also requires the Android workload, a JDK, and the Android SDK:
```bash
dotnet workload install android # .NET Android build packs
# JDK 17+ must be available (set JAVA_HOME)
# Provision the Android SDK once into ~/android-sdk:
dotnet build src/App.Android -t:InstallAndroidDependencies \
-p:AndroidSdkDirectory=$HOME/android-sdk -p:AcceptAndroidSDKLicenses=true
```
To run the apk on an emulator (instead of a physical device), see
[*Android emulator (developer setup)*](#android-emulator-developer-setup) below.
---
## Running it
### Desktop GUI in debug (Linux & Windows)
The desktop head runs the same way on both OSes (`Debug` is the default configuration). Run it from
the repo root:
```bash
dotnet run --project src/App.Desktop # single run (Debug)
dotnet watch --project src/App.Desktop # with hot reload (edit XAML/C# and see changes live)
dotnet run --project src/App.Desktop -c Release # to try the Release config
```
- **Linux** — runs natively on X11/Wayland, no extra graphics packages. On **WSL2** the window
appears on the Windows desktop through WSLg (already working here, nothing to install).
- **Windows** — runs natively; use the same commands from PowerShell or a terminal.
The app writes its data under the per-user data folder (see *User guide → First launch*); delete it
to start from a clean first-run wizard.
### CLI
Same core, useful for scripts and headless environments:
```bash
dotnet run --project src/Cli -- <command>
```
Run without arguments for the full list of commands.
### Android
There is no `dotnet run` for a phone: build the apk and install it (see *Building → Android apk*),
or run it on an emulator (see *Android emulator (developer setup)*).
---
## Running tests
Tests are the **primary verification layer** — the core logic and crypto run headless, without the GUI or a real network.
Every push to `main` and every pull request runs the offline suite on Ubuntu and Windows, plus a fuzz smoke and the docs checks, via GitHub Actions (`.github/workflows/ci.yml`).
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
```
Measure code coverage (the [coverlet](https://github.com/coverlet-coverage/coverlet) collector is already referenced; the report is a Cobertura XML under `TestResults/`). `tests/coverage.runsettings` excludes the test tooling, and `tests/check-coverage.py` applies the same gate as CI:
```bash
dotnet test tests/PalladiumWallet.Tests --settings tests/coverage.runsettings --collect:"XPlat Code Coverage"
python3 tests/check-coverage.py TestResults/*/coverage.cobertura.xml PalladiumWallet.Core:95:88
```
Run the tests against a real indexing server (opt-in, skipped when the variable is unset):
```bash
PALLADIUM_TEST_SERVERS=host:50002 PALLADIUM_TEST_SSL=1 dotnet test --filter LiveServer
```
> Cross-implementation tests compare addresses, txids and PSBTs against reference golden vectors: a different address or txid is a blocking bug.
### What the suite covers
The tests mirror the `Core` layout (`tests/PalladiumWallet.Tests/<area>/`):
| Area | What is verified |
|---|---|
| `Chain/` | Network profiles (prefixes, ports, coin type 746, SLIP-132 headers), NBitcoin network registration and the `INetworkSet` plumbing |
| `Crypto/` | BIP39 (official Trezor vectors, NFKD normalisation, all 8 supported wordlist languages), BIP32/44/49/84/86 derivation against public golden vectors, SLIP-132 encode/decode including corrupted-payload rejection, HD and imported-key accounts (fund-safety fallbacks for out-of-range indices), watch-only isolation |
| `Spv/` | Scripthash (vectors computed independently in Python), Merkle proofs (Bitcoin block 100000 + random trees), header parsing and PoW target validation, and the full **`WalletSynchronizer`**: gap-limit scanning, UTXO/history reconstruction, unconfirmed/immature balances, busy-retry, disk-cache reuse — including the paths where a lying server fails Merkle verification or serves a header chain that does not anchor to a hardcoded checkpoint, and the sync must abort |
| `Net/` | JSON-RPC transport (pipelining, error mapping, notifications, disconnection, cancellation, oversized responses), typed protocol wrappers, peer discovery/persistence, TLS trust-on-first-use pinning end-to-end (pin, match, mismatch, reset), the update check end-to-end via a stubbed HTTP transport (newer/equal/older tags, HTTP errors, malformed JSON, offline — all best-effort to null) |
| `Storage/` | AES-GCM encryption (roundtrip, tampering, fresh salt/nonce), wallet document schema/versioning, atomic saves, single-instance lock, data-path resolution with its full precedence chain (override → portable → pointer file → default) |
| `App/` | Headless ViewModel tests (Avalonia.Headless): wizard flows, password and file-lock handling, seed and private-key reveal gating, contacts, settings, sync and send against the fake server; in-process end-to-end CLI tests; localization consistency (7 languages, placeholders, keys used in sources exist) |
| `Wallet/` | Transaction building and signing (spendability rules, coinbase maturity, dust change, multi-UTXO selection, all standard destination types, watch-only PSBT flow, a golden txid for the PSBT signing path, standardness-policy rejection of absurd fees), transaction detail assembly (fees, mine/theirs attribution, RBF, coinbase), amount parsing/formatting, corrupted-wallet-file rejection |
Network-facing code is tested against an **in-process fake ElectrumX server**
(`tests/PalladiumWallet.Tests/Net/FakeElectrumServer.cs`): a real loopback TCP
socket speaking newline-delimited JSON-RPC (optionally TLS with a self-signed
certificate), with per-method handlers and call counters. Client, synchroniser
and inspector therefore exercise the same code paths used in production —
framing, retries, TLS pinning included — without any external dependency.
The suite also includes **property-based tests** ([CsCheck](https://github.com/AnthonyLloyd/CsCheck)) in `tests/PalladiumWallet.Tests/PropertyTests.cs`. These generate hundreds of random inputs per test and verify invariants that must hold universally — no crash on arbitrary strings, encrypt/decrypt roundtrip for any plaintext and password, SLIP-132 key roundtrip for every script kind and network, every leaf in a randomly-built Merkle tree verifies against its root. They run automatically with `dotnet test` and take ~30 s.
### Fuzzing
`tests/PalladiumWallet.Fuzz` fuzzes every parser that consumes untrusted input
(server-supplied headers/proofs/peer lists, wallet files, user-pasted
keys/mnemonics/addresses/amounts) via [SharpFuzz](https://github.com/Metalnem/sharpfuzz):
each target enforces the parser's documented error contract, so any other
exception escaping is a finding. The seed corpus — including a regression input
for every crash found so far — replays automatically inside `dotnet test`;
coverage-guided campaigns run separately with afl++ (`tests/PalladiumWallet.Fuzz/fuzz.sh`),
and a built-in random-mutation mode (`dotnet run -- <target> --random N`) needs
no external tooling. See `tests/PalladiumWallet.Fuzz/README.md`.
---
## Building
### Reproducible builds (Docker) — recommended for release binaries
All three distribution targets (Windows exe, Linux binary, Android apk) can be
built with one command inside Docker, with **no SDK installed on the host**:
```bash
./docker/build.sh # interactive menu, or: ./docker/build.sh all
```
Why build this way: the whole toolchain is pinned in the Dockerfiles, so every
build uses exactly the same SDK versions regardless of the host machine — no
toolchain drift between releases — and the build environment itself is
reviewable in the repo. For a wallet this is a trust property, not a
convenience: anyone can rebuild the published binaries from source and check
they were produced by the process the repository declares.
See [docker/README.md](docker/README.md) for prerequisites, usage, how to run
each produced artifact, and troubleshooting. The sections below cover manual
builds with a locally installed SDK (the normal path during development).
### Development build
```bash
dotnet build # whole solution (debug)
dotnet build src/App.Desktop # desktop head only
```
> A solution-wide `dotnet build` also builds the Android head, which needs the Android SDK
> (see *Android emulator (developer setup)* below). If you don't have it, build the specific
> non-Android projects (`src/App.Desktop`, `src/Cli`, `tests/...`).
### Desktop release (self-contained)
```bash
# Windows — single self-contained .exe (output: src/App.Desktop/bin/Release/net10.0/win-x64/publish/PalladiumWallet.exe)
# IncludeNativeLibrariesForSelfExtract embeds Avalonia's native libs (Skia, HarfBuzz, ANGLE):
# without it they stay as separate DLLs and the .exe alone silently fails to start.
dotnet publish src/App.Desktop -c Release -r win-x64 -p:PublishSingleFile=true \
-p:IncludeNativeLibrariesForSelfExtract=true --self-contained
# Linux — self-contained; AppImage then produced with PupNet Deploy
# (output: src/App.Desktop/bin/Release/net10.0/linux-x64/publish/PalladiumWallet)
dotnet publish src/App.Desktop -c Release -r linux-x64 --self-contained
```
[PupNet Deploy](https://github.com/kuiperzone/PupNet-Deploy) turns the Linux publish into an AppImage.
The executable is named `PalladiumWallet` (set via `<AssemblyName>` in the desktop head).
### Android apk
Prerequisites: the Android workload + SDK (see *Development environment → Android*). The Android
head already sets `<EmbedAssembliesIntoApk>true</EmbedAssembliesIntoApk>`, so the apk is
**self-contained** and installs/runs standalone (a Fast-Deployment debug apk crashes at launch
with "No assemblies found" when installed without `adb`).
```bash
# Default debug apk — all ABIs (arm64-v8a + x86_64): runs on phones AND the x86_64 emulator.
# ~79 MB. Output: src/App.Android/bin/Debug/net10.0-android/*-Signed.apk
JAVA_HOME=<jdk-path> dotnet build src/App.Android -c Debug -t:SignAndroidPackage \
-p:AndroidSdkDirectory=$HOME/android-sdk
# Smaller apk for a real phone — arm64 only (~41 MB):
JAVA_HOME=<jdk-path> dotnet build src/App.Android -c Debug -t:SignAndroidPackage \
-p:AndroidSdkDirectory=$HOME/android-sdk -p:AbiArm64Only=true
```
The ABI restriction uses the `AbiArm64Only` flag, which is scoped to the Android head's
`<RuntimeIdentifiers>` in its csproj — do **not** pass `-p:RuntimeIdentifiers=android-arm64` on the
command line, it leaks to the `net10.0` projects (`Core`/`App`) and breaks the build. (The legacy
`AndroidSupportedAbis` property is deprecated and ignored.)
(Set `ANDROID_HOME` to skip the `-p:AndroidSdkDirectory` flag.) This debug apk is fine for personal
sideloading, but debug builds are signed with a key regenerated per build machine/container, so a
newer debug apk won't install over an older one without an uninstall first. For a stable signature
across releases (needed to update an existing install in place), build via
`./docker/build.sh android` instead — see [docker/keystore/README.md](docker/keystore/README.md).
> **Verification status.** The default multi-ABI apk is verified running on the x86_64 emulator
> (UI renders, connects to a server over TLS). The arm64-only apk builds correctly (41 MB,
> `arm64-v8a` only) but is meant for a physical arm64 phone — on the x86_64 emulator it only runs
> through slow ARM translation and stalls on the splash, so **verify it on a real device**.
### Version
The application **version** is set in a single place: the `<Version>` tag in
[`src/App/PalladiumWallet.App.csproj`](src/App/PalladiumWallet.App.csproj). It appears in the desktop
window title, in the Help dialog, and is stamped into the published binaries (and the apk's versionName).
---
## Android emulator (developer setup)
How to run the apk without a physical device. Paths assume the Android SDK in `~/android-sdk`
and a JDK at `JAVA_HOME` (JDK 17+). Tested on Linux / WSL2.
**1. Install the emulator, a system image and the matching platform** (once):
```bash
SDK=$HOME/android-sdk
$SDK/cmdline-tools/latest/bin/sdkmanager --sdk_root=$SDK \
"emulator" "system-images;android-34;google_apis;x86_64" "platforms;android-34"
```
Use an `x86_64` image so the emulator runs with hardware acceleration (KVM); the app's min SDK is 23.
**2. Hardware acceleration (Linux/WSL2)** — the emulator needs access to `/dev/kvm`. Add yourself
to the `kvm` group once, then start a new shell (or prefix the launch with `sg kvm -c '…'`):
```bash
sudo usermod -aG kvm $USER
```
On WSL2, KVM must be enabled on the Windows host (nested virtualization); the emulator window is
shown on the Windows desktop through WSLg.
**3. Create an AVD** (virtual device):
```bash
echo no | $SDK/cmdline-tools/latest/bin/avdmanager create avd \
-n plm -k "system-images;android-34;google_apis;x86_64" -d pixel
```
**4. Launch the emulator** (software GL is the most robust under WSLg):
```bash
$SDK/emulator/emulator -avd plm -gpu swiftshader_indirect -no-snapshot -no-audio &
$SDK/platform-tools/adb wait-for-device
# wait for full boot:
until [ "$($SDK/platform-tools/adb shell getprop sys.boot_completed | tr -d '\r')" = 1 ]; do sleep 2; done
```
If the window won't render, add `-no-window` and rely on `adb` + screenshots
(`adb exec-out screencap -p > shot.png`).
**5. Install and run the apk; capture logs to debug crashes:**
```bash
ADB=$SDK/platform-tools/adb
$ADB install -r src/App.Android/bin/Debug/net10.0-android/*-Signed.apk
$ADB shell monkey -p io.github.davide3011.palladiumwallet -c android.intent.category.LAUNCHER 1
$ADB logcat -d | grep -iE "monodroid|exception|fatal|avalonia"
```
**VS Code "Android iOS Emulator" extension** (optional, click-to-launch): it only starts an
existing AVD, so create one first (step 3). Point it at the emulator binary:
```jsonc
// VS Code settings.json
"emulator.emulatorPathLinux": "/home/<user>/android-sdk/emulator"
// on WSL, use: "emulator.emulatorPathWSL": "/home/<user>/android-sdk/emulator"
```
---
## User guide (quick)
A condensed overview follows; for the complete, exhaustive walkthrough (every screen, every
validation rule, troubleshooting) see [USERGUIDE.md](USERGUIDE.md).
### First launch
1. On first launch (desktop), choose **where to store data** (wallet, configuration, certificates) — the default path or a folder of your choice. On Android this step is skipped: data lives in the app's private sandbox.
2. Create a new wallet, restore from seed, or open one of the wallets already in your data folder.
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.
> **Desktop vs Android.** The UI and features are the same on both. Differences: on Android the
> data-location step is skipped (fixed app sandbox) and *File → Open wallet from file* (importing a
> wallet from an arbitrary file) is hidden — open wallets from the in-app chooser instead. The
> version is shown in the desktop window title and, on every platform, in the Help dialog. The CLI
> is desktop/headless only.
### Main tabs
- **History** — list of transactions. *Double-click* (double-tap on touch) 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] [--no-encryption]
dotnet run --project src/Cli -- restore "<mnemonic>" [...]
dotnet run --project src/Cli -- restore-xpub <slip132-key> [--net ...] [--no-encryption]
dotnet run --project src/Cli -- restore-address <addr1,addr2,...> [--net ...] [--no-encryption]
dotnet run --project src/Cli -- info [--net ...]
# 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]
dotnet run --project src/Cli -- servers [--discover]
```
The wallet password is read from `--password-env NAME`, `--password-stdin` or a no-echo terminal
prompt; a new wallet is stored unencrypted only with `--no-encryption` (`--password P` still works
but is unsafe and warns). See USERGUIDE section 17.
The default wallet file is `~/.palladium-wallet/<network>/wallets/default.wallet.json` (override with `--file`).
Run without arguments for the full command list (also covers `newseed`, `addresses`, `reset-certs`);
see [USERGUIDE.md §17](USERGUIDE.md#17-command-line-interface-cli) for complete flag reference.
---
## Changelog
Technical, per-version changes are tracked in [CHANGELOG.md](CHANGELOG.md).
## License
Released under the MIT License. See the [LICENSE](LICENSE) file.
SECURITY.md
+121
View File
@@ -0,0 +1,121 @@
# Security
## Threat model
Palladium Wallet is a self-custody SPV wallet. It is designed to protect funds against:
- Theft of the wallet file at rest (AES-256-GCM encryption with PBKDF2-HMAC-SHA512)
- Memory snooping of private keys after unlock (keys are held only in process memory, never written to disk in plaintext unless the user explicitly disables encryption)
- Fraudulent transaction injection by a malicious server (every confirmed transaction is verified with a Merkle proof against a block header that hash-chains up to a hardcoded checkpoint; the blocks above the newest checkpoint are the known exception, see the SPV trust model)
It does **not** protect against:
- A fully compromised operating system or process (malware with memory access can extract keys from RAM)
- An attacker who obtains the wallet file **and** the password
- Denial of service or eclipse attacks against the indexing server
- Network-level traffic analysis (no Tor/proxy support in the first release)
---
## SPV trust model
This wallet is an SPV client, not a full node. It validates:
- Block headers: `SkipPowValidation` is enabled because LWMA difficulty cannot be recomputed client-side, so proof of work is never checked. Instead, every header used for a Merkle proof is hash-chain-linked (prev-hash) **up to the nearest hardcoded checkpoint at or above its height**, and the header at that checkpoint height must hash to the checkpoint exactly (`Core/Chain/ChainProfiles.cs`, enforced in `Core/Spv/WalletSynchronizer.AnchorToCheckpointAsync`, ADR 0040). The direction matters: with PoW skipped, a chain built *from* a checkpoint *up to* a header proves nothing, because anyone can fabricate such a chain; a chain ending in a known hash cannot be forged without inverting SHA-256. Mainnet checkpoints run every 20,000 blocks from 20,000 (so even the oldest blocks are covered) and are extended at each release. **Known limit:** a transaction in a block *above the highest checkpoint* has no checkpoint to anchor to, so only its Merkle proof against the header the server supplied is checked there; the window is the blocks mined since the last release. The wallet flags such transactions as **not anchored** in the history list and in the transaction detail (ADR 0041), so the reduced guarantee is visible instead of silent. For those blocks the wallet also cross-checks the header with a second server taken from the hardcoded bootstrap list (never from announced peers): a different header at a safe depth (3+ blocks) aborts the sync, a shallower disagreement leaves the proof unverified until the next sync, and with no reachable witness only the Merkle proof applies (ADR 0042). This raises the bar from one lying server to two; it does not help against two colluding servers or an attacker in front of both. Testnet/regtest have no checkpoints yet, so headers there are trusted at face value
- Transaction inclusion in a confirmed block (Merkle branch proof, mandatory for every confirmed transaction — see `Core/Spv/MerkleProof.cs`)
It does **not** validate:
- Script execution (P2WPKH scripts are assumed valid if the server returns a confirmed transaction with a valid Merkle proof)
- Double-spend detection beyond what the server reports (an eclipse attack on the indexing server could hide a conflicting transaction)
- Full block validity (coinbase, consensus rules beyond the header)
The indexing server (ElectrumX-compatible, port 50001/50002) is a **semi-trusted** component. It can:
- Lie about unconfirmed (mempool) transactions — the wallet shows mempool transactions as unconfirmed and non-spendable
- Refuse to relay a broadcast transaction
- Delay reporting of new blocks
- Suggest misleading fee estimates or relay fee (the wallet ignores implausible values, never goes below the relay fee, and always shows the absolute fee, flagging one above 1% of the amount — ADR 0039)
It cannot (given correct Merkle verification):
- Fabricate a confirmed transaction with a valid Merkle proof
- Forge a payment to a wrong address
**Chain identity.** Right after the handshake the wallet checks that the server is on the Palladium chain (`Core/Spv/ChainVerifier.cs`, ADR 0036): `genesis_hash` from `server.features` must match the profile, and the header at the highest checkpoint not above the server's tip must hash to the hardcoded checkpoint. Mainnet shares Bitcoin's genesis, so the checkpoint header is what actually distinguishes it; testnet/regtest (no checkpoints) rely on the genesis alone. A server whose tip is below the first checkpoint is accepted on the genesis check alone.
**Network resource limits.** Server input is bounded so a hostile server cannot hang or kill the
client: every request has a timeout (30 s; 10 s for the handshake; a timeout drops the connection)
and a single reply line is capped at 16 MiB (`Core/Net/ElectrumClient.cs`, ADR 0034 and 0035).
**Progressive verification (mobile-friendly sync).** On a wallet with many historical
transactions, `WalletSynchronizer` no longer blocks the whole sync on every Merkle proof:
balance and history are shown as soon as transaction downloads finish (`PartialResult`,
`Core/Spv/WalletSynchronizer.cs`), while proofs continue to be checked in the background and
each transaction's `Verified` flag catches up progressively. This means the UI can display a
server-reported balance/history that includes not-yet-verified entries — clearly marked with a
"verifying…" badge and a separate non-spendable total (`PendingVerificationSats`). The
security-critical invariant this depends on: coin selection (`TransactionFactory`, gated by
`Wallet/UtxoSpendability.IsSpendable`) refuses to spend a UTXO whose `Verified` flag isn't true,
regardless of confirmations — so a server that fabricates a fake confirmed balance can get it
*displayed* early, but never *spent*, before the forged Merkle proof is caught and the sync
fails outright. The disk cache (`SyncCache`) only ever persists the fully-verified end state of
a sync, never a partial one, so no unverified data survives a restart.
---
## Key and seed management
- The BIP39 mnemonic and derived private keys exist only in process memory after unlock
- Private keys are never written to disk, logged, or sent over the network
- The address list and the address detail sheet hold no private key: the WIF of an address is derived only when the user reveals it (after the wallet password, if the wallet is encrypted) and is dropped when it is hidden, when the sheet closes or when the wallet closes (ADR 0037). The key is a managed string and cannot be zeroed, so it remains in process memory until the garbage collector reclaims it
- The wallet file stores the encrypted seed (with password) or the encrypted/plaintext `WalletDocument` — the document contains the account xpub and sync cache, not the raw seed when watch-only
- Watch-only wallets (`restore-xpub`, or `restore-address` for pure address imports) hold no private keys and cannot sign transactions; `TransactionFactory` only calls `AddKeys`/signs when the account reports a private key, so an address-only import can never produce a signed transaction, only an exportable unsigned PSBT
---
## Encryption at rest
- Algorithm: AES-256-GCM
- Key derivation: PBKDF2-HMAC-SHA512, 600 000 iterations, 16-byte random salt (fresh salt and nonce on every save; the iteration count is stored in the file container, so future increases remain backward-compatible — bounded at 10 000 000 on read, since the count is attacker-controlled in a tampered file and an absurd value would hang the wallet at open)
- Authentication: GCM tag (16 bytes) — any tampering is detected before decryption
- A malformed container (broken JSON, missing fields, bad base64, wrong nonce/tag size) always fails with a typed `InvalidDataException`, never a raw parser exception — the decrypt path is fuzz-tested (`tests/PalladiumWallet.Fuzz`)
- The user can explicitly opt out of encryption (UI shows a warning); the `WalletStore.Save` API accepts `null` password only when the caller has confirmed user intent
---
## TLS certificate pinning
Connections to the indexing server use TOFU (Trust On First Use): the server's TLS certificate is pinned on first connection and stored in `server-certs.json`. A certificate change triggers a hard error (`CertificatePinMismatchException`) requiring explicit reset by the user. This prevents silent MITM substitution after first connection.
---
## Backup
The wallet file is the only thing that needs to be backed up. For encrypted wallets, the password is also required. If both the file and the password are lost, funds are unrecoverable (no server-side backup). For watch-only wallets (restored from xpub or from a plain address), the private keys must be kept in a separate cold storage device.
---
## AI-assisted testing and vulnerability discovery
Part of the test suite and security review for this project is produced with **Claude Fable 5** (Anthropic), used as a targeted tool rather than a blanket "AI-reviewed" stamp. Concretely:
- **Adversarial network simulation**: the SPV/network layer (`ElectrumClient`, `WalletSynchronizer`, `CertificatePinStore`) is tested against an in-process fake ElectrumX server that can be programmed to lie — serve a transaction with a Merkle proof that doesn't match its claimed block header, drop connections mid-request, return malformed or throttling responses. These are exactly the behaviors a malicious or compromised indexing server would exhibit; the suite asserts the wallet detects and rejects them (see `SpvVerificationException`) instead of trusting unverified server data.
- **Property-based fuzzing** (CsCheck): parsers and cryptographic roundtrips (amount parsing, SLIP-132 key encoding, Merkle proof verification, AES-GCM encrypt/decrypt) are exercised against hundreds of generated inputs per run, checking invariants — no crash on arbitrary input, correct rejection of a wrong password, no false-negative Merkle verification — rather than a handful of hand-picked cases. This methodology has already found and fixed two real defects: a corrupted TLS pin file that permanently blocked reconnection, and a wallet-detection routine that threw on unexpected but valid JSON instead of failing safe.
- **Targeted security-focused code review** over the areas where a bug has direct financial impact: key derivation, transaction signing, coin selection/spendability rules, and encryption at rest — cross-checked against the invariants stated in this document (e.g. "the server cannot fabricate a confirmed transaction with a valid Merkle proof").
This is a complement to, not a substitute for, independent human or third-party security review — which is still recommended before relying on this wallet for significant mainnet funds, particularly ahead of a 1.0 release.
---
## Known limitations and out-of-scope for v1
- No Tor/proxy support (network traffic reveals which addresses are being queried)
- No multi-server pooling (single point of failure for the indexing server)
- No hardware wallet integration
- No coin control (automatic UTXO selection only)
- No RBF/CPFP UI (RBF flag is set on all transactions, but fee bumping is not exposed)
- No Lightning Network support
- No multisig (M-of-N) wallets: the network profile defines multisig SLIP-132 header
variants, but derivation for them is not implemented — attempting to use one throws
rather than silently producing an insecure/incorrect wallet
USERGUIDE.md
+912
View File
@@ -0,0 +1,912 @@
# Palladium Wallet — User Guide
This guide covers **every user-facing feature** of Palladium Wallet (GUI and CLI), including
default values, validation rules, limits, and edge cases. It is written so that no behavior
has to be guessed: when the wallet enforces a rule, the rule is stated here with its exact
numbers.
Applies to version **0.9.x**. Where the GUI and the CLI differ, both are described.
---
## Table of contents
1. [What Palladium Wallet is (and is not)](#1-what-palladium-wallet-is-and-is-not)
2. [Key concepts you must understand before holding funds](#2-key-concepts)
3. [Installation and platform differences](#3-installation-and-platform-differences)
4. [First launch: the setup wizard](#4-first-launch-the-setup-wizard)
5. [Opening, closing and managing multiple wallets](#5-opening-closing-and-managing-multiple-wallets)
6. [The main screen](#6-the-main-screen)
7. [Receiving funds](#7-receiving-funds)
8. [Sending funds](#8-sending-funds)
9. [Transaction history and details](#9-transaction-history-and-details)
10. [The Addresses tab](#10-the-addresses-tab)
11. [Contacts](#11-contacts)
12. [Connection, servers and certificate pinning](#12-connection-servers-and-certificate-pinning)
13. [Settings](#13-settings)
14. [Wallet Information (xpub, seed, fingerprint)](#14-wallet-information)
15. [Backup and recovery](#15-backup-and-recovery)
16. [Security model and known limitations](#16-security-model-and-known-limitations)
17. [Command-line interface (CLI)](#17-command-line-interface-cli)
18. [Troubleshooting and error messages](#18-troubleshooting-and-error-messages)
19. [Glossary](#19-glossary)
---
## 1. What Palladium Wallet is (and is not)
Palladium Wallet is a **self-custody SPV (Simplified Payment Verification) wallet** for the
Palladium (PLM) cryptocurrency, a Bitcoin-derived UTXO chain with 2-minute blocks. It runs on
Windows, Linux and Android from the same codebase, plus a separate command-line interface.
**Self-custody** means: *you* hold the keys. There is no account, no server-side backup, no
password recovery service. If you lose your seed phrase (and your wallet file plus its
password), your funds are permanently unrecoverable. Nobody — including the developer — can
restore them.
**SPV** means the wallet does **not** download or validate the full blockchain. It connects to
an **indexing server** (ElectrumX-compatible, ports 50001 TCP / 50002 SSL) and downloads only
the data relevant to your addresses. Every *confirmed* transaction the server reports is
independently verified with a **Merkle proof** against the block header; a server that lies
about confirmed transactions is detected and the synchronization aborts. See
[section 16](#16-security-model-and-known-limitations) for exactly what the server can and
cannot do to you.
What this wallet intentionally does **not** include (as of this version):
- Lightning Network
- Hardware-wallet integration
- Coin control (manual UTXO selection) — coin selection is always automatic
- RBF fee bumping (transactions *signal* RBF, but there is no "bump fee" button)
- Tor/proxy support — the indexing server can observe which addresses you query
- Fiat currency conversion
- Network selection in the GUI — the **GUI operates on mainnet only**; testnet and regtest
are available through the CLI (`--net`)
---
## 2. Key concepts
Read this section once, carefully. Every rule below is enforced by the software exactly as
written.
### 2.1 The seed phrase (BIP39 mnemonic)
- When you create a new wallet in the GUI, it generates a **12-word English** BIP39 mnemonic.
It is shown **once**, during the wizard, and you must write it down **on paper, in order**.
- Whoever knows these words controls the funds — from any device, forever, with no further
information needed (unless you also set a passphrase, see below).
- When *restoring*, the wallet accepts any valid BIP39 mnemonic (12 or 24 words in the GUI
prompt; the parser also accepts 15/18/21-word mnemonics and auto-detects the wordlist
language). The checksum is validated: a mistyped word is rejected, not silently accepted.
### 2.2 The optional passphrase ("25th word")
During creation or restore you may set a **BIP39 passphrase**. Understand precisely what it
does:
- The passphrase is combined with the seed words to derive the keys. Seed + passphrase
produce a **completely different wallet** than the same seed without a passphrase (or with
any other passphrase, including one differing by a single character or by case).
- There is **no validity check possible**: entering the "wrong" passphrase during a restore
does not produce an error — it silently opens a different, empty wallet. If you restore and
see a zero balance where you expected funds, the first thing to check is the passphrase
(then the script type, see 2.3).
- Store the passphrase **separately** from the seed words. Losing the passphrase makes the
funds unrecoverable even if you still have the 12 words.
### 2.3 Script type (address format)
Each wallet is created with exactly one **script type**, which determines the address format
and the derivation path. It cannot be changed later; to switch, create a new wallet and move
the funds.
| Script type | Standard | Derivation | Mainnet addresses look like |
|---|---|---|---|
| Legacy | BIP44 | `m/44'/746'/0'` | start with `P` |
| Wrapped SegWit | BIP49 | `m/49'/746'/0'` | start with `3` |
| **Native SegWit** (default, recommended) | BIP84 | `m/84'/746'/0'` | start with `plm1q` |
| Taproot | BIP86 | `m/86'/746'/0'` | start with `plm1p` |
**Restoring with the wrong script type is the same trap as the wrong passphrase**: the seed
is accepted, but different addresses are derived and the balance shows zero. When restoring,
select the same script type the wallet was created with. If unsure, try Native SegWit first
(the default), then the others.
The coin type in the derivation path is **746** on mainnet (1 on testnet/regtest).
### 2.4 Wallet types
| Type | Created via | Can sign/spend | Notes |
|---|---|---|---|
| HD (BIP39 seed) | Create new / Restore from seed | Yes | The normal case |
| HD (imported xprv) | Import extended key (xprv/yprv/zprv) | Yes | Full account key, no seed words |
| Watch-only (xpub) | Import extended key (xpub/ypub/zpub) | **No** | Sees balances/history; cannot sign. In the GUI it can *prepare* a transaction preview but not sign or broadcast it. The CLI produces an unsigned PSBT for offline signing |
| Imported WIF keys | Import WIF key(s) | Yes | Fixed address list, **no HD derivation and no change chain — change always returns to the first imported address** (this links your coins together; prefer an HD wallet for privacy) |
The extended-key format is **SLIP-132**: `xpub`/`xprv` (Legacy and Taproot), `ypub`/`yprv`
(Wrapped SegWit), `zpub`/`zprv` (Native SegWit). The script type is auto-detected from the
prefix when importing.
### 2.5 The wallet file and its encryption
Everything the wallet knows is stored in **one file per wallet**:
`<data folder>/mainnet/wallets/<name>.wallet.json` (default name `default.wallet.json`).
It contains the seed (or xpub/xprv/WIF keys), the derivation settings, your **contacts**, and
a sync cache (balances, history, verified proofs).
- If you set a password, the file is encrypted with **AES-256-GCM**; the key is derived with
**PBKDF2-HMAC-SHA512, 600,000 iterations, random 16-byte salt** (fresh salt and nonce on
every save). Tampering with the file is detected before decryption.
- If you **decline encryption** (the wizard checkbox, or `--no-encryption` in the CLI),
**the seed is stored in plaintext on disk**. The wizard warns you explicitly. Only do this
on a disk you fully trust (e.g. an encrypted volume).
- There are **no password strength requirements and no attempt limits**. An empty password is
not allowed when encryption is enabled. Choose a strong password yourself: an attacker who
copies the file can try passwords offline at their leisure.
- There is currently **no "change password" function** in the GUI. To change the password,
restore the wallet from its seed into a new wallet file with the new password, verify the
new file opens and syncs, then delete the old file. (Contacts must be re-entered — see
[section 15](#15-backup-and-recovery).)
### 2.6 Confirmations and spendability
Incoming funds are not immediately spendable. The exact rules on mainnet:
- **Unconfirmed (mempool)** transactions: shown as *"pending confirmation … not yet
spendable"*. Never spendable, and — important — unconfirmed amounts are reported by the
server **without cryptographic proof**, so treat them as provisional until confirmed.
- **Regular outputs**: spendable after **6 confirmations** (~12 minutes at 2-minute blocks).
- **Mining (coinbase) outputs**: spendable after **121 confirmations** (~4 hours). Until
then they appear as *"maturing … not yet spendable"*.
The main balance shown is *confirmed minus immature*; pending and maturing amounts are shown
as separate amber lines under the balance when present.
---
## 3. Installation and platform differences
### 3.1 Desktop (Windows / Linux)
Release binaries are self-contained — no runtime to install. Run the single executable
(`PalladiumWallet.exe` on Windows, `PalladiumWallet` on Linux).
### 3.2 Android
Install the `.apk` (sideloading must be allowed). Minimum Android version: 6.0 (API 23).
The app requests the **camera** permission only if you use the QR scanner; **internet** is
required for synchronization.
> **Updating in place**: releases built with the project's official signing key update over
> the installed app. If Android refuses to install an update ("app not installed" /
> signature mismatch), the new apk was signed with a different key — you would have to
> uninstall first, **which deletes the wallet file**. Back up your seed before uninstalling,
> always.
### 3.3 What differs between desktop and Android
| Aspect | Desktop | Android |
|---|---|---|
| Data location | Chosen at first run (default or custom folder) | Fixed: the app's private sandbox (step skipped) |
| Menu bar | File / Network / Settings / Wallet / Help | No menu bar; same functions reachable from the UI |
| Close overlays | `Esc` key or click the dark backdrop | Hardware/gesture **Back** button or tap the backdrop |
| QR code **scanning** (Send) | Not available | Camera scan button in the Send form |
| CLI | Available | Not available |
Everything else — wallet formats, security, sync, features — is identical.
### 3.4 Where your data lives (desktop)
Resolution order:
1. A `palladium-data/` folder next to the executable, if present (**portable mode** — create
the folder manually before first launch to get a fully portable install).
2. The custom folder you picked in the first-run wizard (remembered via a small pointer file
in the default location).
3. The default: `%APPDATA%\PalladiumWallet` on Windows, `~/.palladium-wallet` on Linux.
Inside the data root: `mainnet/wallets/*.wallet.json` (your wallets),
`mainnet/server-certs.json` (pinned TLS certificates), `mainnet/servers.json` (discovered
servers), `config.json` (language, unit, last server — shared across wallets).
---
## 4. First launch: the setup wizard
### 4.1 Step: data location (desktop only, very first run)
Choose where the wallet stores its data: **"Use the default path"** (shown on screen) or
**"Choose a folder…"** (native folder picker). This step never reappears once configured.
On Android it is skipped entirely.
### 4.2 Step: start
Five options:
1. **Open existing wallet** — see [section 5](#5-opening-closing-and-managing-multiple-wallets).
2. **Create a new wallet**
3. **Restore from seed**
4. **Import xpub / xprv**
5. **Import WIF key**
### 4.3 Creating a new wallet
1. **Your seed (12 words)** — the freshly generated mnemonic is displayed. Write the words
on paper, in order. *They are never shown in full again except through the password-gated
"Show seed" function ([section 14](#14-wallet-information)).* Do not photograph them, do
not store them in a cloud note.
2. **Confirm seed** — retype the 12 words, space-separated. Comparison is case-insensitive
and tolerant of extra spaces. A mismatch shows *"The words do not match: check what you
wrote on paper."* and lets you retry.
3. **Optional passphrase** — leave empty to skip. Re-read [section 2.2](#22-the-optional-passphrase-25th-word)
before setting one.
4. **Script type** — default Native SegWit. If unsure, keep the default.
5. **Password step** — see 4.7.
### 4.4 Restoring from seed
1. Enter the mnemonic, words separated by spaces. Invalid words or a bad checksum produce
*"Invalid mnemonic (wrong words or checksum): check again."*
2. Enter the **same passphrase** used originally (empty if none was used).
3. Select the **same script type** used originally.
4. Password step (4.7).
After the first synchronization the balance and full history reappear. If the balance is
zero when it shouldn't be: wrong passphrase or wrong script type
([sections 2.2–2.3](#22-the-optional-passphrase-25th-word)).
### 4.5 Importing an extended key (xpub / xprv)
Paste a SLIP-132 extended key:
- **Public key** (`xpub`/`ypub`/`zpub`) → **watch-only** wallet: monitors balances and
history, cannot spend.
- **Private key** (`xprv`/`yprv`/`zprv`) → fully spendable HD wallet (account level, no seed
words).
The script type is detected automatically from the key prefix and shown for confirmation
(e.g. *"NativeSegwit (watch-only)"*). An unrecognized key shows *"Extended key not
recognised for this network."* — check that it is a Palladium key of a supported format, not
a key from another coin.
### 4.6 Importing WIF private keys
Paste one or more WIF keys, **one per line**. Each key controls exactly one address; there
is no HD derivation. Select the script type (which address form the keys map to), then the
password step. Remember the change-address caveat from
[section 2.4](#24-wallet-types).
### 4.7 The password step (all flows)
- **Wallet name** (optional): letters/numbers recommended; invalid filesystem characters are
replaced with `_`. Left blank → automatic name (`default`, then `wallet-2`, `wallet-3`, …).
A name that already exists is rejected: *"A wallet with this name already exists."*
- **"Encrypt the wallet file with the password"** — checked by default. If you uncheck it,
the file (including the seed) is written **in plaintext** and the UI warns you.
- **Password + confirmation** — must match and be non-empty when encryption is on. No other
rules are imposed; strength is your responsibility.
- **Create wallet** finalizes: the file is written, locked against concurrent access, opened,
and the first connection/sync starts automatically.
---
## 5. Opening, closing and managing multiple wallets
- You can keep **any number of wallets**: each is a separate `*.wallet.json` file in the
wallets folder. With more than one file, "Open existing wallet" shows a chooser list; with
exactly one, it goes straight to the password prompt.
- **Password prompt**: leave empty for an unencrypted wallet. Wrong password → *"Wrong
password."* — retries are unlimited.
- The GUI **only lists wallets inside its own wallets folder**. To use a wallet file from
elsewhere, copy it into `<data folder>/mainnet/wallets/` first (while the app is closed,
or before pressing Open).
- **Single-instance lock**: a wallet file can be open in only one running instance at a
time. A second attempt fails with *"Wallet already open in another instance of the
application."* A stale `.lock` file left by a crash is released automatically when the
owning process is gone.
- **Switching wallets**: menu *File → Close wallet* (returns to the wizard), then *Open
existing wallet*. *File → New / restore wallet…* also closes the current wallet first.
- **Deleting a wallet**: there is no in-app delete. Close the app and delete the
`.wallet.json` file manually — **only after verifying you have the seed on paper** (or,
for imported wallets, the original keys). Deleting the file of an unbacked-up wallet
destroys the funds' keys.
After opening, the header shows the wallet's identity, e.g.
`Mainnet · NativeSegwit · m/84'/746'/0'`, with a ` · watch-only` or ` · imported` tag when
applicable.
---
## 6. The main screen
Five tabs: **History**, **Send**, **Receive**, **Addresses**, **Contacts**.
- **Balance** (top): confirmed, spendable balance in your chosen unit. Below it, when
applicable, two amber advisory lines: *pending confirmation* (mempool, unproven, not
spendable) and *maturing* (young coinbase, not spendable — see
[section 2.6](#26-confirmations-and-spendability)).
- **Status bar** (bottom): left, the sync status (e.g. *"Synchronized: height 123456, 42
SPV-verified transactions. Real-time updates active."*); right, the **connection
indicator** (*connected host:port* / *connecting…* / *not connected* / *reconnecting…*).
**Click/tap the connection indicator to open the server settings.**
- All secondary screens (settings, details, wallet info, help) are **in-app overlays**, not
separate windows. Close them with the ✕ button, by clicking the dark backdrop, with `Esc`
(desktop) or Back (Android).
---
## 7. Receiving funds
The **Receive** tab always shows the **next unused receive address**, as text and as a QR
code (the QR encodes the bare address).
- **Copy** puts the address on the clipboard (*"Address copied to clipboard"*).
- Give a **fresh address to each payer**. After an address receives a payment and a sync
runs, the tab automatically advances to the next unused address. Reusing addresses is not
blocked, but it degrades your privacy by linking payments together.
- Incoming payments appear in History **at the next synchronization** — normally within
seconds, because the wallet subscribes to server push notifications. A payment shows as
*mempool* first, then with its block height once mined.
- The address format is fixed by the wallet's script type
([section 2.3](#23-script-type-address-format)); senders must support that format (in
particular, very old software may not send to `plm1…` bech32 addresses).
**Gap limit — the one receiving rule you must know.** The wallet derives addresses on
demand and, when restoring from seed, scans forward until it finds **20 consecutive unused
addresses** and then stops. Consequence: if you hand out many addresses that never receive
funds, do not skip ahead by more than 20 — a payment to address #30, with #10–#29 unused,
would **not be found after a restore from seed**. Under normal use (addresses handed out
sequentially, most getting used) this never triggers. The limit (20) is stored per wallet
and is not editable in the GUI.
---
## 8. Sending funds
Prerequisites: the wallet must be **connected and synchronized** (otherwise: *"Connect to
the server and synchronize before sending"* / *"Synchronize before sending"*), and the
wallet must be spendable (not watch-only) to actually broadcast.
### 8.1 The form
- **From contacts** — optional dropdown that fills the recipient address from your address
book.
- **Recipient address** — validated when you prepare: an address of the wrong network or
with a typo is rejected (checksums make silent typos virtually impossible).
- **Amount** — interpreted in the **currently selected display unit** (PLM by default — check
the unit in Settings before typing!). Rejected if negative, malformed, or more precise
than 1 satoshi (0.00000001 PLM).
- **Send all** — checkbox; disables the amount field and sends the entire spendable balance,
**with the fee deducted from the amount** (the recipient receives balance − fee).
- **Fee (sat/vB)** — the fee rate, which you can always type by hand. **Default: 1 sat/vB.**
Once connected, the wallet asks the server for the minimum relay fee and for estimates, and
shows three presets — **Fast** (~2 blocks), **Normal** (~6) and **Economy** (~24) — with the
numbers underneath; **Normal** is preselected unless you already typed a rate. An estimate
never goes below the relay fee, and an implausible one (above 1000 sat/vB) is ignored. If the
server gives no estimate the presets are hidden and the manual field stays at 1. A manual rate
below the server's relay fee is refused with a message (the node would reject it anyway).
The estimate comes from the server, which is not trusted: the preview always shows the
**absolute fee**, and warns when it is more than 1% of the amount sent. On the Palladium
chain, blocks are rarely full, so 1 sat/vB normally confirms in the next few blocks; raise it
if a transaction lingers in the mempool. Must be a number greater than zero and at most 1000;
`.` or `,` is the decimal separator (no thousands separators), regardless of the system
language.
- **QR scan** (Android only) — camera button; reads a plain address or a
`palladium:` payment URI (the address part is used).
### 8.2 Prepare, then confirm
Sending is a **two-step** operation:
1. **Prepare transaction** — builds and signs the transaction locally, without sending
anything. The summary card shows the txid (truncated), the **exact fee**, and the virtual
size, e.g. `txid 4f3a…| fee 0.00000141 PLM (141 vB)`. Nothing has left your wallet yet;
you can change the fields and prepare again, or simply navigate away to abandon it.
2. **CONFIRM AND BROADCAST** — transmits the prepared transaction to the server. Success
shows the full txid; the form clears and a re-sync starts. After broadcasting, **a
transaction cannot be cancelled** — it is in the network's mempool and will confirm.
### 8.3 How the transaction is built (facts you may need)
- **Coin selection is automatic** (there is no coin control). The wallet spends from its
spendable UTXOs and sends any **change back to its own internal change chain** — this is
why, in transaction details, one output to an address you don't recognize as "yours" may
still be marked as yours: it is your change.
- All transactions **signal RBF** (BIP125) and use transaction version 2. The wallet does
not offer fee bumping; if you underpay the fee, wait — with RBF signaled, other wallets
could in principle replace it, but this wallet has no UI for that.
- **Dust change is absorbed into the fee**: if the change output would be uneconomically
small, it is added to the fee instead of creating a dust output. The fee shown in the
summary already accounts for this — always check the summary fee before confirming.
- A prepared transaction is fully verified against standardness policy before it can be
confirmed; a policy failure surfaces as *"Invalid transaction: …"* instead of a broadcast.
### 8.4 Why "insufficient funds" can appear despite a visible balance
The error message itemizes the reasons. Funds may be temporarily unspendable because they
are:
- **in the mempool** (unconfirmed — never spendable),
- **recently confirmed** (fewer than 6 confirmations),
- **immature coinbase** (mining rewards younger than 121 blocks).
Wait for confirmations and retry. Also remember that the fee itself must fit: sending your
exact full balance fails unless you use **Send all**.
### 8.5 Watch-only wallets and offline signing
A watch-only (xpub) wallet in the **GUI** can prepare a transaction to preview the fee and
size — the summary is tagged *"unsigned (watch-only)"* — but the confirm button stays
disabled: **the GUI cannot export the unsigned transaction**. To actually use the
watch-only + offline-signing workflow, use the **CLI**, whose `send` command prints an
**unsigned PSBT (base64)** for a watch-only wallet
([section 17](#17-command-line-interface-cli)). Sign that PSBT on the offline machine with
software of your choice, then broadcast the finalized transaction.
### 8.6 The Donate tab (Help → Donate)
The Help overlay includes a donation form (developer address
`plm1qdq3gu2zvg9lyr8gxd6yln4wavc5tlp8prmvfay`) using the same prepare/confirm flow and the
fee rate from the Send tab (an invalid rate is reported as an error). Entirely optional.
---
## 9. Transaction history and details
The **History** tab lists all wallet transactions, newest first; unconfirmed ones are
labeled **mempool** and sorted on top, confirmed ones show their **block height**. The
amount is the transaction's net effect on your wallet (`+` incoming).
**Double-click** (desktop) or **tap** (Android) a row to open the full details. This
requires a live server connection (details are fetched on demand): otherwise *"Connect to
the server to view transaction details."*
The details overlay shows:
- **Overview** — status (*"N confirmations (block H)"* or *"0 confirmations · in
mempool"*), local date/time, counterparty addresses, and the signed net amount. Mining
rewards show *"Newly generated (mining)"* as the sender.
- **Amounts & fees** — the absolute fee, your net amount, and the fee rate in sat/vB.
- **Technical details** — full transaction ID, total size, virtual size, **Replaceable
(RBF)** yes/no, version, locktime.
- **Inputs** — each spent outpoint with its address and amount; your own inputs are
highlighted. Coinbase inputs display the miner's **scriptSig message** when it is readable
text.
- **Outputs** — each output with index, address and amount; your own outputs (including
change) are highlighted. **OP_RETURN** outputs display their decoded text message when the
payload is valid readable text; non-standard outputs show their script type.
Notes and limits:
- Confirmation counts advance automatically as blocks arrive (real-time header
subscription).
- Every **confirmed** transaction in your history has been verified with a Merkle proof
during sync. **Unconfirmed** entries are the server's word only — do not treat a mempool
payment as received until it confirms.
- There are no per-transaction labels and no block-explorer links in this version. The
public explorer is at `https://explorer.palladium-coin.com/` — paste the txid there
manually if needed.
---
## 10. The Addresses tab
A complete table of every derived address: **type** (receive/change), **index**,
**address**, **balance**, and **transaction count**. Before the first sync it shows the
first 10 receive addresses with no data.
Tap (or right-click) a row to open the **address details** overlay:
- the full address and its **derivation path** (e.g. `m/84'/746'/0'/0/3`),
- the **public key** (hex),
- the **private key (WIF)**, hidden behind a **"Show"** button. For an encrypted wallet,
revealing it requires re-entering the wallet password (*"Enter the wallet password to
reveal the private key."*); for an unencrypted wallet it is shown directly. **Never
reveal a private key with anyone watching your screen** — one key controls that one
address's funds. Watch-only wallets have no private keys to show.
`change` addresses are where your own transactions send their change
([section 8.3](#83-how-the-transaction-is-built-facts-you-may-need)) — seeing balance on
them is normal.
---
## 11. Contacts
A simple per-wallet address book, on its own tab:
- **Add**: name + address, both required. The address is **validated when saving** against
the wallet's network: an invalid or wrong-network address, or one already in the list, is
refused with a message. Spaces and line breaks in a pasted address are removed. Contacts
saved by an older version without validation are still shown; the send form validates the
destination again when you use them.
- **Remove selected**: deletes the highlighted contact. There is no edit function — remove
and re-add.
- Contacts are used by the **From contacts** dropdown on the Send tab.
- Contacts are stored **inside the wallet file**. They travel with a file backup, but are
**not** recoverable from the seed phrase ([section 15](#15-backup-and-recovery)).
---
## 12. Connection, servers and certificate pinning
### 12.1 Server settings
Open by clicking the **connection indicator** in the status bar (or Settings → *Indexing
server…*, or menu *Network* on desktop). Fields:
- **Host** and **Port** — defaults: port **50001** (plain TCP) or **50002** (SSL). Editing
one of the known ports auto-toggles the SSL switch to match, and toggling SSL swaps the
port. Note these are the *indexing server* ports — not the Palladium node's P2P port
(2333), which this wallet never uses.
- **Use SSL** — default **on**. Strongly recommended: without SSL, traffic (including which
addresses you query) is readable on the wire.
- **Known servers** list — click an entry to select it. The wallet ships with four bootstrap
mainnet servers and remembers any servers learned via discovery.
- **Discover servers (peers)** — asks the connected server for its known peers and adds new
ones to the list.
Connection behavior: the wallet tries your selected server first, then walks the rest of
the known list until one answers. The last working server is remembered and reused at next
launch. A 20-second keep-alive ping detects drops and reconnects automatically;
server push notifications trigger instant re-syncs when a new block or a relevant
transaction appears (*"Real-time updates active"*).
### 12.2 TLS certificate pinning (TOFU) — read before "fixing" a certificate error
SSL connections use **Trust On First Use**: the first time you connect to a server, its
certificate's fingerprint is saved (in `server-certs.json`). Every later connection must
present the **same** certificate. If it doesn't, the connection is refused with a message
stating that the TLS certificate of that server **has changed**.
This is a security feature, not a bug. A changed certificate means one of two things:
1. **Benign**: the server operator renewed/rotated the certificate (common, e.g. Let's
Encrypt renewals).
2. **Hostile**: someone is intercepting your connection (man-in-the-middle).
You cannot distinguish the two from the wallet alone. If the change is expected or you can
verify it out-of-band, clear the pins: menu **Network → Reset SSL certificates** (desktop),
the **Reset certs** button in server settings, or `reset-certs` in the CLI. This deletes
**all** pinned certificates for the network; the next connection re-pins whatever it sees.
If you have any reason to suspect interception, switch networks (e.g. off a public Wi-Fi)
or servers instead of resetting.
### 12.3 What synchronization actually does
Each sync: gets the chain tip → scans your receive and change address chains (gap limit
20) → downloads your transactions → **verifies a Merkle proof for every confirmed
transaction** against its block header → rebuilds your UTXO set and balances locally.
On mainnet, each block header used for a proof is also chained up (via the previous-block
hashes) to the nearest built-in checkpoint above it, which must match exactly, so a server
cannot substitute a fabricated header for a real one. The blocks mined after the newest
checkpoint (shipped with each release) cannot be anchored this way: for those only the Merkle
proof is checked, which is why updating the wallet regularly matters. Such transactions carry an
orange **"not anchored"** label in the History tab and in the transaction detail (hover it for
the explanation); it disappears once you update to a release whose newest checkpoint covers
that block. The label is informational: the transaction is still Merkle-verified, and its block header is also compared with a second built-in server when one is reachable (if they disagree about a block that is a few blocks deep the sync stops with a "server is not trustworthy" error; for a very recent block the transaction just stays "verifying" until the next sync). Verified data is cached in the wallet file, so later syncs only fetch what
is new — even after a restart. If a proof or the checkpoint chain does not check out, the
sync **aborts** with an explicit "server is not trustworthy" error rather than showing you
unverified data; switch servers.
If the server is overloaded (busy responses), the wallet retries automatically up to 8
times with increasing back-off — a large wallet's first sync may take a little while, but it
resumes from the cache instead of restarting.
**First sync can take noticeably longer than later ones — this is expected.** Each confirmed
transaction requires its own Merkle-proof round trip to the indexing server
(`blockchain.transaction.get_merkle`, one request per transaction — the Electrum-style
protocol has no batched form of this call), plus, on mainnet, chaining the covering block
header up to the nearest hardcoded checkpoint above it. Sync time therefore scales with the number
of confirmed transactions in the wallet's history, not with wall-clock time since creation.
On **Android**, the first sync is typically slower still than on desktop for the same
wallet: mobile networks add higher round-trip latency and lower sustained throughput than a
desktop's wired/Wi-Fi connection, and every proof round trip pays that latency individually.
Every subsequent sync is fast: verified proofs, raw transaction bytes, downloaded block
headers, and the checkpoint hash-chain anchoring state are all persisted into the wallet
file's cache, so a resumed or later sync only fetches and verifies what changed since the
last one — even across an app restart. After updating from a version older than the
checkpoint-direction fix (ADR 0040), the first sync re-verifies every cached proof once
(the cached headers and transactions are reused).
**Do not use this wallet as a mining payout address.** Pool or solo mining payouts typically
arrive as many small, frequent transactions, and — because of the per-transaction Merkle
proof cost described above — sync time grows with transaction count, not balance. A wallet
whose history has accumulated **over 5,000 transactions** has been observed taking on the
order of a couple of minutes to fully synchronize even on a stable connection, with slower
networks (see the Android note above) pushing that further. If you mine, pay out to a wallet
purpose-built for high transaction volume (or one that lets you consolidate UTXOs
aggressively), and only move funds into Palladium Wallet in batches.
---
## 13. Settings
The Settings overlay (gear icon / menu *Settings*) contains exactly two preferences, plus
the door to the server settings:
- **Language** — Italiano, English, Español, Français, Português, Deutsch. Applies
immediately. Default: English.
- **Amount unit** — how amounts are displayed *and interpreted when you type them*:
| Unit | In satoshi | Decimals shown |
|---|---|---|
| PLM (default) | 100,000,000 | 8 |
| mPLM | 100,000 | 5 |
| µPLM | 100 | 2 |
| sat | 1 | 0 |
⚠ The Send form's amount field uses this unit. If you switch to `sat` and forget, typing
`100` means 100 satoshi, not 100 PLM. Double-check the unit before sending.
Settings are saved globally (per data folder, shared by all wallets), not per wallet.
There is no theme selector (the app uses its built-in dark theme) and no fiat display.
---
## 14. Wallet Information
Menu **Wallet → Wallet Information** (desktop) or the equivalent button. Shows:
- **File name**, **network**, **wallet type** (*HD (BIP39 seed)* / *HD (imported xprv)* /
*Imported WIF key* / *Watch-only (xpub)*), **script type**, **derivation path**.
- **Extended public key (xpub)** — displayed as selectable text. This is how you *export*
the xpub: select and copy it. Give the xpub to another device/app to create a
**watch-only** copy of this wallet — it reveals your entire address history and balance to
whoever holds it (privacy risk), but can never spend.
- **Master fingerprint** — 4-byte identifier of the master key, used in PSBT workflows.
- **BIP39 passphrase** — shows only whether one is *set*; the passphrase itself is never
displayed anywhere.
- **Show seed** — reveals the mnemonic, after re-entering the wallet password (for
encrypted wallets). Use it to re-verify your paper backup. The on-screen warning is
literal: *never share these words; whoever holds them controls the funds.* Watch-only and
imported wallets have no seed to show.
---
## 15. Backup and recovery
### 15.1 What to back up
There are two complementary backups; know exactly what each one restores:
| Backup | Restores | Does NOT restore |
|---|---|---|
| **Seed words on paper** (+ passphrase if set, + script type) | All keys, addresses, balance and on-chain history, on any device, forever | Contacts; wallet name; settings |
| **The wallet file** (+ its password) | Everything, including contacts | — |
Recommended: **always** have the paper seed (it survives disk failure, device loss, and
software obsolescence); *additionally* copy the `.wallet.json` file if you care about your
contacts list. An encrypted wallet file is safe to store on ordinary media — but it is only
as strong as its password, and it is useless without it.
For a **watch-only** wallet, the file only restores the watching capability; the actual
keys live wherever you keep the corresponding seed/xprv — back *that* up.
For an **imported WIF** wallet, back up the WIF keys themselves; they are not derivable from
anything else.
### 15.2 Restoring, step by step
1. Install the wallet on the new device.
2. Wizard → **Restore from seed** → enter the words → enter the **same passphrase** (or
leave empty if none) → choose the **same script type** → set a (new) password.
3. Let it synchronize. Balance and history are rebuilt from the chain.
If the balance is zero: wrong passphrase, or wrong script type, or (rare) funds beyond the
gap limit ([section 7](#7-receiving-funds)). Nothing is lost — the coins are still on the
chain; you are simply looking at the wrong derived wallet. Retry with the right parameters.
Restoring from a **file copy** instead: place the `.wallet.json` into
`<data folder>/mainnet/wallets/` and open it with its password.
### 15.3 Unrecoverable situations — be aware
- Seed lost **and** wallet file (or its password) lost → funds gone. No exceptions.
- Passphrase forgotten → funds gone, even with the 12 words in hand.
- Encrypted file's password forgotten, no seed backup → funds gone (the encryption has no
backdoor).
---
## 16. Security model and known limitations
A condensed version of the project's published threat model (`SECURITY.md`).
**The wallet protects you against:**
- Theft of the wallet file at rest (AES-256-GCM + PBKDF2, [section 2.5](#25-the-wallet-file-and-its-encryption)) —
provided you set a good password.
- A **lying indexing server**: it cannot fabricate a confirmed transaction or forge a
payment to a wrong address, because every confirmed transaction must carry a valid Merkle
proof, which the wallet checks itself.
- **Silent TLS interception after first contact** (certificate pinning,
[section 12.2](#122-tls-certificate-pinning-tofu--read-before-fixing-a-certificate-error)).
**The server can still (semi-trusted component):**
- lie about **unconfirmed** transactions (which is why they are marked not-spendable and
should not be trusted until confirmed);
- **withhold** information — hide transactions, delay new blocks, refuse to broadcast;
- **observe** which addresses belong to you (no Tor/proxy support in this version; using
your own indexing server is the strongest mitigation).
**The wallet cannot protect you against:**
- malware on your device (anything that can read process memory can take the keys once the
wallet is unlocked);
- an attacker holding both your wallet file **and** its password (or your seed);
- yourself: there are no confirmation "cool-downs", no address whitelists, and broadcast is
irreversible.
**Honest limitations of this version** (also listed in [section 1](#1-what-palladium-wallet-is-and-is-not)):
single server connection (no pooling), no coin control, no fee estimation, no RBF bumping,
no hardware wallets, no Tor, GUI mainnet-only, and PSBT export only via the CLI.
---
## 17. Command-line interface (CLI)
The CLI (`src/Cli`) runs on the same core as the GUI: same wallet files, same validation,
same security. It is desktop-only and its console output is in English. Run it
as `dotnet run --project src/Cli -- <command>` from the repository (or the published `Cli`
binary); with no arguments it prints usage.
**Shared conventions.** Default wallet file:
`~/.palladium-wallet/<network>/wallets/default.wallet.json` — override with `--file PATH`.
Default network mainnet — override with `--net testnet|regtest` (the CLI is the only way to
use test networks).
**Wallet password.** `create`/`restore*` ask for a password and encrypt the file; encrypted
wallets need it for `info`/`sync`/`send`. Supply it, in order of preference, with:
`--password-env NAME` (read from an environment variable), `--password-stdin` (first line of
stdin), or nothing — in a terminal you are prompted (no echo, with a confirmation when
creating); with no terminal the command fails instead of hanging. `--password P` still works
but is unsafe (it stays in the shell history and the process list) and prints a warning.
Only **one** of the three options may be given. A new wallet is stored **unencrypted only
with the explicit `--no-encryption`** (a warning is printed); forgetting the password no
longer produces a plaintext wallet. Examples:
`printf '%s\n' "$PW" | dotnet run --project src/Cli -- restore "<words>" --password-stdin`,
`PLM_PW=… dotnet run --project src/Cli -- info --password-env PLM_PW`.
`--kind legacy|wrapped|segwit` selects the script type (default Native SegWit — note that
only the literal values `legacy` and `wrapped` switch away from the default). Errors print
to stderr and set exit code 1.
### Wallet commands
```
newseed [--words 24]
```
Prints a fresh mnemonic (12 words unless `--words 24`) and writes nothing to disk.
```
create [--words 24] [--kind K] [--net N] [--passphrase W] [--no-encryption] [--file PATH] [--path m/...]
```
Generates a mnemonic, prints it once, saves the wallet, prints the file path and the first
receive address. `--path` overrides the derivation path (advanced; you must remember it to
restore).
```
restore "<mnemonic>" [same options as create]
```
Restores from an existing mnemonic (quoted, words space-separated).
```
restore-xpub <slip132-key> [--net N] [--no-encryption] [--file PATH]
```
Creates a **watch-only** wallet from an xpub/ypub/zpub; the script type is inferred from
the key prefix.
```
info [--net N] [--file PATH] [--addresses]
```
Prints the wallet's identity and, if it has ever synced, the balance breakdown (spendable /
maturing / pending), tip height, transaction count and next receive address.
`--addresses` adds the per-address list with balances.
```
addresses "<mnemonic>" [--kind K] [--net N] [--count N] [--passphrase W] [--path m/...]
```
Stateless tool: derives and prints receive (default 5) and change addresses from a mnemonic
without creating any file. Useful to check "which script type was this seed used with"
before restoring.
### Network commands
```
sync [--server host[:port]] [--ssl] [--net N] [--file PATH]
```
Connects (default: the first known server; port defaults to 50001, or 50002 with `--ssl`),
synchronizes with full Merkle verification, persists the cache into the wallet file, and
prints balance and history. Transactions the server reported but that are unconfirmed are
marked as unverified.
```
send --to ADDRESS (--amount X | --all) [--feerate R] [--broadcast]
[--server ...] [--ssl] [--net N] [--file PATH]
```
Builds a transaction from the synced cache (`sync` must have been run first). `--amount` is
in **PLM**; `--all` sends everything minus the fee. `--feerate` is in sat/vB, **default 1**.
Behavior by wallet type and flags:
- **Watch-only** wallet → prints the **unsigned PSBT in base64** and stops. This is the
air-gapped workflow: carry the PSBT to the offline signer, sign it there, broadcast the
final transaction by any means.
- Spendable wallet, **without `--broadcast`** → signs and prints the raw transaction hex,
explicitly marked as *not transmitted*. Nothing is sent — a dry run you can inspect or
broadcast elsewhere.
- Spendable wallet, **with `--broadcast`** → signs, transmits, prints the txid. Irreversible
from this point.
```
servers [--discover] [--server ...] [--ssl] [--net N]
```
Lists known servers; with `--discover`, connects and asks the server for its peers, adding
new ones.
```
reset-certs [--net N]
```
Deletes all pinned TLS certificates for the network (the CLI counterpart of *Network →
Reset SSL certificates* — see
[section 12.2](#122-tls-certificate-pinning-tofu--read-before-fixing-a-certificate-error)).
---
## 18. Troubleshooting and error messages
| Symptom / message | Meaning | What to do |
|---|---|---|
| *Wrong password.* | The password does not decrypt the file (or the file was tampered with — the two are indistinguishable by design). | Retry; check keyboard layout/caps lock. If truly lost, restore from seed ([15.2](#152-restoring-step-by-step)). |
| *Wallet already open in another instance of the application.* | Another running process holds this wallet's lock. | Close the other instance (GUI or CLI). |
| *The TLS certificate of host:port has changed…* | Certificate pin mismatch — renewal or interception. | Read [12.2](#122-tls-certificate-pinning-tofu--read-before-fixing-a-certificate-error) **before** resetting certificates. |
| History shows an orange *"not anchored"* next to a transaction | The block is newer than the newest checkpoint built into this version, so its header cannot be chained to a hardcoded hash; only the Merkle proof backs it. | Normal for the most recent blocks. Update the wallet to a newer release to anchor them; for large amounts, wait until it is no longer flagged. |
| Sync aborts, "server is not trustworthy" | A Merkle proof failed, or (mainnet) a block header did not chain up to a known checkpoint. | Switch to another server. Your local data is intact; the wallet refused the bad data. |
| *The server host:port is not on the Palladium chain (different genesis or checkpoint)…* | The server answered, but serves another chain (or a fork) than the wallet expects. Nothing was synced from it. | Pick another server; the wallet moves on to the next known one on its own. See [12.3](#123-what-synchronization-actually-does). |
| *Insufficient funds* with a non-zero balance | Funds are unconfirmed, under 6 confirmations, or immature coinbase; or the fee doesn't fit. | See [8.4](#84-why-insufficient-funds-can-appear-despite-a-visible-balance). Wait, or use Send all. |
| Restored wallet shows zero balance | Wrong passphrase, wrong script type, or funds beyond the gap limit. | See [15.2](#152-restoring-step-by-step) — the coins are not lost. |
| *Invalid mnemonic (wrong words or checksum)* | A word is misspelled, not on the BIP39 list, or the checksum fails. | Compare against your paper backup, word by word. |
| *Extended key not recognised for this network.* | The pasted xpub/xprv is not a SLIP-132 key of this network. | Check the key's prefix and the source wallet's export format. |
| *A wallet with this name already exists.* | Filename collision in the wallets folder. | Pick another name, or leave blank for an automatic one. |
| Payment sent to me doesn't appear | Not yet synced/connected, or sender hasn't broadcast. | Check the connection indicator; mempool entries appear within seconds of broadcast when connected. |
| Update prompt at startup (*"Update available"*) | A newer GitHub release exists (checked once at startup, silently skipped offline). | *Download* opens the release page; *Dismiss* continues. Never enter your seed into anything but the wallet itself. |
| Android: update apk refuses to install | Signature mismatch between builds. | Back up the seed **before** uninstalling; see [3.2](#32-android). |
| First sync is slow / server busy errors | Server throttling (automatic retry, up to 8 attempts) and/or a large transaction history — sync time scales with transaction count, not balance, worse on mobile. | Wait; progress is cached, so restarting resumes rather than repeats. See [12.3](#123-what-synchronization-actually-does). Do not use this wallet for mining payouts (many small transactions). |
---
## 19. Glossary
- **SPV** — Simplified Payment Verification: validating that transactions are included in
blocks via Merkle proofs, without running a full node.
- **Seed / mnemonic** — the 12 (or 24) BIP39 words that deterministically generate every key
in the wallet.
- **Passphrase (BIP39)** — optional extra secret combined with the seed; a different
passphrase yields a different wallet.
- **Script type** — the address format standard (Legacy/BIP44, Wrapped SegWit/BIP49, Native
SegWit/BIP84, Taproot/BIP86).
- **xpub / xprv** — extended public/private key of the wallet's account; the xpub watches,
the xprv spends. SLIP-132 variants: ypub/zpub etc.
- **WIF** — Wallet Import Format: a single address's private key as text.
- **UTXO** — Unspent Transaction Output: a discrete "coin" the wallet can spend.
- **Change** — the portion of spent UTXOs returned to your own (internal) addresses.
- **Coinbase** — the transaction paying the miner of a block; spendable after 121
confirmations.
- **Mempool** — the set of broadcast-but-unconfirmed transactions.
- **Gap limit** — how many consecutive unused addresses the wallet scans past before
stopping (20).
- **PSBT** — Partially Signed Bitcoin Transaction: the standard interchange format for
signing a transaction on a device other than the one that built it.
- **RBF** — Replace-By-Fee: a signal that a transaction may be replaced by a higher-fee
version while unconfirmed.
- **TOFU** — Trust On First Use: pinning a server's TLS certificate at first contact and
refusing silent changes afterwards.
- **Watch-only** — a wallet holding only public keys: full visibility, zero spending
ability.
---
*This guide documents observed behavior of the software and is kept in sync with the code.
For the formal threat model see [SECURITY.md](SECURITY.md); for per-release changes see
[CHANGELOG.md](CHANGELOG.md).*
blueprint.md
-670
View File
@@ -1,670 +0,0 @@
# Blueprint — Wallet desktop per criptovaluta UTXO/SPV
> Specifica **autonoma e indipendente dal linguaggio** per costruire da zero un wallet
> **solo desktop** (Windows e Linux), orientato al power-user come Sparrow Wallet.
>
> Il documento è pensato per essere letto e implementato **passo per passo**: contiene
> tutto il necessario — algoritmi, strutture dati, parametri, protocollo di rete e
> sequenza di costruzione — senza presupporre un framework, un linguaggio o un codice
> sorgente preesistente. Ogni funzionalità elencata va considerata **parte del prodotto
> completo**; quelle marcate *(opzionale)* possono essere rimandate a release successive
> ma sono comunque documentate.
---
## 0. Glossario rapido
| Termine | Significato |
|---|---|
| **SPV** | Simplified Payment Verification: il wallet non scarica la catena, verifica le transazioni tramite prove di Merkle sugli header dei blocchi. |
| **UTXO** | Unspent Transaction Output: una "moneta" non spesa; il saldo è la somma degli UTXO controllati dal wallet. |
| **HD** | Hierarchical Deterministic: tutte le chiavi derivano da un seed unico (BIP32). |
| **PSBT** | Partially Signed Bitcoin Transaction: formato standard per transazioni firmate parzialmente (offline, multisig, hardware). |
| **Watch-only** | Wallet che conosce solo le chiavi pubbliche: vede saldo e storico ma non può firmare. |
| **Server di indicizzazione** | Server che indicizza la catena e risponde alle query del client (protocollo §10). |
| **Scripthash** | SHA-256 dello scriptPubKey con byte invertiti: chiave con cui il server indicizza gli indirizzi. |
---
## 1. Visione del prodotto
Un wallet **desktop nativo** con queste qualità target (modello Sparrow):
- **Solo desktop**: nessuna UI mobile. UX densa, orientata a trasparenza e controllo.
- **Single-sig e multisig** di prima classe, con supporto hardware wallet.
- **Controllo totale su monete e fee**: coin control (UTXO), selezione manuale, etichette,
controllo fee, RBF/CPFP.
- **PSBT-centrico**: ogni flusso di firma passa per PSBT, abilitando firma offline,
air-gapped e collaborativa.
- **Leggero (SPV)**: avvio immediato, nessun full node richiesto (ma con possibilità di
collegare un server proprio).
- **Privacy-aware**: coin selection che preserva la privacy, supporto proxy/Tor,
possibilità di server privato.
- **Eseguibile distribuibile**: binario per Windows e Linux, firma del codice, build
riproducibili.
L'applicazione è strutturata in due grandi blocchi: un **core** (logica pura, senza UI) e
una **GUI desktop** sopra di esso. Tutta la logica di seguito appartiene al core, tranne
dove indicato.
---
## 2. Architettura a livelli (target)
```
┌─────────────────────────────────────────────────────────────────────┐
│ GUI desktop — viste, wizard, coin control, dialog di firma │
├─────────────────────────────────────────────────────────────────────┤
│ Application API — casi d'uso: crea/apri wallet, invia, ricevi, │
│ firma, storico, gestione canali, ecc. │
│ Esposta anche come CLI + RPC locale (§13). │
├─────────────────────────────────────────────────────────────────────┤
│ Dominio wallet — wallet, keystore, indirizzi, UTXO, contatti, │
│ fatture, richieste, costruzione/firma tx, │
│ coin selection, fee policy │
├─────────────────────────────────────────────────────────────────────┤
│ SPV / Sincronizz. — synchronizer, verifier (Merkle), gestione │
│ header/checkpoint, saldo e storico │
├─────────────────────────────────────────────────────────────────────┤
│ Rete — pool di connessioni, selezione server, TLS │
│ con pinning, proxy, protocollo di query (§10) │
├─────────────────────────────────────────────────────────────────────┤
│ Crittografia — secp256k1, hash, BIP32/39/SLIP39, base58, │
│ bech32, cifratura file wallet, ECIES │
├─────────────────────────────────────────────────────────────────────┤
│ Persistenza — file wallet JSON cifrato, config, percorsi │
│ Lightning (⏳ poi) — sottosistema separato, fase successiva (§11) │
└─────────────────────────────────────────────────────────────────────┘
```
**Regola di dipendenza:** ogni livello dipende solo verso il basso. La GUI parla solo con
l'Application API, mai direttamente con rete o crittografia. Questo permette di avere
CLI, test automatici e GUI sullo stesso core.
### Requisiti di componenti (astratti, non legati al linguaggio)
Indipendentemente dallo stack scelto, servono librerie/moduli che forniscano:
1. **Curva ellittica secp256k1** (firma/verifica ECDSA + Schnorr, tweak chiavi). *Non
reimplementare a mano la matematica della curva: usare una libreria auditata.*
2. **Funzioni hash**: SHA-256, doppio SHA-256, RIPEMD-160, HASH160 (SHA256→RIPEMD160),
SHA-512, HMAC-SHA512, PBKDF2-HMAC-SHA512.
3. **Encoding**: Base58Check, Bech32 e Bech32m.
4. **Cifratura simmetrica** (AES-256) e **ECIES** per messaggi.
5. **TLS** con accesso al certificato per il pinning.
6. **JSON** per file wallet e protocollo.
7. **Generatore di numeri casuali crittografico** per seed e nonce.
---
## 3. Profilo di rete / catena (parametri da definire PRIMA di tutto)
Un wallet è legato a una catena specifica tramite un insieme di costanti. **Vanno fissate
all'inizio**: un valore sbagliato produce indirizzi non validi o fa rifiutare la catena.
Definire un oggetto/struct di configurazione con i seguenti campi.
> I valori del profilo di riferimento qui sotto sono stati **verificati contro il sorgente
> del nodo** (`chainparams.cpp` / `pow.cpp`): sono i parametri di consenso autoritativi.
| Campo | Descrizione | Esempio (profilo di riferimento mainnet) |
|---|---|---|
| `net_name` | nome rete / sottocartella dati | `mainnet` |
| `coin_unit` | simbolo unità | `PLM` |
| `wif_prefix` | prefisso chiavi private WIF | `0x80` |
| `addr_p2pkh` | byte versione indirizzi legacy | `55` → indirizzi che iniziano con `P` |
| `addr_p2sh` | byte versione indirizzi P2SH | `5` → iniziano con `3` |
| `segwit_hrp` | prefisso human-readable bech32 | `plm` → indirizzi `plm1...` |
| `bolt11_hrp` | prefisso fatture Lightning | `plm` |
| `genesis_hash` | hash del blocco genesi (mainnet riusa la genesi di Bitcoin) | `000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f` |
| `default_ports` | porte del **server di indicizzazione** usato dal wallet | `{tcp: 50001, ssl: 50002}` |
| `bip44_coin_type` | coin type SLIP-0044 nel derivation path (*convenzione wallet, non parametro di consenso del nodo*) | `746` |
| `uri_scheme` | schema URI pagamenti (BIP21) | `palladium:` |
| `explorer_url` | block explorer di default | `https://explorer.palladium-coin.com/` |
| `skip_pow_validation` | salta la verifica difficoltà — **obbligatorio**: la catena usa LWMA (vedi nota sotto) | `true` |
> **Nota sulle porte.** Le `default_ports` sopra sono quelle del **server di indicizzazione**
> (es. ElectrumX-like) a cui si connette il wallet, **non** la porta P2P del nodo (che nel
> sorgente è `2333` mainnet / `12333` testnet / `28444` regtest). Sono due cose distinte: il
> wallet SPV parla solo col server di indicizzazione.
>
> **Nota sulla difficoltà (LWMA).** Il nodo calcola la difficoltà con **LWMA** (Linearly
> Weighted Moving Average) e un **tempo di blocco di 2 minuti** (`nPowTargetSpacingV2 = 120s`;
> il vecchio `nPowTargetTimespan` di 14 giorni è mantenuto solo per la validazione storica).
> Un client SPV non è in grado di ricalcolare LWMA, quindi `skip_pow_validation` **deve**
> essere `true` e la fiducia sulla catena va ancorata ai **checkpoint** (§7.3).
**Header chiavi estese BIP32** (mainnet di riferimento) — servono per serializzare/parsare
xprv/xpub per ciascun tipo di indirizzo:
| Tipo indirizzo | prefisso priv | header priv | prefisso pub | header pub |
|---|---|---|---|---|
| standard (P2PKH) | xprv | `0x0488ade4` | xpub | `0x0488b21e` |
| segwit wrapped (P2WPKH-P2SH) | yprv | `0x049d7878` | ypub | `0x049d7cb2` |
| multisig wrapped (P2WSH-P2SH) | Yprv | `0x0295b005` | Ypub | `0x0295b43f` |
| native segwit (P2WPKH) | zprv | `0x04b2430c` | zpub | `0x04b24746` |
| native segwit multisig (P2WSH) | Zprv | `0x02aa7a99` | Zpub | `0x02aa7ed3` |
**Testnet** (profilo di riferimento): `wif_prefix=0xff`, `addr_p2pkh=127`, `addr_p2sh=115`,
`segwit_hrp=tplm`, `bip44_coin_type=1`, header tprv/tpub `0x04358394`/`0x043587cf`, ecc.
**Regtest**: `segwit_hrp=rplm`.
**Server iniziali** (bootstrap, profilo di riferimento): forniti come lista
`host:porta_tcp:porta_ssl`; il pool li usa per il primo contatto e poi scopre altri peer
via protocollo (`server.peers.subscribe`).
> Tutte le costanti devono essere **centralizzate** in un solo punto e selezionabili per
> rete (mainnet/testnet/regtest), così da non disperdere magic number nel codice.
---
## 4. Crittografia, seed e gestione chiavi
### 4.1 Seed e mnemoniche — tutti gli schemi supportati
Il wallet deve supportare **più schemi di seed** e saperli riconoscere automaticamente:
1. **Seed nativo versionato**: mnemonica con un prefisso di versione codificato via HMAC
(distingue i sottotipi `standard`, `segwit`, `2fa`, `2fa-segwit`). In creazione si
garantisce che la mnemonica generata **non** sia contemporaneamente un valido BIP39.
2. **BIP39**: import/restore di seed standard a **12 o 24 parole**, con verifica del
checksum.
3. **SLIP39 (Shamir Secret Sharing)** *(opzionale)*: seed suddiviso in più *share*; servono
K share su N per ricostruirlo.
4. **Formato seed legacy** *(opzionale, retrocompatibilità)*: vecchio schema pre-BIP32.
**Wordlist multilingua**: inglese, spagnolo, giapponese, portoghese, cinese. Le parole
vanno normalizzate (NFKD) prima della derivazione.
**Passphrase / extension word (opzionale ma obbligatoria da implementare):** parola/e
aggiuntive combinate col seed tramite **PBKDF2-HMAC-SHA512, 2048 round**, con salt
`"<schema>" + passphrase` (per il seed nativo il prefisso del salt è una costante dello
schema; per BIP39 è `"mnemonic" + passphrase`). Cambia completamente il wallet derivato.
Avvisi UI obbligatori: se persa, i fondi sono **irrecuperabili**; va annotata separatamente
dal seed; è case-sensitive e gli spazi contano.
### 4.2 Derivazione gerarchica (BIP32/BIP44/49/84)
- Da seed → **root key** (BIP32). Da root → chiavi estese per account.
- Path standard con il `coin_type` del profilo:
- Legacy P2PKH: `m/44'/<coin>'/account'/change/index`
- Segwit wrapped P2SH-P2WPKH: `m/49'/<coin>'/account'/change/index`
- Native segwit P2WPKH: `m/84'/<coin>'/account'/change/index`
- Multisig: `m/48'/<coin>'/account'/script_type'/...`
- Supportare **derivation path personalizzati** (Sparrow-like): l'utente può specificare il
path manualmente in import.
- Catena `change=0` (receiving) e `change=1` (change). Derivazione per indice on-demand.
### 4.3 Tipi di indirizzo (tutti)
| Tipo | script | prefisso (profilo rif.) | uso |
|---|---|---|---|
| Native SegWit | P2WPKH | `plm1...` | **default consigliato**: fee minime |
| Legacy | P2PKH | `P...` | massima compatibilità |
| SegWit wrapped | P2SH-P2WPKH | `3...` | compatibilità intermedia |
| Multisig native | P2WSH | `plm1...` | M-di-N moderno |
| Multisig wrapped | P2SH / P2SH-P2WSH | `3...` | M-di-N legacy |
### 4.4 Tipi di keystore (sorgenti di chiavi)
- **HD da seed** (caso principale): seed → root → xprv/xpub.
- **HD da master key importata**: import di xprv/xpub (o y/z varianti). Solo xpub = watch-only.
- **Chiavi private importate**: lista di chiavi WIF singole.
- **Hardware wallet**: la chiave privata non lascia mai il dispositivo (vedi §4.6).
- **Keystore "split/2FA"** *(opzionale)*: parte della firma delegata a un servizio remoto.
- **Keystore legacy** *(opzionale)*.
### 4.5 Tipi di wallet
- **Standard** (single-sig HD) — caso d'uso principale.
- **Multisig M-di-N** — combinazione di più keystore (seed/xpub/hardware misti).
- **Importato** — indirizzi o chiavi private importate; può essere watch-only o spendibile.
- **Watch-only** — solo chiavi pubbliche; costruisce ma non firma (esporta PSBT).
Una factory legge il tipo dal file wallet e istanzia la classe corretta.
### 4.6 Hardware wallet (tutti i modelli supportati)
Integrazione con dispositivi hardware via il loro protocollo USB/HID/seriale. Modelli da
supportare: **Trezor, Ledger, KeepKey, Coldcard, BitBox02, Digital BitBox, Safe-T, Jade**.
Funzioni: import dell'xpub dal dispositivo, conferma indirizzo sullo schermo del device,
firma PSBT sul device (la chiave privata non viene mai esposta), gestione PIN/passphrase.
Per i dispositivi air-gapped (es. Coldcard): scambio PSBT via file/QR/microSD.
### 4.7 Backup e sicurezza delle chiavi
- **Cifratura del file wallet** con password (vedi §8); cambio password.
- **Cifratura/decifratura messaggi** e firma/verifica messaggi con una chiave.
- **Export**: seed, master private key, master public key, chiavi private (per indirizzo o
per path), in modo protetto (richiesta password).
- **Backup su carta con visual one-time-pad** *(opzionale, "revealer")*: genera un foglio
cifrato che, sovrapposto a una griglia segreta stampata, rivela il seed.
- **Recupero a timelock** *(opzionale)*: predisposizione di transazioni di recupero che
diventano spendibili dopo un timelock, per ereditarietà/dead-man-switch.
---
## 5. Ricezione fondi
- **Generazione indirizzi**: prossimo indirizzo non usato; lista indirizzi receiving e
change; rispetto del **gap limit** (numero massimo di indirizzi vuoti consecutivi
scansionati; configurabile, con comando per aumentarlo).
- **Richieste di pagamento**: creare una richiesta con importo, scadenza, descrizione;
elencarle, eliminarle, segnarne lo stato (in attesa/pagata/scaduta).
- **URI BIP21**: generare e parsare `«scheme»:«indirizzo»?amount=...&label=...&message=...`.
- **QR code**: generazione per indirizzi/URI/richieste; scansione da webcam o immagine.
- **Risoluzione nomi**: OpenAlias/DNS, LNURL, e richieste firmate BIP70 *(opzionale)*.
- **Etichette** sugli indirizzi e sulle richieste.
---
## 6. Invio fondi e costruzione transazioni
### 6.1 Composizione
- **Pay-to** singolo e **pay-to-many** (più output in una sola transazione).
- Input destinatario: indirizzo, URI, nome OpenAlias/LNURL, o richiesta scansionata.
- Importo in unità coin o in fiat (con conversione al tasso corrente).
- Opzione **"invia tutto"** (max), con sottrazione fee dall'importo.
- **Locktime** e **sequence** impostabili (per RBF/timelock).
- Etichetta della transazione.
### 6.2 Coin control (cuore di un wallet desktop)
- Vista UTXO completa con importi, indirizzo, conferme, etichetta.
- **Selezione manuale** degli UTXO da spendere (coin control).
- **Freeze/unfreeze** di indirizzi e di singoli UTXO (esclusi dalla spesa automatica).
- Visualizzazione del *change* previsto e dell'indirizzo di change.
### 6.3 Strategie di selezione monete (coin selection)
Implementare almeno due strategie selezionabili:
- **Privacy-preserving**: raggruppa gli UTXO per indirizzo (evita di unire monete di
indirizzi diversi), riduce la perdita di privacy futura e il bloat di UTXO.
- **Random**: selezione casuale con arrotondamento del change per offuscare gli importi.
Obiettivi comuni: minimizzare fee, evitare output *dust*, gestire il change correttamente.
### 6.4 Politiche di fee (tutte)
Modalità di calcolo fee, selezionabili:
- **Fissa** (importo assoluto).
- **Fee rate fisso** (sat/vByte).
- **Dinamica ETA-based**: stima dal server per un target di conferma (es. 1, 2, 5, 10, 25,
144, 1008 blocchi).
- **Dinamica mempool-based**: in base allo stato della mempool.
Mostrare sempre fee totale, fee rate effettivo e dimensione virtuale stimata. Avviso se la
fee è anomala (troppo alta/bassa).
### 6.5 Firma e modello PSBT
Ogni transazione non banale passa per **PSBT**:
- **Crea** PSBT (non firmata) dal wallet.
- **Firma** con: keystore software, hardware wallet, o firma offline su altra macchina.
- **Combina** PSBT parzialmente firmate (multisig: ogni cosigner firma e si uniscono).
- **Finalizza** ed estrai la transazione grezza.
- **Import/export PSBT** via: file, **QR code** (anche animato per PSBT grandi),
**scambio su rete decentralizzata per cosigning** *(opzionale)*, **trasmissione audio**
*(opzionale, "audio modem")*.
- Flusso **watch-only / air-gapped**: la macchina online crea la PSBT, quella offline firma,
la online trasmette.
### 6.6 Gestione post-invio
- **Broadcast** della transazione (e broadcast di un *pacchetto* di transazioni correlate).
- **RBF (Replace-By-Fee)**: bump della fee di una tx non confermata; **cancellazione**
(invio a sé stessi con fee più alta).
- **CPFP (Child-Pays-For-Parent)**: accelerare una tx in entrata spendendola con fee alta.
- **Rimozione di tx locali** non confermate.
- **Sweep**: spazzare tutti i fondi di una chiave privata esterna verso il wallet.
- **Aggiunta manuale di una tx** (incolla raw/hex) e firma con chiave fornita.
### 6.7 Reportistica
- **Plusvalenze/minusvalenze on-chain** (capital gains) per anno fiscale.
- Esportazione storico (CSV/JSON) con etichette.
- Timestamp di inizio/fine anno per i report.
---
## 7. Blockchain, sincronizzazione e validazione (SPV)
### 7.1 Modello SPV
Il wallet **non scarica la catena completa**. Mantiene solo gli **header dei blocchi** e
verifica le transazioni che lo riguardano con **prove di Merkle** contro tali header.
### 7.2 Validazione header
- Header a lunghezza fissa (campi: versione, prev_hash, merkle_root, timestamp, bits, nonce).
- Verifica del **collegamento** (prev_hash) e dell'**hash atteso** di ogni header.
- **Proof-of-Work**: confronto `hash <= target` e coerenza dei `bits`.
- **Difficoltà**: la catena di riferimento usa **LWMA** (retargeting per-blocco, tempo di
blocco 2 minuti — confermato dal nodo). Un client SPV non ricalcola LWMA, quindi il flag
`skip_pow_validation` del profilo (§3) **disattiva** il controllo bits/target; in tal caso
la fiducia è ancorata ai **checkpoint** (sotto). Implementare entrambe le modalità (PoW
classico stile Bitcoin e modalità "skip" per catene LWMA).
- Header organizzati in **chunk** (es. 2016) salvati su file locale; gestione di **fork**
(più rami concorrenti) con scelta del ramo a maggior lavoro.
### 7.3 Checkpoint
Lista hardcoded di `[hash, target]` a intervalli regolari, usata per:
- accelerare la validazione iniziale (non riverificare dall'origine),
- ancorare la validità della catena quando la verifica PoW è disattivata.
Fornire un meccanismo per aggiornare/spedire i checkpoint con le release.
### 7.4 Sincronizzazione wallet
1. Per ogni indirizzo: calcola lo **scripthash**, sottoscrivi al server.
2. Alla notifica di cambiamento: richiedi lo **storico** (lista txid + altezza).
3. Scarica le transazioni mancanti.
4. **Verifica** ciascuna con prova di Merkle contro l'header all'altezza indicata.
5. Aggiorna saldo (confermato/non confermato), UTXO e storico.
6. Estendi la scansione finché si raggiunge il gap limit di indirizzi vuoti.
---
## 8. Persistenza e configurazione
- **File wallet**: un file (JSON) contenente keystore, indirizzi, storico, etichette,
contatti, richieste, fatture, (e stato canali Lightning se attivo). **Cifrato** con AES
quando è impostata una password (la password protegge il file su disco; **non** sblocca
il seed). Schema **versionato** con migrazioni automatiche all'apertura.
- **Configurazione globale** separata dal wallet: rete selezionata, server, proxy, unità,
lingua, politiche fee di default, block explorer.
- **Percorsi dati** per piattaforma + **modalità portable** (dati accanto all'eseguibile,
utile per chiavette USB).
- **Multi-wallet**: aprire/chiudere più wallet, elencarli, passare dall'uno all'altro.
---
## 9. Rete e connettività
- **Pool di connessioni**: più server contemporaneamente per ridondanza; un server
"primario" per gli header; fan-out delle query.
- **Selezione server**: automatica o manuale; scoperta di nuovi peer dal protocollo.
- **TLS con pinning (TOFU)**: al primo contatto il certificato del server viene salvato; ai
successivi viene confrontato. Se cambia → connessione rifiutata. Fornire un comando
**"reset certificati SSL"** per i server self-signed (caso tipico: il server rinnova il
certificato e il client va sbloccato manualmente).
- **Proxy / Tor**: supporto SOCKS5 per instradare tutto il traffico.
- **Stima fee** dal server; **relay fee** minima.
- **Stato connessione** visibile in UI; riconnessione automatica.
---
## 10. Protocollo client ↔ server (query di indicizzazione)
Il client comunica via **JSON-RPC** (su TCP, opzionalmente TLS). Implementare richieste e
parsing per i seguenti metodi (gli indirizzi sono indicizzati per **scripthash**):
```
# Negoziazione / server
server.version server.banner server.features
server.ping server.peers.subscribe server.donation_address
# Header / catena
blockchain.headers.subscribe blockchain.block.header blockchain.block.headers
blockchain.estimatefee blockchain.relayfee
# Indirizzi (per scripthash)
blockchain.scripthash.subscribe blockchain.scripthash.get_balance
blockchain.scripthash.get_history blockchain.scripthash.listunspent
# Transazioni
blockchain.transaction.get blockchain.transaction.get_merkle
blockchain.transaction.broadcast blockchain.transaction.broadcast_package
blockchain.transaction.id_from_pos
```
---
## 11. Lightning Network — ⏳ DA FARE IN SEGUITO (fase successiva, fuori dal primo rilascio)
> **Non incluso nel primo rilascio.** Coerentemente con il modello Sparrow (on-chain only),
> il wallet parte **senza Lightning**. Questo capitolo resta documentato come specifica per
> una **fase successiva**: va affrontato solo dopo che tutte le funzioni on-chain (§4–§10)
> sono complete e stabili. Va progettato come **sottosistema separato e disattivabile**, in
> modo da non bloccare né complicare il primo rilascio.
Quando verrà affrontato, è un grande sottosistema a sé. Funzionalità da implementare:
- **Canali**: apertura, chiusura cooperativa e forzata, lista canali e peer.
- **Pagamenti**: invio/ricezione su BOLT11, **MPP** (multi-part payments), **trampoline
routing**, onion routing, gossip/routing della rete.
- **Fatture**: creazione/decodifica BOLT11; **hold invoice** (trattenute fino a conferma).
- **Backup canali**: export/import dei backup di stato (critici per non perdere fondi).
- **Watchtower**: locale e remoto, per punire chiusure fraudolente quando offline.
- **Submarine swap**: scambio on-chain ↔ Lightning, con provider/server di swap;
rebalance dei canali.
- **LNURL** e indirizzi Lightning (lightning-address).
- **Nostr Wallet Connect (NWC)** *(opzionale)*: controllo remoto del wallet Lightning.
- **Payserver** *(opzionale)*: endpoint per ricevere pagamenti.
> **Promemoria:** per il primo rilascio Lightning è escluso. Le funzioni base (§4–§10) non
> dipendono in alcun modo da questo capitolo; affrontarlo solo come iterazione successiva.
---
## 12. Contatti, etichette e dati ausiliari
- **Rubrica contatti**: nome ↔ indirizzo, con ricerca.
- **Etichette** su indirizzi, transazioni, UTXO, richieste.
- **Sincronizzazione etichette** *(opzionale)*: cifrate, condivise tra istanze del wallet
via un servizio.
- **Lista fatture** (uscite) e **lista richieste** (entrate) con stato.
---
## 13. Interfacce non grafiche
- **CLI**: ogni caso d'uso del core esposto come comando da riga di comando (utile per
scripting e per i test automatici).
- **RPC locale / daemon** *(opzionale)*: un processo in background che espone l'API su
socket locale autenticato, così la GUI e strumenti esterni parlano con lo stesso core.
Famiglie di comandi da prevedere (elenco rappresentativo della superficie API completa):
creazione/restore/apertura/chiusura wallet, generazione indirizzi, saldo e storico,
pay-to / pay-to-many, firma/broadcast, gestione PSBT (deserialize/combine/finalize),
freeze/unfreeze UTXO, bumpfee/cancel, sweep, import/export chiavi e xkey, conversione xkey,
firma/verifica messaggi, gestione richieste e fatture, contatti, conversione fiat,
stato sincronizzazione, gestione server/config. *(Comandi Lightning — apertura/chiusura
canali, pagamenti, swap, backup canali — solo nella fase successiva, vedi §11.)*
---
## 14. Funzioni di supporto e infrastruttura
- **Tassi di cambio / fiat**: integrazione con più provider di prezzo; conversione importi
in valuta locale; **prezzi storici** per la reportistica; aggiornamento periodico.
- **Internazionalizzazione (i18n)**: UI multilingua, con rilevamento lingua di sistema.
- **Crash reporter**: raccolta e invio (con consenso) dei crash.
- **Sistema di plugin** *(opzionale)*: caricamento di estensioni (hardware wallet, swap
server, watchtower, label sync, ecc.) come moduli separati.
- **Hardening memoria** *(opzionale)*: blocco in RAM (no swap su disco) dei segreti dove il
SO lo consente; azzeramento dei buffer sensibili dopo l'uso.
- **Block explorer**: apertura di tx/indirizzi nell'explorer configurato.
---
## 15. Wizard di creazione/restore (flusso UI)
1. Avvio: **crea nuovo wallet** / **apri esistente** / **importa**.
2. Tipo wallet: **Standard** / **Multisig (M-di-N)** / **Importa indirizzi o chiavi** /
**Hardware**.
3. Per Standard: **nuovo seed** / **ho già un seed** / **usa master key** / **usa device hardware**.
4. Nuovo seed → mostra le parole → **conferma** reinserendole.
5. **Passphrase** opzionale (extension word) con avvisi (§4.1).
6. Scelta **tipo di indirizzo** (default: native segwit).
7. **Password** di cifratura del file wallet.
8. Sincronizzazione e comparsa di saldo/storico.
Per multisig: raccolta di N cosigner (seed/xpub/hardware), scelta soglia M, derivation path
e tipo di script; generazione del descrittore del wallet e verifica incrociata degli xpub
tra i partecipanti.
---
## 16. Sequenza di costruzione consigliata (passo per passo)
Costruire e **testare** in quest'ordine; ad ogni passo verificare con vettori noti.
1. **Profilo di rete (§3)**: centralizzare tutte le costanti; selettore mainnet/testnet/regtest.
2. **Crittografia e chiavi (§4)**: hash, secp256k1, base58/bech32, BIP32/39, generazione
indirizzi. *Test:* dato un seed → produrre gli indirizzi attesi (golden vectors).
3. **Persistenza (§8)**: definire e versionare lo schema del file wallet (JSON) + cifratura.
4. **Rete + protocollo (§9–10)**: connessione, TLS+pinning, query base.
5. **SPV + sincronizzazione (§7)**: header, checkpoint, Merkle, saldo/storico su un wallet
**watch-only**. *Test:* stesso xpub → stesso saldo di un wallet di riferimento.
6. **Transazioni (§6)**: costruzione, coin selection, fee, PSBT, firma, broadcast su testnet.
7. **GUI desktop (§15 + viste)**: wizard, dashboard saldo/storico, invia (con coin control),
ricevi, UTXO, contatti, impostazioni.
8. **Hardware wallet (§4.6)** e **multisig (§4.5)**: firma collaborativa via PSBT.
9. **Estensioni**: fiat/exchange rate, label sync, reportistica.
10. **⏳ Fase successiva (post-rilascio)**: **Lightning (§11)** come sottosistema separato,
da iniziare solo quando i passi 1–9 sono completi e stabili.
**Test cross-implementazione (obbligatorio per un wallet):** ad ogni passo confrontare gli
output (indirizzi, txid, PSBT) con un wallet di riferimento usando gli stessi input. Un
indirizzo o un txid diverso è un bug bloccante.
---
## 17. Requisiti di sicurezza (non negoziabili)
- Seed e chiavi private **mai** in chiaro su disco non cifrato, **mai** nei log, **mai**
inviati in rete.
- Cifratura del file wallet con derivazione robusta della chiave dalla password.
- Validare **ogni** dato proveniente dalla rete: le risposte dei server **non sono fidate**;
verificare sempre con prove di Merkle + checkpoint.
- Watch-only realmente read-only: nessuna chiave privata derivabile dalle sole pubbliche.
- TLS con pinning del certificato e reset esplicito controllato dall'utente.
- Azzeramento dei segreti in memoria dopo l'uso; ove possibile blocco anti-swap.
- **Firma del codice** dei binari Windows/Linux e **build riproducibili** per consentire la
verifica indipendente.
---
## 18. Packaging e distribuzione desktop
- **Windows**: eseguibile installabile e versione **portable** (dati accanto all'exe).
Firma Authenticode.
- **Linux**: formato portabile autoconsistente (es. immagine eseguibile singola) e/o
pacchetto nativo; firma GPG dei rilasci.
- **Build riproducibili** (ambiente di build isolato/containerizzato) e pubblicazione degli
hash + firme dei binari.
- File di associazione per lo schema URI dei pagamenti (`uri_scheme` del profilo) così che i
link di pagamento aprano il wallet.
---
## 19. Stack tecnologico raccomandato (.NET 8 + Avalonia + NBitcoin)
> I capitoli §1–§18 sono **indipendenti dal linguaggio** e restano il riferimento. Questa
> sezione propone una **realizzazione concreta** scelta per tre vincoli: sviluppo assistito
> da IA, **semplicità**, e **un solo sorgente** che produca sia `.exe` (Windows) sia
> AppImage (Linux). Lo stack non è obbligatorio: è la via più liscia per *questo* prodotto.
### 19.1 Perché questo stack
- **`NBitcoin` (C#)** modella reti altcoin custom via `NetworkBuilder` (prefissi
P2PKH/P2SH, WIF, header BIP32 xpub/xprv, HRP bech32, genesi): mappatura **diretta** della
§3. Fornisce già HD/BIP32/39, indirizzi (legacy/segwit/wrapped), costruzione e
serializzazione transazioni, **PSBT**, firma, base58/bech32, hashing → è la libreria che
fa scrivere **meno crittografia a mano** per un altcoin.
- **Avalonia UI** è cross-platform nativo: un solo sorgente per Windows e Linux.
- **C#/.NET** ha tooling maturo e un enorme corpus → l'IA produce codice idiomatico con
poche frizioni; alto livello e GC = sviluppo rapido.
- Posizione di **sicurezza accettabile** sulle chiavi senza la curva di apprendimento di
Rust e senza i rischi di Electron (chiavi in JS, footprint, supply-chain npm).
*Alternative scartate:* **Rust + BDK + Tauri** (binari minimi e memory-safe, ma curva
ripida e customizzazione altcoin più laboriosa → contro "semplicità"); **Electron + TS**
(packaging e UI rapidissimi, ma gestione chiavi più fragile → sconsigliato per un wallet);
**Java/JavaFX** (è lo stack di Sparrow e produce già `.exe`+AppImage, ma nessun vantaggio
netto su .NET per questo caso).
### 19.2 Cosa è coperto dalla libreria e cosa va scritto a mano
**Coperto da NBitcoin** (non reimplementare): rete custom, BIP32/39, indirizzi,
transazioni, PSBT, firma, base58/bech32, hashing.
**Da implementare a mano** (NBitcoin non lo include — è il grosso del lavoro originale):
1. **Client del protocollo del server di indicizzazione** (§10): JSON-RPC su TCP/TLS,
pool di connessioni, TLS pinning/TOFU, reset certificati, proxy/Tor.
2. **Sincronizzazione SPV** (§7.4): scripthash, storico, verifica prove di Merkle.
3. **Validazione header + checkpoint con modalità "skip PoW"** per LWMA (§3/§7):
NBitcoin assume il retargeting di Bitcoin, quindi questo strato è **custom**.
4. **Coin selection** privacy-preserving e **fee policy** (fissa/rate/ETA/mempool),
RBF/CPFP (§6): logica di dominio sopra le primitive NBitcoin.
5. **File wallet cifrato** (schema JSON versionato + AES) e **config** (§8).
### 19.3 Mappatura strato del blueprint → componente concreto
| Strato (§2) | Realizzazione |
|---|---|
| Crittografia (§4) | NBitcoin (`Network` custom, `ExtKey`, `Mnemonic`, `BitcoinAddress`, `PSBT`) |
| Profilo rete (§3) | `NetworkBuilder` con i valori §3, centralizzato in `Core/Chain` |
| SPV/Sync (§7) | codice custom in `Core/Spv` |
| Rete/protocollo (§9–10) | client custom in `Core/Net` |
| Dominio wallet (§4–§6) | `Core/Wallet` sopra NBitcoin |
| Persistenza (§8) | `System.Text.Json` + AES in `Core/Storage` |
| Application API (§13) | progetti `Cli` e API condivisa |
| GUI desktop (§15) | Avalonia in `App` |
### 19.4 Struttura del progetto (una sola solution .NET)
```
PalladiumWallet.sln
├─ src/Core/ (libreria, nessuna dipendenza UI)
│ ├─ Chain/ profilo rete (NetworkBuilder), costanti §3, checkpoint
│ ├─ Crypto/ wrapper NBitcoin: seed, BIP32/39, indirizzi, keystore
│ ├─ Wallet/ wallet, UTXO, coin selection, fee policy, PSBT, firma
│ ├─ Spv/ header store, verifier (Merkle), sync
│ ├─ Net/ client protocollo, pool, TLS pinning, proxy
│ └─ Storage/ file wallet JSON cifrato, config
├─ src/App/ (Avalonia UI: wizard, dashboard, invia/ricevi, coin control)
├─ src/Cli/ (riga di comando sullo stesso Core — utile ai test)
└─ tests/ (xUnit: golden vectors indirizzi/txid, test SPV)
```
Regola di dipendenza (§2): `App` e `Cli` dipendono da `Core`; `Core` non conosce la UI.
### 19.5 Ambiente di sviluppo e build — tutto su Ubuntu, senza Wine
- **Dev**: `.NET 8 SDK` (repo Microsoft / `apt`), VS Code + estensione C# o Rider.
Avalonia gira ed è eseguibile nativamente su Ubuntu.
- **Architetture host**: si sviluppa sia su **x86_64** sia su **arm64** (il .NET SDK è
nativo su `linux-x64` e `linux-arm64`; NBitcoin è C# puro gestito, nessuna dipendenza
nativa legata all'arch).
- **Build cross dei binari da Linux, senza Wine** (.NET cross-targeta nativamente):
- Windows: `dotnet publish -r win-x64 -p:PublishSingleFile=true --self-contained` → `.exe`.
- Linux: `dotnet publish -r linux-x64 --self-contained`.
- **Docker** consigliato: un solo `Dockerfile` su `mcr.microsoft.com/dotnet/sdk:8.0`
produce i target in modo riproducibile.
- Wine **non** serve per compilare. Servirebbe solo per costruire un *installer* Windows
con Inno Setup su Linux (evitabile distribuendo l'`.exe` single-file **portable**) o per
*testare* l'`.exe` su Linux (test, non build). Firma Authenticode fattibile da Linux con
`osslsigncode`.
### 19.6 Packaging "un sorgente → .exe + AppImage" (multi-architettura)
Da una macchina **Ubuntu x86_64** si producono tutti e quattro i target:
| Target | RID | Output | Da x86_64 |
|---|---|---|---|
| Windows x64 | `win-x64` | `.exe` | ✅ diretto (no Wine) |
| Windows arm64 | `win-arm64` | `.exe` | ✅ diretto (no Wine) |
| Linux x64 | `linux-x64` | AppImage | ✅ nativo |
| Linux arm64 | `linux-arm64` | AppImage | ✅ via `docker buildx` + QEMU |
- **Binari**: `dotnet publish -r <rid> -p:PublishSingleFile=true --self-contained` per
ciascun RID. Il `.exe` Windows (x64 e arm64) esce direttamente; niente Wine.
- **AppImage Linux x64**: `dotnet publish -r linux-x64` + **PupNet Deploy** su Ubuntu.
- **AppImage Linux arm64**: il `dotnet publish -r linux-arm64` cross-compila i binari da
x86_64, ma l'assemblaggio dell'AppImage (appimagetool/runtime) è arch-specifico → si fa
con **`docker buildx` multi-arch + emulazione QEMU** (`--platform linux/arm64`) nella
stessa pipeline, così l'AppImage arm64 viene impacchettato in ambiente arm64 emulato.
- Associazione dello schema URI `palladium:`; build riproducibili in Docker; firma codice.
### 19.7 Flusso di test (non serve compilare e lanciare l'app per testare)
Tre livelli, tutti su Ubuntu, il grosso **headless**:
1. **`dotnet test`** — logica del `Core` senza GUI né rete reale: golden vector
seed→indirizzi del profilo (confronto 1:1 col wallet di riferimento), costruzione/firma
tx, PSBT, coin selection, parsing protocollo e verifica Merkle con server mockato.
2. **CLI** (`dotnet run --project src/Cli -- ...`) contro **regtest/testnet**: sync, saldo
su xpub watch-only, costruzione tx — flussi reali senza aprire la UI.
3. **GUI** solo per rifinire l'interfaccia: `dotnet run` compila+lancia in un comando, con
**Hot Reload** Avalonia e previewer XAML (niente ciclo build-lancia manuale).
**Dev-loop (equivalente di `npm run dev`) — nativo anche su Debian arm64:**
- `dotnet watch --project src/App` ≈ `npm run dev`: ricompila e applica **Hot Reload** a
ogni salvataggio, con la finestra Avalonia aggiornata dal vivo; `dotnet run` per il lancio
singolo; previewer XAML nell'IDE per le viste.
- Su **arm64 si sviluppa e si vede la grafica nativamente** (.NET SDK `linux-arm64`,
Avalonia rende con Skia, fallback software se manca l'accelerazione GPU). **QEMU non serve
per sviluppare/testare** — l'emulazione riguarda solo l'impacchettamento di AppImage di
un'altra architettura (§19.6).
- Prerequisiti runtime su Debian/Ubuntu: ambiente grafico (X11/Wayland) e librerie native di
Avalonia, es. `apt install libx11-6 libice6 libsm6 libfontconfig1 libglib2.0-0 libgl1`
(più mesa). Per logica/crypto non serve GUI: `dotnet test` e la CLI girano headless.
---
*Questo blueprint è una specifica completa e indipendente dal linguaggio. I parametri del
profilo di rete (§3) e la logica di validazione header/checkpoint (§7) sono gli elementi
critici e specifici della catena; tutto il resto è l'ingegneria standard di un wallet SPV
desktop. Implementando i capitoli nell'ordine del §16 si ottiene un wallet desktop completo
in stile Sparrow.*
docker/Dockerfile.android
+39
View File
@@ -0,0 +1,39 @@
FROM mcr.microsoft.com/dotnet/sdk:10.0
# ── Java (required by the Android SDK tools) ─────────────────────────────────
RUN apt-get update && apt-get install -y --no-install-recommends \
openjdk-17-jdk-headless \
wget \
unzip \
&& apt-get clean && rm -rf /var/lib/apt/lists/*
ENV JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
ENV ANDROID_HOME=/opt/android-sdk
# .NET 10 android workload compiles against API level 36 (see error XA5207
# if this drifts: the workload's Xamarin.Android.Tooling.targets dictates it).
ENV ANDROID_SDK_PLATFORM=36
ENV ANDROID_SDK_BUILD_TOOLS=36.0.0
# ── Android command-line tools ────────────────────────────────────────────────
# Pin the build number to a known-good release; update when Google breaks the URL.
# Latest as of 2025: commandlinetools-linux-11076708_latest.zip (cmdline-tools 12.0)
RUN mkdir -p "${ANDROID_HOME}/cmdline-tools" && \
wget -q "https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip" \
-O /tmp/cmdtools.zip && \
unzip -q /tmp/cmdtools.zip -d "${ANDROID_HOME}/cmdline-tools" && \
mv "${ANDROID_HOME}/cmdline-tools/cmdline-tools" "${ANDROID_HOME}/cmdline-tools/latest" && \
rm /tmp/cmdtools.zip
ENV PATH="${JAVA_HOME}/bin:${ANDROID_HOME}/cmdline-tools/latest/bin:${ANDROID_HOME}/platform-tools:${PATH}"
# ── Android SDK packages ──────────────────────────────────────────────────────
RUN yes | sdkmanager --licenses > /dev/null && \
sdkmanager \
"platform-tools" \
"platforms;android-${ANDROID_SDK_PLATFORM}" \
"build-tools;${ANDROID_SDK_BUILD_TOOLS}"
# ── dotnet android workload (~1 GB, baked into this layer) ───────────────────
RUN dotnet workload install android
WORKDIR /tmp/build
docker/Dockerfile.desktop
+11
View File
@@ -0,0 +1,11 @@
FROM mcr.microsoft.com/dotnet/sdk:10.0
# clang and zlib are required by the .NET SDK for native compilation steps
# that occur even during managed cross-publish (win-x64 / linux-x64).
RUN apt-get update && apt-get install -y --no-install-recommends \
clang \
zlib1g-dev \
libkrb5-dev \
&& apt-get clean && rm -rf /var/lib/apt/lists/*
WORKDIR /tmp/build
docker/README.md
+211
View File
@@ -0,0 +1,211 @@
# PalladiumWallet — Reproducible Builds via Docker
This folder builds all three distribution targets — **Windows**, **Linux**,
**Android** — inside Docker containers. The entire toolchain (.NET 10 SDK,
JDK, Android SDK, android workload) lives in the container images, pinned in
the Dockerfiles, so:
- **anyone can produce the official binaries** with a single command, on any
Linux machine, without installing any SDK on the host;
- **the toolchain never drifts**: every build uses exactly the same SDK
versions, regardless of what is installed (or updated) on the host;
- **the build environment is auditable**: the Dockerfiles in this folder are
the complete, reviewable definition of how release binaries are made — which
matters for a wallet, where users must be able to trust that the shipped
binary comes from the published source.
> **Scope note:** this pins the *build environment*. Bit-for-bit identical
> output across machines is a stronger property that .NET does not guarantee
> by default (embedded timestamps, signing); if two builds of the same commit
> differ, they differ only in those metadata, not in code.
---
## Prerequisites
A Linux host (native, WSL2, or a VM) with **Docker Engine** installed and
running. Nothing else — no .NET SDK, no JDK, no Android SDK.
```bash
# Check that Docker works:
docker info
```
If Docker is missing, install it from <https://docs.docker.com/engine/install/>
(or `sudo apt install docker.io` on Debian/Ubuntu). If `docker info` fails
with a permission error, add yourself to the `docker` group and start a new
shell:
```bash
sudo usermod -aG docker $USER
```
**Disk space:** ~2 GB for the desktop image, ~7 GB for the Android image
(SDK + emulator-less toolchain). **First-run time:** the images are built
automatically on first use — a few minutes for desktop, 10–20 minutes for
Android (large downloads). Subsequent builds reuse the cached images and take
well under a minute (desktop) / a few minutes (Android).
**Android release signing:** before the first `android` build, generate the
persistent signing keystore once — see [`keystore/README.md`](keystore/README.md):
```bash
./docker/keystore/generate-keystore.sh
```
Without it, `build_android` refuses to run — every APK must be signed with
the same key so future releases can update a previous install in place.
---
## Quick start
```bash
# From the repository root (or from the docker/ folder — both work):
./docker/build.sh
```
Running without arguments shows an interactive menu — pick a single target or
`all`. Non-interactive usage:
```
./docker/build.sh [TARGET] [--rebuild]
Targets:
windows Win x64 single-file executable (native libs embedded)
linux Linux x64 single-file binary (runs as-is, nothing to install)
linux-arm64 Linux ARM64 single-file binary (runs as-is, nothing to install)
android Android APK (release-signed, prompts for keystore passwords)
all All targets above
Options:
--rebuild Force rebuild of the Docker images (needed after editing a Dockerfile)
```
Examples:
```bash
./docker/build.sh all # build everything
./docker/build.sh windows # Windows only
./docker/build.sh linux-arm64 # Linux ARM64 only
./docker/build.sh android --rebuild # Android, rebuilding the image first
```
---
## Output — and how to use each artifact
All artifacts land in `dist/` at the repository root. The version number is
read automatically from `<Version>` in `src/App/PalladiumWallet.App.csproj`.
| Target | Path |
|-------------|-----------------------------------------------------------|
| Windows | `dist/windows/PalladiumWallet-{ver}-win-x64.exe` |
| Linux | `dist/linux/PalladiumWallet-{ver}-linux-x64` |
| Linux ARM64 | `dist/linux-arm64/PalladiumWallet-{ver}-linux-arm64` |
| Android | `dist/android/PalladiumWallet-{ver}.apk` |
**Windows** — a single self-contained `.exe` (runtime and native libraries
embedded). Copy it to any 64-bit Windows 10/11 machine and double-click.
The first launch takes a few extra seconds (it unpacks native libraries to a
per-user cache); later launches are normal. SmartScreen may warn because the
binary is not code-signed — choose "Run anyway".
**Linux** — a single self-contained binary, already executable. Copy and run:
```bash
./PalladiumWallet-{ver}-linux-x64
```
Works on any desktop distro with glibc, X11/Wayland and fontconfig (i.e.
effectively all of them); no .NET or other packages to install. If you
transfer it through a channel that strips permissions (e.g. a web download),
restore the execute bit with `chmod +x`.
**Linux ARM64** — same as above, cross-published for `aarch64` (e.g.
Raspberry Pi 4/5, ARM-based SBCs/laptops running a 64-bit distro). The build
runs on an x64 Docker host — .NET's self-contained publish cross-targets
`linux-arm64` without needing ARM hardware. Run it the same way:
```bash
./PalladiumWallet-{ver}-linux-arm64
```
**Android** — a release-signed APK for sideloading: transfer it to the phone
and open it (enable "install from unknown sources" if prompted), or install
via `adb install dist/android/PalladiumWallet-*.apk`. Supports Android 6.0+
(API 23), arm64 phones and x86_64 emulators.
> **Signature:** every APK is signed with the persistent keystore in
> `docker/keystore/` (see [Prerequisites](#prerequisites)), so installing a
> newer build over an existing one updates it in place — no uninstall, no
> data loss. This only holds as long as every release keeps using that same
> keystore file; see `docker/keystore/README.md` for the backup story.
---
## How it works
### Docker images
| Image | Dockerfile | Used for | Size |
|---------------------|----------------------|-----------------|---------|
| `plm-build-desktop` | `Dockerfile.desktop` | windows + linux + linux-arm64 | ~1.5 GB |
| `plm-build-android` | `Dockerfile.android` | android | ~5 GB |
Images are built automatically the first time a target needs them and reused
afterwards. Use `--rebuild` only after modifying a Dockerfile.
### Source isolation
The repository is mounted **read-only** inside the container; the build works
on a copy at `/tmp/build`. Your working tree is never touched — no stray
`bin/`/`obj/` directories, and a dirty working tree doesn't leak into the
build beyond the files it contains. Artifacts are written back through a
bind mount to `dist/` and chown'd to your user.
### NuGet cache
A Docker named volume `plm-nuget-cache` holds downloaded NuGet packages
across builds. To reclaim the space or force a clean re-download:
```bash
docker volume rm plm-nuget-cache
```
---
## Troubleshooting
- **`Docker daemon is not running`** — start it (`sudo systemctl start
docker`; on WSL2, start Docker Desktop or the docker service).
- **Android image build fails downloading `commandlinetools`** — Google
rotates the build number in the URL. Update the URL in
`Dockerfile.android` to the current one from
<https://developer.android.com/studio#command-tools> and rerun with
`--rebuild`.
- **`error XA5207: Could not find android.jar for API level N`** — the .NET
android workload moved to a newer API level. Bump
`ANDROID_SDK_PLATFORM` (and `ANDROID_SDK_BUILD_TOOLS`) in
`Dockerfile.android` to the level the error names, then `--rebuild`.
- **APK won't install over an existing app
(`INSTALL_FAILED_UPDATE_INCOMPATIBLE`)** — the new build wasn't signed with
the same keystore as the installed one. Make sure `docker/keystore/release.keystore`
hasn't changed since the installed build; if it's genuinely a different key,
the user must uninstall the old app first (this deletes app data — back up
the wallet seed before doing this).
- **`build_android` refuses to run, asks to generate a keystore** — run
`./docker/keystore/generate-keystore.sh` once (see `docker/keystore/README.md`).
- **Everything is broken / start from scratch** —
`docker system prune -a && docker volume rm plm-nuget-cache`, then rerun
the script (images and packages are re-downloaded).
---
## Linux AppImage (future)
The Linux target currently produces a single-file self-contained binary.
Once a `pupnet.conf` is added to the repository, the `build_linux` function
in `build.sh` can be extended to call PupNet Deploy inside the same
`plm-build-desktop` image to also produce an AppImage with desktop
integration (icon, menu entry).
docker/build.sh
Executable
+256
View File
@@ -0,0 +1,256 @@
#!/usr/bin/env bash
# Reproducible build script for PalladiumWallet using Docker.
# Run from anywhere; paths are resolved relative to this script.
set -euo pipefail
# ── Paths ─────────────────────────────────────────────────────────────────────
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
DIST_DIR="${PROJECT_ROOT}/dist"
# ── Docker image names ────────────────────────────────────────────────────────
IMAGE_DESKTOP="plm-build-desktop"
IMAGE_ANDROID="plm-build-android"
# Named volume for NuGet package cache (shared across all builds, survives reboots).
NUGET_VOLUME="plm-nuget-cache"
# ── Helpers ───────────────────────────────────────────────────────────────────
bold() { printf '\033[1m%s\033[0m\n' "$*"; }
info() { printf '\033[1;34m>>>\033[0m %s\n' "$*"; }
ok() { printf '\033[1;32m✓\033[0m %s\n' "$*"; }
err() { printf '\033[1;31m✗\033[0m %s\n' "$*" >&2; }
die() { err "$*"; exit 1; }
usage() {
cat <<EOF
$(bold "Usage:") $(basename "$0") [TARGET] [OPTIONS]
$(bold "Targets:")
windows Win x64 single-file executable → dist/windows/
linux Linux x64 single-file binary → dist/linux/
linux-arm64 Linux ARM64 single-file binary → dist/linux-arm64/
android Android APK (release-signed) → dist/android/
all All targets above
$(bold "Options:")
--rebuild Force rebuild of Docker images (e.g. after Dockerfile change)
-h, --help Show this help
$(bold "Examples:")
$(basename "$0") # interactive menu
$(basename "$0") all # build everything
$(basename "$0") windows # Windows only
$(basename "$0") android --rebuild
EOF
}
# ── Argument parsing ──────────────────────────────────────────────────────────
REBUILD=false
TARGET=""
for arg in "$@"; do
case "$arg" in
windows|linux|linux-arm64|android|all) TARGET="$arg" ;;
--rebuild) REBUILD=true ;;
-h|--help) usage; exit 0 ;;
*) err "Unknown argument: $arg"; usage; exit 1 ;;
esac
done
# ── Interactive menu if no target given ───────────────────────────────────────
if [[ -z "$TARGET" ]]; then
bold "PalladiumWallet — reproducible build"
echo ""
PS3="Select target: "
options=("windows" "linux" "linux-arm64" "android" "all" "quit")
select opt in "${options[@]}"; do
case "$opt" in
windows|linux|linux-arm64|android|all) TARGET="$opt"; break ;;
quit) echo "Aborted."; exit 0 ;;
*) echo "Invalid choice, try again." ;;
esac
done
echo ""
fi
# ── Preflight checks ──────────────────────────────────────────────────────────
command -v docker &>/dev/null || die "Docker is not installed or not in PATH."
docker info &>/dev/null || die "Docker daemon is not running."
# ── Read project version from csproj ─────────────────────────────────────────
CSPROJ="${PROJECT_ROOT}/src/App/PalladiumWallet.App.csproj"
[[ -f "$CSPROJ" ]] || die "Cannot find $CSPROJ — run this script from the repo."
VERSION=$(grep -oP '(?<=<Version>)[^<]+' "$CSPROJ") || die "Cannot extract <Version> from $CSPROJ."
info "Version: ${VERSION}"
# ── Ensure NuGet volume exists ────────────────────────────────────────────────
docker volume inspect "$NUGET_VOLUME" &>/dev/null || \
docker volume create "$NUGET_VOLUME" > /dev/null
# ── Image builders ────────────────────────────────────────────────────────────
ensure_desktop_image() {
if [[ "$REBUILD" == true ]] || ! docker image inspect "$IMAGE_DESKTOP" &>/dev/null; then
info "Building Docker image: ${IMAGE_DESKTOP}"
docker build \
--tag "$IMAGE_DESKTOP" \
--file "${SCRIPT_DIR}/Dockerfile.desktop" \
"${SCRIPT_DIR}"
fi
}
ensure_android_image() {
if [[ "$REBUILD" == true ]] || ! docker image inspect "$IMAGE_ANDROID" &>/dev/null; then
info "Building Docker image: ${IMAGE_ANDROID}"
docker build \
--tag "$IMAGE_ANDROID" \
--file "${SCRIPT_DIR}/Dockerfile.android" \
"${SCRIPT_DIR}"
fi
}
# ── Common docker run wrapper ─────────────────────────────────────────────────
# $1 = image name, $2 = inline bash commands to execute inside the container.
# Source is copied to /tmp/build inside the container so bin/obj never pollute
# the repo. Output is written to /output (→ host DIST_DIR sub-folder).
# Optional extra `docker run` args (e.g. keystore mount, signing passwords via
# -e) can be set by the caller in the EXTRA_DOCKER_ARGS array beforehand.
EXTRA_DOCKER_ARGS=()
run_build() {
local image="$1"
local commands="$2"
local out_dir="$3"
mkdir -p "$out_dir"
docker run --rm \
--volume "${PROJECT_ROOT}:/src:ro" \
--volume "${out_dir}:/output" \
--volume "${NUGET_VOLUME}:/root/.nuget/packages" \
"${EXTRA_DOCKER_ARGS[@]}" \
"$image" \
bash -euo pipefail -c "
cp -r /src/. /tmp/build
cd /tmp/build
${commands}
chown -R $(id -u):$(id -g) /output
"
}
# ── Per-target build functions ────────────────────────────────────────────────
build_windows() {
ensure_desktop_image
info "Building Windows x64 …"
run_build "$IMAGE_DESKTOP" \
"dotnet publish src/App.Desktop \
-r win-x64 \
-c Release \
-p:PublishSingleFile=true \
-p:IncludeNativeLibrariesForSelfExtract=true \
--self-contained \
-o /tmp/win-out
cp /tmp/win-out/PalladiumWallet.exe \
\"/output/PalladiumWallet-${VERSION}-win-x64.exe\"" \
"${DIST_DIR}/windows"
ok "Windows → dist/windows/PalladiumWallet-${VERSION}-win-x64.exe"
}
build_linux() {
ensure_desktop_image
info "Building Linux x64 …"
run_build "$IMAGE_DESKTOP" \
"dotnet publish src/App.Desktop \
-r linux-x64 \
-c Release \
-p:PublishSingleFile=true \
-p:IncludeNativeLibrariesForSelfExtract=true \
--self-contained \
-o /tmp/linux-out
install -m 755 /tmp/linux-out/PalladiumWallet \
\"/output/PalladiumWallet-${VERSION}-linux-x64\"" \
"${DIST_DIR}/linux"
ok "Linux → dist/linux/PalladiumWallet-${VERSION}-linux-x64"
}
build_linux_arm64() {
ensure_desktop_image
info "Building Linux ARM64 …"
run_build "$IMAGE_DESKTOP" \
"dotnet publish src/App.Desktop \
-r linux-arm64 \
-c Release \
-p:PublishSingleFile=true \
-p:IncludeNativeLibrariesForSelfExtract=true \
--self-contained \
-o /tmp/linux-arm64-out
install -m 755 /tmp/linux-arm64-out/PalladiumWallet \
\"/output/PalladiumWallet-${VERSION}-linux-arm64\"" \
"${DIST_DIR}/linux-arm64"
ok "Linux ARM64 → dist/linux-arm64/PalladiumWallet-${VERSION}-linux-arm64"
}
build_android() {
ensure_android_image
local keystore="${SCRIPT_DIR}/keystore/release.keystore"
[[ -f "$keystore" ]] || die "No release keystore found at docker/keystore/release.keystore. Run ./docker/keystore/generate-keystore.sh once first (see docker/keystore/README.md)."
info "Building Android APK …"
read -r -s -p "Keystore password: " ANDROID_KS_PASS
echo
read -r -s -p "Key password (press Enter to reuse the keystore password): " ANDROID_KEY_PASS
echo
ANDROID_KEY_PASS="${ANDROID_KEY_PASS:-$ANDROID_KS_PASS}"
# versionCode derived from <Version> (MAJOR.MINOR.PATCH, pre-release suffix
# stripped) so it always increases with releases — required for some
# installers to accept an in-place update even when the signature matches.
local semver="${VERSION%%-*}"
IFS='.' read -r VMAJOR VMINOR VPATCH <<< "$semver"
local VERSION_CODE=$(( ${VMAJOR:-0} * 10000 + ${VMINOR:-0} * 100 + ${VPATCH:-0} ))
info "versionCode: ${VERSION_CODE}"
EXTRA_DOCKER_ARGS=(
--volume "${keystore}:/keystore/release.keystore:ro"
--env "ANDROID_KS_PASS=${ANDROID_KS_PASS}"
--env "ANDROID_KEY_PASS=${ANDROID_KEY_PASS}"
)
run_build "$IMAGE_ANDROID" \
"JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 \
dotnet build src/App.Android \
-c Release \
-t:SignAndroidPackage \
-p:AndroidSdkDirectory=\${ANDROID_HOME} \
-p:ApplicationVersion=${VERSION_CODE} \
-p:AndroidKeyStore=true \
-p:AndroidSigningKeyStore=/keystore/release.keystore \
-p:AndroidSigningKeyAlias=palladiumwallet \
-p:AndroidSigningStorePass=\${ANDROID_KS_PASS} \
-p:AndroidSigningKeyPass=\${ANDROID_KEY_PASS}
cp src/App.Android/bin/Release/net10.0-android/*-Signed.apk \
\"/output/PalladiumWallet-${VERSION}.apk\"" \
"${DIST_DIR}/android"
EXTRA_DOCKER_ARGS=()
ok "Android → dist/android/PalladiumWallet-${VERSION}.apk"
}
# ── Dispatch ──────────────────────────────────────────────────────────────────
START=$(date +%s)
case "$TARGET" in
windows) build_windows ;;
linux) build_linux ;;
linux-arm64) build_linux_arm64 ;;
android) build_android ;;
all)
build_windows
build_linux
build_linux_arm64
build_android
;;
esac
ELAPSED=$(( $(date +%s) - START ))
bold ""
bold "Done in ${ELAPSED}s. Artifacts in: ${DIST_DIR}/"
docker/keystore/README.md
+37
View File
@@ -0,0 +1,37 @@
# Android release-signing keystore
This folder holds the persistent keystore used to sign release APKs built by
`docker/build.sh android`. Every release must be signed with the **same**
key, or Android refuses to install a new build over a previously installed
one (`INSTALL_FAILED_UPDATE_INCOMPATIBLE`) and forces the user to uninstall
first — which deletes the app's data.
## First-time setup
```bash
./docker/keystore/generate-keystore.sh
```
Run this **once**, on whichever machine will keep producing release builds.
It creates `release.keystore` in this folder and asks for a keystore
password (and, optionally, a separate key password). Nothing is written to
git — `release.keystore` is ignored by `.gitignore`, and the script never
saves the passwords anywhere.
`docker/build.sh android` will refuse to run without this file, and will
prompt you for the same passwords at every build.
## Back it up
The keystore file and its passwords cannot be regenerated: if lost, no
future release can ever update existing installs in place again — every
user would need to uninstall and reinstall from scratch. Copy
`release.keystore` and the passwords to a password manager or encrypted
backup outside this repository as soon as you generate them.
## What NOT to do
- Do not commit `release.keystore` (or any `*.jks`/`*.keystore` file) to git.
- Do not re-run `generate-keystore.sh` once a keystore already exists — it
refuses on purpose; delete the file yourself only if you fully accept the
consequences above.
docker/keystore/generate-keystore.sh
Executable
+65
View File
@@ -0,0 +1,65 @@
#!/usr/bin/env bash
# Generates the persistent Android release-signing keystore used by
# docker/build.sh. Every APK built with this keystore carries the same
# signature, which is what lets Android treat a new release as an update to
# a previously installed one instead of a conflicting, different app.
#
# Run this ONCE. Re-running it after the keystore already exists is refused
# below on purpose: regenerating it changes the signature, and every device
# with a prior release installed would then need a full uninstall (and lose
# any app data that isn't in the wallet file itself) to receive the next
# update.
set -euo pipefail
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
KEYSTORE_PATH="${SCRIPT_DIR}/release.keystore"
ALIAS="palladiumwallet"
if [[ -f "$KEYSTORE_PATH" ]]; then
echo "A keystore already exists at $KEYSTORE_PATH — refusing to overwrite it." >&2
echo "Delete it manually first only if you understand the consequences above." >&2
exit 1
fi
command -v keytool &>/dev/null || {
echo "keytool not found on PATH — install a JDK (e.g. openjdk-17-jdk) and retry." >&2
exit 1
}
echo "Creating the Palladium Wallet Android release-signing keystore."
echo "This file and the passwords you enter now must be kept safe OUTSIDE this"
echo "repository (password manager, encrypted backup, ...). They are never"
echo "committed to git. Losing them means no future release can ever update"
echo "existing installs in place — only a fresh keystore + full user reinstall."
echo
read -r -s -p "Keystore password (min 6 characters): " KS_PASS
echo
read -r -s -p "Confirm keystore password: " KS_PASS_CONFIRM
echo
if [[ "$KS_PASS" != "$KS_PASS_CONFIRM" ]]; then
echo "Passwords do not match." >&2
exit 1
fi
if [[ "${#KS_PASS}" -lt 6 ]]; then
echo "Password too short (keytool requires at least 6 characters)." >&2
exit 1
fi
read -r -s -p "Key password (press Enter to reuse the keystore password): " KEY_PASS
echo
KEY_PASS="${KEY_PASS:-$KS_PASS}"
export KS_PASS KEY_PASS
keytool -genkeypair -v \
-keystore "$KEYSTORE_PATH" \
-alias "$ALIAS" \
-keyalg RSA -keysize 2048 -validity 10000 \
-storepass:env KS_PASS -keypass:env KEY_PASS \
-dname "CN=PalladiumWallet, OU=PalladiumWallet, O=PalladiumWallet, C=IT"
unset KS_PASS KEY_PASS
echo
echo "Keystore created at $KEYSTORE_PATH (git-ignored, alias: $ALIAS)."
echo "Back it up now, together with the passwords — it cannot be regenerated."
echo "./docker/build.sh android will prompt for these same passwords at build time."
docs/README.md
+11
View File
@@ -0,0 +1,11 @@
# Documentation
| Document | Purpose |
|----------|---------|
| [docs-as-code.md](docs-as-code.md) | How documentation is written, reviewed and checked |
| [adr/](adr/README.md) | Architecture Decision Records, one per feature |
Related, at the repository root: [README](../README.md), [USERGUIDE](../USERGUIDE.md),
[SECURITY](../SECURITY.md), [CHANGELOG](../CHANGELOG.md).
Check the docs before committing: `./docs/check-docs.sh`
docs/adr/0001-record-architecture-decisions.md
+25
View File
@@ -0,0 +1,25 @@
# 0001. Record architecture decisions as ADRs
- **Status:** Accepted
- **Area:** Process
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Design choices in this wallet (SPV trust model, key handling, storage format) have direct financial impact and are easy to forget or to undo by accident. The reasoning currently lives in code comments, `SECURITY.md` and `CHANGELOG.md`, which record *what* but rarely *why one option was chosen over another*.
## Decision
Keep one Architecture Decision Record per feature in `docs/adr/`, in Markdown, versioned with the code and reviewed in the same pull request as the change they describe. Format and workflow are defined in `docs/docs-as-code.md` and `docs/adr/template.md`. An accepted ADR is never rewritten: a changed decision gets a new ADR that supersedes the old one.
## Consequences
- The rationale survives contributor turnover and is reviewable like code.
- Decisions recorded retroactively (0002 onwards) reconstruct intent from code, comments and the changelog; they are marked as such and should be corrected if the original author remembers differently.
- Small overhead per feature: an ADR is expected when a decision is hard to reverse or touches cryptography, SPV validation, key handling or the file format.
## References
- `docs/docs-as-code.md`
- `docs/adr/template.md`
- `docs/check-docs.sh`
docs/adr/0002-shared-avalonia-ui-with-platform-heads.md
+25
View File
@@ -0,0 +1,25 @@
# 0002. One shared Avalonia UI with thin platform heads
- **Status:** Accepted
- **Area:** Architecture
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The wallet targets Windows, Linux and Android. Maintaining separate UIs would triple the surface to test and make behaviour drift between platforms.
## Decision
Write the UI once in the library `src/App` (Avalonia UI 12, .NET 10). `MainView` (a `UserControl`) is the shared root: hosted by `MainWindow` on desktop and used as the single-view root on Android. The heads `src/App.Desktop` (WinExe) and `src/App.Android` carry only the entry point and platform packages. Top-level services (file picker, clipboard) are reached through `TopLevel.GetTopLevel(this)`; platform differences are gated by `MainWindowViewModel.IsDesktop`.
## Consequences
- One code path for UI logic and one localization table.
- UI must stay mobile-friendly (no OS windows, see 0021) and avoid desktop-only APIs outside `IsDesktop` guards.
- Android needs its own workload, SDK and signing flow (0028, 0029).
## References
- `src/App/Views/MainView.axaml`
- `src/App.Desktop`
- `src/App.Android`
docs/adr/0003-core-without-ui-dependency.md
+24
View File
@@ -0,0 +1,24 @@
# 0003. Layered architecture: Core knows nothing about the UI
- **Status:** Accepted
- **Area:** Architecture
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The same wallet logic must be driven by a GUI, a CLI and headless tests. If cryptography or network code leaked into view code it could not be tested without a display and could not be audited in isolation.
## Decision
Layers depend only downward: GUI → wallet domain → SPV/sync → network → cryptography → persistence. `src/Core` (`Chain/ Crypto/ Wallet/ Spv/ Net/ Storage/`) has no UI dependency. `src/App` and `src/Cli` depend only on `Core`; the UI reaches the network and cryptography exclusively through the wallet domain.
## Consequences
- `dotnet test` covers almost all behaviour headlessly.
- The CLI is a second front end for free (0024).
- Violations (e.g. a ViewModel opening a socket) are review blockers, not style issues.
## References
- `src/Core`
- `src/Cli/Program.cs`
docs/adr/0004-centralized-network-profile.md
+25
View File
@@ -0,0 +1,25 @@
# 0004. Centralize all chain constants in a network profile
- **Status:** Accepted
- **Area:** Chain
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Palladium is a Bitcoin-derived chain with its own address prefixes, BIP32 headers, bech32 HRP, genesis, ports and coin type, and it runs on mainnet, testnet and regtest. Scattered magic numbers make a wrong-network address or key a silent fund-safety bug.
## Decision
Define every chain constant once in `Core/Chain` (`ChainProfile`, `ChainProfiles`, `PalladiumNetworks`): address prefixes (P2PKH 55, P2SH 5), bech32 HRP `plm`, SLIP-132 headers, genesis hash, default ports (50001/50002), BIP44 coin type 746, maturity and confirmation policy, bootstrap servers and checkpoints. The profile is selected per network and passed into the code that needs it.
## Consequences
- A new network or parameter change is a one-file edit.
- Testnet and regtest ship with empty bootstrap-server and checkpoint lists (TODO in code), so they rely on a user-supplied server and have no checkpoint anchoring (see 0006).
- Mainnet currently reuses Bitcoin's genesis hash, as noted in the profile.
## References
- `src/Core/Chain/ChainProfile.cs`
- `src/Core/Chain/ChainProfiles.cs`
- `src/Core/Chain/PalladiumNetworks.cs`
docs/adr/0005-nbitcoin-for-protocol-primitives.md
+24
View File
@@ -0,0 +1,24 @@
# 0005. Use NBitcoin for protocol primitives, hand-write only the rest
- **Status:** Accepted
- **Area:** Crypto
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Reimplementing BIP32/39, address encoding, transaction serialization, signing or PSBT is a classic source of subtle, fund-losing bugs.
## Decision
Build on NBitcoin for the custom network definition, BIP32/39, addresses, transactions, PSBT, signing, encoding and hashing. Hand-written code is limited to what NBitcoin does not provide for this chain: the Electrum JSON-RPC client (0009), SPV sync with Merkle verification and checkpoint anchoring (0006, 0007), coin selection and fee policy (0017), SLIP-132 variants beyond xpub/xprv (0014) and the encrypted wallet container (0012).
## Consequences
- Smaller audited surface; cross-implementation golden vectors catch divergence.
- NBitcoin assumes Bitcoin retargeting, which is why PoW validation is skipped (0006).
- A dependency upgrade can change behaviour; golden-vector tests must pass before bumping.
## References
- `src/Core/Chain/PalladiumNetworks.cs`
- `src/Core/Crypto/Slip132.cs`
docs/adr/0006-spv-checkpoint-anchoring-without-pow.md
+27
View File
@@ -0,0 +1,27 @@
# 0006. Anchor headers to hardcoded checkpoints and skip PoW validation
- **Status:** Accepted (the anchoring direction is superseded by [0040](0040-anchor-headers-up-to-a-checkpoint.md))
- **Area:** SPV
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Palladium uses LWMA difficulty with 2-minute blocks. An SPV client cannot recompute LWMA without the full header history, and NBitcoin assumes Bitcoin's retargeting rules, so checking proof of work client-side would either be wrong or require downloading every header.
## Decision
Set `SkipPowValidation = true` in the profile and anchor trust to hardcoded checkpoints instead. For each header used in a Merkle proof, `WalletSynchronizer.AnchorToCheckpointAsync` downloads the intervening headers, verifies the prev-hash chain back to the nearest checkpoint at or below that height, and requires that checkpoint's hash to match exactly. Mainnet carries a checkpoint every 20,000 blocks.
## Consequences
- A server cannot feed an alternative history below the newest checkpoint.
- Headers above the newest checkpoint are linked but their work is not verified; this is an accepted limitation documented in `SECURITY.md`.
- Testnet/regtest have no checkpoints, so headers there are trusted at face value.
- Checkpoints must be extended with releases; a wrong checkpoint would reject every honest server.
## References
- `src/Core/Spv/WalletSynchronizer.cs`
- `src/Core/Spv/BlockHeaderInfo.cs`
- `src/Core/Chain/ChainProfiles.cs`
- `SECURITY.md`
docs/adr/0007-mandatory-merkle-verification.md
+25
View File
@@ -0,0 +1,25 @@
# 0007. Verify a Merkle proof for every confirmed transaction
- **Status:** Accepted
- **Area:** SPV
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The indexing server is semi-trusted: it can lie about history. Without proof of inclusion it could fabricate a confirmed payment.
## Decision
Every confirmed transaction must come with a Merkle branch that `MerkleProof.Verify` checks against the merkle root of an anchored header (0006). The txid, position and branch are taken from the server, the root only from a verified header. A mismatch fails the sync with `SpvVerificationException`; unconfirmed transactions are shown as such and are never spendable.
## Consequences
- A malicious server cannot fabricate a confirmed transaction with a valid proof.
- Cost: one proof request per confirmed transaction, mitigated by caching verified state (0013) and progressive verification (0008).
- Script execution and double-spend detection are not covered; see `SECURITY.md`.
## References
- `src/Core/Spv/MerkleProof.cs`
- `src/Core/Spv/WalletSynchronizer.cs`
- `SECURITY.md`
docs/adr/0008-progressive-verification-sync.md
+25
View File
@@ -0,0 +1,25 @@
# 0008. Progressive verification: show early, spend only after proof
- **Status:** Accepted
- **Area:** SPV
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
On wallets with thousands of historical transactions, blocking the whole sync on every Merkle proof made the app unusable, especially on mobile hardware.
## Decision
`WalletSynchronizer` raises `PartialResult` as soon as transaction downloads finish, then keeps verifying proofs in the background and refreshes the result periodically. Each cached transaction and UTXO carries a `Verified` flag. The UI marks unverified entries ("verifying…") and shows `PendingVerificationSats` separately. The invariant: `UtxoSpendability.IsSpendable` requires `Verified`, so unverified coins can be displayed but never spent. `SyncOnceAsync` still completes only when verification is finished, and the disk cache stores only the fully verified end state.
## Consequences
- Fast time-to-usable-balance.
- A forged balance can be displayed briefly but never spent before the proof failure aborts the sync.
- Balances have overlapping subsets (immature vs. pending verification); consumers must use `SpendableSats`, never subtract the subsets.
## References
- `src/Core/Spv/WalletSynchronizer.cs`
- `src/Core/Wallet/UtxoSpendability.cs`
- `SECURITY.md`
docs/adr/0009-custom-electrum-client.md
+24
View File
@@ -0,0 +1,24 @@
# 0009. Hand-written Electrum JSON-RPC client with pipelining and an in-flight cap
- **Status:** Accepted
- **Area:** Network
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The wallet talks to an ElectrumX/Fulcrum-style indexing server (ports 50001/50002, not the node's P2P port 2333). No library matched the needs: protocol 1.4, a testable in-process transport and control over throughput on large wallets.
## Decision
Implement `ElectrumClient` directly over `TcpClient`/`SslStream`, newline-delimited JSON-RPC 2.0. A single-reader channel batches writes (like Electrum's buffered writer); a read loop completes pending requests by id; a semaphore caps in-flight requests (`DefaultMaxInFlight = 32`, configurable per connection) to avoid server throttling and disconnects. Typed helpers live in `ElectrumApi`. The class is deliberately not an interface: tests run against a real in-process server instead (0025).
## Consequences
- Full control over request pipelining and error mapping (`ElectrumServerException`).
- No single in-flight value suits every server, hence the per-connection knob.
- Protocol quirks (e.g. `server.version` allowed once per connection) are our responsibility; the server probe (0027) exists to catch server differences.
## References
- `src/Core/Net/ElectrumClient.cs`
- `src/Core/Net/ElectrumApi.cs`
docs/adr/0010-tls-tofu-certificate-pinning.md
+24
View File
@@ -0,0 +1,24 @@
# 0010. TOFU certificate pinning for indexing servers
- **Status:** Accepted
- **Area:** Network
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Indexing servers commonly use self-signed certificates, so CA validation is not available, yet silent MITM substitution must still be detectable.
## Decision
Trust On First Use: the certificate fingerprint is pinned on first successful TLS connection (`CertificatePinStore`, persisted per network in `server-certs.json`). A later mismatch raises `CertificatePinMismatchException` and blocks the connection until the user explicitly resets the pin (GUI, or CLI `reset-certs`). A corrupted pin file must not permanently block reconnection.
## Consequences
- Detects certificate substitution after first contact.
- Does not protect the first connection; users cannot distinguish a legitimate rotation from an attack, so the reset is deliberately manual.
- Reflects `SECURITY.md`; any change to the pinning policy must update it in the same commit.
## References
- `src/Core/Net/CertificatePinStore.cs`
- `SECURITY.md`
docs/adr/0011-server-registry-and-discovery.md
+24
View File
@@ -0,0 +1,24 @@
# 0011. Server registry seeded by bootstrap list and peer discovery
- **Status:** Accepted
- **Area:** Network
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The wallet needs a server without hardcoding a single point of failure, and users should be able to pick their own.
## Decision
`ServerRegistry` starts from the profile's bootstrap servers, adds peers announced via `server.peers.subscribe` (missing ports fall back to profile defaults) and persists the list per network. The first entry is the default when the user specifies none. The last successfully connected server is stored in `AppConfig`.
## Consequences
- Works out of the box and survives bootstrap servers disappearing.
- There is no multi-server pooling or cross-checking yet (listed as a limitation in `SECURITY.md`).
- Discovered peers are unauthenticated hints; every response is still verified (0007).
## References
- `src/Core/Net/ServerRegistry.cs`
- `src/Core/Storage/AppConfig.cs`
docs/adr/0012-encrypted-wallet-file.md
+26
View File
@@ -0,0 +1,26 @@
# 0012. Wallet file encrypted with AES-256-GCM and PBKDF2-HMAC-SHA512
- **Status:** Accepted
- **Area:** Storage
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The wallet file contains the seed and keys; theft of the file must not mean theft of funds.
## Decision
`EncryptedFile` wraps the whole wallet document in a self-describing JSON container (`plm-wallet-aesgcm-v1`: kdf, iterations, salt, nonce, ciphertext, tag). AES-256-GCM, key from PBKDF2-HMAC-SHA512 with 600,000 iterations, a fresh 16-byte salt and 12-byte nonce on every save. The iteration count is stored in the file, so it can be raised later, and is capped at 10,000,000 on read because it is attacker-controlled. A wrong password or tampering raises `WrongPasswordException`; any malformed container raises `InvalidDataException`, never a raw parser error. Writes are atomic (temp file + rename).
## Consequences
- Tampering is detected before decryption; parameter upgrades stay backward compatible.
- The GCM tag cannot tell a wrong password from a corrupted file.
- Users may opt out of encryption (`Save` with a null password), only with an explicit UI warning.
- Changes to parameters or format must update `SECURITY.md` in the same commit.
## References
- `src/Core/Storage/EncryptedFile.cs`
- `src/Core/Storage/WalletStore.cs`
- `SECURITY.md`
docs/adr/0013-versioned-wallet-document-and-sync-cache.md
+24
View File
@@ -0,0 +1,24 @@
# 0013. Versioned JSON wallet document with an offline sync cache
- **Status:** Accepted
- **Area:** Storage
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Wallet metadata (labels, contacts, gap limit) and the last synced state must persist across sessions and across app upgrades; balances should be viewable offline.
## Decision
`WalletDocument` is a versioned JSON schema (`CurrentVersion = 1`) with a migration hook on open. It holds the seed or keys (so it must be encrypted, 0012), account xpub and path, labels, contacts, gap limit (default 20) and a `SyncCache` with balance/history. Only confirmed transactions are cached because unconfirmed ones can change (RBF); only the fully verified end state of a sync is persisted (0008).
## Consequences
- Reopening a wallet is fast and works offline.
- Schema changes require a version bump and a migration, tested before release.
- A large cache makes saves heavy, so `WalletStore.SaveAsync` moves serialization and I/O off the UI thread.
## References
- `src/Core/Storage/WalletDocument.cs`
- `src/Core/Storage/WalletStore.cs`
docs/adr/0014-hd-derivation-and-slip132.md
+25
View File
@@ -0,0 +1,25 @@
# 0014. BIP32/39 HD wallets with BIP44/49/84 paths and SLIP-132 keys
- **Status:** Accepted
- **Area:** Crypto
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Users expect seed compatibility with other wallets and a choice of address format.
## Decision
Derive accounts with BIP39 + BIP32 using purposes 44 (legacy P2PKH), 49 (wrapped P2SH-P2WPKH) and 84 (native P2WPKH), coin type 746 from the profile (`DerivationPaths`). Extended keys are encoded and parsed as SLIP-132 (xpub/ypub/zpub families) with headers from the profile (`Slip132`), since NBitcoin only registers xprv/xpub. An optional BIP39 passphrase is supported. Native SegWit is the default kind.
## Consequences
- Restore from seed or xpub/xprv reproduces the same addresses; golden vectors compare against a reference wallet.
- Taproot (BIP86) and multisig (BIP48) constants exist, but derivation for them is not implemented (see 0031).
## References
- `src/Core/Crypto/DerivationPaths.cs`
- `src/Core/Crypto/Slip132.cs`
- `src/Core/Crypto/HdAccount.cs`
- `src/Core/Crypto/Bip39.cs`
docs/adr/0015-imported-keys-and-watch-only-accounts.md
+25
View File
@@ -0,0 +1,25 @@
# 0015. Imported-key and watch-only accounts
- **Status:** Accepted
- **Area:** Wallet
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Users need to import WIF keys, track an xpub, or watch plain addresses without exposing key material.
## Decision
`IWalletAccount` abstracts HD and imported accounts. `ImportedKeyAccount` holds a fixed address list (no HD derivation; change returns to the first imported address). Watch-only accounts (from xpub, or from addresses with no keys) report no private key, and `TransactionFactory` only signs when the account has one, so they can only ever produce an unsigned PSBT.
## Consequences
- Watch-only is structurally read-only, not just disabled in the UI.
- Imported-key wallets reuse addresses for change, a privacy trade-off.
- Pure address imports derive the script kind only informationally.
## References
- `src/Core/Crypto/IWalletAccount.cs`
- `src/Core/Crypto/ImportedKeyAccount.cs`
- `src/Core/Wallet/WalletLoader.cs`
docs/adr/0016-psbt-centric-signing.md
+23
View File
@@ -0,0 +1,23 @@
# 0016. Route every signing flow through PSBT
- **Status:** Accepted
- **Area:** Wallet
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Offline, air-gapped and hardware-assisted signing all need a transport format, and a wallet that signs through a different path for each case multiplies the code that handles keys.
## Decision
`TransactionFactory.Build` produces a `BuiltTransaction` that always carries a PSBT. Accounts that hold keys also return the signed transaction; watch-only accounts return the unsigned PSBT for export and offline signing.
## Consequences
- One build path, interoperable with other PSBT tools.
- Hardware-wallet and multisig integration (not in v1) can reuse the same format.
- Cross-implementation tests compare PSBTs to a reference wallet; a differing PSBT or txid is a blocking bug.
## References
- `src/Core/Wallet/TransactionFactory.cs`
docs/adr/0017-coin-selection-fee-and-spendability-policy.md
+24
View File
@@ -0,0 +1,24 @@
# 0017. Coin selection, fee and confirmation policy
- **Status:** Accepted
- **Area:** Wallet
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Fund safety depends on never spending immature or unverified coins and on producing standard, relayable transactions.
## Decision
`TransactionFactory` supports automatic or manual UTXO selection, a fixed fee rate in sat/vByte, send-all with the fee subtracted, change on the internal chain, and RBF enabled on every transaction. It rejects transactions above 100,000 vbytes. `UtxoSpendability.IsSpendable` is the single gate shared by coin selection and balance reporting: a coinbase output needs maturity + 1 confirmations (121 on mainnet), a regular output needs `MinConfirmations` (policy, not consensus), frozen UTXOs are excluded, and the Merkle proof must be verified (0008).
## Consequences
- Balances and coin selection cannot disagree.
- Users may see "insufficient funds" despite a larger visible balance when part of it is immature or unverified.
- RBF is set but fee bumping is not exposed in the UI (see `SECURITY.md`).
## References
- `src/Core/Wallet/TransactionFactory.cs`
- `src/Core/Wallet/UtxoSpendability.cs`
docs/adr/0018-exclusive-wallet-file-lock.md
+22
View File
@@ -0,0 +1,22 @@
# 0018. Exclusive OS-level lock on the open wallet file
- **Status:** Accepted
- **Area:** Storage
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Two processes opening the same wallet could overwrite each other's saves and corrupt state.
## Decision
`WalletLock.TryAcquire` holds a `FileStream` opened with `FileShare.None` on a companion `.lock` file for the session. The OS releases it on exit or crash, so there are no stale locks to clean up. A second opener gets `null`; permission errors propagate so the UI can show a distinct message.
## Consequences
- Safe multi-instance behaviour without lock-file housekeeping.
- Protects against concurrent app instances only, not against external tools editing the file.
## References
- `src/Core/Storage/WalletLock.cs`
docs/adr/0019-data-location-resolution.md
+23
View File
@@ -0,0 +1,23 @@
# 0019. Resolve the data root by explicit precedence
- **Status:** Accepted
- **Area:** Storage
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Desktop users want portable installs or a custom folder; Android must use its sandbox; existing installs must keep their data.
## Decision
`AppPaths.DataRoot()` resolves in order: `OverrideDataRoot` (set by the Android head to the app sandbox, or by tests), portable `palladium-data` folder next to the executable, user-chosen folder stored in a pointer file at a fixed bootstrap location, legacy location if it already holds data, then the platform default (`%APPDATA%\PalladiumWallet` on Windows, `~/.palladium-wallet` on Linux). Each network gets its own subfolder (config, wallets, certificates, servers).
## Consequences
- First-run wizard asks for a location only when none is determined; Android skips that step.
- Static override seams complicate tests, which therefore share the xUnit collection `AppPaths`.
## References
- `src/Core/Storage/AppPaths.cs`
- `src/App.Android`
docs/adr/0020-single-viewmodel-with-feature-partials.md
+25
View File
@@ -0,0 +1,25 @@
# 0020. A single ViewModel split into partial classes by feature
- **Status:** Accepted
- **Area:** UI
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The UI is one `MainView` with many overlays sharing wallet, sync and connection state; many small ViewModels would need heavy cross-wiring.
## Decision
Use one `MainWindowViewModel` (CommunityToolkit.Mvvm: `[ObservableProperty]`, `[RelayCommand]`) that drives `Core` directly, split into partial classes by feature (`.Send`, `.Receive`, `.Sync`, `.Settings`, `.Wizard`, `.Contacts`, `.Update`, `.WalletInfo`, `.Donate`). New feature logic goes into the matching partial or a new one.
## Consequences
- Shared state needs no messaging layer.
- The class is large; discipline on partial boundaries is what keeps it navigable.
- Heavy network work must run off the UI thread (`Task.Run`).
## References
- `src/App/ViewModels/MainWindowViewModel.cs`
- `src/App/ViewModels/MainWindowViewModel.Send.cs`
- `src/App/ViewModels/MainWindowViewModel.Sync.cs`
docs/adr/0021-in-app-overlays-instead-of-windows.md
+23
View File
@@ -0,0 +1,23 @@
# 0021. In-app overlays instead of OS windows
- **Status:** Accepted
- **Area:** UI
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Secondary windows and popups are slow on WSLg and do not exist on Android's single-view root.
## Decision
Details (address, transaction), settings and help are full-screen `Border`s gated by an `IsXxxOpen` flag, with Open/Close commands, a backdrop handler and an Esc handler in `MainView`'s code-behind. Close buttons bind via `$parent[UserControl]`, not `$parent[Window]`.
## Consequences
- Instant open/close and identical behaviour on desktop and Android.
- Overlay state lives in the ViewModel and must be closed on navigation.
## References
- `src/App/Views/MainView.axaml`
- `src/App/Views/MainView.axaml.cs`
docs/adr/0022-localization-seven-languages.md
+23
View File
@@ -0,0 +1,23 @@
# 0022. In-code localization table for seven languages
- **Status:** Accepted
- **Area:** UI
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The wallet targets users across several markets and must work offline, with the strings available identically on every platform.
## Decision
`Loc` holds a key → 7-language table (it, en, es, fr, pt, de, zh). XAML uses `{Binding Loc[key]}`, C# uses `Loc.Tr("key")`. On language change the `Loc` instance is replaced so bindings refresh. An unknown language falls back to English. The picker in the Settings overlay is a hand-written list of `RadioButton`s bound to `IsLangXx` properties, so a new language needs a column, a button and a property.
## Consequences
- No resource-file tooling and no runtime lookup failures.
- Adding a language touches three places; forgetting the picker leaves it unreachable.
## References
- `src/App/Localization/Loc.cs`
- `src/App/ViewModels/MainWindowViewModel.Settings.cs`
docs/adr/0023-github-release-update-check.md
+25
View File
@@ -0,0 +1,25 @@
# 0023. Best-effort update check against GitHub releases
- **Status:** Accepted
- **Area:** Distribution
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Android builds are signed sideloads and desktop builds are single-file executables, so there is no store to notify users of fixes.
## Decision
`UpdateChecker.CheckAsync` compares the running version (single source: `<Version>` in the App csproj) with the latest GitHub release tag at startup. Any network or parse failure, or an up-to-date app, resolves to null; the UI prompts only when a newer release exists. The HTTP handler is injectable so tests never reach GitHub.
## Consequences
- Users learn about security fixes promptly; no telemetry is sent beyond the release API request.
- The check leaks to GitHub that a wallet started; this is not covered by a Tor/proxy option.
- The repository URL is hardcoded in the source and must be kept in sync if the project moves.
## References
- `src/Core/Net/UpdateChecker.cs`
- `src/App/ViewModels/MainWindowViewModel.Update.cs`
- `tests/PalladiumWallet.Tests/Net/UpdateCheckerTests.cs`
docs/adr/0024-cli-on-shared-core.md
+22
View File
@@ -0,0 +1,22 @@
# 0024. A CLI front end on the same Core
- **Status:** Accepted
- **Area:** Distribution
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Scripting, headless servers and quick manual verification need the wallet without a GUI.
## Decision
`src/Cli` exposes `create`, `restore`, `restore-xpub`, `restore-address`, `info`, `sync`, `send`, `servers`, `reset-certs`, `newseed` and `addresses` on the same `Core` as the GUI, with `--net`, `--file`, `--server host:port` and `--ssl` options. The default wallet file is `~/.palladium-wallet/<network>/wallets/default.wallet.json`.
## Consequences
- Core behaviour is exercised outside the GUI.
- Passwords on the command line are visible to other local users and shell history; the CLI is a developer tool, not a hardened interface.
## References
- `src/Cli/Program.cs`
docs/adr/0025-in-process-fake-electrum-server-for-tests.md
+23
View File
@@ -0,0 +1,23 @@
# 0025. Test the network layer against an in-process fake server
- **Status:** Accepted
- **Area:** Testing
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
SPV code must be proven to reject lying servers, which cannot be done reliably against real servers, and mocks of `ElectrumClient` would hide transport bugs.
## Decision
`tests/PalladiumWallet.Tests/Net/FakeElectrumServer.cs` is a loopback TCP server with optional TLS, per-method handlers and call counters. Tests program it to return wrong Merkle proofs, drop connections or throttle, and assert that `ElectrumClient`, `WalletSynchronizer`, `TransactionInspector` and certificate pinning react correctly. The client is not made an interface on purpose.
## Consequences
- Real sockets, real serialization, deterministic adversarial scenarios.
- New protocol behaviour means extending the fake, not mocking.
## References
- `tests/PalladiumWallet.Tests/Net/FakeElectrumServer.cs`
- `tests/PalladiumWallet.Tests/Net/ElectrumClientTests.cs`
docs/adr/0026-fuzzing-untrusted-input-parsers.md
+24
View File
@@ -0,0 +1,24 @@
# 0026. Fuzz every untrusted-input parser
- **Status:** Accepted
- **Area:** Testing
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Headers, Merkle branches, extended keys, mnemonics, addresses, amounts, wallet documents, encrypted files and peer lists all arrive from outside the trust boundary. A crash or unexpected exception there is a bug or a denial of service.
## Decision
`tests/PalladiumWallet.Fuzz` (SharpFuzz) has one target per parser (`header merkle slip132 bip39 address coinamount walletdoc encfile peers`), each encoding that parser's error contract: any other escaping exception is a finding. The seed corpus, including regression inputs for past findings, replays inside `dotnet test` through `FuzzCorpusTests`. Property-based tests (CsCheck) complement it for roundtrip invariants.
## Consequences
- Past findings (corrupted pin file, JSON wallet detection) became permanent regression inputs.
- A new parser requires a new fuzz target and seed entries.
- Coverage-guided campaigns need afl++, so they are manual rather than part of the default test run.
## References
- `tests/PalladiumWallet.Fuzz/Program.cs`
- `tests/PalladiumWallet.Fuzz/fuzz.sh`
docs/adr/0027-server-probe-and-live-server-test.md
+24
View File
@@ -0,0 +1,24 @@
# 0027. Server probe tool and opt-in live-server test
- **Status:** Accepted
- **Area:** Testing
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Servers differ (Fulcrum, ElectrumX, electrs), can be on the wrong chain, lag behind or serve invalid proofs. The fake server cannot reveal how a real deployment behaves.
## Decision
`tests/PalladiumWallet.ServerProbe` is a read-only CLI that runs black-box checks against real servers through the wallet's own `ElectrumClient`: handshake and TLS fingerprint, `server.features` (genesis and `sha256`), tip freshness, genesis header, header linkage, a Merkle proof of a recent coinbase against the header root, fees, peers, error handling, latency and a pipelined burst, plus a cross-server tip comparison. `LiveServerTests` runs it from `dotnet test` only when `PALLADIUM_TEST_SERVERS` is set, so the default run stays offline.
## Consequences
- Operators and developers can qualify a server before using it.
- The live test depends on third-party availability and is therefore opt-in.
- The probe reuses production client code, so a pass means the wallet can use the server.
## References
- `tests/PalladiumWallet.ServerProbe/Program.cs`
- `tests/PalladiumWallet.Tests/Net/LiveServerTests.cs`
docs/adr/0028-reproducible-docker-release-builds.md
+26
View File
@@ -0,0 +1,26 @@
# 0028. Reproducible release builds inside pinned Docker images
- **Status:** Accepted
- **Area:** Distribution
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Users of a wallet must be able to trust that a shipped binary comes from the published source, and builds must not drift with whatever SDK a developer has installed.
## Decision
`docker/build.sh [windows|linux|android|all]` builds each target in a container whose toolchain (.NET SDK, JDK, Android SDK and workload) is pinned in `docker/Dockerfile.*`; artifacts land in `dist/`. The desktop single-file publish needs `IncludeNativeLibrariesForSelfExtract=true`, otherwise Avalonia's native libraries stay outside the executable and it silently fails to start.
## Consequences
- The Dockerfiles are the auditable definition of how releases are made.
- This pins the environment; bit-for-bit identical output is not guaranteed by .NET (timestamps, signing).
- The Android workload dictates the SDK API level (error XA5207 means bump `ANDROID_SDK_PLATFORM`).
## References
- `docker/build.sh`
- `docker/Dockerfile.desktop`
- `docker/Dockerfile.android`
- `docker/README.md`
docs/adr/0029-persistent-android-signing-keystore.md
+24
View File
@@ -0,0 +1,24 @@
# 0029. Persistent Android release keystore kept out of git
- **Status:** Accepted
- **Area:** Distribution
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Android refuses to update an installed app signed with a different key, and the user would have to uninstall, which deletes the wallet data.
## Decision
Release APKs are signed with one persistent keystore generated once by `docker/keystore/generate-keystore.sh`. `release.keystore` is ignored by git; passwords are supplied through environment variables or prompts at each build and are never stored. `docker/build.sh android` refuses to run without the keystore.
## Consequences
- In-place updates keep working across releases.
- Losing the keystore or its passwords permanently breaks in-place updates; it must be backed up outside the repository.
## References
- `docker/keystore/generate-keystore.sh`
- `docker/keystore/README.md`
- `.gitignore`
docs/adr/0030-single-source-versioning-and-changelog.md
+24
View File
@@ -0,0 +1,24 @@
# 0030. Single-source versioning with a mandatory changelog entry
- **Status:** Accepted
- **Area:** Distribution
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
The App version, Android's display version and Android's `versionCode` must stay consistent, and `versionCode` must strictly increase or users cannot update in place.
## Decision
`<Version>` in `src/App/PalladiumWallet.App.csproj` is the only source. `update-version.sh` updates it, mirrors `ApplicationDisplayVersion` in the Android head, increments `ApplicationVersion` and stubs a `CHANGELOG.md` entry. The changelog entry is filled in before or with the tag; commit and tag are manual.
## Consequences
- The title bar, update checker (0023) and release builds read the same value.
- The changelog is the technical record of what shipped, not optional bookkeeping.
## References
- `update-version.sh`
- `CHANGELOG.md`
- `src/App/PalladiumWallet.App.csproj`
docs/adr/0031-defer-multisig-lightning-and-hardware-wallets.md
+24
View File
@@ -0,0 +1,24 @@
# 0031. Explicitly defer multisig, Lightning, Tor and hardware wallets
- **Status:** Accepted
- **Area:** Scope
- **Recorded:** 2026-11-03 (retroactive: reconstructed from code, comments and changelog)
## Context
Each of these adds large attack surface or UX complexity. Shipping a half-working version in a wallet is worse than not shipping it.
## Decision
The first release excludes Lightning, M-of-N multisig, hardware-wallet integration, Tor/proxy support, multi-server pooling and RBF/CPFP fee-bumping UI. Where the profile already defines the constants (multisig SLIP-132 headers, BIP48/BIP86 purposes), the unimplemented paths throw rather than silently producing an incorrect wallet. Coin control exists in `TransactionFactory` (manual UTXO selection) and freezing in the cache; `SECURITY.md` lists the limitations users must know.
## Consequences
- A smaller, auditable v1.
- Network traffic reveals which addresses are queried (no Tor); this is stated in the threat model.
- Each deferred feature needs its own ADR when taken up.
## References
- `SECURITY.md`
- `src/Core/Crypto/DerivationPaths.cs`
docs/adr/0032-github-actions-ci.md
+34
View File
@@ -0,0 +1,34 @@
# 0032. Run tests, fuzz smoke and docs checks in GitHub Actions
- **Status:** Accepted
- **Area:** Testing
- **Recorded:** 2026-11-03
## Context
The suite (unit, property-based, fuzz-corpus replay, in-process fake-server tests) is the primary verification layer for a wallet where a regression can lose funds, but it only ran on a developer's machine. Nothing prevented a failing change, a broken docs index or a Windows-only break from reaching `main`.
## Decision
`.github/workflows/ci.yml` runs on every push to `main` and on every pull request, with read-only permissions and cancellation of superseded runs:
- **test**: restore, build (Release) and `dotnet test` of `tests/PalladiumWallet.Tests` on `ubuntu-latest` and `windows-latest`, uploading the TRX and coverage results as artifacts. Only the test project and its references are built, because the Android head needs a workload and SDK that CI does not provision.
- **fuzz-smoke**: one job per parser target, running `--random 20000` mutations; any escaping exception fails the job.
- **docs**: `docs/check-docs.sh`.
- A **coverage gate** on the Ubuntu test job fails the run if `Core` drops below the thresholds in the workflow (see 0033).
The pipeline is offline: `LiveServerTests` does nothing without `PALLADIUM_TEST_SERVERS`, so no third-party indexing server is contacted. Coverage-guided fuzzing (afl++) and release builds stay manual.
## Consequences
- A change that breaks tests on either OS, a fuzz contract or the docs checks is visible before merge.
- Release, Android and Docker builds are not exercised by CI yet.
- Action versions are pinned to major tags; moving to commit SHAs would harden the supply chain further.
- Runs consume hosted-runner minutes; the fuzz matrix is the cheapest place to cut if needed.
## References
- `.github/workflows/ci.yml`
- `docs/check-docs.sh`
- `tests/PalladiumWallet.Fuzz/Program.cs`
- Related: 0025, 0026, 0027, 0033
docs/adr/0033-test-strategy-beyond-core.md
+34
View File
@@ -0,0 +1,34 @@
# 0033. Test the UI layer and CLI headlessly and gate coverage
- **Status:** Accepted
- **Area:** Testing
- **Recorded:** 2026-11-03
## Context
`Core` was covered at about 99% of lines, but `App` (ViewModels, localization) and `Cli` had no tests at all, although they hold logic that moves funds and handles secrets: the send flow, password and lock handling, seed and private-key reveal, the wizard. Nothing stopped coverage from silently dropping.
## Decision
- **ViewModels** are tested headlessly with `Avalonia.Headless` (no window, no GPU). The helper package `Avalonia.Headless.XUnit` is not used because it requires xunit v3 and the suite is on xunit 2; `UiSession` runs each test body on a shared headless session instead. Tests are sandboxed: the data root is a temp folder, the saved server points at the in-process `FakeElectrumServer`, and two internal seams keep them offline: `MainWindowViewModel.UpdateCheck` (stubs the GitHub check) and `MainWindowViewModel.ProfileOverride` (removes the real bootstrap servers).
- **CLI** is tested end to end by invoking the real entry point in-process with a captured console, against the fake server (create, restore, info, sync, send).
- **Localization** has consistency tests: every key has all seven languages, placeholders match across languages, and every key used in XAML or C# exists.
- **Tests that touch process-wide state** (`AppPaths`, `Loc`, `Console`, the seams above) share the xUnit collection `AppPaths` so they run serially.
- **Coverage** is measured with `tests/coverage.runsettings` (test tooling excluded). CI fails if `Core` drops below 95% of lines or 88% of branches (`tests/check-coverage.py`); `App` and `Cli` are reported but not yet gated.
## Consequences
- Regressions in the wizard, reveal gating, lock handling and send preparation are caught without a display.
- Writing the tests found a real defect in `ElectrumClient` (requests hung forever after a protocol error); it is fixed and covered.
- `MainView` code-behind (window-bound) and the Android head remain untested.
- Headless tests run background timers; the test seams must stay in place for the life of the test process so that leftover ViewModels cannot reach the network.
## References
- `tests/PalladiumWallet.Tests/App/HeadlessSetup.cs`
- `tests/PalladiumWallet.Tests/App/VmTestBase.cs`
- `tests/PalladiumWallet.Tests/App/CliTests.cs`
- `tests/PalladiumWallet.Tests/App/LocalizationTests.cs`
- `tests/coverage.runsettings`
- `tests/check-coverage.py`
- Related: 0025, 0026, 0032
docs/adr/0034-bound-every-network-request.md
+28
View File
@@ -0,0 +1,28 @@
# 0034. Bound every network request with a timeout
- **Status:** Accepted
- **Area:** Network
- **Recorded:** 2026-11-03
## Context
`ElectrumClient.RequestAsync` waited until the server answered or the caller cancelled. The only timeout in the stack was the 8 s ping of the ViewModel keep-alive, which does not run while a sync is in progress. A server that stops answering without closing the socket (half-open TCP, Android Doze, a stalled or hostile server) left a running sync waiting forever, with no error and no automatic recovery.
## Decision
- Every request has a timeout, `ElectrumClient.DefaultRequestTimeout` (30 s). The `server.version` handshake has its own, shorter `DefaultHandshakeTimeout` (10 s). Both are parameters of `ConnectAsync` (`requestTimeout`, `handshakeTimeout`), so tests use a few hundred milliseconds.
- The timer starts when the request obtains its in-flight slot: waiting behind the cap (ADR 0009) does not count.
- On expiry the request fails with `TimeoutException` (naming the method and server) and the **whole connection is marked dead**: the other pending requests fail, `IsConnected` becomes false, `Disconnected` is raised and later requests fail fast with `IOException`. After a missed answer the socket cannot be trusted, and the ViewModel reconnects through the existing path. A late reply is dropped because the request is no longer pending.
- The keep-alive is left as it is (it skips ticks while syncing): the request timeout now bounds a stalled sync, so a second mechanism is not needed.
## Consequences
- A stalled server makes a sync fail within the timeout instead of hanging; the existing retry and reconnect logic takes over.
- A legitimately slow reply above 30 s is treated as a dead connection. The largest realistic replies (header batches, large transactions, busy-address histories) are far below that on a working link; the value is a constructor parameter if a deployment needs more.
- One slow request tears down the shared connection and the requests in flight with it. This is deliberate: it is cheaper than a half-open socket that keeps accepting writes.
## References
- `src/Core/Net/ElectrumClient.cs`
- `tests/PalladiumWallet.Tests/Net/ElectrumClientTests.cs`
- Related: 0009
docs/adr/0035-cap-server-line-length.md
+27
View File
@@ -0,0 +1,27 @@
# 0035. Cap the length of a server line
- **Status:** Accepted
- **Area:** Network
- **Recorded:** 2026-11-03
## Context
`ElectrumClient.ReadLoopAsync` accumulated bytes until it found a newline, with no maximum. A malicious, misconfigured or compromised server could send an endless line and drive memory use up until the process died, which is cheap to do and fatal on Android. `SECURITY.md` treats denial of service against the indexing server as out of scope, but here it is the client that dies, and the fix is small.
## Decision
- A single JSON-RPC line is capped at `ElectrumClient.DefaultMaxLineBytes` (16 MiB), a parameter of `ConnectAsync` (`maxLineBytes`). The default is well above the largest legitimate replies: header batches (a few hundred KB), a large transaction (up to about 2 MB of hex) and the history of a very active address (a few MB).
- The check runs as the buffer grows, **before** a newline arrives, and also on complete lines, so neither an unterminated stream nor one huge terminated line is buffered past the cap (apart from what a single read delivers).
- On excess the read loop fails with `InvalidDataException`. This reuses the protocol-error path: pending requests fail with that exception, the connection is marked dead, `Disconnected(ex)` is raised and later requests fail fast.
## Consequences
- One hostile server can no longer exhaust the memory of the client with an unbounded line.
- A legitimate reply larger than 16 MiB would be refused; none is expected on this chain, and the cap is a parameter.
- No new parser is introduced, so no new fuzz target.
## References
- `src/Core/Net/ElectrumClient.cs`
- `tests/PalladiumWallet.Tests/Net/ElectrumClientTests.cs`
- Related: 0009, 0034
docs/adr/0036-verify-chain-identity-on-connect.md
+35
View File
@@ -0,0 +1,35 @@
# 0036. Verify the chain identity of a server right after connecting
- **Status:** Accepted
- **Area:** SPV
- **Recorded:** 2026-11-03
## Context
The wallet connected to any Electrum server that answered on the configured port and found out it was on another chain only indirectly, and only for transactions at or above the first checkpoint, with a message that did not name the cause. The server probe checked the genesis hash; the wallet did not. A further complication: the mainnet profile reuses Bitcoin's genesis hash, and registry servers report exactly that value, so a genesis check alone cannot tell Palladium from Bitcoin.
## Decision
After the handshake, `ChainVerifier.VerifyChainAsync` (`Core/Spv/ChainVerifier.cs`) runs once per connection:
1. `server.features`: `genesis_hash` must be present and equal the profile's genesis (case-insensitive). A server that does not report it, or errors on the method, is rejected: the protocol requires it, and on testnet/regtest it is the only identity check.
2. `blockchain.headers.subscribe` gives the tip height. The highest hardcoded checkpoint with `Height <= tip` is selected.
3. The header at that height (`blockchain.block.header`) is hashed and compared with the checkpoint. A mismatch, a server error, or a malformed header means a different chain.
Any failure throws `WrongChainException` (server, reason). The GUI (connect and peer discovery), the CLI and the server probe all call the same helper; the GUI disposes the connection and moves on to the next candidate server, showing a localised message if none is usable.
A tip **below the first checkpoint** (a young testnet, a server still syncing) has nothing to compare and is accepted on the genesis check alone. A tip below the *latest* checkpoint is checked against the highest one it has reached; being behind is not an error.
## Consequences
- A server on another chain or fork is refused at connect time with an explicit message instead of failing indirectly during a sync.
- Mainnet is protected by the checkpoint header, not by the Bitcoin-shared genesis. Testnet and regtest (no checkpoints yet) rely on the genesis alone.
- Two extra requests per connection (`server.features`, `blockchain.headers.subscribe`, plus one header on mainnet). The sync asks for the tip again anyway.
- The check is made once, at connect time; a server that changes chain mid-connection is still caught by the per-transaction anchoring.
## References
- `src/Core/Spv/ChainVerifier.cs`
- `tests/PalladiumWallet.Tests/Spv/ChainVerifierTests.cs`
- `tests/PalladiumWallet.ServerProbe/Program.cs`
- Related: 0009, 0034
docs/adr/0037-derive-address-private-keys-on-reveal.md
+27
View File
@@ -0,0 +1,27 @@
# 0037. Derive an address private key only when it is revealed
- **Status:** Accepted
- **Area:** Security
- **Recorded:** 2026-11-03
## Context
`AddressRow` carried the WIF of its address, computed for every listed address (ten rows before the first sync, every scanned address after it). The reveal gate (password prompt) controlled only display, not presence: for the whole session the WIF of every address sat in managed strings, which cannot be zeroed, inside objects bound to the UI. That does not leak by itself, and `SECURITY.md` already states that keys live in process memory after unlock, but it widened the exposure to a memory dump or a binding bug for no benefit.
## Decision
- `AddressRow` and `AddressInfo` hold no key. `AddressRow` keeps `HasPrivKey` (true when the account is not watch-only); `AddressInfo` carries the derivation coordinates (`IsChange`, `Index`).
- The ViewModel derives the WIF in the reveal step, after the password check (`RevealPrivKeyInternal`), into `RevealedPrivKey`, which the overlay binds to.
- `RevealedPrivKey` is cleared when the key is hidden, when the sheet changes or closes, and when the wallet closes.
## Consequences
- The exposure window of an address key shrinks from the whole session to the time it is shown.
- The WIF string still cannot be zeroed; it lives until the garbage collector reclaims it. This is documented in `SECURITY.md`.
- Watch-only wallets still never reveal a key (`HasPrivKey` is false and the derivation returns nothing).
## References
- `src/App/ViewModels/MainWindowViewModel.cs`
- `src/App/ViewModels/MainWindowViewModel.Receive.cs`
- `tests/PalladiumWallet.Tests/App/MainWindowViewModelSecurityTests.cs`
docs/adr/0038-cli-password-sources-and-explicit-plaintext.md
+29
View File
@@ -0,0 +1,29 @@
# 0038. CLI password sources and explicit plaintext storage
- **Status:** Accepted
- **Area:** Distribution
- **Recorded:** 2026-11-03
## Context
The CLI read the wallet password only from `--password`, where it is stored in the shell history and visible to other local users in the process list (ADR 0024 already noted it). Worse, when `--password` was missing in `create`/`restore*` the CLI printed a warning and stored the **seed in plaintext**: a forgotten flag silently produced an unencrypted wallet.
## Decision
- Password sources, one at most per command: `--password-env NAME`, `--password-stdin` (first line), or `--password P` (kept for compatibility, prints a warning on stderr). With none, a no-echo prompt on the terminal (`Console.ReadKey(intercept: true)`), with a confirmation when creating a wallet. With no terminal the command fails with a clear message and never hangs.
- A new wallet (`create`, `restore`, `restore-xpub`, `restore-address`) is stored unencrypted **only** with `--no-encryption`, which prints a warning and cannot be combined with a password option. An empty password is refused.
- Opening: a plaintext wallet needs no password; an encrypted one needs a source. The password used to open is reused to save the wallet back (`sync`).
- Implemented in `src/Cli/CliPassword.cs`; the command logic in `Program.cs` only asks it for the password.
## Consequences
- A forgotten flag can no longer produce a plaintext wallet; scripts that relied on that must add `--no-encryption` (recorded as a behaviour change in the changelog).
- `--password` is not removed, so existing scripts with a password keep working; removing it is left to a major version.
- The environment variable route still exposes the password to processes that can read the environment of the CLI; it is safer than an argument but not a hardened interface (the CLI remains a developer tool).
## References
- `src/Cli/CliPassword.cs`
- `src/Cli/Program.cs`
- `tests/PalladiumWallet.Tests/App/CliTests.cs`
- Related: 0024
docs/adr/0039-server-fee-estimates-and-relay-floor.md
+31
View File
@@ -0,0 +1,31 @@
# 0039. Server fee estimates, relay floor and a high-fee warning
- **Status:** Accepted
- **Area:** Wallet
- **Recorded:** 2026-11-03
## Context
`EstimateFeeAsync` and `RelayFeeAsync` existed but nothing called them. The default fee rate was the constant 1 sat/vB and the only validation was "greater than zero" (and the F-01 upper bound). A rate below the node's minimum relay fee built a transaction that was rejected only at broadcast, with a generic server error, and a congested chain gave no guidance. ADR 0017 chose a single manual fee rate; this extends it without replacing the manual field.
## Decision
- After connecting, the ViewModel asks the server for `blockchain.relayfee` and `blockchain.estimatefee` with targets 2, 6 and 24 blocks (`FeePolicy.FetchAsync`, `Core/Wallet/FeePolicy.cs`). Each call is optional: an error or a malformed answer leaves that value empty.
- Values are converted from coin/kB to sat/vB (× 100,000,000 / 1,000), rounded to 2 decimals. `-1` (no estimate), zero, negative, or above `CoinAmount.MaxFeeRate` (1000 sat/vB) is discarded as implausible. An estimate is raised to the relay fee if lower.
- The Send form offers Fast, Normal and Economy buttons and a hint line with the numbers; Normal is preselected only if the user has not typed a rate. Without usable estimates the presets are hidden and the manual field keeps the 1 sat/vB default.
- A manual rate below the known relay fee is refused before building, with a message naming the minimum. Donate follows the same rules.
- The estimate is untrusted input, so the absolute fee is always shown, and the preview adds a warning when the fee exceeds 1% of the amount sent (`FeePolicy.IsHighFee`). The warning is advisory, not blocking.
## Consequences
- A rate the node would reject is caught locally with a clear message; the default follows the network instead of a constant.
- A malicious server can still suggest a high-but-plausible rate (up to 1000 sat/vB); the bound, the visible absolute fee and the 1% warning limit the damage, and the user can always type a rate.
- Presets fetched once per connection are not refreshed during a long session; reconnecting refreshes them.
- The relay-fee check relies on a value from the same server; a server that reports a high relay fee can only make the wallet more conservative, not less.
## References
- `src/Core/Wallet/FeePolicy.cs`
- `src/App/ViewModels/MainWindowViewModel.Send.cs`
- `tests/PalladiumWallet.Tests/Wallet/FeePolicyTests.cs`
- Related: 0017
docs/adr/0040-anchor-headers-up-to-a-checkpoint.md
+32
View File
@@ -0,0 +1,32 @@
# 0040. Anchor headers up to a checkpoint above them
- **Status:** Accepted
- **Area:** SPV
- **Supersedes:** the anchoring direction in 0006 (the rest of 0006 stands)
- **Recorded:** 2026-11-03
## Context
ADR 0006 skips proof-of-work validation (LWMA cannot be recomputed by an SPV client) and relies on hardcoded checkpoints. `AnchorToCheckpointAsync` took the nearest checkpoint **at or below** a transaction's height and verified that the headers from the checkpoint **up to** that height were prev-hash linked. With PoW not checked, that chain proves nothing: a hostile server can fabricate a header for the block of a fake transaction (with any Merkle root) and chain fabricated headers after the real checkpoint hash; every link is valid and the Merkle proof then matches the fabricated root. The existing tests built their own synthetic chains, so they could not see it. A related gap (L-01): heights below the first checkpoint had no anchor at all.
## Decision
- Anchor **up to** the nearest checkpoint at or above the height. The headers from the transaction's height to the checkpoint height are downloaded, must be prev-hash linked, and the last one must hash to the hardcoded checkpoint. Forging that needs a SHA-256 preimage, not just a consistent set of fake headers.
- `_anchoredDownTo[checkpointHeight]` records the lowest height already proven to reach that checkpoint. A later, lower height walks only the new segment, whose top is the already-trusted header; a height inside the range is a no-op. Persisted as `SyncCache.AnchoredDownTo`.
- Heights below the first checkpoint are anchored to it (at most one checkpoint interval, 20,000 headers); this closes L-01 without new checkpoints.
- **Above the newest checkpoint** there is nothing to anchor to: only the Merkle proof against the server's header is checked. This is a known, documented limit; it is narrowed by adding a recent checkpoint at every release (taken from a trusted node).
- A wallet cache without `AnchoredDownTo` (written by an older version) is not trusted for `VerifiedAt`: every proof is verified again once. Cached headers and raw transactions are reused. A preloaded anchor is accepted only if its headers are also cached and the recorded height is not above its checkpoint.
## Consequences
- The "headers are anchored to a checkpoint" claim now holds against a fabricating server, for every height up to the newest checkpoint.
- Recent transactions (since the last release's checkpoint) stay protected by the Merkle proof alone. Releases should always ship a fresh checkpoint.
- Downloading up to 20,000 headers (about 1.6 MB) for an old transaction is bounded and cached.
- First sync after upgrading is slower for wallets with many cached proofs (re-verification once).
## References
- `src/Core/Spv/WalletSynchronizer.cs`
- `src/Core/Storage/WalletDocument.cs`
- `tests/PalladiumWallet.Tests/Spv/WalletSynchronizerTests.cs`
- Related: 0006, 0036
docs/adr/0041-flag-transactions-above-the-newest-checkpoint.md
+28
View File
@@ -0,0 +1,28 @@
# 0041. Flag transactions above the newest checkpoint as not anchored
- **Status:** Accepted
- **Area:** SPV
- **Recorded:** 2026-11-03
## Context
ADR 0040 anchors every header used for a Merkle proof up to a hardcoded checkpoint at or above it. Blocks above the newest checkpoint (those mined since the last release) have nothing to anchor to, so for them only the Merkle proof against the header the server supplied is checked. This is a known limit; the user could not see which transactions it applied to.
## Decision
- `ChainProfile.IsAboveNewestCheckpoint(height)` is true for a confirmed height above the highest checkpoint of a profile that has checkpoints. It is false for unconfirmed transactions and for profiles without checkpoints (testnet/regtest), where nothing is anchored by design and the notion does not apply.
- `HistoryRow` carries `Unanchored`; the History list (desktop and mobile layouts) shows an orange "not anchored" label with a tooltip explaining it, and the transaction detail appends the same text to its status line.
- The flag is informational: it does not block spending or change the Merkle verification. Reducing the window itself is done by shipping a recent checkpoint with every release; a second-server cross-check or a bounded proof-of-work check remain open options (see the backlog).
## Consequences
- The reduced guarantee is visible per transaction instead of silent, and disappears after an update whose checkpoint covers the block.
- Every wallet user sees the label on the most recent transactions between releases; the tooltip and the user guide explain it. It can alarm users unnecessarily, which is the price of honesty here.
## References
- `src/Core/Chain/ChainProfile.cs`
- `src/App/ViewModels/MainWindowViewModel.Receive.cs`
- `src/App/Views/MainView.axaml`
- `tests/PalladiumWallet.Tests/App/MainWindowViewModelTests.cs`
- Related: 0040
docs/adr/0042-cross-check-recent-headers-with-a-witness-server.md
+35
View File
@@ -0,0 +1,35 @@
# 0042. Cross-check recent headers with a witness server; no bounded-PoW check
- **Status:** Accepted
- **Area:** SPV
- **Recorded:** 2026-11-03
## Context
ADR 0040 anchors every header used for a Merkle proof up to a hardcoded checkpoint, but a block above the newest checkpoint has nothing to anchor to: only the header the primary server supplies and the Merkle proof against it are checked. A hostile server could show a payment that never happened in those recent blocks. ADR 0041 made the limit visible; this ADR reduces it.
## Decision
- **Witness cross-check.** For a block above the newest checkpoint, `WalletSynchronizer` asks a second server (a "witness") for the header at the same height and requires identical bytes. The witnesses come from `WalletSynchronizer.WitnessProvider`, called lazily once, only when such a header is first needed.
- **Witness selection** (`WitnessConnector`): only from the **hardcoded bootstrap list** of the profile, never from the peers a server announces (a hostile server could announce only its own), never the primary server, each verified to be on the chain (ADR 0036). One witness by default (`DefaultMax`). Used by the GUI and the CLI; the GUI closes them with the primary connection.
- **Outcomes.** Agreement: the proof verifies as before. A witness that is unreachable, errors, or does not know the block: skipped. No witness at all: unchanged behaviour (Merkle proof only). Disagreement at a depth of at least `CrossCheckMinDepth` (3) blocks: `SpvVerificationException` ("servers disagree"), the sync aborts. Disagreement at a shallower depth may be a reorganisation in progress: the proof is left **unverified** (not spendable, not cached) and decided again at the next sync.
- Each height is asked once per synchronizer. Heights covered by a checkpoint are not cross-checked.
- The "not anchored" flag of ADR 0041 stays height-based: it is not cleared by a successful cross-check, because that result is not persisted.
## Rejected: bounded proof-of-work
The idea was to require recent headers to meet a target no easier than a bound on the newest checkpoint's difficulty. The data in the shipped checkpoints argue against it: between consecutive checkpoints (20,000 blocks) the target changed by up to 8x easier and 200x harder, so a safe bound would be loose; the network is small (about tens of TH/s at the last checkpoint), so work at a fraction of a block's difficulty is cheap to rent; and a bound that is too tight would make the wallet reject honest servers whenever hash rate drops. It would add cost and a false-rejection risk for little protection. Not implemented.
## Consequences
- A single lying server can no longer fabricate a recent payment on its own: it would have to control the witness too. A witness run by the same operator as the primary, or an attacker positioned in front of both, defeats it; this is a hardening, not a proof.
- One extra connection (TLS, pinned) is opened when a recent block needs checking; none for wallets whose history is all below the newest checkpoint.
- A transaction in a block 1-2 deep on which the servers briefly disagree shows as "verifying" until the next sync.
- A fresh checkpoint in every release still shrinks the window the cross-check has to cover.
## References
- `src/Core/Spv/WalletSynchronizer.cs`
- `src/Core/Spv/WitnessConnector.cs`
- `tests/PalladiumWallet.Tests/Spv/WalletSynchronizerTests.cs`
- Related: 0036, 0040, 0041
docs/adr/README.md
+51
View File
@@ -0,0 +1,51 @@
# Architecture Decision Records
One ADR per feature or significant design decision. Format: `template.md`. Workflow: `../docs-as-code.md`.
| # | Decision | Area | Status |
|---|----------|------|--------|
| 0001 | [Record architecture decisions as ADRs](0001-record-architecture-decisions.md) | Process | Accepted |
| 0002 | [One shared Avalonia UI with thin platform heads](0002-shared-avalonia-ui-with-platform-heads.md) | Architecture | Accepted |
| 0003 | [Layered architecture: Core knows nothing about the UI](0003-core-without-ui-dependency.md) | Architecture | Accepted |
| 0004 | [Centralize all chain constants in a network profile](0004-centralized-network-profile.md) | Chain | Accepted |
| 0005 | [Use NBitcoin for protocol primitives, hand-write only the rest](0005-nbitcoin-for-protocol-primitives.md) | Crypto | Accepted |
| 0006 | [Anchor headers to hardcoded checkpoints and skip PoW validation](0006-spv-checkpoint-anchoring-without-pow.md) | SPV | Accepted |
| 0007 | [Verify a Merkle proof for every confirmed transaction](0007-mandatory-merkle-verification.md) | SPV | Accepted |
| 0008 | [Progressive verification: show early, spend only after proof](0008-progressive-verification-sync.md) | SPV | Accepted |
| 0009 | [Hand-written Electrum JSON-RPC client with pipelining and an in-flight cap](0009-custom-electrum-client.md) | Network | Accepted |
| 0010 | [TOFU certificate pinning for indexing servers](0010-tls-tofu-certificate-pinning.md) | Network | Accepted |
| 0011 | [Server registry seeded by bootstrap list and peer discovery](0011-server-registry-and-discovery.md) | Network | Accepted |
| 0012 | [Wallet file encrypted with AES-256-GCM and PBKDF2-HMAC-SHA512](0012-encrypted-wallet-file.md) | Storage | Accepted |
| 0013 | [Versioned JSON wallet document with an offline sync cache](0013-versioned-wallet-document-and-sync-cache.md) | Storage | Accepted |
| 0014 | [BIP32/39 HD wallets with BIP44/49/84 paths and SLIP-132 keys](0014-hd-derivation-and-slip132.md) | Crypto | Accepted |
| 0015 | [Imported-key and watch-only accounts](0015-imported-keys-and-watch-only-accounts.md) | Wallet | Accepted |
| 0016 | [Route every signing flow through PSBT](0016-psbt-centric-signing.md) | Wallet | Accepted |
| 0017 | [Coin selection, fee and confirmation policy](0017-coin-selection-fee-and-spendability-policy.md) | Wallet | Accepted |
| 0018 | [Exclusive OS-level lock on the open wallet file](0018-exclusive-wallet-file-lock.md) | Storage | Accepted |
| 0019 | [Resolve the data root by explicit precedence](0019-data-location-resolution.md) | Storage | Accepted |
| 0020 | [A single ViewModel split into partial classes by feature](0020-single-viewmodel-with-feature-partials.md) | UI | Accepted |
| 0021 | [In-app overlays instead of OS windows](0021-in-app-overlays-instead-of-windows.md) | UI | Accepted |
| 0022 | [In-code localization table for seven languages](0022-localization-seven-languages.md) | UI | Accepted |
| 0023 | [Best-effort update check against GitHub releases](0023-github-release-update-check.md) | Distribution | Accepted |
| 0024 | [A CLI front end on the same Core](0024-cli-on-shared-core.md) | Distribution | Accepted |
| 0025 | [Test the network layer against an in-process fake server](0025-in-process-fake-electrum-server-for-tests.md) | Testing | Accepted |
| 0026 | [Fuzz every untrusted-input parser](0026-fuzzing-untrusted-input-parsers.md) | Testing | Accepted |
| 0027 | [Server probe tool and opt-in live-server test](0027-server-probe-and-live-server-test.md) | Testing | Accepted |
| 0028 | [Reproducible release builds inside pinned Docker images](0028-reproducible-docker-release-builds.md) | Distribution | Accepted |
| 0029 | [Persistent Android release keystore kept out of git](0029-persistent-android-signing-keystore.md) | Distribution | Accepted |
| 0030 | [Single-source versioning with a mandatory changelog entry](0030-single-source-versioning-and-changelog.md) | Distribution | Accepted |
| 0031 | [Explicitly defer multisig, Lightning, Tor and hardware wallets](0031-defer-multisig-lightning-and-hardware-wallets.md) | Scope | Accepted |
| 0032 | [Run tests, fuzz smoke and docs checks in GitHub Actions](0032-github-actions-ci.md) | Testing | Accepted |
| 0033 | [Test the UI layer and CLI headlessly, gate coverage](0033-test-strategy-beyond-core.md) | Testing | Accepted |
| 0034 | [Bound every network request with a timeout](0034-bound-every-network-request.md) | Network | Accepted |
| 0035 | [Cap the length of a server line](0035-cap-server-line-length.md) | Network | Accepted |
| 0036 | [Verify the chain identity of a server right after connecting](0036-verify-chain-identity-on-connect.md) | SPV | Accepted |
| 0037 | [Derive an address private key only when it is revealed](0037-derive-address-private-keys-on-reveal.md) | Security | Accepted |
| 0038 | [CLI password sources and explicit plaintext storage](0038-cli-password-sources-and-explicit-plaintext.md) | Distribution | Accepted |
| 0039 | [Server fee estimates, relay floor and a high-fee warning](0039-server-fee-estimates-and-relay-floor.md) | Wallet | Accepted |
| 0040 | [Anchor headers up to a checkpoint above them](0040-anchor-headers-up-to-a-checkpoint.md) | SPV | Accepted |
| 0041 | [Flag transactions above the newest checkpoint as not anchored](0041-flag-transactions-above-the-newest-checkpoint.md) | SPV | Accepted |
| 0042 | [Cross-check recent headers with a witness server; no bounded-PoW check](0042-cross-check-recent-headers-with-a-witness-server.md) | SPV | Accepted |
ADRs `0002` onwards were written retroactively on 2026-11-03 from the code, comments and changelog.
If one misstates the original reasoning, fix it in a pull request.
docs/adr/template.md
+25
View File
@@ -0,0 +1,25 @@
# NNNN. Title in the imperative, naming the decision
- **Status:** Proposed | Accepted | Deprecated | Superseded by [NNNN](NNNN-slug.md)
- **Area:** Architecture | Chain | Crypto | Net | SPV | Storage | Wallet | UI | Testing | Distribution | Scope | Process
- **Recorded:** YYYY-MM-DD
## Context
The forces at play: the problem, the constraints, what was tried or rejected.
Facts only; link to code, issues or specs instead of restating them.
## Decision
What we do, in the active voice ("We use…"). Specific enough that a reviewer
can check the code against it.
## Consequences
What becomes easier, what becomes harder, new risks, follow-up work.
Be honest about the downsides.
## References
- `path/to/code.cs`
- Related ADRs, specs (BIPs), issues
docs/check-docs.sh
Executable
+50
View File
@@ -0,0 +1,50 @@
#!/usr/bin/env bash
# Mechanical checks for docs/ (see docs/docs-as-code.md). Run from anywhere.
set -u
cd "$(dirname "$0")/.." || exit 2
fail=0
err() { echo "FAIL: $*"; fail=1; }
adr_dir=docs/adr
prev=0
for f in $(ls $adr_dir/[0-9][0-9][0-9][0-9]-*.md 2>/dev/null | sort); do
base=$(basename "$f"); num=${base:0:4}
n=$((10#$num))
[ "$n" -eq $((prev + 1)) ] || err "$base: numbering gap or duplicate (previous $prev)"
prev=$n
head -1 "$f" | grep -q "^# $num\. " || err "$base: first line must be '# $num. <title>'"
grep -qE '^- \*\*Status:\*\* ' "$f" || err "$base: missing Status line"
for s in Context Decision Consequences; do
grep -q "^## $s\$" "$f" || err "$base: missing '## $s' section"
done
grep -q "($base)" $adr_dir/README.md || err "$base: not listed in $adr_dir/README.md"
done
[ "$prev" -gt 0 ] || err "no ADRs found"
# Index rows must point to existing files.
grep -oE '\]\([0-9]{4}-[^)]+\.md\)' $adr_dir/README.md | tr -d '])(' | while read -r l; do
[ -f "$adr_dir/$l" ] || { echo "FAIL: index links to missing $l"; exit 1; }
done || fail=1
# Repo paths cited in backticks must exist.
while IFS= read -r line; do
file=${line%%:*}; p=${line#*:}
[ -e "$p" ] || err "$file: cited path does not exist: $p"
done < <(grep -oE '`(src|tests|docker|docs)/[A-Za-z0-9_./-]+`|`(README|USERGUIDE|SECURITY|CHANGELOG|CLAUDE|AGENTS)\.md`|`update-version\.sh`|`\.gitignore`' -r docs --include='*.md' \
| grep -v 'template.md' | sed -E 's/`//g' | grep -v 'docs/adr/NNNN' | grep -v 'path/to')
# Relative markdown links in docs/ must resolve.
for f in $(find docs -name '*.md'); do
d=$(dirname "$f")
for l in $(grep -oE '\]\([^)#:]+\.md\)' "$f" | sed -E "s/^\]\(|\)\$//g" | grep -v NNNN); do
[ -e "$d/$l" ] || err "$f: broken link $l"
done
done
# CLAUDE.md and AGENTS.md must match apart from the header block (before '## Role').
if ! diff <(sed -n '/^## Role/,$p' CLAUDE.md) <(sed -n '/^## Role/,$p' AGENTS.md) >/dev/null; then
err "CLAUDE.md and AGENTS.md differ after the header block"
fi
[ "$fail" -eq 0 ] && echo "docs OK ($prev ADRs)"
exit "$fail"
docs/docs-as-code.md
+110
View File
@@ -0,0 +1,110 @@
# Docs as code
Documentation in this repository is treated like source code: plain text in git,
changed through pull requests, checked by a script, and kept next to the code it
describes. This page defines how.
## Principles
1. **Docs live in the repo.** Markdown files, versioned with the code. No wiki,
no separate document store that can drift from the release it describes.
2. **One change, one pull request.** A change to behaviour, a file format,
cryptography, SPV validation or key handling updates the affected docs in the
same commit. `SECURITY.md` is the published threat model and must stay accurate
(see `CLAUDE.md`, *Working rules*).
3. **Review docs like code.** Reviewers check that the text matches the diff.
4. **English only** for documentation, comments and commit messages.
5. **Diagrams are text.** Use Mermaid code blocks, which render on GitHub and diff
cleanly. No binary diagram files unless a tool cannot export text.
6. **Prefer links to copies.** Point to the code path or the ADR instead of
restating it, so there is one place to update.
7. **Check mechanically.** `docs/check-docs.sh` runs the checks below; run it
before committing documentation changes.
## Where things go
| What | Where | Audience |
|------|-------|----------|
| Project overview, build and run, test | `README.md` | Developers |
| End-user manual | `USERGUIDE.md` | Users |
| Threat model, crypto parameters, SPV trust | `SECURITY.md` | Users, reviewers |
| What shipped in each release | `CHANGELOG.md` | Everyone |
| Why the design is the way it is | `docs/adr/` | Maintainers, reviewers |
| This process | `docs/docs-as-code.md` | Contributors |
| Build, signing and release procedure | `docker/README.md`, `docker/keystore/README.md` | Release managers |
| Rules for coding agents | `CLAUDE.md` and `AGENTS.md` (kept identical apart from their header) | Agents |
Rule of thumb: *what* and *how* belong to the README, user guide and code comments;
*why this and not the alternative* belongs to an ADR.
## Architecture Decision Records
One ADR per feature or significant decision, in `docs/adr/NNNN-slug.md`, written
from `docs/adr/template.md`. The index is `docs/adr/README.md`.
**When to write one.** Add or change an ADR when a change:
- introduces a feature or subsystem;
- touches cryptography, SPV validation, key or seed handling, or the file format;
- is hard to reverse, or someone is likely to ask "why not X?" later.
Bug fixes and refactors that keep the decision intact do not need an ADR.
**Lifecycle.**
```mermaid
stateDiagram-v2
[*] --> Proposed: opened in a pull request
Proposed --> Accepted: merged
Proposed --> [*]: rejected, PR closed
Accepted --> Superseded: a newer ADR replaces it
Accepted --> Deprecated: feature removed
```
- Number ADRs sequentially; never reuse or renumber.
- Do not rewrite the substance of an Accepted ADR. To change a decision, write a
new ADR, set the old one's status to `Superseded by [NNNN](NNNN-slug.md)` and
link back from the new one. Typos and broken links can be fixed in place.
- Keep each ADR short: context, decision, consequences, references.
- Reference code by repository-relative path in backticks. The check script
verifies these paths still exist, so a rename shows up as a docs failure.
## Workflow
```mermaid
flowchart LR
A[Change code] --> B{Decision hard to<br/>reverse or security-relevant?}
B -- yes --> C[Add or supersede ADR]
B -- no --> D[Update README / USERGUIDE / SECURITY if affected]
C --> D
D --> E[Run docs/check-docs.sh]
E --> F[Pull request: code + docs together]
F --> G[Review checks text against diff]
```
1. Make the code change.
2. Decide whether an ADR is needed (see above) and write or supersede it.
3. Update `README.md`, `USERGUIDE.md`, `SECURITY.md` and `CHANGELOG.md` where the
change affects them. If you edit `CLAUDE.md`, mirror the edit into `AGENTS.md`.
4. Run `docs/check-docs.sh`.
5. Commit code and docs together and open the pull request.
## What `docs/check-docs.sh` verifies
- Every ADR file is named `NNNN-slug.md`, numbers are unique and contiguous.
- Every ADR has a title line matching its number, a `Status`, and the sections
*Context*, *Decision*, *Consequences*.
- Every ADR is listed in `docs/adr/README.md`, and every index row points to a file.
- Repository paths cited in backticks (`src/…`, `tests/…`, `docker/…`, root files)
exist.
- Relative Markdown links in `docs/` resolve.
- `CLAUDE.md` and `AGENTS.md` match apart from their header block.
It needs only `bash` and standard tools, so it runs on a developer machine and in CI
(the `docs` job in `.github/workflows/ci.yml`, see ADR 0032).
## Possible next steps (not in place yet)
- Add a Markdown linter to the `docs` CI job.
- Add a link checker for external URLs.
- Publish `docs/` as a static site if the audience outgrows GitHub's renderer.
src/App.Android/MainActivity.cs
+59
View File
@@ -0,0 +1,59 @@
using System.Threading.Tasks;
using Android.App;
using Android.Content;
using Android.Content.PM;
using Android.OS;
using Avalonia.Android;
using AvaloniaApp = PalladiumWallet.App.App;
namespace PalladiumWallet.Mobile;
[Activity(
Label = "Palladium Wallet",
Theme = "@style/MyTheme.NoActionBar",
MainLauncher = true,
ConfigurationChanges = ConfigChanges.Orientation | ConfigChanges.ScreenSize | ConfigChanges.UiMode)]
public class MainActivity : AvaloniaMainActivity
{
internal const int ScanRequestCode = 9001;
internal static TaskCompletionSource<string?>? ScanTcs;
internal static MainActivity? Current;
private bool _wasPaused;
protected override void OnCreate(Bundle? savedInstanceState)
{
base.OnCreate(savedInstanceState);
Current = this;
}
protected override void OnPause()
{
base.OnPause();
_wasPaused = true;
}
protected override void OnResume()
{
base.OnResume();
if (!_wasPaused) return;
_wasPaused = false;
// The TCP socket can die silently while the screen was off/locked (Doze,
// mobile radio suspend, NAT timeout) without the app ever observing the
// failure. Force an immediate health check instead of waiting for the next
// 20s keep-alive tick, which may itself have been suspended for longer than
// the lock.
if (AvaloniaApp.MainViewModel is { } vm)
_ = vm.CheckConnectionOnResumeAsync();
}
protected override void OnActivityResult(int requestCode, Result resultCode, Intent? data)
{
base.OnActivityResult(requestCode, resultCode, data);
if (requestCode == ScanRequestCode)
{
var text = resultCode == Result.Ok ? data?.GetStringExtra(ScannerActivity.ResultKey) : null;
ScanTcs?.TrySetResult(text);
ScanTcs = null;
}
}
}
src/App.Android/MainApplication.cs
+47
View File
@@ -0,0 +1,47 @@
using System;
using System.Threading.Tasks;
using Android.App;
using Android.Content;
using Android.Runtime;
using Avalonia;
using Avalonia.Android;
using PalladiumWallet.App.Services;
using PalladiumWallet.Core.Storage;
namespace PalladiumWallet.Mobile;
// In Avalonia 12 the Android AppBuilder is configured in the Application subclass
// (AvaloniaAndroidApplication<TApp>), no longer in the Activity. allowBackup=false:
// the encrypted wallet file/seed must not end up in automatic cloud backups.
[Application(Label = "Palladium Wallet", AllowBackup = false,
Icon = "@mipmap/ic_launcher", RoundIcon = "@mipmap/ic_launcher_round")]
public class MainApplication : AvaloniaAndroidApplication<global::PalladiumWallet.App.App>
{
public MainApplication(IntPtr javaReference, JniHandleOwnership transfer)
: base(javaReference, transfer)
{
}
public override void OnCreate()
{
AppPaths.OverrideDataRoot = FilesDir?.AbsolutePath;
// Registers the QR scanner: opens ScannerActivity and waits for its result.
PlatformServices.ScanQrAsync = async () =>
{
var activity = MainActivity.Current;
if (activity == null) return null;
var tcs = new TaskCompletionSource<string?>();
MainActivity.ScanTcs = tcs;
activity.StartActivityForResult(
new Intent(activity, typeof(ScannerActivity)),
MainActivity.ScanRequestCode);
return await tcs.Task;
};
base.OnCreate();
}
protected override AppBuilder CustomizeAppBuilder(AppBuilder builder) =>
base.CustomizeAppBuilder(builder).WithInterFont();
}
src/App.Android/PalladiumWallet.App.Android.csproj
+32
View File
@@ -0,0 +1,32 @@
<Project Sdk="Microsoft.NET.Sdk">
<!-- Head Android: entry-point e pacchetti specifici. La UI vera vive nella
libreria condivisa PalladiumWallet.App (stessa di desktop). -->
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net10.0-android</TargetFramework>
<SupportedOSPlatformVersion>23</SupportedOSPlatformVersion>
<Nullable>enable</Nullable>
<ApplicationId>io.github.davide3011.palladiumwallet</ApplicationId>
<!-- ApplicationVersion = versionCode (intero), ApplicationDisplayVersion = versionName -->
<ApplicationVersion>5</ApplicationVersion>
<ApplicationDisplayVersion>1.2.0</ApplicationDisplayVersion>
<AndroidPackageFormat>apk</AndroidPackageFormat>
<!-- Includi le assembly .NET DENTRO l'apk: senza, in Debug si usa il Fast
Deployment (assembly spinte via adb da `dotnet run`) e un apk installato
a mano — sideload sul telefono o `adb install` — crasha all'avvio con
"monodroid: No assemblies found ... Exiting". Così l'apk è autosufficiente. -->
<EmbedAssembliesIntoApk>true</EmbedAssembliesIntoApk>
<!-- Default: ABI multiple (l'apk gira sia su emulatore x86_64 sia su telefoni arm64).
Per un apk più piccolo solo-telefono: aggiungi -p:AbiArm64Only=true alla build. -->
<RuntimeIdentifiers Condition="'$(AbiArm64Only)' == 'true'">android-arm64</RuntimeIdentifiers>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Avalonia.Android" Version="12.0.4" />
<PackageReference Include="ZXing.Net" Version="0.16.9" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\App\PalladiumWallet.App.csproj" />
</ItemGroup>
</Project>
src/App.Android/Properties/AndroidManifest.xml
+10
View File
@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<!-- Necessario per parlare col server di indicizzazione (TCP/TLS).
L'elemento <application> (label, allowBackup) è generato dall'attributo
[Application] su MainApplication. usesCleartextTraffic resta al default
(bloccato su Android 9+): il wallet preferisce comunque TLS. -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" android:required="false" />
</manifest>
src/App.Android/Resources/drawable/ic_launcher_foreground.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

src/App.Android/Resources/mipmap-anydpi-v26/ic_launcher.xml
+5
View File
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@color/ic_launcher_background"/>
<foreground android:drawable="@drawable/ic_launcher_foreground"/>
</adaptive-icon>
src/App.Android/Resources/mipmap-anydpi-v26/ic_launcher_round.xml
+5
View File
@@ -0,0 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
<background android:drawable="@color/ic_launcher_background"/>
<foreground android:drawable="@drawable/ic_launcher_foreground"/>
</adaptive-icon>
src/App.Android/Resources/mipmap-hdpi/ic_launcher.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.2 KiB

src/App.Android/Resources/mipmap-mdpi/ic_launcher.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.4 KiB

src/App.Android/Resources/mipmap-xhdpi/ic_launcher.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.4 KiB

src/App.Android/Resources/mipmap-xxhdpi/ic_launcher.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 11 KiB

src/App.Android/Resources/mipmap-xxxhdpi/ic_launcher.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

src/App.Android/Resources/values/ic_launcher_background.xml
+4
View File
@@ -0,0 +1,4 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<color name="ic_launcher_background">#FFFFFF</color>
</resources>
src/App.Android/Resources/values/styles.xml
+7
View File
@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- DEVE derivare da Theme.AppCompat: AvaloniaActivity estende AppCompatActivity,
che con un tema non-AppCompat lancia IllegalStateException all'avvio.
Avalonia disegna comunque l'intera UI (NoActionBar). -->
<style name="MyTheme.NoActionBar" parent="Theme.AppCompat.Light.NoActionBar" />
</resources>
src/App.Android/ScannerActivity.cs
+218
View File
@@ -0,0 +1,218 @@
using System;
using System.Collections.Generic;
using System.Linq;
using Android.App;
using Android.Content;
using Android.Graphics;
using Android.Hardware.Camera2;
using Android.Media;
using Android.OS;
using Android.Views;
using Android.Widget;
using ZXing;
using ZXing.Common;
using AndroidResult = Android.App.Result;
namespace PalladiumWallet.Mobile;
/// <summary>
/// Full-screen activity for QR scanning via Camera2 + ZXing.Net.
/// Returns to MainActivity via SetResult with the extra "qr" = code text.
/// </summary>
[Activity(Theme = "@style/MyTheme.NoActionBar",
ScreenOrientation = Android.Content.PM.ScreenOrientation.Portrait)]
internal sealed class ScannerActivity : Activity, TextureView.ISurfaceTextureListener
{
internal const string ResultKey = "qr";
private const int PermReq = 1;
private HandlerThread? _bgThread;
private Handler? _bgHandler;
private CameraDevice? _camera;
private CameraCaptureSession? _session;
private ImageReader? _imageReader;
private SurfaceTexture? _surfaceTex;
private bool _permOk;
private volatile bool _done;
private long _lastDecode;
protected override void OnCreate(Bundle? savedInstanceState)
{
base.OnCreate(savedInstanceState);
Window!.SetFlags(WindowManagerFlags.Fullscreen, WindowManagerFlags.Fullscreen);
var root = new FrameLayout(this);
var preview = new TextureView(this) { SurfaceTextureListener = this };
root.AddView(preview, new FrameLayout.LayoutParams(
FrameLayout.LayoutParams.MatchParent, FrameLayout.LayoutParams.MatchParent));
var hint = new TextView(this) { Text = "Inquadra un codice QR" };
hint.SetTextColor(Color.White);
hint.SetBackgroundColor(Color.ParseColor("#AA000000"));
hint.SetPadding(24, 12, 24, 12);
root.AddView(hint, new FrameLayout.LayoutParams(
FrameLayout.LayoutParams.WrapContent, FrameLayout.LayoutParams.WrapContent,
GravityFlags.Top | GravityFlags.CenterHorizontal) { TopMargin = 60 });
var cancel = new Button(this) { Text = "Annulla" };
cancel.Click += (_, _) => Finish();
root.AddView(cancel, new FrameLayout.LayoutParams(
FrameLayout.LayoutParams.WrapContent, FrameLayout.LayoutParams.WrapContent,
GravityFlags.Bottom | GravityFlags.CenterHorizontal) { BottomMargin = 80 });
SetContentView(root);
_bgThread = new HandlerThread("CamBg");
_bgThread.Start();
_bgHandler = new Handler(_bgThread.Looper!);
if (CheckSelfPermission(Android.Manifest.Permission.Camera) == Android.Content.PM.Permission.Granted)
_permOk = true;
else
RequestPermissions([Android.Manifest.Permission.Camera], PermReq);
}
public override void OnRequestPermissionsResult(int req, string[] perms, Android.Content.PM.Permission[] grants)
{
_permOk = grants.Length > 0 && grants[0] == Android.Content.PM.Permission.Granted;
if (_permOk) TryOpen(); else Finish();
}
public void OnSurfaceTextureAvailable(SurfaceTexture st, int w, int h) { _surfaceTex = st; TryOpen(); }
public bool OnSurfaceTextureDestroyed(SurfaceTexture st) { CloseCamera(); return true; }
public void OnSurfaceTextureSizeChanged(SurfaceTexture st, int w, int h) { }
public void OnSurfaceTextureUpdated(SurfaceTexture st) { }
private void TryOpen() { if (_permOk && _surfaceTex != null) OpenCamera(_surfaceTex); }
private void OpenCamera(SurfaceTexture st)
{
var mgr = (CameraManager)GetSystemService(CameraService)!;
var ids = mgr.GetCameraIdList()!;
string cameraId = ids[0];
foreach (var id in ids)
{
var chars = mgr.GetCameraCharacteristics(id)!;
if (chars.Get(CameraCharacteristics.LensFacing) is Java.Lang.Integer f
&& f.IntValue() == (int)LensFacing.Back)
{ cameraId = id; break; }
}
var map = mgr.GetCameraCharacteristics(cameraId)!
.Get(CameraCharacteristics.ScalerStreamConfigurationMap)
as Android.Hardware.Camera2.Params.StreamConfigurationMap;
var allSizes = map!.GetOutputSizes((int)ImageFormatType.Jpeg)!;
var size = allSizes.OrderBy(s => Math.Abs(s.Width - 640)).First();
st.SetDefaultBufferSize(size.Width, size.Height);
_imageReader = ImageReader.NewInstance(size.Width, size.Height, ImageFormatType.Jpeg, 2);
_imageReader.SetOnImageAvailableListener(new ImageListener(this), _bgHandler);
mgr.OpenCamera(cameraId, new OpenCb(this, st), _bgHandler);
}
private void CloseCamera()
{
_session?.Close(); _session = null;
_camera?.Close(); _camera = null;
_imageReader?.Close(); _imageReader = null;
_bgThread?.QuitSafely();
}
internal void OnCameraOpened(CameraDevice dev, SurfaceTexture st)
{
_camera = dev;
var prevSurf = new Surface(st);
var capSurf = _imageReader!.Surface!;
#pragma warning disable CA1422 // CreateCaptureSession(IList,...) obsoleted on API 30; replacement needs API 28, our min is 23
dev.CreateCaptureSession([prevSurf, capSurf], new SessionCb(this, prevSurf, capSurf), _bgHandler);
#pragma warning restore CA1422
}
internal void OnSessionReady(CameraCaptureSession session, Surface prev, Surface cap)
{
_session = session;
var req = _camera!.CreateCaptureRequest(CameraTemplate.Preview);
req.AddTarget(prev);
req.AddTarget(cap);
session.SetRepeatingRequest(req.Build()!, null, _bgHandler);
}
internal void TryDecode(ImageReader reader)
{
if (_done) return;
var image = reader.AcquireLatestImage();
if (image == null) return;
try
{
var now = SystemClock.ElapsedRealtime();
if (now - _lastDecode < 400) return; // max ~2.5 fps
_lastDecode = now;
var buf = image.GetPlanes()![0].Buffer!;
var bytes = new byte[buf.Remaining()];
buf.Get(bytes);
var bmp = BitmapFactory.DecodeByteArray(bytes, 0, bytes.Length);
if (bmp == null) return;
int w = bmp.Width, h = bmp.Height;
var pixels = new int[w * h];
bmp.GetPixels(pixels, 0, w, 0, 0, w, h);
bmp.Recycle();
// ARGB int[] → RGB byte[] for ZXing.RGBLuminanceSource
var rgb = new byte[pixels.Length * 3];
for (int i = 0; i < pixels.Length; i++)
{
rgb[i * 3] = (byte)(pixels[i] >> 16);
rgb[i * 3 + 1] = (byte)(pixels[i] >> 8);
rgb[i * 3 + 2] = (byte) pixels[i];
}
var source = new RGBLuminanceSource(rgb, w, h, RGBLuminanceSource.BitmapFormat.RGB24);
var zreader = new BarcodeReaderGeneric { AutoRotate = true };
zreader.Options.PossibleFormats = [BarcodeFormat.QR_CODE];
zreader.Options.TryHarder = true;
var result = zreader.Decode(source);
if (result == null) return;
_done = true;
RunOnUiThread(() =>
{
var intent = new Intent().PutExtra(ResultKey, result.Text);
SetResult(AndroidResult.Ok, intent);
Finish();
});
}
finally { image.Close(); }
}
protected override void OnDestroy()
{
CloseCamera();
base.OnDestroy();
}
// ── Callback helpers ─────────────────────────────────────────────────
private sealed class OpenCb(ScannerActivity a, SurfaceTexture st) : CameraDevice.StateCallback
{
public override void OnOpened(CameraDevice cam) => a.OnCameraOpened(cam, st);
public override void OnDisconnected(CameraDevice cam) { cam.Close(); a.Finish(); }
public override void OnError(CameraDevice cam, CameraError err) { cam.Close(); a.Finish(); }
}
private sealed class SessionCb(ScannerActivity a, Surface prev, Surface cap) : CameraCaptureSession.StateCallback
{
public override void OnConfigured(CameraCaptureSession s) => a.OnSessionReady(s, prev, cap);
public override void OnConfigureFailed(CameraCaptureSession s) => a.Finish();
}
private sealed class ImageListener(ScannerActivity a) : Java.Lang.Object, ImageReader.IOnImageAvailableListener
{
// Interface declares ImageReader? but reader is never null in practice
public void OnImageAvailable(ImageReader? reader) => a.TryDecode(reader!);
}
}
src/App.Desktop/PalladiumWallet.App.Desktop.csproj
+25
View File
@@ -0,0 +1,25 @@
<Project Sdk="Microsoft.NET.Sdk">
<!-- Head Desktop (Windows/Linux): entry-point e pacchetti specifici del
desktop. La UI vera vive nella libreria condivisa PalladiumWallet.App. -->
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ApplicationManifest>app.manifest</ApplicationManifest>
<ApplicationIcon>..\App\Assets\logo.ico</ApplicationIcon>
<AssemblyName>PalladiumWallet</AssemblyName>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Avalonia" Version="12.0.4" />
<PackageReference Include="Avalonia.Desktop" Version="12.0.4" />
<PackageReference Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.1">
<IncludeAssets Condition="'$(Configuration)' != 'Debug'">None</IncludeAssets>
<PrivateAssets Condition="'$(Configuration)' != 'Debug'">All</PrivateAssets>
</PackageReference>
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\App\PalladiumWallet.App.csproj" />
</ItemGroup>
</Project>
src/App/Program.cs → src/App.Desktop/Program.cs
View File
File renamed without changes.
src/App/app.manifest → src/App.Desktop/app.manifest
View File
File renamed without changes.
src/App/App.axaml
+13 -1
View File
@@ -8,8 +8,20 @@
<Application.DataTemplates>
<local:ViewLocator/>
</Application.DataTemplates>
<!-- Semantic design tokens (colors, radii, brand accent): defined for
both light/dark variants. See Styles/Theme.axaml. -->
<Application.Resources>
<ResourceDictionary>
<ResourceDictionary.MergedDictionaries>
<ResourceInclude Source="/Styles/Theme.axaml"/>
</ResourceDictionary.MergedDictionaries>
</ResourceDictionary>
</Application.Resources>
<Application.Styles>
<FluentTheme />
<!-- Control refinements and reusable classes (on top of Fluent) -->
<StyleInclude Source="/Styles/Controls.axaml"/>
</Application.Styles>
</Application>
src/App/App.axaml.cs
+39 -31
View File
@@ -1,31 +1,39 @@
using Avalonia;
using Avalonia.Controls.ApplicationLifetimes;
using Avalonia.Data.Core;
using Avalonia.Data.Core.Plugins;
using System.Linq;
using Avalonia.Markup.Xaml;
using PalladiumWallet.App.ViewModels;
using PalladiumWallet.App.Views;
namespace PalladiumWallet.App;
public partial class App : Application
{
public override void Initialize()
{
AvaloniaXamlLoader.Load(this);
}
public override void OnFrameworkInitializationCompleted()
{
if (ApplicationLifetime is IClassicDesktopStyleApplicationLifetime desktop)
{
desktop.MainWindow = new MainWindow
{
DataContext = new MainWindowViewModel(),
};
}
base.OnFrameworkInitializationCompleted();
}
}
using Avalonia;
using Avalonia.Controls.ApplicationLifetimes;
using Avalonia.Markup.Xaml;
using PalladiumWallet.App.ViewModels;
using PalladiumWallet.App.Views;
namespace PalladiumWallet.App;
public partial class App : Application
{
/// <summary>Set once the single ViewModel is created; lets platform heads (e.g. the
/// Android activity) reach it for lifecycle events without a second instance.</summary>
public static MainWindowViewModel? MainViewModel { get; private set; }
public override void Initialize()
{
AvaloniaXamlLoader.Load(this);
}
public override void OnFrameworkInitializationCompleted()
{
var vm = new MainWindowViewModel();
MainViewModel = vm;
// Desktop (Windows/Linux): classic window. Mobile (Android): single
// view. Same shared UI (MainView) and same ViewModel.
switch (ApplicationLifetime)
{
case IClassicDesktopStyleApplicationLifetime desktop:
desktop.MainWindow = new MainWindow { DataContext = vm };
break;
case ISingleViewApplicationLifetime singleView:
singleView.MainView = new MainView { DataContext = vm };
break;
}
base.OnFrameworkInitializationCompleted();
}
}
src/App/Assets/avalonia-logo.ico
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 172 KiB

src/App/Assets/logo.ico
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 47 KiB

src/App/Assets/logo.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 MiB

src/App/Localization/Loc.cs
+483 -122
View File
@@ -1,166 +1,527 @@
using System.Collections.Generic;
using System.ComponentModel;
namespace PalladiumWallet.App.Localization;
/// <summary>
/// Localizzazione UI (blueprint §14): dizionario chiave → [it, en], con
/// indicizzatore bindabile da XAML ({Binding Loc[chiave]}). Al cambio lingua
/// notifica "Item[]" e tutte le binding si aggiornano.
/// UI localisation: key → per-language translations dictionary, with an
/// indexer bindable from XAML ({Binding Loc[key]}). On language change the
/// ViewModel replaces the instance so Avalonia re-evaluates all bindings.
/// </summary>
public sealed class Loc : INotifyPropertyChanged
public sealed class Loc
{
public static Loc Instance { get; } = new();
public static Loc Instance { get; private set; } = new();
public static readonly string[] Languages = ["it", "en"];
public static readonly string[] LanguageNames = ["Italiano", "English"];
public static readonly string[] Languages = ["it", "en", "es", "fr", "pt", "de", "zh"];
public static readonly string[] LanguageNames = ["Italiano", "English", "Español", "Français", "Português", "Deutsch", "中文"];
public string Language { get; private set; } = "it";
public string Language { get; private set; } = "en";
public event PropertyChangedEventHandler? PropertyChanged;
private Loc() { }
private Loc(string language) { Language = language; }
public void SetLanguage(string language)
/// <summary>
/// Creates a new instance for the specified language and updates the singleton
/// used by <see cref="Tr"/>. The ViewModel assigns this instance to its Loc
/// property so Avalonia sees a different reference and re-evaluates all
/// {Binding Loc[key]} bindings.
/// </summary>
internal static Loc SwitchTo(string language)
{
if (Language == language || System.Array.IndexOf(Languages, language) < 0)
return;
Language = language;
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs("Item[]"));
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(nameof(Language)));
if (System.Array.IndexOf(Languages, language) < 0) language = "en";
var loc = new Loc(language);
Instance = loc;
return loc;
}
public string this[string key] =>
Strings.TryGetValue(key, out var values)
? values[Language == "en" ? 1 : 0]
? values[System.Math.Max(0, System.Array.IndexOf(Languages, Language))]
: key;
public static string Tr(string key) => Instance[key];
private static readonly Dictionary<string, string[]> Strings = new()
{
// Menu
["menu.file"] = ["_File", "_File"],
["menu.file.new"] = ["Nuovo / ripristina wallet…", "New / restore wallet…"],
["menu.file.open"] = ["Apri wallet da file…", "Open wallet from file…"],
["menu.file.close"] = ["Chiudi wallet", "Close wallet"],
["menu.net"] = ["_Rete", "_Network"],
["menu.net.discover"] = ["Cerca altri server (peer)", "Discover servers (peers)"],
["menu.net.resetcerts"] = ["Reset certificati SSL", "Reset SSL certificates"],
["menu.settings"] = ["_Impostazioni", "_Settings"],
["settings.unit.short"] = ["Unità", "Unit"],
// Menu it en es fr pt de zh
["menu.file"] = ["_File", "_File", "_Archivo", "_Fichier", "_Arquivo", "_Datei", "_文件"],
["menu.file.new"] = ["Nuovo / ripristina wallet…", "New / restore wallet…", "Nuevo / restaurar wallet…", "Nouveau / restaurer le wallet…", "Novo / restaurar carteira…", "Neu / Wallet wiederherstellen…", "新建/恢复钱包…"],
["menu.file.close"] = ["Chiudi wallet", "Close wallet", "Cerrar wallet", "Fermer le wallet", "Fechar carteira", "Wallet schließen", "关闭钱包"],
["menu.file.quit"] = ["Esci", "Quit", "Salir", "Quitter", "Sair", "Beenden", "退出"],
["menu.net"] = ["_Rete", "_Network", "_Red", "_Réseau", "_Rede", "_Netzwerk", "_网络"],
["menu.net.discover"] = ["Cerca altri server (peer)", "Discover servers (peers)", "Buscar otros servidores (peers)", "Rechercher d'autres serveurs (pairs)", "Procurar outros servidores (peers)", "Weitere Server suchen (Peers)", "发现服务器（节点）"],
["menu.net.resetcerts"] = ["Reset certificati SSL", "Reset SSL certificates", "Restablecer certificados SSL", "Réinitialiser les certificats SSL", "Redefinir certificados SSL", "SSL-Zertifikate zurücksetzen", "重置 SSL 证书"],
["menu.settings"] = ["_Impostazioni", "_Settings", "_Configuración", "_Paramètres", "_Configurações", "_Einstellungen", "_设置"],
["menu.help"] = ["_Help", "_Help", "_Ayuda", "_Aide", "_Ajuda", "_Hilfe", "_帮助"],
["help.title"] = ["Informazioni", "About", "Información", "À propos", "Sobre", "Über", "关于"],
["help.info"] = [
"Wallet SPV leggero e non-custodiale per la rete Palladium (PLM). Sicurezza locale: seed e chiavi sempre cifrati, mai esposti in rete.",
"Lightweight, non-custodial SPV wallet for the Palladium (PLM) network. Local security: seed and keys always encrypted, never exposed on the wire.",
"Monedero SPV ligero y sin custodia para la red Palladium (PLM). Seguridad local: semilla y claves siempre cifradas, nunca expuestas en la red.",
"Portefeuille SPV léger et non-custodial pour le réseau Palladium (PLM). Sécurité locale : graine et clés toujours chiffrées, jamais exposées sur le réseau.",
"Carteira SPV leve e não custodial para a rede Palladium (PLM). Segurança local: semente e chaves sempre cifradas, nunca expostas na rede.",
"Leichtes, nicht-verwahrendes SPV-Wallet für das Palladium (PLM)-Netzwerk. Lokale Sicherheit: Seed und Schlüssel stets verschlüsselt, nie im Netzwerk exponiert.",
"轻量级、非托管的 Palladium（PLM）网络 SPV 钱包。本地安全：种子和密钥始终加密，绝不在网络上明文传输。"],
["help.tab.info"] = ["Info", "Info", "Info", "Info", "Info", "Info", "信息"],
["help.tab.donate"] = ["Dona", "Donate", "Donar", "Faire un don", "Doar", "Spenden", "捐赠"],
["help.bug.report"] = ["Segnala un bug", "Report a bug", "Informar un error", "Signaler un bug", "Reportar um bug", "Fehler melden", "报告错误"],
["help.user.guide"] = ["Guida utente", "User guide", "Guía del usuario", "Guide utilisateur", "Guia do usuário", "Benutzerhandbuch", "用户指南"],
["update.title"] = ["Aggiornamento disponibile", "Update available", "Actualización disponible", "Mise à jour disponible", "Atualização disponível", "Update verfügbar", "有可用更新"],
["update.message"] = ["È disponibile una nuova versione:", "A new version is available:", "Hay una nueva versión disponible:", "Une nouvelle version est disponible :", "Uma nova versão está disponível:", "Eine neue Version ist verfügbar:", "有新版本可用："],
["update.download"] = ["Scarica", "Download", "Descargar", "Télécharger", "Baixar", "Herunterladen", "下载"],
["update.dismiss"] = ["Ignora", "Dismiss", "Ignorar", "Ignorer", "Ignorar", "Verwerfen", "忽略"],
["donate.desc"] = [
"Se questo wallet ti è utile, considera una piccola donazione allo sviluppatore.",
"If you find this wallet useful, consider a small donation to the developer.",
"Si esta wallet te resulta útil, considera una pequeña donación al desarrollador.",
"Si ce portefeuille vous est utile, envisagez un petit don au développeur.",
"Se esta carteira é útil para você, considere uma pequena doação ao desenvolvedor.",
"Wenn Ihnen dieses Wallet nützlich ist, erwägen Sie eine kleine Spende an den Entwickler.",
"如果您觉得这个钱包有用，请考虑向开发者捐赠一点。"],
["donate.dev.address"] = ["Indirizzo sviluppatore", "Developer address", "Dirección del desarrollador", "Adresse du développeur", "Endereço do desenvolvedor", "Entwickleradresse", "开发者地址"],
["donate.amount"] = ["Importo donazione", "Donation amount", "Monto de donación", "Montant du don", "Valor da doação", "Spendenbetrag", "捐赠金额"],
["donate.prepare"] = ["Prepara donazione", "Prepare donation", "Preparar donación", "Préparer le don", "Preparar doação", "Spende vorbereiten", "准备捐赠"],
["donate.confirm"] = ["Conferma e invia", "Confirm and send", "Confirmar y enviar", "Confirmer et envoyer", "Confirmar e enviar", "Bestätigen und senden", "确认并发送"],
["settings.unit.short"] = ["Unità", "Unit", "Unidad", "Unité", "Unidade", "Einheit", "单位"],
// Wizard
["wiz.net"] = ["Rete:", "Network:"],
["wiz.open.btn"] = ["Apri il wallet esistente", "Open existing wallet"],
["wiz.new.btn"] = ["Crea un nuovo wallet", "Create a new wallet"],
["wiz.restore.btn"] = ["Ripristina da seed", "Restore from seed"],
["wiz.open.title"] = ["Apri il wallet", "Open the wallet"],
["wiz.open.placeholder"] = ["Password del file (vuoto se non impostata)", "File password (empty if not set)"],
["wiz.open.ok"] = ["Apri", "Open"],
["wiz.seed.title"] = ["Il tuo seed (12 parole)", "Your seed (12 words)"],
["wiz.seed.warning"] = [
["wiz.data.title"] = ["Dove salvare i dati", "Where to store data", "Dónde guardar los datos", "Où enregistrer les données", "Onde salvar os dados", "Wo Daten gespeichert werden", "数据存储位置"],
["wiz.data.info"] = [
"Scegli la cartella in cui salvare wallet, configurazione e certificati. Puoi usare il percorso predefinito o sceglierne uno tuo.",
"Choose the folder where wallets, configuration and certificates are stored. Use the default path or pick your own.",
"Elige la carpeta donde se guardarán wallets, configuración y certificados. Usa la ruta predeterminada o elige la tuya.",
"Choisissez le dossier où enregistrer les wallets, la configuration et les certificats. Utilisez le chemin par défaut ou le vôtre.",
"Escolha a pasta onde salvar carteiras, configuração e certificados. Use o caminho padrão ou escolha o seu.",
"Wählen Sie den Ordner für Wallets, Konfiguration und Zertifikate. Nutzen Sie den Standardpfad oder einen eigenen.",
"选择用于存储钱包、配置和证书的文件夹。可以使用默认路径，也可以自行选择。"],
["wiz.data.default"] = ["Percorso predefinito:", "Default path:", "Ruta predeterminada:", "Chemin par défaut :", "Caminho padrão:", "Standardpfad:", "默认路径："],
["wiz.data.usedefault"] = ["Usa il percorso predefinito", "Use the default path", "Usar la ruta predeterminada", "Utiliser le chemin par défaut", "Usar o caminho padrão", "Standardpfad verwenden", "使用默认路径"],
["wiz.data.choose"] = ["Scegli una cartella…", "Choose a folder…", "Elegir una carpeta…", "Choisir un dossier…", "Escolher uma pasta…", "Ordner wählen…", "选择文件夹…"],
["wiz.choose.title"] = ["Scegli il wallet da aprire", "Choose the wallet to open", "Elige el wallet a abrir", "Choisissez le wallet à ouvrir", "Escolha a carteira a abrir", "Wallet zum Öffnen wählen", "选择要打开的钱包"],
["wiz.open.btn"] = ["Apri il wallet esistente", "Open existing wallet", "Abrir wallet existente", "Ouvrir le wallet existant", "Abrir carteira existente", "Vorhandenes Wallet öffnen", "打开现有钱包"],
["wiz.new.btn"] = ["Crea un nuovo wallet", "Create a new wallet", "Crear nuevo wallet", "Créer un nouveau wallet", "Criar nova carteira", "Neues Wallet erstellen", "创建新钱包"],
["wiz.restore.btn"] = ["Ripristina da seed", "Restore from seed", "Restaurar desde semilla", "Restaurer depuis la graine", "Restaurar da semente", "Aus Seed wiederherstellen", "从种子恢复"],
["wiz.importxkey.btn"] = ["Importa xpub / xprv", "Import xpub / xprv", "Importar xpub / xprv", "Importer xpub / xprv", "Importar xpub / xprv", "xpub / xprv importieren", "导入 xpub / xprv"],
["wiz.importwif.btn"] = ["Importa chiave WIF", "Import WIF key", "Importar clave WIF", "Importer clé WIF", "Importar chave WIF", "WIF-Schlüssel importieren", "导入 WIF 密钥"],
["wiz.importaddress.btn"] = ["Importa indirizzo (sola lettura)", "Import address (watch-only)", "Importar dirección (solo lectura)", "Importer une adresse (lecture seule)", "Importar endereço (somente leitura)", "Adresse importieren (nur lesend)", "导入地址（仅观察）"],
["wiz.open.title"] = ["Apri il wallet", "Open the wallet", "Abrir el wallet", "Ouvrir le wallet", "Abrir a carteira", "Wallet öffnen", "打开钱包"],
["wiz.open.placeholder"] = ["Password del file (vuoto se non impostata)", "File password (empty if not set)", "Contraseña del archivo (vacío si no establecida)", "Mot de passe du fichier (vide si non défini)", "Senha do arquivo (vazio se não definida)", "Dateipasswort (leer lassen, wenn nicht gesetzt)", "文件密码（未设置则留空）"],
["wiz.open.ok"] = ["Apri", "Open", "Abrir", "Ouvrir", "Abrir", "Öffnen", "打开"],
["wiz.seed.title"] = ["Il tuo seed (12 parole)", "Your seed (12 words)", "Tu semilla (12 palabras)", "Votre graine (12 mots)", "Sua semente (12 palavras)", "Ihr Seed (12 Wörter)", "您的种子（12 个单词）"],
["wiz.seed.warning"] = [
"Scrivi le parole su carta, nell'ordine. Chi le possiede controlla i fondi; se le perdi, i fondi sono irrecuperabili.",
"Write the words on paper, in order. Whoever holds them controls the funds; if you lose them, funds are unrecoverable."],
["wiz.seed.next"] = ["Le ho scritte — Avanti", "I wrote them down — Next"],
["wiz.confirm.title"] = ["Conferma il seed", "Confirm the seed"],
["wiz.confirm.placeholder"] = ["Reinserisci le 12 parole separate da spazi", "Re-enter the 12 words separated by spaces"],
["wiz.words.title"] = ["Ripristina da seed", "Restore from seed"],
["wiz.words.placeholder"] = ["Mnemonica BIP39 (12 o 24 parole separate da spazi)", "BIP39 mnemonic (12 or 24 words separated by spaces)"],
["wiz.passphrase.title"] = ["Passphrase opzionale", "Optional passphrase"],
["wiz.passphrase.placeholder"] = ["Lascia vuoto per non usarla", "Leave empty to skip"],
["wiz.password.title"] = ["Password del file wallet", "Wallet file password"],
["wiz.password.placeholder"] = ["Consigliata (vuoto = file in chiaro su disco)", "Recommended (empty = plaintext file on disk)"],
["wiz.password.create"] = ["Crea il wallet", "Create wallet"],
["wiz.back"] = ["Indietro", "Back"],
["wiz.next"] = ["Avanti", "Next"],
"Write the words on paper, in order. Whoever holds them controls the funds; if you lose them, funds are unrecoverable.",
"Escribe las palabras en papel, en orden. Quien las posea controla los fondos; si las pierdes, los fondos son irrecuperables.",
"Écrivez les mots sur papier, dans l'ordre. Celui qui les possède contrôle les fonds ; si vous les perdez, les fonds sont irrécupérables.",
"Escreva as palavras no papel, em ordem. Quem as possuir controla os fundos; se as perder, os fundos são irrecuperáveis.",
"Schreiben Sie die Wörter auf Papier, in der richtigen Reihenfolge. Wer sie besitzt, kontrolliert die Gelder; wenn Sie sie verlieren, sind die Gelder unwiederbringlich verloren.",
"请按顺序将这些单词写在纸上。持有这些单词的人即可控制资金；一旦丢失，资金将无法找回。"],
["wiz.seed.next"] = ["Le ho scritte — Avanti", "I wrote them down — Next", "Las anoté — Siguiente", "Je les ai notés — Suivant", "Eu as anotei — Próximo", "Ich habe sie notiert — Weiter", "已记录 — 下一步"],
["wiz.confirm.title"] = ["Conferma il seed", "Confirm the seed", "Confirmar la semilla", "Confirmer la graine", "Confirmar a semente", "Seed bestätigen", "确认种子"],
["wiz.confirm.placeholder"] = ["Reinserisci le 12 parole separate da spazi", "Re-enter the 12 words separated by spaces", "Reingresa las 12 palabras separadas por espacios", "Ressaisissez les 12 mots séparés par des espaces", "Reinsira as 12 palavras separadas por espaços", "12 Wörter durch Leerzeichen getrennt erneut eingeben", "重新输入以空格分隔的 12 个单词"],
["wiz.words.title"] = ["Ripristina da seed", "Restore from seed", "Restaurar desde semilla", "Restaurer depuis la graine", "Restaurar da semente", "Aus Seed wiederherstellen", "从种子恢复"],
["wiz.words.placeholder"] = ["Mnemonica BIP39 (12 o 24 parole separate da spazi)", "BIP39 mnemonic (12 or 24 words separated by spaces)", "Mnemónico BIP39 (12 o 24 palabras separadas por espacios)", "Mnémonique BIP39 (12 ou 24 mots séparés par des espaces)", "Mnemônico BIP39 (12 ou 24 palavras separadas por espaços)", "BIP39-Mnemonic (12 oder 24 durch Leerzeichen getrennte Wörter)", "BIP39 助记词（12 或 24 个单词，以空格分隔）"],
["wiz.passphrase.title"] = ["Passphrase opzionale", "Optional passphrase", "Frase de contraseña opcional", "Phrase de passe optionnelle", "Frase-senha opcional", "Optionale Passphrase", "可选密码短语"],
["wiz.passphrase.placeholder"] = ["Lascia vuoto per non usarla", "Leave empty to skip", "Deja vacío para omitir", "Laisser vide pour ignorer", "Deixe vazio para ignorar", "Leer lassen zum Überspringen", "留空以跳过"],
["wiz.name.label"] = ["Nome wallet (opzionale)", "Wallet name (optional)", "Nombre del wallet (opcional)", "Nom du wallet (optionnel)", "Nome da carteira (opcional)", "Wallet-Name (optional)", "钱包名称（可选）"],
["wiz.name.placeholder"] = ["es. risparmio, trading… (lascia vuoto per nome automatico)", "e.g. savings, trading… (leave blank for auto name)", "p.ej. ahorro, trading… (deja en blanco para nombre automático)", "ex. épargne, trading… (laisser vide pour nom automatique)", "ex. poupança, trading… (deixe em branco para nome automático)", "z.B. Sparen, Trading… (leer lassen für automatischen Namen)", "例如：储蓄、交易…（留空则自动命名）"],
["msg.wallet.exists"] = ["Esiste già un wallet con questo nome. Scegli un nome diverso.", "A wallet with this name already exists. Choose a different name.", "Ya existe un wallet con este nombre. Elige un nombre diferente.", "Un wallet avec ce nom existe déjà. Choisissez un nom différent.", "Já existe uma carteira com este nome. Escolha um nome diferente.", "Ein Wallet mit diesem Namen existiert bereits. Wähle einen anderen Namen.", "已存在同名钱包，请选择其他名称。"],
["wiz.password.title"] = ["Password del file wallet", "Wallet file password", "Contraseña del archivo wallet", "Mot de passe du fichier wallet", "Senha do arquivo da carteira", "Wallet-Dateipasswort", "钱包文件密码"],
["wiz.password.placeholder"] = ["Consigliata (vuoto = file in chiaro su disco)", "Recommended (empty = plaintext file on disk)", "Recomendada (vacío = archivo en texto claro en disco)", "Recommandé (vide = fichier en texte clair sur disque)", "Recomendada (vazio = arquivo em texto simples no disco)", "Empfohlen (leer = Klartextdatei auf Disk)", "建议设置（留空 = 文件在磁盘上以明文保存）"],
["wiz.password.create"] = ["Crea il wallet", "Create wallet", "Crear wallet", "Créer le wallet", "Criar carteira", "Wallet erstellen", "创建钱包"],
["wiz.password.confirm"] = ["Ripeti la password", "Repeat the password", "Repite la contraseña", "Répétez le mot de passe", "Repita a senha", "Passwort wiederholen", "重复密码"],
["wiz.password.encrypt"] = ["Cifra il file wallet con la password", "Encrypt the wallet file with the password", "Cifrar el archivo wallet con la contraseña", "Chiffrer le fichier wallet avec le mot de passe", "Criptografar o arquivo da carteira com a senha", "Wallet-Datei mit dem Passwort verschlüsseln", "使用密码加密钱包文件"],
["wiz.password.encrypt.hint"] = [
"Attenzione: senza cifratura il seed resta in chiaro sul disco.",
"Warning: without encryption the seed stays in plaintext on disk.",
"Atención: sin cifrado la semilla queda en texto claro en el disco.",
"Attention : sans chiffrement, la graine reste en clair sur le disque.",
"Atenção: sem criptografia a semente fica em texto simples no disco.",
"Achtung: ohne Verschlüsselung bleibt der Seed im Klartext auf der Festplatte.",
"警告：不加密的话，种子将以明文形式保存在磁盘上。"],
["wiz.back"] = ["Indietro", "Back", "Atrás", "Retour", "Voltar", "Zurück", "返回"],
["wiz.next"] = ["Avanti", "Next", "Siguiente", "Suivant", "Próximo", "Weiter", "下一步"],
["wiz.scripttype.title"] = ["Tipo di script e indirizzi", "Script type and addresses", "Tipo de script y direcciones", "Type de script et adresses", "Tipo de script e endereços", "Skripttyp und Adressen", "脚本类型和地址"],
["wiz.scripttype.hint"] = [
"Determina il formato degli indirizzi. Se non sai cosa scegliere, usa Native SegWit.",
"Determines the address format. If unsure, use Native SegWit.",
"Determina el formato de los direcciones. Si no sabes, usa Native SegWit.",
"Détermine le format des adresses. En cas de doute, utilisez Native SegWit.",
"Determina o formato dos endereços. Em caso de dúvida, use Native SegWit.",
"Bestimmt das Adressformat. Wenn Sie unsicher sind, verwenden Sie Native SegWit.",
"决定地址格式。如果不确定，请使用原生隔离见证（Native SegWit）。"],
["wiz.scripttype.legacy.desc"] = ["BIP44 · m/44'/… · indirizzi P", "BIP44 · m/44'/… · P addresses", "BIP44 · m/44'/… · direcciones P", "BIP44 · m/44'/… · adresses P", "BIP44 · m/44'/… · endereços P", "BIP44 · m/44'/… · P-Adressen", "BIP44 · m/44'/… · P 地址"],
["wiz.scripttype.wrapped.desc"] = ["BIP49 · m/49'/… · indirizzi 3", "BIP49 · m/49'/… · 3 addresses", "BIP49 · m/49'/… · direcciones 3", "BIP49 · m/49'/… · adresses 3", "BIP49 · m/49'/… · endereços 3", "BIP49 · m/49'/… · 3-Adressen", "BIP49 · m/49'/… · 3 地址"],
["wiz.scripttype.native.desc"] = ["BIP84 · m/84'/… · indirizzi plm1q — consigliato", "BIP84 · m/84'/… · plm1q addresses — recommended", "BIP84 · m/84'/… · direcciones plm1q — recomendado", "BIP84 · m/84'/… · adresses plm1q — recommandé", "BIP84 · m/84'/… · endereços plm1q — recomendado", "BIP84 · m/84'/… · plm1q-Adressen — empfohlen", "BIP84 · m/84'/… · plm1q 地址 — 推荐"],
["wiz.scripttype.taproot.desc"] = ["BIP86 · m/86'/… · indirizzi plm1p", "BIP86 · m/86'/… · plm1p addresses", "BIP86 · m/86'/… · direcciones plm1p", "BIP86 · m/86'/… · adresses plm1p", "BIP86 · m/86'/… · endereços plm1p", "BIP86 · m/86'/… · plm1p-Adressen", "BIP86 · m/86'/… · plm1p 地址"],
["wiz.importxkey.title"] = ["Importa chiave estesa", "Import extended key", "Importar clave extendida", "Importer la clé étendue", "Importar chave estendida", "Erweiterten Schlüssel importieren", "导入扩展密钥"],
["wiz.importxkey.hint"] = [
"Incolla una xpub/zpub/ypub (watch-only) o xprv/zprv/yprv (spendibile). Il tipo di script viene rilevato automaticamente.",
"Paste an xpub/zpub/ypub (watch-only) or xprv/zprv/yprv (spendable). The script type is detected automatically.",
"Pega un xpub/zpub/ypub (solo lectura) o xprv/zprv/yprv (gastable). El tipo de script se detecta automáticamente.",
"Collez un xpub/zpub/ypub (lecture seule) ou xprv/zprv/yprv (dépensable). Le type de script est détecté automatiquement.",
"Cole um xpub/zpub/ypub (somente leitura) ou xprv/zprv/yprv (gastável). O tipo de script é detectado automaticamente.",
"Fügen Sie einen xpub/zpub/ypub (nur lesend) oder xprv/zprv/yprv (ausgabefähig) ein. Der Skripttyp wird automatisch erkannt.",
"粘贴 xpub/zpub/ypub（仅观察）或 xprv/zprv/yprv（可花费）。脚本类型将自动识别。"],
["wiz.importxkey.placeholder"] = ["xpub… / zpub… / ypub… / xprv… / zprv…", "xpub… / zpub… / ypub… / xprv… / zprv…", "xpub… / zpub… / ypub… / xprv… / zprv…", "xpub… / zpub… / ypub… / xprv… / zprv…", "xpub… / zpub… / ypub… / xprv… / zprv…", "xpub… / zpub… / ypub… / xprv… / zprv…", "xpub… / zpub… / ypub… / xprv… / zprv…"],
["wiz.importwif.title"] = ["Importa chiave privata WIF", "Import WIF private key", "Importar clave privada WIF", "Importer la clé privée WIF", "Importar chave privada WIF", "WIF-Privatschlüssel importieren", "导入 WIF 私钥"],
["wiz.importwif.hint"] = [
"Incolla una o più chiavi WIF (una per riga). Puoi importare più chiavi per controllare più indirizzi con lo stesso wallet.",
"Paste one or more WIF keys (one per line). You can import multiple keys to control multiple addresses with the same wallet.",
"Pega una o más claves WIF (una por línea). Puedes importar múltiples claves para controlar múltiples direcciones con el mismo wallet.",
"Collez une ou plusieurs clés WIF (une par ligne). Vous pouvez importer plusieurs clés pour contrôler plusieurs adresses avec le même wallet.",
"Cole uma ou mais chaves WIF (uma por linha). Você pode importar várias chaves para controlar vários endereços com a mesma carteira.",
"Fügen Sie einen oder mehrere WIF-Schlüssel ein (einer pro Zeile). Sie können mehrere Schlüssel importieren, um mehrere Adressen mit demselben Wallet zu verwalten.",
"粘贴一个或多个 WIF 密钥（每行一个）。您可以导入多个密钥，用同一个钱包控制多个地址。"],
["wiz.importwif.placeholder"] = ["K… / L… / 5… (una chiave per riga)", "K… / L… / 5… (one key per line)", "K… / L… / 5… (una clave por línea)", "K… / L… / 5… (une clé par ligne)", "K… / L… / 5… (uma chave por linha)", "K… / L… / 5… (ein Schlüssel pro Zeile)", "K… / L… / 5…（每行一个密钥）"],
["wiz.importaddress.title"] = ["Importa indirizzi in sola lettura", "Import watch-only addresses", "Importar direcciones de solo lectura", "Importer des adresses en lecture seule", "Importar endereços somente leitura", "Nur-Lese-Adressen importieren", "导入仅观察地址"],
["wiz.importaddress.hint"] = [
"Incolla uno o più indirizzi (uno per riga). Nessuna chiave privata è coinvolta: potrai vedere saldo e cronologia ma non potrai mai firmare o inviare transazioni da questo wallet.",
"Paste one or more addresses (one per line). No private key is involved: you'll be able to see the balance and history but you can never sign or send transactions from this wallet.",
"Pega una o más direcciones (una por línea). No hay ninguna clave privada involucrada: podrás ver el saldo y el historial, pero nunca podrás firmar ni enviar transacciones desde este wallet.",
"Collez une ou plusieurs adresses (une par ligne). Aucune clé privée n'est impliquée : vous pourrez voir le solde et l'historique, mais vous ne pourrez jamais signer ni envoyer de transactions depuis ce wallet.",
"Cole um ou mais endereços (um por linha). Nenhuma chave privada está envolvida: você poderá ver o saldo e o histórico, mas nunca poderá assinar ou enviar transações a partir desta carteira.",
"Fügen Sie eine oder mehrere Adressen ein (eine pro Zeile). Es ist kein privater Schlüssel beteiligt: Sie können den Kontostand und den Verlauf sehen, aber nie Transaktionen aus diesem Wallet signieren oder senden.",
"粘贴一个或多个地址（每行一个）。不涉及任何私钥：您可以查看余额和历史记录，但永远无法从此钱包签名或发送交易。"],
["wiz.importaddress.placeholder"] = ["Indirizzo… (uno per riga)", "Address… (one per line)", "Dirección… (una por línea)", "Adresse… (une par ligne)", "Endereço… (um por linha)", "Adresse… (eine pro Zeile)", "地址…（每行一个）"],
// Pannello wallet
["wallet.close"] = ["Chiudi wallet", "Close wallet"],
["wallet.server"] = ["Server:", "Server:"],
["wallet.connect"] = ["Connetti e sincronizza", "Connect and sync"],
["wallet.manual"] = ["oppure host:porta manuale", "or manual host:port"],
["wallet.discover"] = ["Cerca altri server", "Discover servers"],
["wallet.resetcert"] = ["Reset cert.", "Reset certs"],
["tab.receive"] = ["Ricevi", "Receive"],
["tab.history"] = ["Storico", "History"],
["tab.addresses"] = ["Indirizzi", "Addresses"],
["tab.send"] = ["Invia", "Send"],
["receive.next"] = ["Prossimo indirizzo non usato:", "Next unused address:"],
["receive.hint"] = [
// Import error messages
["msg.xkey.required"] = ["Incolla una chiave estesa (xpub/xprv o variante).", "Paste an extended key (xpub/xprv or variant).", "Pega una clave extendida (xpub/xprv o variante).", "Collez une clé étendue (xpub/xprv ou variante).", "Cole uma chave estendida (xpub/xprv ou variante).", "Fügen Sie einen erweiterten Schlüssel ein (xpub/xprv oder Variante).", "请粘贴扩展密钥（xpub/xprv 或其变体）。"],
["msg.xkey.invalid"] = ["Chiave estesa non riconosciuta per questa rete.", "Extended key not recognised for this network.", "Clave extendida no reconocida para esta red.", "Clé étendue non reconnue pour ce réseau.", "Chave estendida não reconhecida para esta rede.", "Erweiterter Schlüssel für dieses Netzwerk nicht erkannt.", "此网络无法识别该扩展密钥。"],
["msg.wif.required"] = ["Incolla almeno una chiave WIF.", "Paste at least one WIF key.", "Pega al menos una clave WIF.", "Collez au moins une clé WIF.", "Cole pelo menos uma chave WIF.", "Fügen Sie mindestens einen WIF-Schlüssel ein.", "请至少粘贴一个 WIF 密钥。"],
["msg.wif.invalid"] = ["Chiave WIF non valida per questa rete.", "WIF key not valid for this network.", "Clave WIF no válida para esta red.", "Clé WIF invalide pour ce réseau.", "Chave WIF inválida para esta rede.", "WIF-Schlüssel für dieses Netzwerk ungültig.", "该 WIF 密钥对此网络无效。"],
["msg.address.required"] = ["Incolla almeno un indirizzo.", "Paste at least one address.", "Pega al menos una dirección.", "Collez au moins une adresse.", "Cole pelo menos um endereço.", "Fügen Sie mindestens eine Adresse ein.", "请至少粘贴一个地址。"],
["msg.address.invalid"] = ["Indirizzo non valido per questa rete.", "Address not valid for this network.", "Dirección no válida para esta red.", "Adresse invalide pour ce réseau.", "Endereço inválido para esta rede.", "Adresse für dieses Netzwerk ungültig.", "该地址对此网络无效。"],
// Wallet panel
["wallet.close"] = ["Chiudi wallet", "Close wallet", "Cerrar wallet", "Fermer le wallet", "Fechar carteira", "Wallet schließen", "关闭钱包"],
["wallet.server"] = ["Server:", "Server:", "Servidor:", "Serveur :", "Servidor:", "Server:", "服务器："],
["wallet.connect"] = ["Connetti", "Connect", "Conectar", "Connecter", "Conectar", "Verbinden", "连接"],
["wallet.manual"] = ["oppure host:porta manuale", "or manual host:port", "o host:puerto manual", "ou hôte:port manuel", "ou host:porta manual", "oder manuell host:port", "或手动输入 host:port"],
["wallet.discover"] = ["Sincronizza", "Sync servers", "Sincronizar", "Synchroniser", "Sincronizar", "Synchronisieren", "同步服务器"],
["wallet.resetcert"] = ["Reset cert.", "Reset certs", "Restablecer cert.", "Réinit. cert.", "Redefinir cert.", "Zert. zurücksetzen", "重置证书"],
["tab.receive"] = ["Ricevi", "Receive", "Recibir", "Recevoir", "Receber", "Empfangen", "接收"],
["tab.history"] = ["Storico", "History", "Historial", "Historique", "Histórico", "Verlauf", "历史"],
["tab.addresses"] = ["Indirizzi", "Addresses", "Direcciones", "Adresses", "Endereços", "Adressen", "地址"],
["tab.send"] = ["Invia", "Send", "Enviar", "Envoyer", "Enviar", "Senden", "发送"],
["tab.contacts"] = ["Contatti", "Contacts", "Contactos", "Contacts", "Contatos", "Kontakte", "联系人"],
["receive.next"] = ["Prossimo indirizzo non usato:", "Next unused address:", "Próxima dirección no usada:", "Prochaine adresse non utilisée :", "Próximo endereço não usado:", "Nächste ungenutzte Adresse:", "下一个未使用地址："],
["receive.copy"] = ["Copia", "Copy", "Copiar", "Copier", "Copiar", "Kopieren", "复制"],
["receive.hint"] = [
"Ogni pagamento ricevuto qui comparirà nello storico alla prossima sincronizzazione.",
"Payments received here will appear in the history at the next synchronization."],
["addr.type"] = ["Tipo", "Type"],
["addr.index"] = ["Indice", "Index"],
["addr.address"] = ["Indirizzo", "Address"],
["addr.balance"] = ["Saldo", "Balance"],
["addr.receive"] = ["ricezione", "receive"],
["addr.change"] = ["change", "change"],
["send.to"] = ["Indirizzo destinatario", "Recipient address"],
["send.amount"] = ["Importo", "Amount"],
["send.all"] = ["Invia tutto", "Send all"],
["send.feerate"] = ["fee sat/vB:", "fee sat/vB:"],
["send.prepare"] = ["Prepara transazione", "Prepare transaction"],
["send.confirm"] = ["CONFERMA E TRASMETTI", "CONFIRM AND BROADCAST"],
"Payments received here will appear in the history at the next synchronization.",
"Los pagos recibidos aquí aparecerán en el historial en la próxima sincronización.",
"Les paiements reçus ici apparaîtront dans l'historique à la prochaine synchronisation.",
"Os pagamentos recebidos aqui aparecerão no histórico na próxima sincronização.",
"Hier empfangene Zahlungen erscheinen beim nächsten Synchronisieren im Verlauf.",
"在此收到的付款将在下次同步时出现在历史记录中。"],
["addr.type"] = ["Tipo", "Type", "Tipo", "Type", "Tipo", "Typ", "类型"],
["addr.index"] = ["Indice", "Index", "Índice", "Index", "Índice", "Index", "索引"],
["addr.address"] = ["Indirizzo", "Address", "Dirección", "Adresse", "Endereço", "Adresse", "地址"],
["addr.balance"] = ["Saldo", "Balance", "Saldo", "Solde", "Saldo", "Saldo", "余额"],
["addr.copied"] = ["Indirizzo copiato negli appunti", "Address copied to clipboard", "Dirección copiada al portapapeles", "Adresse copiée dans le presse-papiers", "Endereço copiado para a área de transferência", "Adresse in die Zwischenablage kopiert", "地址已复制到剪贴板"],
["addr.derivpath"] = ["Percorso di derivazione:", "Derivation path:", "Ruta de derivación:", "Chemin de dérivation :", "Caminho de derivação:", "Ableitungspfad:", "派生路径："],
["addr.pubkey"] = ["Chiave pubblica:", "Public key:", "Clave pública:", "Clé publique :", "Chave pública:", "Öffentlicher Schlüssel:", "公钥："],
["addr.privkey"] = ["Chiave privata (WIF):", "Private key (WIF):", "Clave privada (WIF):", "Clé privée (WIF) :", "Chave privada (WIF):", "Privater Schlüssel (WIF):", "私钥（WIF）："],
["addr.show.privkey"] = ["Mostra", "Show", "Mostrar", "Afficher", "Mostrar", "Anzeigen", "显示"],
["addr.privkey.prompt.title"] = ["Conferma identità", "Confirm identity", "Confirmar identidad", "Confirmer l'identité", "Confirmar identidade", "Identität bestätigen", "确认身份"],
["addr.privkey.prompt.desc"] = ["Inserisci la password del wallet per visualizzare la chiave privata.", "Enter the wallet password to reveal the private key.", "Ingresa la contraseña del wallet para ver la clave privada.", "Entrez le mot de passe du wallet pour afficher la clé privée.", "Digite a senha da carteira para ver a chave privada.", "Geben Sie das Wallet-Passwort ein, um den privaten Schlüssel anzuzeigen.", "输入钱包密码以显示私钥。"],
["addr.hide.privkey"] = ["Nascondi", "Hide", "Ocultar", "Masquer", "Ocultar", "Ausblenden", "隐藏"],
["addr.receive"] = ["ricezione", "receive", "recepción", "réception", "recebimento", "Empfang", "接收"],
["addr.change"] = ["change", "change", "cambio", "monnaie", "troco", "Wechselgeld", "找零"],
["addr.info.title"] = ["Informazioni indirizzo", "Address information", "Información de dirección", "Informations sur l'adresse", "Informações do endereço", "Adressinformationen", "地址信息"],
["addr.close"] = ["Chiudi", "Close", "Cerrar", "Fermer", "Fechar", "Schließen", "关闭"],
// Stato connessione
["conn.none"] = ["non connesso", "not connected"],
["conn.disconnected"] = ["disconnesso", "disconnected"],
["conn.reconnecting"] = ["riconnessione…", "reconnecting…"],
["conn.error"] = ["errore di connessione", "connection error"],
["conn.certchanged"] = ["certificato cambiato", "certificate changed"],
["conn.connectedto"] = ["connesso a", "connected to"],
["conn.connectingto"] = ["connessione a", "connecting to"],
// History → transaction detail
["history.hint"] = ["Doppio click su una transazione per i dettagli.", "Double-click a transaction for details.", "Doble clic en una transacción para ver los detalles.", "Double-cliquez sur une transaction pour les détails.", "Clique duplo numa transação para ver os detalhes.", "Doppelklick auf eine Transaktion für Details.", "双击某笔交易可查看详情。"],
["tx.title"] = ["Dettagli transazione", "Transaction details", "Detalles de la transacción", "Détails de la transaction", "Detalhes da transação", "Transaktionsdetails", "交易详情"],
["tx.close"] = ["Chiudi", "Close", "Cerrar", "Fermer", "Fechar", "Schließen", "关闭"],
["tx.loading"] = ["Carico i dati della transazione dal server…", "Loading transaction data from the server…", "Cargando los datos de la transacción desde el servidor…", "Chargement des données de la transaction depuis le serveur…", "Carregando os dados da transação do servidor…", "Lade Transaktionsdaten vom Server…", "正在从服务器加载交易数据…"],
["tx.status"] = ["Stato", "Status", "Estado", "Statut", "Estado", "Status", "状态"],
["tx.status.mempool"] = ["0 conferme · in mempool", "0 confirmations · in mempool", "0 confirmaciones · en mempool", "0 confirmation · dans le mempool", "0 confirmações · no mempool", "0 Bestätigungen · im Mempool", "0 次确认 · 在内存池中"],
["tx.status.confirmations"] = ["conferme", "confirmations", "confirmaciones", "confirmations", "confirmações", "Bestätigungen", "次确认"],
["tx.status.block"] = ["blocco", "block", "bloque", "bloc", "bloco", "Block", "区块"],
["tx.mempool"] = ["in mempool", "in mempool", "en mempool", "dans le mempool", "no mempool", "im Mempool", "在内存池中"],
["tx.date"] = ["Data", "Date", "Fecha", "Date", "Data", "Datum", "日期"],
["tx.to"] = ["A", "To", "Para", "À", "Para", "An", "至"],
["tx.from"] = ["Da", "From", "De", "De", "De", "Von", "来自"],
["tx.debit"] = ["Debito", "Debit", "Débito", "Débit", "Débito", "Soll", "支出"],
["tx.credit"] = ["Credito", "Credit", "Crédito", "Crédit", "Crédito", "Haben", "收入"],
["tx.fee"] = ["Fee transazione", "Transaction fee", "Comisión de transacción", "Frais de transaction", "Taxa da transação", "Transaktionsgebühr", "交易手续费"],
["tx.feerate"] = ["Fee per vByte", "Fee per vByte", "Comisión por vByte", "Frais par vOctet", "Taxa por vByte", "Gebühr pro vByte", "每虚拟字节手续费"],
["tx.net"] = ["Importo netto", "Net amount", "Importe neto", "Montant net", "Valor líquido", "Nettobetrag", "净额"],
["tx.id"] = ["ID transazione", "Transaction ID", "ID de transacción", "ID de transaction", "ID da transação", "Transaktions-ID", "交易 ID"],
["tx.size.total"] = ["Dimensione totale", "Total size", "Tamaño total", "Taille totale", "Tamanho total", "Gesamtgröße", "总大小"],
["tx.size.virtual"] = ["Dimensione virtuale", "Virtual size", "Tamaño virtual", "Taille virtuelle", "Tamanho virtual", "Virtuelle Größe", "虚拟大小"],
["tx.rbf"] = ["Sostituibile (RBF)", "Replaceable (RBF)", "Reemplazable (RBF)", "Remplaçable (RBF)", "Substituível (RBF)", "Ersetzbar (RBF)", "可替换（RBF）"],
["tx.inputs"] = ["Input", "Inputs", "Entradas", "Entrées", "Entradas", "Eingänge", "输入"],
["tx.outputs"] = ["Output", "Outputs", "Salidas", "Sorties", "Saídas", "Ausgänge", "输出"],
["tx.yes"] = ["Sì", "Yes", "Sí", "Oui", "Sim", "Ja", "是"],
["tx.no"] = ["No", "No", "No", "Non", "Não", "Nein", "否"],
["tx.needconnection"] = ["Connettiti al server per vedere i dettagli della transazione.", "Connect to the server to view transaction details.", "Conéctate al servidor para ver los detalles de la transacción.", "Connectez-vous au serveur pour voir les détails de la transaction.", "Conecte-se ao servidor para ver os detalhes da transação.", "Mit dem Server verbinden, um die Transaktionsdetails zu sehen.", "连接服务器以查看交易详情。"],
["tx.sect.overview"] = ["Panoramica", "Overview", "Resumen", "Aperçu", "Visão geral", "Übersicht", "概览"],
["tx.sect.amounts"] = ["Importi e commissioni", "Amounts & fees", "Importes y comisiones", "Montants et frais", "Valores e taxas", "Beträge & Gebühren", "金额与手续费"],
["tx.sect.tech"] = ["Dettagli tecnici", "Technical details", "Detalles técnicos", "Détails techniques", "Detalhes técnicos", "Technische Details", "技术详情"],
["tx.coinbase"] = ["Coinbase", "Coinbase", "Coinbase", "Coinbase", "Coinbase", "Coinbase", "创币交易"],
["tx.coinbase.newcoins"] = ["Nuova emissione (mining)", "Newly generated (mining)", "Nueva emisión (minería)", "Nouvelle émission (minage)", "Nova emissão (mineração)", "Neu erzeugt (Mining)", "新生成（挖矿）"],
["send.from.contact"] = ["Da contatti:", "From contacts:", "De contactos:", "Depuis les contacts :", "De contatos:", "Aus Kontakten:", "来自联系人："],
["send.contact.hint"] = ["seleziona per riempire l'indirizzo", "select to fill address", "selecciona para rellenar la dirección", "sélectionner pour remplir l'adresse", "selecione para preencher o endereço", "auswählen um Adresse einzufügen", "选择以填充地址"],
["send.to"] = ["Indirizzo destinatario", "Recipient address", "Dirección destinataria", "Adresse du destinataire", "Endereço do destinatário", "Empfängeradresse", "收款地址"],
["send.amount"] = ["Importo", "Amount", "Importe", "Montant", "Valor", "Betrag", "金额"],
["send.all"] = ["Invia tutto", "Send all", "Enviar todo", "Tout envoyer", "Enviar tudo", "Alles senden", "全部发送"],
["send.feerate"] = ["fee sat/vB:", "fee sat/vB:", "tarifa sat/vB:", "frais sat/vB :", "taxa sat/vB:", "Gebühr sat/vB:", "手续费 sat/vB："],
["send.prepare"] = ["Prepara transazione", "Prepare transaction", "Preparar transacción", "Préparer la transaction", "Preparar transação", "Transaktion vorbereiten", "准备交易"],
["send.scan"] = ["Scansiona QR", "Scan QR", "Escanear QR", "Scanner QR", "Escanear QR", "QR scannen", "扫描二维码"],
["send.confirm"] = ["CONFERMA E TRASMETTI", "CONFIRM AND BROADCAST", "CONFIRMAR Y TRANSMITIR", "CONFIRMER ET DIFFUSER", "CONFIRMAR E TRANSMITIR", "BESTÄTIGEN UND SENDEN", "确认并广播"],
["send.sect.recipient"] = ["Destinatario", "Recipient", "Destinatario", "Destinataire", "Destinatário", "Empfänger", "收款人"],
["send.sect.amount"] = ["Importo e commissione", "Amount & fee", "Importe y comisión", "Montant et frais", "Valor e taxa", "Betrag & Gebühr", "金额与手续费"],
["send.summary"] = ["Riepilogo", "Summary", "Resumen", "Résumé", "Resumo", "Zusammenfassung", "摘要"],
["send.psbt.label"] = ["PSBT non firmata (base64) — da firmare altrove", "Unsigned PSBT (base64) — sign it elsewhere", "PSBT sin firmar (base64) — fírmala en otro lugar", "PSBT non signée (base64) — à signer ailleurs", "PSBT não assinada (base64) — assine em outro lugar", "Unsignierte PSBT (base64) — anderswo signieren", "未签名 PSBT（base64）— 请在别处签名"],
["send.psbt.copy"] = ["Copia PSBT", "Copy PSBT", "Copiar PSBT", "Copier la PSBT", "Copiar PSBT", "PSBT kopieren", "复制 PSBT"],
["send.watchonly.hint"] = ["Wallet in sola lettura: non può firmare. Esporta la PSBT e firmala con un wallet che possiede le chiavi.", "Watch-only wallet: it cannot sign. Export the PSBT and sign it with a wallet that holds the keys.", "Wallet de solo lectura: no puede firmar. Exporta la PSBT y fírmala con un wallet que tenga las claves.", "Wallet en lecture seule : il ne peut pas signer. Exportez la PSBT et signez-la avec un wallet possédant les clés.", "Carteira somente leitura: não pode assinar. Exporte a PSBT e assine-a com uma carteira que tenha as chaves.", "Nur-Lese-Wallet: kann nicht signieren. Exportieren Sie die PSBT und signieren Sie sie mit einem Wallet, das die Schlüssel besitzt.", "仅观察钱包：无法签名。请导出 PSBT 并用持有密钥的钱包签名。"],
["psbt.copied"] = ["PSBT copiata negli appunti", "PSBT copied to clipboard", "PSBT copiada al portapapeles", "PSBT copiée dans le presse-papiers", "PSBT copiada para a área de transferência", "PSBT in die Zwischenablage kopiert", "PSBT 已复制到剪贴板"],
["receive.your.address"] = ["Il tuo indirizzo", "Your address", "Tu dirección", "Votre adresse", "Seu endereço", "Deine Adresse", "您的地址"],
// Messaggi di stato principali
["msg.welcome.existing"] = [
// Wallet info overlay
["menu.wallet"] = ["_Wallet", "_Wallet", "_Wallet", "_Wallet", "_Wallet", "_Wallet", "_钱包"],
["walletinfo.title"] = ["Informazioni Wallet", "Wallet Information", "Información del Wallet", "Informations Wallet", "Informações da Carteira", "Wallet-Informationen", "钱包信息"],
["walletinfo.file"] = ["File", "File", "Archivo", "Fichier", "Arquivo", "Datei", "文件"],
["walletinfo.network"] = ["Rete", "Network", "Red", "Réseau", "Rede", "Netzwerk", "网络"],
["walletinfo.type"] = ["Tipo wallet", "Wallet type", "Tipo de wallet", "Type de wallet", "Tipo de carteira", "Wallet-Typ", "钱包类型"],
["walletinfo.type.seed"] = ["HD (seed BIP39)", "HD (BIP39 seed)", "HD (seed BIP39)", "HD (graine BIP39)", "HD (semente BIP39)", "HD (BIP39-Seed)", "HD（BIP39 种子）"],
["walletinfo.type.xprv"] = ["HD (xprv importato)", "HD (imported xprv)", "HD (xprv importado)", "HD (xprv importé)", "HD (xprv importado)", "HD (importierter xprv)", "HD（已导入 xprv）"],
["walletinfo.type.wif"] = ["Chiave WIF importata", "Imported WIF key", "Clave WIF importada", "Clé WIF importée", "Chave WIF importada", "Importierter WIF-Schlüssel", "已导入 WIF 密钥"],
["walletinfo.type.watchonly"] = ["Watch-only (xpub)", "Watch-only (xpub)", "Watch-only (xpub)", "Watch-only (xpub)", "Watch-only (xpub)", "Watch-only (xpub)", "仅观察（xpub）"],
["walletinfo.script"] = ["Script", "Script", "Script", "Script", "Script", "Script", "脚本"],
["walletinfo.derivpath"] = ["Percorso derivazione", "Derivation path", "Ruta de derivación", "Chemin de dérivation", "Caminho de derivação", "Ableitungspfad", "派生路径"],
["walletinfo.xpub"] = ["Chiave pubblica estesa", "Extended public key", "Clave pública extendida", "Clé publique étendue", "Chave pública estendida", "Erweiterter öffentlicher Schlüssel", "扩展公钥"],
["walletinfo.fingerprint"] = ["Master fingerprint", "Master fingerprint", "Huella maestra", "Empreinte maître", "Impressão digital mestre", "Master-Fingerprint", "主指纹"],
["walletinfo.seed.section"] = ["Seed (mnemonica BIP39)", "Seed (BIP39 mnemonic)", "Semilla (mnemónico BIP39)", "Graine (mnémonique BIP39)", "Semente (mnemônico BIP39)", "Seed (BIP39-Mnemonic)", "种子（BIP39 助记词）"],
["walletinfo.seed.noseed"] = ["Questo wallet non ha una seed (watch-only o importato).", "This wallet has no seed (watch-only or imported).", "Este wallet no tiene seed (watch-only o importado).", "Ce wallet n'a pas de graine (watch-only ou importé).", "Esta carteira não tem semente (watch-only ou importada).", "Dieses Wallet hat keinen Seed (watch-only oder importiert).", "此钱包没有种子（仅观察或已导入）。"],
["walletinfo.seed.password"] = ["Password del file wallet per sbloccare il seed:", "Wallet file password to unlock the seed:", "Contraseña del archivo para desbloquear la seed:", "Mot de passe du fichier pour déverrouiller la graine :", "Senha do arquivo para desbloquear a semente:", "Dateipasswort zum Entsperren des Seeds:", "输入钱包文件密码以解锁种子："],
["walletinfo.seed.reveal"] = ["Mostra seed", "Show seed", "Mostrar seed", "Afficher la graine", "Mostrar semente", "Seed anzeigen", "显示种子"],
["walletinfo.seed.hide"] = ["Nascondi", "Hide", "Ocultar", "Masquer", "Ocultar", "Ausblenden", "隐藏"],
["walletinfo.seed.warning"] = [
"Non condividere mai queste parole. Chi le possiede controlla i fondi.",
"Never share these words. Whoever holds them controls the funds.",
"Nunca compartas estas palabras. Quien las tenga controla los fondos.",
"Ne partagez jamais ces mots. Celui qui les possède contrôle les fonds.",
"Nunca compartilhe essas palavras. Quem as tiver controla os fundos.",
"Teilen Sie diese Wörter niemals. Wer sie hat, kontrolliert die Gelder.",
"切勿分享这些单词。持有者即可控制资金。"],
["walletinfo.passphrase"] = ["Passphrase BIP39", "BIP39 passphrase", "Frase de contraseña BIP39", "Phrase de passe BIP39", "Frase-senha BIP39", "BIP39-Passphrase", "BIP39 密码短语"],
["walletinfo.passphrase.set"] = ["(impostata)", "(set)", "(establecida)", "(définie)", "(definida)", "(gesetzt)", "（已设置）"],
// Connection status
["conn.none"] = ["non connesso", "not connected", "no conectado", "non connecté", "não conectado", "nicht verbunden", "未连接"],
["conn.disconnected"] = ["disconnesso", "disconnected", "desconectado", "déconnecté", "desconectado", "getrennt", "已断开"],
["conn.reconnecting"] = ["riconnessione…", "reconnecting…", "reconectando…", "reconnexion…", "reconectando…", "Verbindung wird wiederhergestellt…", "正在重新连接…"],
["conn.error"] = ["errore di connessione", "connection error", "error de conexión", "erreur de connexion", "erro de conexão", "Verbindungsfehler", "连接错误"],
["conn.certchanged"] = ["certificato cambiato", "certificate changed", "certificado cambiado", "certificat modifié", "certificado alterado", "Zertifikat geändert", "证书已更改"],
["conn.connectedto"] = ["connesso", "connected", "conectado", "connecté", "conectado", "verbunden", "已连接"],
["conn.connectingto"] = ["connessione a", "connecting to", "conectando a", "connexion à", "conectando a", "Verbindung zu", "正在连接"],
// Main status messages
["msg.welcome.existing"] = [
"Trovato un wallet esistente su questa rete: aprilo, oppure creane un altro.",
"Found an existing wallet on this network: open it, or create another one."],
["msg.welcome.new"] = [
"Found an existing wallet on this network: open it, or create another one.",
"Se encontró un wallet existente en esta red: ábrelo o crea otro.",
"Un wallet existant a été trouvé sur ce réseau : ouvrez-le ou créez-en un autre.",
"Uma carteira existente foi encontrada nesta rede: abra-a ou crie outra.",
"Ein vorhandenes Wallet wurde in diesem Netzwerk gefunden: öffnen Sie es oder erstellen Sie ein neues.",
"在此网络上发现现有钱包：打开它，或创建新钱包。"],
["msg.welcome.new"] = [
"Benvenuto: crea un nuovo wallet o ripristina da seed.",
"Welcome: create a new wallet or restore from seed."],
["msg.open.password"] = [
"Welcome: create a new wallet or restore from seed.",
"Bienvenido: crea un nuevo wallet o restaura desde semilla.",
"Bienvenue : créez un nouveau wallet ou restaurez depuis une graine.",
"Bem-vindo: crie uma nova carteira ou restaure da semente.",
"Willkommen: erstellen Sie ein neues Wallet oder stellen Sie es aus einem Seed wieder her.",
"欢迎：创建新钱包或从种子恢复。"],
["msg.open.password"] = [
"Inserisci la password del file (lascia vuoto se non impostata).",
"Enter the file password (leave empty if not set)."],
["msg.seed.write"] = [
"Enter the file password (leave empty if not set).",
"Ingresa la contraseña del archivo (deja vacío si no establecida).",
"Entrez le mot de passe du fichier (laisser vide si non défini).",
"Digite a senha do arquivo (deixe vazio se não definida).",
"Geben Sie das Dateipasswort ein (leer lassen, wenn nicht gesetzt).",
"输入文件密码（未设置则留空）。"],
["msg.seed.write"] = [
"Scrivi le 12 parole SU CARTA, nell'ordine. Sono l'unico backup del wallet.",
"Write the 12 words ON PAPER, in order. They are the only backup of the wallet."],
["msg.seed.retype"] = [
"Write the 12 words ON PAPER, in order. They are the only backup of the wallet.",
"Escribe las 12 palabras EN PAPEL, en orden. Son la única copia de seguridad del wallet.",
"Écrivez les 12 mots SUR PAPIER, dans l'ordre. C'est la seule sauvegarde du wallet.",
"Escreva as 12 palavras NO PAPEL, em ordem. São o único backup da carteira.",
"Schreiben Sie die 12 Wörter AUF PAPIER, in der richtigen Reihenfolge. Sie sind die einzige Sicherung des Wallets.",
"请将这 12 个单词按顺序写在纸上。它们是钱包唯一的备份。"],
["msg.seed.retype"] = [
"Reinserisci le 12 parole per confermare di averle scritte.",
"Re-enter the 12 words to confirm you wrote them down."],
["msg.seed.mismatch"] = [
"Re-enter the 12 words to confirm you wrote them down.",
"Reingresa las 12 palabras para confirmar que las has anotado.",
"Ressaisissez les 12 mots pour confirmer que vous les avez notés.",
"Reinsira as 12 palavras para confirmar que as anotou.",
"Geben Sie die 12 Wörter erneut ein, um zu bestätigen, dass Sie sie notiert haben.",
"重新输入这 12 个单词，以确认您已记录。"],
["msg.seed.mismatch"] = [
"Le parole non corrispondono: ricontrolla quello che hai scritto su carta.",
"The words do not match: check what you wrote on paper."],
["msg.words.enter"] = [
"The words do not match: check what you wrote on paper.",
"Las palabras no coinciden: revisa lo que escribiste en papel.",
"Les mots ne correspondent pas : vérifiez ce que vous avez écrit sur papier.",
"As palavras não correspondem: verifique o que escreveu no papel.",
"Die Wörter stimmen nicht überein: überprüfen Sie, was Sie auf Papier geschrieben haben.",
"单词不匹配：请检查您写在纸上的内容。"],
["msg.words.enter"] = [
"Inserisci la mnemonica BIP39 (12 o 24 parole separate da spazi).",
"Enter the BIP39 mnemonic (12 or 24 words separated by spaces)."],
["msg.words.invalid"] = [
"Enter the BIP39 mnemonic (12 or 24 words separated by spaces).",
"Ingresa el mnemónico BIP39 (12 o 24 palabras separadas por espacios).",
"Entrez le mnémonique BIP39 (12 ou 24 mots séparés par des espaces).",
"Insira o mnemônico BIP39 (12 ou 24 palavras separadas por espaços).",
"Geben Sie die BIP39-Mnemonic ein (12 oder 24 durch Leerzeichen getrennte Wörter).",
"输入 BIP39 助记词（12 或 24 个单词，以空格分隔）。"],
["msg.words.invalid"] = [
"Mnemonica non valida (parole o checksum errati): ricontrolla.",
"Invalid mnemonic (wrong words or checksum): check again."],
["msg.passphrase.info"] = [
"Invalid mnemonic (wrong words or checksum): check again.",
"Mnemónico no válido (palabras o checksum incorrectos): verifica de nuevo.",
"Mnémonique invalide (mots ou checksum incorrects) : vérifiez à nouveau.",
"Mnemônico inválido (palavras ou checksum incorretos): verifique novamente.",
"Ungültige Mnemonic (falsche Wörter oder Prüfsumme): bitte erneut prüfen.",
"助记词无效（单词错误或校验和不正确）：请重新检查。"],
["msg.passphrase.info"] = [
"Passphrase BIP39 opzionale: cambia completamente il wallet. Se la usi, annotala A PARTE dal seed; se la perdi i fondi sono irrecuperabili. Lascia vuoto per non usarla.",
"Optional BIP39 passphrase: it derives a completely different wallet. If you use it, note it SEPARATELY from the seed; if lost, funds are unrecoverable. Leave empty to skip."],
["msg.password.info"] = [
"Optional BIP39 passphrase: it derives a completely different wallet. If you use it, note it SEPARATELY from the seed; if lost, funds are unrecoverable. Leave empty to skip.",
"Frase de contraseña BIP39 opcional: deriva un wallet completamente diferente. Si la usas, anótala SEPARADA de la semilla; si la pierdes, los fondos son irrecuperables. Deja vacío para omitir.",
"Phrase de passe BIP39 optionnelle : elle dérive un wallet complètement différent. Si vous l'utilisez, notez-la SÉPARÉMENT de la graine ; si vous la perdez, les fonds sont irrécupérables. Laisser vide pour ignorer.",
"Frase-senha BIP39 opcional: deriva uma carteira completamente diferente. Se a usar, anote-a SEPARADAMENTE da semente; se a perder, os fundos são irrecuperáveis. Deixe vazio para ignorar.",
"Optionale BIP39-Passphrase: leitet ein völlig anderes Wallet ab. Falls verwendet, GETRENNT vom Seed notieren; falls verloren, sind die Gelder unwiederbringlich. Leer lassen zum Überspringen.",
"可选的 BIP39 密码短语：它会派生出一个完全不同的钱包。如果使用，请与种子分开记录；一旦丢失，资金将无法找回。留空以跳过。"],
["msg.password.info"] = [
"Password di cifratura del file wallet su disco (consigliata). Non sostituisce il seed: serve solo a proteggere il file.",
"Encryption password for the wallet file on disk (recommended). It does not replace the seed: it only protects the file."],
["msg.wrongpassword"] = ["Password errata.", "Wrong password."],
["msg.opened"] = ["Wallet aperto: connessione al server…", "Wallet opened: connecting to server…"],
["msg.synced"] = ["Sincronizzato", "Synchronized"],
["msg.synced.detail"] = [
"Encryption password for the wallet file on disk (recommended). It does not replace the seed: it only protects the file.",
"Contraseña de cifrado para el archivo wallet en disco (recomendada). No reemplaza la semilla: solo protege el archivo.",
"Mot de passe de chiffrement pour le fichier wallet sur disque (recommandé). Ne remplace pas la graine : protège uniquement le fichier.",
"Senha de criptografia para o arquivo da carteira no disco (recomendada). Não substitui a semente: apenas protege o arquivo.",
"Verschlüsselungspasswort für die Wallet-Datei auf der Festplatte (empfohlen). Ersetzt nicht den Seed: schützt nur die Datei.",
"用于加密磁盘上钱包文件的密码（建议设置）。它不能替代种子，仅用于保护文件。"],
["msg.choose.wallet"] = ["Più wallet disponibili: scegline uno.", "Multiple wallets available: pick one.", "Varios wallets disponibles: elige uno.", "Plusieurs wallets disponibles : choisissez-en un.", "Várias carteiras disponíveis: escolha uma.", "Mehrere Wallets verfügbar: wählen Sie eines.", "有多个可用钱包：请选择一个。"],
["msg.password.required"] = [
"Inserisci una password per cifrare il wallet (o togli la spunta «Cifra il file wallet»).",
"Enter a password to encrypt the wallet (or uncheck “Encrypt the wallet file”).",
"Ingresa una contraseña para cifrar el wallet (o desmarca «Cifrar el archivo wallet»).",
"Entrez un mot de passe pour chiffrer le wallet (ou décochez « Chiffrer le fichier wallet »).",
"Digite uma senha para criptografar a carteira (ou desmarque «Criptografar o arquivo da carteira»).",
"Geben Sie ein Passwort zum Verschlüsseln ein (oder deaktivieren Sie „Wallet-Datei verschlüsseln“).",
"请输入密码以加密钱包（或取消勾选“加密钱包文件”）。"],
["msg.password.mismatch"] = [
"Le due password non coincidono.",
"The two passwords do not match.",
"Las dos contraseñas no coinciden.",
"Les deux mots de passe ne correspondent pas.",
"As duas senhas não coincidem.",
"Die beiden Passwörter stimmen nicht überein.",
"两次输入的密码不一致。"],
["msg.wrongpassword"] = ["Password errata.", "Wrong password.", "Contraseña incorrecta.", "Mot de passe incorrect.", "Senha incorreta.", "Falsches Passwort.", "密码错误。"],
["msg.wallet.locked"] = ["Wallet già aperto in un'altra istanza dell'applicazione.", "Wallet already open in another instance of the application.", "El wallet ya está abierto en otra instancia de la aplicación.", "Le wallet est déjà ouvert dans une autre instance de l'application.", "A carteira já está aberta em outra instância do aplicativo.", "Wallet ist bereits in einer anderen Instanz der Anwendung geöffnet.", "钱包已在应用程序的另一个实例中打开。"],
["msg.wallet.noaccess"] = ["Impossibile accedere al file del wallet: verificare i permessi.", "Cannot access the wallet file: check file permissions.", "No se puede acceder al archivo del wallet: verifique los permisos.", "Impossible d'accéder au fichier du wallet : vérifiez les autorisations.", "Não é possível acessar o arquivo da carteira: verifique as permissões.", "Zugriff auf die Wallet-Datei nicht möglich: Berechtigungen prüfen.", "无法访问钱包文件：请检查文件权限。"],
["msg.opened"] = ["Wallet aperto: connessione al server…", "Wallet opened: connecting to server…", "Wallet abierto: conectando al servidor…", "Wallet ouvert : connexion au serveur…", "Carteira aberta: conectando ao servidor…", "Wallet geöffnet: Verbindung zum Server…", "钱包已打开：正在连接服务器…"],
["msg.synced"] = ["Sincronizzato", "Synchronized", "Sincronizado", "Synchronisé", "Sincronizado", "Synchronisiert", "已同步"],
["msg.synced.detail"] = [
"transazioni verificate SPV. Aggiornamento in tempo reale attivo.",
"SPV-verified transactions. Real-time updates active."],
["msg.height"] = ["altezza", "height"],
["msg.pending"] = ["in attesa di conferma", "pending confirmation"],
["msg.notspendable"] = ["non ancora spendibile", "not yet spendable"],
["msg.settings.saved"] = ["Impostazioni salvate.", "Settings saved."],
["msg.certreset"] = [
"SPV-verified transactions. Real-time updates active.",
"transacciones verificadas SPV. Actualizaciones en tiempo real activas.",
"transactions vérifiées SPV. Mises à jour en temps réel actives.",
"transações verificadas SPV. Atualizações em tempo real ativas.",
"SPV-verifizierte Transaktionen. Echtzeit-Updates aktiv.",
"已通过 SPV 验证的交易。实时更新已启用。"],
["msg.height"] = ["altezza", "height", "altura", "hauteur", "altura", "Höhe", "高度"],
["msg.pending"] = ["in attesa di conferma", "pending confirmation", "pendiente de confirmación", "en attente de confirmation", "aguardando confirmação", "ausstehende Bestätigung", "等待确认"],
["msg.notspendable"] = ["non ancora spendibile", "not yet spendable", "aún no gastable", "pas encore dépensable", "ainda não gastável", "noch nicht verwendbar", "尚不可花费"],
["msg.immature"] = ["in maturazione", "maturing", "en maduración", "en maturation", "em maturação", "in Reifung", "成熟中"],
["msg.verifying"] = ["in verifica SPV", "SPV-verifying", "en verificación SPV", "en cours de vérification SPV", "em verificação SPV", "SPV-Prüfung läuft", "正在进行 SPV 验证"],
["history.unanchored"] = ["non ancorata", "not anchored", "sin anclar", "non ancrée", "não ancorada", "nicht verankert", "未锚定"],
["history.unanchored.tip"] = ["Blocco successivo all'ultimo checkpoint della versione: la sua intestazione e la prova Merkle arrivano dal server e non si collegano a un checkpoint. Aggiorna il wallet per ancorarla.", "Block after the newest checkpoint of this version: its header and Merkle proof come from the server and do not chain to a checkpoint. Update the wallet to anchor it.", "Bloque posterior al último punto de control de esta versión: su cabecera y la prueba Merkle vienen del servidor y no se enlazan a un punto de control. Actualiza la cartera para anclarlo.", "Bloc postérieur au dernier point de contrôle de cette version : son en-tête et la preuve Merkle viennent du serveur et ne se rattachent à aucun point de contrôle. Mettez le portefeuille à jour pour l'ancrer.", "Bloco posterior ao último checkpoint desta versão: o cabeçalho e a prova Merkle vêm do servidor e não se ligam a um checkpoint. Atualize a carteira para ancorá-lo.", "Block nach dem neuesten Checkpoint dieser Version: Header und Merkle-Beweis stammen vom Server und sind an keinen Checkpoint gekettet. Aktualisieren Sie die Wallet, um ihn zu verankern.", "此版本最新检查点之后的区块：其区块头和 Merkle 证明来自服务器，未链接到任何检查点。请更新钱包以完成锚定。"],
["history.unverified"] = ["in verifica…", "verifying…", "verificando…", "vérification…", "verificando…", "wird geprüft…", "验证中…"],
["msg.settings.saved"] = ["Impostazioni salvate.", "Settings saved.", "Configuración guardada.", "Paramètres enregistrés.", "Configurações salvas.", "Einstellungen gespeichert.", "设置已保存。"],
["msg.certreset"] = [
"Certificati SSL azzerati: riprova la connessione.",
"SSL certificates cleared: retry the connection."],
["msg.error"] = ["Errore", "Error"],
"SSL certificates cleared: retry the connection.",
"Certificados SSL restablecidos: reintenta la conexión.",
"Certificats SSL réinitialisés : réessayez la connexion.",
"Certificados SSL redefinidos: tente novamente a conexão.",
"SSL-Zertifikate zurückgesetzt: Verbindung erneut versuchen.",
"SSL 证书已清除：请重试连接。"],
["msg.error"] = ["Errore", "Error", "Error", "Erreur", "Erro", "Fehler", "错误"],
["msg.broadcast.error"] = ["Errore broadcast", "Broadcast error", "Error de transmisión", "Erreur de diffusion", "Erro de transmissão", "Übertragungsfehler", "广播错误"],
["msg.peer.discovery.error"] = ["Errore nella scoperta peer", "Peer discovery error", "Error al descubrir peers", "Erreur de découverte des pairs", "Erro na descoberta de peers", "Fehler bei der Peer-Suche", "节点发现错误"],
["msg.peer.discovery.found"] = ["Trovati {0} nuovi server dai peer (totale {1}).", "Found {0} new servers from peers (total {1}).", "Se encontraron {0} nuevos servidores de peers (total {1}).", "{0} nouveaux serveurs trouvés via les pairs (total {1}).", "Encontrados {0} novos servidores dos peers (total {1}).", "{0} neue Server von Peers gefunden (insgesamt {1}).", "从节点发现了 {0} 个新服务器（共 {1} 个）。"],
["msg.peer.discovery.none"] = ["Nessun nuovo server annunciato (totale {0}).", "No new servers announced (total {0}).", "No se anunciaron nuevos servidores (total {0}).", "Aucun nouveau serveur annoncé (total {0}).", "Nenhum novo servidor anunciado (total {0}).", "Keine neuen Server angekündigt (insgesamt {0}).", "没有新的服务器公告（共 {0} 个）。"],
["msg.send.sync.first"] = ["Sincronizza prima di inviare.", "Synchronize before sending.", "Sincroniza antes de enviar.", "Synchronisez avant d'envoyer.", "Sincronize antes de enviar.", "Vor dem Senden synchronisieren.", "发送前请先同步。"],
["msg.send.connect.first"] = ["Connettiti al server e sincronizza prima di inviare.", "Connect to the server and synchronize before sending.", "Conéctate al servidor y sincroniza antes de enviar.", "Connectez-vous au serveur et synchronisez avant d'envoyer.", "Conecte-se ao servidor e sincronize antes de enviar.", "Mit dem Server verbinden und vor dem Senden synchronisieren.", "发送前请先连接服务器并同步。"],
["msg.amount.invalid"] = ["Importo non valido.", "Invalid amount.", "Importe no válido.", "Montant invalide.", "Valor inválido.", "Ungültiger Betrag.", "金额无效。"],
["msg.feerate.invalid"] = ["Fee rate non valido.", "Invalid fee rate.", "Tarifa no válida.", "Taux de frais invalide.", "Taxa inválida.", "Ungültige Gebührenrate.", "手续费率无效。"],
["msg.broadcasted"] = ["Trasmessa", "Broadcast", "Transmitida", "Diffusée", "Transmitida", "Übertragen", "已广播"],
["msg.donate.thanks"] = ["Grazie! txid", "Thank you! txid", "¡Gracias! txid", "Merci ! txid", "Obrigado! txid", "Danke! txid", "谢谢！交易 ID"],
["msg.unsigned.watchonly"] = [" · NON firmata (watch-only)", " · NOT signed (watch-only)", " · NO firmada (watch-only)", " · NON signée (watch-only)", " · NÃO assinada (watch-only)", " · NICHT signiert (watch-only)", " · 未签名（仅观察）"],
["send.fee.fast"] = ["Veloce", "Fast", "Rápida", "Rapide", "Rápida", "Schnell", "快速"],
["send.fee.normal"] = ["Normale", "Normal", "Normal", "Normale", "Normal", "Normal", "正常"],
["send.fee.economy"] = ["Economica", "Economy", "Económica", "Économique", "Econômica", "Sparsam", "经济"],
["send.fee.hint"] = ["Stima della rete (sat/vB): veloce {0} · normale {1} · economica {2} · minimo relay {3}", "Network estimate (sat/vB): fast {0} · normal {1} · economy {2} · relay minimum {3}", "Estimación de la red (sat/vB): rápida {0} · normal {1} · económica {2} · mínimo de relay {3}", "Estimation du réseau (sat/vB) : rapide {0} · normale {1} · économique {2} · minimum de relais {3}", "Estimativa da rede (sat/vB): rápida {0} · normal {1} · econômica {2} · mínimo de relay {3}", "Netzwerkschätzung (sat/vB): schnell {0} · normal {1} · sparsam {2} · Relay-Minimum {3}", "网络估算 (sat/vB)：快速 {0} · 正常 {1} · 经济 {2} · 中继最低 {3}"],
["msg.feerate.belowrelay"] = ["Fee rate sotto il minimo di relay del server ({0} sat/vB): la transazione verrebbe rifiutata.", "Fee rate below the server's minimum relay fee ({0} sat/vB): the transaction would be rejected.", "Tarifa por debajo del mínimo de relay del servidor ({0} sat/vB): la transacción sería rechazada.", "Taux de frais inférieur au minimum de relais du serveur ({0} sat/vB) : la transaction serait rejetée.", "Taxa abaixo do mínimo de relay do servidor ({0} sat/vB): a transação seria rejeitada.", "Gebührenrate unter dem Relay-Minimum des Servers ({0} sat/vB): Die Transaktion würde abgelehnt.", "手续费率低于服务器的最低中继费 ({0} sat/vB)：交易将被拒绝。"],
["msg.fee.high"] = ["Attenzione: la fee supera l'{0}% dell'importo inviato.", "Warning: the fee is more than {0}% of the amount sent.", "Atención: la comisión supera el {0}% del importe enviado.", "Attention : les frais dépassent {0} % du montant envoyé.", "Atenção: a taxa excede {0}% do valor enviado.", "Achtung: Die Gebühr beträgt mehr als {0} % des gesendeten Betrags.", "警告：手续费超过发送金额的 {0}%。"],
["msg.cert.mismatch"] = [
"Il certificato TLS di {0} è cambiato rispetto a quello salvato. Se il server ha rinnovato il certificato, esegui il reset dei certificati SSL.",
"The TLS certificate of {0} has changed from the one saved. If the server renewed its certificate, reset the SSL certificates.",
"El certificado TLS de {0} ha cambiado respecto al guardado. Si el servidor renovó su certificado, restablece los certificados SSL.",
"Le certificat TLS de {0} a changé par rapport à celui enregistré. Si le serveur a renouvelé son certificat, réinitialisez les certificats SSL.",
"O certificado TLS de {0} mudou em relação ao salvo. Se o servidor renovou o certificado, redefina os certificados SSL.",
"Das TLS-Zertifikat von {0} hat sich gegenüber dem gespeicherten geändert. Wenn der Server das Zertifikat erneuert hat, setzen Sie die SSL-Zertifikate zurück.",
"{0} 的 TLS 证书与已保存的证书不同。如果服务器更新了证书，请重置 SSL 证书。"],
// Finestra impostazioni
["settings.title"] = ["Impostazioni", "Settings"],
["settings.language"] = ["Lingua", "Language"],
["settings.unit"] = ["Unità degli importi", "Amount unit"],
["settings.ok"] = ["Salva", "Save"],
["settings.cancel"] = ["Annulla", "Cancel"],
["msg.chain.wrong"] = [
"Il server {0} non è sulla catena Palladium (genesi o checkpoint diversi). Scegli un altro server.",
"The server {0} is not on the Palladium chain (different genesis or checkpoint). Choose another server.",
"El servidor {0} no está en la cadena Palladium (génesis o punto de control distintos). Elige otro servidor.",
"Le serveur {0} n'est pas sur la chaîne Palladium (genèse ou point de contrôle différent). Choisissez un autre serveur.",
"O servidor {0} não está na cadeia Palladium (gênese ou checkpoint diferente). Escolha outro servidor.",
"Der Server {0} befindet sich nicht auf der Palladium-Chain (anderer Genesis-Block oder Checkpoint). Wählen Sie einen anderen Server.",
"服务器 {0} 不在 Palladium 链上（创世块或检查点不同）。请选择其他服务器。"],
// Contacts
["msg.contact.address.invalid"] = [
"Indirizzo non valido per questa rete: il contatto non è stato salvato.",
"Invalid address for this network: the contact was not saved.",
"Dirección no válida para esta red: el contacto no se guardó.",
"Adresse invalide pour ce réseau : le contact n'a pas été enregistré.",
"Endereço inválido para esta rede: o contato não foi salvo.",
"Ungültige Adresse für dieses Netzwerk: Der Kontakt wurde nicht gespeichert.",
"该网络的地址无效：联系人未保存。"],
["msg.contact.duplicate"] = [
"Esiste già un contatto con questo indirizzo.",
"A contact with this address already exists.",
"Ya existe un contacto con esta dirección.",
"Un contact avec cette adresse existe déjà.",
"Já existe um contato com este endereço.",
"Ein Kontakt mit dieser Adresse existiert bereits.",
"已存在相同地址的联系人。"],
["contacts.name"] = ["Nome", "Name", "Nombre", "Nom", "Nome", "Name", "姓名"],
["contacts.address"] = ["Indirizzo", "Address", "Dirección", "Adresse", "Endereço", "Adresse", "地址"],
["contacts.name.ph"] = ["Nome contatto", "Contact name", "Nombre del contacto", "Nom du contact", "Nome do contato", "Kontaktname", "联系人姓名"],
["contacts.address.ph"] = ["Indirizzo blockchain", "Blockchain address", "Dirección blockchain", "Adresse blockchain", "Endereço blockchain", "Blockchain-Adresse", "区块链地址"],
["contacts.add"] = ["Aggiungi", "Add", "Agregar", "Ajouter", "Adicionar", "Hinzufügen", "添加"],
["contacts.remove"] = ["Rimuovi selezionato", "Remove selected", "Eliminar seleccionado", "Supprimer la sélection", "Remover selecionado", "Auswahl entfernen", "删除所选"],
["contacts.empty"] = ["Nessun contatto salvato.", "No saved contacts.", "No hay contactos guardados.", "Aucun contact enregistré.", "Nenhum contato salvo.", "Keine gespeicherten Kontakte.", "没有已保存的联系人。"],
// Settings window
["settings.title"] = ["Impostazioni", "Settings", "Configuración", "Paramètres", "Configurações", "Einstellungen", "设置"],
["settings.language"] = ["Lingua", "Language", "Idioma", "Langue", "Idioma", "Sprache", "语言"],
["settings.unit"] = ["Unità degli importi", "Amount unit", "Unidad de importes", "Unité des montants", "Unidade dos valores", "Betrageinheit", "金额单位"],
["settings.ok"] = ["Salva", "Save", "Guardar", "Enregistrer", "Salvar", "Speichern", "保存"],
["settings.cancel"] = ["Annulla", "Cancel", "Cancelar", "Annuler", "Cancelar", "Abbrechen", "取消"],
["settings.server"] = ["Server di indicizzazione…", "Indexing server…", "Servidor de indexación…", "Serveur d'indexation…", "Servidor de indexação…", "Indexierungsserver…", "索引服务器…"],
// Server window
["server.title"] = ["Server di indicizzazione", "Indexing server", "Servidor de indexación", "Serveur d'indexation", "Servidor de indexação", "Indexierungsserver", "索引服务器"],
["server.host"] = ["Host", "Host", "Host", "Hôte", "Host", "Host", "主机"],
["server.port"] = ["Porta", "Port", "Puerto", "Port", "Porta", "Port", "端口"],
["server.known"] = ["Server conosciuti (clicca per usarlo):", "Known servers (click to use):", "Servidores conocidos (clic para usar):", "Serveurs connus (cliquez pour utiliser) :", "Servidores conhecidos (clique para usar):", "Bekannte Server (zum Verwenden anklicken):", "已知服务器（点击使用）："],
["server.empty"] = ["Nessun server conosciuto. Usa «Cerca altri server» dopo esserti connesso.", "No known servers. Use “Discover servers” after connecting.", "No hay servidores conocidos. Usa «Buscar otros servidores» tras conectar.", "Aucun serveur connu. Utilisez « Rechercher des serveurs » après connexion.", "Nenhum servidor conhecido. Use «Procurar servidores» após conectar.", "Keine bekannten Server. Nutzen Sie „Server suchen“ nach dem Verbinden.", "没有已知服务器。连接后请使用“发现服务器”。"],
};
}
src/App/PalladiumWallet.App.csproj
+32 -28
View File
@@ -1,30 +1,34 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>WinExe</OutputType>
<TargetFramework>net8.0</TargetFramework>
<Nullable>enable</Nullable>
<ApplicationManifest>app.manifest</ApplicationManifest>
<AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
</PropertyGroup>
<ItemGroup>
<Folder Include="Models\" />
<AvaloniaResource Include="Assets\**" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Avalonia" Version="12.0.4" />
<PackageReference Include="Avalonia.Desktop" Version="12.0.4" />
<PackageReference Include="Avalonia.Themes.Fluent" Version="12.0.4" />
<PackageReference Include="Avalonia.Fonts.Inter" Version="12.0.4" />
<PackageReference Include="AvaloniaUI.DiagnosticsSupport" Version="2.2.1">
<IncludeAssets Condition="'$(Configuration)' != 'Debug'">None</IncludeAssets>
<PrivateAssets Condition="'$(Configuration)' != 'Debug'">All</PrivateAssets>
</PackageReference>
<PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.1" />
</ItemGroup>
<Project Sdk="Microsoft.NET.Sdk">
<!-- Libreria UI condivisa: il codice Avalonia (App, Views, ViewModels, Loc,
Assets) usato sia dall'head Desktop sia dall'head Android. Gli head
portano l'entry-point e i pacchetti specifici di piattaforma. -->
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<!-- Versione dell'applicazione: unico punto da modificare. Compare nel
titolo della finestra ed è incisa nei binari pubblicati. -->
<Version>1.2.0</Version>
<Nullable>enable</Nullable>
<AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>
</PropertyGroup>
<ItemGroup>
<Folder Include="Models\" />
<AvaloniaResource Include="Assets\**" />
</ItemGroup>
<ItemGroup>
<PackageReference Include="Avalonia" Version="12.0.4" />
<PackageReference Include="Avalonia.Themes.Fluent" Version="12.0.4" />
<PackageReference Include="Avalonia.Fonts.Inter" Version="12.0.4" />
<PackageReference Include="CommunityToolkit.Mvvm" Version="8.4.1" />
<PackageReference Include="QRCoder" Version="1.8.0" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\Core\PalladiumWallet.Core.csproj" />
</ItemGroup>
</Project>
</ItemGroup>
<ItemGroup>
<InternalsVisibleTo Include="PalladiumWallet.Tests" />
</ItemGroup>
</Project>
src/App/Services/PlatformServices.cs
+17
View File
@@ -0,0 +1,17 @@
using System;
using System.Threading.Tasks;
namespace PalladiumWallet.App.Services;
/// <summary>
/// Seam for platform-specific services (Android/desktop).
/// The Android head sets the delegates in OnCreate; desktop leaves them null.
/// </summary>
public static class PlatformServices
{
/// <summary>
/// Opens the native QR scanner and returns the raw code text,
/// or null if the user cancels or the scanner is unavailable.
/// </summary>
public static Func<Task<string?>>? ScanQrAsync { get; set; }
}
src/App/Styles/Controls.axaml
+172
View File
@@ -0,0 +1,172 @@
<Styles xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<!-- ============================================================
Palladium wallet control styles ("clean fintech").
Applied on top of FluentTheme: refine spacing, states and
reusable classes without re-templating controls. The "accent"
buttons remain managed by Fluent but inherit the brand blue
via SystemAccentColor (see Theme.axaml).
============================================================ -->
<Design.PreviewWith>
<Border Padding="20" Width="320">
<StackPanel Spacing="12">
<TextBlock Classes="h1" Text="Saldo disponibile"/>
<TextBlock Classes="amount" Text="1 234,56 PLM"/>
<Button Classes="accent" Content="Invia"/>
<Button Content="Annulla"/>
<Border Classes="card" Padding="16">
<TextBlock Text="Card di esempio"/>
</Border>
</StackPanel>
</Border>
</Design.PreviewWith>
<!-- ===== Typography ===== -->
<Style Selector="TextBlock.h1">
<Setter Property="FontSize" Value="20"/>
<Setter Property="FontWeight" Value="SemiBold"/>
<Setter Property="Foreground" Value="{DynamicResource TextPrimaryBrush}"/>
</Style>
<Style Selector="TextBlock.label">
<Setter Property="FontSize" Value="11"/>
<Setter Property="FontWeight" Value="Medium"/>
<Setter Property="Foreground" Value="{DynamicResource TextSecondaryBrush}"/>
</Style>
<Style Selector="TextBlock.muted">
<Setter Property="Foreground" Value="{DynamicResource TextSecondaryBrush}"/>
</Style>
<!-- Amounts and numeric data: tabular figures to prevent layout jumps -->
<Style Selector="TextBlock.amount">
<Setter Property="FontSize" Value="34"/>
<Setter Property="FontWeight" Value="Bold"/>
<Setter Property="Foreground" Value="{DynamicResource TextPrimaryBrush}"/>
<Setter Property="FontFeatures" Value="+tnum"/>
</Style>
<Style Selector="TextBlock.mono, SelectableTextBlock.mono">
<Setter Property="FontFamily" Value="monospace"/>
<Setter Property="FontFeatures" Value="+tnum"/>
</Style>
<!-- Section heading (e.g. transaction detail) -->
<Style Selector="TextBlock.section">
<Setter Property="FontSize" Value="11"/>
<Setter Property="FontWeight" Value="SemiBold"/>
<Setter Property="Foreground" Value="{DynamicResource TextMutedBrush}"/>
<Setter Property="LetterSpacing" Value="0.8"/>
</Style>
<!-- ===== Buttons ===== -->
<Style Selector="Button">
<Setter Property="MinHeight" Value="36"/>
<Setter Property="Padding" Value="14,8"/>
<Setter Property="Cursor" Value="Hand"/>
<Setter Property="FontWeight" Value="Medium"/>
<Setter Property="VerticalContentAlignment" Value="Center"/>
<Setter Property="HorizontalContentAlignment" Value="Center"/>
</Style>
<!-- Accent (CTA) buttons are already blue via Fluent+SystemAccentColor.
Ensure readable white text in both light and dark variants. -->
<Style Selector="Button.accent">
<Setter Property="Foreground" Value="#FFFFFF"/>
</Style>
<!-- "ghost" variant: subtle secondary action, no fill -->
<Style Selector="Button.ghost">
<Setter Property="Background" Value="Transparent"/>
<Setter Property="Foreground" Value="{DynamicResource PrimaryBrush}"/>
<Setter Property="BorderThickness" Value="0"/>
</Style>
<!-- ===== Inputs ===== -->
<Style Selector="TextBox">
<Setter Property="MinHeight" Value="36"/>
<Setter Property="Padding" Value="10,7"/>
</Style>
<Style Selector="ComboBox">
<Setter Property="MinHeight" Value="36"/>
<Setter Property="Padding" Value="10,6"/>
</Style>
<!-- ===== Lists ===== -->
<Style Selector="ListBox">
<Setter Property="Background" Value="Transparent"/>
<Setter Property="BorderThickness" Value="0"/>
<Setter Property="Padding" Value="0"/>
</Style>
<Style Selector="ListBoxItem">
<Setter Property="Padding" Value="12,10"/>
<Setter Property="CornerRadius" Value="8"/>
<Setter Property="Margin" Value="0,1"/>
</Style>
<!-- Hover: neutral tint; selected: subtle brand-blue tint -->
<Style Selector="ListBoxItem:pointerover /template/ ContentPresenter#PART_ContentPresenter">
<Setter Property="Background" Value="{DynamicResource SurfaceAltBrush}"/>
</Style>
<Style Selector="ListBoxItem:selected /template/ ContentPresenter#PART_ContentPresenter">
<Setter Property="Background" Value="{DynamicResource PrimarySoftBrush}"/>
</Style>
<!-- ===== Tabs (dashboard) ===== -->
<!-- Selected item: brand blue + bold; unselected: muted -->
<Style Selector="TabItem">
<Setter Property="Foreground" Value="{DynamicResource TextSecondaryBrush}"/>
<Setter Property="FontWeight" Value="Medium"/>
</Style>
<Style Selector="TabItem:selected">
<Setter Property="Foreground" Value="{DynamicResource PrimaryBrush}"/>
</Style>
<Style Selector="TabItem:selected /template/ ContentPresenter#PART_ContentPresenter">
<Setter Property="TextElement.Foreground" Value="{DynamicResource PrimaryBrush}"/>
</Style>
<!-- Push tab header content up so the 2px selection indicator (drawn at Panel bottom)
does not overlap the text label. -->
<Style Selector="TabItem /template/ ContentPresenter#PART_ContentPresenter">
<Setter Property="Margin" Value="0,0,0,4"/>
</Style>
<!-- ===== Reusable classes ===== -->
<!-- Card: elevated surface with a subtle border and soft corners -->
<Style Selector="Border.card">
<Setter Property="Background" Value="{DynamicResource SurfaceBrush}"/>
<Setter Property="BorderBrush" Value="{DynamicResource BorderSubtleBrush}"/>
<Setter Property="BorderThickness" Value="1"/>
<Setter Property="CornerRadius" Value="14"/>
<Setter Property="BoxShadow" Value="0 1 3 0 #14000000"/>
<Setter Property="Transitions">
<Transitions>
<BoxShadowsTransition Property="BoxShadow" Duration="0:0:0.18"/>
</Transitions>
</Setter>
</Style>
<Style Selector="Border.card:pointerover">
<Setter Property="BoxShadow" Value="0 6 16 -4 #26000000"/>
</Style>
<!-- Balance card: subtle blue accent, slightly more prominent -->
<Style Selector="Border.balance-card">
<Setter Property="Background" Value="{DynamicResource SurfaceBrush}"/>
<Setter Property="BorderBrush" Value="{DynamicResource BorderSubtleBrush}"/>
<Setter Property="BorderThickness" Value="1"/>
<Setter Property="CornerRadius" Value="14"/>
<Setter Property="Padding" Value="20,16"/>
<Setter Property="BoxShadow" Value="0 2 8 0 #1A000000"/>
</Style>
<!-- Hero balance card: brand gradient + blue glow. Signature dashboard
element; overlaid text is white (on-hero class). -->
<Style Selector="Border.balance-hero">
<Setter Property="Background" Value="{DynamicResource BalanceGradientBrush}"/>
<Setter Property="CornerRadius" Value="16"/>
<Setter Property="Padding" Value="24,20"/>
<Setter Property="BoxShadow" Value="0 8 24 -6 #663B82F6"/>
</Style>
<Style Selector="Border.balance-hero TextBlock.amount">
<Setter Property="Foreground" Value="#FFFFFF"/>
</Style>
<Style Selector="Border.balance-hero TextBlock.on-hero">
<Setter Property="Foreground" Value="#D6E2FF"/>
</Style>
<!-- Status pill / badge -->
<Style Selector="Border.chip">
<Setter Property="CornerRadius" Value="20"/>
<Setter Property="Padding" Value="10,5"/>
<Setter Property="Background" Value="{DynamicResource SurfaceAltBrush}"/>
</Style>
</Styles>
src/App/Styles/Theme.axaml
+96
View File
@@ -0,0 +1,96 @@
<ResourceDictionary xmlns="https://github.com/avaloniaui"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
<!-- ============================================================
Palladium wallet design tokens.
Identity: cobalt blue (trust) + green (money/positive),
derived from the logo. "Clean fintech" style.
All colors are SEMANTIC (role, not name): components
must never use inline hex but these brushes. Defined for
both variants (light/dark) via ThemeDictionaries, so
the app follows the system theme with no further configuration.
============================================================ -->
<ResourceDictionary.ThemeDictionaries>
<!-- ============ LIGHT THEME ============ -->
<ResourceDictionary x:Key="Light">
<!-- Surfaces -->
<SolidColorBrush x:Key="AppBackgroundBrush" Color="#F1F5F9"/> <!-- slate-100 -->
<SolidColorBrush x:Key="SurfaceBrush" Color="#FFFFFF"/>
<SolidColorBrush x:Key="SurfaceAltBrush" Color="#F8FAFC"/> <!-- slate-50 -->
<SolidColorBrush x:Key="OverlayCardBrush" Color="#FFFFFF"/>
<SolidColorBrush x:Key="ScrimBrush" Color="#66000000"/> <!-- 40% -->
<!-- Borders and separators -->
<SolidColorBrush x:Key="BorderSubtleBrush" Color="#E2E8F0"/> <!-- slate-200 -->
<SolidColorBrush x:Key="BorderStrongBrush" Color="#CBD5E1"/> <!-- slate-300 -->
<!-- Text -->
<SolidColorBrush x:Key="TextPrimaryBrush" Color="#0F172A"/> <!-- slate-900 -->
<SolidColorBrush x:Key="TextSecondaryBrush" Color="#475569"/> <!-- slate-600 -->
<SolidColorBrush x:Key="TextMutedBrush" Color="#94A3B8"/> <!-- slate-400 -->
<!-- Brand / state -->
<SolidColorBrush x:Key="PrimaryBrush" Color="#2563EB"/> <!-- blue-600 -->
<SolidColorBrush x:Key="PrimaryHoverBrush" Color="#1D4ED8"/> <!-- blue-700 -->
<SolidColorBrush x:Key="OnPrimaryBrush" Color="#FFFFFF"/>
<SolidColorBrush x:Key="PrimarySoftBrush" Color="#EFF6FF"/> <!-- blue-50 -->
<SolidColorBrush x:Key="SuccessBrush" Color="#16A34A"/> <!-- green-600 -->
<SolidColorBrush x:Key="WarningBrush" Color="#D97706"/> <!-- amber-600 -->
<SolidColorBrush x:Key="DangerBrush" Color="#DC2626"/> <!-- red-600 -->
<!-- Hero gradient of the balance card: blue → indigo -->
<LinearGradientBrush x:Key="BalanceGradientBrush" StartPoint="0%,0%" EndPoint="100%,100%">
<GradientStop Offset="0" Color="#2563EB"/>
<GradientStop Offset="1" Color="#4F46E5"/>
</LinearGradientBrush>
</ResourceDictionary>
<!-- ============ DARK THEME ============ -->
<ResourceDictionary x:Key="Dark">
<!-- Surfaces -->
<SolidColorBrush x:Key="AppBackgroundBrush" Color="#0F172A"/> <!-- slate-900 -->
<SolidColorBrush x:Key="SurfaceBrush" Color="#1E293B"/> <!-- slate-800 -->
<SolidColorBrush x:Key="SurfaceAltBrush" Color="#273449"/>
<SolidColorBrush x:Key="OverlayCardBrush" Color="#1E293B"/>
<SolidColorBrush x:Key="ScrimBrush" Color="#99000000"/> <!-- 60% -->
<!-- Borders and separators -->
<SolidColorBrush x:Key="BorderSubtleBrush" Color="#334155"/> <!-- slate-700 -->
<SolidColorBrush x:Key="BorderStrongBrush" Color="#475569"/> <!-- slate-600 -->
<!-- Text -->
<SolidColorBrush x:Key="TextPrimaryBrush" Color="#F8FAFC"/> <!-- slate-50 -->
<SolidColorBrush x:Key="TextSecondaryBrush" Color="#94A3B8"/> <!-- slate-400 -->
<SolidColorBrush x:Key="TextMutedBrush" Color="#64748B"/> <!-- slate-500 -->
<!-- Brand / state (brighter tones on dark background) -->
<SolidColorBrush x:Key="PrimaryBrush" Color="#3B82F6"/> <!-- blue-500 -->
<SolidColorBrush x:Key="PrimaryHoverBrush" Color="#60A5FA"/> <!-- blue-400 -->
<SolidColorBrush x:Key="OnPrimaryBrush" Color="#0B1120"/>
<SolidColorBrush x:Key="PrimarySoftBrush" Color="#1E3A8A"/> <!-- blue-900 -->
<SolidColorBrush x:Key="SuccessBrush" Color="#22C55E"/> <!-- green-500 -->
<SolidColorBrush x:Key="WarningBrush" Color="#F59E0B"/> <!-- amber-500 -->
<SolidColorBrush x:Key="DangerBrush" Color="#EF4444"/> <!-- red-500 -->
<!-- Hero gradient of the balance card: blue → indigo (deeper tones) -->
<LinearGradientBrush x:Key="BalanceGradientBrush" StartPoint="0%,0%" EndPoint="100%,100%">
<GradientStop Offset="0" Color="#1D4ED8"/>
<GradientStop Offset="1" Color="#4338CA"/>
</LinearGradientBrush>
</ResourceDictionary>
</ResourceDictionary.ThemeDictionaries>
<!-- ============================================================
Override of the Fluent accent → brand blue. Recolors
consistently the controls that read SystemAccentColor (accent
buttons, selections, tab indicator, focus) without retemplating anything.
Variant-independent: #2563EB works on light and dark.
============================================================ -->
<Color x:Key="SystemAccentColor">#2563EB</Color>
<Color x:Key="SystemAccentColorDark1">#1D4ED8</Color>
<Color x:Key="SystemAccentColorDark2">#1E40AF</Color>
<Color x:Key="SystemAccentColorDark3">#1E3A8A</Color>
<Color x:Key="SystemAccentColorLight1">#3B82F6</Color>
<Color x:Key="SystemAccentColorLight2">#60A5FA</Color>
<Color x:Key="SystemAccentColorLight3">#93C5FD</Color>
<!-- Global Fluent control corner radii: rounds buttons, inputs, combos,
and lists uniformly without retemplating each control. -->
<CornerRadius x:Key="ControlCornerRadius">8</CornerRadius>
<CornerRadius x:Key="OverlayCornerRadius">12</CornerRadius>
</ResourceDictionary>
src/App/ViewModels/BoolToTabPlacementConverter.cs
+21
View File
@@ -0,0 +1,21 @@
using System;
using System.Globalization;
using Avalonia.Controls;
using Avalonia.Data.Converters;
namespace PalladiumWallet.App.ViewModels;
/// <summary>
/// true (mobile) → Dock.Bottom — tab strip at the bottom, Android standard.
/// false (desktop) → Dock.Top — Avalonia default behavior.
/// </summary>
public sealed class BoolToTabPlacementConverter : IValueConverter
{
public static readonly BoolToTabPlacementConverter Instance = new();
public object Convert(object? value, Type targetType, object? parameter, CultureInfo culture) =>
value is true ? Dock.Bottom : Dock.Top;
public object ConvertBack(object? value, Type targetType, object? parameter, CultureInfo culture) =>
throw new NotSupportedException();
}
src/App/ViewModels/MainWindowViewModel.Contacts.cs
+88
View File
@@ -0,0 +1,88 @@
using System.Collections.ObjectModel;
using System.Linq;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using NBitcoin;
using PalladiumWallet.App.Localization;
using PalladiumWallet.Core.Chain;
using PalladiumWallet.Core.Storage;
namespace PalladiumWallet.App.ViewModels;
public partial class MainWindowViewModel
{
public ObservableCollection<ContactEntry> Contacts { get; } = [];
[ObservableProperty]
private ContactEntry? selectedContactInList;
/// <summary>Contact selected in the Send panel's ComboBox: fills SendTo.</summary>
[ObservableProperty]
private ContactEntry? sendToContact;
partial void OnSendToContactChanged(ContactEntry? value)
{
if (value is not null)
SendTo = value.Address;
}
[ObservableProperty]
private string newContactName = "";
[ObservableProperty]
private string newContactAddress = "";
[RelayCommand]
private void AddContact()
{
var name = NewContactName.Trim();
// Pasted addresses often carry spaces or line breaks anywhere: drop all whitespace.
var addr = string.Concat(NewContactAddress.Where(c => !char.IsWhiteSpace(c)));
if (string.IsNullOrEmpty(name) || string.IsNullOrEmpty(addr)) return;
try
{
BitcoinAddress.Create(addr, PalladiumNetworks.For(Net));
}
catch (System.FormatException)
{
StatusMessage = Loc.Tr("msg.contact.address.invalid");
return;
}
if (Contacts.Any(c => string.Equals(c.Address, addr, System.StringComparison.OrdinalIgnoreCase)))
{
StatusMessage = Loc.Tr("msg.contact.duplicate");
return;
}
Contacts.Add(new ContactEntry(name, addr));
NewContactName = NewContactAddress = "";
PersistContacts();
}
[RelayCommand]
private void RemoveSelectedContact()
{
if (SelectedContactInList is { } c)
{
Contacts.Remove(c);
SelectedContactInList = null;
PersistContacts();
}
}
private void PersistContacts()
{
if (_doc is null || _walletPath is null) return;
_doc.Contacts = Contacts
.Select(c => new StoredContact { Name = c.Name, Address = c.Address })
.ToList();
WalletStore.Save(_doc, _walletPath, _password);
}
private void LoadContacts()
{
Contacts.Clear();
if (_doc is null) return;
foreach (var c in _doc.Contacts)
Contacts.Add(new ContactEntry(c.Name, c.Address));
}
}
src/App/ViewModels/MainWindowViewModel.Donate.cs
+106
View File
@@ -0,0 +1,106 @@
using System;
using System.Threading.Tasks;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using NBitcoin;
using PalladiumWallet.App.Localization;
using PalladiumWallet.Core.Chain;
using PalladiumWallet.Core.Net;
using PalladiumWallet.Core.Wallet;
namespace PalladiumWallet.App.ViewModels;
public partial class MainWindowViewModel
{
public const string DevAddress = "plm1qdq3gu2zvg9lyr8gxd6yln4wavc5tlp8prmvfay";
[ObservableProperty]
private string donateAmount = "";
[ObservableProperty]
private string donatePreview = "";
[ObservableProperty]
private bool hasPendingDonate;
private BuiltTransaction? _pendingDonate;
[RelayCommand]
private async Task PrepareDonate()
{
_pendingDonate = null;
HasPendingDonate = false;
if (_account is null || _doc?.Cache is null || _lastTransactions is null)
{
DonatePreview = Loc.Tr("msg.send.sync.first");
return;
}
try
{
var destination = BitcoinAddress.Create(DevAddress, PalladiumNetworks.For(Net));
if (!CoinAmount.TryParseIn(DonateAmount.Trim(), _config.Unit, out var amount) || amount <= 0)
{
DonatePreview = Loc.Tr("msg.amount.invalid");
return;
}
if (!CoinAmount.TryParseFeeRate(SendFeeRate, out var feeRate))
{
DonatePreview = Loc.Tr("msg.feerate.invalid");
return;
}
if (FeePolicy.IsBelowRelay(feeRate, _feeEstimates?.Relay))
{
DonatePreview = string.Format(Loc.Tr("msg.feerate.belowrelay"),
FeePolicy.Format(_feeEstimates!.Relay!.Value));
return;
}
_pendingDonate = new TransactionFactory(_account).Build(
_doc.Cache.Utxos, _lastTransactions, destination, amount, feeRate,
_doc.Cache.NextChangeIndex, _doc.Cache.TipHeight, sendAll: false);
DonatePreview = $"txid {_pendingDonate.Txid[..16]}… · " +
$"fee {Fmt(_pendingDonate.Fee.Satoshi)} " +
$"({_pendingDonate.Transaction.GetVirtualSize()} vB)" +
(_pendingDonate.Signed ? "" : " · watch-only") +
HighFeeWarning(_pendingDonate.Fee.Satoshi, amount);
HasPendingDonate = _pendingDonate.Signed;
}
catch (Exception ex)
{
_pendingDonate = null;
HasPendingDonate = false;
DonatePreview = $"{Loc.Tr("msg.error")}: {ex.Message}";
}
await Task.CompletedTask;
}
[RelayCommand]
private async Task ConfirmDonate()
{
if (_pendingDonate is null || _client is null)
return;
try
{
var txid = await _client.BroadcastAsync(_pendingDonate.ToHex());
DonatePreview = $"{Loc.Tr("msg.donate.thanks")}: {txid}";
DonateAmount = "";
_pendingDonate = null;
HasPendingDonate = false;
await ConnectAndSync();
}
catch (Exception ex)
{
DonatePreview = $"{Loc.Tr("msg.broadcast.error")}: {ex.Message}";
}
}
private void ResetDonate()
{
DonateAmount = "";
DonatePreview = "";
HasPendingDonate = false;
_pendingDonate = null;
}
}
src/App/ViewModels/MainWindowViewModel.Receive.cs
+330
View File
@@ -0,0 +1,330 @@
using System;
using System.IO;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Avalonia.Media.Imaging;
using CommunityToolkit.Mvvm.ComponentModel;
using CommunityToolkit.Mvvm.Input;
using PalladiumWallet.App.Localization;
using PalladiumWallet.Core.Chain;
using PalladiumWallet.Core.Spv;
using PalladiumWallet.Core.Storage;
using PalladiumWallet.Core.Wallet;
using QRCoder;
namespace PalladiumWallet.App.ViewModels;
public partial class MainWindowViewModel
{
// ---- balance and wallet info ----
[ObservableProperty]
private string balanceText = "—";
[ObservableProperty]
private string unconfirmedText = "";
[ObservableProperty]
private string immatureText = "";
[ObservableProperty]
private string verifyingText = "";
[ObservableProperty]
private string networkInfo = "";
// ---- receive address and QR ----
[ObservableProperty]
private string receiveAddress = "";
[ObservableProperty]
private Bitmap? receiveQr;
partial void OnReceiveAddressChanged(string value)
{
var previous = ReceiveQr;
ReceiveQr = string.IsNullOrEmpty(value) ? null : GenerateQr(value);
previous?.Dispose();
}
public void NotifyAddressCopied() => StatusMessage = Loc.Tr("addr.copied");
private static Bitmap? GenerateQr(string text)
{
try
{
using var generator = new QRCodeGenerator();
using var data = generator.CreateQrCode(text, QRCodeGenerator.ECCLevel.M);
var png = new PngByteQRCode(data).GetGraphic(8);
return new Bitmap(new MemoryStream(png));
}
catch
{
return null;
}
}
// ---- addresses tab ----
[ObservableProperty]
private AddressRow? selectedAddressRow;
[ObservableProperty]
private AddressInfo? addressInfo;
[ObservableProperty]
private bool isAddressPrivKeyRevealed;
// WIF of the address in the open sheet, derived only after the reveal gate and dropped as
// soon as the key is hidden or the sheet closes. Never stored in rows or in AddressInfo.
[ObservableProperty]
private string revealedPrivKey = "";
// ---- private key password prompt ----
[ObservableProperty]
private bool isPrivKeyPromptOpen;
[ObservableProperty]
private string privKeyPromptPassword = "";
[ObservableProperty]
private string privKeyPromptError = "";
partial void OnAddressInfoChanged(AddressInfo? value)
{
HidePrivKeyInternal();
ClosePrivKeyPromptInternal();
}
private void HidePrivKeyInternal()
{
IsAddressPrivKeyRevealed = false;
RevealedPrivKey = "";
}
private void RevealPrivKeyInternal()
{
if (AddressInfo is not { HasPrivKey: true } info) return;
RevealedPrivKey = KeyWif(info.IsChange, info.Index);
IsAddressPrivKeyRevealed = RevealedPrivKey.Length > 0;
}
private void ClosePrivKeyPromptInternal()
{
IsPrivKeyPromptOpen = false;
PrivKeyPromptPassword = "";
PrivKeyPromptError = "";
}
public void ShowAddressInfo(AddressRow row) =>
AddressInfo = new AddressInfo(Loc, row.Indirizzo, row.DerivPath, row.PubKey,
row.IsChange, row.Indice, row.HasPrivKey);
[RelayCommand]
private void CloseAddressInfo()
{
ClosePrivKeyPromptInternal();
AddressInfo = null;
}
[RelayCommand]
private void RequestPrivKeyReveal()
{
if (AddressInfo is null || !AddressInfo.HasPrivKey) return;
if (string.IsNullOrEmpty(_password))
{
// No encryption: reveal directly
RevealPrivKeyInternal();
}
else
{
// Encrypted: open password prompt
PrivKeyPromptPassword = "";
PrivKeyPromptError = "";
IsPrivKeyPromptOpen = true;
}
}
[RelayCommand]
private void ConfirmPrivKeyPassword()
{
if (PrivKeyPromptPassword != _password)
{
PrivKeyPromptError = Loc.Tr("msg.wrongpassword");
return;
}
RevealPrivKeyInternal();
ClosePrivKeyPromptInternal();
}
[RelayCommand]
private void CancelPrivKeyPrompt() => ClosePrivKeyPromptInternal();
[RelayCommand]
private void HideAddressPrivKey() => HidePrivKeyInternal();
// ---- transaction detail overlay ----
[ObservableProperty]
private bool isTxDetailsOpen;
[ObservableProperty]
private bool isTxDetailsLoading;
[ObservableProperty]
private TransactionDetailsViewModel? txDetails;
public async Task ShowTransactionDetailsAsync(string txid)
{
if (_client is null || !_client.IsConnected)
{
StatusMessage = Loc.Tr("tx.needconnection");
return;
}
_txDetailsCts?.Cancel();
_txDetailsCts = new CancellationTokenSource();
var ct = _txDetailsCts.Token;
TxDetails = null;
IsTxDetailsLoading = true;
IsTxDetailsOpen = true;
var details = await BuildTransactionDetailsAsync(txid, ct);
if (ct.IsCancellationRequested || !IsTxDetailsOpen)
return;
if (details is null)
{
IsTxDetailsOpen = false;
IsTxDetailsLoading = false;
return;
}
TxDetails = details;
IsTxDetailsLoading = false;
}
[RelayCommand]
private void CloseTransactionDetails()
{
_txDetailsCts?.Cancel();
IsTxDetailsOpen = false;
IsTxDetailsLoading = false;
TxDetails = null;
}
public async Task<TransactionDetailsViewModel?> BuildTransactionDetailsAsync(
string txid, CancellationToken ct = default)
{
if (_client is null || !_client.IsConnected)
{
StatusMessage = Loc.Tr("tx.needconnection");
return null;
}
if (_doc?.Cache is not { } cache)
return null;
var client = _client;
var network = PalladiumNetworks.For(Net);
var row = cache.History.FirstOrDefault(t => t.Txid == txid);
var owned = cache.Addresses.Select(a => a.Address).ToHashSet();
var tipHeight = cache.TipHeight;
var height = row?.Height ?? 0;
var delta = row?.DeltaSats ?? 0;
var verified = row?.Verified ?? false;
var transactions = _lastTransactions;
var loc = _loc;
var unit = _config.Unit;
var unanchored = Profile.IsAboveNewestCheckpoint(height);
try
{
return await Task.Run(async () =>
{
var details = await TransactionInspector.FetchAsync(
client, network, txid, tipHeight, height, owned, delta, verified, transactions, ct);
return new TransactionDetailsViewModel(details, loc, unit, unanchored);
}, ct);
}
catch (OperationCanceledException)
{
return null;
}
catch (Exception ex)
{
StatusMessage = $"{Loc.Tr("msg.error")}: {ex.Message}";
return null;
}
}
// ---- update display from the sync result ----
private void ApplyCache(SyncCache? cache)
{
if (_account is null)
return;
if (cache is null)
{
BalanceText = $"0.00000000 {Profile.CoinUnit}";
UnconfirmedText = "";
ImmatureText = "";
VerifyingText = "";
ReceiveAddress = _account.GetReceiveAddress(0).ToString();
History.Clear();
Addresses.Clear();
for (var i = 0; i < 10; i++)
Addresses.Add(new AddressRow(_loc["addr.receive"], i,
_account.GetReceiveAddress(i).ToString(), "—", "—",
false,
_account.GetPublicKey(false, i)?.ToHex() ?? "",
$"m/{_doc!.AccountPath}/0/{i}",
!_account.IsWatchOnly));
return;
}
// Not "Confirmed - Immature - PendingVerification": those two can overlap (an
// immature coinbase can also be unverified), which double-subtracts and can go
// negative. SpendableSats is computed directly from the same IsSpendable gate
// coin selection uses, so it's always correct.
BalanceText = Fmt(cache.SpendableSats);
var pending = cache.History.Where(t => t.Height <= 0).Sum(t => t.DeltaSats);
UnconfirmedText = pending != 0
? $"{Loc.Tr("msg.pending")}: {(pending > 0 ? "+" : "")}{Fmt(pending)} — {Loc.Tr("msg.notspendable")}"
: "";
ImmatureText = cache.ImmatureSats != 0
? $"{Loc.Tr("msg.immature")}: {Fmt(cache.ImmatureSats)} — {Loc.Tr("msg.notspendable")}"
: "";
// Progressive verification (§7.4): funds confirmed by the server but whose Merkle
// proof background verification hasn't reached yet — same "not spendable" treatment
// as immature/pending, distinct wording so it doesn't read as a maturity/confirmation problem.
VerifyingText = cache.PendingVerificationSats != 0
? $"{Loc.Tr("msg.verifying")}: {Fmt(cache.PendingVerificationSats)} — {Loc.Tr("msg.notspendable")}"
: "";
ReceiveAddress = _account.GetReceiveAddress(cache.NextReceiveIndex).ToString();
History.Clear();
foreach (var tx in cache.History)
History.Add(new HistoryRow(
tx.Height > 0 ? tx.Height.ToString() : "mempool",
(tx.DeltaSats >= 0 ? "+" : "") + Fmt(tx.DeltaSats, withLabel: false),
tx.Txid,
tx.Verified,
Profile.IsAboveNewestCheckpoint(tx.Height)));
Addresses.Clear();
foreach (var a in cache.Addresses)
Addresses.Add(new AddressRow(
a.IsChange ? _loc["addr.change"] : _loc["addr.receive"],
a.Index,
a.Address,
a.BalanceSats > 0 ? Fmt(a.BalanceSats, withLabel: false) : (a.TxCount > 0 ? "0" : "—"),
a.TxCount > 0 ? a.TxCount.ToString() : "—",
a.IsChange,
_account.GetPublicKey(a.IsChange, a.Index)?.ToHex() ?? "",
$"m/{_doc!.AccountPath}/{(a.IsChange ? 1 : 0)}/{a.Index}",
!_account.IsWatchOnly));
}
}
Loaded 100 of 225 files, more files were not shown because too many files have changed in this diff. Show more