Resatoshi Electrum compatibility lab — NOT a public server deployment

Purpose: exercise real upstream indexing, mempool subscriptions, raw transactions,
TLS, confirmations and reorgs against isolated Resatoshi Core. No mock RPC server.
Pinned upstream: https://github.com/spesmilo/electrumx
Revision: 280cb339aa158e099eb936033eecd15719770651 (ElectrumX 2.0.0, MIT)
Upstream source stays in its own checkout; its MIT notice is also preserved in
LICENSE-ELECTRUMX.txt. Our adapter is covered by the
repository MIT license. Python 3.12 and binary plyvel wheels used for local tests.
No CI files, CI settings, production nodes or real wallets are used or changed.

Example environment setup (outside this repository):
  git clone https://github.com/spesmilo/electrumx /path/to/electrumx
  git -C /path/to/electrumx checkout 280cb339aa158e099eb936033eecd15719770651
  python3.12 -m venv /path/to/venv
  /path/to/venv/bin/python -m pip install --only-binary=:all: -r tools/backend-lab/requirements.txt


Install dependencies into a separate virtualenv with requirements.txt; clone the
pinned upstream and set ELECTRUMX_SOURCE to that checkout. Do not run against an
unreviewed updated checkout. Then run integration.py with:
  RESATOSHI_CORE_BIN=/path/to/resatoshi/build/bin
  ELECTRUMX_SOURCE=/path/to/pinned/electrumx
  NODE_BIN=/path/to/node22/bin
  /path/to/venv/bin/python tools/backend-lab/integration.py

The integration runner creates private disposable data directories, ephemeral
RPC ports and a temporary localhost certificate; no real credentials are stored
in Git. All daemons bind loopback, disable peer discovery/announcement, and use
isolated Core with no P2P connections. The regtest adapter is NOT imported by the
Android app; its production mainnet genesis check is never weakened.

Prototype limitations and release gates
- Bitcoin-derived wire serialization is compatible in the paths exercised, but
  this is not complete consensus/index compatibility certification.
- Resatoshi expires outputs without normal spending inputs. Unmodified Bitcoin
  indexers retain these in their UTXO index. The adapter filters them at query
  time for listunspent/get_balance using the next spend height. The underlying
  stale index entries remain; production sizing/compaction and other protocol
  endpoints need review. Only protocol 1.4–1.4.3 is advertised.
- No synthetic history entries are invented for expiry. Clients must reconcile
  expiry on header changes; expiry-specific subscription behavior needs review.
- Upstream's forward-block polling did not handle a shortened Core tip in this
  experiment. The lab adapter queues a bounded rollback only when the shorter
  tip hash matches the indexed prefix, and publishes the caught-up rollback.
  Divergent shorter chains, deep reorgs and interrupted rollback need further
  review. This is prototype behavior, not a production sync engine certification.
- Reorg/expiry and mempool results must be compared with Core, including rollback
  across expiry boundaries and persistence. Passing lab cases is not sufficient
  to certify every scenario or public capacity.
- Fixture-generated keys/phrases are public test data. Do not fund them.
- Temporary test certificate is trusted only by the lab client. Android phones
  need a real hostname and a publicly trusted TLS certificate for actual use.
- Mainnet genesis with an empty isolated chain checks connection separation only;
  it is not a mainnet funded-transaction or physical-phone test.
- No VPS has been provisioned. A real server, domain, TLS and physical phone(s)
  are still required for the device release gate. This harness is not installation
  automation, an unaudited new public backend, or a claim of production readiness.

Diagnostics
The fixture wallet bridge counts logical RPC requests and wire request frames;
it does not log seeds or credentials. The runner allows 300 seconds for a scan.
The historical unbatched empty-account scan took 140664ms / 4044 RPC requests.
The updated bridge checks cold full recovery, a persisted-hint refresh on a new
connection and manual full recovery. See docs/DISCOVERY-PERFORMANCE.txt for the
complete rerun and limitations. Full recovery coverage is not reduced. Local
server cost thresholds are deliberately raised for the lab workload; these are
NOT production rate-limit recommendations.
Set LAB_SKIP_MAINNET=1 only for targeted debugging; the results explicitly record
that skip and cannot be presented as a complete run. Final verification omits it.
