@smartledger/bsv 8.2.0 → 8.3.0

package/test/notaryhash/certificate.js

@@ -0,0 +1,249 @@
+'use strict'
+
+/* global describe, it */
+
+// BRC-220 certificate. This is validity check 2 of the three the spec requires — proof
+// integrity — plus the object a verifier is actually handed.
+//
+// The tests below concentrate on three things the spec makes explicit and that would fail
+// silently if got wrong: the certificate carries FULL blobs even when the chain carries
+// digests; the SPV envelope never disturbs proofHash; and proofHash is over the binary
+// proof bytes, NOT over the certificate JSON.
+
+require('chai').should()
+var Certificate = require('../../lib/notaryhash/certificate')
+var Encoding = require('../../lib/notaryhash/encoding')
+var NS = require('../../lib/notaryhash/script')
+var Hash = require('../../lib/crypto/hash')
+var JCS = require('../../lib/util/jcs')
+
+var PARAMS = {
+  mode: NS.MODE.FULL,
+  algorithm: 'ECDSA-secp256k1',
+  hashAlgorithm: 'SHA-256',
+  payloadHash: Buffer.alloc(32, 0x11),
+  publicKey: Buffer.alloc(33, 0x02),
+  signature: Buffer.alloc(64, 0x30),
+  createdAt: '2026-08-16T00:00:00.000Z',
+  anchor: { txid: 'ab'.repeat(32), blockHeight: 800000 }
+}
+
+var SPV = {
+  rawTx: 'deadbeef',
+  blockHash: 'cc'.repeat(32),
+  blockHeight: 800000,
+  merkleProof: { index: 0, nodes: ['aa'.repeat(32), '*'] }
+}
+
+describe('BRC-220 certificate', function () {
+  describe('build', function () {
+    it('carries every field the spec requires', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.REQUIRED_FIELDS.forEach(function (field) {
+        ;(cert[field] === undefined).should.equal(false, 'missing ' + field)
+      })
+    })
+
+    it('defaults encoding to raw', function () {
+      Certificate.build(PARAMS).encoding.should.equal('raw')
+    })
+
+    it('accepts der for Bitcoin-native signers', function () {
+      Certificate.build(Object.assign({}, PARAMS, { encoding: 'der' })).encoding.should.equal('der')
+    })
+
+    it('rejects an unknown encoding rather than passing it through', function () {
+      ;(function () {
+        Certificate.build(Object.assign({}, PARAMS, { encoding: 'base64' }))
+      }).should.throw(/encoding must be/)
+    })
+
+    it('hex-encodes the byte fields', function () {
+      var cert = Certificate.build(PARAMS)
+      cert.payloadHash.should.equal(PARAMS.payloadHash.toString('hex'))
+      cert.publicKey.should.equal(PARAMS.publicKey.toString('hex'))
+      cert.signature.should.equal(PARAMS.signature.toString('hex'))
+    })
+
+    // proofHash is computed, never accepted. A caller cannot hand in a value that
+    // disagrees with the fields beside it — which is precisely the artefact this protocol
+    // exists to make impossible.
+    it('computes proofHash rather than accepting one', function () {
+      var cert = Certificate.build(Object.assign({}, PARAMS, { proofHash: 'ff'.repeat(32) }))
+      cert.proofHash.should.not.equal('ff'.repeat(32))
+      Certificate.proofHashMatches(cert).should.equal(true)
+    })
+
+    it('requires a merkle proof for batch mode', function () {
+      ;(function () {
+        Certificate.build(Object.assign({}, PARAMS, { mode: NS.MODE.BATCH }))
+      }).should.throw(/merkle/)
+    })
+
+    it('carries the merkle proof when batched', function () {
+      var cert = Certificate.build(Object.assign({}, PARAMS, {
+        mode: NS.MODE.BATCH,
+        merkle: { root: 'aa'.repeat(32), leafIndex: 2, leafCount: 8, path: [] }
+      }))
+      cert.merkle.leafIndex.should.equal(2)
+      cert.merkle.leafCount.should.equal(8)
+    })
+
+    // Hybrid puts only digests on chain; the certificate keeps the originals. That
+    // asymmetry is the whole point of the mode.
+    it('keeps the FULL key and signature in hybrid mode', function () {
+      var cert = Certificate.build(Object.assign({}, PARAMS, { mode: NS.MODE.HYBRID }))
+      cert.publicKey.should.equal(PARAMS.publicKey.toString('hex'))
+      cert.signature.should.equal(PARAMS.signature.toString('hex'))
+      // What goes on chain is the digest of each — different values entirely.
+      var onChain = NS.parse(NS.build(Object.assign({}, PARAMS, { mode: NS.MODE.HYBRID, proofHash: Buffer.alloc(32) })))
+      onChain.publicKeyHash.toString('hex').should.equal(Hash.sha256(PARAMS.publicKey).toString('hex'))
+      onChain.publicKeyHash.toString('hex').should.not.equal(cert.publicKey)
+    })
+  })
+
+  describe('proof integrity (validity check 2)', function () {
+    it('matches for a well-formed certificate', function () {
+      Certificate.proofHashMatches(Certificate.build(PARAMS)).should.equal(true)
+    })
+
+    // Each field is inside the canonical proof bytes, so tampering with any of them must
+    // be detected. This is the certificate-level counterpart of the encoding module's
+    // coverage test.
+    it('detects tampering with any covered field', function () {
+      var cert = Certificate.build(PARAMS)
+      var tampers = {
+        algorithm: 'ML-DSA-65',
+        hashAlgorithm: 'SHA-512',
+        payloadHash: 'ff'.repeat(32),
+        publicKey: '03' + '11'.repeat(32),
+        signature: 'aa'.repeat(64),
+        createdAt: '2026-08-17T00:00:00.000Z'
+      }
+      Object.keys(tampers).forEach(function (field) {
+        var bad = Object.assign({}, cert)
+        bad[field] = tampers[field]
+        Certificate.proofHashMatches(bad)
+          .should.equal(false, 'tampering with ' + field + ' was not detected')
+      })
+    })
+
+    // Fields NOT in the canonical proof bytes must not affect it — otherwise the SPV
+    // envelope could not be additive.
+    it('is unaffected by fields outside the canonical bytes', function () {
+      var cert = Certificate.build(PARAMS)
+      var moved = Object.assign({}, cert, {
+        anchor: { txid: 'ff'.repeat(32), blockHeight: 999999 },
+        mode: NS.MODE.HYBRID
+      })
+      Certificate.proofHashMatches(moved).should.equal(true)
+    })
+
+    it('returns a strict boolean, never a truthy object', function () {
+      Certificate.proofHashMatches(Certificate.build(PARAMS)).should.be.a('boolean')
+      Certificate.proofHashMatches(null).should.equal(false)
+      Certificate.proofHashMatches({}).should.equal(false)
+      Certificate.proofHashMatches({ proofHash: 'nonsense' }).should.equal(false)
+    })
+
+    // The hex fields decode to bytes before hashing. Hashing the strings would be twice
+    // as many bytes and produce something that still looks like a hash.
+    it('hashes the decoded bytes, not the hex strings', function () {
+      var cert = Certificate.build(PARAMS)
+      var overHex = Hash.sha256(Encoding.canonicalBytes({
+        algorithm: cert.algorithm,
+        hashAlgorithm: cert.hashAlgorithm,
+        payloadHash: Buffer.from(cert.payloadHash, 'utf8'), // the STRING, wrongly
+        publicKey: Buffer.from(cert.publicKey, 'hex'),
+        signature: Buffer.from(cert.signature, 'hex'),
+        createdAtUnix: Encoding.toUnixSeconds(cert.createdAt)
+      })).toString('hex')
+      overHex.should.not.equal(cert.proofHash)
+    })
+  })
+
+  describe('SPV envelope', function () {
+    // The spec's explicit guarantee. If it ever broke, every previously issued
+    // certificate would become unverifiable.
+    it('never changes proofHash', function () {
+      var cert = Certificate.build(PARAMS)
+      var withSPV = Certificate.attachSPV(cert, SPV)
+      withSPV.proofHash.should.equal(cert.proofHash)
+      Certificate.proofHashMatches(withSPV).should.equal(true)
+    })
+
+    it('does not mutate the certificate it was given', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.attachSPV(cert, SPV)
+      ;(cert.spv === undefined).should.equal(true)
+    })
+
+    it('defaults format to TSC', function () {
+      Certificate.attachSPV(Certificate.build(PARAMS), SPV).spv.format.should.equal('TSC')
+    })
+
+    it('keeps an explicit format, for BUMP or BEEF', function () {
+      var withSPV = Certificate.attachSPV(Certificate.build(PARAMS),
+        Object.assign({}, SPV, { format: 'BUMP' }))
+      withSPV.spv.format.should.equal('BUMP')
+    })
+  })
+
+  describe('validateShape', function () {
+    it('passes a well-formed certificate', function () {
+      Certificate.validateShape(Certificate.build(PARAMS)).should.deep.equal([])
+    })
+
+    it('names every missing required field', function () {
+      var problems = Certificate.validateShape({})
+      problems.length.should.equal(Certificate.REQUIRED_FIELDS.length)
+      problems[0].should.match(/missing required field/)
+    })
+
+    it('rejects a foreign protocol or version', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.validateShape(Object.assign({}, cert, { protocol: 'Other' }))
+        .should.include('protocol must be "NotaryHash"')
+      Certificate.validateShape(Object.assign({}, cert, { version: 2 }))
+        .should.include('unsupported version: 2')
+    })
+
+    it('rejects a hash field of the wrong length or that is not hex', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.validateShape(Object.assign({}, cert, { payloadHash: 'ab' }))
+        .should.include('payloadHash must be 32 bytes (64 hex chars)')
+      Certificate.validateShape(Object.assign({}, cert, { proofHash: 'zz'.repeat(32) }))
+        .should.include('proofHash must be a hex string')
+    })
+
+    // Shape is not verification, and a test says so — otherwise it gets used as one.
+    it('says nothing about whether the proofHash is correct', function () {
+      var cert = Certificate.build(PARAMS)
+      var lying = Object.assign({}, cert, { proofHash: '00'.repeat(32) })
+      Certificate.validateShape(lying).should.deep.equal([])
+      Certificate.proofHashMatches(lying).should.equal(false)
+    })
+  })
+
+  describe('canonicalize', function () {
+    it('is RFC 8785 over the certificate', function () {
+      var cert = Certificate.build(PARAMS)
+      Certificate.canonicalize(cert).should.equal(JCS.stringify(cert))
+    })
+
+    it('sorts keys, so transport order does not matter', function () {
+      var cert = Certificate.build(PARAMS)
+      var reordered = {}
+      Object.keys(cert).reverse().forEach(function (k) { reordered[k] = cert[k] })
+      Certificate.canonicalize(reordered).should.equal(Certificate.canonicalize(cert))
+    })
+
+    // proofHash is over the length-prefixed BINARY proof bytes, not over this JSON.
+    // Confusing the two produces a value that looks like a proofHash and is not one.
+    it('is not what proofHash is computed over', function () {
+      var cert = Certificate.build(PARAMS)
+      Hash.sha256(Buffer.from(Certificate.canonicalize(cert), 'utf8')).toString('hex')
+        .should.not.equal(cert.proofHash)
+    })
+  })
+})

package/test/notaryhash/encoding.js

@@ -0,0 +1,186 @@
+'use strict'
+
+/* global describe, it */
+
+// BRC-220 canonical encoding. The property that matters is not that these bytes are
+// stable for us — it is that another implementation reading the spec produces the same
+// ones. So the tests assert the byte layout the spec dictates, field by field, rather
+// than only pinning our own output.
+//
+// The failure this module is most exposed to is a proofHash that is self-consistent and
+// wrong: it verifies against itself, every local test passes, and nobody finds out until
+// a third party tries to verify a certificate. Several tests below exist only to make
+// that shape impossible.
+
+require('chai').should()
+var Encoding = require('../../lib/notaryhash/encoding')
+var Hash = require('../../lib/crypto/hash')
+
+var FIELDS = {
+  algorithm: 'ECDSA-secp256k1',
+  hashAlgorithm: 'SHA-256',
+  payloadHash: Buffer.alloc(32, 0x11),
+  publicKey: Buffer.alloc(33, 0x02),
+  signature: Buffer.alloc(71, 0x30),
+  createdAtUnix: 1786838400
+}
+
+describe('BRC-220 encoding', function () {
+  describe('lp()', function () {
+    it('is u32be(len) followed by the bytes', function () {
+      Encoding.lp(Buffer.from([0xaa, 0xbb])).toString('hex').should.equal('00000002aabb')
+    })
+
+    it('encodes an empty value as a bare zero length', function () {
+      Encoding.lp(Buffer.alloc(0)).toString('hex').should.equal('00000000')
+    })
+
+    it('measures BYTES, not characters, for text', function () {
+      // 'é' is one character and two UTF-8 bytes. Using .length here would prefix 1,
+      // and every proof containing a non-ASCII algorithm name would be unverifiable.
+      Encoding.lp('é').toString('hex').should.equal('00000002c3a9')
+      Encoding.lp('abc').toString('hex').should.equal('00000003616263')
+    })
+
+    // Length-prefixing exists to make field boundaries unambiguous. If it did not, these
+    // two field pairs would concatenate to identical bytes.
+    it('keeps ambiguous field splits distinct', function () {
+      var a = Buffer.concat([Encoding.lp('ab'), Encoding.lp('c')])
+      var b = Buffer.concat([Encoding.lp('a'), Encoding.lp('bc')])
+      a.toString('hex').should.not.equal(b.toString('hex'))
+    })
+  })
+
+  describe('u64be()', function () {
+    it('is 8 bytes, big-endian', function () {
+      Encoding.u64be(1).toString('hex').should.equal('0000000000000001')
+      Encoding.u64be(1786838400).toString('hex').should.equal('000000006a80fd80')
+    })
+
+    // Date.now() is milliseconds. A caller who forgets to divide gets a timestamp about
+    // a thousand years in the future that still encodes cleanly, so the guard is on the
+    // input rather than the output.
+    it('rejects a fractional value, which is what a millisecond mistake looks like', function () {
+      ;(function () { Encoding.u64be(1786838400.5) }).should.throw(/whole seconds/)
+    })
+
+    it('rejects non-finite and negative values', function () {
+      ;(function () { Encoding.u64be(NaN) }).should.throw(/finite/)
+      ;(function () { Encoding.u64be(-1) }).should.throw(/negative/)
+    })
+  })
+
+  describe('toUnixSeconds()', function () {
+    it('converts an ISO 8601 string to whole seconds', function () {
+      Encoding.toUnixSeconds('2026-08-16T00:00:00.000Z').should.equal(1786838400)
+    })
+
+    // Certificates carry millisecond precision in createdAt; the canonical bytes do not.
+    // Two implementations must agree on the fractional part, and truncation is the only
+    // choice that never moves a timestamp forward.
+    it('truncates rather than rounds', function () {
+      Encoding.toUnixSeconds('2026-08-16T00:00:00.999Z').should.equal(1786838400)
+    })
+
+    it('rejects an unparseable date', function () {
+      ;(function () { Encoding.toUnixSeconds('not-a-date') }).should.throw(/not a valid date/)
+    })
+  })
+
+  describe('canonicalBytes()', function () {
+    // The layout, asserted against a hand-built expectation rather than against the
+    // function's own output — otherwise this only proves the function is deterministic.
+    it('lays the fields out exactly as the spec specifies', function () {
+      var expected = Buffer.concat([
+        Encoding.lp('NotaryHash/1.0'),
+        Buffer.from([1]),
+        Encoding.lp('ECDSA-secp256k1'),
+        Encoding.lp('SHA-256'),
+        Encoding.lp(FIELDS.payloadHash),
+        Encoding.lp(FIELDS.publicKey),
+        Encoding.lp(FIELDS.signature),
+        Encoding.u64be(FIELDS.createdAtUnix)
+      ])
+      Encoding.canonicalBytes(FIELDS).toString('hex').should.equal(expected.toString('hex'))
+    })
+
+    it('opens with the protocol prefix and the version byte', function () {
+      var bytes = Encoding.canonicalBytes(FIELDS)
+      bytes.slice(0, 4).readUInt32BE(0).should.equal(14) // len('NotaryHash/1.0')
+      bytes.slice(4, 18).toString('utf8').should.equal('NotaryHash/1.0')
+      bytes[18].should.equal(1) // u8(version)
+    })
+
+    it('ends with the timestamp', function () {
+      var bytes = Encoding.canonicalBytes(FIELDS)
+      bytes.slice(-8).toString('hex').should.equal(Encoding.u64be(FIELDS.createdAtUnix).toString('hex'))
+    })
+
+    // THE test for this module. GDAF once signed a serialization that silently omitted
+    // credentialSubject, so a forger could rewrite the claims without breaking the proof.
+    // Every field must move the hash, or it is not covered by it.
+    it('covers every field — changing any one changes the hash', function () {
+      var base = Encoding.proofHash(FIELDS).toString('hex')
+      var mutations = {
+        algorithm: 'ML-DSA-65',
+        hashAlgorithm: 'SHA-512',
+        payloadHash: Buffer.alloc(32, 0x12),
+        publicKey: Buffer.alloc(33, 0x03),
+        signature: Buffer.alloc(71, 0x31),
+        createdAtUnix: FIELDS.createdAtUnix + 1
+      }
+      Object.keys(mutations).forEach(function (field) {
+        var altered = Object.assign({}, FIELDS)
+        altered[field] = mutations[field]
+        Encoding.proofHash(altered).toString('hex')
+          .should.not.equal(base, field + ' does not affect proofHash, so it is not covered by it')
+      })
+    })
+
+    // Hex is what certificates carry, and hex is twice as long as the bytes it encodes.
+    // Accepting it here would produce a proof that verifies locally and nowhere else.
+    it('refuses a hex string where raw bytes are required', function () {
+      var withHex = Object.assign({}, FIELDS, { payloadHash: FIELDS.payloadHash.toString('hex') })
+      ;(function () { Encoding.canonicalBytes(withHex) }).should.throw(/must be a Buffer/)
+    })
+
+    it('names the offending field and points at the hex trap', function () {
+      var withHex = Object.assign({}, FIELDS, { signature: FIELDS.signature.toString('hex') })
+      ;(function () { Encoding.canonicalBytes(withHex) }).should.throw(/signature.*hex/)
+    })
+
+    it('requires the string fields to be present and non-empty', function () {
+      ;(function () {
+        Encoding.canonicalBytes(Object.assign({}, FIELDS, { algorithm: '' }))
+      }).should.throw(/algorithm/)
+      ;(function () {
+        Encoding.canonicalBytes(Object.assign({}, FIELDS, { hashAlgorithm: undefined }))
+      }).should.throw(/hashAlgorithm/)
+    })
+
+    it('handles a post-quantum-sized signature', function () {
+      // SLH-DSA signatures run to tens of kilobytes; the u32be length prefix must carry
+      // them without truncation.
+      var big = Object.assign({}, FIELDS, { signature: Buffer.alloc(49856, 0x7f) })
+      var bytes = Encoding.canonicalBytes(big)
+      var sigLenOffset = bytes.length - 8 - 49856 - 4
+      bytes.readUInt32BE(sigLenOffset).should.equal(49856)
+    })
+  })
+
+  describe('proofHash()', function () {
+    it('is SHA-256 of the canonical bytes', function () {
+      Encoding.proofHash(FIELDS).toString('hex')
+        .should.equal(Hash.sha256(Encoding.canonicalBytes(FIELDS)).toString('hex'))
+    })
+
+    it('is 32 bytes', function () {
+      Encoding.proofHash(FIELDS).length.should.equal(32)
+    })
+
+    it('is deterministic', function () {
+      Encoding.proofHash(FIELDS).toString('hex')
+        .should.equal(Encoding.proofHash(Object.assign({}, FIELDS)).toString('hex'))
+    })
+  })
+})

package/test/notaryhash/merkle.js

@@ -0,0 +1,181 @@
+'use strict'
+
+/* global describe, it */
+
+// RFC 6962 Merkle trees, for BRC-220 batch mode.
+//
+// The first version of foldPath here descended from the root by splitting at the largest
+// power of two, mirroring how root() builds the tree. It round-tripped perfectly for
+// powers of two and failed for 21 of the 45 leaves in trees of size 1..9 — which is
+// exactly why the published vectors below matter more than any round-trip test. A tree
+// that agrees with itself is not evidence.
+
+require('chai').should()
+var Merkle = require('../../lib/notaryhash/merkle')
+var Hash = require('../../lib/crypto/hash')
+
+// The canonical RFC 6962 / Certificate Transparency inputs.
+var D = ['', '00', '10', '2021', '3031', '40414243', '5051525354555657',
+  '606162636465666768696a6b6c6d6e6f'].map(function (h) { return Buffer.from(h, 'hex') })
+
+describe('RFC 6962 Merkle tree', function () {
+  describe('published vectors', function () {
+    // External validation. Everything else in this file could be internally consistent
+    // and wrong; these numbers come from outside this codebase.
+    var EXPECTED = {
+      0: 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855',
+      1: '6e340b9cffb37a989ca544e6bb780a2c78901d3fb33738768511a30617afa01d',
+      2: 'fac54203e7cc696cf0dfcb42c92a1d9dbaf70ad9e621f4bd8d98662f00e3c125',
+      4: 'd37ee418976dd95753c1c73862b9398fa2a2cf9b4ff0fdfe8b30cd95209614b7',
+      7: 'ddb89be403809e325750d3d263cd78929c2942b7942a34b77e122c9594a74c8c',
+      8: '5dc9da79a70659a9ad559cb701ded9a2ab9d823aad2f4960cfe370eff4604328'
+    }
+
+    Object.keys(EXPECTED).forEach(function (n) {
+      it('MTH of ' + n + ' leaves matches the published root', function () {
+        Merkle.root(D.slice(0, Number(n))).toString('hex').should.equal(EXPECTED[n])
+      })
+    })
+  })
+
+  describe('construction', function () {
+    it('hashes the empty tree as SHA-256 of the empty string, not zeroes', function () {
+      Merkle.root([]).toString('hex').should.equal(Hash.sha256(Buffer.alloc(0)).toString('hex'))
+      Merkle.root([]).toString('hex').should.not.equal('00'.repeat(32))
+    })
+
+    it('domain-separates leaves from internal nodes', function () {
+      Merkle.hashLeaf(Buffer.from('ab', 'hex')).toString('hex')
+        .should.equal(Hash.sha256(Buffer.from('00ab', 'hex')).toString('hex'))
+      Merkle.hashNode(Buffer.alloc(32, 1), Buffer.alloc(32, 2)).toString('hex')
+        .should.equal(Hash.sha256(Buffer.concat([
+          Buffer.from([0x01]), Buffer.alloc(32, 1), Buffer.alloc(32, 2)
+        ])).toString('hex'))
+    })
+
+    // Without the 0x00/0x01 prefixes an internal node could be reinterpreted as a leaf,
+    // which is the second-preimage attack Bitcoin's tree is open to.
+    it('gives a leaf and a node over the same bytes different hashes', function () {
+      var payload = Buffer.alloc(64, 7)
+      Merkle.hashLeaf(payload).toString('hex')
+        .should.not.equal(Merkle.hashNode(Buffer.alloc(32, 7), Buffer.alloc(32, 7)).toString('hex'))
+    })
+
+    // The split point, not the midpoint. For n=5 the RFC splits 4/1.
+    it('splits at the largest power of two below n', function () {
+      var expected = { 2: 1, 3: 2, 4: 2, 5: 4, 6: 4, 7: 4, 8: 4, 9: 8, 16: 8, 17: 16 }
+      Object.keys(expected).forEach(function (n) {
+        Merkle.largestPowerOfTwoBelow(Number(n)).should.equal(expected[n])
+      })
+    })
+  })
+
+  // The property the plan named as the one that would ship silently: a Bitcoin-style
+  // tree over the same leaves must produce a DIFFERENT root.
+  describe('is not the Bitcoin tree', function () {
+    function bitcoinStyleRoot (leaves) {
+      var level = leaves.map(function (l) { return Hash.sha256sha256(l) })
+      while (level.length > 1) {
+        var next = []
+        for (var i = 0; i < level.length; i += 2) {
+          var left = level[i]
+          var right = i + 1 < level.length ? level[i + 1] : left // duplicated
+          next.push(Hash.sha256sha256(Buffer.concat([left, right])))
+        }
+        level = next
+      }
+      return level[0]
+    }
+
+    it('produces a different root over the same leaves', function () {
+      var leaves = D.slice(0, 4)
+      Merkle.root(leaves).toString('hex')
+        .should.not.equal(bitcoinStyleRoot(leaves).toString('hex'))
+    })
+
+    it('differs for an odd leaf count, where Bitcoin duplicates and RFC 6962 does not', function () {
+      var leaves = D.slice(0, 3)
+      Merkle.root(leaves).toString('hex')
+        .should.not.equal(bitcoinStyleRoot(leaves).toString('hex'))
+    })
+  })
+
+  describe('inclusion proofs', function () {
+    it('round-trips every leaf for every tree size 1..33', function () {
+      var failures = []
+      for (var n = 1; n <= 33; n++) {
+        var leaves = []
+        for (var i = 0; i < n; i++) leaves.push(Buffer.from([i & 0xff, n & 0xff]))
+        var root = Merkle.root(leaves)
+        for (var j = 0; j < n; j++) {
+          if (!Merkle.verifyInclusion(leaves[j], j, n, Merkle.path(leaves, j), root)) {
+            failures.push('n=' + n + ' i=' + j)
+          }
+        }
+      }
+      failures.should.deep.equal([])
+    })
+
+    it('rejects a proof for the wrong leaf', function () {
+      var leaves = D.slice(0, 8)
+      var root = Merkle.root(leaves)
+      Merkle.verifyInclusion(D[1], 0, 8, Merkle.path(leaves, 0), root).should.equal(false)
+    })
+
+    it('rejects a proof at the wrong index', function () {
+      var leaves = D.slice(0, 8)
+      var root = Merkle.root(leaves)
+      Merkle.verifyInclusion(leaves[3], 4, 8, Merkle.path(leaves, 3), root).should.equal(false)
+    })
+
+    // leafCount changes the tree shape — but only for SOME indices. On an 8-leaf tree
+    // claimed as 7, indices 0..5 fold identically and only 6 and 7 differ, because the
+    // left region of the tree is the same shape either way.
+    //
+    // That is a property worth knowing rather than a defect: it means an inclusion proof
+    // alone cannot be trusted to detect a wrong leafCount, which is why
+    // NotaryHash.recordMatchesCertificate compares the certificate's count against the
+    // authoritative u32be in the on-chain record instead of assuming the fold implies it.
+    it('rejects a wrong leafCount where the shape differs', function () {
+      var leaves = D.slice(0, 8)
+      var root = Merkle.root(leaves)
+      Merkle.verifyInclusion(leaves[6], 6, 7, Merkle.path(leaves, 6), root).should.equal(false)
+      Merkle.verifyInclusion(leaves[7], 7, 7, Merkle.path(leaves, 7), root).should.equal(false)
+    })
+
+    it('does NOT catch a wrong leafCount where the shape is the same', function () {
+      var leaves = D.slice(0, 8)
+      var root = Merkle.root(leaves)
+      // Documented, not desired. The on-chain leafCount is what closes this.
+      Merkle.verifyInclusion(leaves[3], 3, 7, Merkle.path(leaves, 3), root).should.equal(true)
+    })
+
+    it('rejects a truncated or padded path', function () {
+      var leaves = D.slice(0, 8)
+      var root = Merkle.root(leaves)
+      var path = Merkle.path(leaves, 3)
+      Merkle.verifyInclusion(leaves[3], 3, 8, path.slice(0, -1), root).should.equal(false)
+      Merkle.verifyInclusion(leaves[3], 3, 8, path.concat([Buffer.alloc(32)]), root).should.equal(false)
+    })
+
+    it('rejects a tampered sibling', function () {
+      var leaves = D.slice(0, 8)
+      var root = Merkle.root(leaves)
+      var path = Merkle.path(leaves, 3)
+      path[0] = Buffer.alloc(32, 0xff)
+      Merkle.verifyInclusion(leaves[3], 3, 8, path, root).should.equal(false)
+    })
+
+    it('returns a strict boolean and never throws on malformed input', function () {
+      Merkle.verifyInclusion(D[0], 0, 1, [], Merkle.root([D[0]])).should.be.a('boolean')
+      Merkle.verifyInclusion(null, 0, 1, [], Buffer.alloc(32)).should.equal(false)
+      Merkle.verifyInclusion(D[0], 5, 1, [], Buffer.alloc(32)).should.equal(false)
+      Merkle.verifyInclusion(D[0], 0, 1, [], 'not-a-buffer').should.equal(false)
+    })
+
+    it('gives an empty path for a single-leaf tree', function () {
+      Merkle.path([D[0]], 0).should.deep.equal([])
+      Merkle.verifyInclusion(D[0], 0, 1, [], Merkle.hashLeaf(D[0])).should.equal(true)
+    })
+  })
+})