Merge upstream v1.2.18 into the fork

Merges upstream tag v1.2.18 (bc3de30) into our 24 commits. The merge base is
a259215, upstream's own commit, whose src/ tree is byte-identical to 68de575 --
our commits were replayed onto a259215 first so that git had a real base to work
from. That produced 28 conflict hunks in 9 files instead of the 21 conflict
events / 51 hunks a direct cherry-pick onto the tag would have forced, most of
which were artifacts of lifting our commits away from their own predecessors.

No consensus change. main.cpp's GetBlockValue, GetNextWorkRequired,
ConnectInputs, ConnectBlock, CheckBlock, AcceptBlock and AcceptTransaction are
untouched by this merge; script.cpp, serialize.h and randomx_pow.h are
identical on both sides. The frozen-chain oracle reproduces the pinned UTXO root
116a2b6b... byte for byte, and the merged binary loads the same 12,586-block
chain to the same tip aac622f0a3b2f8... with all blocks re-verified and none
rejected.

Which side won, per file and per hunk.

src/rpc.cpp -- 15 hunks.

1. RebuildJob transaction selection. THEIRS for the multi-pass loop and the
   nFees fix, OURS for the cap. Their vfAlreadyAdded/fFoundSomething loop lands
   dependent transactions that our single pass dropped deterministically, and
   their nFees is accumulated across the scan instead of being redeclared inside
   it -- ours passed a hardcoded 0 to GetBlockValue, so every pool block built
   here discarded its fees. But their bound is MAX_SIZE/2 = 16 MB, and
   MAX_BLOCK_SIZE is 1 MB, so their template can exceed what their own
   CheckBlock accepts. Cap kept at MAX_BLOCK_SIZE/2, with our inner break so a
   single pass cannot overshoot by more than one transaction. Our RebuildJob
   sync gating and deaf-node detection are kept; upstream has none.

2. struct PendingPayout. OURS for the key, THEIRS for paidTxids. Their id is
   the string "block-<height>", which is height keying -- the exact bug 44849e6
   fixed after a 280-block reorg left ~14.4k BTF owed against blocks that no
   longer existed. Height keying also lets the crash-recovery probe match the
   previous round's transaction after a reorg and silently skip a miner, so
   their id is dropped entirely and blockHash stays the key. paidTxids is taken
   because it is what makes an entry survivable. Their nextAttempt and our
   retryAfter are the same concept under two names; ours is kept and theirs
   dropped. matureAtHeight gained an explicit = 0, which neither side had in
   our style of initialiser.

3./4. Ledger writer and loader. Mechanical follow-ons of 2. The loader keeps
   ours and takes their tolerance for an entry with no usable height, guarded so
   it cannot fire on a well-formed entry. One redundancy was removed rather than
   merged: their unguarded `if (obj.contains("blockHeight")) get<int>()` sat two
   lines above our is_number-guarded version, and an unguarded get<int>() on a
   malformed value throws out of the whole loop, losing every entry in the file.
   Verified against the live production pending_payouts.json (2 entries, keys
   amounts/blockHash/blockHeight/matureAtHeight): loads both. A file in the new
   shape, with retryAfter and paidTxids, also loads.

5. Insertion point after the loader. BOTH. Our PayingRecord/gPaying in-flight
   ledger and their PoolRoundProof/PoolRoundToJson are disjoint features that
   landed at the same offset. Both kept, in full.

6. Writer tail. THEIRS, copied into our writer. Checking fclose() matters here
   because fclose is where the buffered write actually reaches the OS: renaming
   a short .tmp over a good file is precisely the truncation the atomic write
   exists to prevent. The Windows remove()-before-rename() is required because
   rename() there will not replace an existing file.

7. Loader bodies. BOTH -- LoadPaying and LoadPoolRounds are different functions
   that happened to share a common tail.

8. Function block, 111 vs 36 lines. BOTH, with one deliberate deletion.
   PayoutBlockStillOnChain, PayoutComment, RecordPoolRound, MarkPoolRoundPaid
   all kept. WalletAlreadyPaid is DELETED and ReconcilePayouts rewritten,
   because our reconciliation and their FindRecordedPoolPayout are two answers
   to the same crash-recovery question and running both would give the same debt
   two authorities. Their wallet probe wins: it matches structured metadata
   rather than a comment string, so it can tell two rounds paying the same
   address the same amount apart. ReconcilePayouts keeps only the job that is
   still real -- dropping in-flight records the ledger already shows paid, and
   arming each restored record for its one wallet probe. It no longer touches
   gPendingPayouts at all; under the new model dropping ledger entries there
   would reintroduce the loss this merge adopts their model to prevent. Their
   gPayoutExecMutex/gPayoutThreadRunning re-declarations were dropped as
   duplicates of ours, and gPayoutExecQueue was not taken: gPaying is the exec
   queue in this tree, at finer granularity.

9. QueuePayouts signature. THEIRS for the round-proof arguments, OURS for the
   type of blockHash. It stays a uint256 and is converted to hex only where the
   round proof needs text -- a ledger key that has been through ToString() is a
   key that can be compared wrong.

10. Maturity policy. OURS. matureAtHeight = blockHeight +
    COINBASE_SPENDABLE_DEPTH (120), not + COINBASE_MATURITY (100). At depth 100
    the block's own coinbase is still 20 blocks short of spendable, so the
    payment must come from unrelated mature coin and the pool runs a permanent
    float. Our own history contradicts itself here -- d6972a0 argued for
    COINBASE_MATURITY citing "96% of 934 payments", 44849e6 reversed it on the
    grounds that the measurement was taken while the node was alone on a private
    fork paying itself. HEAD's position is kept. This is a considered
    disagreement with upstream, not an oversight. The live production ledger
    confirms it: both entries have matureAtHeight - blockHeight = 120.

11. Comment above FlushMaturePayouts. Rewritten to describe the merged design.

12. FlushMaturePayouts, the central difference. THEIRS for the model. The ledger
    entry now survives on disk until every recipient has a txid, instead of
    being erased as soon as its payments were handed off -- the old ordering
    left a window where the debt was described by nothing at all, and a
    container restart on 2026-07-30 silently dropped ~1,156 BTF through it. Our
    gPaying is kept on top as the in-flight working set, because it carries the
    per-recipient retry and deferral state a per-round nextAttempt cannot
    express. It is explicitly a cache derived from the ledger, not a second
    record of debt: if it were lost the next flush would rebuild it.

13. PayoutThreadFn, 79 vs 70 lines. OURS for the loop and the reorg re-check,
    THEIRS for the per-recipient dedupe. The re-check on every attempt is
    load-bearing and upstream has no equivalent -- it decides once, at maturity,
    and a payment can sit through hours of retries during which the reorg that
    kills its funding block can land. Their paidTxids check is taken, against
    the ledger rather than against the batch. Our deferral policy is kept:
    waiting for coin is not a failure and must not consume the retry budget.

    Two fixes upstream does not have are folded in here rather than deferred to
    a follow-up commit:

    - FindRecordedPoolPayout runs once per record, on its first attempt, not on
      every attempt. It is a linear scan of mapWallet under cs_mapWallet, per
      recipient; upstream repeats it for every retry, which with 2000 rotating
      payout addresses and a budget of 1440 retries is a full wallet scan per
      address per minute for a day. The question it answers can only change
      across a restart, and every restart re-arms the flag.
    - The ledger file write no longer happens under gPayoutLedgerMutex in the
      per-recipient loop. SavePendingPayoutsLocked was split into a serialise
      step that needs the lock and a write step that does not, so the mutex is
      held only long enough to read the structure. The orphan scan in
      FlushMaturePayouts was likewise restructured so the ledger mutex is not
      held across PayoutBlockStillOnChain's cs_main acquisition.

    One case the merged model created and neither side handled: under
    survives-until-fully-paid, our GIVING UP path dropped the in-flight record
    but left the recipient owed in the ledger forever, so every later flush
    would explode it again -- a forfeit that silently becomes an infinite retry.
    ForfeitPayoutRecipient writes the amount off so the entry can retire.

14. QueuePayouts call site. Follow-on of 9.

15. ThreadRPCServer startup. BOTH. LoadPoolRounds added; LoadPaying and
    ReconcilePayouts stay, and stay before the payout thread starts.

    Crash safety, stated as the property that must hold: after kill -9 at any
    point, restart pays each recipient exactly once. Before SendMoney, the
    ledger has no txid and the payment is retried. Between SendMoney and the
    ledger write, the wallet holds the transaction and the first-attempt probe
    finds it. After the ledger write, paidTxids suppresses it. If the in-flight
    file is lost entirely, the ledger rebuilds it and the probe still covers the
    middle window.

src/nostr.cpp -- 3 hunks. THEIRS as the base, with two things restored from
ours. Theirs loads the Windows ROOT certificate store, which ours lacks and
genuinely needs, since OpenSSL's default verify paths are usually empty there
and our version would fail closed. But the plan's claim that theirs is a
superset of our 06bceb4 is FALSE: upstream's nostr.cpp contains no
min_proto_version, no TLS1_2, no SSL_OP_NO_*, and no set_options anywhere, so
taking it wholesale would have removed the TLS-version floor outright. Restored.
Second, their SSL_get_verify_result check sits after a successful handshake,
where with SSL_VERIFY_PEER set it is nearly dead code -- a bad certificate
aborts inside SSL_connect. The reporting belongs in the failure branch, which is
where the merge put it; their post-handshake duplicate was dropped. Our
relay-list and socket-pooling hunks auto-merged and were verified intact.

src/net.cpp -- 1 hunk. THEIRS. Their guard, hSocket == INVALID_SOCKET ||
pnode->hSocket != hSocket, subsumes ours and additionally catches descriptor
recycling, which ours did not; our version also referenced a pnode that only
existed in the select() loop. Our other db34011 hunk, nulling pnode->hSocket in
the poll-failure branch, auto-merged and was NOT re-applied -- plan section 7
Batch D says to re-apply it, and that instruction is stale. Two pieces of
residue the merge left behind were cleaned up: a comment still describing
select() semantics, and a pnode->hSocket != INVALID_SOCKET guard made redundant
by a continue two lines above it.

src/main.cpp -- 2 hunks. h1 BOTH, pure add/add adjacency between our
ParticipantHashThreadCount and their SecureClear forward declarations. h2 OURS,
and their handler discarded: 44004e3 no-ops checkorder/submitorder but keeps
market.cpp and market.h, whereas 11766be deletes the marketplace outright
including CRequestTracker, subscribe/publish and mapProducts. Ours is strictly
more.

src/main_gui.cpp -- 2 hunks. BOTH, additive on both sides. Our /payoutaddr,
/payoutfile and /hashthreads alongside their /stratumbridge and
/stratumbridgeport.

src/btfrv.cpp -- 1 hunk, not predicted by the plan. False adjacency: our
INVALID_SOCKET check and their #endif landed at the same offset. Ordering is
load-bearing -- our check goes inside the #else arm, before the #endif, or the
non-proxy build silently loses it. The BITFLASH_NODE_BUILD arm already returns
early, so both paths now have the check.

Makefile -- 2 hunks plus a hazard with no conflict marker. THEIRS for both
dependency-fetch recipes: checkout --detach FETCH_HEAD followed by test
"$(git rev-parse HEAD)" = "$(..._COMMIT)" asserts the pin actually landed, where
ours only checked it out. Everything of ours that they lack is kept: the
appimagetool 1.9.1 release pin with a sha256 check, where upstream fetches the
mutable "continuous" tag and executes it undigested, and the move of both the
tool and the AppDir out of /tmp, where any local user could pre-place an
executable and have it run as whoever runs make.

The hazard: both sides added a pin block in a different place, so git merged
both, outside any conflict region. SECP256K1_COMMIT and RANDOMX_COMMIT ended up
assigned twice, near L16 and near L44, and GNU Make takes the last := -- a naive
resolution would have silently built against our old secp256k1 pin while
appearing to adopt upstream's. The duplicate block was deleted by hand. Each of
the four variables is now assigned exactly once, and make -n resolves
SECP256K1_COMMIT to 7fecac74 with 6e2c8bc4 appearing nowhere.

Also applied here, from plan phase 4: SECP256K1_COMMIT moved to upstream's
7fecac74aed8e1fd9078380d67dd04663705c989 so signature validation matches the
binaries the rest of the network runs. secp256k1 was rebuilt from scratch
against the new pin on the build host and the checked-out dependency commit
verified. RANDOMX_COMMIT already matched at 1e9d4b2d and is unchanged.

src/Makefile, src/makefile.mingw -- 1 hunk each, both the HEADERS list. Ours
drops market.h, theirs adds proxy.h; the resolution does both. Taking theirs
wholesale would have left the Makefiles referencing a header git had already
deleted in our favour, silently, without a conflict.

Files the plan predicted would conflict and did not: net.h, main.h and db.cpp
auto-merged. Verified rather than assumed. net.h carries both our
BTF_MSG_WAIT_MAX_SECS work, including the constructor fix from 2d84982 that
starts nMsgWaitSince and nMsgWaitSize at 0, and their comment rewrite with
extern int nPeersWatched. The dead members that fix removed are gone from every
file.

Deviations from MERGE-1.2.18-PLAN.md.

- Section 6's mechanism was not used. Replayed onto the real merge base and
  merged, rather than cherry-picking onto the tag. Same result, 28 hunks
  instead of 51.
- Section 2 calls 09ff575 a superset of our 06bceb4. It is not; upstream has no
  TLS-version floor at all. Ours restored on top of theirs.
- Section 7 Batch D says to re-apply our db34011 line into their poll-failure
  branch. It auto-merged; re-applying would have duplicated it.
- Section 2 says do not take the stratum bridge. It is taken, and left off.
  fStratumBridge defaults false in main.cpp, the thread is only spawned when
  /stratumbridge is passed, and the listener binds 127.0.0.1 only. Excising it
  would cost real divergence and future conflict for no gain while it is
  disabled. Its defects -- select()/FD_SET on a node that can hold more than
  1024 descriptors, and an uncapped thread per connection -- are real only when
  it is enabled and are being reported upstream separately.
- Section 7's staged batches were not run as separate gated commits. The
  conflict surface is interleaved within single functions, chiefly the payout
  ledger, and splitting it would have meant committing states that do not
  build. The merge is one commit, as briefed.
- Batch F's two fixes are folded into hunk 13 rather than deferred, because
  they change the same lines the resolution rewrites.
- The plan did not anticipate the btfrv.cpp conflict, the duplicate pin block,
  the market.h trap in the two Makefiles, or the give-up/infinite-retry
  interaction created by adopting upstream's ledger model.

10 files changed, 825 insertions, 28 deletions

diff --git a/docs/dependencies.md b/docs/dependencies.md
new file mode 100644
index 0000000..9fd45b6
--- /dev/null
+++ b/docs/dependencies.md
@@ -0,0 +1,18 @@
+# Build Dependencies
+
+Bitflash links consensus-adjacent cryptographic and proof-of-work code from
+external repositories. Fresh builds must not follow upstream `master` silently:
+a changed upstream branch can break reproducible builds or change behavior in
+code that every node relies on.
+
+The top-level `Makefile` pins source dependencies by full commit hash:
+
+| dependency | repository | pinned commit |
+|---|---|---|
+| libsecp256k1 | https://github.com/bitcoin-core/secp256k1 | `7fecac74aed8e1fd9078380d67dd04663705c989` |
+| RandomX | https://github.com/tevador/RandomX | `1e9d4b2df63fa6edf46b06789486e23c0fcaa55a` |
+
+When updating either dependency, rebuild from a clean dependency directory and
+run the full selftest suite before opening the PR. The PR should explain why the
+dependency changed and whether the update can affect consensus, addresses,
+signatures, proof-of-work validation, or mining.
diff --git a/docs/fair-launch.md b/docs/fair-launch.md
new file mode 100644
index 0000000..9603910
--- /dev/null
+++ b/docs/fair-launch.md
@@ -0,0 +1,70 @@
+# Bitflash fair-launch verifier
+
+Bitflash ships a deterministic fair-launch audit script:
+
+```bash
+python3 scripts/verify-fair-launch.py --max-blocks 1000 --out bitflash-fair-launch-report.json --json
+```
+
+The verifier reads `blk*.dat` directly from the local Bitflash data directory.
+It does not use Berkeley DB, does not call the node binary, and does not need
+network access. It uses the same shared Python chain parser as the UTXO
+commitment and proof tools, so block serialization fixes land in one place.
+
+The report proves the launch baseline that can be checked from the chain:
+
+- the genesis block hash matches the source constant;
+- the genesis merkle root matches the source constant;
+- the genesis transaction is a single coinbase transaction;
+- the genesis output total is exactly `50.00000000 BTF`;
+- the scanned block range and mined coinbase total are reproducible.
+
+For machines that do not have a synced data directory yet, the source constants
+can be checked without disk blocks:
+
+```bash
+python3 scripts/verify-fair-launch.py --reconstruct-genesis
+```
+
+## Deterministic output
+
+Use `--json` or `--out` for canonical JSON. The JSON is written with sorted
+keys, fixed separators, ASCII escaping, and one trailing newline. It deliberately
+does not include local paths or wall-clock generation time, so two auditors
+scanning the same block range produce the same bytes.
+
+That makes the report shareable:
+
+```bash
+python3 scripts/verify-fair-launch.py --max-blocks 1000 --out report.json --json
+sha256sum report.json
+```
+
+If another auditor runs the same command against the same chain prefix, the
+`sha256sum` should match.
+
+## OpenTimestamps
+
+OpenTimestamps is optional and external. It anchors the report in Bitcoin
+without adding any bridge or dependency to Bitflash consensus.
+
+After generating a canonical JSON report:
+
+```bash
+ots stamp report.json
+ots verify report.json.ots
+```
+
+The `.ots` file proves that the exact report bytes existed no later than the
+Bitcoin block that confirms the timestamp.
+
+## What this does not claim
+
+This is not a retroactive genesis commitment. The Bitflash genesis block already
+exists, so adding a new on-chain commitment to genesis would create a different
+chain. This verifier instead audits the launch state that is already on-chain
+and makes the result reproducible and timestampable.
+
+It also does not prove real-world miner identity. It proves the genesis state,
+the absence of non-coinbase premine in genesis, and the deterministic coinbase
+totals over the scanned prefix.
diff --git a/docs/mining-calculator.md b/docs/mining-calculator.md
new file mode 100644
index 0000000..352eea1
--- /dev/null
+++ b/docs/mining-calculator.md
@@ -0,0 +1,86 @@
+# Bitflash mining calculator
+
+`scripts/bitflash-mining-calculator.py` is a local WhatToMine-style calculator
+for Bitflash.
+
+It does not fetch market prices, does not talk to exchanges, and does not
+change consensus. Price is a manual input until Bitflash has a reliable public
+market.
+
+## Examples
+
+Estimate from network hashrate:
+
+```bash
+python3 scripts/bitflash-mining-calculator.py \
+  --hashrate 21 --hashrate-unit kh/s \
+  --network-hashrate 1.56 --network-hashrate-unit mh/s \
+  --watts 140 --kwh-cost 0.10 \
+  --price 0.001 --pool-fee 1
+```
+
+Estimate from Bitflash difficulty:
+
+```bash
+python3 scripts/bitflash-mining-calculator.py \
+  --hashrate 21 --hashrate-unit kh/s \
+  --difficulty 45600 \
+  --watts 140 --kwh-cost 0.10
+```
+
+Machine-readable output:
+
+```bash
+python3 scripts/bitflash-mining-calculator.py \
+  --hashrate 21 --hashrate-unit kh/s \
+  --network-hashrate 1.56 --network-hashrate-unit mh/s \
+  --json
+```
+
+## Bitflash Difficulty Scale
+
+Bitflash does not use Bitcoin's SHA256 difficulty-1 constant for pool shares.
+The chain's easiest RandomX target is `bnProofOfWorkLimit = ~uint256(0) >> 12`,
+so difficulty 1 expects about `4096` hashes.
+
+The calculator uses:
+
+```text
+network_hashrate = difficulty * 4096 / block_time_seconds
+```
+
+At the default two-minute block target:
+
+```text
+network_hashrate = difficulty * 4096 / 120
+```
+
+If you already know network hashrate, pass `--network-hashrate` directly and
+the script derives the equivalent Bitflash difficulty for display.
+
+## Reward Estimate
+
+The expected daily reward is:
+
+```text
+blocks_per_day = 86400 / block_time_seconds
+miner_share = miner_hashrate / network_hashrate
+gross_btf_per_day = blocks_per_day * block_reward * miner_share
+net_btf_per_day = gross_btf_per_day * (1 - pool_fee_percent / 100)
+```
+
+Electricity is:
+
+```text
+electricity_per_day = watts / 1000 * 24 * kwh_cost
+```
+
+This is an expectation, not a promise. Solo mining variance can be very large,
+especially when the miner has a small share of the network.
+
+## Future Website Use
+
+The script is intentionally standalone so the same math can later back a
+website widget or status dashboard. Until a public price exists, a website
+calculator should keep price as a manual field and label fiat profit as
+speculative.
diff --git a/docs/pool-directory.md b/docs/pool-directory.md
new file mode 100644
index 0000000..76269b9
--- /dev/null
+++ b/docs/pool-directory.md
@@ -0,0 +1,43 @@
+# Public Pool Directory
+
+`pool.bitflash.network` should be a public directory, not a network dependency.
+Nodes discover pools through Nostr and `.btf`; the website only helps humans
+compare operators.
+
+Operators can publish the `pool_status.json` and `pool_rounds.json` files
+produced by:
+
+```bash
+bitflash -nogui -gen -operator \
+  -poolstatusfile=/var/www/pool_status.json \
+  -poolroundsfile=/var/www/pool_rounds.json
+```
+
+Build a static directory from one or more status files:
+
+```bash
+python3 scripts/build-pool-index.py --out-dir public/pool \
+  https://operator-one.example/pool_status.json \
+  https://operator-two.example/pool_status.json
+```
+
+The generated output contains:
+
+- `index.html`: human-readable ranking page.
+- `pools.json`: machine-readable API for `api.bitflash.network/pools.json`.
+
+When a source is an HTTP(S) `pool_status.json`, the directory links to a
+`pool_rounds.json` proof file next to it. That file records the block height,
+block hash, coinbase txid, coinbase value, pool fee, total shares, per-address
+share counts, computed payouts, and payout txids once paid.
+
+Ranking order is intentionally simple:
+
+1. online pools first;
+2. higher reported hashrate;
+3. more authorized miners;
+4. lower fee;
+5. name as a stable tie-breaker.
+
+An entry is considered online when the source says the pool is running and its
+status file is no more than 120 seconds old.
diff --git a/docs/release-verification.md b/docs/release-verification.md
index ecacd5f..32de74f 100644
--- a/docs/release-verification.md
+++ b/docs/release-verification.md
@@ -3,60 +3,82 @@
 Bitflash releases publish binaries and a `SHA256SUMS` file. The checksum file
 proves that the file you downloaded matches the file the release page names.
 A detached signature, `SHA256SUMS.asc`, proves that the checksum file itself was
-signed by a trusted release key.
+signed by the Bitflash release key.
 
 That gives users two separate checks:
 
-1. `gpg --verify SHA256SUMS.asc SHA256SUMS` checks who signed the checksums.
-2. `sha256sum -c SHA256SUMS` checks the binaries against those checksums.
+1. `gpg --verify SHA256SUMS.asc SHA256SUMS` — who signed the checksums.
+2. `sha256sum -c SHA256SUMS` — the binaries against those checksums.
 
-## User Check
+But the first check is only worth something if you require a **specific** key.
+A good signature by *some* key proves nothing; anyone can make one.
 
-From a shell with `curl` or `wget` and `sha256sum`:
+## The release signing key
 
-```bash
-scripts/verify-release.sh latest
+```text
+fingerprint  910A 2B4C CA87 9E81 FB4B  2AEA 1D4A 53D3 B78A A4B8
+uid          Bitflash Releases (bitflash.network release signing)
+             <releases@bitflash.network>
 ```
 
-For a specific release:
+The public key is published at
+`https://releases.bitflash.network/bitflash-release-key.asc` and embedded in
+`scripts/verify-release.sh`, so the tool's trust anchor lives in this
+repository rather than on the server it verifies.
+
+## User check
+
+From a shell with `curl` or `wget`, `sha256sum` and `gpg`:
 
 ```bash
-scripts/verify-release.sh v1.2.13
+scripts/verify-release.sh latest
 ```
 
-For release audits, require the signature:
+For a specific release:
 
 ```bash
-scripts/verify-release.sh v1.2.13 --require-signature
+scripts/verify-release.sh v1.2.15
 ```
 
-Older releases may not have `SHA256SUMS.asc`. In that case the script warns and
-still checks file integrity. New release audits should use `--require-signature`.
-
-## Maintainer Flow
+The script downloads the release, imports the pinned key into a throwaway
+keyring, and **refuses anything that is not a valid signature by the key above**
+before checking the hashes. Releases from before signing was introduced ship
+only `SHA256SUMS`; without `--require-signature` those are checked for integrity
+and reported as unsigned.
 
-After building release assets in the repository root:
+By hand, if you would rather not run the script:
 
 ```bash
-scripts/make-release-checksums.sh --sign --local-user RELEASE_KEY_ID
+curl -O https://releases.bitflash.network/bitflash-release-key.asc
+gpg --import bitflash-release-key.asc
+gpg --verify SHA256SUMS.asc SHA256SUMS   # must name the fingerprint above
+sha256sum -c SHA256SUMS
 ```
 
-Upload all built assets plus:
+## Maintainer flow
 
-```text
-SHA256SUMS
-SHA256SUMS.asc
+The signing key lives on a dedicated location, not in the build tree. After
+building the release assets in the repository root, write and sign the
+checksums:
+
+```bash
+sha256sum Bitflash-*.zip Bitflash-*.AppImage bitflash-node-* > SHA256SUMS
+gpg --armor --detach-sign --output SHA256SUMS.asc SHA256SUMS
 ```
 
-Keep the private signing key offline or on a dedicated release machine. Publish
-the public key fingerprint in the release notes and keep using the same key for
-future releases unless there is a clearly announced rotation.
+Publish, alongside the assets, `SHA256SUMS` and `SHA256SUMS.asc`, and update
+`latest.txt` on the releases host to the new tag. Keep using the same key; if it
+is ever rotated, announce the new fingerprint clearly and update the embedded
+key in `verify-release.sh`.
 
-## Why This Matters
+## Why this matters
 
 `SHA256SUMS` alone protects against a broken download, but not against someone
-replacing both a binary and the checksum file. Signing `SHA256SUMS` means an
-attacker must also have the release signing key to make the replacement verify.
+replacing both a binary and the checksum file. Signing `SHA256SUMS`, and
+requiring a pinned key, means an attacker must also hold the release signing key
+to make the replacement verify. Serving from bitflash.network makes this the
+guarantee that matters: without a pinned key, "trust the site" is the only
+thing standing behind a download.
 
 This is not reproducible builds yet. It is the smaller, immediate step that
-makes every release asset auditable by users before they run it.
+makes every release asset auditable before anyone runs it.
diff --git a/docs/rendezvous.md b/docs/rendezvous.md
new file mode 100644
index 0000000..ac8e598
--- /dev/null
+++ b/docs/rendezvous.md
@@ -0,0 +1,288 @@
+# Bitflash `.btf` Rendezvous Protocol
+
+This is the specification of how Bitflash nodes reach each other, and how miners
+reach pools, without revealing an IP address and without any central directory.
+It documents the protocol as implemented in `src/btfaddr.cpp`, `src/btfchan.cpp`,
+`src/btfrv.cpp`, `src/btftunnel.cpp` and `src/nostr.cpp`.
+
+The design is ported from the Itzal hidden service design. A `.btf` address names
+a public key, a node proves ownership of that key by signing a service
+descriptor, other nodes find the descriptor over Nostr, and the two sides then
+meet through an untrusted relay over an end to end encrypted tunnel. The relay
+carries ciphertext only and never learns the plaintext.
+
+## 1. Overview
+
+A connection to a `.btf` service has three layers:
+
+1. **Discovery (Nostr).** The service publishes a signed descriptor as a Nostr
+   event. A caller fetches it by the service public key and verifies the
+   signature. The descriptor says which rendezvous relay the service is waiting
+   at and which encryption key to use.
+2. **Rendezvous (TCP).** Caller and service both connect out to the same relay
+   and are paired by public key. Neither needs an inbound port or a public IP.
+   After pairing the relay is a blind byte pipe.
+3. **Encrypted channel (X25519 + XChaCha20-Poly1305).** Over the paired pipe the
+   caller and service run an ephemeral to static handshake and then exchange
+   authenticated frames. The relay sees only ciphertext.
+
+The caller ends up holding an ordinary local socket that behaves like a direct
+TCP connection to the peer. The node treats it exactly like any other peer
+socket.
+
+## 2. Identities and keys
+
+A node holds two independent keypairs.
+
+- **Signing / identity key**: a secp256k1 x-only key (BIP340 Schnorr). This is
+  the `.btf` identity and also the node's Nostr identity. Persisted in
+  `nostr.key`.
+- **Encryption key**: an X25519 (Curve25519) keypair. Persisted in
+  `btf_enc.key`. Its public half is published in the descriptor as `enc` and is
+  used for the tunnel key agreement.
+
+The identity key names the service and authenticates the descriptor. The
+encryption key secures the tunnel. They are separate so the long term identity
+never performs Diffie-Hellman and the encryption key can be rotated in a new
+signed descriptor.
+
+## 3. The `.btf` address
+
+An address is the identity public key plus a short checksum, Base32 encoded, with
+the suffix `.btf`.
+
+```
+label   = Base32( pubkey[32] || checksum[2] )
+address = label + ".btf"
+```
+
+- `pubkey` is the 32 byte secp256k1 x-only public key.
+- `checksum` is the first two bytes of `SHA256(".btf-checksum-v1" || pubkey)`.
+- Base32 uses the lowercase alphabet `abcdefghijklmnopqrstuvwxyz234567`, no
+  padding. The 34 byte payload encodes to 55 characters.
+- Parsing is case insensitive, trims surrounding whitespace, and strips a
+  trailing dot. A wrong checksum is rejected.
+
+The address is self certifying: it *is* the public key, so no registry has to be
+trusted to map a name to a key.
+
+## 4. Discovery over Nostr
+
+Nodes publish and read three kinds of parameterized replaceable Nostr events.
+Parameterized replaceable means the newest event for a given author and `d` tag
+supersedes the older one, so a descriptor is always the latest state.
+
+| Purpose | kind | `d` tag |
+|---|---|---|
+| Service descriptor | 38501 | `btf-descriptor-2` |
+| Rendezvous relay announcement | 38502 | `btf-relay-2` |
+| Pool announcement | 38503 | `btf-pool-2` |
+
+The Nostr event is signed with the node's identity key, so the event author
+equals the `.btf` public key. That binds the descriptor to the address at the
+Nostr layer, and the descriptor is *also* signed inside its own content (see
+below), so a relay operator cannot forge or swap a descriptor for an address it
+does not control.
+
+**Resolving an address.** To reach `X.btf`, a caller parses the address to the 32
+byte key and sends a Nostr `REQ` filtered by `authors = [X]`, `kinds = [38501]`,
+`#d = ["btf-descriptor-2"]`, `limit = 1`. It verifies the returned descriptor and
+uses its `meeting_node` and `enc`.
+
+**Relay auto discovery.** A relay operator runs a rendezvous relay and publishes a
+kind 38502 event carrying `host:port`. Every node that reads it adds the relay to
+the set it can register at and dial through. No seed list edit or maintainer
+approval is needed. A small curated seed list is still shipped for bootstrap:
+
+```
+92.246.128.180:8434
+31.44.4.249:8434
+90.156.222.107:8434
+```
+
+The default rendezvous port is `8434`.
+
+## 5. The service descriptor
+
+The descriptor is a JSON object, signed with the identity key over a domain
+separated digest of its own fields.
+
+```json
+{
+  "v": 2,
+  "pubkey": "<hex 32-byte x-only identity key>",
+  "enc": "<hex 32-byte X25519 public key>",
+  "meeting_node": "host:port",
+  "created": <unix seconds>,
+  "sig": "<hex 64-byte BIP340 Schnorr signature>"
+}
+```
+
+The signed digest is:
+
+```
+digest = SHA256( ".btf-descriptor-v2"
+               || pubkey[32]
+               || enc            (raw bytes of the string)
+               || meeting_node   (raw bytes of the string)
+               || created        (8 bytes, big endian) )
+```
+
+The signature is a deterministic BIP340 Schnorr signature (no auxiliary
+randomness) over `digest` by the identity key.
+
+**Verification** (untrusted input, must never throw): parse the JSON, require all
+fields with the right types, confirm `pubkey` equals the address being resolved,
+recompute the digest, and verify the Schnorr signature. Any failure rejects the
+descriptor.
+
+`created` lets a reader prefer the freshest descriptor when more than one is
+seen. A node only publishes a descriptor once it has actually registered at a
+`meeting_node`, so it never advertises a relay it cannot be reached at.
+
+## 6. Rendezvous transport
+
+The relay is a small TCP server. Every connection opens with a fixed 33 byte
+header:
+
+```
+byte 0     role: 'S' (service) or 'C' (client)
+bytes 1..32 target public key (the .btf identity, 32 bytes)
+```
+
+**Service registration (`S`).** The service connects out to the relay and sends
+`'S' || own_pubkey`. The relay stores the connection in a table keyed by the
+public key and leaves it open, waiting. There is one slot per key: a new
+registration for the same key replaces and closes the old one. The service does
+not block waiting to be paired at registration time; it is considered registered
+the moment the relay reads the header, which is what lets it publish a descriptor
+pointing at this relay.
+
+**Client dial (`C`).** The caller connects out to the same relay and sends
+`'C' || target_pubkey`. The relay looks up the waiting service:
+
+- If present, it removes it from the table, writes a single `0x01` byte to both
+  sockets, and then forwards raw bytes in both directions until either side
+  closes. From this point the relay is a blind pipe.
+- If absent, it writes `0x00` to the caller and closes.
+
+Both sides connect *outbound* to the relay, so neither needs a public IP or an
+open inbound port. The relay never sees the identity of the caller (the caller
+sends no key of its own, only the target it wants).
+
+**Liveness.** A registration socket is idle by design and can outlive the network
+path that created it (a NAT drops the idle mapping, the relay restarts, a route
+changes) with no FIN and nothing readable. TCP keepalive was measured and does
+not reliably detect this. The service therefore imposes its own timeout on the
+wait for the pairing byte and re-registers on expiry. Expiring is not a failure;
+it costs one reconnect per interval and returns the loop to a known state.
+
+## 7. The encrypted channel
+
+Once paired through the relay, the caller and service run an end to end handshake
+and then exchange authenticated frames. The primitive is libsodium
+`crypto_box_curve25519xchacha20poly1305` (X25519 key agreement, XChaCha20-Poly1305
+AEAD), the same construction as Rust's `crypto_box` ChaChaBox.
+
+**Handshake (ephemeral to static).**
+
+1. The caller generates a fresh ephemeral X25519 keypair, computes
+   `shared = X25519(eph_sk, service_enc_pub)` reduced to a box key
+   (`crypto_box_beforenm`), and sends the 32 byte ephemeral public key over the
+   paired pipe.
+2. The service reads the ephemeral public key and computes the same
+   `shared = X25519(enc_sk, eph_pub)`.
+
+Because the caller uses a new ephemeral key per connection, each session has an
+independent key and forward secrecy against later compromise of the service
+encryption key.
+
+**Framing.** Every message is length prefixed:
+
+```
+frame = len[4]  (big endian, length of the body that follows)
+        body    = nonce[24] || ciphertext || mac[16]
+```
+
+The nonce is 24 random bytes per frame (XChaCha20), the MAC is 16 bytes
+(Poly1305). A body shorter than `nonce + mac` or larger than 1 MiB is rejected.
+Decryption that fails authentication drops the frame and tears the tunnel down.
+
+The tunnel is transparent: the application is handed a local socket pair end and
+reads and writes plaintext. Two pump threads move data between that socket and
+the relay socket, encrypting outbound and decrypting inbound.
+
+## 8. End to end connection flow
+
+To dial `X.btf`:
+
+1. Parse `X.btf` to the 32 byte identity key.
+2. Fetch and verify the descriptor over Nostr (kind 38501). Obtain
+   `meeting_node` and `enc`.
+3. Connect to `meeting_node`, send `'C' || X`, and wait for `0x01`.
+4. Generate an ephemeral X25519 key, derive the shared key against `enc`, send
+   the ephemeral public key.
+5. Exchange XChaCha20-Poly1305 frames. Hand the application a local socket that
+   speaks the ordinary peer protocol.
+
+A service, symmetrically: registers at a relay (`'S' || own_pubkey`), publishes a
+descriptor pointing at that relay, waits for `0x01`, reads the caller ephemeral
+public key, derives the shared key with its encryption secret, and serves the
+tunnel.
+
+## 9. Security properties
+
+- **Address unforgeability.** The address is the identity key and the descriptor
+  is Schnorr signed by it, and the Nostr event is signed by it. A relay or Nostr
+  operator cannot publish a working descriptor for an address it does not own.
+- **Relay confidentiality.** The relay forwards ciphertext and never holds the
+  channel key. It cannot read or modify traffic undetected; a tampered frame
+  fails the Poly1305 tag and the tunnel closes.
+- **Caller anonymity to the service and relay.** The caller presents no identity
+  key, only the target it wants to reach. It connects outbound, so its address is
+  not published anywhere.
+- **Forward secrecy.** The caller's per connection ephemeral key means a later
+  compromise of the service encryption key does not decrypt past sessions.
+- **IP privacy.** Neither side needs a public IP or an inbound port. The observable
+  network fact is that each side has a TCP connection to a relay.
+
+## 10. Threat model and limitations
+
+- **The relay is trusted for availability, not for confidentiality.** It can
+  refuse to pair, drop a connection, or go offline. This is why relays are
+  plural, auto discovered, and re-registration is periodic. It cannot read
+  traffic.
+- **Traffic analysis is not addressed.** A network observer, or the relay, can
+  see connection timing and byte volumes. There is no padding or mixing.
+- **Single slot registration causes churn.** One waiting slot per key per relay
+  means a race or a stale registration can briefly make a service unreachable at
+  that relay. Multiple relays and the wait timeout bound the damage, but this is
+  a known source of connection churn.
+- **Descriptor freshness is best effort.** `created` is a self reported
+  timestamp; readers prefer the newest descriptor they have seen but there is no
+  global clock.
+- **Discovery depends on public Nostr relays.** If the relays a node uses are all
+  unreachable, discovery stalls until one is reachable again. Relay TLS is
+  verified, which closes a man in the middle path on discovery, but availability
+  still rests on the relay set.
+
+## 11. Wire reference
+
+| Item | Value |
+|---|---|
+| `.btf` Base32 alphabet | `abcdefghijklmnopqrstuvwxyz234567`, no padding |
+| Address payload | `pubkey[32] || checksum[2]`, 55 Base32 chars |
+| Address checksum | `SHA256(".btf-checksum-v1" || pubkey)[0..2]` |
+| Descriptor domain sep | `.btf-descriptor-v2` |
+| Descriptor version | `2` |
+| Descriptor signature | BIP340 Schnorr, deterministic (no aux rand) |
+| Nostr descriptor event | kind `38501`, `d = btf-descriptor-2` |
+| Nostr relay event | kind `38502`, `d = btf-relay-2` |
+| Nostr pool event | kind `38503`, `d = btf-pool-2` |
+| Rendezvous port (default) | `8434` |
+| Rendezvous header | `role[1] ('S'/'C') || pubkey[32]`, 33 bytes |
+| Rendezvous pairing byte | `0x01` paired, `0x00` no service |
+| Channel primitive | `crypto_box_curve25519xchacha20poly1305` |
+| Nonce / MAC / key sizes | 24 / 16 / 32 bytes |
+| Frame | `len[4 big endian] || nonce[24] || ct || mac[16]` |
+| Max frame body | 1 MiB |
diff --git a/docs/social.png b/docs/social.png
index 19e2a3b..9a08b02 100644
--- a/docs/social.png
+++ b/docs/social.png
diff --git a/docs/tor.md b/docs/tor.md
new file mode 100644
index 0000000..087c822
--- /dev/null
+++ b/docs/tor.md
@@ -0,0 +1,84 @@
+# Tor mode
+
+Bitflash can route outbound discovery traffic through a local Tor SOCKS5 proxy.
+This is transport plumbing only: it does not change consensus, wallet keys,
+mining, `.btf` addresses, or the encrypted rendezvous protocol.
+
+## Client mode
+
+Start Tor locally, then start Bitflash with:
+
+```bash
+bitflash -tor
+```
+
+`-tor` is shorthand for:
+
+```bash
+bitflash -socks=127.0.0.1:9050
+```
+
+If Tor listens somewhere else:
+
+```bash
+bitflash -tor=127.0.0.1:9150
+bitflash -tor=[::1]:9050
+```
+
+When Tor mode is enabled:
+
+- outbound Nostr relay dials use Tor;
+- outbound `.btf` rendezvous relay dials use Tor;
+- destination names are sent to Tor as SOCKS5 domain-name CONNECT requests, so
+  the local DNS resolver does not see them;
+- direct `.onion` dials are refused unless a SOCKS5/Tor proxy is enabled;
+- plain HTTP external-IP probes are skipped.
+
+## Onion rendezvous relay
+
+An operator can expose a Bitflash rendezvous relay as a Tor hidden service. The
+node does not create hidden services itself; Tor owns that configuration.
+
+Example `torrc`:
+
+```text
+HiddenServiceDir /var/lib/tor/bitflash-rendezvous/
+HiddenServicePort 8434 127.0.0.1:8434
+```
+
+After restarting Tor, read the generated onion name:
+
+```bash
+sudo cat /var/lib/tor/bitflash-rendezvous/hostname
+```
+
+Then run the relay on localhost/VPS as usual and announce the onion endpoint from
+nodes that use Tor:
+
+```bash
+bitflash -tor -rvrelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434
+bitflash -tor -announcerelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434
+```
+
+For a pool operator that wants the pool descriptor to point at an onion
+rendezvous relay, use both:
+
+```bash
+bitflash -operator -tor \
+  -rvrelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434 \
+  -announcerelay=exampleexampleexampleexampleexampleexampleexampleexample.onion:8434
+```
+
+## Full-node hidden service
+
+The legacy P2P listener still binds to port `8433`. You can expose it through
+Tor manually:
+
+```text
+HiddenServiceDir /var/lib/tor/bitflash-node/
+HiddenServicePort 8433 127.0.0.1:8433
+```
+
+Current automatic peer discovery is `.btf`/rendezvous based, not onion-address
+gossip. Treat direct full-node onion access as an operator/admin tool unless a
+future release adds first-class onion peer advertisements.
diff --git a/docs/utxo-commitment.md b/docs/utxo-commitment.md
new file mode 100644
index 0000000..ab43deb
--- /dev/null
+++ b/docs/utxo-commitment.md
@@ -0,0 +1,125 @@
+# Bitflash UTXO-set commitment
+
+`scripts/verify-utxo-set.py` reconstructs a deterministic commitment to the
+current UTXO set from local `blk*.dat` files.
+
+This is intentionally not a consensus rule yet. It is an audit tool: independent
+operators can run it against the same chain prefix and compare the resulting
+root and canonical JSON hash.
+
+```bash
+python3 scripts/verify-utxo-set.py --max-blocks 1000 --out utxo-report.json --json
+```
+
+Use `--max-blocks 0` or omit the option to scan every available block file:
+
+```bash
+python3 scripts/verify-utxo-set.py --out utxo-report.json --json
+```
+
+## What It Verifies
+
+The verifier:
+
+- parses Bitflash block files directly with the shared Python chain parser;
+- streams `blk*.dat` records instead of loading full block files into memory;
+- reconstructs the best chain rooted at the Bitflash genesis block;
+- ignores side blocks that may also be present in `blk*.dat`;
+- verifies every scanned block merkle root;
+- applies spends and creates outputs in deterministic order;
+- reports current UTXO count, current supply, mined coinbase total, fees, and
+  historical duplicate-output overwrites;
+- computes a deterministic UTXO root.
+
+## Commitment Algorithm
+
+The UTXO map is keyed by:
+
+```text
+txid:vout
+```
+
+Keys are sorted lexicographically. Each leaf is:
+
+```text
+SHA256("BTFUTXO1|" || outpoint || "|" || value_satoshis || "|" ||
+       script_pub_key_hex || "|" || created_height || "|" || created_txid)
+```
+
+The tree is then reduced pairwise. If a level has an odd number of hashes, the
+last hash is duplicated. Each parent is:
+
+```text
+SHA256("BTFNODE1|" || left_hash || right_hash)
+```
+
+The final hash is the UTXO-set root.
+
+## Inclusion Proofs
+
+After a root has been computed, `scripts/prove-utxo.py` can create a compact
+inclusion proof for one unspent output:
+
+```bash
+python3 scripts/prove-utxo.py TXID:VOUT --out utxo-proof.json --json
+python3 scripts/verify-utxo-proof.py utxo-proof.json
+```
+
+The verifier does not need local block files. It recomputes the target leaf,
+walks the sibling path, and compares the result with the expected root. See
+[UTXO inclusion proofs](utxo-proofs.md).
+
+## Deterministic Output
+
+`--json` and `--out` write canonical JSON with sorted keys, fixed separators,
+ASCII escaping, and one trailing newline. It contains no local path and no
+generation timestamp, so two auditors scanning the same chain prefix should
+produce byte-identical reports.
+
+```bash
+python3 scripts/verify-utxo-set.py --out utxo-report.json --json
+sha256sum utxo-report.json
+```
+
+## OpenTimestamps
+
+The canonical JSON can be timestamped in Bitcoin without adding any dependency
+to Bitflash consensus:
+
+```bash
+ots stamp utxo-report.json
+ots verify utxo-report.json.ots
+```
+
+## Historical Duplicates
+
+Bitflash inherited early Bitcoin behavior around duplicate transaction IDs.
+The verifier reports duplicate-output overwrites as warnings and uses
+last-write-wins semantics for the UTXO map, matching the legacy index model.
+Those warnings are part of the report so auditors can see the historical debt
+instead of relying on a polished summary.
+
+For synthetic chains or future clean consensus ranges, auditors can make
+duplicates a hard failure:
+
+```bash
+python3 scripts/verify-utxo-set.py --strict-duplicates
+```
+
+The default remains compatible with the current historical chain because it has
+known legacy duplicate-output overwrites.
+
+## Shared Parser
+
+The audit scripts share `scripts/bitflash_chain.py` for block parsing,
+main-chain selection, UTXO application, canonical JSON, and genesis
+reconstruction. That keeps `verify-utxo-set.py`, `verify-fair-launch.py`,
+`prove-utxo.py`, and the explorer on the same serialization rules.
+
+## Future Consensus Path
+
+This tool is the low-risk first step toward consensus commitments. A future
+hard-fork design can commit this root, or a Utreexo-style accumulator root, in
+coinbase or block headers after a fixed activation height. Until then this
+script provides reproducible supply and state commitments without changing what
+nodes accept.
diff --git a/docs/utxo-proofs.md b/docs/utxo-proofs.md
new file mode 100644
index 0000000..4947c3c
--- /dev/null
+++ b/docs/utxo-proofs.md
@@ -0,0 +1,61 @@
+# Bitflash UTXO inclusion proofs
+
+`scripts/prove-utxo.py` creates a deterministic inclusion proof for one
+currently unspent output. `scripts/verify-utxo-proof.py` verifies that proof
+against the UTXO root produced by `scripts/verify-utxo-set.py`.
+
+This is intentionally outside consensus. It turns the audit root into something
+useful for a specific coin without changing what nodes accept.
+
+## Create A Proof
+
+Use an unspent output in `txid:vout` form:
+
+```bash
+python3 scripts/prove-utxo.py TXID:VOUT --out utxo-proof.json --json
+```
+
+The proof contains:
+
+- the target UTXO;
+- its sorted leaf index;
+- the leaf hash;
+- the Merkle sibling path;
+- the UTXO root and chain tip used to create it.
+
+It does not contain the full UTXO set.
+
+## Verify A Proof
+
+Verify against the root embedded in the proof:
+
+```bash
+python3 scripts/verify-utxo-proof.py utxo-proof.json
+```
+
+Or verify against a root copied from another machine, dashboard, block explorer,
+or future node export:
+
+```bash
+python3 scripts/verify-utxo-proof.py utxo-proof.json \
+  --root ROOT_FROM_REPORT_OR_EXPORT
+```
+
+The verifier does not need local `blk*.dat` files. It only needs the proof and
+the expected root.
+
+## Scope
+
+This first proof format supports inclusion only. Absence and range proofs are
+left for a later design because they require a more careful commitment scheme
+and are easier to get subtly wrong.
+
+The proof uses the exact same leaf and node domains as the UTXO commitment:
+
+```text
+BTFUTXO1
+BTFNODE1
+```
+
+That keeps the verifier language-neutral and gives future implementations a
+small, stable target.