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. They do so primarily by increasing resilience though identification of the seed (in typed storage and with metadata) and through sharding of the seed to allow reconstruction (with Shamir’s Secret Sharing).

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: Identification Technologies (for Developers)

Helping a user to identify a seed offers another level of protection, because it stops them from accidentally using the wrong seed for a transaction (which might be the result of a phishing attack). The following Blockchain Commons technologies do this.

Object Identity Block (OIB)

Standardized Identification. An OIB is a best practice that standardizes a collection of data that will help users to identify seeds (and other digital data). It includes: an automatically generated name, an abbreviated digest, a type icon, a LifeHash, and (when identifying a seed) additional information for a master fingerprint.

The object of an OIB is to ensure that a user can understand at a glance what digital object they’re dealing with rather than trying to parse a long hex string.

  • For more, see OIB

LifeHash

Visual Hash. A LifeHash is a visual hash built from the SHA-256 hash of data and iterated through Conway’s Game of Life. It’s meant to provide identification of a digital value at a glance and is incorporated into the Object Identity Block (OIB) to help identify seeds, keys, and other large values used to protect digital assets.

IV: 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).

V. Sample Seeds

Blockchain Commons uses the following sample seeds in its examples and docs.

128-Bit seed

The example uses Blockchain Commons’ default 128-bit seed, YINMN BLUE.

HEX: 59f2293a5bce7d4de59e71b4207ac5d2
BIP-39 WORDS: fly mule excess resource treat plunge nose soda reflect adult ramp planet
BYTEWORDS: hawk whiz diet fact help taco kiwi gift view noon jugs quiz crux kiln silk tied omit keno lung jade
GORDIAN ENVELOPE (with METADATA): ur:envelope/lptpsogdhkwzdtfthptokigtvwnnjsqzcxknsktdoybdtpsojyhkinjtjnjtcxfwjzkpihcxfpiainiecxfekshsjnoyadcsspoybetpsosecyidbbwnnnoyaatpsoksdighisinjkcxinjkcxjlkpjpcxjkjyhsjtiehsjpiecxeheyetdpidinjycxjyihjkjycxjkihihiedmplrnihld
SEGWIT UR OUTPUT DESCRIPTOR: ur:output-descriptor/oeadisktjojeisdefzdydtaolytantjloxaxhdclaxvlcprfttldjobkredtlnhsidwybaeyjtswyandlgjnehtkdsidbkqzsrkphyfhsaaahdcxhnfgnepefxgdytryckticelyotsstoknfntavevaskiddmolsarntykbrybtjpksamtantjooeadlncsghykaeykaeykaocyhngrmuwzaycyzssajpsndifmkohy
SEGWIT TEXT OUTPUT DESCRIPTOR: wpkh([604b93f2/84'/0'/0']xpub6DVfq9VduocgjGeR69Nyr8CCi9w5gywnU7wXMYGswpHjffjcbLYNzz6G6555VDcSZLDwZPzJHJQabVWWgkpvYntpunL3UjHGrkCJ6VndbQf)#ncwysjuk

:warning: Do not use this seed to hold real monies; they could disappear immediately!

The following PDFs, which were exported from iOS SeedTool, demonstrate our best practices of documenting seeds and SSKR shares, including object identity blocks, Lifehash, Bytewords to help identification, and metadata in the form of notes to provide more content (and in some cases help recovery).

Seed PDF:
 SSKR PDF:

256-Bit seed

The example uses Blockchain Commons’ default 256-bit seed, KHAKI.

HEX: e3955cda304771c0031895637f55c3abe45153c87abd81c51ed14e8aafa1af13
BIP-39 WORDS: toe priority custom gauge jacket theme arrest bargain gloom wide ill fit eagle prepare capable fish limb cigar reform other priority speak rough imitate
BYTEWORDS: vial mild high twin duty fuel jugs rust apex cats mild idea lamb gyro scar play vibe gray guru soap kiln ruby lazy silk cook tent girl love pose obey pose brew exit gray king iced
GORDIAN ENVELOPE (with METADATA): ur:envelope/lptpsohdcxvlmdhhtndyfljsrtaxcsmdialbgosrpyvegyguspknrylyskckttgllepeoypebwoyadcsspoycfadzttpsotantjyoeadisktjojeisdefzdydtaolytantjloxaxhdclaodsjnasrfrtytvdcfvawyluladinygrgyjeesoekibtwdoecllafehgdezmpfrlfdaahdcxzttyeeetzmskiorkdntlwfrehytlhypajosrvthfcfplyklyjztdqzmemwgdotwlamtantjooeadlncsghykaeykaeykaocyuehdglzcaycyhdoytolnoybetpsosecyhhdnpafmoybdtpsoksdieyecendpidinjycxguihihiecxgdkpidjziniacxghihjkjycxhfihiajyjljpcxdegrishsjeindtsnlrfpjs
SEGWIT UR OUTPUT DESCRIPTOR: ur:output-descriptor/oeadisktjojeisdefzdydtaolytantjloxaxhdclaodsjnasrfrtytvdcfvawyluladinygrgyjeesoekibtwdoecllafehgdezmpfrlfdaahdcxzttyeeetzmskiorkdntlwfrehytlhypajosrvthfcfplyklyjztdqzmemwgdotwlamtantjooeadlncsghykaeykaeykaocyuehdglzcaycyhdoytolntdkezsfw
SEGWIT TEXT OUTPUT DESCRIPTOR: wpkh([de584efd/84'/0'/0']xpub6CJZ4hvDg49xgXpHh1h5MsKuxnpnu5m1shocnzueZUry1nrRjbAJhBPaDoByGSXKVyXJYdydRtiGps63oNP43hzbxHU9ey5mH3Cm6NNvSSo)#hxn88s0v

:warning: Do not use this seed to hold real monies; they could disappear immediately!