@scure/btc-signer 2.0.1 → 2.3.0

package/p2p.d.ts

@@ -17,21 +17,30 @@
  *
  * @module
  */
-import { type Bytes } from './utils.ts';
+import { type Bytes, type TArg, type TRet } from './utils.ts';
 /**
  * Experimental ElligatorSwift implementation:
  * Schnorr-like x-only ECDH with public keys indistinguishable from uniformly random bytes.
  * Documented in BIP324.
+ * @example
+ * Encode an x-only secp256k1 public key into the 64-byte BIP324 pseudorandom form.
+ * ```ts
+ * import { bytesToNumberBE } from '@noble/curves/utils.js';
+ * import { schnorr } from '@noble/curves/secp256k1.js';
+ * import { elligatorSwift } from '@scure/btc-signer/p2p.js';
+ * const secret = schnorr.utils.randomSecretKey();
+ * const encoded = elligatorSwift.encode(bytesToNumberBE(schnorr.getPublicKey(secret)));
+ * elligatorSwift.decode(encoded);
+ * ```
  */
-export declare const elligatorSwift: {
+export declare const elligatorSwift: Readonly<{
     _inv: (x: bigint, u: bigint, ellCase: number) => bigint | void;
-    encode: (x: bigint) => Uint8Array;
-    decode: (data: Uint8Array) => Uint8Array;
+    encode: (x: bigint) => TRet<Uint8Array>;
+    decode: (data: TArg<Uint8Array>) => TRet<Uint8Array>;
     keygen: () => {
         privateKey: Bytes;
         publicKey: Bytes;
     };
-    getSharedSecret: (privateKeyA: Uint8Array, publicKeyB: Uint8Array) => Bytes;
-    getSharedSecretBip324: (privateKeyOurs: Uint8Array, publicKeyTheirs: Uint8Array, publicKeyOurs: Uint8Array, initiating: boolean) => Uint8Array;
-};
-//# sourceMappingURL=p2p.d.ts.map
+    getSharedSecret: (privateKeyA: TArg<Uint8Array>, publicKeyB: TArg<Uint8Array>) => TRet<Bytes>;
+    getSharedSecretBip324: (privateKeyOurs: TArg<Uint8Array>, publicKeyTheirs: TArg<Uint8Array>, publicKeyOurs: TArg<Uint8Array>, initiating: boolean) => TRet<Uint8Array>;
+}>;

package/p2p.js

@@ -22,16 +22,31 @@ import { concatBytes, abytes } from '@noble/curves/utils.js';
 import { schnorr, secp256k1 } from '@noble/curves/secp256k1.js';
 import { randomBytes } from '@noble/hashes/utils.js';
 import { tagSchnorr } from "./utils.js";
+// BIP324's EllSwift formulas use full secp256k1 points for priv*G and x-only ECDH
+// before exporting x coordinates or x-only bytes.
 const Point = secp256k1.Point;
+// BIP324 defines XSwiftEC over integers modulo secp256k1's field prime p, so the
+// EllSwift u/t/x arithmetic and 32-byte field encodings in this file all go through Point.Fp.
 const Fp = Point.Fp;
+// EllSwift private scalars use secp256k1's subgroup order n, not the field prime p used
+// by Point.Fp; Point.Fn is the generic scalar field object, not a secret-key validator.
 const Fn = Point.Fn;
 const _1n = BigInt(1);
 const _2n = BigInt(2);
+// BIP324's XSwiftEC uses c = sqrt(-3) mod p and chooses the square root that is
+// itself a square, which is what Fp.sqrt(Fp.create(-3)) returns here.
 const MINUS_3_SQRT = Fp.sqrt(Fp.create(BigInt(-3)));
 const _3n = BigInt(3);
 const _4n = BigInt(4);
 const _7n = BigInt(7);
+// Precomputed 1/2 mod p: turns the frequent "divide by 2" steps of XSwiftEC/XSwiftECInv
+// into single multiplications instead of one modular inversion per call.
+const INV_2 = Fp.inv(Fp.create(_2n));
+// This is the "lift_x(x) succeeds" predicate for field-normalized x values.
+// Raw x >= p would need the full BIP340 range check before reducing modulo p.
 const isValidX = (x) => FpIsSquare(Fp, Fp.add(Fp.mul(Fp.mul(x, x), x), _7n));
+// BIP324's "return None if the square root does not exist" branches are modeled with
+// undefined here; current callers only pass field-normalized values from Fp arithmetic.
 const trySqrt = (x) => {
     try {
         return Fp.sqrt(x);
@@ -42,9 +57,20 @@ const trySqrt = (x) => {
  * Experimental ElligatorSwift implementation:
  * Schnorr-like x-only ECDH with public keys indistinguishable from uniformly random bytes.
  * Documented in BIP324.
+ * @example
+ * Encode an x-only secp256k1 public key into the 64-byte BIP324 pseudorandom form.
+ * ```ts
+ * import { bytesToNumberBE } from '@noble/curves/utils.js';
+ * import { schnorr } from '@noble/curves/secp256k1.js';
+ * import { elligatorSwift } from '@scure/btc-signer/p2p.js';
+ * const secret = schnorr.utils.randomSecretKey();
+ * const encoded = elligatorSwift.encode(bytesToNumberBE(schnorr.getPublicKey(secret)));
+ * elligatorSwift.decode(encoded);
+ * ```
  */
-export const elligatorSwift = {
+export const elligatorSwift = /* @__PURE__ */ Object.freeze({
     // (internal stuff, exported for tests only): decode(u, _inv(x, u)) = x
+    // Returns the case-selected BIP324 XSwiftECInv representative, or undefined for None.
     _inv: (x, u, ellCase) => {
         if (!Number.isSafeInteger(ellCase) || ellCase < 0 || ellCase > 7)
             throw new Error(`elligatorSwift._inv: wrong case=${ellCase}`);
@@ -70,7 +96,7 @@ export const elligatorSwift = {
                 return; // [2 condition]
             if (ellCase & 1 && Fp.is0(r))
                 return;
-            v = Fp.div(Fp.add(Fp.neg(u), Fp.div(r, s)), _2n); // v = (-u + r / s) / 2
+            v = Fp.mul(Fp.add(Fp.neg(u), Fp.div(r, s)), INV_2); // v = (-u + r / s) / 2
         }
         const w = trySqrt(s);
         if (w === undefined)
@@ -79,15 +105,29 @@ export const elligatorSwift = {
         const t0 = last & 1 ? Fp.add(_1n, MINUS_3_SQRT) : Fp.sub(_1n, MINUS_3_SQRT);
         const w0 = last === 0 || last === 5 ? Fp.neg(w) : w; // -w | w
         // w0 * (u * t0 / 2 + v)
-        return Fp.mul(w0, Fp.add(Fp.div(Fp.mul(u, t0), _2n), v));
+        return Fp.mul(w0, Fp.add(Fp.mul(Fp.mul(u, t0), INV_2), v));
     },
     // Encode public key (point or x coordinate bigint) into 64-byte pseudorandom encoding
+    // BIP324 samples encodings for x(P), so callers must pass a curve X coordinate in 0..p-1;
+    // without an explicit guard, the field helpers below interpret out-of-range x modulo p.
     encode: (x) => {
+        // BIP324 XSwiftEC uses field elements in `0..p-1`, and ellswift_create passes `XElligatorSwift(x(P))`,
+        // so encode() must reject out-of-range x instead of silently reducing a different bigint modulo p.
+        if (!Fp.isValid(x))
+            throw new RangeError('elligatorSwift.encode: expected x coordinate in range 0..p-1');
+        // Off-curve x cannot round-trip: decode() only returns lift_x-able candidates, so
+        // the loop below would silently emit an encoding of a *different* public key.
+        if (!isValidX(x))
+            throw new RangeError('elligatorSwift.encode: expected x coordinate of a curve point');
         // 200k test cycles per keygen: avg=4 max=48
         // seems too much, but same as for reference implementation
         while (true) {
-            // random scalar 1..Fp.ORDER
-            const u = Fp.create(Fp.fromBytes(secp256k1.utils.randomSecretKey()));
+            // Random field element 1..p-1: BIP324 samples u over the whole field (the previous
+            // secret-key sampler silently restricted u to 1..n-1); decode() remaps u = 0, so
+            // zero cannot round-trip and is skipped.
+            const u = Fp.create(Fp.fromBytes(randomBytes(32), true));
+            if (Fp.is0(u))
+                continue;
             const ellCase = randomBytes(1)[0] & 7; // [0..8)
             const t = elligatorSwift._inv(x, u, ellCase);
             if (!t)
@@ -98,6 +138,8 @@ export const elligatorSwift = {
     // Decode elligatorSwift point to xonly
     decode: (data) => {
         const _data = abytes(data, 64, 'data');
+        // BIP324 interprets both 32-byte halves as integers modulo p before the
+        // XSwiftEC remaps below, so arbitrary 64-byte inputs are valid here.
         let u = Fp.create(Fp.fromBytes(_data.subarray(0, 32), true));
         let t = Fp.create(Fp.fromBytes(_data.subarray(32, 64), true));
         if (Fp.is0(u))
@@ -117,16 +159,19 @@ export const elligatorSwift = {
         let res = Fp.add(u, Fp.mul(Fp.mul(y, y), _4n)); // u + 4 * Y ** 2,
         if (isValidX(res))
             return Fp.toBytes(res);
-        res = Fp.div(Fp.sub(Fp.div(Fp.neg(x), y), u), _2n); // (-X / Y - u) / 2
+        // X / Y is shared by the remaining candidates; computing it once saves an inversion.
+        const xDivY = Fp.div(x, y);
+        res = Fp.mul(Fp.sub(Fp.neg(xDivY), u), INV_2); // (-X / Y - u) / 2
         if (isValidX(res))
             return Fp.toBytes(res);
-        res = Fp.div(Fp.sub(Fp.div(x, y), u), _2n); // (X / Y - u) / 2
+        res = Fp.mul(Fp.sub(xDivY, u), INV_2); // (X / Y - u) / 2
         if (isValidX(res))
             return Fp.toBytes(res);
         throw new Error('elligatorSwift: cannot decode public key');
     },
     // Generate pair (public key, secret key)
     keygen: () => {
+        // Use a subgroup-valid secp256k1 secret key, then ElligatorSwift-encode x(priv*G).
         const privateKey = secp256k1.utils.randomSecretKey();
         const p = Point.BASE.multiply(Point.Fn.fromBytes(privateKey));
         const publicKey = elligatorSwift.encode(p.x);
@@ -134,6 +179,8 @@ export const elligatorSwift = {
     },
     // Generates shared secret between a pub key and a priv key
     getSharedSecret: (privateKeyA, publicKeyB) => {
+        // decode() accepts arbitrary 64-byte ElligatorSwift encodings, but the private scalar
+        // here still follows the usual secp256k1 subgroup-secret domain (1..n-1).
         const pub = elligatorSwift.decode(publicKeyB);
         const priv = abytes(privateKeyA, 32, 'privKey');
         const point = schnorr.utils.lift_x(Fp.fromBytes(pub));
@@ -142,11 +189,16 @@ export const elligatorSwift = {
     },
     // BIP324 shared secret
     getSharedSecretBip324: (privateKeyOurs, publicKeyTheirs, publicKeyOurs, initiating) => {
-        const ours = abytes(publicKeyOurs, undefined, 'publicKeyOurs');
-        const theirs = abytes(publicKeyTheirs, undefined, 'publicKeyTheirs');
+        // BIP324 Shared secret computation hashes "the exactly 64-byte public keys'
+        // encodings sent over the wire", so both ElligatorSwift inputs must be 64 bytes here.
+        // Initiator/responder ordering decides the hash-input order, so require a real boolean
+        // instead of letting arbitrary truthy values pick a side.
+        if (typeof initiating !== 'boolean')
+            throw new TypeError('"initiating" expected boolean, got type=' + typeof initiating);
+        const ours = abytes(publicKeyOurs, 64, 'publicKeyOurs');
+        const theirs = abytes(publicKeyTheirs, 64, 'publicKeyTheirs');
         const ecdhPoint = elligatorSwift.getSharedSecret(privateKeyOurs, theirs);
         const pubs = initiating ? [ours, theirs] : [theirs, ours];
         return tagSchnorr('bip324_ellswift_xonly_ecdh', ...pubs, ecdhPoint);
     },
-};
-//# sourceMappingURL=p2p.js.map
+});

package/package.json

@@ -1,42 +1,42 @@
 {
   "name": "@scure/btc-signer",
-  "version": "2.0.1",
+  "version": "2.3.0",
   "description": "Audited & minimal library for Bitcoin. Handle transactions, Schnorr, Taproot, UTXO & PSBT",
   "files": [
     "*.js",
     "*.d.ts",
-    "*.js.map",
-    "*.d.ts.map",
     "src",
     "!_type_test.*"
   ],
   "dependencies": {
-    "@noble/curves": "~2.0.0",
-    "@noble/hashes": "~2.0.0",
-    "@scure/base": "~2.0.0",
-    "micro-packed": "~0.8.0"
+    "@noble/curves": "~2.3.0",
+    "@noble/hashes": "~2.3.0",
+    "@scure/base": "~2.3.0",
+    "micro-packed": "~0.11.0"
   },
   "devDependencies": {
-    "@paulmillr/jsbt": "0.4.4",
-    "@scure/bip32": "~2.0.0",
+    "@paulmillr/jsbt": "0.6.5",
+    "@scure/bip32": "2.2.0",
+    "micro-ftch": "^1.1.0",
     "prettier": "3.6.2",
-    "typescript": "5.9.2"
+    "typescript": "6.0.2"
   },
   "scripts": {
+    "benchmark:size": "npx bismar@0.1.3 -s",
     "build": "tsc",
-    "build:clean": "rm -f *.{js,d.ts,js.map,d.ts.map}",
-    "build:release": "npx --no @paulmillr/jsbt esbuild test/build",
+    "build:clean": "rm -f *.{js,d.ts}",
+    "check": "jsbt-check",
+    "benchmark": "node benchmark/index.ts",
+    "benchmark:network": "node benchmark/network.ts",
     "format": "prettier --write src test/*.test.*",
-    "test": "node --no-warnings test/index.ts",
-    "test:bun": "bun test/index.ts",
-    "test:deno": "deno --allow-env --allow-read test/index.js",
-    "test:node20": "cd test; npx tsc; node compiled/test/index.js",
-    "test:big": "node test/slow.test.ts",
+    "test": "node test/index.ts",
+    "test:slow": "node test/slow.test.ts",
     "test:extended": "node --experimental-loader ./test/bitcoinjs-test/esm-loader.js ./test/bitcoinjs-test/index.test.js"
   },
   "exports": {
     ".": "./index.js",
     "./musig2.js": "./musig2.js",
+    "./net.js": "./net.js",
     "./p2p.js": "./p2p.js",
     "./payment.js": "./payment.js",
     "./psbt.js": "./psbt.js",