@smartledger/bsv 8.2.0 → 8.3.1

package/test/notaryhash/interop.js

@@ -0,0 +1,112 @@
+'use strict'
+
+/* global describe, it */
+
+// BRC-220 signature interoperability.
+//
+// Every other test in this directory signs with `lib/crypto/ecdsa.js` and verifies
+// through `lib/notaryhash/suites.js`, which also uses `lib/crypto/ecdsa.js`. That
+// proves the module agrees with itself. It cannot prove the module agrees with the
+// spec, and in 8.3.0 it did not: the suite set `endian: 'little'` before verifying,
+// so it rejected any signature produced the way BRC-220 describes and accepted only
+// signatures made with bsv's own byte-reversed convention. Twenty-odd passing tests
+// said nothing about it, because they all signed the same wrong way.
+//
+// So this file verifies against `@noble/curves` instead — a separate implementation
+// that shares no verification code with ours. It is the only test here that can fail
+// when our code and our tests are wrong together.
+//
+// One trap worth naming, because it cost real time when this was diagnosed: noble v2
+// PREHASHES by default. `secp256k1.sign(digest, key)` signs `sha256(digest)`, and
+// `secp256k1.verify` prehashes to match, so noble looks self-consistent while
+// disagreeing with everyone. BRC-220 signs the payloadHash itself, so every call
+// below passes `{ prehash: false }`. Omit it and these tests compare the wrong things
+// and "pass" for the wrong reason.
+
+require('chai').should()
+var bsv = require('../..')
+var Suites = require('../../lib/notaryhash/suites')
+var Hash = require('../../lib/crypto/hash')
+var { secp256k1 } = require('@noble/curves/secp256k1.js')
+
+var PAYLOAD_HASH = Hash.sha256(Buffer.from('the document nobody sees'))
+
+// A fixed key, so a failure is reproducible rather than one-in-N flaky.
+var SECRET = Buffer.from('c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee00c0ffee01', 'hex')
+var PUBLIC_KEY = Buffer.from(secp256k1.getPublicKey(SECRET, true))
+
+function rawSig (sig) {
+  return Buffer.concat([
+    sig.r.toArrayLike(Buffer, 'be', 32),
+    sig.s.toArrayLike(Buffer, 'be', 32)
+  ])
+}
+
+describe('BRC-220 signature interop', function () {
+  it('agrees with @noble/curves on the public key for a given secret', function () {
+    // If this fails nothing below means anything — the two libraries would be
+    // signing under different keys.
+    var ours = bsv.PrivateKey.fromBuffer(SECRET).toPublicKey().toBuffer()
+    ours.toString('hex').should.equal(PUBLIC_KEY.toString('hex'))
+  })
+
+  it('ACCEPTS a signature made the way the spec describes', function () {
+    // This is the regression. Under 8.3.0 this assertion fails.
+    var conformant = Buffer.from(secp256k1.sign(PAYLOAD_HASH, SECRET, { prehash: false }))
+    Suites.verify('ECDSA-secp256k1', PAYLOAD_HASH, conformant, PUBLIC_KEY)
+      .should.equal(true, 'a conformant BRC-220 signature must verify')
+  })
+
+  it('emits signatures an independent implementation accepts', function () {
+    var key = bsv.PrivateKey.fromBuffer(SECRET)
+    var ecdsa = bsv.crypto.ECDSA().set({ hashbuf: PAYLOAD_HASH, privkey: key })
+    ecdsa.sign()
+    secp256k1.verify(rawSig(ecdsa.sig), PAYLOAD_HASH, PUBLIC_KEY, { prehash: false })
+      .should.equal(true, 'our signature must verify under @noble/curves')
+  })
+
+  it('REJECTS a signature over the byte-reversed digest', function () {
+    // The 8.3.0 convention. It must now fail: accepting both would mean two valid
+    // signatures exist for one signing act, and both are inside proofHash.
+    var key = bsv.PrivateKey.fromBuffer(SECRET)
+    var ecdsa = bsv.crypto.ECDSA().set({ hashbuf: PAYLOAD_HASH, endian: 'little', privkey: key })
+    ecdsa.sign()
+    Suites.verify('ECDSA-secp256k1', PAYLOAD_HASH, rawSig(ecdsa.sig), PUBLIC_KEY)
+      .should.equal(false, 'the pre-8.3.1 little-endian convention must not verify')
+  })
+
+  it('round-trips both ways over many payloads, not just one', function () {
+    // A single vector can pass by coincidence — the reversal of a digest whose bytes
+    // happen to be near-palindromic still differs, but a lucky scalar could mask a
+    // subtler bug. Twenty payloads with distinct digests makes that implausible.
+    var key = bsv.PrivateKey.fromBuffer(SECRET)
+    for (var i = 0; i < 20; i++) {
+      var h = Hash.sha256(Buffer.from('payload ' + i))
+
+      var theirs = Buffer.from(secp256k1.sign(h, SECRET, { prehash: false }))
+      Suites.verify('ECDSA-secp256k1', h, theirs, PUBLIC_KEY)
+        .should.equal(true, 'noble sig ' + i + ' rejected by our suite')
+
+      var ecdsa = bsv.crypto.ECDSA().set({ hashbuf: h, privkey: key })
+      ecdsa.sign()
+      secp256k1.verify(rawSig(ecdsa.sig), h, PUBLIC_KEY, { prehash: false })
+        .should.equal(true, 'our sig ' + i + ' rejected by noble')
+    }
+  })
+
+  it('still rejects a signature over a DIFFERENT payload', function () {
+    // Guards against the fix degenerating into "accept anything". A verifier that
+    // returns true unconditionally would pass every test above.
+    var other = Hash.sha256(Buffer.from('a different document'))
+    var sig = Buffer.from(secp256k1.sign(other, SECRET, { prehash: false }))
+    Suites.verify('ECDSA-secp256k1', PAYLOAD_HASH, sig, PUBLIC_KEY)
+      .should.equal(false)
+  })
+
+  it('still rejects a signature from a DIFFERENT key', function () {
+    var otherSecret = Buffer.from('a11ce00a11ce00a11ce00a11ce00a11ce00a11ce00a11ce00a11ce00a11ce001', 'hex')
+    var sig = Buffer.from(secp256k1.sign(PAYLOAD_HASH, otherSecret, { prehash: false }))
+    Suites.verify('ECDSA-secp256k1', PAYLOAD_HASH, sig, PUBLIC_KEY)
+      .should.equal(false)
+  })
+})

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)
+    })
+  })
+})

package/test/notaryhash/script.js

@@ -0,0 +1,270 @@
+'use strict'
+
+/* global describe, it */
+
+// BRC-220 on-chain record. As with the encoding module, the property that matters is that
+// another implementation reading the spec produces and accepts the same bytes — so the
+// tests assert the push layout the spec dictates rather than only round-tripping our own
+// output, which would pass even if every field were in the wrong place.
+
+require('chai').should()
+var bsv = require('../..')
+var NS = require('../../lib/notaryhash/script')
+var Hash = require('../../lib/crypto/hash')
+var Opcode = require('../../lib/opcode')
+
+var FULL = {
+  mode: NS.MODE.FULL,
+  algorithm: 'ECDSA-secp256k1',
+  hashAlgorithm: 'SHA-256',
+  payloadHash: Buffer.alloc(32, 0x11),
+  proofHash: Buffer.alloc(32, 0x22),
+  publicKey: Buffer.alloc(33, 0x02),
+  signature: Buffer.alloc(64, 0x30)
+}
+
+// The spec counts PUSH indices, which start after OP_FALSE OP_RETURN. Script chunks
+// include those two opcodes, so push N is chunk N+2.
+function pushes (script) {
+  return script.chunks.slice(2)
+}
+
+describe('BRC-220 on-chain record', function () {
+  describe('push layout', function () {
+    it('is OP_FALSE OP_RETURN followed by the pushes', function () {
+      var s = NS.build(FULL)
+      s.chunks[0].opcodenum.should.equal(Opcode.OP_FALSE)
+      s.chunks[1].opcodenum.should.equal(Opcode.OP_RETURN)
+    })
+
+    it('puts the prefix at push index 0, as 10 ASCII bytes', function () {
+      var p = pushes(NS.build(FULL))
+      p[0].buf.toString('ascii').should.equal('NOTARYHASH')
+      p[0].buf.length.should.equal(10)
+      p[0].buf.toString('hex').should.equal('4e4f5441525948415348')
+    })
+
+    // The spec discriminates on "the mode/kind byte at push index 2". If this drifts,
+    // every other implementation reads the wrong field.
+    it('puts the version at push index 1 and the mode at push index 2', function () {
+      var p = pushes(NS.build(FULL))
+      p[1].buf.length.should.equal(1)
+      p[1].buf[0].should.equal(1)
+      p[2].buf.length.should.equal(1)
+      p[2].buf[0].should.equal(NS.MODE.FULL)
+    })
+
+    it('orders full-mode fields as the spec lists them', function () {
+      var p = pushes(NS.build(FULL))
+      p.length.should.equal(9)
+      p[3].buf.toString('utf8').should.equal('ECDSA-secp256k1')
+      p[4].buf.toString('utf8').should.equal('SHA-256')
+      p[5].buf.toString('hex').should.equal(FULL.payloadHash.toString('hex'))
+      p[6].buf.toString('hex').should.equal(FULL.proofHash.toString('hex'))
+      p[7].buf.toString('hex').should.equal(FULL.publicKey.toString('hex'))
+      p[8].buf.toString('hex').should.equal(FULL.signature.toString('hex'))
+    })
+
+    it('lays batch mode out as root then u32be count', function () {
+      var p = pushes(NS.build({ mode: NS.MODE.BATCH, merkleRoot: Buffer.alloc(32, 0xaa), leafCount: 12345 }))
+      p.length.should.equal(5)
+      p[2].buf[0].should.equal(NS.MODE.BATCH)
+      p[3].buf.length.should.equal(32)
+      p[4].buf.length.should.equal(4)
+      p[4].buf.readUInt32BE(0).should.equal(12345)
+    })
+
+    // The canonical proof bytes use lp() because they are one flat string; here the push
+    // opcode already carries the length. Applying lp() as well would double-encode.
+    it('does not length-prefix inside the pushes', function () {
+      var p = pushes(NS.build(FULL))
+      // A doubly-encoded payloadHash would be 4 + 32 bytes.
+      p[5].buf.length.should.equal(32)
+      p[3].buf.length.should.equal('ECDSA-secp256k1'.length)
+    })
+  })
+
+  describe('hybrid mode', function () {
+    it('puts SHA-256 of the key and signature on chain', function () {
+      var p = pushes(NS.build(Object.assign({}, FULL, { mode: NS.MODE.HYBRID })))
+      p[7].buf.toString('hex').should.equal(Hash.sha256(FULL.publicKey).toString('hex'))
+      p[8].buf.toString('hex').should.equal(Hash.sha256(FULL.signature).toString('hex'))
+      p[7].buf.length.should.equal(32)
+      p[8].buf.length.should.equal(32)
+    })
+
+    // The caller always supplies the FULL key and signature; hashing is this module's job.
+    // Accepting a pre-hashed blob would produce a record that looks right and cannot be
+    // reconciled with the certificate, and nothing downstream would notice.
+    it('hashes internally rather than trusting a pre-hashed input', function () {
+      var preHashed = Object.assign({}, FULL, {
+        mode: NS.MODE.HYBRID,
+        publicKey: Hash.sha256(FULL.publicKey)
+      })
+      var p = pushes(NS.build(preHashed))
+      // Hashed again, so it does NOT equal the value that was passed in.
+      p[7].buf.toString('hex').should.not.equal(Hash.sha256(FULL.publicKey).toString('hex'))
+    })
+
+    it('parses to hashes, never to raw blobs', function () {
+      var parsed = NS.parse(NS.build(Object.assign({}, FULL, { mode: NS.MODE.HYBRID })))
+      parsed.publicKeyHash.toString('hex').should.equal(Hash.sha256(FULL.publicKey).toString('hex'))
+      ;(parsed.publicKey === undefined).should.equal(true)
+      ;(parsed.signature === undefined).should.equal(true)
+    })
+  })
+
+  describe('round trip', function () {
+    it('preserves every full-mode field', function () {
+      var p = NS.parse(NS.build(FULL))
+      p.mode.should.equal(NS.MODE.FULL)
+      p.version.should.equal(1)
+      p.algorithm.should.equal(FULL.algorithm)
+      p.hashAlgorithm.should.equal(FULL.hashAlgorithm)
+      p.payloadHash.toString('hex').should.equal(FULL.payloadHash.toString('hex'))
+      p.proofHash.toString('hex').should.equal(FULL.proofHash.toString('hex'))
+      p.publicKey.toString('hex').should.equal(FULL.publicKey.toString('hex'))
+      p.signature.toString('hex').should.equal(FULL.signature.toString('hex'))
+    })
+
+    it('preserves batch fields', function () {
+      var p = NS.parse(NS.build({ mode: NS.MODE.BATCH, merkleRoot: Buffer.alloc(32, 0xbb), leafCount: 1 }))
+      p.merkleRoot.toString('hex').should.equal(Buffer.alloc(32, 0xbb).toString('hex'))
+      p.leafCount.should.equal(1)
+    })
+
+    it('round-trips through hex', function () {
+      var hex = NS.build(FULL).toHex()
+      NS.parse(hex).algorithm.should.equal(FULL.algorithm)
+    })
+
+    it('carries a post-quantum-sized signature in full mode', function () {
+      var big = Object.assign({}, FULL, { signature: Buffer.alloc(7856, 0x5a) })
+      NS.parse(NS.build(big)).signature.length.should.equal(7856)
+    })
+  })
+
+  describe('parser rejects', function () {
+    function corrupt (fn) {
+      var s = NS.build(FULL)
+      fn(s)
+      return s
+    }
+
+    // Long enough to pass the length check, so the OP_FALSE check is what rejects it.
+    it('a record that does not open with OP_FALSE', function () {
+      var s = corrupt(function (s) { s.chunks[0] = { opcodenum: Opcode.OP_1 } })
+      ;(function () { NS.parse(s) }).should.throw(/OP_FALSE/)
+    })
+
+    it('a record with no OP_RETURN', function () {
+      var s = corrupt(function (s) { s.chunks[1] = { opcodenum: Opcode.OP_1 } })
+      ;(function () { NS.parse(s) }).should.throw(/OP_RETURN/)
+    })
+
+    it('a foreign protocol prefix', function () {
+      var s = corrupt(function (s) { s.chunks[2].buf = Buffer.from('SOMETHINGELSE', 'ascii') })
+      ;(function () { NS.parse(s) }).should.throw(/prefix/)
+    })
+
+    it('an unsupported version', function () {
+      var s = corrupt(function (s) { s.chunks[3].buf = Buffer.from([9]) })
+      ;(function () { NS.parse(s) }).should.throw(/version: 9/)
+    })
+
+    it('an unknown mode', function () {
+      var s = corrupt(function (s) { s.chunks[4].buf = Buffer.from([7]) })
+      ;(function () { NS.parse(s) }).should.throw(/unknown NotaryHash mode: 7/)
+    })
+
+    it('the wrong number of pushes', function () {
+      var s = corrupt(function (s) { s.chunks.pop() })
+      ;(function () { NS.parse(s) }).should.throw(/exactly 11 pushes/)
+    })
+
+    it('a payloadHash that is not 32 bytes', function () {
+      var s = corrupt(function (s) { s.chunks[7].buf = Buffer.alloc(31, 1) })
+      ;(function () { NS.parse(s) }).should.throw(/payloadHash must be exactly 32/)
+    })
+
+    it('a leafCount that is not 4 bytes', function () {
+      var s = NS.build({ mode: NS.MODE.BATCH, merkleRoot: Buffer.alloc(32, 1), leafCount: 5 })
+      s.chunks[6].buf = Buffer.alloc(3, 0)
+      ;(function () { NS.parse(s) }).should.throw(/leafCount must be 4 bytes/)
+    })
+
+    it('too few pushes to be a record at all', function () {
+      ;(function () { NS.parse(new bsv.Script().add(Opcode.OP_FALSE).add(Opcode.OP_RETURN)) })
+        .should.throw(/too few pushes/)
+    })
+  })
+
+  describe('builder rejects', function () {
+    it('an unknown mode', function () {
+      ;(function () { NS.build(Object.assign({}, FULL, { mode: 5 })) }).should.throw(/mode must be/)
+    })
+
+    it('hex where raw bytes belong', function () {
+      ;(function () {
+        NS.build(Object.assign({}, FULL, { payloadHash: FULL.payloadHash.toString('hex') }))
+      }).should.throw(/must be a Buffer/)
+    })
+
+    it('a payloadHash of the wrong length', function () {
+      ;(function () {
+        NS.build(Object.assign({}, FULL, { payloadHash: Buffer.alloc(31) }))
+      }).should.throw(/exactly 32 bytes/)
+    })
+
+    it('a non-integer leafCount', function () {
+      ;(function () {
+        NS.build({ mode: NS.MODE.BATCH, merkleRoot: Buffer.alloc(32), leafCount: 1.5 })
+      }).should.throw(/leafCount/)
+    })
+  })
+
+  // A builder that minimally encodes its pushes represents u8(1) as OP_1. Those records
+  // are conformant, and rejecting them would be an interop failure rather than a safety
+  // measure — the mode byte is a routing hint, and every field that matters is checked
+  // on its own terms.
+  describe('interop with minimally-encoded pushes', function () {
+    it('reads OP_1 / OP_0 as the version and mode bytes', function () {
+      var s = NS.build(FULL)
+      s.chunks[3] = { opcodenum: Opcode.OP_1 }
+      s.chunks[4] = { opcodenum: Opcode.OP_0 }
+      var p = NS.parse(s)
+      p.version.should.equal(1)
+      p.mode.should.equal(NS.MODE.FULL)
+    })
+
+    it('reads OP_2 as batch mode', function () {
+      var s = NS.build({ mode: NS.MODE.BATCH, merkleRoot: Buffer.alloc(32, 3), leafCount: 2 })
+      s.chunks[4] = { opcodenum: Opcode.OP_2 }
+      NS.parse(s).mode.should.equal(NS.MODE.BATCH)
+    })
+  })
+
+  describe('isNotaryHash', function () {
+    it('accepts a record of each mode', function () {
+      NS.isNotaryHash(NS.build(FULL)).should.equal(true)
+      NS.isNotaryHash(NS.build(Object.assign({}, FULL, { mode: NS.MODE.HYBRID }))).should.equal(true)
+      NS.isNotaryHash(NS.build({ mode: NS.MODE.BATCH, merkleRoot: Buffer.alloc(32), leafCount: 0 }))
+        .should.equal(true)
+    })
+
+    it('rejects an unrelated output without throwing', function () {
+      NS.isNotaryHash(bsv.Script.buildPublicKeyHashOut(bsv.PrivateKey.fromRandom().toAddress()))
+        .should.equal(false)
+      NS.isNotaryHash('not-hex-at-all').should.equal(false)
+    })
+
+    // It is a scanning filter, not a validator. Saying so in a test stops it being used
+    // as one.
+    it('is only a filter — a truncated record still passes it but fails parse()', function () {
+      var s = NS.build(FULL)
+      s.chunks = s.chunks.slice(0, 6)
+      NS.isNotaryHash(s).should.equal(true)
+      ;(function () { NS.parse(s) }).should.throw()
+    })
+  })
+})