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.
docs(userguide): document first-sync timing and warn against mining payouts
2026-07-19 12:59:15 +02:00 · 2026-07-19 12:59:02 +02:00
3 changed files with 41 additions and 7 deletions
@@ -8,11 +8,11 @@ Unlike generic wallets adapted to many coins, Palladium Wallet is designed aroun

 - **Lightweight SPV**: syncs against an indexing server (ElectrumX-like protocol) without downloading the full chain.
 - **Security**: seed and private keys encrypted on disk (AES-GCM, PBKDF2-SHA512), never in plaintext in logs or on the wire; every server response is validated with Merkle proofs + checkpoints.
- **HD wallet** (BIP39/BIP32), SegWit/wrapped/legacy addresses, watch-only from xpub.
- **PSBT-centric**: signing flows go through PSBT (offline / air-gapped / multisig).
+- **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.
 - **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.
+- **Multilingual**: Italian, English, Spanish, French, Portuguese, German, Chinese (Simplified).

 ## Architecture

@@ -331,6 +331,9 @@ existing AVD, so create one first (step 3). Point it at the emulator binary:

 ## 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.
@@ -360,15 +363,20 @@ existing AVD, so create one first (step 3). Point it at the emulator binary:
 ### CLI in brief
 ```bash
 # Wallet
-dotnet run --project src/Cli -- create   [--words 12|24] [--kind segwit|wrapped|legacy] [--net mainnet|testnet|regtest] [--password P]
-dotnet run --project src/Cli -- restore  "<mnemonic>" [...]
-dotnet run --project src/Cli -- info     [--net ...] [--password P]
+dotnet run --project src/Cli -- create          [--words 12|24] [--kind segwit|wrapped|legacy] [--net mainnet|testnet|regtest] [--password P]
+dotnet run --project src/Cli -- restore         "<mnemonic>" [...]
+dotnet run --project src/Cli -- restore-xpub    <slip132-key> [--net ...] [--password P]
+dotnet run --project src/Cli -- restore-address <addr1,addr2,...> [--net ...] [--password P]
+dotnet run --project src/Cli -- info            [--net ...] [--password P]

 # Network
 dotnet run --project src/Cli -- sync     [--server host[:port]] [--ssl]
 dotnet run --project src/Cli -- send     --to ADDRESS (--amount X | --all) [--feerate sat/vB] [--broadcast]
+dotnet run --project src/Cli -- servers  [--discover]
 ```
 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.

 ---

@@ -108,3 +108,6 @@ This is a complement to, not a substitute for, independent human or third-party
 - 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
@@ -578,6 +578,29 @@ If the server is overloaded (busy responses), the wallet retries automatically u
 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 back to the nearest hardcoded checkpoint. 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.
+
+**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
@@ -818,7 +841,7 @@ Reset SSL certificates* — see
 | 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; the wallet retries automatically (up to 8 attempts, growing back-off). | Wait; progress is cached, so restarting resumes rather than repeats. |
+| 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). |

 ---