@bsv/overlay 2.0.2 → 2.0.4

package/docs/BRC-136-BASM.md

@@ -0,0 +1,285 @@
+# BRC-136 BASM Synchronization & Admin/Janitor Removal
+
+This document explains how the BRC-136 Block-Anchored synchronization layer
+([spec](https://bsv.brc.dev/overlays/0136)) is implemented in this engine, and —
+critically — **how it interacts with admin and janitor removal of outputs from a
+topic**. The two systems are deliberately decoupled. Read the final section
+("How BASM and removal interact") before operating a node that runs the janitor
+or removes tokens via the admin API.
+
+## What BRC-136 gives you
+
+GASP ([Synchronization.md](./Synchronization.md)) replicates transaction *data*
+between peers. BRC-136 sits alongside it and answers a different question:
+
+> Do two overlays **agree about which transactions were admitted to a topic** at
+> every block height, from the topic's genesis to the chain tip?
+
+It does this with a per-topic **Topic Anchor Chain (TAC)** — a cumulative hash
+that commits to every block's admitted-transaction set. If two nodes report the
+same `TAC(topic, H)`, they provably agree on every admitted transaction for that
+topic from genesis through height `H`. A single round trip detects agreement; a
+binary search over heights localizes any divergence in `O(log H)` rounds.
+
+### Core data structures
+
+| Concept | Type | Source of truth |
+|---|---|---|
+| Admitted set at a block | `AdmittedTxRef[]` | `applied_transactions` table |
+| Block anchor | `TopicBlockAnchor` | `topic_block_anchors` table |
+| Cumulative chain hash | `tac` field on the anchor | derived |
+
+- **`basmRoot`** — Merkle root over the admitted txids at one block height, in
+  canonical block order. Empty set → 32 zero bytes; single txid → the txid
+  itself (unhashed); multiple → `SHA256d` binary tree with Bitcoin odd-leaf
+  duplication. See `computeBasmRoot` in `src/BASM.ts`.
+- **`tac`** — `SHA256d(prevTac ‖ blockHash ‖ basmRoot)`, all inputs in internal
+  byte order. See `computeTac` in `src/BASM.ts`.
+
+### Gap-free chains
+
+The TAC must advance on **every** block — including blocks with no admitted
+transactions — or peers could not distinguish "no transactions here" from "I
+haven't synced this height." The engine keeps chains contiguous:
+
+- `advanceTopicAnchorChains(toHeight)` extends each topic forward with empty
+  anchors (zero root, zero count) up to `toHeight`.
+- `rebuildTopicAnchorChain(...)` / `recomputeTopicBlockAnchor(...)` rebuild a
+  contiguous slice after an admission (including out-of-order proofs), filling
+  any missing heights with empty anchors rather than leaving a hole.
+
+A chain only *starts* at the topic's first admitted height (its genesis).
+Covered by `src/__tests/BASMChain.test.ts`.
+
+## The admitted set is a historical fact, not current UTXO state
+
+This is the key design decision, and the source of the assurance this layer
+provides.
+
+The admitted set for `(topic, height)` is read by
+`Storage.findAdmittedTransactionsForBlock`, which queries:
+
+```
+applied_transactions WHERE topic = ? AND blockHeight = ? AND proven = true AND blockIndex IS NOT NULL
+```
+
+It is **append-only for proven transactions**. A row lands here when a
+transaction is admitted to the topic and has a merkle proof
+(`buildAppliedTransactionRecord` sets `proven: true` only when proof metadata is
+present). From that point the row — and therefore the `basmRoot` and `tac` that
+commit to it — is an immutable record of "this overlay received and admitted
+this txid at this block height."
+
+It is **not** derived from current unspent outputs. Spending an output, pruning
+its history, or removing it from lookup does not change the admitted set.
+
+## The lookup set is separate, mutable, and policy-driven
+
+What an overlay *serves* in lookup responses is a different set, in different
+storage:
+
+- The engine `outputs` table, filtered to `spent: false`.
+- The lookup service's own index (e.g. the Mongo `shipRecords` / `slapRecords`
+  collections for the discovery services).
+
+This set is mutable by design. Outputs get marked spent, pruned from history,
+removed by an admin, or deleted by the janitor.
+
+## Removal paths — exactly what each one touches
+
+| Path | Code | Touches lookup set | Touches admitted set (`applied_transactions`) |
+|---|---|---|---|
+| Spend / history prune | `Engine.deleteUTXODeep` → `deleteOutput` | yes | **no** |
+| Admin remove-token | `/admin/remove-token` → `evictFromServices` → `LookupService.outputEvicted` | yes (lookup index) | **no** |
+| Janitor (dead SHIP/SLAP host) | `JanitorService.handleUnhealthyOutput` → `deleteOne` + ban | yes (lookup index) | **no** |
+| Ban enforcement | `BanAwareLookupWrapper.outputAdmittedByTopic` | blocks re-entry into lookup index on GASP re-sync | **no** |
+| Unproven eviction | `Engine.evictUnprovenTransactions` → `deleteAppliedTransaction` | yes | yes — **but only `proven: false` rows** |
+
+Notes:
+
+- **`deleteUTXODeep` never deletes the applied-transaction record.** It calls
+  `deleteOutput` only. The admission proof survives a normal spend or prune.
+- **Admin and janitor removal operate on the lookup layer only.** Admin
+  `evictFromServices` calls `LookupService.outputEvicted`; the janitor deletes
+  from its own Mongo collection and writes to the ban list. Neither calls
+  `deleteAppliedTransaction`, `deleteOutput` on proven engine state, or anything
+  that mutates `topic_block_anchors`.
+- **The ban list is a lookup-layer filter.** `BanAwareLookupWrapper` blocks
+  banned outpoints/domains at `outputAdmittedByTopic`, preventing a removed token
+  from re-entering the *lookup index* when GASP re-syncs it from a peer. It does
+  not — and must not — block the BRC-136 admitted record.
+- **`evictUnprovenTransactions` is the only path that deletes an
+  applied-transaction row**, and it filters to `proven: false`. Such rows never
+  appear in any anchor (the anchor query requires `proven: true`), so evicting
+  them cannot change any `basmRoot` or `tac`.
+
+## How BASM and removal interact
+
+This is the question operators most need answered.
+
+### You can always prove you received and processed a token
+
+Even after the janitor deletes a dead host's advertisement, or an admin removes a
+malicious output via `/admin/remove-token` (with or without a ban), the overlay
+**retains full proof that it received and admitted that token**:
+
+- the `applied_transactions` row (`proven: true`, with `blockHeight`,
+  `blockIndex`, `blockHash`, `merkleRoot`),
+- the `topic_block_anchors` row whose `basmRoot` commits to that txid, and
+- the ability to serve a compound merkle path for it via the BRC-136 endpoints.
+
+Removal is a **lookup-serving policy decision**. It changes what the node returns
+to lookup queries. It does not, and cannot, rewrite the historical admitted set
+or the TAC.
+
+### TAC agreement means agreement on *admission*, not on *lookup results*
+
+This is the most important operational caveat:
+
+> **A matching TAC proves two overlays agree on which transactions were admitted.
+> It does NOT prove they will return identical lookup results.**
+
+Bans and removals are **per-node policy and are not synchronized between peers**.
+Two honest overlays running the same topic manager can therefore:
+
+- report the **same** `TAC(topic, H)` (identical admitted sets), while
+- returning **different** lookup results — because one node banned a malicious
+  output that the other still serves.
+
+This is correct and intended. BRC-136 anchors *receipt and admission*, which is
+an objective, deterministic function of chain state and the topic manager. It
+intentionally does not anchor each node's local moderation policy.
+
+### Consequence: divergence diagnosis
+
+- **TACs match** → the two nodes admitted exactly the same transactions. Any
+  difference in lookup output is explained by local removal/ban policy, not by a
+  sync problem.
+- **TACs diverge** → the nodes genuinely disagree about admission at some height
+  (e.g. different topic-manager versions, a missed transaction, or a reorg
+  handled differently). This is a real sync issue; the binary-search localizes
+  the height.
+
+Removing a token from lookup will **not** cause TAC divergence. If you ever see
+TAC divergence after only running the janitor/admin removal, that is a bug —
+something is incorrectly deleting proven `applied_transactions` rows or mutating
+anchors.
+
+### Caveat for the GASP validation guidance
+
+[Synchronization.md](./Synchronization.md) suggests validating sync by comparing
+per-topic SQL row counts across nodes. Once the janitor or admin removal is
+active, **lookup-set counts can legitimately differ between nodes even when their
+TACs match**. To validate BRC-136 agreement, compare `TAC(topic, tip)` between
+peers — not lookup row counts.
+
+## Reorg handling
+
+A blockchain reorganization can orphan a block whose transactions were already
+admitted and anchored. Since anchors and the admitted set are keyed by
+`(topic, blockHeight, blockHash)`, an orphaned block would otherwise leave stale
+`applied_transactions` rows and an anchor whose `basmRoot`/`tac` commit to a
+block hash that is no longer canonical — permanently diverging the TAC from peers
+that observed the reorg. The engine reconciles this automatically.
+
+### Chaintracks is the reorg authority
+
+Reorg detection is **not** reinvented here. The production chain tracker is
+Arcade, which wraps go-chaintracks; its reorg SSE is the source of truth:
+
+- **`GET /v2/reorg/stream`** emits `data: <JSON>\n\n` frames (no `event:`/`id:`
+  lines; `: keepalive` comments between events). Each frame is a `ReorgEvent`:
+
+  ```jsonc
+  {
+    "orphanedHashes": ["<blockHash>", ...], // blocks removed from the active chain
+    "commonAncestor": { "height": 100, "hash": "..." },
+    "newTip":         { "height": 103, "hash": "..." },
+    "depth": 3
+  }
+  ```
+
+- The same go-chaintracks service answers the merkle-root checks
+  (`isValidRootForHeight`) the engine already trusts for all SPV verification.
+
+`packages/overlays/overlay-express/src/ReorgStream.ts` consumes this stream and
+maps each event to the engine: `orphanedHashes` → blocks to reconcile,
+`commonAncestor.height + 1` → rebuild floor, `newTip.height` → rebuild ceiling.
+Block hashes are lower-cased to match stored display-hex hashes (go-sdk
+`chainhash.Hash` marshals as reversed/display hex).
+
+> **No replay on this stream.** It carries no event ids, so a reorg that fires
+> while the SSE client is disconnected is lost. Every (re)connect therefore runs a
+> catch-up revalidation sweep (below), and the periodic block poll runs the same
+> sweep as a standing fallback for chain trackers that expose no reorg stream.
+
+### What the engine does on a reorg — `Engine.handleReorg`
+
+1. **Demote orphaned admissions.** For each orphaned block hash, every **proven**
+   `applied_transactions` row anchored to it is demoted to unproven
+   (`demoteAppliedTransactionToUnproven`): block height/hash/index/merkleRoot are
+   cleared and `proven` is set to `false`, **but `firstSeenHeight` is kept**. The
+   transaction immediately leaves the admitted set.
+2. **Rebuild affected anchor chains.** Every topic whose chain intersects the
+   reorged height range is rebuilt over the **canonical** block hashes (the rebuild
+   forces header re-resolution rather than reusing the stale stored hash). Topics
+   with no demoted transaction are rebuilt too, because the canonical block hash
+   for those heights changed and the `tac` must re-chain over it.
+
+`handleReorg` is **idempotent**: a clean window demotes nothing and reproduces an
+identical TAC, so it is safe to run on every reorg event, SSE reconnect, and poll.
+
+### Fallback / catch-up — `Engine.revalidateRecentAnchors(depth = 3)`
+
+Scans proven `applied_transactions` in `[tip - depth + 1, tip]`. Any row whose
+proof root no longer validates (`isValidRootForHeight`) or whose block hash
+diverges from the canonical header is treated as orphaned and fed into
+`handleReorg`. This is the reorg path for chain trackers without a reorg stream,
+and the catch-up step on every SSE reconnect. Default depth is 3 blocks
+(`reorgScanDepth`, configurable via `configureReorgStream`).
+
+### Interaction with admin/janitor removal
+
+Reorg recovery and lookup-layer removal are independent and do not interfere:
+
+- Removal/bans touch only the lookup layer; they never demote `applied_transactions`.
+- Reorg demotion touches only the admitted set (proven → unproven) via the chain
+  tracker; it never consults the ban list or lookup index.
+
+A demoted transaction follows the engine's existing unproven lifecycle: if it is
+re-mined, Arcade/ARC re-notifies `/arc-ingest` → `handleNewMerkleProof` re-proves
+it at its new height and the anchor includes it again; if it is never re-mined,
+`evictUnprovenTransactions` removes it after the threshold. The "we received it"
+record survives until one of those resolves.
+
+### Configuration
+
+```ts
+server.configureReorgStream('https://arcade.example/v2/reorg/stream', 3)
+```
+
+- `reorgStreamUrl` — when set, the SSE adapter reconciles reorgs in real time.
+- `reorgScanDepth` — sweep depth from tip (default `3`).
+- The block poll (`basmBlockPollIntervalMs`) runs the sweep as a fallback even
+  when no stream is configured.
+
+## Verification checklist for operators
+
+1. After removing a token, confirm its `applied_transactions` row still exists
+   (`proven: true`) and the `topic_block_anchors` row for its height is unchanged.
+2. Confirm `TAC(topic, tip)` is unchanged by the removal.
+3. Confirm the token no longer appears in lookup responses (and, if banned, does
+   not reappear after a GASP re-sync).
+
+If all three hold, removal is behaving correctly: the node no longer serves the
+token, yet can still prove it was received and admitted.
+
+### Reorg verification
+
+4. After a reorg orphans an admitted transaction's block, confirm its
+   `applied_transactions` row is demoted (`proven: false`, block fields cleared,
+   `firstSeenHeight` retained) and the affected `topic_block_anchors` rows now
+   carry the canonical block hashes with a recomputed `tac`.
+5. Confirm `TAC(topic, tip)` reconverges with peers that observed the same reorg.
+6. If the orphaned transaction is re-mined, confirm `/arc-ingest` re-proves it and
+   the anchor re-includes it; otherwise confirm it is eventually evicted as unproven.

package/docs/README.md

@@ -5,6 +5,8 @@ The documentation is split into various pages, each covering a set of related fu
 ## Main Documentation
 
 - [API](./API.md) — How to interact with the Overlay Services Engine
+- [Synchronization](./Synchronization.md) — GASP peer synchronization
+- [BRC-136 BASM](./BRC-136-BASM.md) — Block-anchored sync, and how it interacts with admin/janitor removal
 - [Concepts](./concepts/README.md) — High-level concepts
 - [Examples](./examples/README.md) — Guides, tutorials and examples of using the Engine
 - [Internal](./internal/README.md) — References for working with internal system components

package/docs/Synchronization.md

@@ -200,4 +200,13 @@ Example (adapt the table/query to your schema):
 +-------------+------+
 ```
 
-**What you’re looking for:** the topic(s) you care about (e.g. tm_plite, tm_blockbeta) should move toward the same counts/data across nodes after sync, and your lookup results for identical queries should converge as well.
+**What you’re looking for:** the topic(s) you care about (e.g. tm_plite, tm_blockbeta) should move toward the same counts/data across nodes after sync, and your lookup results for identical queries should converge as well.
+
+> **Caveat (BRC-136 / janitor / admin removal):** Row-count comparison is only a
+> valid convergence check on nodes that do **not** remove outputs locally. Once
+> the janitor or `/admin/remove-token` is active, lookup-set counts can
+> legitimately differ between peers even when they fully agree on what was
+> admitted, because bans/removals are per-node policy and are not synchronized.
+> To verify that two nodes agree on which transactions were admitted to a topic,
+> compare their per-topic Topic Anchor Chain (`TAC`) at the tip rather than
+> lookup row counts. See [BRC-136 BASM](./BRC-136-BASM.md).

package/mod.ts

@@ -10,7 +10,31 @@ export type { TaggedBEEF, STEAK, LookupQuestion, LookupAnswer, AdmittanceInstruc
 export type { LookupFormula } from './src/LookupFormula.js'
 export type { Advertisement } from './src/Advertisement.js'
 export type { AdvertisementData, Advertiser } from './src/Advertiser.js'
+export {
+  BASM_ZERO_HASH,
+  computeBasmRoot,
+  computeTac,
+  extractMerkleProofMetadata
+} from './src/BASM.js'
+export type {
+  AdmittedListRequest,
+  AdmittedListResponse,
+  AdmittedTxRef,
+  BASMPeerSyncReport,
+  CompoundMerklePathRequest,
+  CompoundMerklePathResponse,
+  MerkleProofMetadata,
+  RawTransactionRecord,
+  RawTransactionRequest,
+  RawTransactionResponse,
+  TopicAnchorHeader,
+  TopicAnchorHeaderResolver,
+  TopicAnchorRangeRequest,
+  TopicAnchorRangeResponse,
+  TopicAnchorTip,
+  TopicBlockAnchor
+} from './src/BASM.js'
 
 // The Knex storage system
 export { KnexStorage } from './src/storage/knex/KnexStorage.js'
-export * as KnexStorageMigrations from './src/storage/knex/all-migrations.js'
+export * as KnexStorageMigrations from './src/storage/knex/all-migrations.js'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bsv/overlay",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "type": "module",
   "description": "BSV Blockchain Overlay Services Engine",
   "main": "dist/cjs/mod.js",
@@ -35,20 +35,10 @@
       "types": "./dist/types/src/storage/*.d.ts"
     }
   },
-  "scripts": {
-    "test": "npm run build && jest",
-    "test:watch": "npm run build && jest --watch",
-    "test:coverage": "npm run build && jest --coverage",
-    "lint": "ts-standard --fix src/**/*.ts",
-    "lint:ci": "ts-standard src/**/*.ts",
-    "build": "tsc -b && tsconfig-to-dual-package tsconfig.cjs.json",
-    "dev": "tsc -b -w",
-    "prepublish": "npm run build",
-    "doc": "ts2md --inputFilename=mod.ts --outputFilename=docs/API.md --filenameSubstring=API --firstHeadingLevel=1"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/bsv-blockchain/overlay-services.git"
+    "url": "git+https://github.com/bsv-blockchain/ts-stack.git",
+    "directory": "packages/overlays/overlay"
   },
   "keywords": [
     "BSV",
@@ -60,21 +50,33 @@
   "author": "BSV Association",
   "license": "SEE LICENSE IN LICENSE.txt",
   "bugs": {
-    "url": "https://github.com/bitcoin-sv/overlay-services/issues"
+    "url": "https://github.com/bsv-blockchain/ts-stack/issues"
   },
-  "homepage": "https://github.com/bitcoin-sv/overlay-services#readme",
+  "homepage": "https://github.com/bsv-blockchain/ts-stack/tree/main/packages/overlays/overlay#readme",
   "devDependencies": {
-    "@types/jest": "^29.5.12",
-    "jest": "^29.7.0",
-    "ts-jest": "^29.1.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.9.3",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
     "ts-standard": "^12.0.2",
     "ts2md": "^0.2.0",
     "tsconfig-to-dual-package": "^1.2.0",
-    "typescript": "^5.2.2"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@bsv/gasp": "^1.2.2",
-    "@bsv/sdk": "^2.0.4",
-    "knex": "^3.1.0"
+    "@bsv/gasp": "^1.2.3",
+    "@bsv/sdk": "^2.1.4",
+    "knex": "^3.2.10"
+  },
+  "scripts": {
+    "test": "npm run build && jest",
+    "test:watch": "npm run build && jest --watch",
+    "test:coverage": "npm run build && jest --coverage",
+    "lint": "ts-standard --fix src/**/*.ts",
+    "lint:ci": "ts-standard src/**/*.ts",
+    "build": "tsc -b && tsconfig-to-dual-package tsconfig.cjs.json",
+    "dev": "tsc -b -w",
+    "prepublish": "npm run build",
+    "doc": "ts2md --inputFilename=mod.ts --outputFilename=docs/API.md --filenameSubstring=API --firstHeadingLevel=1"
   }
-}
+}

package/src/BASM.ts

@@ -0,0 +1,208 @@
+import { createHash } from 'node:crypto'
+import { MerklePath } from '@bsv/sdk'
+
+export const BASM_ZERO_HASH = '0000000000000000000000000000000000000000000000000000000000000000'
+
+export interface TopicBlockAnchor {
+  topic: string
+  blockHeight: number
+  blockHash: string
+  basmRoot: string
+  admittedCount: number
+  tac: string
+}
+
+export interface TopicAnchorTip {
+  topic: string
+  blockHeight: number
+  blockHash?: string
+  basmRoot?: string
+  admittedCount?: number
+  tac: string
+}
+
+export interface AdmittedTxRef {
+  txid: string
+  blockIndex: number
+}
+
+export interface RawTransactionRecord {
+  txid: string
+  rawTx: string
+}
+
+export interface RawTransactionRequest {
+  txids: string[]
+}
+
+export interface RawTransactionResponse {
+  transactions: RawTransactionRecord[]
+  missing: string[]
+}
+
+export interface TopicAnchorHeader {
+  blockHeight: number
+  blockHash: string
+  merkleRoot?: string
+}
+
+export type TopicAnchorHeaderResolver = (blockHeight: number) => Promise<TopicAnchorHeader | undefined>
+
+export interface TopicAnchorRangeRequest {
+  fromHeight: number
+  toHeight: number
+}
+
+export interface TopicAnchorRangeResponse {
+  topic: string
+  anchors: TopicBlockAnchor[]
+}
+
+export interface AdmittedListRequest {
+  blockHeight: number
+  blockHash?: string
+}
+
+export interface AdmittedListResponse {
+  topic: string
+  blockHeight: number
+  blockHash?: string
+  admitted: AdmittedTxRef[]
+}
+
+export interface CompoundMerklePathRequest {
+  blockHeight: number
+  txids: string[]
+}
+
+export interface CompoundMerklePathResponse {
+  topic: string
+  blockHeight: number
+  txids: string[]
+  merklePath: string
+}
+
+export interface MerkleProofMetadata {
+  blockHeight: number
+  blockIndex: number
+  merkleRoot: string
+}
+
+export interface ReorgReport {
+  perTopic: Array<{
+    topic: string
+    demotedTxids: string[]
+    rebuiltFrom: number
+    rebuiltTo: number
+  }>
+}
+
+export interface BASMPeerSyncReport {
+  topic: string
+  endpoint: string
+  status: 'matched' | 'advanced' | 'diverged' | 'skipped' | 'error'
+  localTip?: TopicAnchorTip
+  remoteTip?: TopicAnchorTip
+  checkedHeights: number[]
+  missingTxids: string[]
+  fetchedTxCount: number
+  message?: string
+}
+
+type AdmittedTxLike = string | AdmittedTxRef
+
+function sha256d(buffer: Buffer): Buffer {
+  const first = createHash('sha256').update(buffer).digest()
+  return createHash('sha256').update(first).digest()
+}
+
+function assertHashHex(hash: string, label: string): void {
+  if (!/^[0-9a-fA-F]{64}$/.test(hash)) {
+    throw new Error(`${label} must be 32 bytes of hex`)
+  }
+}
+
+function displayHexToInternal(hash: string): Buffer {
+  assertHashHex(hash, 'hash')
+  return Buffer.from(hash, 'hex').reverse()
+}
+
+function internalToDisplayHex(hash: Buffer): string {
+  return Buffer.from(hash).reverse().toString('hex')
+}
+
+function normalizeAdmittedTxids(admitted: AdmittedTxLike[]): string[] {
+  return admitted
+    .map((item, originalIndex) => {
+      if (typeof item === 'string') {
+        return { txid: item, blockIndex: originalIndex }
+      }
+      return item
+    })
+    .sort((a, b) => a.blockIndex - b.blockIndex)
+    .map(item => item.txid.toLowerCase())
+}
+
+/**
+ * Computes a BRC-136 BASM root from admitted topic txids.
+ *
+ * The API accepts normal display-order txid hex because that is what the BSV
+ * TypeScript stack exposes at its public boundaries. Hashing is performed on
+ * internal byte order as required by the BRC, and the returned root is display
+ * order for JSON/wire compatibility.
+ */
+export function computeBasmRoot(admitted: AdmittedTxLike[]): string {
+  const txids = normalizeAdmittedTxids(admitted)
+
+  if (txids.length === 0) {
+    return BASM_ZERO_HASH
+  }
+
+  let layer = txids.map(txid => displayHexToInternal(txid))
+  if (layer.length === 1) {
+    return internalToDisplayHex(layer[0])
+  }
+
+  while (layer.length > 1) {
+    const next: Buffer[] = []
+    for (let i = 0; i < layer.length; i += 2) {
+      const left = layer[i]
+      const right = i + 1 < layer.length ? layer[i + 1] : left
+      next.push(sha256d(Buffer.concat([left, right])))
+    }
+    layer = next
+  }
+
+  return internalToDisplayHex(layer[0])
+}
+
+/**
+ * Computes the BRC-136 cumulative Topic Anchor Chain hash:
+ * SHA256d(prevTac || blockHash || basmRoot), with all inputs reversed to
+ * internal byte order before hashing and the output returned as display hex.
+ */
+export function computeTac(prevTac: string, blockHash: string, basmRoot: string): string {
+  const input = Buffer.concat([
+    displayHexToInternal(prevTac.toLowerCase()),
+    displayHexToInternal(blockHash.toLowerCase()),
+    displayHexToInternal(basmRoot.toLowerCase())
+  ])
+  return internalToDisplayHex(sha256d(input))
+}
+
+export function extractMerkleProofMetadata(txid: string, proof?: MerklePath): MerkleProofMetadata | undefined {
+  if (proof === undefined) {
+    return undefined
+  }
+
+  const leaf = proof.path[0]?.find(candidate => candidate.hash === txid)
+  if (leaf === undefined) {
+    return undefined
+  }
+
+  return {
+    blockHeight: proof.blockHeight,
+    blockIndex: leaf.offset,
+    merkleRoot: proof.computeRoot(txid)
+  }
+}

package/src/BASMRemote.ts

@@ -0,0 +1,54 @@
+import type {
+  AdmittedListResponse,
+  CompoundMerklePathResponse,
+  RawTransactionResponse,
+  TopicAnchorRangeResponse,
+  TopicAnchorTip
+} from './BASM.js'
+
+export class BASMRemote {
+  constructor(
+    private readonly endpoint: string,
+    private readonly topic: string,
+    private readonly fetchImpl: typeof fetch = fetch.bind(globalThis)
+  ) { }
+
+  async requestTopicAnchorTip(): Promise<TopicAnchorTip> {
+    return await this.post<TopicAnchorTip>('/requestTopicAnchorTip', {})
+  }
+
+  async requestTopicAnchorRange(fromHeight: number, toHeight: number): Promise<TopicAnchorRangeResponse> {
+    return await this.post<TopicAnchorRangeResponse>('/requestTopicAnchorRange', { fromHeight, toHeight })
+  }
+
+  async requestAdmittedList(blockHeight: number, blockHash?: string): Promise<AdmittedListResponse> {
+    return await this.post<AdmittedListResponse>('/requestAdmittedList', { blockHeight, blockHash })
+  }
+
+  async requestCompoundMerklePath(blockHeight: number, txids: string[]): Promise<CompoundMerklePathResponse> {
+    return await this.post<CompoundMerklePathResponse>('/requestCompoundMerklePath', { blockHeight, txids })
+  }
+
+  async requestRawTransactions(txids: string[]): Promise<RawTransactionResponse> {
+    return await this.post<RawTransactionResponse>('/requestRawTransactions', { txids })
+  }
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const response = await this.fetchImpl(new URL(path, this.endpoint).toString(), {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        'x-bsv-topic': this.topic
+      },
+      body: JSON.stringify(body)
+    })
+
+    const text = await response.text()
+    if (!response.ok) {
+      throw new Error(`BASM peer ${this.endpoint} returned ${response.status}: ${text}`)
+    }
+
+    return (text.length === 0 ? {} : JSON.parse(text)) as T
+  }
+}