ReSatoshi Android connection modes — 0.1.20-preview (internal build 38)
=================================================

Server mode is the initial and upgrade default. Settings > Connection mode / Server / Full node selects one fixed backend for the app. A mode change closes wallet
sessions, monitoring clients and prepared payments. The same signing keys,
derivation path, secure storage and backup formats are used in both modes.
Failures in full-node mode never fall back to Electrum.

Server mode retains the previous TLS/genesis-checked Electrum backend. Full-node
mode uses the on-device Resatoshi Core node for balance, UTXOs, transaction
history, source transactions, mempool validation and sendrawtransaction/P2P
broadcast. Hot wallets and watch-only QR workflows use the same routing.
Signing remains in the existing app; Core receives only public descriptors.
Full-node mode disables Electrum receipt subscriptions and refreshes locally.

Remove local node data
----------------------
The bottom connection-mode action switches to server mode, closes wallet
sessions, stops Core and deletes fullnode-index-v1 plus public-script-index-v1.
It includes public Core wallets, old recovery archives and descriptors. App
signing wallets, recovery phrases and submission journals are not in these
roots and are preserved. Only Core registration flags are removed from app
preferences. Partial deletion resumes before any later Core start. Shutdown uses one timed
startup-lock/process-exit budget; file deletion time is separate. Optional app
registration-cleanup failure is reported separately from completed deletion. Reusing the
node requires a fresh synchronization. Chain resynchronization is a different
action: it preserves public Core wallets and starts downloading immediately.

Fast repeated balance reads
---------------------------
The public script/path index is cached in atomic no-backup app files. It survives
wallet-session reopening and chain-only recovery; it contains no private keys or
balances. Actual cached UTXO paths are rederived before acceptance. Missing or
invalid cache data rebuilds safely. Full recovery always rebuilds the index.
Independent UTXO reads use the bridge's two workers, with one funding-transaction
read per TXID per scan. Live chain and source verification remain required.
See LICENSE-REVIEW.txt for the reviewed distribution and bundled source notices.

Readiness and local wallet recovery
----------------------------------
The node must report the correct genesis/mainnet, index expiry mode, pruning,
no initial download, and equal block/header heights. A Core watch-only descriptor
wallet is named rst_<account discovery hash>. Its receive/change descriptors
cover addresses 0..1999. Registration imports timestamp zero, then checks that
Core has finished scanning and processed the exact current chain tip.

The app records successful registration separately: an interrupted/failed import
must never be mistaken for a full historical scan just because descriptors are
present. The node loads every registered public wallet at startup so pruning
cannot outrun a wallet while its UI is locked. Core next_index and previous
public discovery hints prevent address reuse after funds have been spent.

Each offered confirmed output is checked against gettxout including the local
mempool, its owned script, amount, height/maturity, raw transaction and txid.
A changed tip rejects the snapshot. Source raw transactions remain available
from the local watch wallet for QR PSBTs. History uses up to 1000 recent Core
transaction entries and discloses the cap; balance queries all available UTXOs.
Sending rechecks readiness, the reviewed tip, peer availability and local
mempool acceptance. Closing the wallet during asynchronous validation cancels
any later send. A stopped/syncing node clears balances and prepared payments.

A restored wallet whose earlier blocks have been pruned is not shown with a
partial/zero balance. The app first installs its public descriptors, then asks
the user to stop the node and choose Chain resynchronization / wallet recovery.
A refused historical scan preserves any existing successful registration, so
ordinary balance refresh remains usable for an already complete wallet.

Recovery deletes only blocks, chainstate/snapshots, optional indexes, mempool
cache and the corruption latch, including old chain-quarantine copies. Core
public wallets, descriptors and app signing storage stay in place. Deletion is
irreversible and the confirmation explains this. It starts a fresh validated
chain rather than running -reindex against a corruption latch. An AtomicFile
journal commits the allowed deletion plan first. Partial deletion resumes before
Core starts, including old pre-upgrade move journals. Cache symlinks are unlinked
without following them into wallet directories. The 3 GiB startup check runs
after cleanup so recoverable chain space can be reclaimed first.

Networking is initially disabled. At height zero, the service verifies actual
loaded public SQLite wallets and their supported receive/change descriptors,
then persists the verified descriptor set before enabling P2P downloads. The
public JSON cache alone is not an attestation. After full synchronization,
registration can be completed for those exact preloaded descriptors. The proof
persists across node restarts and unfinished download can resume with Node start.
Only the chain is reconstructed; signing keys still require their own backup.

The public script-to-path index is cached for one wallet session. Its first
build yields after each 16 addresses and an interrupted build is discarded.
Every refresh still checks current Core UTXOs, mempool spends and the chain tip.

Build and artifacts
-------------------
To rebuild embedded Core, use Node22+, JDK17, SDK36, NDK27.1.12297006,
CMake and host Boost headers >=1.74. The wallet app now uses SDK37.0/NDK28.2
with RN0.88.1; the existing standalone Core executable is unchanged.
Supply the official sqlite-autoconf-3500400.tar.gz source archive. Its SHA256 is
checked against the pinned Core depends recipe. No dependency lock changes.

  python3 scripts/build-android-node.py --sdk <SDK> --sqlite-source <archive>
  npm run typecheck:resatoshi
  npm run test:resatoshi
  RESATOSHI_CORE_BIN=<Core build/bin> node --import tsx scripts/check-local-backend.ts
  cd android
  ./gradlew :app:assemblePreview :app:assembleFullnode :app:lintPreview --offline --no-daemon

Core must have clean tracked files at commit
89089ee5ae02aa4692d041f141487c1f2f5e782f from
https://gitlab.com/rst-group4210239/RST-project.git . The script records Core,
Boost, SQLite-source hash, ABI/API and executable SHA256. Generated build and
native binary directories are git-ignored. Core wallet support uses SQLite
built with the same NDK; only public-key wallets are created by the bridge.
No consensus source changes are needed.

Preview updates org.resatoshi.wallet with the existing development signature.
Fullnode uses org.resatoshi.wallet.fullnode for separate testing. Both default
to server mode. No production signing, publication or installation is implied.
For emulator builds also build the node with --abi x86_64, then use
-PreactNativeArchitectures=x86_64. The custom Android smoke instrumentation is
only in the test APK, requires an emulator and the separate Fullnode package,
and never signs or broadcasts mainnet funds. It accepts a public test xpub and
its discovery-hash wallet name as instrumentation arguments.

Node lifecycle and privacy
--------------------------
Managed settings: index mode, 1024MiB block-file target, 64MiB cache, 32MB
mempool, one validation worker, eight peers, no inbound listening. A 3GiB free
space startup check does not guarantee future capacity: UTXOs, indexes and
public wallet history require additional space. Wi-Fi/charging operation is
advised but not automatically enforced in this preview.

Node data is private to noBackupFilesDir/fullnode-index-v1. Native cookie RPC
binds only to 127.0.0.1:29332. Credentials never cross the JS bridge; a fixed
method allowlist restricts RPC. Creation enforces blank, disabled-private-key
descriptor wallets, and imports enforce the supported public-key pattern/range.
Only loopback permits cleartext. Core P2P peers see network traffic; public
wallet descriptors are not sent to Electrum in full-node mode.

Android runs the node in a foreground dataSync service. User start/rebuild is
explicit, there is no boot restart. Stop uses RPC then SIGTERM, never SIGKILL.
The Android launcher requests SIGTERM on parent death; Core recovery applies
if the OS kills the app. Android 15 service limits still apply. Public Core
wallet records may remain after signing-wallet deletion, as disclosed in the
updated privacy notice. Uninstall/clear-data removes all local app/node data;
keep separate signing-wallet backups.

Physical ARM64 lifecycle, long-term initial sync, battery/heat/storage growth,
and real funded-device/camera/credential workflows remain release checks.
See FULLNODE-VALIDATION.txt for actual test evidence and its limits.

Historical implementation changes are retained in CHANGELOG.txt.
