Merge pull request #378 from bsv-blockchain/serialization-speedups

Serialization speedups

Author: ty-everett

.github/workflows/benchmark-report.yml

@@ -0,0 +1,85 @@
+name: Benchmark Comparison
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  benchmarks:
+    name: Benchmarks (Node 22)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - name: Checkout PR branch
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build PR branch
+        run: npm run build
+
+      - name: Run PR benchmarks
+        run: node scripts/run-benchmarks.js --repo . --output pr-benchmarks.json
+
+      - name: Checkout master baseline
+        uses: actions/checkout@v4
+        with:
+          ref: master
+          path: master
+
+      - name: Install dependencies (master)
+        working-directory: master
+        run: npm ci
+
+      - name: Build master
+        working-directory: master
+        run: npm run build
+
+      - name: Run master benchmarks
+        run: node scripts/run-benchmarks.js --repo master --output master-benchmarks.json
+
+      - name: Capture baseline sha
+        id: baseline_sha
+        run: echo "value=$(cd master && git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Generate benchmark report
+        run: >
+          node scripts/format-benchmark-comment.js
+          --baseline master-benchmarks.json
+          --branch pr-benchmarks.json
+          --output benchmark-report.md
+          --branch-ref $GITHUB_SHA
+          --baseline-ref ${{ steps.baseline_sha.outputs.value }}
+
+      - name: Upload benchmark artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: |
+            pr-benchmarks.json
+            master-benchmarks.json
+            benchmark-report.md
+
+      - name: Comment on PR
+        if: github.event.pull_request.number != ''
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require('fs');
+            const body = fs.readFileSync('benchmark-report.md', 'utf8');
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: context.payload.pull_request.number,
+              body
+            });

CHANGELOG.md

@@ -181,6 +181,18 @@ All notable changes to this project will be documented in this file. The format
 
 ---
 
+### [1.9.0] - 2025-11-09
+
+### Added
+
+- Faster serialization and caching improvements
+- Use node- and browser-specific fast-paths opportunistically
+- Cache signatures in Spend to avoid repeated verifications
+- Cache serialized values and use Uint8Array in more places
+- These changes are not intended to be breaking, but a minor version increment is performed out of an abundance of caution
+
+---
+
 ### [1.8.12] - 2025-11-06
 
 ### Fixed

benchmarks/serialization-bench.js benchmarks/bn-serialization-bench.jsbenchmarks/serialization-bench.js renamed to benchmarks/bn-serialization-bench.js

@@ -4,6 +4,15 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ## Interfaces
 
+| |
+| --- |
+| [JacobianPointBI](#interface-jacobianpointbi) |
+| [SignatureHashCache](#interface-signaturehashcache) |
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
+---
+
 ### Interface: JacobianPointBI
 
 ```ts
@@ -16,6 +25,20 @@ export interface JacobianPointBI {
 
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
+---
+### Interface: SignatureHashCache
+
+```ts
+export interface SignatureHashCache {
+    hashPrevouts?: number[];
+    hashSequence?: number[];
+    hashOutputsAll?: number[];
+    hashOutputsSingle?: Map<number, number[]>;
+}
+```
+
+Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
+
 ---
 ## Classes
 
@@ -3898,7 +3921,7 @@ const sha256 = new SHA256();
 ```ts
 export class SHA256 {
     constructor() 
-    update(msg: number[] | string, enc?: "hex" | "utf8"): this 
+    update(msg: Uint8Array | number[] | string, enc?: "hex" | "utf8"): this 
     digest(): number[] 
     digestHex(): string 
 }
@@ -3919,8 +3942,8 @@ This class also uses the SHA-256 cryptographic hash algorithm that produces a 25
 export class SHA256HMAC {
     blockSize = 64;
     outSize = 32;
-    constructor(key: number[] | string) 
-    update(msg: number[] | string, enc?: "hex"): SHA256HMAC 
+    constructor(key: Uint8Array | number[] | string) 
+    update(msg: Uint8Array | number[] | string, enc?: "hex"): SHA256HMAC 
     digest(): number[] 
     digestHex(): string 
 }
@@ -3935,7 +3958,7 @@ If the key size is larger than the blockSize, it is digested using SHA-256.
 If the key size is less than the blockSize, it is padded with zeroes.
 
 ```ts
-constructor(key: number[] | string) 
+constructor(key: Uint8Array | number[] | string) 
 ```
 
 Argument Details
@@ -4006,7 +4029,7 @@ let hashedMessage = myHMAC.digestHex();
 Updates the `SHA256HMAC` object with part of the message to be hashed.
 
 ```ts
-update(msg: number[] | string, enc?: "hex"): SHA256HMAC 
+update(msg: Uint8Array | number[] | string, enc?: "hex"): SHA256HMAC 
 ```
 See also: [SHA256HMAC](./primitives.md#class-sha256hmac)
 
@@ -4067,8 +4090,8 @@ This class also uses the SHA-512 cryptographic hash algorithm that produces a 51
 export class SHA512HMAC {
     blockSize = 128;
     outSize = 32;
-    constructor(key: number[] | string) 
-    update(msg: number[] | string, enc?: "hex" | "utf8"): SHA512HMAC 
+    constructor(key: Uint8Array | number[] | string) 
+    update(msg: Uint8Array | number[] | string, enc?: "hex" | "utf8"): SHA512HMAC 
     digest(): number[] 
     digestHex(): string 
 }
@@ -4083,7 +4106,7 @@ If the key size is larger than the blockSize, it is digested using SHA-512.
 If the key size is less than the blockSize, it is padded with zeroes.
 
 ```ts
-constructor(key: number[] | string) 
+constructor(key: Uint8Array | number[] | string) 
 ```
 
 Argument Details
@@ -4154,7 +4177,7 @@ let hashedMessage = myHMAC.digestHex();
 Updates the `SHA512HMAC` object with part of the message to be hashed.
 
 ```ts
-update(msg: number[] | string, enc?: "hex" | "utf8"): SHA512HMAC 
+update(msg: Uint8Array | number[] | string, enc?: "hex" | "utf8"): SHA512HMAC 
 ```
 See also: [SHA512HMAC](./primitives.md#class-sha512hmac)
 
@@ -4682,27 +4705,50 @@ export default class TransactionSignature extends Signature {
     public static readonly SIGHASH_FORKID = 64;
     public static readonly SIGHASH_ANYONECANPAY = 128;
     scope: number;
-    static format(params: {
-        sourceTXID: string;
-        sourceOutputIndex: number;
-        sourceSatoshis: number;
-        transactionVersion: number;
-        otherInputs: TransactionInput[];
-        outputs: TransactionOutput[];
-        inputIndex: number;
-        subscript: Script;
-        inputSequence: number;
-        lockTime: number;
-        scope: number;
-    }): number[] 
+    static format(params: TransactionSignatureFormatParams): number[] 
+    static formatBytes(params: TransactionSignatureFormatParams): Uint8Array 
     static fromChecksigFormat(buf: number[]): TransactionSignature 
     constructor(r: BigNumber, s: BigNumber, scope: number) 
     public hasLowS(): boolean 
     toChecksigFormat(): number[] 
 }
 ```
 
-See also: [BigNumber](./primitives.md#class-bignumber), [Script](./script.md#class-script), [Signature](./primitives.md#class-signature), [TransactionInput](./transaction.md#interface-transactioninput), [TransactionOutput](./transaction.md#interface-transactionoutput)
+See also: [BigNumber](./primitives.md#class-bignumber), [Signature](./primitives.md#class-signature)
+
+#### Method format
+
+Formats the SIGHASH preimage for the targeted input, optionally using a cache to skip recomputing shared hash prefixes.
+
+```ts
+static format(params: TransactionSignatureFormatParams): number[] 
+```
+
+Argument Details
+
++ **params**
+  + Context for the signing input plus transaction metadata.
++ **params.cache**
+  + Optional cache storing previously computed `hashPrevouts`, `hashSequence`, or `hashOutputs*` values; it will be populated if present.
+
+#### Method formatBytes
+
+Formats the same SIGHASH preimage bytes as `format`, supporting the optional cache for hash reuse.
+
+```ts
+static formatBytes(params: TransactionSignatureFormatParams): Uint8Array 
+```
+
+Returns
+
+Bytes for signing.
+
+Argument Details
+
++ **params**
+  + Context for the signing operation.
++ **params.cache**
+  + Optional `SignatureHashCache` that may already contain hashed prefixes and is populated during formatting.
 
 #### Method hasLowS
 
@@ -4721,11 +4767,12 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 export class Writer {
-    public bufs: number[][];
-    constructor(bufs?: number[][]) 
+    public bufs: WriterChunk[];
+    constructor(bufs?: WriterChunk[]) 
     getLength(): number 
+    toUint8Array(): Uint8Array 
     toArray(): number[] 
-    write(buf: number[]): this 
+    write(buf: WriterChunk): this 
     writeReverse(buf: number[]): this 
     writeUInt8(n: number): this 
     writeInt8(n: number): this 
@@ -5309,7 +5356,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: hash160
 
 ```ts
-hash160 = (msg: number[] | string, enc?: "hex" | "utf8"): number[] => {
+hash160 = (msg: Uint8Array | number[] | string, enc?: "hex" | "utf8"): number[] => {
     const first = new SHA256().update(msg, enc).digest();
     return new RIPEMD160().update(first).digest();
 }
@@ -5323,7 +5370,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: hash256
 
 ```ts
-hash256 = (msg: number[] | string, enc?: "hex" | "utf8"): number[] => {
+hash256 = (msg: Uint8Array | number[] | string, enc?: "hex" | "utf8"): number[] => {
     const first = new SHA256().update(msg, enc).digest();
     return new SHA256().update(first).digest();
 }
@@ -5655,7 +5702,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: sha256
 
 ```ts
-sha256 = (msg: number[] | string, enc?: "hex" | "utf8"): number[] => {
+sha256 = (msg: Uint8Array | number[] | string, enc?: "hex" | "utf8"): number[] => {
     return new SHA256().update(msg, enc).digest();
 }
 ```
@@ -5668,7 +5715,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: sha256hmac
 
 ```ts
-sha256hmac = (key: number[] | string, msg: number[] | string, enc?: "hex"): number[] => {
+sha256hmac = (key: Uint8Array | number[] | string, msg: Uint8Array | number[] | string, enc?: "hex"): number[] => {
     return new SHA256HMAC(key).update(msg, enc).digest();
 }
 ```
@@ -5694,7 +5741,7 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 ### Variable: sha512hmac
 
 ```ts
-sha512hmac = (key: number[] | string, msg: number[] | string, enc?: "hex"): number[] => {
+sha512hmac = (key: Uint8Array | number[] | string, msg: Uint8Array | number[] | string, enc?: "hex"): number[] => {
     return new SHA512HMAC(key).update(msg, enc).digest();
 }
 ```
@@ -5851,16 +5898,19 @@ Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](
 
 ```ts
 toHex = (msg: number[]): string => {
-    let res = "";
-    for (const num of msg) {
-        res += zero2(num.toString(16));
+    if (CAN_USE_BUFFER) {
+        return BufferCtor.from(msg).toString("hex");
     }
-    return res;
+    if (msg.length === 0)
+        return "";
+    const out = new Array(msg.length);
+    for (let i = 0; i < msg.length; i++) {
+        out[i] = HEX_BYTE_STRINGS[msg[i] & 255];
+    }
+    return out.join("");
 }
 ```
 
-See also: [zero2](./primitives.md#variable-zero2)
-
 Links: [API](#api), [Interfaces](#interfaces), [Classes](#classes), [Functions](#functions), [Types](#types), [Enums](#enums), [Variables](#variables)
 
 ---