Mnemonic and seed

Your 12 words are not a password. They are your wallet’s random number, written in a form people can copy by hand without mistakes.

Every private key the wallet will ever use is computed from them, in a fixed order. Lose the computer, keep the words, and you can rebuild everything. Let someone else see the words, and they can rebuild everything too. That’s the whole story; the rest of this page is the arithmetic.

Try it

Generate a phrase, or type the test phrase, and watch the seed, the keys and the first addresses appear.

How do 12 words hold a random number?

Through a fixed list of 2,048 English words. 2,048 is 2¹¹, so each word stands for exactly 11 bits.

1. Draw 128 random bits

   The entropy. Pearl’s wallet asks the operating system for 16 random bytes.

2. Add a checksum

   Hash the entropy with SHA-256 and take the first 4 bits. Append them: 132 bits.

3. Cut into 11-bit groups

   12 groups, each a number from 0 to 2,047.

4. Look up the words

   Each number picks a word from the English list (abandon = 0, ability = 1, able = 2, about = 3, …).

Worked example: the test phrase

The BIP-39 test vector uses all-zero entropy. It is published everywhere, so it is the least safe phrase in the world. Here is how it comes out:

How do the words become a seed?

With a deliberately slow function. BIP-39 runs PBKDF2 with HMAC-SHA512 2,048 times over the words:

The words go in as plain text, joined by single spaces. On Pearl the passphrase is always empty, so the salt is just the 8 letters “mnemonic”. For the test phrase:

Size

64 bytes

Type

BIP-39 seed

Format

PBKDF2-HMAC-SHA512 output

That 64-byte seed is what the wallet actually uses. The next step, turning it into a master key with HMAC-SHA512 and the key “Bitcoin seed”, is on the extended keys page.

What do Pearl wallets do differently?

The format is standard BIP-39. The habits around it are Pearl’s own:

• Always 12 words. oyster --create and the desktop wallet both generate 128 bits of entropy. 24-word phrases are never created.
• Imports are more flexible. The desktop wallet’s import screen accepts 12, 15, 18, 21 or 24 English words (checksum checked), or a raw hex seed.
• No passphrase. Every seed computation in Oyster passes an empty passphrase. There is no “25th word” option anywhere.
• English only. The word list is never changed from English.
• A short quiz. After showing the phrase, the desktop wallet asks you for words 3, 7 and 12 before it continues.

Will my words work in another wallet?

In Pearl’s own wallets, yes: Oyster, oystercli and the desktop wallet all derive the same addresses from the same words.

Elsewhere, be careful. A generic “BIP-86 wallet with coin type 808276” will match Pearl for most seeds, but not all. Oyster inherits an old quirk in hardened key derivation that gives different addresses for about 0.8% of seeds. The derivation paths page shows a real phrase where the two disagree.

How should you store the words?

• Write them on paper or metal, in order, spelled exactly. Not in a photo, a cloud note or an email.
• Never type them into a website, a chat, or a form that “verifies your wallet”. No one from Pearl will ever ask for them.
• Keep them as safe as the coins. Anyone who reads them owns the wallet, from anywhere, without your computer.

import { generateMnemonic, mnemonicToSeedSync, validateMnemonic } from '@scure/bip39';
import { wordlist } from '@scure/bip39/wordlists/english.js';

const words = generateMnemonic(wordlist, 128);      // 12 words, like a new Pearl wallet
validateMnemonic(words, wordlist);                  // true
const seed = mnemonicToSeedSync(words, '');         // 64 bytes; Pearl's passphrase is always ''