KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #ai-agents #dsh-plugin #codex #developer-tools #claude-code #windows #desktop-app #typescript #rust #ai-agent #cli

scure-btc-signer

★ 237 Open GitHub ↗

Audited & minimal library for creating, signing & decoding Bitcoin transactions.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# scure-btc-signer

Audited & minimal library for creating, signing & decoding Bitcoin transactions.

- 🔒 [**Audited**](#security) by an independent security firm
- ✍️ Create transactions, inputs, outputs, sign them
- 📡 Optional network helper; core signer works offline
- 🔀 UTXO selection with different strategies
- 🎻 Classic & SegWit: P2PK, P2PKH, P2WPKH, P2SH, P2WSH, P2MS
- 🧪 Schnorr & Taproot BIP340/BIP341: P2TR, P2TR-NS, P2TR-MS
- 📨 BIP174 PSBT, BIP327 MuSig2
- 🗳️ Easy ordinals and inscriptions
- 🪶 39KB (gzipped) with all deps

Initial development has been funded by [Ryan Shea](https://shea.io).
Musig2 feature has been funded by [Arklabs](https://arklabs.to).

For discussions, questions and support, visit
[GitHub Discussions](https://github.com/paulmillr/scure-btc-signer/discussions)
section of the repository.

_Check out all web3 utility libraries:_ [ETH](https://github.com/paulmillr/micro-eth-signer), [BTC](https://github.com/paulmillr/scure-btc-signer), [SOL](https://github.com/paulmillr/micro-sol-signer), [ordinals](https://github.com/paulmillr/micro-ordinals)

### 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/btc-signer`

> `deno add jsr:@scure/btc-signer`

We support all major platforms and runtimes.
For [Deno](https://deno.land), ensure to use [npm specifier](https://deno.land/manual@v1.28.0/node/npm_specifiers).
For React Native, you may need a [polyfill for crypto.getRandomValues](https://github.com/LinusU/react-native-get-random-values).

```ts
import * as btc from '@scure/btc-signer';
```

### Quickstart

Create a Taproot address, build a transaction spending one of its UTXOs, sign and finalize it:

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';

const privKey = hex.decode('a1547d0a01c9acb2b8a4128f97bbcd74d9a5750a9a3d1571ee3d9840b41d1fbb');
const pubKey = btc.utils.pubSchnorr(privKey);

// Taproot payment for a single key. Also check out p2wpkh, p2sh, p2wsh & others below
const spend = btc.p2tr(pubKey);
console.log(spend.address);
// bc1pkw4e67whvet7q6xa854tstt7kjn9f7n3gqvyjqznezqwux0gnzhsrtlvy3

const tx = new btc.Transaction();
tx.addInput({
  ...spend, // adds tapInternalKey & other fields required for signing
  txid: '75ddabb27b8845f5247975c8a5ba7c6f336c4570708ebe230caf6db5217ae858',
  index: 0,
  witnessUtxo: { script: spend.script, amount: 100_000n }, // amounts are always bigint sats
});
tx.addOutputAddress(spend.address!, 90_000n); // leftover 10k sats become the fee
tx.sign(privKey);
tx.finalize();

console.log(tx.id);
// 927bc3441c7b376a83913b534bf10430139d9f64d83cbc38eb3a4e24cce54dc5
console.log(tx.hex); // ready to broadcast, e.g. via net.ts EsploraProvider
```

The rest of the docs cover every payment type, PSBT workflows, UTXO selection and more:

- [Payments](#payments)
  - [P2PK Pay To Public Key](#p2pk-pay-to-public-key)
  - [P2PKH Public Key Hash](#p2pkh-public-key-hash)
  - [P2WPKH Witness Public Key Hash](#p2wpkh-witness-public-key-hash)
  - [P2SH Script Hash](#p2sh-script-hash)
  - [P2WSH Witness Script Hash](#p2wsh-witness-script-hash)
  - [P2SH-P2WSH](#p2sh-p2wsh)
  - [P2MS classic multisig](#p2ms-classic-multisig)
  - [P2TR Taproot](#p2tr-taproot)
  - [P2TR-NS Taproot multisig](#p2tr-ns-taproot-multisig)
  - [P2TR-MS Taproot M-of-N multisig](#p2tr-ms-taproot-m-of-n-multisig)
  - [P2TR-PK Taproot single P2PK script](#p2tr-pk-taproot-single-p2pk-script)
  - [P2A Pay To Anchor](#p2a-pay-to-anchor)
- [Transaction](#transaction)
  - [Encode/decode](#encodedecode)
  - [Inputs](#inputs)
  - [Outputs](#outputs)
  - [Basic transaction sign](#basic-transaction-sign)
  - [BIP174 PSBT multi-sig example](#bip174-psbt-multi-sig-example)
- [UTXO selection](#utxo-selection)
- [Network](#network)
- [MuSig2](#musig2)
- [P2P, ElligatorSwift, BIP324](#p2p-elligatorswift-bip324)
- [Ordinals and custom scripts](#ordinals-and-custom-scripts)
- [Utils](#utils)
  - [getAddress](#getaddress)
    - [WIF](#wif)
  - [Script](#script)
  - [OutScript](#outscript)
- [Bitcoin is flawed](#bitcoin-is-flawed)
- [Security](#security)
- [License](#license)

## Payments

BTC has several UTXO types:

- P2PK: Legacy, from 2010
- P2PKH, P2SH, P2MS: Classic
- P2WPKH, P2WSH: SegWit (signature is removed from tx hash calculation)
- P2TR: Taproot (schnorr signatures instead of ECDSA)

For test examples, the usage is as following:

```sh
npm install @scure/btc-signer @scure/base assert
```

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual, throws } from 'assert';
```

### P2PK (Pay To Public Key)

Legacy script, doesn't have an address. Must be wrapped in P2SH / P2WSH / P2SH-P2WSH. Not recommended.

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const uncompressed = hex.decode(
  '04ad90e5b6bc86b3ec7fac2c5fbda7423fc8ef0d58df594c773fa05e2c281b2bfe877677c668bd13603944e34f4818ee03cadd81a88542b8b4d5431264180e2c28'
);

deepStrictEqual(btc.p2pk(uncompressed), {
  type: 'pk',
  script: hex.decode(
    '4104ad90e5b6bc86b3ec7fac2c5fbda7423fc8ef0d58df594c773fa05e2c281b2bfe877677c668bd13603944e34f4818ee03cadd81a88542b8b4d5431264180e2c28ac'
  ),
});
```

### P2PKH (Public Key Hash)

Classic (pre-SegWit) address.

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

### P2WPKH (Witness Public Key Hash)

SegWit V0 version of [P2PKH](#p2pkh-public-key-hash).
In SegWit, signature is removed from tx hash calculation.

Uses bech32 address.
Can't be wrapped in [P2WSH](#p2wsh-witness-script-hash).

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const PubKey = hex.decode('030000000000000000000000000000000000000000000000000000000000000001');
deepStrictEqual(btc.p2wpkh(PubKey), {
  type: 'wpkh',
  address: 'bc1qz69ej270c3q9qvgt822t6pm3zdksk2x35j2jlm',
  script: hex.decode('0014168b992bcfc44050310b3a94bd0771136d0b28d1'),
  hash: hex.decode('168b992bcfc44050310b3a94bd0771136d0b28d1'),
});
// P2SH-P2WPKH
deepStrictEqual(btc.p2sh(btc.p2wpkh(PubKey)), {
  type: 'sh',
  address: '3BCuRViGCTXmQjyJ9zjeRUYrdZTUa38zjC',
  script: hex.decode('a91468602f2db7b7d7cdcd2639ab6bf7f5bfe828e53f87'),
  redeemScript: hex.decode('0014168b992bcfc44050310b3a94bd0771136d0b28d1'),
  hash: hex.decode('68602f2db7b7d7cdcd2639ab6bf7f5bfe828e53f'),
});
```

### P2SH (Script Hash)

Classic (pre-SegWit) script address. Useful for multisig and other advanced use-cases. Consumes full output of other payments — NOT only script.

Required tx input fields to make it spendable: `redeemScript`

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const PubKey = hex.decode('030000000000000000000000000000000000000000000000000000000000000001');
// Wrap P2PKH in P2SH
deepStrictEqual(btc.p2sh(btc.p2pkh(PubKey)), {
  type: 'sh',
  address: '3EPhLJ1FuR2noj6qrTs4YvepCvB6sbShoV',
  script: hex.decode('a9148b530b962725af3bb7c818f197c619db3f71495087'),
  redeemScript: hex.decode('76a914168b992bcfc44050310b3a94bd0771136d0b28d188ac'),
  hash: hex.decode('8b530b962725af3bb7c818f197c619db3f714950'),
});
```

### P2WSH (Witness Script Hash)

SegWit V0 version of [P2SH](#p2sh-script-hash).
In SegWit, signature is removed from tx hash calculation.

Required tx input fields to make it spendable: `witnessScript`

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const PubKey = hex.decode('030000000000000000000000000000000000000000000000000000000000000001');
deepStrictEqual(btc.p2wsh(btc.p2pkh(PubKey)), {
  type: 'wsh',
  address: 'bc1qhxtthndg70cthfasy8y4qlk9h7r3006azn9md0fad5dg9hh76nkqaufnuz',
  script: hex.decode('0020b996bbcda8f3f0bba7b021c9507ec5bf8717bf5d14cbb6bd3d6d1a82defed4ec'),
  witnessScript: hex.decode('76a914168b992bcfc44050310b3a94bd0771136d0b28d188ac'),
  hash: hex.decode('b996bbcda8f3f0bba7b021c9507ec5bf8717bf5d14cbb6bd3d6d1a82defed4ec'),
});
```

### P2SH-P2WSH

Not really script type, but construction of P2WSH inside P2SH.

Required tx input fields to make it spendable: `redeemScript`, `witnessScript`

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const PubKey = hex.decode('030000000000000000000000000000000000000000000000000000000000000001');
deepStrictEqual(btc.p2sh(btc.p2wsh(btc.p2pkh(PubKey))), {
  type: 'sh',
  address: '3EHxWHyLv5Seu5Cd6D1cH56jLKxSi3ps8C',
  script: hex.decode('a9148a3d36fb710a9c7cae06cfcdf39792ff5773e8f187'),
  redeemScript: hex.decode('0020b996bbcda8f3f0bba7b021c9507ec5bf8717bf5d14cbb6bd3d6d1a82defed4ec'),
  witnessScript: hex.decode('76a914168b992bcfc44050310b3a94bd0771136d0b28d188ac'),
  hash: hex.decode('8a3d36fb710a9c7cae06cfcdf39792ff5773e8f1'),
});
```

### P2MS (classic multisig)

Classic / segwit (pre-taproot) M-of-N Multisig. Doesn't have an address, must be wrapped in P2SH / P2WSH / P2SH-P2WSH.

Duplicate public keys are not accepted to reduce mistakes. Use flag `allowSamePubkeys` to override the behavior, for cases like `2-of-[A,A,B,C]`, which can be signed by `A or (B and C)`.

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

### P2TR (Taproot)

TapRoot (SegWit V1) script which replaces both public key and script types from previous versions.

Consumes `p2tr(PubKey?, ScriptTree?)` and works as `PubKey` OR `ScriptTree`, which means
if you use any spendable PubKey and ScriptTree of multi-sig, owner of private key for PubKey will
be able to spend output. If PubKey is undefined we use static unspendable PubKey by default, which leaks information about script type. However, any dynamic unspendable keys will require complex interaction
to sign multi-sig wallets, and there is no BIP/PSBT fields for that yet.

Required tx input fields to make it spendable: `tapInternalKey`, `tapMerkleRoot`, `tapLeafScript`

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const PubKey = hex.decode('0101010101010101010101010101010101010101010101010101010101010101');
// Key Path Spend (owned of private key for PubKey can spend)
deepStrictEqual(btc.p2tr(PubKey), {
  type: 'tr',
  address: 'bc1p7yu5dsly83jg5tkxcljsa30vnpdpl22wr6rty98t6x6p6ekz2gkqzf2t2s',
  script: hex.decode('5120f13946c3e43c648a2ec6c7e50ec5ec985a1fa94e1e86b214ebd1b41d66c2522c'),
  tweakedPubkey: hex.decode('f13946c3e43c648a2ec6c7e50ec5ec985a1fa94e1e86b214ebd1b41d66c2522c'),
  tapInternalKey: hex.decode('0101010101010101010101010101010101010101010101010101010101010101'),
});

const clean = (x) => ({ type: x.type, address: x.address, script: hex.encode(x.script) });

### P2TR-NS (Taproot multisig)

Taproot N-of-N multisig (`[<PubKeys[0:n-1]> CHECKSIGVERIFY] <PubKeys[n-1]> CHECKSIG`).

First arg is M, if M!=PubKeys.length, it will create a multi-leaf M-of-N taproot script tree.
This allows one to reveal only `M` PubKeys on spend, without any information about the others.
This is fast for cases like 15-of-20, but extremely slow for cases like 5-of-20.

Duplicate public keys are not accepted to reduce mistakes. Use flag `allowSamePubkeys` to override the behavior, for cases like `2-of-[A,A,B,C]`, which can be signed by `A or (B and C)`.

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

// Simple 3-of-3 multisig
// Creates a single script that requires all three pubkeys: [PubKey, PubKey2, PubKey3]
deepStrictEqual(btc.p2tr_ns(3, [PubKey, PubKey2, PubKey3]), [
  {
    type: 'tr_ns',
    script: hex.decode(
      '200101010101010101010101010101010101010101010101010101010101010101ad200202020202020202020202020202020202020202020202020202020202020202ad201212121212121212121212121212121212121212121212121212121212121212ac'
    ),
  },
]);
// Simple 2-of-3 multisig
// If M (pubkeys required) is less than N (# of pubkeys), then multiple scripts are created: [[PubKey, PubKey2], [PubKey, PubKey3], [PubKey2, PubKey3]]
const clean = (x) => ({ type: x.type, address: x.address, script: hex.encode(x.script) });
deepStrictEqual(clean(btc.p2tr(undefined, btc.p2tr_ns(2, [PubKey, PubKey2, PubKey3]))), {
  type: 'tr',
  address: 'bc1pevfcmnkqqq09a4n0fs8c7mwlc6r4efqpvgyqpjvegllavgw235fq3kz7a0',
  script: '5120cb138dcec0001e5ed66f4c0f8f6ddfc6875ca401620800c99947ffd621ca8d12',
});
```

### P2TR-MS (Taproot M-of-N multisig)

M-of-N single leaf TapRoot multisig (`<PubKeys[0]> CHECKSIG [<PubKeys[1:n]> CHECKSIGADD] <M> NUMEQUAL`)

Duplicate public keys are not accepted to reduce mistakes. Use flag `allowSamePubkeys` to override the behavior, for cases like `2-of-[A,A,B,C]`, which can be signed by `A or (B and C)`.

**Experimental**, use at your own risk.

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

### P2TR-PK (Taproot single P2PK script)

Specific case of `p2tr_ns(1, [pubkey])`, which is the same as the BTC descriptor: `tr($H,pk(PUBKEY))`

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const PubKey = hex.decode('0101010101010101010101010101010101010101010101010101010101010101');
// P2PK for taproot
const clean = (x) => ({ type: x.type, address: x.address, script: hex.encode(x.script) });
deepStrictEqual(clean(btc.p2tr(undefined, [btc.p2tr_pk(PubKey)])), {
  type: 'tr',
  address: 'bc1pfj6w68w3v2f4pkzesc9tsqfvy5znw5qgydwa832v3v83vjn76kdsmr4360',
  script: '51204cb4ed1dd1629350d859860ab8012c2505375008235dd3c54c8b0f164a7ed59b',
});
```

### P2A (Pay to Anchor)

Ephemeral anchors are supported. [Check out docs](https://bitcoinops.org/en/topics/ephemeral-anchors/).

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const p2aScript = hex.decode('51024e73');
const decoded = btc.OutScript.decode(p2aScript);
deepStrictEqual(decoded, { type: 'p2a', script: p2aScript });
deepStrictEqual(hex.encode(btc.OutScript.encode(decoded)), '51024e73');
```

## Transaction

### Encode/decode

We support both PSBTv0 and draft PSBTv2 (there is no PSBTv1). If PSBTv2 transaction is encoded into PSBTv1, all PSBTv2 fields will be stripped.

We strip 'unknown' keys inside PSBT, they needed for new version/features support,
however any unsupported feature/new version can significantly break assumptions about code.
If you have use-case where they are needed, create a github issue.

PSBTv2 features tx_modifiable and taproot+bip32 are not supported yet.

```text
// Decode
Transaction.fromRaw(raw: Bytes, opts: TxOpts = {}); // Raw tx
Transaction.fromPSBT(psbt: Bytes, opts: TxOpts = {}); // PSBT tx
// Encode
tx.unsignedTx; // Bytes of raw unsigned tx
tx.hex; // hex encoded signed raw tx
tx.toPSBT(ver = this.PSBTVersion); // PSBT
```

### Inputs

We have txid (BE) instead of hash (LE) in transactions. We can support both,
but txid is consistent across block explorers, while some explorers treat hash
as txid - so hash is not consistent.

Use `getInput` and `inputsLength` to read information about inputs: they return a copy.
This is necessary to avoid accidental modification of internal structures without calling methods (addInput/updateInput) that will verify correctness.

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual, throws } from 'node:assert';

// tx.addInput(input: TransactionInput): number;
// tx.updateInput(idx: number, input: TransactionInput);

// Input
tx.addInput({ txid: new Uint8Array(32), index: 0 });
deepStrictEqual(tx.inputs[0], {
  txid: new Uint8Array(32),
  index: 0,
  sequence: btc.DEFAULT_SEQUENCE,
});
// Update basic value
tx.updateInput(0, { index: 10 });
deepStrictEqual(tx.inputs[0], {
  txid: new Uint8Array(32),
  index: 10,
  sequence: btc.DEFAULT_SEQUENCE,
});
// Add value as hex
tx.addInput({
  txid: '0000000000000000000000000000000000000000000000000000000000000000',
  index: 0,
});
deepStrictEqual(tx.inputs[1], {
  txid: new Uint8Array(32),
  index: 0,
  sequence: btc.DEFAULT_SEQUENCE,
});
// Update key map
const pubKey = hex.decode('030000000000000000000000000000000000000000000000000000000000000001');
const bip1 = [pubKey, { fingerprint: 5, path: [1, 2, 3] }];
const pubKey2 = hex.decode('030000000000000000000000000000000000000000000000000000000000000002');
const bip2 = [pubKey2, { fingerprint: 6, path: [4, 5, 6] }];
const pubKey3 = hex.decode('030000000000000000000000000000000000000000000000000000000000000003');
const bip3 = [pubKey3, { fingerprint: 7, path: [7, 8, 9] }];
// Add K-V
tx.updateInput(0, { bip32Derivation: [bip1] });
deepStrictEqual(tx.inputs[0].bip32Derivation, [bip1]);
// Add another K-V
tx.updateInput(0, { bip32Derivation: [bip2] });
deepStrictEqual(tx.inputs[0].bip32Derivation, [bip1, bip2]);
// Delete K-V
tx.updateInput(0, { bip32Derivation: [[pubKey, undefined]] });
deepStrictEqual(tx.inputs[0].bip32Derivation, [bip2]);
// Second add of same k-v does nothing
tx.updateInput(0, { bip32Derivation: [bip2] });
deepStrictEqual(tx.inputs[0].bip32Derivation, [bip2]);
// Second add of k-v with different value breaks
throws(() => tx.updateInput(0, { bip32Derivation: [[pubKey2, bip1[1]]] }));
tx.updateInput(0, { bip32Derivation: [bip1, bip2, bip3] });
// Preserves order (re-ordered on PSBT encoding)
deepStrictEqual(tx.inputs[0].bip32Derivation, [bip2, bip1, bip3]);
// PSBT encoding re-order k-v
const tx2 = btc.Transaction.fromPSBT(tx.toPSBT());
deepStrictEqual(tx2.inputs[0].bip32Derivation, [bip1, bip2, bip3]);
// Remove field
tx.updateInput(0, { bip32Derivation: undefined });
deepStrictEqual(tx.inputs[0], {
  txid: new Uint8Array(32),
  index: 10,
  sequence: btc.DEFAULT_SEQUENCE,
});

// Read inputs
for (let i = 0; i < tx.inputsLength; i++) {
  console.log('I', tx.getInput(i));
}
```

### Outputs

`addOutputAddress` uses bigint amounts, which means satoshis, not BTC. If you need BTC representation, use `Decimal`:

```ts
import * as btc from '@scure/btc-signer';

const amountSatoshi = btc.Decimal.decode('1.5'); // 1.5 btc in satoshi
```

Use `getOutput` and `outputsLength` to read outputs information. This methods returns copy of output, instead of internal representation.
This is necessary to avoid accidental modification of internal structures without calling methods (addOutput/updateOutput) that will verify correctness.

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual, throws } from 'node:assert';

const tx = new btc.Transaction();
type Bytes = Uint8Array | string;
type DerivationPath = { fingerprint: number; path: number[] };
type TransactionOutput = {
  script?: Bytes;
  amount?: bigint;
  redeemScript?: Bytes;
  witnessScript?: Bytes;
  bip32Derivation?: [Bytes, DerivationPath | undefined][]; // [PubKey, DeriviationPath]
  tapInternalKey?: Bytes;
};

// tx.addOutput(o: TransactionOutput): number;
// tx.updateOutput(idx: number, output: TransactionOutput);
// tx.addOutputAddress(address: string, amount: bigint, network = NETWORK): number;

// Read outputs
for (let i = 0; i < tx.outputsLength; i++) {
  console.log('O', tx.getOutput(i));
}
```

### Basic transaction sign

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { pubECDSA } from '@scure/btc-signer/utils.js';
import { deepStrictEqual } from 'node:assert';

### BIP174 PSBT multi-sig example

> `npm install @scure/base @scure/bip32`

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import * as bip32 from '@scure/bip32';
import { deepStrictEqual } from 'node:assert';

### UTXO selection

UTXO selection is the process of choosing which UTXOs to use as inputs
when making an on-chain bitcoin payment. The library:

- can create tx, integrated with the signer
- ensures change address is always specified
- supports bip69
- supports segwit + taproot
- calculates weight with good precision
- implements multiple strategies

Taproot estimation is precise, but you have to pass sighash if you want to use non-default one,
because it changes signature size. For complex taproot trees you need to filter tapLeafScript
to include only leafs which you can sign we estimate size with smallest leaf (same as finalization),
but in specific case keys for this leaf can be unavailable (complex multisig)

`Oldest` / `Newest` expects UTXO provided in historical order (oldest first),
otherwise we have no way to detect age of tx.

#### Strategies

Strategy selection is complicated. Best should be: `exactBiggest/accumSmallest`.

`exactBiggest/accumBiggest` creates tx with smallest fees,
but it breaks big outputs to small ones, which in the end will create
a lot of outputs close to dust.

- `default`: good for privacy, same as `exactBiggest/accumBiggest`
- `all`: send all coins to change address (consolidation)
- `accum`: accumulates inputs until the target value (+fees) is reached, skipping detrimental inputs
- `exact`: accumulates inputs until the target value (+fees) is matched, does not accumulate inputs
  that go over the target value (within a threshold)
- `accumNewest`
- `accumOldest`
- `accumSmallest`
- `accumBiggest`
- `exactNewest/accumNewest`
- `exactNewest/accumOldest`
- `exactNewest/accumSmallest`
- `exactNewest/accumBiggest`
- `exactOldest/accumNewest`
- `exactOldest/accumOldest`
- `exactOldest/accumSmallest`
- `exactOldest/accumBiggest`
- `exactSmallest/accumNewest`
- `exactSmallest/accumOldest`
- `exactSmallest/accumSmallest`
- `exactSmallest/accumBiggest`
- `exactBiggest/accumNewest`
- `exactBiggest/accumOldest`
- `exactBiggest/accumSmallest`
- `exactBiggest/accumBiggest`

#### Example

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { pubECDSA } from '@scure/btc-signer/utils.js';
import { deepStrictEqual } from 'node:assert';

## Network

Bitcoin nodes can't be used as source-of-truth to construct transactions & get UTXOs.
An extra indexer is required. Our `net.js` submodule allows to easily fetch UTXOs,
balances, and other data for an address.
See [README-fullnode.md](./README-fullnode.md) for details and
guide on running a full node with an indexer.

```ts
import * as btc from '@scure/btc-signer';
import { EsploraProvider } from '@scure/btc-signer/net.js';
import { pubECDSA } from '@scure/btc-signer/utils.js';
const net = new EsploraProvider(fetch, 'http://127.0.0.1:3000');
// Methods: `height`, `blockInfo`, `fee`, `balance`, `txCount`, `sendTx`, `waitForTx`, `txInfo`,
// `unspent`, `transfers`, `history`, `historyMulti`.
// Transient backend failures (429/5xx, dropped connections) are retried with backoff on GETs.
// Long scans accept `signal` (AbortSignal) and `onProgress`; raw-tx fan-out is
// bounded by `concurrency` (default 8).

// Get latest block.
async function latestBlock() {
  const height = await net.height();
  const block = await net.blockInfo(height);
  return { number: block.number, hash: block.hash, timestamp: new Date(block.timestamp) };
}

// Get per-address transaction history.
async function addressTransactions(address: string) {
  const txs = await net.transfers(address, { limit: 10 });
  return txs.map((tx) => ({ txid: tx.txid, block: tx.block, fee: tx.info.fee }));
}

// Stream history instead of buffering it: rows arrive newest-first while pages
// are fetched, and stopping early also stops fetching.
async function streamHistory(address: string) {
  for await (const tx of net.history(address, { onProgress: (p) => console.log(p.percent) })) {
    if (tx.block !== undefined && tx.block < 800_000) break;
    console.log(tx.txid, tx.transfers);
  }
}

// Merged history for a set of addresses (HD wallets): one txid-deduplicated
// stream; each row lists the watched addresses participating in it.
async function walletHistory(addresses: string[]) {
  for await (const tx of net.historyMulti(addresses)) console.log(tx.txid, tx.addresses);
}

// Broadcast, then wait for confirmation.
async function sendAndWait(rawTx: string) {
  const txid = await net.sendTx(rawTx);
  return await net.waitForTx(txid, { confirmations: 2, timeoutMs: 3_600_000 });
}

// Get UTXOs, select inputs, and sign. Call with a key that controls funded UTXOs.
async function signSpend(privKey: Uint8Array, to: string, amount: bigint) {
  const spend = btc.p2wpkh(pubECDSA(privKey));
  const unspent = await net.unspent(spend.address!);
  const feePerByte = await net.fee(2);
  const selected = btc.selectUTXO(unspent.utxo, [{ address: to, amount }], 'default', {
    feePerByte,
    changeAddress: spend.address!,
  });
  if (!selected) throw new Error(`not enough funds for ${spend.address}`);
  const { tx } = selected;
  tx.sign(privKey);
  tx.finalize();
  return { txid: tx.id, raw: tx.hex };
}

// For wrapped or script spends, add caller-owned metadata before selection:
// const wrapped = btc.p2sh(btc.p2wpkh(pubECDSA(privKey)));
// const base = await net.unspent(wrapped.address!);
// const utxo = base.utxo.map((u) => ({ ...u, redeemScript: wrapped.redeemScript }));
// const selected = btc.selectUTXO(utxo, outputs, 'default', opts);
```

First argument is `fetch` API-compatible transport.
We suggest using `micro-ftch` package - a wrapper, which supports kill-switch,
logging, timeouts, concurrency limits, replay fixtures, and other useful network controls:

```ts
import { ftch } from 'micro-ftch';
let NETWORK_ENABLED = true;
const fetcher = ftch(fetch, {
  isValidRequest: () => NETWORK_ENABLED,
  timeout: 10_000,
  concurrencyLimit: 4,
});
const net = new EsploraProvider(fetcher, 'http://127.0.0.1:3000')
```

## MuSig2

MuSig2 implementation conforming to [BIP-327](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki)
is available in `@scure/btc-signer/musig2.js`. Check out [bip327-musig2.test.ts](./test/bip327-musig2.test.ts) as well:

> `npm install @noble/curves`

```ts
import * as btc from '@scure/btc-signer';
import * as musig2 from '@scure/btc-signer/musig2.js';
import { schnorr } from '@noble/curves/secp256k1.js';
import { deepStrictEqual } from 'node:assert';
// MuSig2 Multi-signature for Alice, Bob, and Carol
// 1. Key Generation (for each signer: Alice, Bob, Carol)
// - Alice's key generation
const aliceSecretKey = btc.utils.randomPrivateKeyBytes(); // Alice generates a random 32-byte secret key
const alicePublicKey = musig2.IndividualPubkey(aliceSecretKey); // Alice derives her individual public key from her secret key
// - Bob's key generation
const bobSecretKey = btc.utils.randomPrivateKeyBytes(); // Bob generates a random 32-byte secret key
const bobPublicKey = musig2.IndividualPubkey(bobSecretKey); // Bob derives his individual public key from his secret key
// - Carol's key generation
const carolSecretKey = btc.utils.randomPrivateKeyBytes(); // Carol generates a random 32-byte secret key
const carolPublicKey = musig2.IndividualPubkey(carolSecretKey); // Carol derives her individual public key from her secret key

// 2. Key Aggregation (All signers participate by sharing public keys)
const individualPublicKeys = [alicePublicKey, bobPublicKey, carolPublicKey]; // Collect all individual public keys
const sortedPublicKeys = musig2.sortKeys(individualPublicKeys); // Sort public keys lexicographically (as required by MuSig2)
const aggregatePublicKey = musig2.keyAggExport(musig2.keyAggregate(sortedPublicKeys)); // Extract the X-only aggregate public key (32 bytes)
// At this point, all signers have the 'aggregatePublicKey' and 'keyAggContext'.
// 3. Nonce Generation - Round 1 (Each signer generates and broadcasts public nonce)
const msg = new Uint8Array(32).fill(5); // Example message to be signed (32-byte message is recommended for BIP340)
// Alice generates her nonce
const aliceNonces = musig2.nonceGen(alicePublicKey, aliceSecretKey, aggregatePublicKey, msg);
// Secret nonce: must be kept secret and used only once per signing session!
// Public nonce: to be shared with Bob and Carol
// Bob generates his nonce
const bobNonces = musig2.nonceGen(bobPublicKey, bobSecretKey, aggregatePublicKey, msg);
// Carol generates her nonce
const carolNonces = musig2.nonceGen(carolPublicKey, carolSecretKey, aggregatePublicKey, msg);
// Each signer creates own instance
const session = new musig2.Session(
  // 4. Nonce Aggregation (All signers participate by sharing public nonces)
  musig2.nonceAggregate([aliceNonces.public, bobNonces.public, carolNonces.public]),
  sortedPublicKeys,
  msg
);
// At this point, all signers have the 'aggregateNonce'.
// 5. Partial Signature Generation - Round 2 (Each signer generates partial signature)
// Alice generates her partial signature
const alicePartialSignature = session.sign(aliceNonces.secret, aliceSecretKey);
// Bob generates his partial signature
const bobPartialSignature = session.sign(bobNonces.secret, bobSecretKey);
// Carol generates her partial signature
const carolPartialSignature = session.sign(carolNonces.secret, carolSecretKey);
// 6. Partial Signature Aggregation (Anyone can aggregate partial signatures)
const partialSignatures = [alicePartialSignature, bobPartialSignature, carolPartialSignature]; // Collect all partial signatures
const finalSignature = session.partialSigAgg(partialSignatures); // Aggregate partial signatures to create the final signature

// 7. Signature Verification (Anyone can verify the final signature)
deepStrictEqual(schnorr.verify(finalSignature, msg, aggregatePublicKey), true);
```

## Ordinals and custom scripts

We support custom scripts. You can pass it as last argument to `p2tr`.

We've developed separate [micro-ordinals](https://github.com/paulmillr/micro-ordinals) package, which contains:

- Real code for ordinals / inscriptions / runes
- CLI tool that allows to upload files as inscriptions
- Example usage of custom scripts

## P2P, ElligatorSwift, BIP324

Experimental implementation of ElligatorSwift from [BIP324](https://github.com/bitcoin/bips/blob/master/bip-0324.mediawiki)
is available.

ElligatorSwift is Schnorr-like x-only ECDH with public keys indistinguishable from uniformly random bytes.

Check out [libsecp](https://github.com/bitcoin/bitcoin/blob/master/src/secp256k1/doc/ellswift.md) docs.

```ts
import { elligatorSwift } from '@scure/btc-signer/p2p.js';

const alice = elligatorSwift.keygen();
const bob = elligatorSwift.keygen();
// ECDH
const sharedAlice = elligatorSwift.getSharedSecret(alice.privateKey, bob.publicKey);
const sharedBob = elligatorSwift.getSharedSecret(bob.privateKey, alice.publicKey);
// deepStrictEqual(sharedAlice, sharedBob);
// ECDH BIP324
const sharedAlice2 = elligatorSwift.getSharedSecretBip324(
  alice.privateKey,
  bob.publicKey,
  alice.publicKey,
  true
);
const sharedBob2 = elligatorSwift.getSharedSecretBip324(
  bob.privateKey,
  alice.publicKey,
  bob.publicKey,
  false
);
// deepStrictEqual(sharedAlice2, sharedBob2);
// pubKey decoding
for (const k of [alice, bob]) {
  // deepStrictEqual(
  //   toHex(elligatorSwift.decode(k.publicKey)),
  //   toHex(secp256k1.getPublicKey(k.privateKey, true).subarray(1))
  // );
}
```

## Utils

> `npm install @scure/base`

### secp256k1 keys

```ts
import { pubSchnorr, signSchnorr } from '@scure/btc-signer/utils.js';
import { pubECDSA, signECDSA } from '@scure/btc-signer/utils.js';
import { randomPrivateKeyBytes } from '@scure/btc-signer/utils.js';

const priv = randomPrivateKeyBytes();
const pub = pubSchnorr(priv);
```

### getAddress

Returns common addresses from privateKey

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const privKey = hex.decode('0101010101010101010101010101010101010101010101010101010101010101');
deepStrictEqual(btc.getAddress('pkh', privKey), '1C6Rc3w25VHud3dLDamutaqfKWqhrLRTaD'); // P2PKH (legacy address)
deepStrictEqual(btc.getAddress('wpkh', privKey), 'bc1q0xcqpzrky6eff2g52qdye53xkk9jxkvrh6yhyw'); // SegWit V0 address
deepStrictEqual(
  btc.getAddress('tr', privKey),
  'bc1p33wm0auhr9kkahzd6l0kqj85af4cswn276hsxg6zpz85xe2r0y8syx4e5t'
); // TapRoot KeyPathSpend
```

#### WIF

Encoding/decoding of WIF privateKeys. Only compressed keys are supported for now.

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

const privKey = hex.decode('0101010101010101010101010101010101010101010101010101010101010101');
deepStrictEqual(btc.WIF().encode(privKey), 'KwFfNUhSDaASSAwtG7ssQM1uVX8RgX5GHWnnLfhfiQDigjioWXHH');
deepStrictEqual(
  hex.encode(btc.WIF().decode('KwFfNUhSDaASSAwtG7ssQM1uVX8RgX5GHWnnLfhfiQDigjioWXHH')),
  '0101010101010101010101010101010101010101010101010101010101010101'
);
```

### Script

Encoding/decoding bitcoin scripts

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

deepStrictEqual(
  btc.Script.decode(
    hex.decode(
      '5221030000000000000000000000000000000000000000000000000000000000000001210300000000000000000000000000000000000000000000000000000000000000022103000000000000000000000000000000000000000000000000000000000000000353ae'
    )
  ).map((i) => (btc.utils.isBytes(i) ? hex.encode(i) : i)),
  [
    2,
    '030000000000000000000000000000000000000000000000000000000000000001',
    '030000000000000000000000000000000000000000000000000000000000000002',
    '030000000000000000000000000000000000000000000000000000000000000003',
    3,
    'CHECKMULTISIG',
  ]
);
deepStrictEqual(
  hex.encode(
    btc.Script.encode([
      2,
      hex.decode('030000000000000000000000000000000000000000000000000000000000000001'),
      hex.decode('030000000000000000000000000000000000000000000000000000000000000002'),
      hex.decode('030000000000000000000000000000000000000000000000000000000000000003'),
      3,
      'CHECKMULTISIG',
    ])
  ),
  '5221030000000000000000000000000000000000000000000000000000000000000001210300000000000000000000000000000000000000000000000000000000000000022103000000000000000000000000000000000000000000000000000000000000000353ae'
);
```

### OutScript

Encoding / decoding of output scripts

```ts
import * as btc from '@scure/btc-signer';
import { hex } from '@scure/base';
import { deepStrictEqual } from 'node:assert';

deepStrictEqual(
  btc.OutScript.decode(
    hex.decode(
      '5221030000000000000000000000000000000000000000000000000000000000000001210300000000000000000000000000000000000000000000000000000000000000022103000000000000000000000000000000000000000000000000000000000000000353ae'
    )
  ),
  {
    type: 'ms',
    m: 2,
    pubkeys: [
      '030000000000000000000000000000000000000000000000000000000000000001',
      '030000000000000000000000000000000000000000000000000000000000000002',
      '030000000000000000000000000000000000000000000000000000000000000003',
    ].map(hex.decode),
  }
);
deepStrictEqual(
  hex.encode(
    btc.OutScript.encode({
      type: 'ms',
      m: 2,
      pubkeys: [
        '030000000000000000000000000000000000000000000000000000000000000001',
        '030000000000000000000000000000000000000000000000000000000000000002',
        '030000000000000000000000000000000000000000000000000000000000000003',
      ].map(hex.decode),
    })
  ),
  '5221030000000000000000000000000000000000000000000000000000000000000001210300000000000000000000000000000000000000000000000000000000000000022103000000000000000000000000000000000000000000000000000000000000000353ae'
);
```

## Bitcoin is flawed

Bitcoin is more complex than ETH / SOL despite having less features:

- **Legacy:** too much decade-old code / standards
- **Overengineering:** features were designed to be extensible and future-proof; then abandoned when future arrived.
  - Transaction has `version` field, which is nice, allowing to change format later, however when there
    was first change (SegWit V0), instead of using different tx version, there was hack with zero-inputs prefix
    (tx cannot have zero inputs, so inputsCount=0 + '01' flag after that for tx version with witness data).
    Probably it was done so it won't interfere with different transaction versions of different coins.
    However, there is also `txVersion=2` (BIP68) which changes lockTime behaviour, but not tx format.
  - There is bech32/witness program addresses, which is very extensible. By default rules software should
    support future versions (0..16), so there will be no change in libraries to support new addresses.
    However, even after first update (version 0 to 1) format of addresses itself changed from bech32 to bech32m,
    so whole mechanic of different address versions is already unused. Also, supporting future version
    of addresses is cool, but they are currently unspendable and we cannot know rules for spending new version address,
    which means any new version address created now will be unspendable in future (SegWitV0->SegWitV1(taproot) even
    changes public key format). So we cannot use this whole mechanic of future addresses at all (or users can accidentally create unspendable address and lose coins).
  - PSBT supports unknown fields, according to spec we need to pass them as is, without modifications.
    It was probably done this way to be future-proof: new version of PSBT can be parsed with old parser, which will ignore new fields. However, when future came (PSBTv2), format significantly changed (no `global.unsignedTx`) anyway.
- **Bad BIP specs:** likely because there is only one relevant BTC Core implementation.
  - To implement something, specs are not enough: need to read source code of Core (which is very complex, especially functional tests which re-implement parts in python) and other bitcoin libraries (such as bitcoinjs-lib)
  - No one cares about specs much: for example, in [BIP174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki),
    despite being old 2017 spec, formatting issues still haven't been fixed: `m/0&#39;/0&#39;/0&#39;`
  - [BIP174](https://github.com/bitcoin/bips/blob/master/bip-0174.mediawiki) multisig example has unsorted partialSig field
    inside input (it's better to sort it)
  - Many PSBT tests are in format of `valid/invalid` (especially for PSBTv2), which isn't very helpful.
    Parser which produces garbage, but doesn't throw exception, is still broken.
- **Major flaws in PSBT:**
  - PSBT was designed to be opaque key-value store. Combiner only needed to merge dictories, without a need to understand
    fields. However, parsing requires to understand `unsignedTx`, since there is no input/output count in format itself.
  - Instead of `global, inputCount, inputs[], outputCount, outputs[]`, inputCount and outputCount are stored inside
    `global.unsignedTx` (v0) or `global.inputCount/global.outputCount` (v2), which means in order to parse
    basic structure we need to completely parse global KV and understand its fields.
  - **Security issue:** Unknown PSBT fields can be used to pass some code to backdoored wallets while being ignore by others.
  - In JS, it is even harder to implement properly, because JS doesn't support complex keys in objects / dicts.
    There is whole controlBlock of taproot in key inside tapLeafScript, which we need to parse, leading to structure like:
    `{key: {version, internalKey, merklePath}, value: {script, version}`.
    But, since there is no support for complex keys, we cannot do `correct by construction` using js objects,
    we need to do this dict as array and constantly check if keys are unique.

## Security

The library has been independently audited:

- at version 2.2.0, in Apr 2026, by ourselves (self-audited)
  - Scope: everything
  - [Changes since audit](https://github.com/paulmillr/scure-btc-signer/compare/2.2.0..main)
- at version 0.3.0, in Feb 2023, by [cure53](https://cure53.de)
  - PDFs: [online](https://cure53.de/audit-report_micro-btc-signer.pdf), [offline](./audit/2023-02-21-cure53-audit-report.pdf)
  - [Changes since audit](https://github.com/paulmillr/scure-btc-signer/compare/0.3.0..main).
  - The audit has been funded by [Ryan Shea](https://shea.io)

MuSig2 and UTXO selection has not been audited yet.
Commit [58d4554](58d455480919e968aabff132503560effb2f8eaf)
split the library from one into several files to ease future maintainability.

If you see anything unusual: investigate and report.

### Supply chain security

- **Commits** are signed with PGP keys, to prevent forgery. Make sure to verify commit signatures
- **Releases** are transparent and built on GitHub CI. Make sure to verify [provenance](https://docs.npmjs.com/generating-provenance-statements) logs
  - Use GitHub CLI to verify single-file builds:
    `gh attestation verify --owner paulmillr scure-btc-signer.js`
- **Rare releasing** is followed to ensure less re-audit need for end-users
- **Dependencies** are minimized and locked-down: any dependency could get hacked and users will be downloading malware with every install.
  - We make sure to use as few dependencies as possible
  - Automatic dep updates are prevented by locking-down version ranges; diffs are checked with `npm-diff`
- **Dev Dependencies** are disabled for end-users; they are only used to develop / build the source code

For this package, there are 4 dependencies; and a few dev dependencies:

- [noble-hashes](https://github.com/paulmillr/noble-hashes) provides cryptographic hashing functionality
- [noble-curves](https://github.com/paulmillr/noble-curves) provides secp256k1 elliptic curve
- [scure-base](https://github.com/paulmillr/scure-base) provides base58 and bech32
- [micro-packed](https://github.com/paulmillr/micro-packed) is responsible for binary encoding
- jsbt is used for benchmarking / testing / build tooling and developed by the same author
- prettier, fast-check and typescript are used for code quality / test generation / ts compilation. It's hard to audit their source code thoroughly and fully because of their size

## Learning & documentation

There are several nice resources on the topic:

- [Learn me a bitcoin](https://learnmeabitcoin.com)
- [Bitcoin wiki](https://bitcoinwiki.org)

## License

MIT (c) Paul Miller [(https://paulmillr.com)](https://paulmillr.com), see LICENSE file.

scure-btc-signer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README