Seed XOR

TypeScript/JavaScript implementation of Seed XOR: A simple way of securing seeds.

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. Each part is itself a valid BIP-39 mnemonic, so it can be stored and backed up like any normal seed phrase.

Supports 12, 18, and 24-word mnemonics.

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

Installation

npm install seed-xor

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

Example

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

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, 3, true);

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

const recovered = await combine([share1, share2, share3]);

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 seed into multiple shares. It takes 3 parameters:

split(mnemonic: string, numberOfShares: 2 | 3 | 4 = 2, useRandom = false): Promise<string[]>

• mnemonic: The seed that should be split. Must be a valid BIP-39 mnemonic (12, 18, or 24 words).
• numberOfShares: The number of shares to split into (2, 3, or 4). You need ALL shares to recover your seed phrase.
• useRandom: If true, shares are generated randomly (different each time). If false (default), shares are generated deterministically (same seed always produces the same shares), matching the Coldcard implementation.

Combine

combine is used to combine Seed XOR shares and reconstruct the original seed phrase. You need ALL shares to recover your seed phrase.

combine(shares: string[]): Promise<string>

• shares: An array of shares to combine. All shares must be the same word length. Can be provided in any order.

Testing

npm install
npm test

Test vectors are sourced from:

• Coldcard firmware reference implementation
• Coldcard firmware test suite
• Rust seedxor library

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 2 (non-dev) dependencies:

• bip39 (by bitcoinjs)
• @noble/hashes (by paulmillr)

Usages

Currently, the following wallets support or are working on integrating Seed XOR:

• Coldcard
• AirGap Vault (planned)

Credits

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

LICENSE

MIT