scure-btc-signer

UTXO selection chooses which unspent outputs to use as inputs for a transaction. Use btc.selectUTXO to automate this process.

Key Options:

• changeAddress: The address where remaining funds should be sent (required).
• feePerByte: The fee rate in satoshis per vByte (required).
• bip69: Enables lexicographical indexing of inputs and outputs.
• createTx: If true, returns a Transaction object ready for signing.
• filterTaproot: An array of x-only public keys. Use this to prevent the selector from choosing Taproot UTXOs that the current wallet cannot spend.

Strategies: Selection behavior is determined by a strategy string. The recommended strategy for most cases is exactBiggest/accumSmallest (or default).

Common strategies include:

• default: Good for privacy.
• all: Consolidates all coins to the change address.
• accum: Accumulates inputs until the target value (+fees) is reached.
• exact: Accumulates inputs until the target value is matched without going over (within a threshold).

selectUTXO returns undefined if there are insufficient funds.

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

const selected = btc.selectUTXO(utxos, outputs, 'default', {
  changeAddress: 'bcrt1pea3850rzre54e53eh7suwmrwc66un6nmu9npd7eqrhd6g4lh8uqsxcxln8',
  feePerByte: 2n,
  bip69: true,
  createTx: true,
  network: regtest,
  filterTaproot: [myPublicKey],
});

if (selected) {
  const { tx } = selected;
  tx.sign(privKey);
  tx.finalize();
}

This method installs the Blockstream fork of electrs, which provides an HTTP API.

Installation Steps:

1. Install dependencies (build-essential, cmake, protobuf-compiler, etc.).
2. Create a system user electrs and group bitcoin.
3. Clone https://github.com/Blockstream/electrs.git.
4. Build using cargo build --locked --release --bin electrs.
5. Install the binary to /usr/local/bin/electrs-blockstream.

Key Configuration Flags:

• --http-addr: The address the HTTP API listens on (e.g., 127.0.0.1:3000).
• --cors '*': Enables CORS for browser-based tools.
• --utxos-limit 10000: Increases the per-address UTXO lookup ceiling.
• --electrum-txs-limit 10000: Increases the raw Electrum history ceiling.
• --jsonrpc-import: Enables JSON-RPC import.

# Build and install command snippet
cd /srv/electrs/blockstream
cargo build --locked --release --bin electrs
sudo install -m 0755 target/release/electrs /usr/local/bin/electrs-blockstream

# Execution example
/usr/local/bin/electrs-blockstream \
  --network bitcoin \
  --daemon-dir /var/lib/bitcoin \
  --blocks-dir /var/lib/bitcoin/blocks \
  --cookie /var/lib/bitcoin/.cookie \
  --daemon-rpc-addr 127.0.0.1:8332 \
  --db-dir /var/lib/electrs-blockstream \
  --electrum-rpc-addr 127.0.0.1:51001 \
  --http-addr 127.0.0.1:3000 \
  --cors '*' \
  --utxos-limit 10000 \
  --electrum-txs-limit 10000 \
  --monitoring-addr 127.0.0.1:4324 \
  --jsonrpc-import

MuSig2 implementation is available in @scure/btc-signer/musig2.js. The process involves several rounds:

1. Key Generation: Each signer generates a secret key and derives an individual public key using musig2.IndividualPubkey(secretKey).
2. Key Aggregation: Signers share public keys. Use musig2.sortKeys(publicKeys) to sort them, then musig2.keyAggregate(sortedKeys) to create the aggregate key. The final X-only aggregate public key is extracted via musig2.keyAggExport(...).
3. Nonce Generation (Round 1): Each signer generates nonces using musig2.nonceGen(individualPubKey, secretKey, aggregatePubKey, msg). This returns both a secret (to be kept private) and a public nonce.
4. Nonce Aggregation: Signers share public nonces. Create a musig2.Session by passing the aggregated public nonces via musig2.nonceAggregate(...), the sorted public keys, and the message.
5. Partial Signature (Round 2): Each signer generates a partial signature using session.sign(nonceSecret, secretKey).
6. Aggregation & Verification: Aggregate partial signatures using session.partialSigAgg(partialSignatures) and verify the final signature using standard Schnorr verification.

CRITICAL SECURITY WARNING: Every MuSig2 secret nonce must be used for exactly one partial signature. Reusing a nonce in distinct sessions can reveal the signer's secret key. Session.sign() only zeroes the specific Uint8Array passed to it; you must ensure clones or database records of the nonce are not reused.

import * as btc from '@scure/btc-signer';
import * as musig2 from '@scure/btc-signer/musig2.js';
import { schnorr } from '@noble/curves/secp256k1.js';

// 1. Key Generation
const aliceSecretKey = btc.utils.randomPrivateKeyBytes();
const alicePublicKey = musig2.IndividualPubkey(aliceSecretKey);
const bobSecretKey = btc.utils.randomPrivateKeyBytes();
const bobPublicKey = musig2.IndividualPubkey(bobSecretKey);

// 2. Key Aggregation
const individualPublicKeys = [alicePublicKey, bobPublicKey];
const sortedPublicKeys = musig2.sortKeys(individualPublicKeys);
const aggregatePublicKey = musig2.keyAggExport(musig2.keyAggregate(sortedPublicKeys));

// 3. Nonce Generation
const msg = new Uint8Array(32).fill(5);
const aliceNonces = musig2.nonceGen(alicePublicKey, aliceSecretKey, aggregatePublicKey, msg);
const bobNonces = musig2.nonceGen(bobPublicKey, bobSecretKey, aggregatePublicKey, msg);

// 4. Session & Nonce Aggregation
const session = new musig2.Session(
  musig2.nonceAggregate([aliceNonces.public, bobNonces.public]),
  sortedPublicKeys,
  msg
);

// 5. Partial Signature
const alicePartialSignature = session.sign(aliceNonces.secret, aliceSecretKey);
const bobPartialSignature = session.sign(bobNonces.secret, bobSecretKey);

// 6. Aggregation
const finalSignature = session.partialSigAgg([alicePartialSignature, bobPartialSignature]);

// 7. Verification
schnorr.verify(finalSignature, msg, aggregatePublicKey);