Refuse unsafe MWEB CompactSize values and trailing transaction bytes with a typed parse error

transactionFromHex now consumes exactly the bytes it is given and wraps every wire-parse failure, in it and in the block path, in TransactionParseError, and the MWEB CompactSize reader refuses values above Number.MAX_SAFE_INTEGER. Fixed node-txid vectors, truncation and trailing-byte cases, and a mempool containment test cover the change, and the parse fuzz harness accepts the typed error by its code.

Author: jdogresorg

src/chain/XChainBlockDecoder.js

@@ -19,6 +19,19 @@ const coins = require('../coins');
 const LITECOIN_HOGEX_FLAG = 0x08
 const LITECOIN_MWEB_SEGWIT_FLAG = 0x09
 
+class TransactionParseError extends Error {
+    constructor(message, cause) {
+        super(message, cause ? { cause } : undefined)
+        this.name = 'TransactionParseError'
+        this.code = 'ERR_TRANSACTION_PARSE'
+    }
+}
+
+function transactionParseError(message, cause) {
+    if (cause instanceof TransactionParseError) return cause
+    return new TransactionParseError(message, cause)
+}
+
 // Block/tx wire-serialization families this decoder actually implements. The
 // per-coin branches below (Litecoin 'mweb' MWEB-flagged tx reading, Dogecoin
 // 'auxpow' handled upstream in BlockchainConnector.getBlockWithoutAuxPow,
@@ -56,7 +69,11 @@ function readMwebCompactSize(buf, offset, what) {
     const end = skipMwebBytes(buf, offset + 1, width, what)
     if (width === 2) return { value: buf.readUInt16LE(offset + 1), end }
     if (width === 4) return { value: buf.readUInt32LE(offset + 1), end }
-    return { value: Number(buf.readBigUInt64LE(offset + 1)), end }
+    const value = buf.readBigUInt64LE(offset + 1)
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new TransactionParseError('MWEB tx parse: ' + what + ' exceeds Number.MAX_SAFE_INTEGER')
+    }
+    return { value: Number(value), end }
 }
 
 function skipMwebVarBytes(buf, offset, what) {
@@ -209,6 +226,10 @@ function readMwebTransactions(bufferReader, block) {
 
 class XChainBlockDecoder {
 
+    // Callers tell a wire-parse failure apart by this class, reached through the one
+    // export, so the module keeps a single export shape.
+    static TransactionParseError = TransactionParseError
+
     constructor(networkName) {
         let networkNameSplit = networkName.split("-")
         this.coin = networkNameSplit[0]
@@ -227,14 +248,28 @@ class XChainBlockDecoder {
     }
 
     transactionFromHex(txHex){
-        const buffer = Buffer.from(txHex, "hex")
-        if (this.wireFormat === "mweb" && hasMwebFlag(buffer, 0)) {
-            // Litecoin's getrawtransaction answers in the MWEB serialization when the
-            // tx has an MWEB part; bitcoinjs cannot read that flag, so read it here.
-            return readMwebFlaggedTransaction(buffer, 0, true).tx
+        try {
+            if (typeof txHex !== 'string' || txHex.length === 0 || (txHex.length % 2) !== 0 || !/^[0-9a-fA-F]+$/.test(txHex)) {
+                throw new TransactionParseError('Transaction hex must be a non-empty, even-length hexadecimal string')
+            }
+            const buffer = Buffer.from(txHex, "hex")
+            if (this.wireFormat === "mweb" && hasMwebFlag(buffer, 0)) {
+                // Litecoin's getrawtransaction answers in the MWEB serialization when the
+                // tx has an MWEB part; bitcoinjs cannot read that flag, so read it here.
+                const parsed = readMwebFlaggedTransaction(buffer, 0, true)
+                if (parsed.consumed !== buffer.length) {
+                    throw new TransactionParseError('Transaction has ' + (buffer.length - parsed.consumed) + ' trailing byte(s)')
+                }
+                return parsed.tx
+            }
+            const tx = transaction_js_1.Transaction.fromBuffer(buffer, true)
+            if (tx.byteLength() !== buffer.length) {
+                throw new TransactionParseError('Transaction has ' + (buffer.length - tx.byteLength()) + ' trailing byte(s)')
+            }
+            return tx
+        } catch (err) {
+            throw transactionParseError('Transaction parse failed: ' + (err && err.message ? err.message : err), err)
         }
-        // Non-strict mode ignores any bytes after the tx.
-        return transaction_js_1.Transaction.fromBuffer(buffer, true)
     }
 
     doubleSha256AndReverse(data){
@@ -261,14 +296,24 @@ class XChainBlockDecoder {
                 block.bits = bufferReader.readUInt32();
                 block.nonce = bufferReader.readUInt32();
                 if (buffer.length === 80) return block;
-                const extensionFollows = readMwebTransactions(bufferReader, block)
+                let extensionFollows
+                try {
+                    extensionFollows = readMwebTransactions(bufferReader, block)
+                } catch (err) {
+                    throw transactionParseError('Block transaction parse failed: ' + (err && err.message ? err.message : err), err)
+                }
                 assertBlockBodyIntact(block, buffer.length, bufferReader.offset, extensionFollows)
                 const witnessCommit = block.getWitnessCommit();
                 // This Block contains a witness commit
                 if (witnessCommit) block.witnessCommit = witnessCommit;
                 return block;
             default: {
-                const plainBlock = bitcoinjs.Block.fromBuffer(buffer)
+                let plainBlock
+                try {
+                    plainBlock = bitcoinjs.Block.fromBuffer(buffer)
+                } catch (err) {
+                    throw transactionParseError('Block transaction parse failed: ' + (err && err.message ? err.message : err), err)
+                }
                 // An 80-byte buffer is a header-only parse, with no body to check.
                 if (buffer.length === 80) return plainBlock
                 assertBlockBodyIntact(plainBlock, buffer.length, plainBlock.byteLength(), false)

test/fixtures/decoder_parse_vectors.json

@@ -0,0 +1,12 @@
+{
+  "bitcoinGenesisCoinbase": {
+    "form": "legacy",
+    "txid": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
+    "hex": "01000000010000000000000000000000000000000000000000000000000000000000000000ffffffff4d04ffff001d0104455468652054696d65732030332f4a616e2f32303039204368616e63656c6c6f72206f6e206272696e6b206f66207365636f6e64206261696c6f757420666f722062616e6b73ffffffff0100f2052a01000000434104678afdb0fe5548271967f1a67130b7105cd6a828e03909a67962e0ea1f61deb649f6bc3f4cef38c4f35504e51ec112de5c384df7ba0b8d578a4c702b6bf11d5fac00000000"
+  },
+  "taprootWitnessSpend": {
+    "form": "segwit-v1",
+    "txid": "065e8cd3378b9925feee408ae9e5f58e5bba75e8d7682a7fbcf230a3b435f7bb",
+    "hex": "0200000000010111111111111111111111111111111111111111111111111111111111111111110300000000fdffffff013930000000000000225120222222222222222222222222222222222222222222222222222222222222222201403333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333340d10c00"
+  }
+}

test/fuzz/harness/parse_transaction.fuzz/support.cjs

@@ -44,8 +44,12 @@ function createDecoder() {
 }
 
 // Errors thrown by bitcoinjs-lib during Transaction.fromHex/fromBuffer are expected
-// when we feed it corrupted hex. These are not decoder bugs.
+// when we feed it corrupted hex. These are not decoder bugs. transactionFromHex
+// refuses malformed, truncated and trailing-byte hex with a TransactionParseError,
+// keyed here on its code rather than its message, so a refusal stops counting as
+// expected the moment the decoder stops typing it.
 function isBitcoinjsParseError(err) {
+    if (err != null && err.code === 'ERR_TRANSACTION_PARSE') return true
     const msg = err.message || ''
     return msg.includes('Cannot read slice out of bounds') ||
            msg.includes('Transaction has unexpected data') ||

test/unit/wire_parse/mempool_node_txid.test.js

@@ -71,5 +71,14 @@ describe('decoder mempool rows keyed on the node txid @regression', function ()
             assert.deepStrictEqual(seen.parsed, [])
             assert.strictEqual(decoder.parseErrors, before + 1)
         })
+
+        it('handles a typed malformed-transaction error without aborting the mempool cycle', async function () {
+            const { decoder, seen } = buildDecoder('cd'.repeat(32), 'not-hex')
+            const before = decoder.parseErrors
+            await decoder.updateMempool()
+            assert.deepStrictEqual(seen.rows, [])
+            assert.deepStrictEqual(seen.parsed, [])
+            assert.strictEqual(decoder.parseErrors, before + 1)
+        })
     })
 })

test/unit/wire_parse/transaction_parse_conformance.test.js

@@ -0,0 +1,188 @@
+// Copyright © 2025–2026 Dankest, LLC
+// Based on XChain Platform by Dankest, LLC – https://dankest.llc
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+'use strict'
+
+const assert = require('assert')
+const bitcoin = require('bitcoinjs-lib')
+const ecc = require('tiny-secp256k1')
+const XChainDecoder = require('../../../src/XChainDecoder')
+const XChainBlockDecoder = require('../../../src/chain/XChainBlockDecoder')
+const CryptoNetworks = require('../../../src/chain/crypto_networks')
+const NEW_VECTORS = require('../../fixtures/decoder_parse_vectors.json')
+const WIRE_VECTORS = require('../../fixtures/wire_parse_vectors.json')
+
+bitcoin.initEccLib(ecc)
+
+const P2PKH = Buffer.from('76a914' + '11'.repeat(20) + '88ac', 'hex')
+const P2SH = Buffer.from('a914' + '22'.repeat(20) + '87', 'hex')
+const P2WPKH = Buffer.from('0014' + '33'.repeat(20), 'hex')
+const P2WSH = Buffer.from('0020' + '44'.repeat(32), 'hex')
+const P2TR = Buffer.from('5120' + '22'.repeat(32), 'hex')
+
+describe('transaction wire parsing conformance', function () {
+    it('matches node txids for legacy, segwit v0, taproot v1, LTC MWEB and DOGE coinbase forms', function () {
+        const forms = [
+            ['bitcoin-mainnet', NEW_VECTORS.bitcoinGenesisCoinbase],
+            ['bitcoin-mainnet', WIRE_VECTORS.ltcPegin],
+            ['bitcoin-mainnet', NEW_VECTORS.taprootWitnessSpend],
+            ['litecoin-mainnet', WIRE_VECTORS.ltcHogEx3195200],
+            ['dogecoin-mainnet', { hex: WIRE_VECTORS.doge4500000.txs[0], txid: WIRE_VECTORS.doge4500000.txids[0] }],
+        ]
+
+        for (const [network, vector] of forms) {
+            assert.strictEqual(new XChainBlockDecoder(network).transactionFromHex(vector.hex).getId(), vector.txid)
+        }
+    })
+
+    it('rejects truncated, non-hex and trailing bytes with a typed error', function () {
+        const decoder = new XChainBlockDecoder('bitcoin-mainnet')
+        const valid = NEW_VECTORS.taprootWitnessSpend.hex
+        const malformed = [
+            '',
+            '0',
+            'zz',
+            valid.slice(0, -2),
+            valid + '00',
+        ]
+
+        for (const hex of malformed) {
+            assert.throws(
+                () => decoder.transactionFromHex(hex),
+                err => err instanceof XChainBlockDecoder.TransactionParseError && err.code === 'ERR_TRANSACTION_PARSE'
+            )
+        }
+    })
+
+    it('rejects an MWEB CompactSize above 2^53 before using it as a length', function () {
+        // version 2, MWEB flag 0x08, then input-count CompactSize 2^53.
+        const unsafeInputCount = '020000000008ff0000000000002000'
+        assert.throws(
+            () => new XChainBlockDecoder('litecoin-mainnet').transactionFromHex(unsafeInputCount),
+            err => err instanceof XChainBlockDecoder.TransactionParseError &&
+                /exceeds Number\.MAX_SAFE_INTEGER/.test(err.message)
+        )
+    })
+})
+
+describe('transaction wire parsing conformance', function () {
+    it('bounds-checks every truncation of a fixed MWEB transaction', function () {
+        const decoder = new XChainBlockDecoder('litecoin-mainnet')
+        const valid = WIRE_VECTORS.ltcHogEx3195200.hex
+        for (let end = 0; end < valid.length; end += 2) {
+            assert.throws(
+                () => decoder.transactionFromHex(valid.slice(0, end)),
+                err => err instanceof XChainBlockDecoder.TransactionParseError
+            )
+        }
+        assert.throws(
+            () => decoder.transactionFromHex(valid + '00'),
+            err => err instanceof XChainBlockDecoder.TransactionParseError && /trailing byte/.test(err.message)
+        )
+    })
+
+    it('types a truncated transaction inside a block for the block-loop caller', function () {
+        const block = Buffer.concat([
+            Buffer.from(WIRE_VECTORS.doge4500000.header, 'hex'),
+            Buffer.from([WIRE_VECTORS.doge4500000.txs.length]),
+            ...WIRE_VECTORS.doge4500000.txs.map(hex => Buffer.from(hex, 'hex')),
+        ])
+        assert.throws(
+            () => new XChainBlockDecoder('dogecoin-mainnet').blockFromBuffer(block.subarray(0, -1)),
+            err => err instanceof XChainBlockDecoder.TransactionParseError && err.code === 'ERR_TRANSACTION_PARSE'
+        )
+    })
+})
+
+// The addresses each network derives for P2PKH, P2SH, P2WPKH, P2WSH and P2TR, in
+// that order; DOGE has no witness outputs, so it lists only the first two.
+const EXPECTED_ADDRESSES = {
+    'bitcoin-mainnet': [
+        '12ZEw5Hcv1hTb6YUQJ69y1V7uhcoDz92PH',
+        '34oVnh4gNviJGMnNvgquMeLAxvXJuaRVMZ',
+        'bc1qxvenxvenxvenxvenxvenxvenxvenxven2ymjt8',
+        'bc1qg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zqd8sxw4',
+        'bc1pyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3qfpjpqe',
+    ],
+    'bitcoin-testnet': [
+        'mh5CE8Nbj38iND267s4XnvhSmhDW7yWc6Q',
+        '2MvMhrRzhzPDeU9QvbpTmybKSBGjUmC6TTu',
+        'tb1qxvenxvenxvenxvenxvenxvenxvenxvenqzqps5',
+        'tb1qg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zq60xf56',
+        'tb1pyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3q7fyw6k',
+    ],
+    'bitcoin-regtest': [
+        'mh5CE8Nbj38iND267s4XnvhSmhDW7yWc6Q',
+        '2MvMhrRzhzPDeU9QvbpTmybKSBGjUmC6TTu',
+        'bcrt1qxvenxvenxvenxvenxvenxvenxvenxvenztev8a',
+        'bcrt1qg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zqhkv0pq',
+        'bcrt1pyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3qnswg0v',
+    ],
+    'litecoin-mainnet': [
+        'LLnCCHbSzfwWquEdaS5TF2Yt7uz5Qb1SZ1',
+        'MB1e6aUeL3Zj4s4H2ZqFBHaaHd7kvvzTco',
+        'ltc1qxvenxvenxvenxvenxvenxvenxvenxvenwcpknh',
+        'ltc1qg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zqwr7k5s',
+        'ltc1pyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3q29u36u',
+    ],
+    'litecoin-testnet': [
+        'mh5CE8Nbj38iND267s4XnvhSmhDW7yWc6Q',
+        '2MvMhrRzhzPDeU9QvbpTmybKSBGjUmC6TTu',
+        'tltc1qxvenxvenxvenxvenxvenxvenxvenxvene2zlqa',
+        'tltc1qg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zq9v6gt9',
+        'tltc1pyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3qp2c09f',
+    ],
+    'litecoin-regtest': [
+        'mh5CE8Nbj38iND267s4XnvhSmhDW7yWc6Q',
+        '2MvMhrRzhzPDeU9QvbpTmybKSBGjUmC6TTu',
+        'rltc1qxvenxvenxvenxvenxvenxvenxvenxvenuxr9sr',
+        'rltc1qg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zql4xswd',
+        'rltc1pyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg3qmnyhqp',
+    ],
+    'dogecoin-mainnet': [
+        'D6hLULEGDRbk86j58t5iWmeinqM6acA16V',
+        '9uYkXY8aSzbCAj9rLpWKbmxYfVuM33MqfZ',
+    ],
+    'dogecoin-testnet': [
+        'nVkQCLyB9Q4U15JGAhjAmBF22hjPYUwj3w',
+        '2MvMhrRzhzPDeU9QvbpTmybKSBGjUmC6TTu',
+    ],
+    'dogecoin-regtest': [
+        'mh5CE8Nbj38iND267s4XnvhSmhDW7yWc6Q',
+        '2MvMhrRzhzPDeU9QvbpTmybKSBGjUmC6TTu',
+    ],
+}
+
+async function assertNetworkAddresses(network, addresses) {
+    const decoder = new XChainDecoder(
+        network, null, null, null, null, null,
+        '127.0.0.1', 0, null, null, false
+    )
+    const tx = new bitcoin.Transaction()
+    tx.addInput(Buffer.alloc(32, 1), 0)
+    const scripts = network.startsWith('dogecoin')
+        ? [P2PKH, P2SH]
+        : [P2PKH, P2SH, P2WPKH, P2WSH, P2TR]
+    for (const script of scripts) tx.addOutput(script, 1)
+
+    const parsed = await decoder.parseTransaction(tx, new Set())
+    assert.deepStrictEqual(parsed.paymentOutputs.map(output => output.destinationAddress), addresses)
+
+    if (!network.startsWith('dogecoin')) {
+        assert.strictEqual(bitcoin.address.fromOutputScript(P2WPKH, CryptoNetworks.getBitcoinJsNetwork(network)), addresses[2])
+        assert.strictEqual(bitcoin.address.fromOutputScript(P2TR, CryptoNetworks.getBitcoinJsNetwork(network)), addresses[4])
+    } else {
+        assert.throws(() => bitcoin.address.fromOutputScript(P2WPKH, CryptoNetworks.getBitcoinJsNetwork(network)))
+        assert.throws(() => bitcoin.address.fromOutputScript(P2TR, CryptoNetworks.getBitcoinJsNetwork(network)))
+    }
+}
+
+describe('output address derivation conformance', function () {
+    for (const [network, addresses] of Object.entries(EXPECTED_ADDRESSES)) {
+        it(network + ' derives the coin prefixes and witness checksum variant', async function () {
+            await assertNetworkAddresses(network, addresses)
+        })
+    }
+})