Merge pull request #170 from ty-everett/codex/brc136-basm-sync

[codex] Implement BRC-136 BASM overlay sync

Author: sirdeggen

.github/workflows/ci.yml

@@ -80,6 +80,17 @@ jobs:
           if [ -n "$SCOPE_FILTER" ]; then EXTRA="--filter $SCOPE_FILTER"; fi
           pnpm -r --filter '!@bsv/ts-stack' $EXTRA run lint --if-present
 
+      - name: Warm MongoDB memory-server binary cache
+        # The mongodb-memory-server tests download+extract the mongod binary on first
+        # use. When that cold start happens under the parallel `pnpm -r run test` load
+        # below, the just-extracted binary can still be open for writing when it is
+        # exec'd, producing `spawn ETXTBSY` and startup timeouts (seen on Node 24).
+        # Pre-extract the binary serially here so the test step reuses a settled cache.
+        continue-on-error: true
+        run: >
+          pnpm --filter @bsv/overlay-topics exec node --input-type=module -e
+          "import { MongoMemoryServer } from 'mongodb-memory-server'; const s = await MongoMemoryServer.create({ instance: { launchTimeout: 120000 } }); await s.stop(); console.log('mongodb-memory-server binary cache warmed');"
+
       - name: Test changed packages
         # Exclude: workspace root (delegating script) and example-paymail (example package, not production)
         env:

conformance/runner/ts/dispatchers/sync.ts

@@ -35,11 +35,13 @@
  */
 
 import { expect } from '@jest/globals'
+import { createHash } from 'node:crypto'
 
 export const categories: ReadonlyArray<string> = [
   'gasp-protocol',
   'brc40-user-state',
-  'chaintracks-v2-http'
+  'chaintracks-v2-http',
+  'brc136-basm'
 ]
 
 // ── Constants ──────────────────────────────────────────────────────────────────
@@ -49,6 +51,7 @@ const GASP_CURRENT_VERSION = 1
 
 /** txid pattern: exactly 64 hex characters (upper or lower). */
 const TXID_RE = /^[0-9a-fA-F]{64}$/
+const ZERO_HASH = '0000000000000000000000000000000000000000000000000000000000000000'
 
 // ── Helpers ────────────────────────────────────────────────────────────────────
 
@@ -787,6 +790,123 @@ function dispatchChaintracksV2 (
   }
 }
 
+// ── BRC-136 BASM ──────────────────────────────────────────────────────────────
+
+function sha256d(buffer: Buffer): Buffer {
+  const first = createHash('sha256').update(buffer).digest()
+  return createHash('sha256').update(first).digest()
+}
+
+function displayToInternal(hash: string): Buffer {
+  expect(TXID_RE.test(hash)).toBe(true)
+  return Buffer.from(hash, 'hex').reverse()
+}
+
+function internalToDisplay(hash: Buffer): string {
+  return Buffer.from(hash).reverse().toString('hex')
+}
+
+function computeBasmRootForVector(txids: string[]): string {
+  if (txids.length === 0) return ZERO_HASH
+  let layer = txids.map(displayToInternal)
+  if (layer.length === 1) return internalToDisplay(layer[0])
+  while (layer.length > 1) {
+    const next: Buffer[] = []
+    for (let i = 0; i < layer.length; i += 2) {
+      const right = i + 1 < layer.length ? layer[i + 1] : layer[i]
+      next.push(sha256d(Buffer.concat([layer[i], right])))
+    }
+    layer = next
+  }
+  return internalToDisplay(layer[0])
+}
+
+function computeTacForVector(prevTac: string, blockHash: string, basmRoot: string): string {
+  return internalToDisplay(sha256d(Buffer.concat([
+    displayToInternal(prevTac),
+    displayToInternal(blockHash),
+    displayToInternal(basmRoot)
+  ])))
+}
+
+function dispatchBRC136HTTP(input: Record<string, unknown>, expected: Record<string, unknown>): void {
+  const method = getString(input, 'method')
+  const path = getString(input, 'path')
+  const headers = (input['headers'] ?? {}) as Record<string, string>
+  const expectedStatus = getNumber(expected, 'status')
+
+  expect(method).toBe('POST')
+  expect(path.startsWith('/request')).toBe(true)
+  const requiresTopic = path !== '/requestRawTransactions'
+  if (requiresTopic) {
+    const hasTopic = Object.keys(headers).some(k => k.toLowerCase() === 'x-bsv-topic')
+    expect(hasTopic).toBe(expectedStatus < 400)
+  }
+
+  if (expectedStatus >= 400) {
+    const body = expected['body']
+    expect(body !== undefined).toBe(true)
+    assertErrorEnvelope(body as Record<string, unknown>)
+    return
+  }
+
+  if (expected['body'] !== undefined) {
+    const body = expected['body'] as Record<string, unknown>
+    if (path === '/requestTopicAnchorTip') {
+      expect(typeof body['topic']).toBe('string')
+      expect(typeof body['blockHeight']).toBe('number')
+      expect(typeof body['tac']).toBe('string')
+      expect(TXID_RE.test(body['tac'] as string)).toBe(true)
+    }
+  }
+}
+
+function dispatchBRC136(input: Record<string, unknown>, expected: Record<string, unknown>): void {
+  const method = getString(input, 'method')
+  if (method !== '') {
+    dispatchBRC136HTTP(input, expected)
+    return
+  }
+
+  const channel = getString(input, 'channel')
+  if (channel === 'basm/root') {
+    const cases = input['cases'] as Array<{ name: string, txids: string[] }>
+    const roots = (expected['roots'] ?? {}) as Record<string, string>
+    for (const testCase of cases) {
+      expect(computeBasmRootForVector(testCase.txids)).toBe(roots[testCase.name])
+    }
+    return
+  }
+
+  if (channel === 'basm/tac') {
+    expect(computeTacForVector(
+      getString(input, 'prevTac'),
+      getString(input, 'blockHash'),
+      getString(input, 'basmRoot')
+    )).toBe(expected['tac'])
+    return
+  }
+
+  if (channel === 'basm/rawTransactions') {
+    const msg = (input['message'] ?? {}) as Record<string, unknown>
+    expect(Array.isArray(msg['transactions'])).toBe(true)
+    for (const record of msg['transactions'] as unknown[]) {
+      expect(typeof record).toBe('object')
+      expect(record).not.toBeNull()
+      const tx = record as Record<string, unknown>
+      expect(typeof tx['txid']).toBe('string')
+      expect(TXID_RE.test(tx['txid'] as string)).toBe(true)
+      expect(typeof tx['rawTx']).toBe('string')
+      expect(/^[0-9a-fA-F]+$/.test(tx['rawTx'] as string)).toBe(true)
+    }
+    expect(Array.isArray(msg['missing'])).toBe(true)
+    expect(expected['valid']).toBe(true)
+    return
+  }
+
+  throw new Error(`sync dispatcher: unknown BRC-136 BASM channel '${channel}'`)
+}
+
 // ── Main dispatch entry point ──────────────────────────────────────────────────
 
 export function dispatch (
@@ -802,6 +922,10 @@ export function dispatch (
     dispatchChaintracksV2(input, expected)
     return
   }
+  if (category === 'brc136-basm') {
+    dispatchBRC136(input, expected)
+    return
+  }
   if (category !== 'gasp-protocol') {
     throw new Error(`sync dispatcher: unknown category '${category}'`)
   }

conformance/vectors/sync/brc136-basm.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "../../schema/vector.schema.json",
+  "id": "sync.brc136-basm",
+  "name": "BRC-136 BASM anchor vectors",
+  "brc": ["BRC-136"],
+  "version": "1.0.0",
+  "reference_impl": "packages/overlays/overlay/src/BASM.ts",
+  "parity_class": "required",
+  "vectors": [
+    {
+      "id": "sync.brc136-basm.1",
+      "description": "BASM root edge cases and odd-leaf duplication",
+      "input": {
+        "channel": "basm/root",
+        "cases": [
+          {
+            "name": "empty",
+            "txids": []
+          },
+          {
+            "name": "single",
+            "txids": ["0101010101010101010101010101010101010101010101010101010101010101"]
+          },
+          {
+            "name": "two",
+            "txids": [
+              "0101010101010101010101010101010101010101010101010101010101010101",
+              "0202020202020202020202020202020202020202020202020202020202020202"
+            ]
+          },
+          {
+            "name": "odd",
+            "txids": [
+              "0101010101010101010101010101010101010101010101010101010101010101",
+              "0202020202020202020202020202020202020202020202020202020202020202",
+              "0303030303030303030303030303030303030303030303030303030303030303"
+            ]
+          }
+        ]
+      },
+      "expected": {
+        "roots": {
+          "empty": "0000000000000000000000000000000000000000000000000000000000000000",
+          "single": "0101010101010101010101010101010101010101010101010101010101010101",
+          "two": "b4100303b9e99ada4b479b0bb93d9b549cb057a1c4be08896bc982debe20ce39",
+          "odd": "acbd47d5022a6c5e954ad677df8ec221c893f871889826df53f0f1ad3f023e22"
+        }
+      },
+      "tags": ["basm", "root", "byte-order", "odd-leaf"]
+    },
+    {
+      "id": "sync.brc136-basm.2",
+      "description": "TAC chaining uses display-order inputs but hashes internal bytes",
+      "input": {
+        "channel": "basm/tac",
+        "prevTac": "0000000000000000000000000000000000000000000000000000000000000000",
+        "blockHash": "0404040404040404040404040404040404040404040404040404040404040404",
+        "basmRoot": "acbd47d5022a6c5e954ad677df8ec221c893f871889826df53f0f1ad3f023e22"
+      },
+      "expected": {
+        "tac": "d0d3e770802c7c28ca1da59cc92263d59425f00e48d421ffebb02497b4702307"
+      },
+      "tags": ["basm", "tac", "byte-order"]
+    },
+    {
+      "id": "sync.brc136-basm.3",
+      "description": "BASM HTTP route shapes",
+      "input": {
+        "method": "POST",
+        "path": "/requestTopicAnchorTip",
+        "headers": {
+          "x-bsv-topic": "tm_example"
+        },
+        "body": {}
+      },
+      "expected": {
+        "status": 200,
+        "body": {
+          "topic": "tm_example",
+          "blockHeight": 850000,
+          "tac": "d0d3e770802c7c28ca1da59cc92263d59425f00e48d421ffebb02497b4702307"
+        }
+      },
+      "tags": ["basm", "http", "tip"]
+    },
+    {
+      "id": "sync.brc136-basm.4",
+      "description": "Raw transaction response shape for BEEF-free BASM catch-up",
+      "input": {
+        "channel": "basm/rawTransactions",
+        "message": {
+          "transactions": [
+            {
+              "txid": "0101010101010101010101010101010101010101010101010101010101010101",
+              "rawTx": "01000000000000000000"
+            }
+          ],
+          "missing": []
+        }
+      },
+      "expected": {
+        "valid": true
+      },
+      "tags": ["basm", "raw-tx"]
+    }
+  ]
+}