[bitcoindev] Re: BIP idea: Timelock-Recovery storage format

'orenz0' via Bitcoin Development Mailing List
2026-03-23T09:54:29Z

Hi Matt,
I can't find your message on https://groups.google.com/g/bitcoindev so I'll answer directly from my email.

> * What should be the value of the "checksum" field during the checksum calculation? Null? An empty string? Absent entirely? None of those options satisfy the schema, which mandates that the value must be a string of 8 to 64 characters. Perhaps a string of eight zeros?

The checksum field should be absent entirely during checksum calculation.

> * What is "an array of key, value pairs"? Is it [{"key":"one","value":1},{"key":"two","value":2}]? The example JavaScript code implies that it should be [["one",1],["two",2]], but this is not spelled out in the normative text. Typically in a specification, example code is non-normative, and all necessary information to implement the spec is provided in the normative text.

Your interpretation is correct, key-value pairs are exactly converting an object like {"one":1,"two":2} into [["one",1],["two",2]].
How would you improve the description of "...by converting the top-level JSON object to an array of [key, value] pairs" (in https://github.com/bitcoin/bips/blob/master/bip-0128.mediawiki#checksum-calculation )?
Converting objects into key-value pairs (i.e. with the Object.entries() function) is pretty common when the order of the keys is important - i.e. when you need a consistent hash. For example it is used in the Nostr protocol before signing event objects.

> * What does "stringifying" mean? There are many ways to encode abstract structured data into JSON. For instance, just look at all the possible "flags" that can be passed to PHP's json_encode function: https://www.php.net/json_encode . Are non-ASCII characters to be encoded in UTF-8 or as hex escapes? How about control characters? How are quotation marks to be escaped: as a backslash and a quotation mark or as a Unicode hex escape? Is there any optional whitespace between terminals in the encoding? If so, where, and are the line endings LF or CR+LF?

I think we should agree that "stringifying" means using Javascript's JSON.stringify() function with a single parameter (no "replacer" and no "space" parameters). All other programming languages should follow the ECMAScript specification.

Regards,
Oren

P.S. I'm curious what you're working on. If it's relevant, I'd be happy to publish it on https://timelockrecovery.com .
If you're looking for a good way to communicate the recovery details to your heirs, you should definitely check out the Timelock Recovery plugin for Electrum.
It's an internal plugin that was reviewed by Electrum's team (sometimes people hear the word "plugin" and assume it's external code).
The plugin lets you generate PDFs like this one: https://timelockrecovery.com/assets/recovery.pdf which includes a step-by-step tutorial for your heirs.

On Sunday, 8 March 2026 at 19:24, Matt Whitlock <bitcoin@mattwhitlock.name> wrote:

> On Sunday, December 28, 2025 at 9:59:43 AM UTC-5, Oren wrote:
> > The BIP will be about the JSON format, which includes not only the raw
> > transactions themselves, but also user-information (i.e. name, description,
> > destination-labels, wallet-name, wallet-version), and data about the
> > transactions (i.e. txids, amounts, fees, input-utxos, anchor-addresses,
> > relative-locktime).
> > A standard JSON format will allow implementing a compatible feature on
> > other wallets, as well as apps/servers for monitoring & initiating
> > timelock-recovery plans - such as the one being developed by RITREK.com
> > <https://ritrek.com> (disclosure: I'm one of RITREK's founders).
>
> I appreciate this BIP, as I have personally implemented a two-phase, relative-time-locked, alertable/recoverable transaction scheme to pass along my inheritance, but I had previously no standardized way of communicating the details of my implementation to my heirs. This BIP solves that problem, so thank you.
>
> However, in trying to implement the BIP, I am finding that the section describing the checksum calculation is extremely vague and not at all rigorous. Some questions include:
>
> * What should be the value of the "checksum" field during the checksum calculation? Null? An empty string? Absent entirely? None of those options satisfy the schema, which mandates that the value must be a string of 8 to 64 characters. Perhaps a string of eight zeros?
>
> * What is "an array of key, value pairs"? Is it [{"key":"one","value":1},{"key":"two","value":2}]? The example JavaScript code implies that it should be [["one",1],["two",2]], but this is not spelled out in the normative text. Typically in a specification, example code is non-normative, and all necessary information to implement the spec is provided in the normative text.
>
> * When sorting the array, how are elements to be compared? Are strings to be compared lexicographically? Is the comparison case-sensitive? What character encoding is used? Are strings compared lexicographically by UTF-8 code units, by UTF-16 code units, or by Unicode code points? How are non-string values to be compared with string values? Please sort the following values in ascending order: [12,false], 5, true, "seven".
>
> * What does "stringifying" mean? There are many ways to encode abstract structured data into JSON. For instance, just look at all the possible "flags" that can be passed to PHP's json_encode function: https://www.php.net/json_encode . Are non-ASCII characters to be encoded in UTF-8 or as hex escapes? How about control characters? How are quotation marks to be escaped: as a backslash and a quotation mark or as a Unicode hex escape? Is there any optional whitespace between terminals in the encoding? If so, where, and are the line endings LF or CR+LF?
>
> Perhaps there already exists a standard canonicalized encoding for JSON for purposes of digesting and MAC'ing, and your BIP could simply incorporate that standard by reference.
>

--
You received this message because you are subscribed to the Google Groups "Bitcoin Development Mailing List" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bitcoindev+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/bitcoindev/V4jlo4nh2GdJFIW0NM2ljGIWqgsKi5afoKeyGHgaBusUlSLeQU-JKKuiQ8cuRtlBi3566Y3qmGw4NOJz_LOE5Nfl1r6EqHM46kBPE38GEPs%3D%40protonmail.com.