@ust-protocol/ots-verify 1.0.0-rc.3 → 1.0.0-rc.4

package/index.mjs

@@ -1,41 +1,59 @@
 // SPDX-License-Identifier: Apache-2.0
-// @ust-protocol/ots-verify — the OPT-IN Bitcoin substrateVerify for UST anchors (#68 Ф1b).
+// @ust-protocol/ots-verify — the OPT-IN Bitcoin substrateVerify for UST anchors (#68 Ф1b / #69 A2).
 //
 // WHY A SEPARATE PACKAGE: the zero-dependency reference verifier (ust-protocol) must never embed a
-// blockchain / the heavy opentimestamps lib — a verifier that carries a Bitcoin node is not portable.
-// resolveByDiscovery / verifyAnchor take `substrateVerify` as an OPTIONAL injection: without it, an
-// anchor is honestly `unproven` (→ "HIGH pending"); WITH this package the anchor is cross-checked against
-// Bitcoin. An integrator that wants the cross-check installs this; nobody is forced to.
+// blockchain / the heavy opentimestamps lib. resolveByDiscovery / verifyAnchor take `substrateVerify` as an
+// OPTIONAL injection: without it, an anchor is honestly `unproven`; WITH this package it is cross-checked
+// against Bitcoin.
 //
-// substrateVerify(anchor, root) → { final, time } | null  — the exact shape verifyAnchor expects:
-//   · final:true  → the root is committed in a Bitcoin block (≥ the lib's confirmation view)
-//   · final:false → the .ots is still calendar-pending (no Bitcoin attestation yet)
-//   · null        → the .ots does not attest THIS root (wrong digest) → treated as not-verified
+// #69 A2 (P0) — `isTimestampComplete()` only means "a Bitcoin attestation EXISTS in the .ots tree"; it does
+// NOT mean that block actually commits the root, nor that it is buried. A fabricated 'complete' .ots would
+// pass. So finality now REQUIRES: (1) the .ots attests THIS root; (2) the committed value equals the REAL
+// merkle root of the Bitcoin block at the attested height (fetched from a read-only explorer — public
+// consensus, the explorer only mirrors it); (3) the block is buried under >= minConfirmations (default 6,
+// §17). The explorer is untrusted: a wrong answer fails the merkle match (claim ≠ proof); unreachable →
+// `unproven`, never a false `final`.
 import { createRequire } from 'node:module';
-// the lib ships a broken package.json main; createRequire sidesteps bundlers (proven in noosphere-anchor).
+import { createHash } from 'node:crypto';
 const OTS = createRequire(import.meta.url)('opentimestamps');
 
-const hexToBytes = (hex) => { const h = hex.replace(/^sha256:/, ''); const o = new Uint8Array(h.length / 2); for (let i = 0; i < o.length; i++) o[i] = parseInt(h.substr(i * 2, 2), 16); return o; };
-const bytesEq = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+const EXPLORERS = ['https://blockstream.info/api', 'https://mempool.space/api'];
+const OTS_BTC_TAG = Buffer.from([0x05, 0x88, 0x96, 0x0d, 0x73, 0xd7, 0x19, 0x01]);
+const sha256 = (b) => createHash('sha256').update(b).digest();
+const hexToBytes = (hex) => Buffer.from(hex.replace(/^sha256:/, ''), 'hex');
+const bytesEq = (a, b) => Buffer.from(a).equals(Buffer.from(b));
 
-// Extract the Bitcoin block height (if any) from a complete timestamp's attestations.
-function bitcoinHeight(det) {
-  try {
-    for (const [, atts] of det.timestamp.allAttestations()) {
-      for (const a of (Array.isArray(atts) ? atts : [atts])) {
-        if (a && (a._type === 'BitcoinBlockHeaderAttestation' || a.constructor?.name?.includes('Bitcoin')) && typeof a.height === 'number') return a.height;
-      }
-    }
-  } catch { /* shape drift — fall through */ }
-  return null;
+// Parse an OpenTimestamps proof (canonical Timestamp.deserialize grammar: 0xff separates sibling branches at
+// a node, an op recurses into a sub-timestamp on the transformed message, an attestation fixes the node's
+// message) down to its BitcoinBlockHeaderAttestation → { height, merkle (internal byte order) }. sha256/
+// append/prepend only — an unsupported op throws and the parse fails closed. (Same logic proven in the web
+// verifier docs/ust-resolve.mjs, against a live block header.)
+export function parseOtsBitcoin(ots) {
+  let pos = 31; pos++; /* major version */ pos++; /* file-hash op */
+  const digest = ots.subarray(pos, pos + 32); pos += 32;
+  const readVarint = () => { let r = 0, sh = 0; for (;;) { const b = ots[pos++]; r += (b & 0x7f) * (2 ** sh); if (!(b & 0x80)) break; sh += 7; } return r; };
+  let found = null;
+  const applyOp = (tag, msg) => {
+    if (tag === 0xf0) { const n = readVarint(); const a = ots.subarray(pos, pos + n); pos += n; return Buffer.concat([msg, a]); }
+    if (tag === 0xf1) { const n = readVarint(); const a = ots.subarray(pos, pos + n); pos += n; return Buffer.concat([a, msg]); }
+    if (tag === 0x08) return sha256(msg);
+    throw new Error('ots op 0x' + tag.toString(16) + ' unsupported');
+  };
+  const doOne = (tag, msg) => {
+    if (tag === 0x00) {
+      const at = ots.subarray(pos, pos + 8); pos += 8; const len = readVarint(); const payload = ots.subarray(pos, pos + len); pos += len;
+      if (at.equals(OTS_BTC_TAG)) { let h = 0, sh = 0, p = 0; for (;;) { const b = payload[p++]; h += (b & 0x7f) * (2 ** sh); if (!(b & 0x80)) break; sh += 7; } found = { height: h, merkle: Buffer.from(msg) }; }
+    } else { deserialize(applyOp(tag, msg)); }
+  };
+  function deserialize(msg) { let tag = ots[pos++]; while (tag === 0xff) { doOne(ots[pos++], msg); tag = ots[pos++]; } doOne(tag, msg); }
+  deserialize(digest);
+  return found ? { height: found.height, merkle: found.merkle, digest } : null;
 }
 
-export function makeSubstrateVerify({ upgrade = true } = {}) {
+export function makeSubstrateVerify({ upgrade = true, fetchImpl = fetch, explorers = EXPLORERS, minConfirmations = 6 } = {}) {
   return async function substrateVerify(anchor, root) {
-    // handle ONLY bitcoin-ots — return null for any other substrate so a multi-substrate router
-    // (ust-protocol combineSubstrates) can delegate to the next plugin.
     const sub = anchor?.substrate ?? anchor?.anchor?.substrate;
-    if (sub && sub !== 'bitcoin-ots') return null;
+    if (sub && sub !== 'bitcoin-ots') return null;                 // not ours → router delegates onward
     const otsB64 = anchor?.ots ?? anchor?.anchor?.ots;
     if (!otsB64 || typeof root !== 'string') return null;
     let det;
@@ -47,8 +65,26 @@ export function makeSubstrateVerify({ upgrade = true } = {}) {
       try { await OTS.upgrade(det); } catch { /* calendar unreachable → stays pending */ }
     }
     if (!det.timestamp.isTimestampComplete()) return { final: false, time: 'unproven' };
-    const h = bitcoinHeight(det);
-    return { final: true, time: h ? 'bitcoin-block-' + h : 'anchored' };
+
+    // #69 A2 — parse to the Bitcoin attestation and PROVE it against the real chain (not just structure).
+    let parsed;
+    try { parsed = parseOtsBitcoin(Buffer.from(det.serializeToBytes())); } catch { return { final: false, time: 'unproven' }; }
+    if (!parsed || typeof parsed.height !== 'number') return { final: false, time: 'unproven' };
+    const wantMerkle = Buffer.from(parsed.merkle).reverse().toString('hex');   // block header displays reversed
+
+    for (const base of explorers) {
+      try {
+        const hash = (await (await fetchImpl(`${base}/block-height/${parsed.height}`, { signal: AbortSignal.timeout(10000) })).text()).trim();
+        if (!/^[0-9a-f]{64}$/.test(hash)) continue;
+        const blk = await (await fetchImpl(`${base}/block/${hash}`, { signal: AbortSignal.timeout(10000) })).json();
+        if (!blk || blk.merkle_root !== wantMerkle) return { final: false, time: 'unproven' };  // definitive NO
+        const tip = Number((await (await fetchImpl(`${base}/blocks/tip/height`, { signal: AbortSignal.timeout(10000) })).text()).trim());
+        const confirmations = Number.isFinite(tip) ? tip - parsed.height + 1 : 0;
+        if (confirmations < minConfirmations) return { final: false, time: 'unproven' };         // not yet buried
+        return { final: true, time: blk.timestamp ? new Date(blk.timestamp * 1000).toISOString().slice(0, 19) + 'Z' : 'bitcoin-block-' + parsed.height };
+      } catch { /* explorer unreachable — try the next */ }
+    }
+    return { final: false, time: 'unproven' };                    // no explorer could confirm → honest unproven
   };
 }
 

package/package.json

@@ -1,15 +1,37 @@
 {
   "name": "@ust-protocol/ots-verify",
-  "version": "1.0.0-rc.3",
-  "description": "Opt-in Bitcoin (OpenTimestamps) substrateVerify for UST anchors — the cross-check ust-protocol takes as an injection, so the zero-dep verifier never embeds a blockchain. #68 witness / TOP time.",
+  "version": "1.0.0-rc.4",
+  "description": "Opt-in Bitcoin/OpenTimestamps substrateVerify for UST anchors — cross-checks a genesis/hour root against a REAL Bitcoin block header + >=6 confirmations. #68 witness / #69 A2.",
   "type": "module",
   "main": "index.mjs",
   "exports": "./index.mjs",
-  "files": ["index.mjs", "LICENSE", "README.md"],
-  "keywords": ["ust", "opentimestamps", "bitcoin", "anchor", "substrate-verify", "witness"],
+  "files": [
+    "index.mjs",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "ust",
+    "opentimestamps",
+    "bitcoin",
+    "anchor",
+    "substrate-verify",
+    "witness"
+  ],
   "license": "Apache-2.0",
-  "engines": { "node": ">=20" },
-  "dependencies": { "opentimestamps": "^0.4.9" },
-  "repository": { "type": "git", "url": "git+https://github.com/thelabmd/UST-Protocol.git", "directory": "packages/ust-ots-verify" },
-  "homepage": "https://github.com/thelabmd/UST-Protocol/tree/main/packages/ust-ots-verify#readme"
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "opentimestamps": "^0.4.9"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thelabmd/UST-Protocol.git",
+    "directory": "packages/ust-ots-verify"
+  },
+  "homepage": "https://github.com/thelabmd/UST-Protocol/tree/main/packages/ust-ots-verify#readme",
+  "scripts": {
+    "test": "node --test"
+  }
 }