https://github.com/paulmillr/scure-bip39

Secure, audited & minimal implementation of BIP39 mnemonic phrases
https://github.com/paulmillr/scure-bip39

bip32 bip39 code mnemonic mnemonic-phrase

Last synced: about 2 months ago
JSON representation

Secure, audited & minimal implementation of BIP39 mnemonic phrases

• Host: GitHub
• URL: https://github.com/paulmillr/scure-bip39
• Owner: paulmillr
• License: mit
• Created: 2021-12-21T06:55:51.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-04-04T16:25:09.000Z (6 months ago)
• Last Synced: 2024-05-18T14:43:48.108Z (4 months ago)
• Topics: bip32, bip39, code, mnemonic, mnemonic-phrase
• Language: TypeScript
• Homepage: https://paulmillr.com/noble/#scure
• Size: 600 KB
• Stars: 109
• Watchers: 5
• Forks: 27
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/funding.yml
  • License: LICENSE
  • Audit: audit/2022-01-05-cure53-audit-nbl2.pdf
  • Security: SECURITY.md

Awesome Lists containing this project

README

        
# scure-bip39

Audited & minimal JS implementation of [BIP39 mnemonic phrases](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki).

- 🔒 [**Audited**](#security) by an independent security firm

- 🔻 Tree-shakeable: unused code is excluded from your builds

- 📦 ESM and common.js

- ➰ Only 2 audited dependencies by the same author:

  [noble-hashes](https://github.com/paulmillr/noble-hashes) and [scure-base](https://github.com/paulmillr/scure-base)

- 🪶 37KB with all deps bundled and 279KB with wordlists: much smaller than similar libraries

Check out [scure-bip32](https://github.com/paulmillr/scure-bip32) if you need

hierarchical deterministic wallets ("HD Wallets").

### This library belongs to *scure*

> **scure** — audited micro-libraries.

- Zero or minimal dependencies

- Highly readable TypeScript / JS code

- PGP-signed releases and transparent NPM builds

- Check out [homepage](https://paulmillr.com/noble/#scure) & all libraries:

  [base](https://github.com/paulmillr/scure-base),

  [bip32](https://github.com/paulmillr/scure-bip32),

  [bip39](https://github.com/paulmillr/scure-bip39),

  [btc-signer](https://github.com/paulmillr/scure-btc-signer),

  [starknet](https://github.com/paulmillr/scure-starknet)

## Usage

> npm install @scure/bip39

```js

import * as bip39 from '@scure/bip39';

import { wordlist } from '@scure/bip39/wordlists/english';

// Generate x random words. Uses Cryptographically-Secure Random Number Generator.

const mn = bip39.generateMnemonic(wordlist);

console.log(mn);

// Reversible: Converts mnemonic string to raw entropy in form of byte array.

const ent = bip39.mnemonicToEntropy(mn, wordlist)

// Reversible: Converts raw entropy in form of byte array to mnemonic string.

bip39.entropyToMnemonic(ent, wordlist);

// Validates mnemonic for being 12-24 words contained in `wordlist`.

bip39.validateMnemonic(mn, wordlist);

// Irreversible: Uses KDF to derive 64 bytes of key data from mnemonic + optional password.

await bip39.mnemonicToSeed(mn, 'password');

bip39.mnemonicToSeedSync(mn, 'password');

```

This submodule contains the word lists defined by BIP39 for Czech, English, French, Italian, Japanese, Korean, Portuguese, Simplified and Traditional Chinese, and Spanish. These are not imported by default, as that would increase bundle sizes too much. Instead, you should import and use them explicitly.

```typescript

function generateMnemonic(wordlist: string[], strength?: number): string;

function mnemonicToEntropy(mnemonic: string, wordlist: string[]): Uint8Array;

function entropyToMnemonic(entropy: Uint8Array, wordlist: string[]): string;

function validateMnemonic(mnemonic: string, wordlist: string[]): boolean;

function mnemonicToSeed(mnemonic: string, passphrase?: string): Promise;

function mnemonicToSeedSync(mnemonic: string, passphrase?: string): Uint8Array;

```

All wordlists:

```typescript

import { wordlist as czech } from '@scure/bip39/wordlists/czech';

import { wordlist as english } from '@scure/bip39/wordlists/english';

import { wordlist as french } from '@scure/bip39/wordlists/french';

import { wordlist as italian } from '@scure/bip39/wordlists/italian';

import { wordlist as japanese } from '@scure/bip39/wordlists/japanese';

import { wordlist as korean } from '@scure/bip39/wordlists/korean';

import { wordlist as portuguese } from '@scure/bip39/wordlists/portuguese';

import { wordlist as simplifiedChinese } from '@scure/bip39/wordlists/simplified-chinese';

import { wordlist as spanish } from '@scure/bip39/wordlists/spanish';

import { wordlist as traditionalChinese } from '@scure/bip39/wordlists/traditional-chinese';

```

## Security

To audit wordlist content, run `node scripts/fetch-wordlist.js`.

The library has been independently audited:

- at version 1.0.0, in Jan 2022, by [cure53](https://cure53.de)

  - PDFs: [online](https://cure53.de/pentest-report_hashing-libs.pdf), [offline](./audit/2022-01-05-cure53-audit-nbl2.pdf)

  - [Changes since audit](https://github.com/paulmillr/scure-bip39/compare/1.0.0..main).

  - The audit has been funded by [Ethereum Foundation](https://ethereum.org/en/) with help of [Nomic Labs](https://nomiclabs.io)

The library was initially developed for [js-ethereum-cryptography](https://github.com/ethereum/js-ethereum-cryptography).

At commit [ae00e6d7](https://github.com/ethereum/js-ethereum-cryptography/commit/ae00e6d7d24fb3c76a1c7fe10039f6ecd120b77e),

it was extracted to a separate package called `micro-bip39`.

After the audit we've decided to use `@scure` NPM namespace for security.

## License

[MIT License](./LICENSE)

Copyright (c) 2022 Patricio Palladino, Paul Miller (paulmillr.com)