Blockchain Commons

Docs for Developers

Target Technology: Cryptocurrency & Digital Identity
Target Audience: Crypto Developers

Seeds are the foundations for the keys that protect cryptocurrencies and digital assets. They must be protected so that they’re secure (avoiding compromise) and resilient (avoiding loss). This touchpoint details Blockchain Commons tutorials and technologies that accomplish these goals.

I: Resilience Tutorials (for Users & Developer)

The following user-level documents demonstrate best practices for protecting seeds, some of them using various Blockchain Commons technologies.

Smart Custody

Book & Articles. Our Smart Custody book was our initial release on how to protect your seeds with a variety of devices available at the time of writing. We’ve since supplemented it with articles on technologies such as multisig and Shamir’s Secret Sharing, which were not easily available at the time of our initial writing.

This is the simple beginning to protecting seeds, using systematic risk assessment and guarding against the threats that endanger you personally.

Protecting Seeds

CLI Guides. Blockchain Commons has produced a number of CLI guides that demonstrate how to generate and/or protect seeds for use generally or with specific blockchains such as Bitcoin and Ethereum.

It does so via a variety of methods, including storing metadata in a Gordian Envelope, encryption, and sharding shares of a secret using SSKR envelopes.

II: Protective Technologies (for Developers)

Though our Smart Custody guide includes general best practices, other seed protection is offered by specific Blockchain Commons technologies.

Gordian Envelope

Data Format. Envelope is a smart document format that allows for the structured storage of information in a radically recursive format, with the ability to elide, encrypt, compress, or lock any information within the envelope.

Gordian Envelope is an excellent format for storing seeds (and other secrets such as private keys, or even just sensitive information) not just for its elision and encryption abilities, but also because the secrets can be stored along with metadata, which can improve the resilience of secrets by offering hints on how to recover them or what to do with them when they’re recovered.

Sharded Secret Key Reconstruction (SSKR)

Data Resilience. Storing a secret in just one place makes it vulnerable to a Single Point of Failure (SPOF), but storing it in lots of places makes it vulnerable to a Single Point of Compromise (SPOC). Shamir’s Secret Sharing offers a great middle ground: it shards a secret into multiple shares. With a threshold such as 2-of-3, no single share can compromise the secret, but a share can be lost and the secret is preserved.

SSKR is Blockchain Commons’ expansion of Shamir’s Secret Sharing that allows for thresholds of not just individuals, but also groups. It’s also available in a security-reviewed library.

Envelopes can be locked with SSKR shares, where the content of the envelope can only be recovered if a threshold of envelopes, each with an SSKR share, are combined. This is an SSKR Envelope.

SSKR is also built into a number of Blockchain Commons’ reference apps, including envelope-cli, seedtool-cli, and the iOS Seedtool.

  • For more, see SSKR
  • For reference apps, see the Apps page, or the list below.

Uniform Resources (URs)

Data Format. URs are a data format that encodes binary CBOR data into text strings. Because envelopes are CBOR, this means that they can be encoded as text strings, which allows for their long-term storage. This is done using ByteWords.

URs are also self-describing. For example, any envelope UR starts with `ur:envelope/”. This makes URs resilient because it’s easy to see what they are (and therefore how to recover them) into the far future.

Collaborative Seed Recovery (CSR)

Data Resilience. CSR utilizes SSKR to shard a secret and then stores those secrets on independent remote servers. This offers considerable resilience over ad hoc methods of share storage (such as keeping them with relatives and friends).

Though Blockchain Commons has prototyped the Gordian Depository, which allows for the exchange of seed envelopes using GSTP, to date the technology remains largely theoretical because of the need for multiple, independent servers willing to accept the liability of seed storage.

III: Reference Applications (for Developers)

Several reference apps demonstrate the usage of Blockchain Commons’ seed protection technologies as well as other best practices.

iOS Seedtool

iOS App. iOS Seedtool demonstrates the creation of seeds and the backup of seeds as envelopes with notes metadata, as URs, as SSKR shares, and as SSKR envelopes.

Envelope-CLI

Rust CLI App. envelope-cli parallels iOS Seedtool from the command line. It similarly allows for the creation of seeds as envelopes with freeform metadata and the backup of seeds as URs and as SSKR envelopes.

Keytool-CLI

Python CLI App. keytool-cli is a transformer, allowing seeds to be converted into a number of other formats, most notably including account keys and descriptors for Bitcoin.

Keytool is somewhat deprecated, as it’s never been updated to Rust, but remains a crucial reference for seed storage.

Seedtool-CLI

Rust CLI App. seedtool-cli focuses on the creation of seeds, which can be output as URs, as Envelopes, as SSKR shares, and as SSKR envelopes (plus a number of other formats).