site: document public deployment contract

8 files changed, 300 insertions, 46 deletions

diff --git a/README.md b/README.md
index ef4f39b..e671302 100644
--- a/README.md
+++ b/README.md
@@ -38,6 +38,8 @@ Worth being precise, because the difference matters if you are relying on it.
 
 This is unlinkability between peers, not anonymity against a network observer.
 For Tor routing, start the node with `-tor`; see [Tor mode](docs/tor.md).
+For a plain SOCKS5 proxy without Tor-specific defaults, use
+`-socks=HOST:PORT`.
 
 ---
 
@@ -74,6 +76,14 @@ scripts/verify-release.sh latest
 See [release verification](docs/release-verification.md) for the full release
 audit flow and the maintainer signing step.
 
+Public mirrors should make the latest checksum files available both under the
+versioned release directory and at the release root:
+
+```text
+https://releases.bitflash.network/v1.2.18/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS        # alias to latest
+```
+
 Bitflash also ships a deterministic UTXO-set commitment tool:
 
 ```bash
@@ -113,6 +123,12 @@ python3 scripts/build-explorer.py --datadir ~/.bitflash ./explorer-out
 python3 scripts/build-explorer.py ~/.bitflash/blk0001.dat ~/.bitflash/blk0002.dat ./explorer-out
 ```
 
+The generated explorer is static and self-contained: `index.html`,
+`style.css`, `explorer.js`, `blocks.json`, `block/*.json`, and `logo.png`. It is
+safe to host behind a strict policy such as `default-src 'none'; img-src 'self';
+style-src 'self'; script-src 'self'; connect-src 'self'; base-uri 'none';
+form-action 'none'`.
+
 **Keep your node current.** Consensus rules have changed since the first
 releases — 1.2.1 fixed a bug that let anyone spend anyone's coins, and 1.2.2
 added a per-block signature-operation cap. A node on an older build will accept
@@ -265,6 +281,7 @@ default both are created in the data directory; use `-poolstatusfile=PATH` and
 `-poolroundsfile=PATH` to write them somewhere a dashboard or web sync can read.
 The files are informational only: nodes still discover pools through Nostr and
 `.btf`, not through any web domain.
+See [public pool directory](docs/pool-directory.md) for the website/API shape.
 
 **Participant** — mine to someone else's pool. Enter or select the pool's `.btf` address and enable Start Mining.
 
diff --git a/docs/mining-calculator.md b/docs/mining-calculator.md
index 352eea1..e6cb61b 100644
--- a/docs/mining-calculator.md
+++ b/docs/mining-calculator.md
@@ -84,3 +84,25 @@ 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.
+
+## Website Fields
+
+A public calculator should ask for:
+
+- miner hashrate and unit;
+- power draw in watts;
+- electricity price per kWh;
+- pool fee percent;
+- optional BTF price;
+- either current Bitflash difficulty or current network hashrate.
+
+The output should separate:
+
+- estimated BTF per day;
+- estimated gross fiat revenue, if a manual price was provided;
+- electricity cost;
+- net profit/loss;
+- the difficulty/hashrate assumptions used.
+
+Never present the fiat number as a market quote unless it comes from a real
+public market. Before that exists, label it as a manual scenario.
diff --git a/docs/pool-directory.md b/docs/pool-directory.md
index 76269b9..ff0640a 100644
--- a/docs/pool-directory.md
+++ b/docs/pool-directory.md
@@ -26,6 +26,10 @@ The generated output contains:
 - `index.html`: human-readable ranking page.
 - `pools.json`: machine-readable API for `api.bitflash.network/pools.json`.
 
+The website is a convenience layer, not a consensus or discovery dependency.
+Nodes discover pools through Nostr descriptors and `.btf`; a missing website
+must not stop mining or pool operation.
+
 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
@@ -41,3 +45,17 @@ Ranking order is intentionally simple:
 
 An entry is considered online when the source says the pool is running and its
 status file is no more than 120 seconds old.
+
+## Recommended Hostnames
+
+Use:
+
+```text
+pool.bitflash.network        human-readable pool directory
+api.bitflash.network/pools.json
+status.bitflash.network      relay/node health, not pool ranking
+docs.bitflash.network        operator setup guide
+```
+
+The GUI may use the API as a shortcut for humans, but it should keep the
+existing decentralized pool discovery path as the source of truth.
diff --git a/docs/release-verification.md b/docs/release-verification.md
index 32de74f..408bab9 100644
--- a/docs/release-verification.md
+++ b/docs/release-verification.md
@@ -34,6 +34,16 @@ From a shell with `curl` or `wget`, `sha256sum` and `gpg`:
 scripts/verify-release.sh latest
 ```
 
+The public release host should expose latest-file aliases for convenience:
+
+```text
+https://releases.bitflash.network/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS.asc
+```
+
+Those aliases must point at the current versioned directory. They do not replace
+signature verification; they only make the common manual path shorter.
+
 For a specific release:
 
 ```bash
diff --git a/docs/site.md b/docs/site.md
new file mode 100644
index 0000000..522da10
--- /dev/null
+++ b/docs/site.md
@@ -0,0 +1,115 @@
+# Public Site Contract
+
+The public Bitflash sites are generated from this repository. If a deployed
+page and the source disagree, the deployed page is stale.
+
+## Canonical Navigation
+
+Every public page should use the same top navigation:
+
+| label | target |
+|---|---|
+| home | `https://bitflash.network/` |
+| code | `https://git.bitflash.network/bitflash/bitflash` |
+| docs | `https://docs.bitflash.network/` |
+| downloads | `https://releases.bitflash.network/` |
+| explorer | `https://explorer.bitflash.network/` |
+| status | `https://status.bitflash.network/` |
+
+The `code` link intentionally points at the repository, not the Forgejo
+instance root. A visitor choosing "code" wants the source tree.
+
+## Documentation Pages To Publish
+
+The docs index should expose these source files:
+
+| page | source | why it matters |
+|---|---|---|
+| Manual | `README.md` | run, mine, recover, operate |
+| Key derivation and address format | `docs/derivation.md` | independent wallet recovery |
+| Release verification | `docs/release-verification.md` | pinned signing-key flow |
+| Dependencies | `docs/dependencies.md` | pinned secp256k1/RandomX supply chain |
+| Rendezvous and .btf addressing | `docs/rendezvous.md` | network design and caveats |
+| Tor mode | `docs/tor.md` | `-tor`, `-socks`, onion relay operation |
+| Fair launch verifier | `docs/fair-launch.md` | no-premine launch audit |
+| UTXO set commitment | `docs/utxo-commitment.md` | deterministic supply/root audit |
+| UTXO inclusion proofs | `docs/utxo-proofs.md` | proof for one unspent output |
+| Mining calculator | `docs/mining-calculator.md` | local WhatToMine-style estimates |
+| Public pool directory | `docs/pool-directory.md` | `pool_status.json`, `pools.json`, ranking |
+
+## Release Mirror Aliases
+
+Each release remains under its versioned directory:
+
+```text
+https://releases.bitflash.network/v1.2.18/SHA256SUMS
+https://releases.bitflash.network/v1.2.18/SHA256SUMS.asc
+```
+
+The release root should also alias the latest files:
+
+```text
+https://releases.bitflash.network/SHA256SUMS
+https://releases.bitflash.network/SHA256SUMS.asc
+https://releases.bitflash.network/Bitflash-latest-windows.zip
+https://releases.bitflash.network/Bitflash-latest-x86_64.AppImage
+https://releases.bitflash.network/bitflash-node-latest-x86_64
+```
+
+The aliases are convenience only. Verification must still require the pinned
+release key documented in `docs/release-verification.md`.
+
+## Static Explorer
+
+`scripts/build-explorer.py` writes a static explorer with no backend:
+
+```text
+index.html
+style.css
+explorer.js
+logo.png
+blocks.json
+block/<height>.json
+```
+
+Serve it with a strict content policy:
+
+```text
+default-src 'none';
+img-src 'self';
+style-src 'self';
+script-src 'self';
+connect-src 'self';
+base-uri 'none';
+form-action 'none';
+frame-ancestors 'none';
+```
+
+The viewer must never use `innerHTML` for chain data. A malicious transaction
+must be rendered as text, not interpreted as markup.
+
+## Cache Policy
+
+Recommended defaults:
+
+| path | cache |
+|---|---|
+| HTML pages | `public, max-age=0, must-revalidate` |
+| `status.json` | `no-store` |
+| `blocks.json`, `block/*.json` | `public, max-age=0, must-revalidate` |
+| release assets | `public, max-age=14400, must-revalidate` |
+| `SHA256SUMS`, signatures, keys | `public, max-age=0, must-revalidate` |
+
+## Security Headers
+
+Recommended for all static pages:
+
+```text
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Content-Type-Options: nosniff
+Referrer-Policy: no-referrer
+Permissions-Policy: interest-cohort=(), geolocation=(), camera=(), microphone=()
+```
+
+Forgejo has its own application headers and should not blindly inherit the
+static-site CSP.
diff --git a/docs/tor.md b/docs/tor.md
index 087c822..69b29f1 100644
--- a/docs/tor.md
+++ b/docs/tor.md
@@ -25,6 +25,17 @@ bitflash -tor=127.0.0.1:9150
 bitflash -tor=[::1]:9050
 ```
 
+For a SOCKS5 proxy that is not Tor, use `-socks` directly:
+
+```bash
+bitflash -socks=127.0.0.1:9050
+bitflash -socks=[::1]:9050
+```
+
+If both `-tor` and `-socks` are present, Tor mode wins and the node prints a
+warning. That keeps a command line with `-tor` from silently becoming a custom
+proxy route.
+
 When Tor mode is enabled:
 
 - outbound Nostr relay dials use Tor;
@@ -34,6 +45,24 @@ When Tor mode is enabled:
 - direct `.onion` dials are refused unless a SOCKS5/Tor proxy is enabled;
 - plain HTTP external-IP probes are skipped.
 
+Tor mode affects outbound discovery and relay dials. It does not encrypt
+`wallet.dat`, hide mining rewards on-chain, or change the `.btf` identity. A
+relay still sees the TCP client that connected to it; with Tor mode that client
+is the Tor exit or onion circuit endpoint instead of the user's direct IP.
+
+## What to test
+
+Use the public status page only as a rough health check. To prove the local node
+is using Tor/SOCKS, test from the node machine:
+
+```bash
+bitflash -tor -debug
+```
+
+Then confirm in `debug.log` that Nostr and rendezvous dials report the proxy
+path. A DNS leak test should show no local resolver lookup for relay hostnames:
+the SOCKS5 request uses the domain-name form and asks the proxy to resolve it.
+
 ## Onion rendezvous relay
 
 An operator can expose a Bitflash rendezvous relay as a Tor hidden service. The
diff --git a/scripts/build-explorer.py b/scripts/build-explorer.py
index 97a7f4e..dbb8e17 100755
--- a/scripts/build-explorer.py
+++ b/scripts/build-explorer.py
@@ -4,6 +4,7 @@
 import argparse
 import hashlib
 import json
+import shutil
 import sys
 from pathlib import Path
 
@@ -148,6 +149,11 @@ def build_explorer(raw_blocks, out_dir):
         encoding="ascii",
     )
     (out / "index.html").write_text(INDEX_HTML, encoding="utf-8")
+    (out / "style.css").write_text(STYLE_CSS, encoding="utf-8")
+    (out / "explorer.js").write_text(EXPLORER_JS, encoding="utf-8")
+    logo = Path(__file__).resolve().parents[1] / "docs" / "logo.png"
+    if logo.exists():
+        shutil.copyfile(logo, out / "logo.png")
     return len(blocks), len(blocks) - 1
 
 
@@ -167,43 +173,26 @@ INDEX_HTML = r"""<!doctype html>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <title>Bitflash Block Explorer</title>
-<style>
-  :root { color-scheme: light dark; --bg:#fff; --fg:#111; --mut:#666; --line:#e2e2e2; --card:#fafafa; --acc:#2b6cb0; }
-  @media (prefers-color-scheme: dark){ :root{ --bg:#0e0f11; --fg:#e6e6e6; --mut:#9aa0a6; --line:#26282c; --card:#16181b; --acc:#63b3ed; } }
-  * { box-sizing: border-box; }
-  body { font: 15px/1.5 system-ui, sans-serif; margin:0; background:var(--bg); color:var(--fg); }
-  header { padding:20px 24px; border-bottom:1px solid var(--line); display:flex; gap:16px; align-items:baseline; flex-wrap:wrap; }
-  h1 { font-size:18px; margin:0; }
-  h2 { font-size:16px; }
-  .mut { color:var(--mut); }
-  .wrap { padding:16px 24px; max-width:1100px; margin:0 auto; }
-  input { width:100%; max-width:420px; padding:9px 12px; border:1px solid var(--line); border-radius:8px; background:var(--card); color:var(--fg); font-size:14px; }
-  table { width:100%; border-collapse:collapse; margin-top:12px; }
-  th,td { text-align:left; padding:9px 10px; border-bottom:1px solid var(--line); font-variant-numeric:tabular-nums; }
-  th { font-size:12px; text-transform:uppercase; letter-spacing:.05em; color:var(--mut); }
-  tr.blk { cursor:pointer; }
-  tr.blk:hover td { background:var(--card); }
-  code { font-size:12px; word-break:break-all; }
-  .scroll { overflow-x:auto; }
-  .card { border:1px solid var(--line); border-radius:10px; background:var(--card); padding:14px 16px; margin-top:12px; }
-  .kv { display:grid; grid-template-columns:150px 1fr; gap:4px 12px; font-size:13px; }
-  .kv div:nth-child(odd){ color:var(--mut); }
-  .tx { border-top:1px solid var(--line); padding:10px 0; }
-  .io { display:grid; grid-template-columns:1fr 1fr; gap:16px; }
-  @media (max-width:640px){ .io{ grid-template-columns:1fr; } .kv{ grid-template-columns:110px 1fr; } }
-  .pill { display:inline-block; font-size:11px; padding:1px 7px; border-radius:99px; border:1px solid var(--line); color:var(--mut); }
-  button.link { background:none; border:none; color:var(--acc); cursor:pointer; font:inherit; padding:0; }
-  .note { color:var(--mut); font-size:13px; max-width:820px; }
-</style>
+<meta name="description" content="Read-only Bitflash block explorer generated from local blk*.dat files.">
+<link rel="icon" href="logo.png" type="image/png">
+<link rel="stylesheet" href="style.css">
+<script src="explorer.js" defer></script>
 </head>
 <body>
-<header>
-  <h1>Bitflash Block Explorer</h1>
-  <span class="mut" id="tip"></span>
-  <span style="flex:1"></span>
-  <button class="link" id="home" style="display:none">back to blocks</button>
+<header class="topbar">
+  <a class="brand" href="https://bitflash.network/"><img src="logo.png" width="22" height="22" alt="">Bitflash</a>
+  <nav aria-label="Bitflash sites">
+    <a href="https://bitflash.network/">home</a>
+    <a href="https://git.bitflash.network/bitflash/bitflash">code</a>
+    <a href="https://docs.bitflash.network/">docs</a>
+    <a href="https://releases.bitflash.network/">downloads</a>
+    <a href="https://explorer.bitflash.network/" aria-current="page">explorer</a>
+    <a href="https://status.bitflash.network/">status</a>
+  </nav>
+  <span class="meta" id="tip"></span>
 </header>
 <div class="wrap">
+  <h1>Block explorer <button class="link" id="home" hidden>back to blocks</button></h1>
   <p class="note">Read-only view of the main chain: blocks, their transactions, and the coinbase payout. There is no mempool and no per-address history here.</p>
   <div id="listview">
     <input id="q" placeholder="Search by height or block hash">
@@ -213,9 +202,63 @@ INDEX_HTML = r"""<!doctype html>
     </table></div>
     <p class="mut" id="more"></p>
   </div>
-  <div id="detail" style="display:none"></div>
+  <div id="detail" hidden></div>
 </div>
-<script>
+</body>
+</html>
+"""
+
+
+STYLE_CSS = r""":root{
+  color-scheme: light dark;
+  --bg:#fff; --bg-2:#f6f6f6; --fg:#111; --dim:#6b6b6b; --line:#d7d7d7; --line-hard:#111;
+  --accent:#0b7a34; --accent-2:#12a047; --bar:3rem;
+  --mono: ui-monospace,"Cascadia Mono","Segoe UI Mono",Consolas,"DejaVu Sans Mono","Liberation Mono","Courier New",monospace;
+}
+@media (prefers-color-scheme: dark){:root{
+  --bg:#000; --bg-2:#0b0b0b; --fg:#dcdcdc; --dim:#8a8a8a; --line:#242424; --line-hard:#4a4a4a;
+  --accent:#2ee06a; --accent-2:#6bff9f;
+}}
+*{box-sizing:border-box;}
+html,body{margin:0;background:var(--bg);color:var(--fg);font:15px/1.55 var(--mono);-webkit-text-size-adjust:100%;}
+a{color:var(--accent);}
+.topbar{display:flex;align-items:center;gap:1rem;flex-wrap:wrap;min-height:var(--bar);
+        padding:.5rem clamp(.9rem,2.5vw,3rem);border-bottom:1px solid var(--line);position:sticky;top:0;background:var(--bg);z-index:5;}
+.brand{display:flex;align-items:center;gap:.6rem;text-decoration:none;color:var(--fg);font-weight:bold;}
+.brand img{width:22px;height:22px;display:block;}
+.topbar nav{display:flex;flex-wrap:wrap;gap:.15rem 1.4rem;font-size:.86rem;}
+.topbar nav a{text-decoration:none;color:var(--dim);}
+.topbar nav a::before{content:"/";color:var(--line-hard);margin-right:.3rem;}
+.topbar nav a:hover{color:var(--fg);text-decoration:underline;}
+.topbar nav a[aria-current="page"]{color:var(--accent);font-weight:bold;}
+.topbar nav a[aria-current="page"]::before{color:var(--accent);}
+.topbar .meta{margin-left:auto;font-size:.76rem;color:var(--dim);letter-spacing:.06em;}
+.wrap{padding:1.4rem clamp(.9rem,2.5vw,3rem) 4rem;}
+h1{font-size:1rem;margin:0 0 .3rem;letter-spacing:.02em;}
+h2{font-size:.95rem;margin:1.2rem 0 .4rem;}
+.mut{color:var(--dim);}
+.note{color:var(--dim);font-size:.82rem;max-width:60rem;margin:.2rem 0 1rem;}
+input{width:100%;max-width:28rem;padding:.5rem .7rem;border:1px solid var(--line);background:var(--bg-2);color:var(--fg);font:inherit;font-size:.86rem;}
+input:focus{outline:none;border-color:var(--accent);}
+.scroll{overflow-x:auto;}
+table{width:100%;border-collapse:collapse;margin-top:.8rem;font-size:.86rem;}
+th,td{text-align:left;padding:.5rem .6rem;border-bottom:1px solid var(--line);font-variant-numeric:tabular-nums;}
+th{font-size:.72rem;text-transform:uppercase;letter-spacing:.1em;color:var(--dim);font-weight:normal;}
+tr.blk{cursor:pointer;}
+tr.blk:hover td{background:var(--bg-2);}
+code{font-size:.8rem;word-break:break-all;color:var(--fg);}
+.card{border:1px solid var(--line);background:var(--bg-2);padding:.9rem 1rem;margin-top:.8rem;}
+.kv{display:grid;grid-template-columns:11rem 1fr;gap:.25rem .8rem;font-size:.82rem;}
+.kv div:nth-child(odd){color:var(--dim);}
+.tx{border-top:1px solid var(--line);padding:.7rem 0;}
+.io{display:grid;grid-template-columns:1fr 1fr;gap:1rem;}
+@media (max-width:640px){.io{grid-template-columns:1fr;}.kv{grid-template-columns:7rem 1fr;}.topbar .meta{margin-left:0;width:100%;}}
+.pill{display:inline-block;font-size:.68rem;padding:.05rem .5rem;border:1px solid var(--line);color:var(--dim);text-transform:uppercase;letter-spacing:.05em;}
+button.link{background:none;border:none;color:var(--accent);cursor:pointer;font:inherit;padding:0;text-decoration:underline;}
+"""
+
+
+EXPLORER_JS = r"""
 var SUM = [], SHOWN = 200;
 function btf(sat){ return (sat/1e8).toFixed(8).replace(/0+$/,'').replace(/\.$/,'')+" BTF"; }
 function ts(t){ return new Date(t*1000).toISOString().replace('T',' ').replace('.000Z',' UTC'); }
@@ -310,25 +353,22 @@ function openBlock(h){
       }));
       append(tx, head, io); append(detail, tx);
     });
-    document.getElementById('listview').style.display='none';
-    detail.style.display='block';
-    document.getElementById('home').style.display='inline';
+    document.getElementById('listview').hidden = true;
+    detail.hidden = false;
+    document.getElementById('home').hidden = false;
     window.scrollTo(0,0);
   });
 }
 document.getElementById('home').onclick=function(){
-  document.getElementById('detail').style.display='none';
-  document.getElementById('listview').style.display='block';
-  this.style.display='none';
+  document.getElementById('detail').hidden = true;
+  document.getElementById('listview').hidden = false;
+  this.hidden = true;
 };
 document.getElementById('q').oninput=function(){ renderList(this.value); };
 fetch('blocks.json').then(function(r){return r.json();}).then(function(d){
   SUM=d.blocks; document.getElementById('tip').textContent='tip height '+d.tipHeight+' - '+d.count+' blocks';
   renderList('');
 });
-</script>
-</body>
-</html>
 """
 
 
diff --git a/tests/scripts/test_bitflash_tools.py b/tests/scripts/test_bitflash_tools.py
index 4b18d1e..3b4c846 100644
--- a/tests/scripts/test_bitflash_tools.py
+++ b/tests/scripts/test_bitflash_tools.py
@@ -159,8 +159,11 @@ def compare_golden(name, actual, update):
         path.parent.mkdir(parents=True, exist_ok=True)
         path.write_bytes(actual)
         return
-    expected = path.read_bytes()
-    if actual != expected:
+    # The tools promise canonical LF-terminated JSON. On Windows checkouts a
+    # fixture may still appear as CRLF in the working tree; normalize only line
+    # endings so content, field order and compact serialization still drift-test.
+    expected = path.read_bytes().replace(b"\r\n", b"\n")
+    if actual.replace(b"\r\n", b"\n") != expected:
         raise AssertionError("golden mismatch: %s" % name)