init

.gitea/workflows/mkdocs.yml

@@ -0,0 +1,58 @@
+site_name: BAL — Bitcoin After Life
+site_description: Documentation for BAL, the open-source Electrum plugin for Bitcoin digital inheritance
+site_url: https://bitcoin-after.life/docs/
+repo_url: https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_manual
+repo_name: Gitea
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: deep orange
+      accent: amber
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: deep orange
+      accent: amber
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.sections
+    - navigation.top
+    - navigation.footer
+    - search.suggest
+    - content.code.copy
+
+nav:
+  - Home: index.md
+  - User Guide:
+      - Installation: user-guide/installation.md
+      - Interface overview: user-guide/interface.md
+      - Setting up heirs: user-guide/heirs.md
+      - The WILL tab: user-guide/will.md
+      - Backup transaction: user-guide/backup-transaction.md
+      - Wallet backup & recovery: user-guide/wallet-backup.md
+      - Hardware wallets: user-guide/hardware-wallets.md
+  - Will-Executors:
+      - Service list: will-executor/service-list.md
+      - Running a server: will-executor/running-a-server.md
+  - Security & Privacy: security-privacy.md
+  - FAQ: faq.md
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - tables
+  - pymdownx.details
+  - pymdownx.superfences
+
+extra:
+  social:
+    - icon: material/web
+      link: https://bitcoin-after.life
+copyright: BAL Protocol 1.0 — Documentation draft based on User Manual revB

faq.md

@@ -0,0 +1,41 @@
+# FAQ
+
+## Can I set different inheritance dates for different heirs?
+
+Not in BAL 1.0 — the inheritance date is unique per wallet. Prepare a separate wallet per date: Electrum makes it easy to create and manage multiple wallets. See [Setting up heirs](user-guide/heirs.md#one-delivery-date-per-wallet).
+
+## Can I stagger the inheritance over time (like an annuity)?
+
+Not yet. This is planned for **Protocol version 2**: e.g., 10% per year for 10 years, or 1% per month — without third parties or intermediaries.
+
+## How do I quickly test the plugin?
+
+Set a near-term delivery time (e.g., Raw `18h`-equivalent, or an upcoming date/time) and set **check-alive to a past date** so it doesn't interfere. See [Quick testing](user-guide/heirs.md#2-check-alive-threshold).
+
+## Is the inheritance executed at the exact time I set?
+
+Roughly. With Raw values the plugin estimates the corresponding block number (tolerance of a few hours). On average execution happens about **1 hour after** the set time, due to the 11-block Bitcoin median.
+
+## What happens if I keep using the wallet after setting the inheritance?
+
+Nothing to worry about: on Electrum close, BAL detects balance/UTXO changes and updates the inheritance automatically. You can use the wallet for everyday transactions.
+
+## Can I use a hardware wallet?
+
+Yes — every hardware key compatible with Electrum works with BAL (Ledger, BitBox02, etc.).
+
+## What if all will-executor servers disappear?
+
+A highly unrealistic event, but you can enable the offline [backup transaction](user-guide/backup-transaction.md) as a fallback that works without any server.
+
+## What does the will-executor earn?
+
+The **base fee** you see in the service list — paid only on the inheritance date, and only to the **first** server that broadcasts the transaction to the nodes.
+
+## I restored my wallet from seed and the inheritance is gone. Why?
+
+The inheritance data is stored in the **wallet file**, not the seed. Always back up the wallet file (`File → Save backup`) and keep your wallet password safe.
+
+## How can I run a will-executor server?
+
+Write to [info@bitcoin-after.life](mailto:info@bitcoin-after.life). Operator documentation is [in preparation](will-executor/running-a-server.md).

index.md

@@ -0,0 +1,27 @@
+# BAL — Bitcoin After Life
+
+**BAL** is an open-source plugin for [Electrum](https://electrum.org), the gold standard of Bitcoin wallets, dedicated to managing **Bitcoin digital inheritance**.
+
+With BAL you define your heirs, a delivery date, and a list of *will-executor* servers. If you stop accessing your wallet, the pre-signed inheritance transaction is broadcast to the Bitcoin network on the date you set — with no third parties or intermediaries holding your funds.
+
+## Why a plugin and not a new wallet?
+
+Developing a new wallet (or forking Electrum) was not considered reasonable, so as not to put funds at risk. BAL leans on the most tested and secure open-source Bitcoin wallet — Electrum — with the goal that in the future the plugin will ship with Electrum by default.
+
+Being open source, anyone can view, modify, and distribute the plugin code.
+
+## How it works in short
+
+1. You add **heirs** (name, Bitcoin address, amount or percentage).
+2. You set a **delivery time** (locktime): the date the inheritance is transferred.
+3. You set a **check-alive threshold**: if you open your wallet after this time, BAL offers to postpone the inheritance — because you are evidently still alive.
+4. The plugin **prepares, signs, and broadcasts** the inheritance transaction to the will-executor servers, which will send it to the Bitcoin nodes on the delivery date.
+
+## Where to go next
+
+- New user? Start with [Installation](user-guide/installation.md).
+- Want to understand the core parameters? See [Setting up heirs](user-guide/heirs.md).
+- Interested in running a will-executor server? See [Running a server](will-executor/running-a-server.md).
+
+!!! note "Documentation status"
+    This site is a draft based on the **BAL Protocol 1.0 User Manual (revB)**. Corrections and contributions are welcome via the [Gitea repository](https://bitcoin-after.life/gitea/bitcoinafterlife/bal_plugin_manual).

security-privacy.md

@@ -0,0 +1,27 @@
+# Security & Privacy
+
+## UTXO consolidation caution
+
+When you send the **entire contents** of a wallet, you risk losing the privacy of your UTXOs.
+
+A good rule of thumb: execute the inheritance leaving a small remainder to another wallet, especially when there is only one heir. For example: 99.7% to the heir and 0.3% to a random Bitcoin address (e.g., taken randomly from a block explorer). This makes the transaction harder to interpret.
+
+## Same seed on multiple devices
+
+Using the same seed on multiple devices is **strongly discouraged**. If you spend even a single satoshi from another device, you change the wallet's UTXO structure and **invalidate the inheritance transaction** — nodes will discard it.
+
+## Read-only (watch-only) wallets
+
+If you monitor the wallet via Zpub/Xpub on other devices, funds received there are **not** automatically added to the inheritance. Open the wallet in Electrum with BAL so the plugin can update the UTXOs and re-send the will to the executors.
+
+## Wallet file vs. seed
+
+The BAL inheritance data lives in the **Electrum wallet file**, not in the seed. Keep backups of the wallet file (`File → Save backup`) and do not lose the wallet password: restoring from seed recovers the funds but **loses the inheritance configuration**.
+
+## Will-executor privacy
+
+Inheritance transactions stored on will-executor servers are not publicly accessible. Only your plugin can check their presence (right-click → **Check** in the WILL tab).
+
+## Backup transaction discretion
+
+If you deliver an offline [backup transaction](user-guide/backup-transaction.md) directly to an heir, the heir learns the date and amount of the inheritance — consider whether that is prudent, or use a notary/trusted person instead.

user-guide/backup-transaction.md

@@ -0,0 +1,29 @@
+# Backup transaction
+
+Accessible from `Tools → Plugins` (BAL parameters).
+
+**Backup Transaction** (default: *Disabled*) lets you keep the inheritance transaction (locktime TX) even **without** relying on the automation of the will-executor online servers.
+
+![Backup transaction parameter](../img/fig_p06_0.png)
+
+When enabled, you get an **offline backup of the signed legacy transaction** — useful in the (highly unrealistic) event that all will-executor servers are destroyed.
+
+The backup can be saved locally, on a USB stick, or wherever you prefer — and delivered through a notary, trusted persons, or even directly to the heir. In the latter case, note that the heir will learn they are receiving an inheritance on a specific date and of a specific amount, which could be imprudent.
+
+Once delivered to the heir, the backup transaction can be sent to the nodes via Electrum (on a date later than the delivery time) to receive the funds.
+
+## Risks of relying only on the backup
+
+1. The transaction is **invalidated** if you accidentally spend even one satoshi from the wallets whose UTXOs were pre-signed in the legacy transaction.
+2. Delivering the signed transaction reveals the inheritance and its value to the heir.
+3. Every step must be handled by hand, with risk of errors.
+
+## Saving the backup
+
+With Backup Transactions enabled, the transaction appears in the **WILL** tab with status `NONE` in the Will-Executor column.
+
+![Backup transaction in the WILL tab](../img/fig_p07_0.png)
+
+Right-click it, select **Details**, and save the transaction to your preferred medium (USB drive, cloud, NAS, etc.).
+
+![Transaction details](../img/fig_p07_1.png)

user-guide/hardware-wallets.md

@@ -0,0 +1,7 @@
+# Hardware wallets
+
+BAL works with hardware keys (Ledger, BitBox02, etc.).
+
+**All hardware keys that are compatible with and recognized by Electrum are compatible with the BAL plugin.**
+
+You can sign your legacy transaction with the hardware key exactly as you would a normal Electrum transaction, and keep using the inheritance-ready wallet for everyday transactions with hardware-key signing.

user-guide/heirs.md

@@ -0,0 +1,81 @@
+# Setting up heirs
+
+The **HEIRS** tab is where you define your inheritance. It has three core parameters plus the list of heirs.
+
+![HEIRS tab parameters](../img/fig_p03_0.png)
+
+## 1. Delivery time (locktime)
+
+The date on which the inheritance of your wallet will be transferred to the recipients on the blockchain.
+
+You can enter it in two ways:
+
+- **Raw (relative)** — a delay from today, using suffixes:
+    - `d` = days (`1d` = tomorrow)
+    - `y` = years (`1y` = one year from today)
+- **Date (absolute)** — a precise date.
+
+!!! note "Raw timing tolerance"
+    With Raw values the plugin estimates the blockchain block number corresponding to that time, so execution has a tolerance of a few hours. On average the inheritance is executed by nodes about **1 hour after** the set date and time (because of the 11-block Bitcoin median).
+
+The locktime can be **anticipated** to update the will.
+
+## 2. Check-alive (threshold)
+
+The "are you still alive?" check. This parameter — settable as relative (Raw) or absolute (Date) — defines the time window during which the inheritance will **not** be changed by postponing it.
+
+If you open your wallet **after** the threshold has passed, BAL asks whether you want to postpone the inheritance date: since you opened the wallet, you are evidently still alive, and you probably don't want the inheritance delivered while you're around.
+
+**Practical example.** Today is January 1, 2025. You set the inheritance for December 1, 2025 (11 months) and the check-alive threshold at 6 months (June 1, 2025):
+
+| Case | What happens |
+|---|---|
+| You never access the wallet again | On December 1, 2025 the inheritance is sent to Bitcoin nodes by the will-executors |
+| You access the wallet after 4 months (before the threshold) | Inheritance stays set for December 1, 2025 |
+| You access the wallet after 7 months (past the threshold) | The plugin asks if you want to postpone the inheritance date |
+
+!!! tip "Quick testing"
+    Setting the check-alive to a **negative/past** value (a date before today) effectively disables it. Useful for quickly testing the plugin with a near-term delivery time (e.g., 18 hours from now).
+
+## 3. Fees (satoshi/vbyte)
+
+The fee that goes to the **miners** to validate the inheritance transaction on the blockchain — the classic fee you pay every time you send bitcoin.
+
+We recommend keeping the default of **100 sat/vbyte**: it ensures the inheritance is accepted by miners even on days when the network is saturated.
+
+## Adding heirs — the [New HEIR] button
+
+![New heir window](../img/fig_p05_0.png)
+
+For each heir enter:
+
+- **Name** — name of the heir, with any details you prefer.
+- **Address** — the Bitcoin address where the inheritance will be sent.
+- **Amount** — how much to send, as a **percentage** or a **fixed value**.
+
+You can add many heirs — 10 or more.
+
+## Sizing of inheritance amounts (automatic 100%)
+
+The plugin always makes sure that **all** the value of the wallet is delivered to the heirs.
+
+- Wallet with 3 BTC; you assign 1 BTC to Jonny and 10% to Andrea → BAL sends 1 BTC to Jonny and **all the rest** (2 BTC) to Andrea.
+- You assign 5% to Jonny and 80% to Andrea → the plugin recalculates proportionally (5.9% and 94.1%) so the wallet is completely emptied. Without recalculation, 15% would remain stuck in the wallet.
+- You own 10 BTC and want to give **exactly** 4 to Jonny and 2 to Andrea → designate a third heir (e.g., another wallet of yours) to receive the remaining 4 BTC.
+
+!!! info "Deliberate burning"
+    If you want to make part of your wallet inaccessible forever (increasing digital scarcity), add yourself as an heir with the desired percentage pointing to an address of your own — or an unspendable one. This also improves transaction privacy, since destination wallets are harder to interpret.
+
+## Changing the delivery time
+
+If you change the delivery time of a will, BAL notifies you on Electrum close that the inheritance must be updated:
+
+- **Postponed**: the plugin creates a transaction (which you sign, cost ~100 sat/vbyte, sent to the miners) to invalidate the current inheritance, then creates the new postponed one.
+- **Anticipated**: the plugin simply sends a new inheritance transaction to the will-executor servers, which anticipates and invalidates the ones already stored.
+
+## One delivery date per wallet
+
+In BAL 1.0 the inheritance date is **unique** per wallet. If you need different dates per heir (e.g., 5 BTC to each of two children when each turns 18), prepare **separate wallets** — Electrum makes creating and managing multiple wallets easy.
+
+!!! info "Staggered inheritance (BAL 2.0)"
+    Version 1.0 does not support staggering the inheritance over time. Protocol version 2 (in development) will allow e.g. 10% per year for 10 years, or 1% per month — a kind of annuity without third parties or intermediaries.

user-guide/installation.md

@@ -0,0 +1,17 @@
+# Installation
+
+Installing the BAL plugin takes four steps:
+
+1. **Install the latest version of Electrum** (Bitcoin wallet) from [electrum.org](https://electrum.org).
+2. **Install the BAL plugin**: download the files from the [Bitcoin-after.life](https://bitcoin-after.life) site (or via the links on the Bitcointalk forum) and copy them into the Electrum plugins folder.
+3. **Activate the plugin** from the Electrum menu: `Tools → Plugins → BAL`.
+4. **Restart Electrum.**
+
+After restarting, two new tabs appear in the Electrum interface: **HEIRS** and **WILL**.
+
+![Electrum with the BAL plugin installed](../img/fig_p02_0.png)
+
+You are now ready to leave your digital legacy to your heirs.
+
+!!! tip "Defaults are fine"
+    You can leave the default plugin parameters: they are more than fine for 99% of inheritance cases.

user-guide/interface.md

@@ -0,0 +1,25 @@
+# Interface overview
+
+With BAL installed, Electrum shows two new tabs:
+
+## HEIRS tab
+
+The screen of the heirs to whom you want to leave your inheritance, together with the three core parameters: **Delivery time (locktime)**, **Check-alive (threshold)**, and **Fees**. See [Setting up heirs](heirs.md).
+
+## WILL tab
+
+The screen that shows the technical details of your inheritance:
+
+| Field | Meaning |
+|---|---|
+| Locktime | Date of the inheritance |
+| Creation time | When the inheritance transaction was created |
+| Transaction fee | Fee that goes to the miners |
+| Status | Progress of the transaction (see the [status table](will.md#transaction-statuses)) |
+| Heirs | The configured heirs |
+| Will-executor | Server address and associated base fee |
+
+See [The WILL tab](will.md) for details.
+
+!!! note
+    Inheritance with the BAL plugin can also be set on a wallet that is still receiving incoming transactions not yet confirmed on the blockchain.

user-guide/wallet-backup.md

@@ -0,0 +1,12 @@
+# Wallet backup & recovery
+
+To have a copy of your will, simply save the wallet from Electrum: `File → Save backup`.
+
+If your computer is stolen or breaks down, install Electrum plus the BAL plugin on a new machine and open the previously saved wallet file.
+
+!!! warning "Do not lose your Electrum wallet password"
+    If you lose it, you can no longer access the inheritance data saved with the wallet file. Restoring the wallet **from seed** gives you back your bitcoin funds, but the BAL inheritance data stored in the wallet file is **lost**.
+
+You can also **export the heirs list** for a printable copy of your inheritance.
+
+![Exporting the heirs list](../img/fig_p08_0.png)

user-guide/will.md

@@ -0,0 +1,54 @@
+# The WILL tab
+
+The **WILL** tab shows your inheritance transactions and their progress on each will-executor.
+
+![WILL tab](../img/fig_p11_0.png)
+
+## Columns
+
+| Column | Meaning |
+|---|---|
+| Locktime | The date of the inheritance |
+| Txid | Identifier of the Bitcoin transaction |
+| Will-Executor | Address of the will-executor |
+| Status | Progress of the transaction (see below) |
+
+## Commands
+
+1. **Prepare** — prepares the inheritance and puts it on the list.
+2. **Sign** — signs your legacy transaction with your private key (wallet password or hardware key).
+3. **Broadcast** — sends the inheritance transaction to the online will-executor servers in your [service list](../will-executor/service-list.md).
+4. **Display** — opens the *Will-Details* window with all available data: locktime, creation time, transaction fee (miners), status, heirs, will-executor address, and the will-executor's base fee.
+
+!!! note "Automatic execution on close"
+    When you close Electrum, the plugin automatically runs **Prepare → Sign → Broadcast** for any step not yet completed, to ensure the inheritance is correctly executed.
+
+## Checking storage on servers
+
+Transactions pushed to will-executor servers are stored there, but are **not publicly accessible** (for privacy). You can verify at any time that your transaction is properly stored: right-click the inheritance transaction in the WILL tab and select **Check**. If it is online on the server, its status becomes `Checked`.
+
+## Transaction statuses
+
+Transactions in the WILL tab are color-coded by status:
+
+| # | Status | Meaning | Color | HEX |
+|---|---|---|---|---|
+| 1 | New | New inheritance TX | White (transparent) | `#FFFFFF` |
+| 2 | Signed | TX signed in the wallet | Azure | `#2BC8ED` |
+| 3 | Pushed | TX sent to will-executor | Azure-green | `#73F3C8` |
+| 4 | Checked | TX actually present on the will-executor | Bright green | `#8AFA6C` |
+| 5 | Confirmed | TX confirmed on the blockchain | Gray | `#BFBFBF` |
+| 6 | Pending | TX awaiting confirmation on the blockchain | Yellow | `#FFCE30` |
+| 7 | Failed | Communication failure with the will-executor | Red | `#E83845` |
+| 8 | Invalidated | A UTXO input is no longer available | Orange | `#F87838` |
+| 9 | Replaced | A backdated-locktime transaction spends the same input | Violet | `#FF97E9` |
+
+## Behavior when the wallet balance or UTXOs change
+
+If the balance or UTXO set of your BAL-managed wallet changes (you receive or spend funds), the inheritance must be updated. **BAL checks this automatically when Electrum closes** and updates the inheritance if needed.
+
+This means you can use an inheritance-ready wallet for everyday Bitcoin transactions (ideally signing with a hardware key), knowing the entire wallet content will go to your heirs.
+
+!!! warning "Read-only wallets and shared seeds"
+    - If you receive funds on this wallet via a **read-only copy** on another device (Zpub/Xpub), those funds are **not** added to the inheritance until you open the wallet in Electrum with BAL, so the plugin can update the UTXOs and re-send the will to the executors.
+    - If you use the **same seed on multiple devices** (strongly discouraged), spending even one satoshi elsewhere **invalidates the inheritance**: the UTXO structure changes and nodes discard the inheritance transaction.

will-executor/running-a-server.md

@@ -0,0 +1,12 @@
+# Running a will-executor server
+
+!!! warning "Draft — to be written"
+    This section is a placeholder for the upcoming operator documentation: server requirements, installation, the push/check API used by the plugin, base-fee configuration, and privacy obligations.
+
+Will-executor servers earn the **base fee** set in the service list — paid on the inheritance date to the first server that broadcasts the transaction to the Bitcoin nodes.
+
+## Get in touch
+
+For installing a will-executor server, or to collaborate, send your request to:
+
+**[info@bitcoin-after.life](mailto:info@bitcoin-after.life)**

will-executor/service-list.md

@@ -0,0 +1,45 @@
+# Will-executor service list
+
+Will-executors are the online servers that store your signed inheritance transaction and broadcast it to the Bitcoin nodes on the delivery date.
+
+The service list window opens from the Electrum menu: `Tools → Will-executor`. It shows the official list of will-executor servers.
+
+![Will-executor service list](../img/fig_p09_0.png)
+
+You can modify the list: add a server manually or import a list of servers (found on the bitcointalk.org forum or the official BAL website).
+
+## Window commands
+
+| Command | Function |
+|---|---|
+| **Ping** | Checks which servers in the list are online (green dot = active) |
+| **Import** | Imports a will-executor list other than the default |
+| **Export** | Exports your list — useful for moving to another Electrum installation with BAL |
+| **Add** | Adds a will-executor server manually |
+
+## List columns
+
+| Column | Meaning |
+|---|---|
+| URL | Address of the will-executor |
+| Base Fee | Commission/reward for the will-executor (see below) |
+| Info | Server description or website link |
+| Default Address | Bitcoin address where the base fee will be sent |
+| S | Server status (green dot = online) |
+
+## Right-click menu on a server row
+
+1. **Select** — adds the green check mark; this will-executor will be used in your inheritance.
+2. **Edit** — edits the relevant column field.
+3. **Ping** — verifies the server is online.
+4. **Delete** — removes the server from the list.
+
+## How the base fee works
+
+The base fee rewards the will-executor for the cost of keeping the server online. The will-executor earns it **only on the inheritance date**, and **only if it is the first** to send the transaction to the nodes — creating competition among will-executors.
+
+Example: if you set up an inheritance that happens in 4 years, the will-executor earns the fee only in 4 years.
+
+## Privacy
+
+Transactions pushed to will-executor servers are stored there but are **not publicly accessible**. From your BAL plugin you can verify at any time that your transaction is stored: right-click it in the WILL tab → **Check** (status becomes `Checked`).