forked from bitcoinafterlife/bal-electrum-plugin
docs: add DUST section to inheritance-options (v0.4.7) and translate agent memory to English
- inheritance-options.md/.html: new section 4.8 explaining the dust limit (some-dust continues vs all-dust blocks), dust quick-reference row, golden rule #5, and footer bumped to v0.4.7 referencing core/heirs.py. - .agent_memory_tasks.md: translated remaining Italian user-quote lines to English (Point B2 = replace, English only, no Italian originals kept). - Verified: no Italian text remains in any repo doc; md/html mirrors in sync.
This commit is contained in:
@@ -235,6 +235,30 @@ Electrum <strong>close</strong>, not only on Prepare.</blockquote>
|
||||
<p>If heirs, percentages, fees, executors and locktimes all still match the signed transactions,
|
||||
<code>is_will_valid</code> returns <code>True</code> and <strong>nothing happens</strong>.</p>
|
||||
|
||||
<h3>4.8 An heir's share is below the dust limit (DUST)</h3>
|
||||
<p>Bitcoin refuses outputs that are too small to spend — the <strong>dust limit</strong>
|
||||
(the wallet's <code>dust_threshold</code>). BAL resolves each heir's final amount when it builds
|
||||
the will (<code>Heirs.prepare_lists</code>) and compares every share against that limit.</p>
|
||||
<ul>
|
||||
<li><strong>Some heirs are dust, others valid → build continues.</strong> Each dust heir is
|
||||
<strong>skipped</strong> (its share would be unspendable) and listed in the build report as
|
||||
<em>“… is DUST – excluded (amount below dust limit)”</em>. The will is still prepared, signed and
|
||||
checked with the payable heirs (unchanged behaviour).</li>
|
||||
<li><strong>EVERY heir is dust → build blocked.</strong> If all shares are below the dust limit the
|
||||
inheritance would pay nobody. As of <strong>v0.4.7</strong> BAL refuses it
|
||||
(<code>HeirAmountIsDustException</code>) and the <strong>Building Will</strong> window stops with a
|
||||
clear <span class="pill red">red</span> message: <em>“All heirs' shares are below the dust limit:
|
||||
the inheritance cannot be created. Increase the amounts or reduce the number of heirs.”</em>
|
||||
Nothing is built, signed, checked or added to the list.</li>
|
||||
</ul>
|
||||
<blockquote><strong>When?</strong> Typically with a <strong>very small balance</strong> split among
|
||||
<strong>percentage</strong> heirs, or when every fixed amount is below the dust limit. Fix: raise the
|
||||
per‑heir amounts or use fewer heirs.</blockquote>
|
||||
<blockquote><strong>Note (v0.4.7):</strong> the dust check lives in <code>prepare_lists</code>, which sees
|
||||
<strong>all</strong> heirs across <strong>all</strong> locktimes — a single transaction only covers the
|
||||
earliest locktime, so checking there would wrongly block a will whose later dates still have valid
|
||||
heirs. <strong>On‑chain fee:</strong> none (pre‑build safety check).</blockquote>
|
||||
|
||||
<h2>5. What happens on the will‑executor servers</h2>
|
||||
<table>
|
||||
<thead><tr><th>Your action</th><th>Effect on the servers</th></tr></thead>
|
||||
@@ -267,6 +291,7 @@ executor that <em>should</em> hold your tx did not return it — re‑Broadcast
|
||||
<tr><td>Check‑Alive threshold already passed</td><td class="yes">Yes after</td><td class="fee">Yes</td></tr>
|
||||
<tr><td>Any change to an <strong>already signed/sent</strong> will <strong>that postpones it or expires it</strong></td><td class="yes">Yes after</td><td class="fee">Yes</td></tr>
|
||||
<tr><td>Nothing changed</td><td class="no">No</td><td class="no">No</td></tr>
|
||||
<tr><td>Every heir's share below the dust limit (all‑dust) — build <strong>blocked</strong> (§4.8)</td><td class="no">No</td><td class="no">No</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
@@ -280,10 +305,11 @@ executor that <em>should</em> hold your tx did not return it — re‑Broadcast
|
||||
it is just a free <strong>rebuild</strong>.</li>
|
||||
<li>Always finish with <strong>Sign → Broadcast → Check</strong> so executors hold the current plan (green).</li>
|
||||
<li>The wallet is always <strong>fully emptied</strong> by the inheritance, so heir amounts must add up.</li>
|
||||
<li><strong>Mind the dust limit.</strong> A share below Bitcoin's dust limit is skipped; if <strong>every</strong> heir is dust the build is blocked with a clear message (§4.8) — raise the amounts or use fewer heirs.</li>
|
||||
</ol>
|
||||
|
||||
<footer>This document reflects BAL plugin v0.3.4. Behaviour is derived directly from
|
||||
<code>core/will.py</code> and <code>gui/qt/window.py</code>.</footer>
|
||||
<footer>This document reflects BAL plugin v0.4.7. Behaviour is derived directly from
|
||||
<code>core/will.py</code>, <code>core/heirs.py</code> and <code>gui/qt/window.py</code>.</footer>
|
||||
</div>
|
||||
|
||||
<script type="module">
|
||||
|
||||
@@ -227,6 +227,10 @@ the will is no longer coherent → it is treated like an heir change
|
||||
> whole spendable balance is distributed; otherwise an `AmountException` warns you
|
||||
> to adjust.
|
||||
|
||||
> **Watch the dust limit.** If a share is so small that it falls below Bitcoin's
|
||||
> *dust limit*, that heir is skipped (see §4.8). Splitting a tiny balance among
|
||||
> many heirs, or giving an heir a very small percentage, can produce dust shares.
|
||||
|
||||
### 4.5 Changing the transaction fee (sat/byte)
|
||||
|
||||
Each will item stores the fee rate it was built with. A different rate raises
|
||||
@@ -255,6 +259,43 @@ If heirs, percentages, fees, executors and locktimes all still match the signed
|
||||
transactions, `is_will_valid` returns `True` and **nothing happens** — your will
|
||||
stays exactly as broadcast to the executors.
|
||||
|
||||
### 4.8 An heir's share is below the dust limit (DUST)
|
||||
|
||||
Bitcoin refuses to create outputs that are too small to be worth spending — the
|
||||
so‑called **dust limit** (the wallet's `dust_threshold`). BAL resolves every
|
||||
heir's final amount when it builds the will (`Heirs.prepare_lists` →
|
||||
`fixed_percent_lists_amount` / `normalize_perc`) and compares each share against
|
||||
that limit.
|
||||
|
||||
- **Some heirs are dust, others are valid → build continues.** Each dust heir is
|
||||
**skipped** (its share would be unspendable). The build proceeds with the
|
||||
remaining valid heirs, and the build report lists every excluded heir as
|
||||
*“… is DUST – excluded (amount below dust limit)”* so you can see who was left
|
||||
out. Behaviour is unchanged: the will is still prepared, signed and checked
|
||||
with the payable heirs.
|
||||
|
||||
- **EVERY heir is dust → the build is blocked.** If *all* heirs' shares are below
|
||||
the dust limit, the inheritance would pay nobody (only the change and the
|
||||
will‑executor fee). Previously such an *empty* will was still built, signed,
|
||||
checked and shown in the list. As of **v0.4.7** BAL refuses it:
|
||||
`Heirs.prepare_lists` raises `HeirAmountIsDustException`, and the **Building
|
||||
Will** window stops with a clear **red** message:
|
||||
*“All heirs' shares are below the dust limit: the inheritance cannot be
|
||||
created. Increase the amounts or reduce the number of heirs.”*
|
||||
Nothing is built, signed, checked or added to the list.
|
||||
|
||||
> **When does this happen?** Typically with a **very small wallet balance** split
|
||||
> among **percentage** heirs (e.g. each heir ends up with a few hundred sats), or
|
||||
> when every fixed amount is set below the dust limit. The fix is exactly what
|
||||
> the message says: raise the per‑heir amounts, or reduce the number of heirs.
|
||||
|
||||
> **Note (v0.4.7):** the dust check lives in `prepare_lists`, which sees **all**
|
||||
> heirs across **all** locktimes with their final amounts. This is deliberate: a
|
||||
> single transaction only ever covers the earliest locktime, so checking there
|
||||
> would wrongly block a will whose *later* dates still have valid heirs.
|
||||
|
||||
- **On‑chain fee:** none — this is a pre‑build safety check; nothing is broadcast.
|
||||
|
||||
---
|
||||
|
||||
## 5. What happens on the will‑executor servers
|
||||
@@ -291,6 +332,7 @@ stays exactly as broadcast to the executors.
|
||||
| Check‑Alive threshold already in the past | ✅ after | ✅ **yes** |
|
||||
| Any change to an **already signed/sent** will **that postpones it or expires it** | ✅ after | ✅ **yes** (invalidate first) |
|
||||
| Nothing changed | ❌ | ❌ |
|
||||
| Every heir's share below the dust limit (all‑dust) — build **blocked** (§4.8) | ❌ | ❌ |
|
||||
|
||||
---
|
||||
|
||||
@@ -306,8 +348,11 @@ stays exactly as broadcast to the executors.
|
||||
*current* plan (green), not an obsolete one.
|
||||
4. The wallet is always **fully emptied** by the inheritance, so heir amounts must
|
||||
add up.
|
||||
5. **Mind the dust limit.** A share below Bitcoin's dust limit is skipped; if
|
||||
**every** heir is dust the build is blocked with a clear message (§4.8) —
|
||||
raise the amounts or use fewer heirs.
|
||||
|
||||
---
|
||||
|
||||
*This document reflects BAL plugin v0.3.4. Behaviour is derived directly from
|
||||
`core/will.py` and `gui/qt/window.py`.*
|
||||
*This document reflects BAL plugin v0.4.7. Behaviour is derived directly from
|
||||
`core/will.py`, `core/heirs.py` and `gui/qt/window.py`.*
|
||||
|
||||
Reference in New Issue
Block a user