For example, we can build a script that allows one main key to spend the funds at any time,
and a secondary key to spend the funds only in transactions with nLocktime above a certain
date/block-height, or only in transactions with nSequence above a certain relative
time-gap/number-of-blocks.
This makes the secondary key useful only after an absolute date/block-height, or after
a relative time since the funds were received (each UTXO independently).
This approach does have some advantages over pre-signed transactions, for example the
recovery-mechanism automatically applies to new funds received into the wallet.
However, script-based wallets have some disadvantages over a sequence of
pre-signed transactions:
* Script-based wallets are harder to implement correctly by hardware wallets, and harder to backup properly (i.e. users may forget to backup wallet-descriptors even for basic multisig wallets).
* As of the time of writing, scripts can limit when secondary-keys can be used, but not how they can be used: if the user doesn't touch the wallets' UTXOs for long-enough time, the secondary key will eventually become useable and could move the funds anywhere. This is true whether we measure the time in absolute terms (OP_CHECKLOCKTIMEVERIFY) or relative terms compared to when the wallets' UTXOs were created (OP_CHECKSEQUENCEVERIFY). This means that even in the happy-flow scenario of an untouched wallet, where no recovery is needed, the user must periodically "renew" the recovery-mechanism by spending the UTXO to a new wallet/address. This may be inconvenient in ultra-cold-storage scenarios (i.e. multisig with main keys hidden in different geographic locations). New opcode suggestions, such as OP_CHECKTEMPLATEVERIFY ([[bip-0119.mediawiki|BIP-119]]) and OP_CHECKCONTRACTVERIFY ([[bip-0443.mediawiki|BIP-443]]), discuss possible recovery-mechanisms in which in order for a secondary key to have full control over the funds, some onchain operations must be performed, with a required time-gap between them - giving the user enough time to revoke the whole process and move the funds elsewhere (assuming they still have the main key and the recovery-mechanism was triggered unintentionally). However, these suggestions are still in the discussion phase and even if ever implemented, their adoption may be slow.
* New Bitcoiners today typically don't think of such recovery-mechanisms in advance, and start with a P2WPKH wallet. They can pre-sign transactions with this wallet, but to utilize script-based features they would need to create a new wallet and move the funds there - an operation that might seem intimidating for large amounts.
== Specification ==
A ''Timelock-Recovery plan'' consists of two transactions:
* ''Alert Transaction'': A mostly-consolidation transaction that keeps most funds in the original wallet, except for a fee and a small fixed amount that goes to ''anchor-addresses'' - addresses which can be used to accelerate the ''Alert Transaction'' via CPFP. The majority of funds should remain on the original wallet, in a new previously-unused address which we call the ''alert-address''. We use the term ''Alert Transaction'' because monitoring the blockchain and looking for it should alert the user that the recovery-plan has been initiated (intentionally, unintentionally or maliciously).
* ''Recovery Transaction'': The transaction that moves the funds from the alert-address UTXO from the ''Alert Transaction'' to one or more addresses of secondary wallets (each may receive a different amount). This transaction should have a special <code>nSequence</code> relative-locktime according to the size of cancellation-period requested by the user, following the rules of [[bip-0068.mediawiki|BIP-68]].
With a reliable tool to monitor the blockchain for the ''Alert Transaction''
or the ''Alert Address'', the user can safely store online backups of the recovery plan's
JSON file (or, even without a tool, by checking the blockchain manually from time to time).
If the presigned transactions leak and the ''Alert Transaction'' is broadcast
unintentionally, the user has the cancellation period (expected to be at least a
few days) to prevent most funds from moving by sending them to a new address, thereby
invalidating the ''Recovery Transaction''.
It is important that the ''Alert Transaction'' will be non-malleable (e.g. by using
[[bip-0140.mediawiki|BIP-140]]).
If a malleable ''Alert Transaction'' is used, a malicious miner could replace the
''Alert Transaction'' with a similar transaction with a different txid,
making the ''Recovery Transaction'' invalid (pointing to a non-existent UTXO).
The <code>nLocktime</code> of both transactions should not be higher than the current
block height.
The ''anchor-addresses'' mentioned above, which are used for CPFP acceleration, could possibly
be P2A addresses (described in [[bip-0433.mediawiki|BIP-433]]), or other addresses under the
participants' control (i.e. addresses from the secondary wallets).
As of the time of writing, P2A is not widely adopted, and less-technical users may
struggle using them for CPFP acceleration - so we currently recommend using regular addresses.
=== nSequence calculation ===
Users will specify the cancellation-period in whole days between 2-388.
Following [[bip-0068.mediawiki|BIP-68]], the <code>nSequence</code> can represent a timespan in
units of 512 seconds, when bit (1 << 22) is set. An example calculation is provided below:
Users should be notified that the cancellation-period is not guaranteed to be exact (due to miners'
manipulation of block-timestamps).
Less than 2 days of cancellation-period and partial-days are not supported, as they are not useful.
More than 388 days of cancellation-period will overflow the <code>nSequence</code> field bits
allocated for the relative-locktime, and is not supported.
=== JSON format ===
For simplicity, this BIP proposes that a ''Timelock-Recovery plan'' will be saved as a JSON
object.
The JSON object will have the following fields:
* kind (mandatory): must be "timelock-recovery-plan".
* id (mandatory): a non-empty string of up to 100 characters, to represent the plan uniquely (i.e. a UUID, or a server generated ID).
* name (optional): a name for the plan, decided by the user. A string of up to 200 characters.
* description (optional): a description for the plan, decided by the user. A string of up to 10,000 characters.
* created_at (mandatory): an ISO 8601 timestamp of the plan creation time, including timezone offset ('Z' if the timezone is UTC).
* plugin_version (optional): The version of the plugin that generated the plan. A string of up to 100 characters.
* wallet_version (mandatory): The version of the wallet that generated the plan. A string of up to 100 characters.
* wallet_name (mandatory): The human-readable name of the wallet app that generated the plan. A string of up to 100 characters.
* wallet_kind (mandatory): The internal name of the wallet app that generated the plan. A string of up to 100 characters.
* timelock_days (mandatory): The cancellation period in whole days. A number between 2 and 388.
* anchor_amount_sats (mandatory): The amount in satoshis sent to each anchor address in the <code>Alert Transaction</code>. We recommend using 600 sats, which is above the dust limit.
* anchor_addresses (mandatory): An array of up to 10,000 Bitcoin addresses that receive the anchor amount in the <code>Alert Transaction</code>. Each address is a string of up to 100 characters.
* alert_address (mandatory): The Bitcoin address that receives the majority of funds in the <code>Alert Transaction</code>. A string of up to 100 characters.
* alert_inputs (mandatory): An array of up to 2439 inputs spent by the <code>Alert Transaction</code>. Each input is a string in the format "txid:vout" where txid is a 64-character lowercase hexadecimal string and vout is a decimal number of up to 6 digits. The maximal length of 2439 is calculated from a standard transaction of 400,000 wu where each input contains at least 41 bytes.
* alert_tx (mandatory): The raw <code>Alert Transaction</code> in uppercase hexadecimal format. A string of up to 800,000 characters.
* alert_txid (mandatory): The transaction ID of the <code>Alert Transaction</code>. A 64-character lowercase hexadecimal string.
* alert_fee (mandatory): The total fee paid by the <code>Alert Transaction</code> in satoshis. A non-negative integer.
* alert_weight (mandatory): The weight of the <code>Alert Transaction</code>. A positive integer, not higher than 400,000.
* recovery_tx (mandatory): The raw <code>Recovery Transaction</code> in uppercase hexadecimal format. A string of up to 800,000 characters.
* recovery_txid (mandatory): The transaction ID of the <code>Recovery Transaction</code>. A 64-character lowercase hexadecimal string.
* recovery_fee (mandatory): The total fee paid by the <code>Recovery Transaction</code> in satoshis. A non-negative integer.
* recovery_weight (mandatory): The weight of the <code>Recovery Transaction</code>. A positive integer, not higher than 400,000.
* recovery_outputs (mandatory): An array of up to 10,000 outputs from the <code>Recovery Transaction</code>. Each output is a tuple containing: <code>[address, amount_sats, label?]</code> where:
** address is a mandatory Bitcoin address string (up to 100 characters).
** amount_sats is a mandatory positive integer representing the amount in satoshis.
** label is an optional string of up to 200 characters.
* metadata (optional): A string of up to 10,000 characters for additional metadata, for example a digital-signature.
* checksum (mandatory): A checksum for verifying the integrity of the plan. A string of 8 to 64 characters.
=== Checksum Calculation ===
Notice that besides the top-level JSON object, all the internal values are either primitive or
arrays.
This is intentional, so a conversion of the values to JSON strings will be deterministic.
The checksum is calculated by converting the top-level JSON object to an array of
<code>[key, value]</code> pairs, sorting the array, stringifying, calculating the
SHA256 hash of the result in lowercase hexadecimal format, and taking a prefix of at least 8
