Merge pull request #135 from bsv-blockchain/infra/chaintracks-server-onboarding

infra(chaintracks-server): onboard with docs + v2 HTTP conformance vectors

Author: sirdeggen

README.md

@@ -133,6 +133,7 @@ These deployable projects are not included in `pnpm-workspace.yaml`; they keep t
 
 | Path | Package | Role |
 |---|---|---|
+| [`infra/chaintracks-server`](infra/chaintracks-server) | `chaintracks-server` private | Block header service exposing v1 + v2 REST API over `ChaintracksService` |
 | [`infra/message-box-server`](infra/message-box-server) | `@bsv/messagebox-server` private | Message box server |
 | [`infra/overlay-server`](infra/overlay-server) | `@bsv/overlay-express-examples` private | Overlay server deployment |
 | [`infra/uhrp-server-basic`](infra/uhrp-server-basic) | [`@bsv/uhrp-lite`](https://www.npmjs.com/package/@bsv/uhrp-lite) | Basic UHRP storage host |

conformance/META.json

@@ -97,12 +97,15 @@
     ],
     "message-box": [
       "messaging.messagebox-http"
+    ],
+    "chaintracks-v2": [
+      "sync.chaintracks-v2-http"
     ]
   },
   "stats": {
-    "total_files": 72,
-    "total_vectors": 6625,
-    "last_updated": "2026-05-14"
+    "total_files": 73,
+    "total_vectors": 6646,
+    "last_updated": "2026-05-19"
   },
   "regression_index": {
     "beef-v2-txid-panic": "go-sdk#306",

conformance/PARITY_MATRIX.json

@@ -4,18 +4,18 @@
   "source": "ts-stack conformance corpus",
   "description": "Machine-readable parity status for cross-language SDK implementations (Go, Rust, Python). Use this to track and drive conformance.",
   "summary": {
-    "total_files": 72,
-    "total_vectors": 6625,
-    "fully_required_files": 53,
+    "total_files": 73,
+    "total_vectors": 6646,
+    "fully_required_files": 54,
     "files_with_intended": 17,
     "files_with_mixed_status": 15,
     "vectors_by_status": {
-      "required": 6421,
+      "required": 6442,
       "intended": 204,
       "skipped": 8
     },
     "by_reason_category": {
-      "fully_supported": 1283,
+      "fully_supported": 1304,
       "historical_regression": 36,
       "partial_ts_behavioral_difference": 5116,
       "wallet_stateful_harness_required": 190
@@ -530,6 +530,18 @@
       "justification": "Runtime-state assertion; requires producer with seeded user table. Cannot be validated by shape-only dispatcher.",
       "categories": []
     },
+    {
+      "path": "sync/chaintracks-v2-http.json",
+      "id": "sync.chaintracks-v2-http",
+      "total_vectors": 21,
+      "file_level_parity": "required",
+      "effective_status": "required",
+      "required_count": 21,
+      "intended_count": 0,
+      "skipped_count": 0,
+      "reason_category": "fully_supported",
+      "categories": []
+    },
     {
       "path": "sync/gasp-protocol.json",
       "id": "sync.gasprotocol",

conformance/runner/ts/dispatchers/sync.ts

@@ -38,7 +38,8 @@ import { expect } from '@jest/globals'
 
 export const categories: ReadonlyArray<string> = [
   'gasp-protocol',
-  'brc40-user-state'
+  'brc40-user-state',
+  'chaintracks-v2-http'
 ]
 
 // ── Constants ──────────────────────────────────────────────────────────────────
@@ -704,6 +705,88 @@ function dispatchBRC40 (
   throw new Error(`sync dispatcher: unknown channel '${channel}' in brc40-user-state`)
 }
 
+// ── Chaintracks v2 HTTP vector dispatcher ──────────────────────────────────────
+//
+// Structural validation of the chaintracks-server v2 REST contract. Cross-language
+// implementations replace this with real HTTP calls against a running server;
+// here we only assert that each vector's expected payload obeys the v2 envelope
+// rules so the corpus stays well-formed.
+
+const V2_PATH_RE = /^\/v2\/(network|tip(?:\.bin)?|header\/height\/.+|header\/hash\/.+|headers(?:\.bin)?)$/
+const V2_ERROR_CODES: ReadonlySet<string> = new Set([
+  'ERR_INVALID_PARAMS',
+  'ERR_NOT_FOUND',
+  'ERR_NO_TIP',
+  'ERR_INTERNAL'
+])
+
+function assertSuccessEnvelope (eb: Record<string, unknown>): void {
+  expect(eb['status']).toBe('success')
+  expect('value' in eb).toBe(true)
+}
+
+function assertErrorEnvelope (eb: Record<string, unknown>): void {
+  expect(eb['status']).toBe('error')
+  const code = eb['code']
+  expect(typeof code).toBe('string')
+  expect(V2_ERROR_CODES.has(code as string)).toBe(true)
+  expect(typeof eb['description']).toBe('string')
+}
+
+function assertBinaryShape (shape: Record<string, unknown>): void {
+  expect(shape['encoding']).toBe('binary')
+  const len = shape['length_bytes']
+  // length_bytes may be a fixed integer or a formula string for variable-length payloads.
+  if (typeof len === 'number') {
+    expect(Number.isInteger(len) && len >= 0).toBe(true)
+    const stride = shape['stride']
+    if (typeof stride === 'number') {
+      expect(len % stride).toBe(0)
+    }
+  } else {
+    expect(typeof len).toBe('string')
+  }
+}
+
+function dispatchChaintracksV2 (
+  input: Record<string, unknown>,
+  expected: Record<string, unknown>
+): void {
+  const method = getString(input, 'method')
+  const path = getString(input, 'path')
+  expect(method).toBe('GET')
+  expect(V2_PATH_RE.test(path)).toBe(true)
+
+  const status = getNumber(expected, 'status')
+  expect([200, 400, 404].includes(status)).toBe(true)
+
+  if (status >= 400) {
+    const body = expected['body']
+    expect(body !== undefined).toBe(true)
+    assertErrorEnvelope(body as Record<string, unknown>)
+    return
+  }
+
+  // Success path — either a JSON envelope (body) or a binary shape (body_shape).
+  const hasJson = expected['body'] !== undefined
+  const hasShape = expected['body_shape'] !== undefined
+  expect(hasJson || hasShape).toBe(true)
+
+  if (hasJson) {
+    assertSuccessEnvelope(expected['body'] as Record<string, unknown>)
+  }
+  if (hasShape) {
+    const shape = expected['body_shape'] as Record<string, unknown>
+    if (shape['encoding'] === 'binary') {
+      assertBinaryShape(shape)
+    } else {
+      // JSON success shape — must describe a {status, value} envelope.
+      expect(shape['status']).toBe('success')
+      expect('value' in shape).toBe(true)
+    }
+  }
+}
+
 // ── Main dispatch entry point ──────────────────────────────────────────────────
 
 export function dispatch (
@@ -715,6 +798,10 @@ export function dispatch (
     dispatchBRC40(input, expected)
     return
   }
+  if (category === 'chaintracks-v2-http') {
+    dispatchChaintracksV2(input, expected)
+    return
+  }
   if (category !== 'gasp-protocol') {
     throw new Error(`sync dispatcher: unknown category '${category}'`)
   }