--- bip: 128 title: "Timelock-Recovery Storage Format" status: Draft type: Specification layer: "Applications" authors: ["Oren Z"] assigned: 2026-02-05 last_modified: 2026-03-16 topics: ["wallets"] license: "BSD-2-Clause" url: https://bipexplorer.com/bip/128 source: https://github.com/bitcoin/bips/blob/master/bip-0128.mediawiki --- # BIP 128: Timelock-Recovery Storage Format > **In plain English:** Proposes a standard file format for 'timelock recovery plans', pre-signed transactions that move funds to a backup location after a delay unless cancelled. Shared formats let one wallet create a plan and another service store, monitor or carry it out. ## Abstract This document proposes a standard format for saving timelock-recovery plans, to allow different wallets to generate them, and different services to monitor/execute them. ## Motivation Pre-signed transactions are one way to create a recovery-plan, for use in case of seed loss or inheritance. The most common example is a single pre-signed transaction with an `nLocktime` set to a future date, as explained in [BIP-65](https://bipexplorer.com/bip/65). One limitation of this approach is that in the happy-flow scenario, when the seed is not lost, and the `nLocktime` is about to be reached, the user must access their wallet and spend one of its UTXOs - in order to revoke the pre-signed transaction and prevent it from being able to move the funds with no cancellation period. This could be frustrating, for example, for users that split their seed over multiple geographic locations. _Timelock-Recovery plans_ are a way to pre-sign a pair of transactions that eventually move the funds to one or more secondary wallets - with a special `nSequence` relative-locktime in the second transaction, so that the user always has a cancellation-period. Executing and monitoring a _Timelock-Recovery plan_ thus requires more than broadcasting and monitoring a single transaction. It also requires mechanisms for accelerating the first transaction (which does not move most funds to the secondary wallet), for checking whether the relative-timelock has passed, and a more nuanced handling of reorgs. This BIP proposes a standard format for exporting _Timelock-Recovery plans_ from the wallet that generated them, and importing them into apps/services for monitoring/execution. ### Comparison with Script-Based Wallets Script-based wallets are another way to create recovery mechanisms, and can use absolute and relative locktimes using OP\_CHECKLOCKTIMEVERIFY ([BIP-65](https://bipexplorer.com/bip/65)) and OP\_CHECKSEQUENCEVERIFY ([BIP-112](https://bipexplorer.com/bip/112)). 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-119](https://bipexplorer.com/bip/119)) and OP\_CHECKCONTRACTVERIFY ([BIP-443](https://bipexplorer.com/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 `nSequence` relative-locktime according to the size of cancellation-period requested by the user, following the rules of [BIP-68](https://bipexplorer.com/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-140](https://bipexplorer.com/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 `nLocktime` 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-433](https://bipexplorer.com/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-68](https://bipexplorer.com/bip/68), the `nSequence` can represent a timespan in units of 512 seconds, when bit (1 << 22) is set. An example calculation is provided below: ```python n_sequence = (1 << 22) | round(cancellation_period_days * 24 * 60 * 60 / 512) ``` 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 `nSequence` 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 `Alert Transaction`. 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 `Alert Transaction`. Each address is a string of up to 100 characters. - alert\_address (mandatory): The Bitcoin address that receives the majority of funds in the `Alert Transaction`. A string of up to 100 characters. - alert\_inputs (mandatory): An array of up to 2439 inputs spent by the `Alert Transaction`. 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 `Alert Transaction` in uppercase hexadecimal format. A string of up to 800,000 characters. - alert\_txid (mandatory): The transaction ID of the `Alert Transaction`. A 64-character lowercase hexadecimal string. - alert\_fee (mandatory): The total fee paid by the `Alert Transaction` in satoshis. A non-negative integer. - alert\_weight (mandatory): The weight of the `Alert Transaction`. A positive integer, not higher than 400,000. - recovery\_tx (mandatory): The raw `Recovery Transaction` in uppercase hexadecimal format. A string of up to 800,000 characters. - recovery\_txid (mandatory): The transaction ID of the `Recovery Transaction`. A 64-character lowercase hexadecimal string. - recovery\_fee (mandatory): The total fee paid by the `Recovery Transaction` in satoshis. A non-negative integer. - recovery\_weight (mandatory): The weight of the `Recovery Transaction`. A positive integer, not higher than 400,000. - recovery\_outputs (mandatory): An array of up to 10,000 outputs from the `Recovery Transaction`. Each output is a tuple containing: `[address, amount_sats, label?]` 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 `[key, value]` pairs, sorting the array, stringifying, calculating the SHA256 hash of the result in lowercase hexadecimal format, and taking a prefix of at least 8 characters. "stringifying" in this context means converting the array to a JSON string following [ECMAScript's JSON.stringify function specification](https://262.ecma-international.org/16.0/index.html#sec-json.stringify) (without additional `replacer` or `space` arguments). This specification covers special cases such as non-ascii characters and newlines. Optional fields without a value should not be included in the key-value pairs array. Also, there should not be a key-value pair for the "checksum" field itself. Code example: ```javascript delete recoveryPlanJson.checksum; // In case the checksum was calculated previously and the object was then modified const checksumData = new TextEncoder().encode( JSON.stringify(Object.entries(recoveryPlanJson).sort()), ); const checksum = new Uint8Array(await crypto.subtle.digest('SHA-256', checksumData)); recoveryPlanJson.checksum = Array.from(checksum).map(b => b.toString(16).padStart(2, '0')).join('').slice(0, 8); ``` Checksum hex string should be at least 8 characters long. Wallets may choose to use a longer checksum. ## Rationale The JSON object will contain the raw transactions, in addition to other information - some of which could technically be extracted from the raw transactions. This is intentional, to let frontend UIs display the plan before uploading it to any service, without the need for complicated parsing in the frontend. Backend services that receive the JSON object for monitoring/execution are expected to validate that the information is consistent with the raw transactions. Also, if some wallet apps did not implement the specifications correctly, the services could write custom code based on the `wallet_kind`, `wallet_version` and `plugin_version` fields. Servers may decide to put more restrictions on JSON objects, for example to refuse storing very large transactions. Notice that the raw transactions (`alert_tx` and `recovery_tx`) are expected to be in uppercase hexadecimal format. This is useful for frontend UIs to display them as QR codes, which are more compact when using uppercase-only alphanumeric characters. ### Monitoring Timelock-Recovery Plans Checking whether the `Alert Transaction` is valid is trivial, via the `testmempoolaccept` RPC call in bitcoin core 0.17+. However, checking whether the `Recovery Transaction` is valid is more complex, since it depends on a UTXO created by the `Alert Transaction`. The `testmempoolaccept` RPC can receive a list of transactions in which the later transactions may depend on earlier transactions - however in our case the `Recovery Transaction` has an `nSequence` relative-locktime, and therefore calling `testmempoolaccept 'alert-tx' 'recovery-tx'` will fail, claiming that the `Alert Transaction` UTXO is not confirmed (and the required time window has not passed). We recommend services that want to verify the entire `Timelock-Recovery plan` to parse the `Recovery Transaction` and check its signatures manually, and reject complicated spending scripts. Discovering that the `Recovery Transaction` is invalid only at the time of execution, could lead to funds being locked forever. ## Reference Implementation JSON files can be generated using the Timelock Recovery plugin on [Electrum Wallet](https://electrum.org): [https://github.com/spesmilo/electrum/tree/master/electrum/plugins/timelock\_recovery](https://github.com/spesmilo/electrum/tree/master/electrum/plugins/timelock_recovery) Demo Video: [https://drive.google.com/file/d/10uXRouQbH1kz\_HC14WnmRnYHa3gPZY8l/preview](https://drive.google.com/file/d/10uXRouQbH1kz_HC14WnmRnYHa3gPZY8l/preview) Example JSON file: ```json { "kind": "timelock-recovery-plan", "id": "exported-692452189b301b561ed57cbe", "name": "Recovery Plan ac300e72-7612-497e-96b0-df2fdeda59ea", "description": "RITREK APP 1.1.0: Trezor Account #1", "created_at": "2025-11-24T12:39:53.532Z", "plugin_version": "1.0.1", "wallet_version": "1.0.1", "wallet_name": "RITREK Service", "wallet_kind": "RITREK BACKEND", "timelock_days": 2, "anchor_amount_sats": 600, "anchor_addresses": [ "bc1qnda6x2gxdh3yujd2zjpsd7qzx3awxmlaf9wwlk" ], "alert_address": "bc1qj0f9sjenwyjs0u7mlgvptjp05z3syzq7mru3ep", "alert_inputs": [ "a265a485df4c6417019b91379257eb387bceeda96f7bb6311794b8ed358cf104:0", "2f621c2151f33173983133cbc1000e3b603b8a18423b0379feffe8513171d5d3:0" ], "alert_tx": "0200000000010204F18C35EDB8941731B67B6FA9EDCE7B38EB579237919B0117644CDF85A465A20000000000FDFFFFFFD3D5713151E8FFFE79033B42188A3B603B0E00C1CB3331987331F351211C622F0000000000FDFFFFFF0258020000000000001600149B7BA329066DE24E49AA148306F802347AE36FFD205600000000000016001493D2584B33712507F3DBFA1815C82FA0A302081E02483045022100DCDBAE77C35EB4A0B3ED0DE5484206AB6B07041BE99B2BBAF0243C125916523C0220396959C3C52B2B1F9E472AEEE7C5D9540531B131C3221DE942754C6D0941397D012103C08FF3ADBA14B742646572BCA6F07AEB910666FB28E4DDDC40E33755E7C869D30248304502210089084472FDA3CF82D6ABC11BF1A5E77C9B423617C8B840F58C02746035B3BA6302203942AA1FA13F952F49FB114D48130A9AAF70151E7D09036D15734DB1F41A8B6001210397064EDED7DAD7D662290DC2847E87C5C27DA8865B89DDB58FDE9A006BA7DB3900000000", "alert_txid": "f1413fedadaf30697820bcd8f6a393fcc73ea00a15bea3253f89d5658690d2f7", "alert_fee": 231, "alert_weight": 834, "recovery_tx": "02000000000101F7D2908665D5893F25A3BE150AA03EC7FC93A3F6D8BC20786930AFADED3F41F101000000005201400001A6550000000000001600149B7BA329066DE24E49AA148306F802347AE36FFD0247304402204AFF87C2127F5697F300C6522067A8D5E5290CA8D140D2E5BCEF4A36606C5FE5022056673BEC5BB459DFFBD4D266EE95AEF0D701383ED80BD433A02C3C486A826D76012102774DBCD59F2D08EFF718BC09972ADC609FBC31C26B551B3E4EA30A1D43EEDB9700000000", "recovery_txid": "bc304610e8f282036345e87163d4cba5b16488a3bf2e4d738379d7bda3a0bca3", "recovery_fee": 122, "recovery_weight": 437, "recovery_outputs": [ [ "bc1qnda6x2gxdh3yujd2zjpsd7qzx3awxmlaf9wwlk", 21926, "My Backup Wallet" ] ], "metadata": "sig:825d6b3858c175c7fc16da3134030e095c4f9089c3c89722247eeedc08a7ef4f", "checksum": "92f8b3da" } ``` ## Copyright This document is licensed under the 2-clause BSD license.