@bopen-io/wallet-toolbox 2.6.2-brc153.5 → 2.14.5

package/out/src/services/chaintracker/chaintracks/util/blockHeaderUtilities.js

@@ -12,8 +12,10 @@ exports.convertBitsToTarget = convertBitsToTarget;
 exports.convertBitsToWork = convertBitsToWork;
 exports.deserializeBaseBlockHeaders = deserializeBaseBlockHeaders;
 exports.deserializeBlockHeaders = deserializeBlockHeaders;
+exports.validateBaseBlockHeaderFormat = validateBaseBlockHeaderFormat;
 exports.validateHeaderFormat = validateHeaderFormat;
 exports.validateHeaderDifficulty = validateHeaderDifficulty;
+exports.validateHeaderProofOfWork = validateHeaderProofOfWork;
 exports.blockHash = blockHash;
 exports.serializeBaseBlockHeader = serializeBaseBlockHeader;
 exports.serializeBaseBlockHeaders = serializeBaseBlockHeaders;
@@ -30,22 +32,114 @@ exports.readUInt32BE = readUInt32BE;
 exports.convertBufferToUint32 = convertBufferToUint32;
 const dirtyHashes_1 = require("./dirtyHashes");
 const sdk_1 = require("@bsv/sdk");
+const Hash_1 = require("@bsv/sdk/primitives/Hash");
+const utils_1 = require("@bsv/sdk/primitives/utils");
 const utilityHelpers_noBuffer_1 = require("../../../../utility/utilityHelpers.noBuffer");
 const utilityHelpers_1 = require("../../../../utility/utilityHelpers");
-const validBulkHeaderFilesByFileHash_1 = require("./validBulkHeaderFilesByFileHash");
 const WERR_errors_1 = require("../../../../sdk/WERR_errors");
+const MAX_HEADER_COUNT = 100_000;
+const MAX_HEADER_BYTES = MAX_HEADER_COUNT * 80;
+const MAX_BLOCK_HEIGHT = 0x7fffffff;
+const UINT32_MAX = 0xffffffff;
+const HEX_32_BYTES = /^[0-9a-fA-F]{64}$/;
+function validateByteWindow(buffer, offset, length, name = 'buffer') {
+    if (!Array.isArray(buffer) && !(buffer instanceof Uint8Array)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER(name, 'a byte array');
+    }
+    if (!Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        !Number.isSafeInteger(length) ||
+        length < 0 ||
+        !Number.isSafeInteger(offset + length) ||
+        offset + length > buffer.length) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER(`${name} window`, 'non-negative safe integers within the byte array');
+    }
+    if (Array.isArray(buffer)) {
+        for (let index = offset; index < offset + length; index++) {
+            const value = buffer[index];
+            if (!Number.isInteger(value) || value < 0 || value > 0xff) {
+                throw new WERR_errors_1.WERR_INVALID_PARAMETER(name, 'an array of byte integers');
+            }
+        }
+    }
+}
+function validateWritableByteWindow(buffer, offset, length) {
+    if (!Array.isArray(buffer) && !(buffer instanceof Uint8Array)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('buffer', 'a writable byte array');
+    }
+    if (!Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        !Number.isSafeInteger(offset + length) ||
+        offset + length > buffer.length) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('offset', `a non-negative safe integer with ${length} writable bytes`);
+    }
+}
+function validateWork(value, name) {
+    if (typeof value !== 'string' || !HEX_32_BYTES.test(value)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER(name, 'exactly 32 hexadecimal bytes');
+    }
+    return new sdk_1.BigNumber(value, 16);
+}
+function copyBaseHeaderData(value) {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('header', 'a plain data object');
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('header', 'a plain data object');
+    }
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    if (Object.values(descriptors).some(descriptor => descriptor.get != null || descriptor.set != null)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('header', 'accessor-free data properties');
+    }
+    const read = (name) => {
+        const descriptor = descriptors[name];
+        if (descriptor == null || !('value' in descriptor)) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('header', `an own ${name} data property`);
+        }
+        return descriptor.value;
+    };
+    return {
+        version: read('version'),
+        previousHash: read('previousHash'),
+        merkleRoot: read('merkleRoot'),
+        time: read('time'),
+        bits: read('bits'),
+        nonce: read('nonce')
+    };
+}
 /**
  * Computes sha256 hash of file contents read as bytes with no encoding.
  * @param filepath Full filepath to file.
  * @param bufferSize Optional read buffer size to use. Defaults to 80,000 bytes. Currently ignored.
  * @returns `{hash, length}` where `hash` is base64 string form of file hash and `length` is file length in bytes.
  */
-async function sha256HashOfBinaryFile(fs, filepath, _bufferSize = 80000) {
-    const sha256 = new sdk_1.Hash.SHA256();
-    const bytes = await fs.readFile(filepath);
-    const length = bytes.length;
-    sha256.update((0, utilityHelpers_noBuffer_1.asArray)(bytes));
-    return { hash: sdk_1.Utils.toBase64(sha256.digest()), length };
+async function sha256HashOfBinaryFile(fs, filepath, bufferSize = 80000) {
+    if (!Number.isSafeInteger(bufferSize) || bufferSize < 1 || bufferSize > MAX_HEADER_BYTES) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bufferSize', `an integer from 1 through ${MAX_HEADER_BYTES}`);
+    }
+    const hasher = new Hash_1.SHA256();
+    const file = await fs.openReadableFile(filepath);
+    try {
+        const length = await file.getLength();
+        if (!Number.isSafeInteger(length) || length < 0 || length > MAX_HEADER_BYTES) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('file length', `an integer from 0 through ${MAX_HEADER_BYTES}`);
+        }
+        let offset = 0;
+        while (offset < length) {
+            const requested = Math.min(bufferSize, length - offset);
+            const bytes = await file.read(requested, offset);
+            if (!(bytes instanceof Uint8Array) || bytes.length === 0 || bytes.length > requested) {
+                throw new Error('Binary file reader returned an invalid or incomplete chunk.');
+            }
+            hasher.update((0, utilityHelpers_noBuffer_1.asArray)(bytes));
+            offset += bytes.length;
+        }
+        return { hash: (0, utils_1.toBase64)(hasher.digest()), length };
+    }
+    finally {
+        await file.close();
+    }
 }
 /**
  * Validates the contents of a bulk header file.
@@ -56,30 +150,68 @@ async function sha256HashOfBinaryFile(fs, filepath, _bufferSize = 80000) {
  * @returns Validated BulkHeaderFileInfo with `validated` set to true.
  */
 async function validateBulkFileData(bf, prevHash, prevChainWork, fetch) {
+    if (bf == null || typeof bf !== 'object' || Array.isArray(bf)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf', 'a plain data object');
+    }
+    const prototype = Object.getPrototypeOf(bf);
+    const descriptors = Object.getOwnPropertyDescriptors(bf);
+    if ((prototype !== Object.prototype && prototype !== null) ||
+        Object.values(descriptors).some(descriptor => descriptor.get != null || descriptor.set != null)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf', 'an accessor-free plain data object');
+    }
     const vbf = { ...bf };
+    if (!Number.isSafeInteger(vbf.count) || vbf.count <= 0 || vbf.count > MAX_HEADER_COUNT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.count', `an integer from 1 through ${MAX_HEADER_COUNT}`);
+    }
+    if (!Number.isSafeInteger(vbf.firstHeight) || vbf.firstHeight < 0 || vbf.firstHeight > MAX_BLOCK_HEIGHT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.firstHeight', `an integer from 0 through ${MAX_BLOCK_HEIGHT}`);
+    }
+    if (vbf.firstHeight + vbf.count - 1 > MAX_BLOCK_HEIGHT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf', 'a header range within the supported block heights');
+    }
+    if (!['main', 'test', 'stn', 'ttn', 'tstn', 'mock'].includes(vbf.chain)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.chain', 'a supported Chaintracks network');
+    }
+    if (typeof vbf.fileName !== 'string' ||
+        !/^[A-Za-z0-9][A-Za-z0-9._~-]{0,254}$/.test(vbf.fileName) ||
+        vbf.fileName === '.' ||
+        vbf.fileName === '..') {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.fileName', 'a safe path-free ASCII file name');
+    }
+    if (typeof prevHash !== 'string' || !HEX_32_BYTES.test(prevHash)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('prevHash', 'exactly 32 hexadecimal bytes');
+    }
+    validateWork(prevChainWork, 'prevChainWork');
     if (vbf.data == null && vbf.sourceUrl && fetch != null) {
         const url = fetch.pathJoin(vbf.sourceUrl, vbf.fileName);
-        vbf.data = await fetch.download(url);
+        vbf.data = await fetch.download(url, vbf.count * 80);
     }
     if (vbf.data == null)
         throw new WERR_errors_1.WERR_INVALID_OPERATION(`bulk file ${vbf.fileName} data is unavailable`);
-    if (vbf.count <= 0) {
-        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.count', `expected count to be greater than 0, but got ${vbf.count}`);
-    }
+    if (!(vbf.data instanceof Uint8Array))
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.data', 'a Uint8Array');
     if (vbf.data.length !== vbf.count * 80) {
         throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.data', `bulk file ${vbf.fileName} data length ${vbf.data.length} does not match expected count ${vbf.count}`);
     }
-    vbf.fileHash = (0, utilityHelpers_noBuffer_1.asString)(sdk_1.Hash.sha256((0, utilityHelpers_noBuffer_1.asArray)(vbf.data)), 'base64');
+    vbf.fileHash = (0, utilityHelpers_noBuffer_1.asString)((0, Hash_1.sha256)((0, utilityHelpers_noBuffer_1.asArray)(vbf.data)), 'base64');
     if (bf.fileHash && bf.fileHash !== vbf.fileHash) {
         throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.fileHash', `expected ${bf.fileHash} but got ${vbf.fileHash}`);
     }
-    if (!(0, validBulkHeaderFilesByFileHash_1.isKnownValidBulkHeaderFile)(vbf)) {
-        const { lastHeaderHash, lastChainWork } = validateBufferOfHeaders(vbf.data, prevHash, 0, undefined, prevChainWork);
-        vbf.lastHash = lastHeaderHash;
-        vbf.lastChainWork = lastChainWork;
-        if (vbf.firstHeight === 0) {
-            validateGenesisHeader(vbf.data, vbf.chain);
-        }
+    const { lastHeaderHash, lastChainWork } = validateBufferOfHeaders(vbf.data, prevHash, 0, undefined, prevChainWork);
+    if (bf.lastHash &&
+        (typeof bf.lastHash !== 'string' || !HEX_32_BYTES.test(bf.lastHash) || bf.lastHash.toLowerCase() !== lastHeaderHash)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.lastHash', `expected ${bf.lastHash} but got ${lastHeaderHash}`);
+    }
+    if (bf.lastChainWork &&
+        (typeof bf.lastChainWork !== 'string' ||
+            !HEX_32_BYTES.test(bf.lastChainWork) ||
+            bf.lastChainWork.toLowerCase() !== lastChainWork)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bf.lastChainWork', `expected ${bf.lastChainWork} but got ${lastChainWork}`);
+    }
+    vbf.lastHash = lastHeaderHash;
+    vbf.lastChainWork = lastChainWork;
+    if (vbf.firstHeight === 0) {
+        validateGenesisHeader(vbf.data, vbf.chain);
     }
     vbf.validated = true;
     return vbf;
@@ -94,11 +226,32 @@ async function validateBulkFileData(bf, prevHash, prevChainWork, fetch) {
  * @returns Header hash of last header validated or previousHash if there where none.
  */
 function validateBufferOfHeaders(buffer, previousHash, offset = 0, count = -1, previousChainWork) {
-    if (count < 0)
-        count = Math.floor((buffer.length - offset) / 80);
-    count = Math.max(0, count);
-    let lastHeaderHash = previousHash;
+    if (!(buffer instanceof Uint8Array))
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('buffer', 'a Uint8Array');
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > buffer.length) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('offset', 'a non-negative safe integer within the buffer');
+    }
+    if (!Number.isSafeInteger(count) || count < -1 || count > MAX_HEADER_COUNT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('count', `-1 or an integer from 0 through ${MAX_HEADER_COUNT}`);
+    }
+    if (count < 0) {
+        if ((buffer.length - offset) % 80 !== 0) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('buffer', 'a complete sequence of 80-byte headers');
+        }
+        count = (buffer.length - offset) / 80;
+    }
+    if (count > MAX_HEADER_COUNT || offset + count * 80 > buffer.length) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('buffer', 'enough bytes for the bounded requested header count');
+    }
+    if (typeof previousHash !== 'string' || !HEX_32_BYTES.test(previousHash)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('previousHash', 'exactly 32 hexadecimal bytes');
+    }
+    let lastHeaderHash = previousHash.toLowerCase();
     let lastChainWork = previousChainWork;
+    if (lastChainWork !== undefined) {
+        validateWork(lastChainWork, 'previousChainWork');
+        lastChainWork = lastChainWork.toLowerCase();
+    }
     for (let i = 0; i < count; i++) {
         const headerStart = offset + i * 80;
         const headerEnd = headerStart + 80;
@@ -113,6 +266,7 @@ function validateBufferOfHeaders(buffer, previousHash, offset = 0, count = -1, p
         }
         lastHeaderHash = (0, utilityHelpers_noBuffer_1.asString)((0, utilityHelpers_1.doubleSha256BE)(header));
         (0, dirtyHashes_1.validateAgainstDirtyHashes)(lastHeaderHash);
+        validateConsensusProofOfWork(lastHeaderHash, h.bits);
         if (lastChainWork) {
             lastChainWork = addWork(lastChainWork, convertBitsToWork(h.bits));
         }
@@ -144,20 +298,24 @@ function validateGenesisHeader(buffer, chain) {
  * @returns Converted chainWork value from BN to hex string of 32 bytes.
  */
 function workBNtoBuffer(work) {
-    return work.toString(16).padStart(64, '0');
+    const encoded = work.toString(16);
+    if (!/^[0-9a-f]+$/i.test(encoded) || encoded.length > 64) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('work', 'a non-negative integer no greater than 256 bits');
+    }
+    return encoded.toLowerCase().padStart(64, '0');
 }
 /**
  * Returns true if work1 is more work (greater than) work2
  */
 function isMoreWork(work1, work2) {
-    return new sdk_1.BigNumber((0, utilityHelpers_noBuffer_1.asArray)(work1), 16).gt(new sdk_1.BigNumber((0, utilityHelpers_noBuffer_1.asArray)(work2), 16));
+    return validateWork(work1, 'work1').gt(validateWork(work2, 'work2'));
 }
 /**
  * Add two Buffer encoded chainwork values
  * @returns Sum of work1 + work2 as Buffer encoded chainWork value
  */
 function addWork(work1, work2) {
-    const sum = new sdk_1.BigNumber(work1, 16).add(new sdk_1.BigNumber(work2, 16));
+    const sum = validateWork(work1, 'work1').add(validateWork(work2, 'work2'));
     return workBNtoBuffer(sum);
 }
 /**
@@ -165,7 +323,11 @@ function addWork(work1, work2) {
  * @returns work1 - work2 as Buffer encoded chainWork value
  */
 function subWork(work1, work2) {
-    const sum = new sdk_1.BigNumber(work1, 16).sub(new sdk_1.BigNumber(work2, 16));
+    const minuend = validateWork(work1, 'work1');
+    const subtrahend = validateWork(work2, 'work2');
+    if (minuend.lt(subtrahend))
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('work1/work2', 'a non-negative subtraction');
+    const sum = minuend.sub(subtrahend);
     return workBNtoBuffer(sum);
 }
 /**
@@ -174,8 +336,13 @@ function subWork(work1, work2) {
  * @returns 32 byte Buffer with "target" value
  */
 function convertBitsToTarget(bits) {
-    if (Array.isArray(bits))
+    if (Array.isArray(bits)) {
+        if (bits.length !== 4)
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('bits', 'exactly four bytes');
+        validateByteWindow(bits, 0, 4, 'bits');
         bits = readUInt32LE(bits, 0);
+    }
+    validateUnsignedHeaderInteger(bits, 'bits', UINT32_MAX);
     const shift = (bits >> 24) & 0xff;
     const data = bits & 0x007fffff;
     const target = new sdk_1.BigNumber(data);
@@ -187,31 +354,59 @@ function convertBitsToTarget(bits) {
     }
     return target;
 }
+function readCompactBits(bits) {
+    if (bits.length !== 4)
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('bits', 'exactly four bytes');
+    validateByteWindow(bits, 0, 4, 'bits');
+    return readUInt32LE(bits, 0);
+}
 /**
  * Computes "chainWork" value for 4 byte Bitcoin block header "bits" value.
  * @param bits number or converted from Buffer using `readUint32LE`
  * @returns 32 byte Buffer with "chainWork" value
  */
 function convertBitsToWork(bits) {
-    const target = convertBitsToTarget(bits);
+    const encoded = Array.isArray(bits) ? readCompactBits(bits) : bits;
+    const target = validateCompactTarget(encoded);
     // convert target to work
     const work = target.notn(256).div(target.addn(1)).addn(1);
     return work.toString(16).padStart(64, '0');
 }
 function deserializeBaseBlockHeaders(buffer, offset = 0, count) {
+    if (!Array.isArray(buffer) && !(buffer instanceof Uint8Array)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('buffer', 'a byte array');
+    }
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > buffer.length) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('offset', 'a non-negative safe integer within the buffer');
+    }
+    if (count !== undefined && (!Number.isSafeInteger(count) || count < 0 || count > MAX_HEADER_COUNT)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('count', `an integer from 0 through ${MAX_HEADER_COUNT}`);
+    }
+    const available = Math.floor((buffer.length - offset) / 80);
+    const limit = count ?? available;
+    if (Math.min(available, limit) > MAX_HEADER_COUNT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('buffer', `no more than ${MAX_HEADER_COUNT} headers per decode`);
+    }
     const headers = [];
-    while ((!count || headers.length < count) && offset + 80 <= buffer.length && offset >= 0) {
+    while (headers.length < limit && offset + 80 <= buffer.length) {
         headers.push(deserializeBaseBlockHeader(buffer, offset));
         offset += 80;
     }
     return headers;
 }
 function deserializeBlockHeaders(firstHeight, buffer, offset = 0, count) {
+    if (!Number.isSafeInteger(firstHeight) || firstHeight < 0 || firstHeight > MAX_BLOCK_HEIGHT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('firstHeight', `an integer from 0 through ${MAX_BLOCK_HEIGHT}`);
+    }
+    const baseHeaders = deserializeBaseBlockHeaders(buffer, offset, count);
+    if (firstHeight + baseHeaders.length - 1 > MAX_BLOCK_HEIGHT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('headers', 'a range within the supported block heights');
+    }
     const headers = [];
     let nextHeight = firstHeight;
-    while ((!count || headers.length < count) && offset + 80 <= buffer.length && offset >= 0) {
+    while (headers.length < baseHeaders.length) {
         const baseBuffer = buffer.slice(offset, offset + 80);
-        const base = deserializeBaseBlockHeader(baseBuffer);
+        const base = baseHeaders[headers.length];
         const header = {
             ...base,
             height: nextHeight++,
@@ -232,7 +427,7 @@ function deserializeBlockHeaders(firstHeight, buffer, offset = 0, count) {
  *
  * @returns true if the header is correctly formatted
  */
-function validateUnsignedHeaderInteger(value, field, maximum, rangeField = field) {
+function validateUnsignedHeaderInteger(value, field, maximum) {
     if (typeof value !== 'number') {
         throw new TypeError(`Header ${field} must be a number.`);
     }
@@ -240,69 +435,60 @@ function validateUnsignedHeaderInteger(value, field, maximum, rangeField = field
         throw new TypeError(`Header ${field} must be an integer.`);
     }
     if (value < 0 || value > maximum) {
-        throw new Error(`Header ${rangeField} must be between 0 and ${maximum}.`);
+        throw new Error(`Header ${field} must be between 0 and ${maximum}.`);
     }
 }
-function validateHeaderFormat(header) {
-    const ALLOWED_KEYS = {
-        version: true,
-        previousHash: true,
-        merkleRoot: true,
-        time: true,
-        bits: true,
-        nonce: true,
-        height: true,
-        hash: true
-    };
-    const UINT_MAX = 0xffffffff;
-    /**
-     * Root object checks
-     */
-    if (header === undefined) {
+const BASE_HEADER_KEYS = ['version', 'previousHash', 'merkleRoot', 'time', 'bits', 'nonce'];
+const BLOCK_HEADER_KEYS = [...BASE_HEADER_KEYS, 'height', 'hash'];
+function validateHeaderRecord(header, allowedKeys) {
+    if (header == null)
         throw new TypeError('Missing header.');
-    }
-    if (typeof header !== 'object') {
+    if (typeof header !== 'object' || Array.isArray(header)) {
         throw new TypeError('Header must be an object.');
     }
-    if (!Object.keys(header).every(key => key in ALLOWED_KEYS)) {
-        throw new Error('Header contains extra properties.');
+    const prototype = Object.getPrototypeOf(header);
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError('Header must be a plain data object.');
     }
-    /**
-     * Version
-     */
+    const descriptors = Object.getOwnPropertyDescriptors(header);
+    const keys = Object.keys(descriptors);
+    if (keys.length !== allowedKeys.length ||
+        !keys.every(key => allowedKeys.includes(key)) ||
+        keys.some(key => descriptors[key]?.get != null || descriptors[key]?.set != null)) {
+        throw new Error('Header must contain exactly the required data properties.');
+    }
+}
+/**
+ * Validates the exact data representation of an unpositioned 80-byte block
+ * header before it reaches a chain lookup, queue, or serializer.
+ */
+function validateBaseBlockHeaderFormat(header) {
+    const UINT_MAX = 0xffffffff;
+    validateHeaderRecord(header, BASE_HEADER_KEYS);
     validateUnsignedHeaderInteger(header.version, 'version', UINT_MAX);
-    /**
-     * Height
-     */
-    validateUnsignedHeaderInteger(header.height, 'height', UINT_MAX / 2, 'version');
-    /**
-     * Previous hash
-     */
-    if (header.previousHash.length !== 64) {
+    if (typeof header.previousHash !== 'string' || !HEX_32_BYTES.test(header.previousHash)) {
         throw new Error('Header previousHash must be 32 hex bytes.');
     }
-    /**
-     * Merkle root
-     */
-    if (header.merkleRoot.length !== 64) {
+    if (typeof header.merkleRoot !== 'string' || !HEX_32_BYTES.test(header.merkleRoot)) {
         throw new Error('Header merkleRoot must be 32 hex bytes.');
     }
-    /**
-     * Time
-     */
     validateUnsignedHeaderInteger(header.time, 'time', UINT_MAX);
-    /**
-     * Bits
-     */
     validateUnsignedHeaderInteger(header.bits, 'bits', UINT_MAX);
-    /**
-     * Nonce
-     */
     validateUnsignedHeaderInteger(header.nonce, 'nonce', UINT_MAX);
-    /**
-     * Hash
-     */
-    if (header.hash.length !== 64) {
+}
+function validateHeaderFormat(header) {
+    validateHeaderRecord(header, BLOCK_HEADER_KEYS);
+    const baseHeader = {
+        version: header.version,
+        previousHash: header.previousHash,
+        merkleRoot: header.merkleRoot,
+        time: header.time,
+        bits: header.bits,
+        nonce: header.nonce
+    };
+    validateBaseBlockHeaderFormat(baseHeader);
+    validateUnsignedHeaderInteger(header.height, 'height', 0x7fffffff);
+    if (typeof header.hash !== 'string' || !HEX_32_BYTES.test(header.hash)) {
         throw new Error('Header hash must be 32 hex bytes.');
     }
     if (header.hash !== (0, utilityHelpers_noBuffer_1.asString)(blockHash(header))) {
@@ -310,20 +496,66 @@ function validateHeaderFormat(header) {
     }
 }
 /**
- * Ensures that a header has a valid proof-of-work
- * Requires chain is 'main'
+ * Ensures that a header has a valid proof-of-work target and hash.
  *
  * @param header The header to validate
  *
  * @returns true if the header is valid
  */
 function validateHeaderDifficulty(hash, bits) {
+    if (!Array.isArray(hash) && !(hash instanceof Uint8Array)) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('hash', 'exactly 32 bytes');
+    }
+    validateByteWindow(hash, 0, hash.length, 'hash');
+    if (hash.length !== 32)
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('hash', 'exactly 32 bytes');
     const hashBN = new sdk_1.BigNumber((0, utilityHelpers_noBuffer_1.asArray)(hash));
-    const target = convertBitsToTarget(bits);
+    const target = validateCompactTarget(bits);
     if (hashBN.lte(target))
         return true;
     throw new Error('Block hash is not less than specified target.');
 }
+const proofOfWorkExceptions = new Map([
+    // The historical STN genesis header is a network-defined bootstrap
+    // checkpoint whose hash does not satisfy its encoded target. No later
+    // header receives this exception.
+    ['6b38bdbcd73a19f7889d23e1fa6166a9de71affceca60ca3bb1b28af8135c594', 0x1d00ffff]
+]);
+function validateConsensusProofOfWork(hash, bits) {
+    if (proofOfWorkExceptions.get(hash) === bits)
+        return;
+    validateHeaderDifficulty((0, utilityHelpers_noBuffer_1.asArray)(hash, 'hex'), bits);
+}
+function validateCompactTarget(bits) {
+    if (!Number.isSafeInteger(bits) || bits < 0 || bits > 0xffffffff) {
+        throw new Error('Block target encoding is invalid.');
+    }
+    const size = bits >>> 24;
+    const word = bits & 0x007fffff;
+    const negative = word !== 0 && (bits & 0x00800000) !== 0;
+    const overflow = word !== 0 && (size > 34 || (word > 0xff && size > 33) || (word > 0xffff && size > 32));
+    if (word === 0 || negative || overflow) {
+        throw new Error('Block target encoding is invalid.');
+    }
+    const target = convertBitsToTarget(bits);
+    const proofOfWorkLimit = convertBitsToTarget(0x1d00ffff);
+    if (target.gt(proofOfWorkLimit)) {
+        throw new Error('Block target exceeds the proof-of-work limit.');
+    }
+    return target;
+}
+/**
+ * Ensures that a structured header's computed hash satisfies its declared
+ * proof-of-work target.
+ *
+ * @param header Header whose format and hash have already been checked.
+ * @returns true if the header has valid proof-of-work.
+ * @publicbody
+ */
+function validateHeaderProofOfWork(header) {
+    validateConsensusProofOfWork(header.hash, header.bits);
+    return true;
+}
 /**
  * Computes double sha256 hash of bitcoin block header
  * bytes are reversed to bigendian order
@@ -349,32 +581,39 @@ function blockHash(header) {
  * @publicbody
  */
 function serializeBaseBlockHeader(header, buffer, offset) {
-    const writer = new sdk_1.Utils.Writer();
-    writer.writeUInt32LE(header.version);
-    writer.write((0, utilityHelpers_noBuffer_1.asArray)(header.previousHash).reverse());
-    writer.write((0, utilityHelpers_noBuffer_1.asArray)(header.merkleRoot).reverse());
-    writer.writeUInt32LE(header.time);
-    writer.writeUInt32LE(header.bits);
-    writer.writeUInt32LE(header.nonce);
+    const validated = copyBaseHeaderData(header);
+    validateBaseBlockHeaderFormat(validated);
+    const writer = new utils_1.Writer();
+    writer.writeUInt32LE(validated.version);
+    writer.write((0, utilityHelpers_noBuffer_1.asArray)(validated.previousHash).reverse());
+    writer.write((0, utilityHelpers_noBuffer_1.asArray)(validated.merkleRoot).reverse());
+    writer.writeUInt32LE(validated.time);
+    writer.writeUInt32LE(validated.bits);
+    writer.writeUInt32LE(validated.nonce);
     const data = writer.toArray();
     if (buffer != null) {
-        offset ||= 0;
+        if (!Array.isArray(buffer))
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('buffer', 'an array');
+        offset ??= 0;
+        if (!Number.isSafeInteger(offset) || offset < 0 || offset + data.length > buffer.length) {
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('offset', 'a non-negative safe integer with 80 writable bytes');
+        }
         for (let i = 0; i < data.length; i++) {
-            if (offset + i >= buffer.length) {
-                throw new Error(`Buffer overflow at offset ${offset + i} for data length ${data.length}`);
-            }
             buffer[offset + i] = data[i];
         }
     }
     return data;
 }
 function serializeBaseBlockHeaders(headers) {
+    if (!Array.isArray(headers) || headers.length > MAX_HEADER_COUNT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('headers', `a dense array of no more than ${MAX_HEADER_COUNT} entries`);
+    }
     const data = new Uint8Array(headers.length * 80);
-    let i = -1;
-    for (const header of headers) {
-        i++;
-        const d = serializeBaseBlockHeader(header);
-        data.set(d, i * 80);
+    for (let index = 0; index < headers.length; index++) {
+        if (!Object.hasOwn(headers, index))
+            throw new WERR_errors_1.WERR_INVALID_PARAMETER('headers', 'a dense array');
+        const d = serializeBaseBlockHeader(headers[index]);
+        data.set(d, index * 80);
     }
     return data;
 }
@@ -383,7 +622,8 @@ function serializeBaseBlockHeaders(headers) {
  * @publicbody
  */
 function deserializeBaseBlockHeader(buffer, offset = 0) {
-    const reader = sdk_1.Utils.ReaderUint8Array.makeReader(buffer, offset);
+    validateByteWindow(buffer, offset, 80);
+    const reader = utils_1.ReaderUint8Array.makeReader(buffer, offset);
     const header = {
         version: reader.readUInt32LE(),
         previousHash: (0, utilityHelpers_noBuffer_1.asString)(reader.read(32).reverse()),
@@ -395,6 +635,9 @@ function deserializeBaseBlockHeader(buffer, offset = 0) {
     return header;
 }
 function deserializeBlockHeader(buffer, height, offset = 0) {
+    if (!Number.isSafeInteger(height) || height < 0 || height > MAX_BLOCK_HEIGHT) {
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('height', `an integer from 0 through ${MAX_BLOCK_HEIGHT}`);
+    }
     const base = deserializeBaseBlockHeader(buffer, offset);
     const header = {
         ...base,
@@ -492,6 +735,9 @@ function swapByteOrder(buffer) {
  * @publicbody
  */
 function convertUint32ToBuffer(n, littleEndian = true) {
+    validateUnsignedHeaderInteger(n, 'uint32', UINT32_MAX);
+    if (typeof littleEndian !== 'boolean')
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('littleEndian', 'a boolean');
     const a = [
         n & 0xff, // lowest byte
         (n >> 8) & 0xff,
@@ -501,6 +747,8 @@ function convertUint32ToBuffer(n, littleEndian = true) {
     return littleEndian ? a : a.reverse();
 }
 function writeUInt32LE(n, a, offset) {
+    validateUnsignedHeaderInteger(n, 'uint32', UINT32_MAX);
+    validateWritableByteWindow(a, offset, 4);
     a[offset++] = n & 0xff; // lowest byte
     a[offset++] = (n >> 8) & 0xff;
     a[offset++] = (n >> 16) & 0xff;
@@ -508,6 +756,8 @@ function writeUInt32LE(n, a, offset) {
     return offset;
 }
 function writeUInt32BE(n, a, offset) {
+    validateUnsignedHeaderInteger(n, 'uint32', UINT32_MAX);
+    validateWritableByteWindow(a, offset, 4);
     a[offset++] = (n >> 24) & 0xff; // highest byte
     a[offset++] = (n >> 16) & 0xff;
     a[offset++] = (n >> 8) & 0xff;
@@ -515,10 +765,12 @@ function writeUInt32BE(n, a, offset) {
     return offset;
 }
 function readUInt32LE(a, offset) {
-    return a[offset++] | (a[offset++] << 8) | (a[offset++] << 16) | (a[offset++] << 24);
+    validateByteWindow(a, offset, 4);
+    return (a[offset++] | (a[offset++] << 8) | (a[offset++] << 16) | (a[offset++] << 24)) >>> 0;
 }
 function readUInt32BE(a, offset) {
-    return (a[offset++] << 24) | (a[offset++] << 16) | (a[offset++] << 8) | a[offset++];
+    validateByteWindow(a, offset, 4);
+    return ((a[offset++] << 24) | (a[offset++] << 16) | (a[offset++] << 8) | a[offset++]) >>> 0;
 }
 /**
  * @param buffer four byte buffer with Uint32 number encoded
@@ -527,8 +779,13 @@ function readUInt32BE(a, offset) {
  * @publicbody
  */
 function convertBufferToUint32(buffer, littleEndian = true) {
+    validateByteWindow(buffer, 0, 4);
+    if (buffer.length !== 4)
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('buffer', 'exactly four bytes');
+    if (typeof littleEndian !== 'boolean')
+        throw new WERR_errors_1.WERR_INVALID_PARAMETER('littleEndian', 'a boolean');
     const a = littleEndian ? buffer : buffer.slice().reverse();
-    const n = a[0] | (a[1] << 8) | (a[2] << 16) | (a[3] << 24);
+    const n = (a[0] | (a[1] << 8) | (a[2] << 16) | (a[3] << 24)) >>> 0;
     return n;
 }
 //# sourceMappingURL=blockHeaderUtilities.js.map