Replace draft with full manual (docs-as-code, colors, logo, versioning)

docs/will-executors/choosing.md

@@ -0,0 +1,47 @@
+# Choosing Will-Executors in the plugin
+
+The plugin downloads the [WeList](welist.md) directory by default and tries to use as many Will-Executors as possible. You can also add servers manually, or draw from alternative lists — the WeList makes discovery easier, it does not control access to the network.
+
+The service list window opens from the Electrum menu: **Tools → Will-executor**.
+
+![Will-Executor service list](../img/willexecutors-window.png){ .screenshot }
+*The list of known Will-Executors, with fees and online status.*
+
+## Columns
+
+| Column | Meaning |
+|---|---|
+| **URL** | Address of the Will-Executor |
+| **Base fee** | The commission that server asks, paid only on execution |
+| **Info** | Description or website link |
+| **Default address** | Bitcoin address where the fee will be sent |
+| **Status** | Green dot = server responding |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| **Ping** | Checks which servers are online |
+| **Import** | Imports a Will-Executor list other than the default |
+| **Export** | Exports your list — useful when moving to another Electrum installation |
+| **Add** | Adds a Will-Executor manually |
+
+## Per-server actions
+
+![Right-click menu on a Will-Executor](../img/willexecutors-context-menu.png){ .screenshot }
+*Right-click a row for per-server actions.*
+
+- **Select** — includes this Will-Executor in your inheritance (green check mark).
+- **Edit** — edits the corresponding field.
+- **Ping** — checks whether that server is online.
+- **Delete** — removes it from your list.
+
+## How to choose well
+
+- **Quantity first.** One transaction is created per selected server, and only one has to survive to the delivery date. Select generously.
+- **Ignore extremes on price.** Too expensive eats into the inheritance; suspiciously cheap may not survive for years.
+- **Prefer diversity.** Different operators, different hosting, different jurisdictions — the point of redundancy is that failures are uncorrelated.
+- **Re-check periodically.** Use the [Server column](../user-guide/will-tab.md#the-server-column) to confirm your wills are still stored, and renew the will if servers have disappeared.
+
+!!! info "Adding a server by hand"
+    You are not limited to the WeList. Servers announced on BitcoinTalk or shared through alternative directories can be added manually with **Add**.

docs/will-executors/running-a-server.md

@@ -0,0 +1,127 @@
+# Running a Will-Executor
+
+This page covers setting up your own Will-Executor node. If you are wondering *why* you would, start with [What Will-Executors are](what-they-are.md).
+
+!!! warning "Read this first"
+    Running a Will-Executor is a **long-horizon commitment**, not a quick return. You will hold pre-signed transactions belonging to living people, and you are compensated only when you successfully broadcast an inheritance that confirms on-chain — potentially years from now. Costs are certain; revenue is not.
+
+    Nothing on this page is an offer, a solicitation, or a promise of any economic result. It describes a technical role.
+
+## What the role actually requires
+
+- **A server that stays up.** A dedicated machine, a VPS, or a home node — at least one Will-Executor on the network runs on Umbrel OS. Modern releases run comfortably on a small VPS.
+- **Reliable connectivity.** Tor-only operation is possible: at least one active Will-Executor is reachable exclusively that way.
+- **A Bitcoin full node** with ZMQ enabled (see below).
+- **Real maintenance.** Updates, backups, monitoring. A server that fails to broadcast when it matters earns nothing — and, more importantly, fails the user who relied on the network.
+- **Discretion.** You will be handling data that reflects the wallets of living people. Privacy and reliability, not just price, are what Will-Executors compete on.
+
+!!! tip "A Will-Executor doesn't have to be one person"
+    From the protocol's point of view a Will-Executor is a service plus a Bitcoin address. Several operators can pool resources, present themselves as a single Will-Executor, and use a shared **multisig** address for the fee, splitting proceeds however they agree. A meetup, an association, or a group of friends can run one together.
+
+    Two things to keep in mind: for a user's redundancy, a consortium still counts as **one** Will-Executor; and the internal split is an agreement outside the protocol, which BAL neither arbitrates nor guarantees.
+
+## The two components
+
+| Component | Role |
+|---|---|
+| **`bal-server`** | Receives and stores the pre-signed inheritance transactions sent by plugins |
+| **`bal-pusher`** | Watches for new Bitcoin blocks via ZMQ and broadcasts stored transactions once their locktime passes the median time past (MTP) |
+
+Both live in the [bal-server repository](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server) (Rust, [releases](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server/releases)).
+
+## Prerequisites
+
+1. **Bitcoin Core compiled with ZMQ support**, with this line in `bitcoin.conf`:
+
+    ```text
+    zmqpubhashblock=tcp://127.0.0.1:28332
+    ```
+
+2. **Rust and Cargo** — see the [official installation instructions](https://www.rust-lang.org/tools/install).
+
+## Installing `bal-server`
+
+```bash
+git clone https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server.git
+cd bal-server
+
+# Ed25519 keypair identifying this Will-Executor
+openssl genpkey -algorithm ED25519 -out private_key.pem
+openssl pkey -in private_key.pem -pubout -out public_key.pem
+
+cargo build --release
+sudo cp target/release/bal-server /usr/local/bin
+bal-server
+```
+
+!!! danger "Back up `private_key.pem`"
+    It is the identity of your Will-Executor. Store it securely and restrict its permissions (`chmod 600`).
+
+### Configuration
+
+`bal-server` is configured through environment variables:
+
+| Variable | Description | Default |
+|---|---|---|
+| `BAL_SERVER_CONFIG_FILE` | Configuration file path — created if missing | `$HOME/.config/bal-server/default-config.toml` |
+| `BAL_SERVER_DB_FILE` | SQLite3 database file — created if missing | `bal.db` |
+| `BAL_SERVER_BIND_ADDRESS` | Public listening address | `127.0.0.1` |
+| `BAL_SERVER_BIND_PORT` | Listening port | `9137` |
+| `BAL_SERVER_PUB_KEY_PATH` | Will-Executor Ed25519 public key | `public_key.pem` |
+| `BAL_SERVER_BITCOIN_ADDRESS` | Address that receives fees on **mainnet** | — |
+| `BAL_SERVER_BITCOIN_FIXED_FEE` | Fixed fee on mainnet | `50000` |
+| `BAL_SERVER_TESTNET_ADDRESS` / `..._FIXED_FEE` | Same, for testnet | — / `50000` |
+| `BAL_SERVER_SIGNET_ADDRESS` / `..._FIXED_FEE` | Same, for signet | — / `50000` |
+| `BAL_SERVER_REGTEST_ADDRESS` / `..._FIXED_FEE` | Same, for regtest | — / `50000` |
+
+A sample environment file (`bal-server.env`) and a systemd unit (`bal-server.service`) ship with the repository.
+
+!!! warning "Bind address and exposure"
+    The default `127.0.0.1` is local-only. To be reachable by users you must expose the service deliberately — typically behind a reverse proxy with TLS, or as a Tor hidden service. Do not expose it carelessly.
+
+## Installing `bal-pusher`
+
+`bal-pusher` reads the same database and does the broadcasting.
+
+```bash
+bal-pusher [bitcoin|testnet|regtest]
+```
+
+### Configuration
+
+| Variable | Description | Default |
+|---|---|---|
+| `BAL_PUSHER_CONFIG_FILE` | Configuration file path — created if missing | `$HOME/.config/bal-pusher/default-config.toml` |
+| `BAL_PUSHER_DB_FILE` | SQLite3 database file | `bal.db` |
+| `BAL_PUSHER_ZMQ_LISTENER` | ZMQ endpoint for block updates | `tcp://127.0.0.1:28332` |
+| `BAL_PUSHER_BITCOIN_HOST` | Bitcoin RPC host | `http://127.0.0.1` |
+| `BAL_PUSHER_BITCOIN_PORT` | Bitcoin RPC port | `8332` |
+| `BAL_PUSHER_BITCOIN_COOKIE_FILE` | Bitcoin RPC cookie file | `$HOME/.bitcoin/.cookie` |
+| `BAL_PUSHER_BITCOIN_RPC_USER` | Bitcoin RPC username | — |
+| `BAL_PUSHER_BITCOIN_RPC_PASSWORD` | Bitcoin RPC password | — |
+| `BAL_PUSHER_SEND_STATS` | Report timing statistics to the WeList | `false` |
+| `WELIST_SERVER_URL` | WeList server URL | `https://welist.bitcoin-after.life` |
+| `BAL_SERVER_URL` | URL of your Will-Executor | — |
+| `SSL_KEY_PATH` | Ed25519 private key (PEM) | `private_key.pem` |
+
+!!! note "`bal-pusher` must point at the same database as `bal-server`"
+    `BAL_PUSHER_DB_FILE` and `BAL_SERVER_DB_FILE` have to resolve to the same SQLite file, otherwise the pusher will have nothing to broadcast.
+
+## RPC interface
+
+The request/response interface used by the plugin is documented in [`RPC.md`](https://bitcoin-after.life/gitea/bitcoinafterlife/bal-server/src/branch/main/RPC.md) in the repository.
+
+## Going live
+
+1. **Test on testnet or regtest first.** The WeList lets users filter by network, so a testnet server is a legitimate way to validate the whole chain of events.
+2. **Verify reachability** from outside your own network, at the exact URL you intend to publish.
+3. **Set up monitoring and restart policies** (the provided systemd unit is a starting point).
+4. **Plan your backups** — the SQLite database holds the wills you have accepted; the Ed25519 key is your identity.
+5. **List on the [WeList](welist.md)** if you want automatic discovery by plugin users — {{ bal.welist_fee_sats }} sats per year. Listing is optional; users can also add your server manually.
+
+!!! tip "CPFP for congested conditions"
+    Inheritance transactions are built with a prudent miner fee, but a Will-Executor can use **CPFP (Child Pays For Parent)** to speed up confirmation if the network is congested at delivery time. Being the first to get a transaction confirmed is what earns the fee.
+
+## Getting in touch
+
+For help setting up a Will-Executor, or to collaborate on the project: **[info@bitcoin-after.life](mailto:info@bitcoin-after.life)**

docs/will-executors/welist.md

@@ -0,0 +1,35 @@
+# The WeList directory
+
+The **WeList** is the public directory of Will-Executors, published at [welist.bitcoin-after.life](https://welist.bitcoin-after.life/). The plugin downloads it by default, so listed servers appear automatically when you set up a will.
+
+![The WeList leaderboard](../img/welist-website.png){ .screenshot }
+*The public Will-Executor leaderboard.*
+
+## What it shows
+
+For each server: URL, description, fee, software version, block height, wins, and score. You can filter by network (**Bitcoin**, **Testnet**, **Testnet4**, **Regtest**) and choose whether to include **Tor** servers. The list is also available as **JSON** for programmatic use.
+
+!!! note "Data freshness"
+    Fee, description and version refresh roughly once a day, and may be outdated. The plugin remains the authoritative source at the moment you build your will.
+
+## Ranking
+
+Servers are ordered by: excess donated over the yearly fee, then total amount paid, then lower base fee, then WeTime points.
+
+## Listing your own server
+
+| | |
+|---|---|
+| **Yearly fee** | {{ bal.welist_fee_sats }} sats |
+| **Listing period** | {{ bal.welist_period_days }} days, starting when the payment reaches 3 confirmations (~30 min) |
+| **Renewal window** | From 6 months before expiry, for one additional year |
+| **Plugin integration** | Automatic once listed |
+
+The procedure: enter your server URL on the WeList site, accept the [terms](https://welist.bitcoin-after.life/terms.html), and pay the invoice. Your server appears once the deposit confirms.
+
+!!! warning "Before you pay"
+    Make sure your server is **online and reachable** at the exact URL you submit. There are no refunds after payment, and later URL changes require proof of ownership.
+
+## Listing is optional
+
+Being on the WeList is **not** required to operate a Will-Executor. Users can add servers manually, and the plugin can draw from alternative lists. The WeList exists to simplify discovery, not to gate participation in the network.

docs/will-executors/what-they-are.md

@@ -0,0 +1,44 @@
+# What Will-Executors are
+
+A Will-Executor is a server with one narrow job: **it stores pre-signed inheritance transactions and broadcasts them to the Bitcoin network on the date the user chose.** Nothing else.
+
+## What a Will-Executor cannot do
+
+- **It cannot spend your funds.** It holds no keys.
+- **It cannot alter the transaction.** The transaction is already fully signed by you; any modification would invalidate the signature.
+- **It cannot execute early.** The transaction carries an absolute `nLockTime`, and Bitcoin nodes reject it until that date is reached.
+- **It does not coordinate with other Will-Executors.** Every node is independent. There is no central point to attack or compromise.
+
+What it *does* require is longevity: being still there, still working, years from now.
+
+## Why competition makes it work
+
+When you create your will, the plugin generates **a separate transaction for every Will-Executor you selected**. Each of those transactions carries an extra output paying that specific server its fee.
+
+On the delivery date, every Will-Executor holding a copy can broadcast. Only one transaction can confirm — and the fee goes to whoever broadcast the one that made it into a block. It is a competitive mechanism, conceptually close to mining: **the reward goes to whoever is actually operating**, not to whoever is merely listed in a directory.
+
+For you, the consequence is simple and reassuring: **only one of your selected Will-Executors has to still be alive on the delivery date** for the inheritance to be executed.
+
+!!! tip "Select as many as you can"
+    Redundancy is the whole guarantee. Each additional Will-Executor is another independent chance that someone is still there when it matters.
+
+## Who sets the fees
+
+Each Will-Executor freely sets its own commission — there is no price imposed by the protocol. The market sets the price.
+
+When creating your will you can exclude servers you consider too expensive. It is also worth being wary of **suspiciously cheap** ones: a price that cannot cover the cost of running a server for years is a hint that the service may not last.
+
+!!! warning "Don't lower the fee manually"
+    Fees are shown both on the [WeList](welist.md) and inside the plugin. Setting a fee below what a server asks will typically get your transaction rejected by that server.
+
+## New servers cannot join old wills
+
+Inheritance transactions are pre-signed and already contain the address of the Will-Executor that will be paid. A signed transaction cannot be modified — so a server that joins the network today receives the wills created **from today onwards**, never the ones already out there.
+
+This is why renewing your will periodically is useful: it brings newer Will-Executors into your selection. See [Keeping the will up to date](../user-guide/updating.md).
+
+## What they can see
+
+The Will-Executors you select receive pre-signed transactions that reflect the state of your wallet. That is why the choice of which servers receive them stays entirely in your hands, and why privacy — alongside reliability — is the real ground of competition between Will-Executors.
+
+Transactions stored on the servers are **not publicly accessible**. From the plugin you can verify at any time that yours is still there: see the [Server column](../user-guide/will-tab.md#the-server-column).