Hamming Backups: 2-of-3 variant of SeedXOR

TypeScript/JavaScript implementation of Hamming Backups: A 2-of-3 variant of SeedXOR.

Description

Seed XOR allows you to split up your BIP-39 seed phrase into multiple parts. The parts can then be used to reconstruct the original seed.

One shortcoming of SeedXOR is that you need all shares to recover the original mnemonic. Hamming Backups are a variant of SeedXOR that allow the original seed to be restored if only 2 out of 3 shares are available. Only 24-word mnemonics are supported.

Read more about the concepts behind SeedXOR on the official website: seedxor.com

Installation

npm install seed-xor-hamming

Requires Node.js >= 20.19.0. This package is ESM-only.

Example

import { combine, split } from 'seed-xor-hamming';

const original =
  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art';

const [share1, share2, share3] = await split(original, true);

console.log('Share 1:', share1);
console.log('Share 2:', share2);
console.log('Share 3:', share3);

const recovered = await combine(share1, share2); // Any 2 shares can be used

// The result is a tuple of 2 mnemonics: the original seed and the missing third share.
// The position depends on the input order. If you're unsure, just try both.
console.log('Recovered:', recovered);

For more examples, check the examples folder or the tests.

Documentation

This library exports two methods, split and combine.

Split

split is used to split an existing 24-word seed into 3 shares. It takes 2 parameters:

split(mnemonic: string, useRandom = false): Promise<[string, string, string]>

• mnemonic: The seed that should be split. Must be a valid 24-word BIP-39 mnemonic.
• useRandom: If true, shares are generated randomly (different each time). If false (default), shares are generated deterministically (same seed always produces the same shares).

Combine

combine is used to combine Hamming Backup shares and reconstruct the original seed phrase. You need 2 out of 3 shares to recover your seed phrase.

combine(share1: string, share2: string): Promise<[string, string]>

• share1: One of the Hamming Backup shares.
• share2: Another one of the Hamming Backup shares.

The result is a tuple of two mnemonics. One of them is the original seed, and the other is the missing third share. The position depends on the order of the inputs — there is no way to know which element is the original seed and which is the third share without additional context (e.g., by recognizing your original seed). This is an inherent property of the Hamming Backup algorithm. If you're unsure about the order, try both of the recovered seeds.

Testing

npm install
npm test

Test vectors are sourced from:

• Hamming Backups reference implementation
• Coldcard firmware documentation

Dependencies

We try to use only a minimal set of dependencies to reduce the attack surface of malicious code being added by one of those dependencies.

There are only 3 (non-dev) dependencies:

• bip39 (by bitcoinjs)
• @noble/hashes (by paulmillr)
• seed-xor (by AndreasGassmann)

Usages

Currently, the following wallets support or are working on integrating Hamming Backups:

• AirGap Vault (planned)

Credits

The original idea for the 2-of-3 Hamming Backups came from Adam P. Goucher. He created a reference implementation in Python. Most of this package's code is based on the reference implementation.

The project setup has been inspired by multiple bitcoinjs libraries, such as bip39 and bip85.

LICENSE

MIT