1 files changed, 89 insertions, 7 deletions
diff --git a/README.md b/README.md
index 590f3a6..1720c46 100644
--- a/README.md
+++ b/README.md
@@ -22,19 +22,50 @@ Bitflash keeps Satoshi's original consensus rules and replaces two things:
 **RandomX proof of work.** Memory-hard algorithm used by Monero. A laptop competes equally with a server. ASICs and GPUs have no advantage.
-**Anonymous addressing.** Every node has a `.btf` address derived from its public key, similar to a Tor `.onion`. Nodes find each other through Nostr relays and connect via encrypted rendezvous tunnels. Your IP is never exposed to other nodes, and no port forwarding is needed.
+**Anonymous addressing.** Every node has a `.btf` address derived from its public key, similar to a Tor `.onion`. Nodes reach each other through encrypted rendezvous tunnels, so no port forwarding is needed and a node behind CGNAT works normally.
 No premine. No ICO. 50 BTF per block, halving on schedule, 21M cap, ~2 minute blocks.
+### What `.btf` does and does not hide
+Worth being precise, because the difference matters if you are relying on it.
+**A peer you reach over `.btf` does not learn your IP.** All outbound connections go through a rendezvous tunnel; there is no IP-based peer dialling left in the node. The relay forwards encrypted bytes and cannot read or alter them.
+**The rendezvous relay does see your IP.** It has to — it is the thing your TCP connection terminates on. Relays are run by volunteers, so treat that as a party who knows you are on the network.
+**The node still listens on 8433.** Nothing dials by IP any more, but the listener is still there, so anyone who already knows your address and can reach that port may connect directly. If that matters to you, firewall it.
+This is unlinkability between peers, not anonymity against a network observer. It is not Tor.
 ---
 ## Quick start
-Download the latest release and run. No install, no configuration — it connects automatically and starts syncing.
+Download the [latest release](../../releases/latest) and run. No install, no
+configuration — it connects automatically and starts syncing.
+**Linux:** make the `.AppImage` executable and run it.
+**Windows:** extract the `-windows.zip` and run `Bitflash.exe`.
-**Linux:** `Bitflash-1.1.0-x86_64.AppImage` — make executable and run.
+Every release ships a `SHA256SUMS` covering both assets. Verifying takes a second
+and is worth doing:
-**Windows:** Extract `Bitflash-1.1.0-windows.zip` and run `Bitflash.exe`.
+```bash
+sha256sum -c SHA256SUMS
+```
+**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
+blocks that current nodes reject, which puts it on a different chain without any
+warning.
+Your wallet and chain data live in `%APPDATA%\Bitflash` (Windows) or
+`~/.bitflash` (Linux) and are shared by every version, so upgrading is just
+replacing the binary. Never delete that directory to "fix" something without a
+backup — it holds your keys.
 ---
@@ -63,10 +94,27 @@ xmrig -a rx/0 -o POOL_BTF_ADDRESS -u YOUR_BTF_ADDRESS -p x
 ```bash
 ./bitflash /nogui                     # node only
+./bitflash /nogui /gen                # node + solo mining
 ./bitflash /nogui /gen /operator      # pool operator
 ./bitflash /nogui /gen /participant=POOL_BTF_ADDRESS  # mine to pool
 ```
+Mining is off unless you pass `/gen` — it is not remembered between restarts, so
+put the flag in whatever starts the node rather than enabling it in the window.
+Other options worth knowing:
+```bash
+/datadir=PATH    # wallet and chain data elsewhere
+/port=N          # P2P listen port, default 8433
+/debug           # verbose log; without it debug.log is nearly silent
+/help            # full list
+```
+`/port` plus `/datadir` is what lets two nodes share one machine. Both are
+needed — the data directory takes an exclusive lock, so a second node pointed at
+the same one will refuse to start.
 As a systemd service:
 ```ini
@@ -86,6 +134,31 @@ WantedBy=multi-user.target
 ---
+## How nodes find each other
+A node publishes a **self-certifying descriptor**: its `.btf` address, an
+encryption key, and the rendezvous relay where it is currently reachable, signed
+with the key the address decodes to. Nobody can publish a descriptor for an
+address they do not own, so a hostile relay can withhold descriptors but cannot
+forge one.
+Discovery runs on four layers, so no single failure takes the network down:
+| | |
+|---|---|
+| **Nostr relays** | where descriptors are published and looked up |
+| **Rendezvous relays** | the tunnel itself, where two nodes are paired |
+| **Peer cache** | peers that answered last time, saved to `btfpeers.json` and dialled on start before any relay is contacted |
+| **Peer exchange** | connected nodes hand each other signed descriptors, so discovery keeps working while relays are down |
+Peer exchange carries the same signed descriptors, verified the same way, so a
+peer passing one on is trusted for nothing.
+The cache is what makes a restart fast: on a clean install the first peer takes
+about 36 seconds, and on the next start about 2.
+---
 ## Running a relay
 Relays are the meeting points that let nodes behind NAT connect to each other. More relays make the network more resilient.
@@ -121,13 +194,22 @@ Installs deps via pacman, produces `Bitflash-*-windows.zip`.
 |---|---|
 | Ticker | BTF |
 | Proof of work | RandomX (CPU, memory-hard) |
-| Block reward | 50 BTF, halving on schedule |
-| Max supply | 21,000,000 BTF |
 | Block time | ~2 minutes |
-| Privacy | `.btf` hidden-service addressing over Nostr |
+| Difficulty retarget | every 30 blocks (~1 hour) |
+| Block reward | 50 BTF, halving every 210,000 blocks |
+| Halving interval | **~292 days** at target block time |
+| Max supply | 21,000,000 BTF |
+| Coinbase maturity | 100 blocks (~3.3 hours) before mined coins can be spent |
+| Max signature ops | 20,000 per block |
+| P2P port | 8433 |
+| Addressing | `.btf` rendezvous — see the caveats above |
 | Premine | None |
 | Pool server | Built-in — `.btf` rendezvous only |
+The halving interval is the number most people get wrong coming from Bitcoin.
+Same 210,000 blocks, but at two minutes instead of ten, so it arrives in about
+ten months rather than four years.
 ---
 Experimental software. Young network. Don't put in more than you are willing to lose.

diff --git a/README.md b/README.md index 590f3a6..1720c46 100644 --- a/README.md +++ b/README.md
@@ -22,19 +22,50 @@ Bitflash keeps Satoshi's original consensus rules and replaces two things:
22		22
23	RandomX proof of work. Memory-hard algorithm used by Monero. A laptop competes equally with a server. ASICs and GPUs have no advantage.	23	RandomX proof of work. Memory-hard algorithm used by Monero. A laptop competes equally with a server. ASICs and GPUs have no advantage.
24		24
25	Anonymous addressing. Every node has a `.btf` address derived from its public key, similar to a Tor `.onion`. Nodes find each other through Nostr relays and connect via encrypted rendezvous tunnels. Your IP is never exposed to other nodes, and no port forwarding is needed.	25	Anonymous addressing. Every node has a `.btf` address derived from its public key, similar to a Tor `.onion`. Nodes reach each other through encrypted rendezvous tunnels, so no port forwarding is needed and a node behind CGNAT works normally.
26		26
27	No premine. No ICO. 50 BTF per block, halving on schedule, 21M cap, ~2 minute blocks.	27	No premine. No ICO. 50 BTF per block, halving on schedule, 21M cap, ~2 minute blocks.
28		28
		29	### What `.btf` does and does not hide
		30
		31	Worth being precise, because the difference matters if you are relying on it.
		32
		33	A peer you reach over `.btf` does not learn your IP. All outbound connections go through a rendezvous tunnel; there is no IP-based peer dialling left in the node. The relay forwards encrypted bytes and cannot read or alter them.
		34
		35	The rendezvous relay does see your IP. It has to — it is the thing your TCP connection terminates on. Relays are run by volunteers, so treat that as a party who knows you are on the network.
		36
		37	The node still listens on 8433. Nothing dials by IP any more, but the listener is still there, so anyone who already knows your address and can reach that port may connect directly. If that matters to you, firewall it.
		38
		39	This is unlinkability between peers, not anonymity against a network observer. It is not Tor.
		40
29	---	41	---
30		42
31	## Quick start	43	## Quick start
32		44
33	Download the latest release and run. No install, no configuration — it connects automatically and starts syncing.	45	Download the [latest release](../../releases/latest) and run. No install, no
		46	configuration — it connects automatically and starts syncing.
		47
		48	Linux: make the `.AppImage` executable and run it.
		49
		50	Windows: extract the `-windows.zip` and run `Bitflash.exe`.
34		51
35	Linux: `Bitflash-1.1.0-x86_64.AppImage` — make executable and run.	52	Every release ships a `SHA256SUMS` covering both assets. Verifying takes a second
		53	and is worth doing:
36		54
37	Windows: Extract `Bitflash-1.1.0-windows.zip` and run `Bitflash.exe`.	55	```bash
		56	sha256sum -c SHA256SUMS
		57	```
		58
		59	Keep your node current. Consensus rules have changed since the first
		60	releases — 1.2.1 fixed a bug that let anyone spend anyone's coins, and 1.2.2
		61	added a per-block signature-operation cap. A node on an older build will accept
		62	blocks that current nodes reject, which puts it on a different chain without any
		63	warning.
		64
		65	Your wallet and chain data live in `%APPDATA%\Bitflash` (Windows) or
		66	`~/.bitflash` (Linux) and are shared by every version, so upgrading is just
		67	replacing the binary. Never delete that directory to "fix" something without a
		68	backup — it holds your keys.
38		69
39	---	70	---
40		71
@@ -63,10 +94,27 @@ xmrig -a rx/0 -o POOL_BTF_ADDRESS -u YOUR_BTF_ADDRESS -p x
63		94
64	```bash	95	```bash
65	./bitflash /nogui # node only	96	./bitflash /nogui # node only
		97	./bitflash /nogui /gen # node + solo mining
66	./bitflash /nogui /gen /operator # pool operator	98	./bitflash /nogui /gen /operator # pool operator
67	./bitflash /nogui /gen /participant=POOL_BTF_ADDRESS # mine to pool	99	./bitflash /nogui /gen /participant=POOL_BTF_ADDRESS # mine to pool
68	```	100	```
69		101
		102	Mining is off unless you pass `/gen` — it is not remembered between restarts, so
		103	put the flag in whatever starts the node rather than enabling it in the window.
		104
		105	Other options worth knowing:
		106
		107	```bash
		108	/datadir=PATH # wallet and chain data elsewhere
		109	/port=N # P2P listen port, default 8433
		110	/debug # verbose log; without it debug.log is nearly silent
		111	/help # full list
		112	```
		113
		114	`/port` plus `/datadir` is what lets two nodes share one machine. Both are
		115	needed — the data directory takes an exclusive lock, so a second node pointed at
		116	the same one will refuse to start.
		117
70	As a systemd service:	118	As a systemd service:
71		119
72	```ini	120	```ini
@@ -86,6 +134,31 @@ WantedBy=multi-user.target
86		134
87	---	135	---
88		136
		137	## How nodes find each other
		138
		139	A node publishes a self-certifying descriptor: its `.btf` address, an
		140	encryption key, and the rendezvous relay where it is currently reachable, signed
		141	with the key the address decodes to. Nobody can publish a descriptor for an
		142	address they do not own, so a hostile relay can withhold descriptors but cannot
		143	forge one.
		144
		145	Discovery runs on four layers, so no single failure takes the network down:
		146
		147	\| \| \|
		148	\|---\|---\|
		149	\| Nostr relays \| where descriptors are published and looked up \|
		150	\| Rendezvous relays \| the tunnel itself, where two nodes are paired \|
		151	\| Peer cache \| peers that answered last time, saved to `btfpeers.json` and dialled on start before any relay is contacted \|
		152	\| Peer exchange \| connected nodes hand each other signed descriptors, so discovery keeps working while relays are down \|
		153
		154	Peer exchange carries the same signed descriptors, verified the same way, so a
		155	peer passing one on is trusted for nothing.
		156
		157	The cache is what makes a restart fast: on a clean install the first peer takes
		158	about 36 seconds, and on the next start about 2.
		159
		160	---
		161
89	## Running a relay	162	## Running a relay
90		163
91	Relays are the meeting points that let nodes behind NAT connect to each other. More relays make the network more resilient.	164	Relays are the meeting points that let nodes behind NAT connect to each other. More relays make the network more resilient.
@@ -121,13 +194,22 @@ Installs deps via pacman, produces `Bitflash-*-windows.zip`.
121	\|---\|---\|	194	\|---\|---\|
122	\| Ticker \| BTF \|	195	\| Ticker \| BTF \|
123	\| Proof of work \| RandomX (CPU, memory-hard) \|	196	\| Proof of work \| RandomX (CPU, memory-hard) \|
124	\| Block reward \| 50 BTF, halving on schedule \|
125	\| Max supply \| 21,000,000 BTF \|
126	\| Block time \| ~2 minutes \|	197	\| Block time \| ~2 minutes \|
127	\| Privacy \| `.btf` hidden-service addressing over Nostr \|	198	\| Difficulty retarget \| every 30 blocks (~1 hour) \|
		199	\| Block reward \| 50 BTF, halving every 210,000 blocks \|
		200	\| Halving interval \| ~292 days at target block time \|
		201	\| Max supply \| 21,000,000 BTF \|
		202	\| Coinbase maturity \| 100 blocks (~3.3 hours) before mined coins can be spent \|
		203	\| Max signature ops \| 20,000 per block \|
		204	\| P2P port \| 8433 \|
		205	\| Addressing \| `.btf` rendezvous — see the caveats above \|
128	\| Premine \| None \|	206	\| Premine \| None \|
129	\| Pool server \| Built-in — `.btf` rendezvous only \|	207	\| Pool server \| Built-in — `.btf` rendezvous only \|
130		208
		209	The halving interval is the number most people get wrong coming from Bitcoin.
		210	Same 210,000 blocks, but at two minutes instead of ten, so it arrives in about
		211	ten months rather than four years.
		212
131	---	213	---
132		214
133	Experimental software. Young network. Don't put in more than you are willing to lose.	215	Experimental software. Young network. Don't put in more than you are willing to lose.