Blockchain Commons

Docs for Developers

LifeHashes are generated by inputting source data into SHA-256, generating a digest, and then using that digest as the input for LifeHash. See BCR-2021-002: Digests for Digital Objects for more information.

Seeds, master fingerprints, and keys are commonly input into LifeHash. Their digests may be generated as follows.

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: See QR code, above
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!

Creating a Seed Digest

LifeHashes of seeds are important when transferring a seed from one device to another or when indicating a seed that is being requested for a signature.

See “Seed Digest Source Specification” in BCR-2020-006 for the definition of a seed digest source.

  1. Use the hex representation of your seed as a source.
  2. Hash that hex source using SHA-256.
  3. Generate your LifeHash from the hash.

Source: 59f2293a5bce7d4de59e71b4207ac5d2 Hash: ffa11a8b90954fc89ae625779ca11b8f0227573a2f8b4ed85d96ddf901a72cea

Following are three methods that may be used to test the creation of the hex source from a seed.

1. Use shasum from the Command Line

$ echo -n 59f2293a5bce7d4de59e71b4207ac5d2 | xxd -r -p | shasum -b -a 256 | awk '{print $1}'
ffa11a8b90954fc89ae625779ca11b8f0227573a2f8b4ed85d96ddf901a72cea

Note that the hex is converted into binary so that shasum will correctly recognize it as hex and not text.

2. Use an Online Conversion Tool

Use an online function such as the SHA256 Online Hash Function. Be sure to choose “Hex” as your input choice and that you don’t have any trailing returns.

3. Use Blockchain Commons’ keytool

keytool will automatically output a seed-digest:

% keytool --seed-hex=59f2293a5bce7d4de59e71b4207ac5d2 seed-digest
ffa11a8b90954fc89ae625779ca11b8f0227573a2f8b4ed85d96ddf901a72cea

Creating a Master Fingerprint Digest

Lifehashes of master fingerprints are important when a watch-only public key is being transferred from one machine to another, such as when a seed vault is contributing a key to multisig.

A master fingerprint hash is generated directly from the four-byte masterfingerprint, leaving it with considerably less entropy than a seed or key.

  1. Generate the xpub for the master key from your seed.
  2. Calculate the master fingerprint of that xpub per BIP32 by calculating the RIPEMD160 of the SHA256 of the serialization of your public key, ignoring the chain code.
  3. Hash the four-byte fingerprint using SHA-256.
  4. Generate your LifeHash from the hash.

XPub: xpub661MyMwAqRbcGqsCi8m9DxP6DA8fQzEdAxUFum3MfL9MKPogjREiP6w7qjaeHuDUGuVmgCFf5iMntcyVoHsEFMKoxo7UxMpmafjeQofQezj Source: 604b93f2 Hash: 41c1955cd765eb84b32cac4d10d53b687caaf5e0d1d53260b00c4ddc8868d932

Creation of master fingerprints can be checked against a site such as Bitcoin Extended Public Key Converter or by using keytool.

$ keytool --seed-hex=59f2293a5bce7d4de59e71b4207ac5d2 master-key-fingerprint
604b93f2

Once you’ve generated the source, you can then use an online hash function or command line tools for testing:

$ echo -n 604b93f2 | xxd -r -p | shasum -b -a 256 | awk '{print $1}'
41c1955cd765eb84b32cac4d10d53b687caaf5e0d1d53260b00c4ddc8868d932

Creating a Key Digest

LifeHashes of keys are important when transferring a key from one device to another or when indicating a key that is being requested for a signature.

Keys have the most complex directions for creating a source, as described in the “HDKey Digest Source Specification”.

  1. Generate the xpub for your derivation path.
  2. Extract the chain code and key from your xpub using the BIP32 serialization format.
  3. Create a CBOR array with four objects: the key in hex, the chain code in hex, the coin type, and the coin network.
  4. Convert that CBOR structure to hex.
  5. Hash the CBOR structure using SHA-256.
  6. Generate your LifeHash from the hash.