diff --git a/docs/comparison.md b/docs/comparison.md index 9756874..cbada6e 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -1,4 +1,4 @@ -# How BAL compares +# :material-scale-balance: How BAL compares !!! info "This information may be out of date" This page compares other projects (Nunchuk, Liana) whose features and prices change diff --git a/docs/examples.md b/docs/examples.md index 708b3d7..fc9ec92 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -1,38 +1,92 @@ -# REAL EXAMPLE +# :material-script-text: An example of a proper succession plan with Bitcoin -!!! danger "Draft — needs review before publishing" - This page has not been checked against the plugin's actual behaviour. It - was written from the manual's own descriptions elsewhere, which may not - be complete or precise enough on their own — treat every claim below, - especially about costs and timing, as unverified until confirmed with - the developers or by testing directly. Do not treat it as authoritative - yet. +A concrete, start-to-finish walkthrough of how someone actually sets up a Bitcoin +inheritance with BAL — and keeps it current for years without spending anything. -Real-world scenarios, to make the mechanics concrete. +## Step by step -## Inheritance across three continents, renewed for years at no cost +
-**The setup.** Four heirs, living in three different countries. A delivery time of **5 years**, and several Will-Executors selected from the [WeList](will-executors/welist.md) for redundancy. +
+**:material-shield-check: Start from Electrum.** You use [Electrum](https://electrum.org), +a state-of-the-art Bitcoin wallet with one of the longest security track records in the +ecosystem. BAL builds on it rather than reinventing the wallet. +
-**Cost at setup: zero.** Both fees — the miner fee and the Will-Executor fee — are only paid **once**, at the moment a Will-Executor actually broadcasts the inheritance. Setting up the will, signing it, and sending it to several servers costs nothing beyond the wallet's own normal use. +
+**:material-usb-flash-drive: Add a hardware wallet (optional).** If you want, pair Electrum +with a hardware device to raise the security of your keys even further. BAL works the same +either way — Electrum still does all the signing. +
-**Staying current costs nothing, as long as you don't push the date later.** Ordinary use of the wallet — receiving funds, spending some, adding or editing an heir — makes the plugin rebuild the will automatically. Because this **anticipates** the delivery date by one day and redistributes it to the same Will-Executors, it is a free operation: no on-chain fee, no signature beyond the one Electrum already asks for. See [Postponing vs anticipating](user-guide/updating.md#postponing-vs-anticipating). +
+**:material-account-heart: You have funds to protect.** You hold bitcoin in Electrum that, +in case of an accident, death, or a lost seed, should reach your children — or simply a +backup wallet of your own. +
-!!! warning "One thing this does *not* do for free" - Bringing forward the inheritance simply brings the date forward by one day and resends it to the Will-Executors, at no cost. - If, on the other hand, you wish to maintain a fixed time horizon — "always 5 years from today", as explained in the [Delivery time](user-guide/delivery-time.md) section — in this case the date is postponed each time it is updated. - This involves postponing the date further into the future, which requires a full on-chain transaction to first invalidate the previously distributed will. This incurs a mining fee on the Bitcoin blockchain. +
+**:material-puzzle: Install the BAL plugin.** Add Bitcoin After Life to Electrum. See +[Installation](getting-started/installation.md). +
-**What this looks like over time:** +
+**:material-auto-fix: Set up the inheritance with the guided wizard.** BAL walks you through +the whole thing step by step — see [Create your first will](getting-started/quick-start.md). +
-- **Year 0.** The will is created: 5 years out, 4 heirs, several Will-Executors. Cost: 0. -- **Year 1–2.** The wallet is used normally — a few incoming and outgoing transactions. Each one triggers a free refresh. The delivery date itself hasn't moved, so the horizon has quietly shrunk to 3–4 years. Cost: 0. -- **Year 3.** Time to push the horizon back out to 5 years. This is a postponement: one small on-chain transaction to invalidate the old will before signing the new one. Cost: one miner fee, paid by the wallet owner. -- **Onward.** Repeat every 2–3 years — see [How often to renew](user-guide/updating.md#how-often-to-renew). Each cycle also picks up newer Will-Executors that joined the network since the last renewal. +
+**:material-account-group: Add your heirs and their shares.** Enter how many heirs receive +the funds and the share for each. *To avoid future disputes, equal shares for everyone are +usually the wisest choice.* +
-The heirs are not involved in any way throughout this entire process. They simply need to keep their receiving wallet safe, or the sheets on which the seed is written (Bitcoin private keys, 12 or 24 words), which we will have taken care to give them if they do not already have a Bitcoin wallet or are not old enough to manage one. -They do not need to know the date of the will, nor do they need to take any action: the entire mechanism operates invisibly until the day it is needed. -Furthermore, they do not know how much in Bitcoin funds awaits them, unless we choose to tell them. +
+**:material-calendar-clock: Choose the delivery date.** For example 5 or 10 years from now. +
+ +
+**:material-file-sign: The plugin builds the post-dated transaction.** It includes the fee +for the miners and for the Will-Executors — the servers that hold the will until the chosen +date and, on that day, broadcast it to the Bitcoin nodes that will accept the transaction. + +!!! success "Setting up and updating a will costs nothing" + You pay no fee to create or update an inheritance. The fees exist only in the transaction + itself and are paid **only if and when** the inheritance is actually executed. +
+ +
+**:material-refresh: Renew it once a year or two.** Mark it in your calendar. When you renew +— adding an heir, changing shares — the plugin rewrites the inheritance transaction and +re-sends it to the Will-Executors **dated one day earlier**, so you avoid an on-chain +transaction and any mining fee. Renewing regularly brings two real advantages: + +- **More redundancy** — each renewal can pick up additional Will-Executors that will hold +your will until the delivery date. +- **Future-proofing** — a fresh time-locked transaction can incorporate future Bitcoin +protocol upgrades, such as quantum-resistant security, as they arrive. +
+ +
+ +## Using your wallet normally + +Setting up an inheritance does not freeze your wallet — you keep using Electrum as usual. + +If you **receive** or **spend** funds after the will is set up, the next time you close +Electrum the BAL plugin checks your balance (by inspecting your UTXOs) and warns you if the +inheritance needs updating. + +Here too the plugin **anticipates the date by one day**. So a will set to execute on +**30 July 2031** is reissued for **29 July 2031** — with no need to write anything on-chain +and no miner fee. This works because an *earlier* time-locked transaction automatically +invalidates the later one it replaces. + +!!! info "Why anticipating is free, and postponing is not" + Moving the date **earlier** (anticipating) is free, because the new transaction simply + supersedes the old one. Moving the date **later** (postponing) is the one case that needs + a real on-chain transaction, and therefore a small miner fee. For the full mechanics see + [Keeping the will up to date](user-guide/updating.md#postponing-vs-anticipating). --- diff --git a/docs/faq.md b/docs/faq.md index 429e126..f4229f5 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,4 +1,4 @@ -# FAQ +# :material-help-circle: FAQ ## The project diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 9a9a344..5a4e69c 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1,4 +1,4 @@ -# Installation +# :material-puzzle: Installation ## Requirements diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md index 6abf473..2f0c1a9 100644 --- a/docs/getting-started/quick-start.md +++ b/docs/getting-started/quick-start.md @@ -1,4 +1,4 @@ -# Create your first will +# :material-auto-fix: Create your first will The plugin ships with a **guided wizard** that walks you through the whole setup. You only need two decisions: *who inherits* and *when*. diff --git a/docs/index.md b/docs/index.md index 0fdec5d..967a4dd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,11 +26,11 @@ You set your heirs and a delivery date. The plugin builds a time-locked transact
-- **New here?** → [Installation](getting-started/installation.md), then [create your first will](getting-started/quick-start.md). -- **Want the details?** → [Heirs and shares](user-guide/heirs.md), [Delivery time](user-guide/delivery-time.md), [The WILL tab](user-guide/will-tab.md). -- **Curious about the servers?** → [What Will-Executors are](will-executors/what-they-are.md). -- **Want to run one?** → [Running a Will-Executor](will-executors/running-a-server.md). -- **Just have a question?** → [**FAQ**](faq.md) — costs, hardware wallets, what happens if a server disappears, and more. +- :material-rocket-launch:{ .card-ico } **New here?** → [Installation](getting-started/installation.md), then [create your first will](getting-started/quick-start.md). +- :material-book-open-variant:{ .card-ico } **Want the details?** → [Heirs and shares](user-guide/heirs.md), [Delivery time](user-guide/delivery-time.md), [The WILL tab](user-guide/will-tab.md). +- :material-server-network:{ .card-ico } **Curious about the servers?** → [What Will-Executors are](will-executors/what-they-are.md). +- :material-server:{ .card-ico } **Want to run one?** → [Running a Will-Executor](will-executors/running-a-server.md). +- :material-help-circle:{ .card-ico } **Just have a question?** → [**FAQ**](faq.md) — costs, hardware wallets, what happens if a server disappears, and more.
diff --git a/docs/javascripts/nav-section-icons.js b/docs/javascripts/nav-section-icons.js new file mode 100644 index 0000000..8a35b83 --- /dev/null +++ b/docs/javascripts/nav-section-icons.js @@ -0,0 +1,29 @@ +// Prepend a Material icon to selected top-level nav entries (section titles and +// a couple of standalone links) in the sidebar, matched by exact label text. +// Nav labels are plain text in mkdocs.yml, so the theme cannot carry an icon for +// them — this adds it on the client side. +(function () { + var ICONS = { + 'Getting started': "", + 'User guide': "", + 'Will-Executors': "", + 'Protocol': "", + 'Example inheritance plan': "", + 'How BAL compares': "", + 'Security & Privacy': "" + }; + function decorate() { + document.querySelectorAll('.md-nav--primary label.md-nav__link, .md-nav--primary .md-nav__item--section > .md-nav__link, .md-nav--primary a.md-nav__link').forEach(function (label) { + var span = label.querySelector('.md-ellipsis'); + if (!span) return; + var name = span.textContent.trim(); + if (!ICONS[name] || label.querySelector('.nav-sec-ico')) return; + var holder = document.createElement('span'); + holder.className = 'nav-sec-ico'; + holder.innerHTML = ICONS[name]; + label.insertBefore(holder, label.firstChild); + }); + } + if (document.readyState !== 'loading') decorate(); + else document.addEventListener('DOMContentLoaded', decorate); +})(); diff --git a/docs/protocol/how-it-works.md b/docs/protocol/how-it-works.md index f6ab20a..1380e3c 100644 --- a/docs/protocol/how-it-works.md +++ b/docs/protocol/how-it-works.md @@ -1,4 +1,4 @@ -# How the protocol works +# :material-cog: How the protocol works A summary of the mechanism, for readers who want to understand what happens underneath the interface. diff --git a/docs/security-privacy.md b/docs/security-privacy.md index 049fb49..bab5462 100644 --- a/docs/security-privacy.md +++ b/docs/security-privacy.md @@ -1,4 +1,4 @@ -# Security & Privacy +# :material-shield-lock: Security & Privacy ## Where trust actually sits diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index ec1f27c..a51b30d 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -408,3 +408,90 @@ img.diagram + em { .md-typeset .compact-table table:not([class]) { font-size: .515rem; } .md-typeset .compact-table table:not([class]) th { font-size: .46rem; } .md-typeset .compact-table code { font-size: .9em; } + +/* -------- Numbered step list (examples page) ------------------------------ */ +.md-typeset .steps { counter-reset: step; margin: 1.3em 0; } +.md-typeset .steps .step { + position: relative; + padding: .15rem 0 .15rem 3rem; + margin: 0 0 1.2rem; + min-height: 2rem; +} +/* number badge */ +.md-typeset .steps .step::before { + counter-increment: step; + content: counter(step); + position: absolute; + left: 0; + top: -.05rem; + width: 2rem; + height: 2rem; + border-radius: 50%; + background: var(--bal-accent); + color: #fff; + display: flex; + align-items: center; + justify-content: center; + font-weight: 700; + font-size: .9rem; +} +/* connector line between badges */ +.md-typeset .steps .step:not(:last-child)::after { + content: ""; + position: absolute; + left: .97rem; + top: 2.2rem; + bottom: -1.2rem; + width: 2px; + background: var(--bal-line); +} +.md-typeset .steps .step > :first-child { margin-top: 0; } +.md-typeset .steps .step > :last-child { margin-bottom: 0; } +/* the Material icon at the start of each step title, tinted accent */ +.md-typeset .steps .step .twemoji { + color: var(--bal-accent); + margin-right: .15rem; +} +.md-typeset .steps .step .twemoji svg { + width: 1.1rem; + height: 1.1rem; + vertical-align: -.2rem; +} +/* admonitions nested inside a step sit tighter */ +.md-typeset .steps .step .admonition { margin: .6rem 0 0; } + +/* -------- Nav section icons (added by nav-section-icons.js) ---------------- */ +.md-nav--primary .nav-sec-ico { + display: inline-flex; + vertical-align: -.15em; + margin-right: .4em; +} +.md-nav--primary .nav-sec-ico svg { + width: .95rem; + height: .95rem; + fill: var(--bal-accent); +} + +/* -------- Homepage "Where to start" card icons ---------------------------- */ +.md-typeset .grid.cards .card-ico { + color: var(--bal-accent); + margin-right: .35em; +} +.md-typeset .grid.cards .card-ico svg { + width: 1.1rem; + height: 1.1rem; + vertical-align: -.2rem; +} + +/* -------- Page-title (H1) icons ------------------------------------------- */ +/* A themed Material icon sits at the start of each page's H1 (added in the + Markdown as :material-...:). Make it larger than body icons and tint accent. */ +.md-typeset h1 .twemoji { + color: var(--bal-accent); + margin-right: .5rem; +} +.md-typeset h1 .twemoji svg { + width: 1.6rem; + height: 1.6rem; + vertical-align: -.28rem; +} diff --git a/docs/user-guide/backup-transaction.md b/docs/user-guide/backup-transaction.md index 46f095a..d39444e 100644 --- a/docs/user-guide/backup-transaction.md +++ b/docs/user-guide/backup-transaction.md @@ -1,4 +1,4 @@ -# Offline backup transaction +# :material-usb-flash-drive: Offline backup transaction Beyond the Will-Executor network, the plugin can save the signed inheritance transaction to a **file you keep yourself**. It is the fallback for the (unlikely) scenario where every Will-Executor holding your will has ceased to operate. diff --git a/docs/user-guide/check-alive.md b/docs/user-guide/check-alive.md index a65b1eb..cfd15f6 100644 --- a/docs/user-guide/check-alive.md +++ b/docs/user-guide/check-alive.md @@ -1,4 +1,4 @@ -# Check Alive +# :material-heart-pulse: Check Alive **Check Alive** is the plugin's "are you still around?" mechanism. It is available in **advanced mode**. diff --git a/docs/user-guide/compatibility.md b/docs/user-guide/compatibility.md index b3f8578..8f5d913 100644 --- a/docs/user-guide/compatibility.md +++ b/docs/user-guide/compatibility.md @@ -1,4 +1,4 @@ -# Compatibility +# :material-check-decagram: Compatibility ## Wallet types diff --git a/docs/user-guide/delivery-time.md b/docs/user-guide/delivery-time.md index 5dedcf6..2c3d7ba 100644 --- a/docs/user-guide/delivery-time.md +++ b/docs/user-guide/delivery-time.md @@ -1,4 +1,4 @@ -# Delivery time +# :material-calendar-clock: Delivery time The **delivery time** (technically the transaction's `nLockTime`) is the date on which the Will-Executors broadcast your inheritance to the Bitcoin network. diff --git a/docs/user-guide/hardware-wallets.md b/docs/user-guide/hardware-wallets.md index 5ecf347..f199192 100644 --- a/docs/user-guide/hardware-wallets.md +++ b/docs/user-guide/hardware-wallets.md @@ -1,4 +1,4 @@ -# Hardware wallets +# :material-key-chain-variant: Hardware wallets BAL works with **any hardware wallet supported by Electrum** — Ledger, Trezor, Coldcard, BitBox02, Jade, KeepKey and others. diff --git a/docs/user-guide/heirs.md b/docs/user-guide/heirs.md index 2ff0707..8d9954c 100644 --- a/docs/user-guide/heirs.md +++ b/docs/user-guide/heirs.md @@ -1,4 +1,4 @@ -# Heirs and shares +# :material-account-group: Heirs and shares The **HEIRS** tab is where you define who receives your bitcoin. diff --git a/docs/user-guide/updating.md b/docs/user-guide/updating.md index 578f10e..92f8879 100644 --- a/docs/user-guide/updating.md +++ b/docs/user-guide/updating.md @@ -1,4 +1,4 @@ -# Keeping the will up to date +# :material-refresh: Keeping the will up to date An inheritance transaction spends specific UTXOs. If those UTXOs change, the transaction the Will-Executors are holding becomes invalid — so the will has to be rebuilt. diff --git a/docs/user-guide/wallet-backup.md b/docs/user-guide/wallet-backup.md index b078573..34a01f4 100644 --- a/docs/user-guide/wallet-backup.md +++ b/docs/user-guide/wallet-backup.md @@ -1,4 +1,4 @@ -# Backing up wallet and will +# :material-content-save: Backing up wallet and will ## Where your will actually lives diff --git a/docs/user-guide/wallet-recovery.md b/docs/user-guide/wallet-recovery.md index 3cd85d4..49e26fb 100644 --- a/docs/user-guide/wallet-recovery.md +++ b/docs/user-guide/wallet-recovery.md @@ -1,4 +1,4 @@ -# Using BAL as a wallet recovery net (or wallet backup) +# :material-lifebuoy: Using BAL as a wallet recovery net (or wallet backup) Inheritance is not the only use for a time-locked transaction. The same mechanism gives you a **decentralized safety net against losing your seed**. diff --git a/docs/user-guide/will-tab.md b/docs/user-guide/will-tab.md index 2d6b2d8..bc1ca39 100644 --- a/docs/user-guide/will-tab.md +++ b/docs/user-guide/will-tab.md @@ -1,4 +1,4 @@ -# The WILL tab +# :material-format-list-checks: The WILL tab The **WILL** tab is the technical view of your inheritance: one row per inheritance transaction, per Will-Executor. diff --git a/docs/will-executors/choosing.md b/docs/will-executors/choosing.md index 9f6aec4..e8a3303 100644 --- a/docs/will-executors/choosing.md +++ b/docs/will-executors/choosing.md @@ -1,4 +1,4 @@ -# Choosing Will-Executors in the plugin +# :material-checkbox-marked-circle-outline: 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. diff --git a/docs/will-executors/running-a-server.md b/docs/will-executors/running-a-server.md index b9d52a3..c5b22df 100644 --- a/docs/will-executors/running-a-server.md +++ b/docs/will-executors/running-a-server.md @@ -1,4 +1,4 @@ -# Running a Will-Executor +# :material-console: 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). diff --git a/docs/will-executors/welist.md b/docs/will-executors/welist.md index ea0a92a..f2ac4be 100644 --- a/docs/will-executors/welist.md +++ b/docs/will-executors/welist.md @@ -1,4 +1,4 @@ -# The WeList directory +# :material-format-list-bulleted: 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. diff --git a/docs/will-executors/what-they-are.md b/docs/will-executors/what-they-are.md index b05e4a8..293f44e 100644 --- a/docs/will-executors/what-they-are.md +++ b/docs/will-executors/what-they-are.md @@ -1,4 +1,4 @@ -# What Will-Executors are +# :material-server: 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. diff --git a/mkdocs.yml b/mkdocs.yml index b8c7cc3..f63562a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,10 +37,11 @@ theme: extra_css: # The ?v= suffix defeats browser caching of the stylesheet. Bump the number # whenever you change extra.css and the browser keeps showing the old style. - - stylesheets/extra.css?v=14 + - stylesheets/extra.css?v=17 extra_javascript: - javascripts/brand-notranslate.js # keep "Bitcoin After Life" untranslated in Chrome + - javascripts/nav-section-icons.js # small Material icon before each nav section title nav: - Home: index.md @@ -66,7 +67,7 @@ nav: - Running a Will-Executor: will-executors/running-a-server.md - Protocol: - How it works: protocol/how-it-works.md - - REAL EXAMPLE: examples.md + - Example inheritance plan: examples.md - How BAL compares: comparison.md - Security & Privacy: security-privacy.md @@ -91,6 +92,9 @@ markdown_extensions: - pymdownx.details - pymdownx.superfences - pymdownx.tabbed: { alternate_style: true } + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - toc: { permalink: true } # --- Italian translation (not enabled yet) ------------------------------------