@scure/btc-signer 2.2.0 → 2.4.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)
@@ -480,13 +515,28 @@ deepStrictEqual(hex.encode(btc.OutScript.encode(decoded)), '51024e73');
 
 ### 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 support both PSBTv0 and PSBTv2 (there is no PSBTv1). Explicit PSBTv0 conversion removes
+PSBTv2-only fields after translating the unsigned transaction representation.
+
+Assigned fields from BIPs 322, 353, 372, 373, 375, and 376 are decoded explicitly and survive the
+default path. `TxOpts.unknown` and `TxOpts.proprietary` govern only genuinely unknown and
+proprietary records:
+
+- `ignore` preserves them, but the library may operate without understanding future constraints.
+- `strip` accepts and removes them; this is the default and can break interoperability with future
+  extensions.
+- `strict` rejects them.
 
-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.
+Undefined bits in PSBTv2 `txModifiable` follow the `unknown` policy. `strip` and `strict` can also
+fingerprint this library or version, while `ignore` offers better forwarding compatibility at the
+cost of interpreting less protocol state. The deprecated `allowUnknown` boolean maps `true` to
+`ignore` and `false` to `strip`.
 
-PSBTv2 features tx_modifiable and taproot+bip32 are not supported yet.
+When signing an untrusted or multi-party PSBT, pass
+`{ strictPrevoutValidation: true }` to `Transaction.fromPSBT`. This requires every input to include
+a full `nonWitnessUtxo` matching its outpoint before any signature is produced. It prevents forged
+`witnessUtxo` amounts from making the displayed transaction fee appear lower than the fee that the
+valid transaction will actually pay.
 
 ```text
 // Decode
@@ -519,27 +569,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 +682,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;
@@ -902,10 +952,28 @@ when making an on-chain bitcoin payment. The library:
 - 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)
+Taproot estimation is precise, but you have to pass `sighashType` when using a non-default
+sighash because it changes signature size. A Taproot input can advertise paths that the current
+wallet cannot spend. Pass the wallet's x-only public keys as `filterTaproot` to remove unavailable
+internal-key and script paths before selection:
+
+```js
+import * as btc from '@scure/btc-signer';
+
+const select = (utxos, outputs, changeAddress, feePerByte, myPublicKey) =>
+  btc.selectUTXO(utxos, outputs, 'default', {
+    changeAddress,
+    feePerByte,
+    filterTaproot: [myPublicKey],
+  });
+```
+
+Filtering is opt-in: when `filterTaproot` is omitted, no paths are removed. The standalone
+`btc.filterTaproot(utxos, [myPublicKey])` utility returns the same filtered candidate records.
+Built-in `tr_ns` and `tr_ms` paths are checked directly. Custom or unknown leaves are rejected;
+callers must filter those paths using their own semantics before invoking this helper. Estimation
+and finalization choose the available path with the smallest complete witness, retaining the old
+shallowest-path order for equal weights.
 
 `Oldest` / `Newest` expects UTXO provided in historical order (oldest first),
 otherwise we have no way to detect age of tx.
@@ -1025,11 +1093,108 @@ 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)
 is available in `@scure/btc-signer/musig2.js`. Check out [bip327-musig2.test.ts](./test/bip327-musig2.test.ts) as well:
 
+**Security warning:** every MuSig2 secret nonce must be used for exactly one partial signature.
+`Session.sign()` zeroes only the exact `Uint8Array` passed to it; clones, serialized values,
+database records, and process snapshots remain live. Reusing the same nonce in distinct sessions
+can reveal the signer's secret key. Stateful signers must keep one authoritative nonce record and
+atomically consume it before releasing a partial signature.
+
 > `npm install @noble/curves`
 
 ```ts
@@ -1348,12 +1513,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

@@ -5,9 +5,10 @@ export { multisig, p2ms, p2pk, p2pkh, p2sh, p2tr, p2tr_ms, p2tr_ns, p2tr_pk, p2w
 export { CompactSize, MAX_SCRIPT_BYTE_LENGTH, OP, RawTx, RawWitness, Script, ScriptNum, } from './script.ts';
 export type { ScriptType } from './script.ts';
 export { getInputType, Transaction } from './transaction.ts';
-export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK } from './utils.ts';
+export type { TxOpts, Unknowns } from './transaction.ts';
+export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK, taprootNumsKey } from './utils.ts';
 export type { TArg, TRet } from './utils.ts';
-export { selectUTXO } from './utxo.ts';
+export { filterTaproot, selectUTXO } from './utxo.ts';
 /**
  * Small collection of commonly used utility exports.
  * @example
@@ -24,9 +25,8 @@ export declare const utils: TRet<Readonly<{
     randomPrivateKeyBytes: () => TRet<Uint8Array>;
     taprootTweakPubkey: typeof taprootTweakPubkey;
 }>>;
-export { _sortPubkeys, Address, combinations, getAddress, OutScript, sortedMultisig, taprootListToTree, WIF, } from './payment.ts';
+export { _sortPubkeys, Address, combinations, getAddress, MAX_COMBINATIONS, OutScript, sortedMultisig, taprootListToTree, WIF, } from './payment.ts';
 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

@@ -4,8 +4,8 @@ import { compareBytes, concatBytes, isBytes, pubSchnorr, randomPrivateKeyBytes,
 export { multisig, p2ms, p2pk, p2pkh, p2sh, p2tr, p2tr_ms, p2tr_ns, p2tr_pk, p2wpkh, p2wsh } from "./payment.js";
 export { CompactSize, MAX_SCRIPT_BYTE_LENGTH, OP, RawTx, RawWitness, Script, ScriptNum, } from "./script.js";
 export { getInputType, Transaction } from "./transaction.js";
-export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK } from "./utils.js";
-export { selectUTXO } from "./utxo.js";
+export { NETWORK, TAPROOT_UNSPENDABLE_KEY, TEST_NETWORK, taprootNumsKey } from "./utils.js";
+export { filterTaproot, selectUTXO } from "./utxo.js";
 /**
  * Small collection of commonly used utility exports.
  * @example
@@ -23,10 +23,9 @@ export const utils = /* @__PURE__ */ (() => Object.freeze({
     randomPrivateKeyBytes,
     taprootTweakPubkey,
 }))();
-export { _sortPubkeys, Address, combinations, getAddress, OutScript, sortedMultisig, taprootListToTree, WIF, } from "./payment.js";
+export { _sortPubkeys, Address, combinations, getAddress, MAX_COMBINATIONS, OutScript, sortedMultisig, taprootListToTree, WIF, } from "./payment.js";
 // remove
 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,9 +1,13 @@
+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 = {
     /** Public nonce that gets shared with the other participants. */
     public: Uint8Array;
-    /** Secret nonce that stays local until partial signing finishes. */
+    /**
+     * Secret nonce that stays local until partial signing finishes. It MUST be consumed exactly once;
+     * never retain a copy that could be loaded for another signing session.
+     */
     secret: Uint8Array;
 };
 /**
@@ -16,6 +20,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 +99,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}
@@ -110,6 +119,12 @@ export declare function keyAggregate(publicKeys: TArg<Uint8Array[]>, tweaks?: TA
 export declare function keyAggExport(ctx: ReturnType<typeof keyAggregate>): TRet<Uint8Array>;
 /**
  * Generates a nonce pair (public and secret) for MuSig2 signing.
+ *
+ * SECURITY: The returned secret nonce MUST be used for exactly one partial signature. Keep one
+ * authoritative copy and atomically consume it when calling {@link Session.sign}. That method
+ * zeroes only the exact `Uint8Array` passed to it; clones, serialized values, database records, and
+ * snapshots remain live. Reusing a secret nonce in distinct sessions can reveal the secret key.
+ *
  * @param publicKey - individual public key of the signer
  * @param secretKey - optional secret key, mixed in to blind the randomness source
  * @param aggPublicKey - aggregate public key of all signers
@@ -221,7 +236,12 @@ export declare class Session {
     /**
      * Generates a partial signature for a given message, secret nonce,
      * secret key, and session context.
-     * @param secretNonce - secret nonce for this signing session; it is zeroed after use
+     *
+     * SECURITY: `secretNonce` MUST be used exactly once. This method zeroes the first 64 bytes of the
+     * supplied array, including when later validation fails, but cannot erase copies or persisted
+     * representations. Reusing those nonce scalars in a distinct session can reveal the secret key.
+     *
+     * @param secretNonce - sole authoritative secret-nonce buffer for this signing session
      * @param secret - secret key of the signer
      * @param fastSign - if `true`, skip the self-verification pass
      * @returns The partial signature (Uint8Array).
@@ -241,7 +261,7 @@ export declare class Session {
     partialSigVerify(partialSig: Uint8Array, pubNonces: Uint8Array[], i: number): boolean;
     /**
      * Aggregates partial signatures from multiple signers into a single final signature.
-     * @param partialSigs - partial signatures from each signer
+     * @param partialSigs - exactly one positional partial signature per session participant
      * @returns The final aggregate signature (Uint8Array).
      * @throws If the input is invalid, such as wrong array sizes or malformed
      * signatures. {@link Error}
@@ -283,4 +303,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);
@@ -278,6 +288,12 @@ const nonceHash = (rand, publicKey, aggPublicKey, i, msgPrefixed, extraIn) =>
 taggedInt('MuSig/nonce', rand, new Uint8Array([publicKey.length]), publicKey, new Uint8Array([aggPublicKey.length]), aggPublicKey, msgPrefixed, numberToBytesBE(extraIn.length, 4), extraIn, new Uint8Array([i]));
 /**
  * Generates a nonce pair (public and secret) for MuSig2 signing.
+ *
+ * SECURITY: The returned secret nonce MUST be used for exactly one partial signature. Keep one
+ * authoritative copy and atomically consume it when calling {@link Session.sign}. That method
+ * zeroes only the exact `Uint8Array` passed to it; clones, serialized values, database records, and
+ * snapshots remain live. Reusing a secret nonce in distinct sessions can reveal the secret key.
+ *
  * @param publicKey - individual public key of the signer
  * @param secretKey - optional secret key, mixed in to blind the randomness source
  * @param aggPublicKey - aggregate public key of all signers
@@ -425,6 +441,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 +460,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,19 +496,27 @@ 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);
     }
     /**
      * Generates a partial signature for a given message, secret nonce,
      * secret key, and session context.
-     * @param secretNonce - secret nonce for this signing session; it is zeroed after use
+     *
+     * SECURITY: `secretNonce` MUST be used exactly once. This method zeroes the first 64 bytes of the
+     * supplied array, including when later validation fails, but cannot erase copies or persisted
+     * representations. Reusing those nonce scalars in a distinct session can reveal the secret key.
+     *
+     * @param secretNonce - sole authoritative secret-nonce buffer for this signing session
      * @param secret - secret key of the signer
      * @param fastSign - if `true`, skip the self-verification pass
      * @returns The partial signature (Uint8Array).
@@ -510,7 +538,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 +549,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))));
@@ -570,26 +598,27 @@ export class Session {
     }
     /**
      * Aggregates partial signatures from multiple signers into a single final signature.
-     * @param partialSigs - partial signatures from each signer
+     * @param partialSigs - exactly one positional partial signature per session participant
      * @returns The final aggregate signature (Uint8Array).
      * @throws If the input is invalid, such as wrong array sizes or malformed
      * signatures. {@link Error}
      */
     partialSigAgg(partialSigs) {
         abytesArray(partialSigs, 32);
-        // BIP327 PartialSigAgg is defined for a non-empty psig_1..u list tied to this session_ctx;
-        // [] is not a valid aggregate-signature input even though the sum starts from zero.
-        if (partialSigs.length < 1)
-            throw new RangeError('partialSigs.length must be >= 1');
+        // BIP327 PartialSigAgg consumes psig_1..u for the same u signers in session_ctx. Accepting
+        // fewer or more scalars would return a signature-shaped value for a different equation.
+        if (partialSigs.length !== this.publicKeys.length)
+            throw new RangeError(`partialSigs.length=${partialSigs.length} must equal ` +
+                `participant count=${this.publicKeys.length}`);
         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 +682,3 @@ export function deterministicSign(secret, aggOtherNonce, publicKeys, msg, tweaks
     const partialSig = session.sign(secretNonce, secret, fastSign);
     return { publicNonce, partialSig };
 }
-//# sourceMappingURL=musig2.js.map