ECPair: SECP256k1 Keypair Management for Bitcoin

Common errors

• TypeError: ECPair.makeRandom is not a function

  cause The `ECPair` object itself is not directly imported but is the result of calling `ECPairFactory` with an ECC library.
  fix Ensure you initialize `ECPair` by calling `const ECPair = ECPairFactory(tinysecp);` after importing `ECPairFactory` and `tiny-secp256k1`.

• Error: Missing TinySecp256k1Interface implementation. Please provide an ECC library (e.g., tiny-secp256k1).

  cause `ECPairFactory` was called without a valid implementation of `TinySecp256k1Interface` (most commonly `tiny-secp256k1`).
  fix Install `tiny-secp256k1` (`npm install tiny-secp256k1`) and pass it to the factory: `const tinysecp = require('tiny-secp256k1'); const ECPair = ECPairFactory(tinysecp);`

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require()` to import `ecpair` in an ES Module context.
  fix Use ES Module `import` syntax: `import { ECPairFactory } from 'ecpair';`.

Warnings

• gotcha The `ECPair.makeRandom()` method, when no custom `rng` function is provided, internally uses `crypto.getRandomValues`. This API was experimental in Node.js 18.19.0 and earlier. Running on older Node versions without the `--experimental-global-webcrypto` flag or a polyfill can lead to issues.
  Fix: For Node.js < 20, either provide a custom `rng` function (e.g., using `randombytes` package) or run Node.js with `--experimental-global-webcrypto` flag. Ensure your Node.js environment is v20.0.0 or higher.
• breaking Version 3.x of `ecpair` has moved to an ESM-first (ECMAScript Module) architecture and mandates Node.js >= 20.0.0. Direct `require()` statements for `ecpair` will generally not work in new projects or if your environment is configured for ESM. Similarly, the internal usage of `crypto.getRandomValues` instead of `randombytes` is a significant change.
  Fix: Update your project to use ES Modules (`import`/`export`) for `ecpair`. Ensure your Node.js version is 20.0.0 or higher. If you need CommonJS, consider using a bundler (like Webpack or Rollup) or stick to `ecpair` v2.x if compatible with your other dependencies.
• gotcha Passing a custom Random Number Generator (RNG) function to `ECPair.makeRandom({ rng: customRng })` requires extreme caution. A poorly implemented or compromised RNG can lead to predictable private keys, resulting in significant security vulnerabilities and loss of funds.
  Fix: Only provide a custom `rng` function if you fully understand cryptographic random number generation and have a strong justification for it. In most cases, rely on the default, cryptographically secure RNG provided by the library (which uses `crypto.getRandomValues`).

Install

• npm install ecpair npm
• yarn add ecpair yarn
• pnpm add ecpair pnpm

Imports

• ECPairFactory
  wrong:

  const { ECPairFactory } = require('ecpair');

  correct:

  import { ECPairFactory } from 'ecpair';

  ecpair v3 is an ESM-first package. This is the primary export for initializing the ECPair API.
• ECPairAPI
  wrong:

  import ECPair from 'ecpair'; // ECPairAPI is a type, not a runtime value

  correct:

  import { ECPairAPI } from 'ecpair';

  This is a TypeScript type definition. The runtime instance is created via `ECPairFactory`.
• TinySecp256k1Interface

  import { TinySecp256k1Interface } from 'ecpair';

  This is a TypeScript interface defining the required methods for the external ECC library (e.g., `tiny-secp256k1`).

Quickstart

This quickstart demonstrates how to initialize `ecpair` with an ECC library, generate random keypairs, and import keys from WIF, private keys, and public keys, including custom network and RNG function usage.

import { ECPairFactory, TinySecp256k1Interface, ECPairInterface } from 'ecpair';
import * as crypto from 'crypto';

// You need to provide an ECC library that implements TinySecp256k1Interface
// This is typically 'tiny-secp256k1'
const tinysecp: TinySecp256k1Interface = require('tiny-secp256k1');
const ECPair = ECPairFactory(tinysecp);

// Generate a random key pair
const keyPair1: ECPairInterface = ECPair.makeRandom();
console.log('Random Private Key (HEX):', keyPair1.privateKey?.toString('hex'));
console.log('Random Public Key (HEX):', keyPair1.publicKey.toString('hex'));

// Import from WIF
const wifKey = 'L45P2H58kPq611cRjP5H3rXfRjP5H3rXfRjP5H3rXfRjP5H3rXfRjP5H3rXfRjP5H3rXfRjP5H3rXf'; // Example WIF (DO NOT USE FOR REAL ASSETS)
const keyPair2: ECPairInterface = ECPair.fromWIF(wifKey);
console.log('WIF Public Key (HEX):', keyPair2.publicKey.toString('hex'));

// Import from a private key buffer
const privateKeyBuffer = crypto.randomBytes(32);
const keyPair3: ECPairInterface = ECPair.fromPrivateKey(privateKeyBuffer);
console.log('Imported Private Key (HEX):', keyPair3.privateKey?.toString('hex'));

// Import from a public key buffer
const keyPair4: ECPairInterface = ECPair.fromPublicKey(keyPair1.publicKey);
console.log('Imported Public Key (HEX):', keyPair4.publicKey.toString('hex'));

// Demonstrate custom network and RNG
const customNetwork = { messagePrefix: '\x18Bitcoin Signed Message:\n', bip32: { public: 0x0488b21e, private: 0x0488ade4 }, pubKeyHash: 0x00, scriptHash: 0x05, wif: 0x80 };
const customRng = (size: number): Buffer => crypto.randomBytes(size);
const keyPair5 = ECPair.makeRandom({ network: customNetwork, rng: customRng });
console.log('Custom Network Public Key (HEX):', keyPair5.publicKey.toString('hex'));