@scure/btc-signer 2.2.0 → 2.3.0

package/README.md

@@ -4,7 +4,7 @@ Audited & minimal library for creating, signing & decoding Bitcoin transactions.
 
 - 🔒 [**Audited**](#security) by an independent security firm
 - ✍️ Create transactions, inputs, outputs, sign them
-- 📡 No network code: simplified audits and offline usage
+- 📡 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
@@ -49,6 +49,40 @@ For React Native, you may need a [polyfill for crypto.getRandomValues](https://g
 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)
@@ -69,6 +103,7 @@ import * as btc from '@scure/btc-signer';
   - [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)
@@ -519,27 +554,27 @@ type DerivationPath = { fingerprint: number; path: number[] };
 type TapScriptSigKey = { pubKey: Bytes; leafHash: Bytes };
 type TapLeafScriptKey = { version: number; internalKey: Bytes; merklePath: Bytes[] };
 type TransactionInput = {
-  txid?: Bytes,
-  index?: number,
-  nonWitnessUtxo?: RawTransactionBytesOrHex,
-  witnessUtxo?: { script?: Bytes; amount: bigint },
+  txid?: Bytes;
+  index?: number;
+  nonWitnessUtxo?: RawTransactionBytesOrHex;
+  witnessUtxo?: { script?: Bytes; amount: bigint };
   partialSig?: [Bytes, Bytes][]; // [PubKey, Signature]
-  sighashType?: number,
-  redeemScript?: Bytes,
-  witnessScript?: Bytes,
+  sighashType?: number;
+  redeemScript?: Bytes;
+  witnessScript?: Bytes;
   bip32Derivation?: [Bytes, DerivationPath | undefined][]; // [PubKey, DeriviationPath]
-  finalScriptSig?: Bytes,
-  finalScriptWitness?: Bytes[],
-  porCommitment?: Bytes,
-  sequence?: number,
-  requiredTimeLocktime?: number,
-  requiredHeightLocktime?: number,
-  tapKeySig?: Bytes,
+  finalScriptSig?: Bytes;
+  finalScriptWitness?: Bytes[];
+  porCommitment?: Bytes;
+  sequence?: number;
+  requiredTimeLocktime?: number;
+  requiredHeightLocktime?: number;
+  tapKeySig?: Bytes;
   tapScriptSig?: [TapScriptSigKey, Bytes][]; // [PubKeySchnorr, LeafHash]
   // [ControlBlock, ScriptWithVersion]
   tapLeafScript?: [TapLeafScriptKey, Bytes][];
-  tapInternalKey?: Bytes,
-  tapMerkleRoot?: Bytes,
+  tapInternalKey?: Bytes;
+  tapMerkleRoot?: Bytes;
 };
 
 // tx.addInput(input: TransactionInput): number;
@@ -632,12 +667,12 @@ 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,
+  script?: Bytes;
+  amount?: bigint;
+  redeemScript?: Bytes;
+  witnessScript?: Bytes;
   bip32Derivation?: [Bytes, DerivationPath | undefined][]; // [PubKey, DeriviationPath]
-  tapInternalKey?: Bytes,
+  tapInternalKey?: Bytes;
 };
 
 // tx.addOutput(o: TransactionOutput): number;
@@ -1025,6 +1060,97 @@ deepStrictEqual(tx.id, 'b702078d65edd65a84b2a97a669df5631b06f42a67b0d7090e540b02
 deepStrictEqual(tx.fee, 394n);
 ```
 
+## 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)
@@ -1348,12 +1474,6 @@ For this package, there are 4 dependencies; and a few dev dependencies:
 - 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
 
-## Contributing & testing
-
-- `npm install && npm run build && npm test` will build the code and run tests.
-- `npm run lint` / `npm run format` will run linter / fix linter issues.
-- `npm run build:release` will build single file
-
 ## Learning & documentation
 
 There are several nice resources on the topic:

package/index.d.ts

@@ -29,4 +29,3 @@ export type { CustomScript, OptScript } from './payment.ts';
 export { _DebugPSBT, TaprootControlBlock } from './psbt.ts';
 export { bip32Path, Decimal, DEFAULT_SEQUENCE, PSBTCombine, SigHash } from './transaction.ts';
 export { _cmpBig, _Estimator } from './utxo.ts';
-//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -29,4 +29,3 @@ export { _DebugPSBT, TaprootControlBlock } from "./psbt.js";
 // remove
 export { bip32Path, Decimal, DEFAULT_SEQUENCE, PSBTCombine, SigHash } from "./transaction.js";
 export { _cmpBig, _Estimator } from "./utxo.js";
-//# sourceMappingURL=index.js.map

package/musig2.d.ts

@@ -1,3 +1,4 @@
+import type { WeierstrassPoint } from '@noble/curves/abstract/weierstrass.js';
 import { type TArg, type TRet } from './utils.ts';
 /** Represents a pair of public and secret nonces used in MuSig2 signing. */
 export type Nonces = {
@@ -16,6 +17,15 @@ export type DetNonce = {
     /** Partial signature produced after combining all participant data. */
     partialSig: Uint8Array;
 };
+/** MuSig2 key aggregation context used by signing sessions. */
+export type KeyAggregate = {
+    /** Aggregate public key before x-only export. */
+    aggPublicKey: WeierstrassPoint<bigint>;
+    /** Accumulated sign from x-only tweaks. */
+    gAcc: bigint;
+    /** Accumulated tweak scalar. */
+    tweakAcc: bigint;
+};
 /**
  * Represents an error indicating an invalid contribution from a signer.
  * This allows pointing out which participant is malicious and what specifically is wrong.
@@ -86,11 +96,7 @@ export declare function sortKeys(publicKeys: TArg<Uint8Array[]>): TRet<Uint8Arra
  * ]);
  * ```
  */
-export declare function keyAggregate(publicKeys: TArg<Uint8Array[]>, tweaks?: TArg<Uint8Array[]>, isXonly?: boolean[]): {
-    aggPublicKey: import("@noble/curves/abstract/weierstrass.js").WeierstrassPoint<bigint>;
-    gAcc: bigint;
-    tweakAcc: bigint;
-};
+export declare function keyAggregate(publicKeys: TArg<Uint8Array[]>, tweaks?: TArg<Uint8Array[]>, isXonly?: boolean[]): KeyAggregate;
 /**
  * Exports the aggregate public key to a byte array.
  * @param ctx - result of {@link keyAggregate}
@@ -283,4 +289,3 @@ export declare class Session {
  * ```
  */
 export declare function deterministicSign(secret: TArg<Uint8Array>, aggOtherNonce: TArg<Uint8Array>, publicKeys: TArg<Uint8Array[]>, msg: TArg<Uint8Array>, tweaks?: TArg<Uint8Array[]>, isXonly?: boolean[], rand?: TArg<Uint8Array>, fastSign?: boolean): TRet<DetNonce>;
-//# sourceMappingURL=musig2.d.ts.map

package/musig2.js

@@ -2,7 +2,7 @@ import { schnorr, secp256k1 } from '@noble/curves/secp256k1.js';
 import { aInRange, concatBytes, equalBytes, numberToBytesBE } from '@noble/curves/utils.js';
 import { abytes, anumber, randomBytes } from '@noble/hashes/utils.js';
 import * as P from 'micro-packed';
-import { compareBytes, hasEven } from "./utils.js";
+import { compareBytes, hasEven, validateObject } from "./utils.js";
 /**
  * Represents an error indicating an invalid contribution from a signer.
  * This allows pointing out which participant is malicious and what specifically is wrong.
@@ -43,6 +43,9 @@ const PUBKEY_LEN = /* @__PURE__ */ (() => secp256k1.lengths.publicKey)();
 // BIP327 uses bytes(33, 0) both as cbytes_ext(Point.ZERO) for infinity and as GetSecondKey's
 // "no second distinct key" sentinel, so this all-zero compressed slot is intentionally out-of-band.
 const ZERO = /* @__PURE__ */ new Uint8Array(PUBKEY_LEN); // Compressed zero point
+// Be friendly to bad ECMAScript parsers by not using bigint literals.
+// prettier-ignore
+const _0n = /* @__PURE__ */ BigInt(0), _1n = /* @__PURE__ */ BigInt(1);
 // Encoding
 // TODO: re-use in PSBT?
 // This is BIP327's cbytes_ext/cpoint_ext adapter: normal points stay in compressed SEC1,
@@ -54,7 +57,7 @@ const compressed = /* @__PURE__ */ (() => P.apply(P.bytes(33), {
 // This coder is only for stored secnonce limbs k1/k2, which BIP327 requires to be
 // nonzero scalars in [1, n); tweak scalars use different validation because 0 is allowed there.
 const scalar = /* @__PURE__ */ (() => P.validate(P.U256BE, (n) => {
-    aInRange('n', n, 1n, Fn.ORDER);
+    aInRange('n', n, _1n, Fn.ORDER);
     return n;
 }))();
 // Shared for both per-signer pubnonce bytes and aggregate aggnonce bytes. Because it accepts
@@ -172,7 +175,7 @@ function keyAggCoeffInternal(publicKey1, publicKey2, L) {
     abytes(publicKey1, PUBKEY_LEN);
     abytes(publicKey2, PUBKEY_LEN);
     if (equalBytes(publicKey1, publicKey2))
-        return 1n;
+        return _1n;
     return taggedInt('KeyAgg coefficient', L, publicKey1);
 }
 /**
@@ -223,6 +226,10 @@ export function keyAggregate(publicKeys, tweaks = [], isXonly = []) {
         }
         aggPublicKey = aggPublicKey.add(Pi.multiply(keyAggCoeffInternal(publicKeys[i], pk2, L)));
     }
+    // BIP327 KeyAggInternal: "Fail if is_infinite(Q)". Computationally unreachable for
+    // hash-derived coefficients, but the spec mandates the explicit check before tweaking.
+    if (isZero(aggPublicKey))
+        throw new Error('keyAggregate: aggregate public key cannot be infinity');
     let gAcc = Fn.ONE;
     let tweakAcc = Fn.ZERO;
     // Apply tweaks
@@ -257,6 +264,9 @@ export function keyAggregate(publicKeys, tweaks = [], isXonly = []) {
  * ```
  */
 export function keyAggExport(ctx) {
+    validateObject(ctx, {}, {}, 'ctx');
+    if (!(ctx.aggPublicKey instanceof Point))
+        throw new TypeError('"ctx.aggPublicKey" expected point, got type=' + typeof ctx.aggPublicKey);
     // BIP327 GetXonlyPubkey returns xbytes(Q), so this is the 32-byte x-only aggregate key
     // instead of the 33-byte compressed SEC1 form.
     return pointToBytes(ctx.aggPublicKey);
@@ -425,6 +435,7 @@ export class Session {
      * @throws If the input is invalid, such as wrong array sizes or lengths. {@link Error}
      */
     constructor(aggNonce, publicKeys, msg, tweaks = [], isXonly = []) {
+        abytes(aggNonce, 66);
         abytesArray(publicKeys, 33);
         abytesArray(tweaks, 32);
         aXonly(isXonly);
@@ -443,7 +454,10 @@ export class Session {
         this.gAcc = gAcc;
         this.tweakAcc = tweakAcc;
         this.b = taggedInt('MuSig/noncecoef', aggNonce, pointToBytes(aggPublicKey), msg);
-        const R = R1.add(R2.multiply(this.b));
+        // b and the nonce points are public session values, so the faster variable-time
+        // multiplication is safe here; it also matches the reference point_mul, which
+        // maps a (negligible-probability) zero coefficient to infinity instead of failing.
+        const R = R1.add(R2.multiplyUnsafe(this.b));
         this.R = isZero(R) ? Point.BASE : R;
         this.e = taggedInt('BIP0340/challenge', pointToBytes(this.R), pointToBytes(aggPublicKey), msg);
         this.tweaks = tweaks.map((t) => Uint8Array.from(t));
@@ -476,13 +490,16 @@ export class Session {
         // BIP327 PartialSigVerifyInternal: `Let s = int(psig); fail if s >= n`, so s=0 must stay
         // in the public verification equation and return false on mismatch instead of throwing.
         const { R1, R2 } = PubNonce.decode(publicNonce);
-        const Re_s_ = R1.add(R2.multiply(b));
+        // Verification only handles public data (nonces, pubkeys, hash-derived scalars),
+        // so the faster variable-time multiplications are safe here; they also match the
+        // reference point_mul, which maps zero scalars to infinity instead of failing.
+        const Re_s_ = R1.add(R2.multiplyUnsafe(b));
         const Re_s = hasEven(R.y) ? Re_s_ : Re_s_.negate();
         const P = Point.fromBytes(publicKey);
         const a = this.getSessionKeyAggCoeff(P);
-        const g = Fn.mul(evenScalar(Q, 1n), gAcc);
+        const g = Fn.mul(evenScalar(Q, _1n), gAcc);
         const left = Point.BASE.multiplyUnsafe(s);
-        const right = Re_s.add(P.multiply(Fn.mul(e, Fn.mul(a, g))));
+        const right = Re_s.add(P.multiplyUnsafe(Fn.mul(e, Fn.mul(a, g))));
         return left.equals(right);
     }
     /**
@@ -510,7 +527,7 @@ export class Session {
         if (!Fn.isValid(k1_))
             throw new Error('wrong k1');
         if (!Fn.isValid(k2_))
-            throw new Error('wrong k1');
+            throw new Error('wrong k2');
         const k1 = evenScalar(R, k1_);
         const k2 = evenScalar(R, k2_);
         const d_ = Fn.fromBytes(secret);
@@ -521,7 +538,7 @@ export class Session {
         if (!equalBytes(pk, originalPk))
             throw new Error('Public key does not match nonceGen argument');
         const a = this.getSessionKeyAggCoeff(P);
-        const g = evenScalar(Q, 1n);
+        const g = evenScalar(Q, _1n);
         const d = Fn.mul(g, Fn.mul(gAcc, d_));
         /// k1 + (b*k2) + (e*a*d)
         const s = Fn.add(k1, Fn.add(Fn.mul(b, k2), Fn.mul(e, Fn.mul(a, d))));
@@ -582,14 +599,14 @@ export class Session {
         if (partialSigs.length < 1)
             throw new RangeError('partialSigs.length must be >= 1');
         const { Q, tweakAcc, R, e } = this;
-        let s = 0n;
+        let s = _0n;
         for (let i = 0; i < partialSigs.length; i++) {
             const si = Fn.fromBytes(partialSigs[i], true);
             if (!Fn.isValid(si))
                 throw new InvalidContributionErr(i, 'psig');
             s = Fn.add(s, si);
         }
-        const g = evenScalar(Q, 1n);
+        const g = evenScalar(Q, _1n);
         s = Fn.add(s, Fn.mul(e, Fn.mul(g, tweakAcc))); // s + e * g * tweakAcc
         return concatBytes(pointToBytes(R), Fn.toBytes(s));
     }
@@ -653,4 +670,3 @@ export function deterministicSign(secret, aggOtherNonce, publicKeys, msg, tweaks
     const partialSig = session.sign(secretNonce, secret, fastSign);
     return { publicNonce, partialSig };
 }
-//# sourceMappingURL=musig2.js.map