btcnotar 0.1.0 → 0.2.1

package/README.md

@@ -1,174 +1,240 @@
 # btcnotar
 
-Batch Bitcoin notarization for Node.js.
+**Prove that a text or a file existed at a certain time — using the Bitcoin blockchain.**
 
-`btcnotar` collects document hashes, combines them into a **Merkle tree**,
-and anchors only the tree's root on the Bitcoin blockchain via a single
-`OP_RETURN` transaction — automatically, on a schedule (once a day by
-default). Each individual hash gets back a small **inclusion proof** that
-lets anyone later prove — unambiguously, against the live chain, down to
-the transaction id, block and date — that their document was notarized,
-without needing the rest of the batch.
+- **Free.** No Bitcoin, no wallet, no key. The public server pays the fee.
+- **Private.** Only the SHA-256 hash is sent. Your file never leaves your computer.
+- **Trustless.** `verify()` checks the proof directly on the blockchain, not on our server.
 
-## Why batching
+```bash
+npm install btcnotar
+```
 
-Anchoring one hash per transaction is expensive and doesn't scale. Batching
-thousands of hashes into one Merkle root per settlement means:
+---
 
-- **One on-chain transaction settles an unlimited number of documents.**
-- **Cheap**: fees are paid once per batch, not per document.
-- **Reversible / verifiable**: given only your original hash and its proof,
-  you can recompute the Merkle root and confirm it matches what's actually
-  on-chain — no trust in the notary's database required.
+## Easy examples
 
-## Install
+All examples use the free public server. Save them as `.mjs` files and run with `node`.
 
-```bash
-npm install btcnotar
+### 1. Notarize a text
+
+```js
+// notarize-text.mjs
+import { BTCNotarClient, sha256Hex } from "btcnotar";
+
+const client = new BTCNotarClient();
+const hash = sha256Hex("Hello, Bitcoin!");
+
+const result = await client.submit(hash);
+console.log(result);
+// { status: "pending", hash: "...", nextSettleAt: "2026-10-25T15:00:00.000Z" }
 ```
 
-## Quick start
+`pending` means: your hash is in the queue. It goes on the blockchain at `nextSettleAt` (about 1 hour).
+
+### 2. Check it later
 
 ```js
-import { BTCNotar, FileStore } from "btcnotar";
+// check-text.mjs
+import { BTCNotarClient, sha256Hex } from "btcnotar";
+
+const client = new BTCNotarClient();
+const result = await client.verify(sha256Hex("Hello, Bitcoin!"));
+
+if (result.valid) {
+  console.log("On the blockchain!");
+  console.log("Date: ", result.date);
+  console.log("Block:", result.blockHeight);
+  console.log("Tx:   ", `https://mempool.space/tx/${result.txid}`);
+} else {
+  console.log("Not yet:", result.reason); // "pending" = still waiting
+}
+```
 
-const notary = new BTCNotar({
-  wif: process.env.BTCNOTAR_WIF,       // Bitcoin private key (WIF) that funds/signs anchor txs
-  network: "mainnet",                   // or "testnet"
-  store: new FileStore({ filePath: "./.btcnotar/store.json" }),
-  intervalMs: 24 * 60 * 60 * 1000,      // settle once a day (default)
-});
+### 3. Notarize a file
+
+```js
+// notarize-file.mjs
+import fs from "node:fs";
+import { BTCNotarClient, sha256Hex } from "btcnotar";
 
-// 1. Queue hashes as documents come in (e.g. sha256 of a file)
-await notary.addHash("2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881");
+const client = new BTCNotarClient();
+const hash = sha256Hex(fs.readFileSync("contract.pdf"));
 
-// 2. Start automatic daily settlement (builds the Merkle tree + broadcasts
-//    one OP_RETURN transaction anchoring the root)
-notary.start();
+console.log("SHA-256:", hash);
+console.log(await client.submit(hash));
+```
 
-// ... later, anywhere, even in a different process that only has the hash ...
+Keep the file **exactly as it is**. If one byte changes, the hash changes and the proof will not match.
 
-const proof = await notary.getProof(hash);
-// { hash, merkleRoot, proof, txid, batchId, blockHeight, blockHash, blockTime, ... }
+### 4. Many texts, save results, check later
 
-const result = await notary.verify(hash);
-// {
-//   valid: true,
-//   confirmed: true,
-//   txid: "…",
-//   blockHeight: 912345,
-//   blockHash: "…",
-//   date: "2026-09-10T00:00:00.000Z",
-//   merkleRoot: "…",
-// }
+```js
+// many.mjs
+import fs from "node:fs";
+import { BTCNotarClient, sha256Hex } from "btcnotar";
+
+const client = new BTCNotarClient();
+const texts = ["first text", "second text", "third text"];
+
+const results = [];
+for (const text of texts) {
+  const hash = sha256Hex(text);
+  const r = await client.submit(hash);
+  results.push({ text, hash, status: r.status, nextSettleAt: r.nextSettleAt });
+}
+
+fs.writeFileSync("results.json", JSON.stringify(results, null, 2));
+console.log("Saved to results.json");
 ```
 
-`verify()` does two independent checks before it reports `valid: true`:
+```js
+// check-many.mjs
+import fs from "node:fs";
+import { BTCNotarClient } from "btcnotar";
 
-1. **Cryptographic**: recomputes the Merkle root from the hash + its proof
-   and checks it equals the stored root.
-2. **On-chain**: fetches the anchoring transaction live from the blockchain
-   and confirms its `OP_RETURN` output actually carries that same root.
+const client = new BTCNotarClient();
+const results = JSON.parse(fs.readFileSync("results.json", "utf8"));
 
-Only when both agree is the hash reported as anchored — together with the
-transaction id, block hash/height and date, so "is this document on the
-blockchain, and when/where" has one unambiguous answer.
+for (const item of results) {
+  const r = await client.verify(item.hash);
+  console.log(item.text, "->", r.valid ? `YES, block ${r.blockHeight}, ${r.date}` : `not yet (${r.reason})`);
+}
+```
 
-## API
+All texts sent in the same hour go into **one** Bitcoin transaction.
 
-### `new BTCNotar(options)`
-
-| option        | required | default             | description |
-|---------------|----------|---------------------|-------------|
-| `wif`         | yes      | —                   | Bitcoin private key (WIF) used to fund and sign anchor transactions |
-| `network`     | no       | `"mainnet"`         | `"mainnet"` or `"testnet"` |
-| `store`       | no       | `new MemoryStore()` | pending hashes + settled batches storage (see below) |
-| `provider`    | no       | `new MempoolProvider()` | chain data source (UTXOs, fees, broadcast, tx lookup) |
-| `feeRateSatVb`| no       | fetched live        | fixed fee rate override (sat/vB) |
-| `intervalMs`  | no       | `86400000` (24h)    | used by `start()`: a batch is anchored once the oldest pending hash has waited this long (no tx while the queue is empty) |
-
-### Instance methods
-
-- `addHash(hashHex)` — queue a hex-encoded hash for the next settlement.
-- `pendingCount()` — number of hashes waiting to be settled.
-- `settle()` — build a Merkle tree over everything pending and anchor its
-  root in one `OP_RETURN` transaction right now. Returns the batch record
-  (`{ batchId, merkleRoot, txid, hashes, proofs, ... }`), or `null` if
-  nothing was pending.
-- `start({ intervalMs })` / `stop()` — automatic settlement: checks every minute and anchors when the oldest pending hash is `intervalMs` old. Survives restarts (uses the stored `addedAt`).
-- `settleIfDue()` — the check `start()` runs; anchors only if something has waited `intervalMs`.
-- `anchorNow(hash)` — anchor one hash immediately (together with anything already queued) and return its proof. If the hash is already anchored, returns the existing proof without a new transaction.
-- `getProof(hashHex)` — look up the stored proof + anchor info for a hash.
-- `verify(hashHex)` — cryptographically and on-chain verification (see above).
-- `refreshStatus(batchId)` — re-fetch a batch's transaction and update its
-  confirmation / block info.
-
-### `MerkleTree`
-
-The underlying Merkle tree, usable standalone:
+### 5. Command line (no code)
 
-```js
-import { MerkleTree } from "btcnotar";
+```bash
+npx btcnotar submit "Hello, Bitcoin!"
+npx btcnotar check  "Hello, Bitcoin!"
+```
+
+You can give a text or a SHA-256 hash (64 hex characters).
+
+---
+
+## How long does it take?
+
+| Step | Time |
+|---|---|
+| `submit()` | instant — status `pending` |
+| Hash goes into a Bitcoin transaction | at `nextSettleAt` (about every hour) |
+| Transaction is in a block | about 10 minutes later |
+
+After the transaction is sent, `verify()` returns `valid: true`.
+`confirmed: false` means it is still waiting for a block. `confirmed: true` means it is in a block.
 
-const tree = new MerkleTree([hashA, hashB, hashC]);
-tree.root;                       // hex string
-const proof = tree.getProof(0);  // inclusion proof for hashA
-MerkleTree.verifyProof(hashA, proof, tree.root); // true
+## What `verify()` returns
+
+```js
+{ valid: true, confirmed: true, txid: "...", blockHeight: 920123, date: "2026-10-25T15:08:12.000Z", merkleRoot: "..." }
+{ valid: false, reason: "pending", nextSettleAt: "..." }   // waiting in the queue
+{ valid: false, reason: "unknown-hash" }                    // never sent
+{ valid: false, reason: "merkle-proof-mismatch" }           // proof is wrong
+{ valid: false, reason: "on-chain-data-mismatch" }          // blockchain has different data
 ```
 
-Leaves are domain-separated from internal nodes (distinct hash prefixes),
-and an unpaired node at the end of a level is carried up unchanged rather
-than duplicated — this avoids both the classic leaf/node confusion forgery
-and the Bitcoin-style duplicate-leaf ambiguity (CVE-2012-2459).
+## Why you don't need to trust the server
+
+`verify()` downloads the proof from the server, then:
+
+1. rebuilds the Merkle root from your hash and the proof, and
+2. reads the real Bitcoin transaction from [mempool.space](https://mempool.space) and checks that its `OP_RETURN` contains that root.
+
+If the server lies, the check fails.
+
+---
+
+## Run your own notary (with your own Bitcoin)
 
-### Storage
+If you want your own server, use `BTCNotar` with your own key (WIF) and a funded address.
 
-`MemoryStore` (default, non-persistent) and `FileStore` (JSON file on disk)
-are included and share the same interface: `addPending`, `listPending`,
-`clearPending`, `saveBatch`, `getBatch`, `findBatchByHash`, `listBatches`.
-Implement the same interface against a real database for multi-process or
-production use.
+```js
+import { BTCNotar, FileStore, sha256Hex } from "btcnotar";
 
-### Chain provider
+const notary = new BTCNotar({
+  wif: process.env.BTCNOTAR_WIF,                       // your private key (WIF)
+  store: new FileStore({ filePath: "./store.json" }),  // keeps queue and proofs
+  intervalMs: 60 * 60 * 1000,                          // anchor every hour (if queue is not empty)
+});
 
-`MempoolProvider` talks to the public [mempool.space](https://mempool.space)
-REST API for UTXOs, fee estimation, broadcasting and transaction lookup.
-Supply your own object implementing `fetchUtxos`, `fetchFeeRateSatVb`,
-`broadcastTx`, `fetchTransaction` to use a different backend (e.g. a local
-`bitcoind` or Electrum server).
+console.log("Fund this address:", notary.address);
 
-## CLI
+await notary.addHash(sha256Hex("my document"));  // add to queue
+notary.start();                                  // anchors automatically
 
-The package also installs a `btcnotar` command:
+// or right now:
+const proof = await notary.anchorNow(sha256Hex("urgent document"));
+console.log(proof.txid);
+
+// check:
+console.log(await notary.verify(sha256Hex("my document")));
+```
+
+Command line for your own notary:
 
 ```bash
-export BTCNOTAR_WIF=...        # required
-export BTCNOTAR_NETWORK=mainnet
-export BTCNOTAR_STORE=./.btcnotar/store.json
-
-npx btcnotar add <hash>
-npx btcnotar settle
-npx btcnotar proof <hash>
-npx btcnotar verify <hash>
-npx btcnotar address
+export BTCNOTAR_WIF=...                  # required
+npx btcnotar address                     # address to fund
+npx btcnotar add <hash>                  # add to queue
+npx btcnotar settle                      # send the transaction now
+npx btcnotar verify <hash>               # check on the blockchain
 ```
 
-`btcnotar settle` is handy if you'd rather trigger settlement from an
-external scheduler (system cron, a serverless cron trigger) instead of the
-built-in `start()` interval.
+---
 
-## How anchoring works on-chain
+## API
 
-Each settlement broadcasts one transaction with a zero-value `OP_RETURN`
-output carrying:
+### `new BTCNotarClient(options?)` — free public server
+
+| option | default | description |
+|---|---|---|
+| `serverUrl` | public server | your own server URL |
+| `network` | `"mainnet"` | `"mainnet"` or `"testnet"` |
+| `provider` | `MempoolProvider` | where `verify()` reads the blockchain |
+
+- `submit(hash)` — add a hash to the queue → `{ status, hash, addedAt, nextSettleAt }`
+- `verify(hash)` — check on the blockchain → see [What verify() returns](#what-verify-returns)
+- `getProof(hash)` — raw proof, `{ status: "pending" }`, or `null`
+
+### `sha256Hex(textOrBuffer)`
+
+SHA-256 of a string (UTF-8) or a Buffer, as a hex string.
+
+### `new BTCNotar(options)` — your own notary
+
+| option | default | description |
+|---|---|---|
+| `wif` | — (required) | private key that pays and signs |
+| `network` | `"mainnet"` | `"mainnet"` or `"testnet"` |
+| `store` | `MemoryStore` (lost on exit) | use `FileStore({ filePath })` to keep data |
+| `intervalMs` | 24 hours | `start()` anchors when the oldest queued hash is this old |
+| `feeRateSatVb` | live from mempool.space | fixed fee (sat/vB) |
+| `provider` | `MempoolProvider` | blockchain backend |
+
+Methods: `address`, `addHash(hash)`, `pendingCount()`, `settle()`, `anchorNow(hash)`, `start()`, `stop()`, `settleIfDue()`, `getStatus(hash)`, `getProof(hash)`, `verify(hash)`, `refreshStatus(batchId)`.
+
+### Other exports
+
+`MerkleTree`, `verifyProof(hash, proof, provider)`, `MemoryStore`, `FileStore`, `MempoolProvider`, `DEFAULT_SERVER_URL`.
+
+---
+
+## How it looks on the blockchain
+
+Every batch is one transaction with an `OP_RETURN` output:
 
 ```
-"BTN1" (4 bytes, protocol magic)  ||  Merkle root (32 bytes)
+42544e31 + <Merkle root, 32 bytes>
+ "BTN1"
 ```
 
-36 bytes total, well within Bitcoin's 80-byte `OP_RETURN` limit. The magic
-prefix lets `verify()` recognize a BTCNotar anchor (and reject unrelated
-`OP_RETURN` data) before trusting its contents as a Merkle root.
+Your hash is not visible on the blockchain — only the Merkle root of all hashes in the batch.
+The proof connects your hash to that root.
+
+Merkle tree: leaf = `sha256(0x00 || hash)`, node = `sha256(0x01 || left || right)`, an odd node is moved up unchanged.
 
 ## License
 

package/bin/cli.js

@@ -1,12 +1,16 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import "dotenv/config";
-import { BTCNotar } from "../index.js";
+import { BTCNotar, BTCNotarClient, sha256Hex } from "../index.js";
 import { FileStore } from "../src/store.js";
 
 function usage() {
     console.log(`btcnotar - batch Bitcoin notarization CLI
 
-Usage:
+Free public server (no key, no bitcoin needed):
+  btcnotar submit <hash|text>  Send a hash to the server queue (text is hashed with SHA-256)
+  btcnotar check <hash|text>   Get the proof from the server and verify it on the blockchain
+
+Own notary (needs BTCNOTAR_WIF and a funded address):
   btcnotar add <hash>        Queue a document hash for the next settlement
   btcnotar settle            Settle all pending hashes now (build Merkle tree + anchor on-chain)
   btcnotar proof <hash>      Print the stored proof for a hash
@@ -14,6 +18,7 @@ Usage:
   btcnotar address           Print the notary's Bitcoin address
 
 Environment variables:
+  BTCNOTAR_SERVER    Server for submit/check (or --server <url>). Default: the free public server
   BTCNOTAR_WIF       Bitcoin private key (WIF) used to fund/sign anchor transactions [required]
   BTCNOTAR_NETWORK   "mainnet" or "testnet" (default: mainnet)
   BTCNOTAR_STORE     Path to the JSON store file (default: ./.btcnotar/store.json)
@@ -31,11 +36,37 @@ function buildNotary() {
     return new BTCNotar({ wif, network, store: new FileStore({ filePath }) });
 }
 
+function toHash(input) {
+    if (!input) throw new Error("give a hash or a text");
+    return /^[0-9a-fA-F]{64}$/.test(input) ? input.toLowerCase() : sha256Hex(input);
+}
+
+function buildClient(args) {
+    const i = args.indexOf("--server");
+    const serverUrl = (i >= 0 ? args[i + 1] : process.env.BTCNOTAR_SERVER) || undefined; // undefined = public server
+    if (i >= 0) args.splice(i, 2);
+    return new BTCNotarClient({ serverUrl, network: process.env.BTCNOTAR_NETWORK || "mainnet" });
+}
+
 async function main() {
-    const [cmd, arg] = process.argv.slice(2);
+    const args = process.argv.slice(2);
+    const cmd = args[0];
 
     if (!cmd || cmd === "-h" || cmd === "--help") return usage();
 
+    if (cmd === "submit" || cmd === "check") {
+        const client = buildClient(args);
+        const input = args.slice(1).join(" ");
+        const hash = toHash(input);
+        if (hash !== input.toLowerCase()) console.log(`SHA-256: ${hash}`);
+        const out = cmd === "submit" ? await client.submit(hash) : await client.verify(hash);
+        console.log(JSON.stringify(out, null, 2));
+        if (cmd === "check") process.exit(out.valid ? 0 : 1);
+        return;
+    }
+
+    const arg = args[1];
+
     if (cmd === "address") {
         const notary = buildNotary();
         console.log(notary.address);

package/index.js

@@ -1,4 +1,6 @@
 export { BTCNotar } from "./src/notary.js";
+export { BTCNotarClient, sha256Hex, DEFAULT_SERVER_URL } from "./src/client.js";
+export { verifyProof } from "./src/verify.js";
 export { MerkleTree } from "./src/merkle.js";
 export { MemoryStore, FileStore } from "./src/store.js";
 export {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "btcnotar",
-  "version": "0.1.0",
-  "description": "Batch Bitcoin notarization: aggregate document hashes into a Merkle tree, anchor the root on-chain via OP_RETURN on a schedule, and generate per-hash proofs that can be verified independently against the live blockchain (transaction, block and date).",
+  "version": "0.2.1",
+  "description": "Free Bitcoin notarization: prove a text or file existed at a certain time. Send a SHA-256 hash, get a proof you can verify yourself on the Bitcoin blockchain (Merkle tree + OP_RETURN).",
   "type": "module",
   "main": "index.js",
   "exports": {
@@ -30,7 +30,9 @@
     "timestamping",
     "op_return",
     "proof-of-existence",
-    "blockchain"
+    "blockchain",
+    "timestamp",
+    "sha256"
   ],
   "author": "Yordan Karparov",
   "license": "MIT",
@@ -45,5 +47,6 @@
     "dotenv": "^17.2.3",
     "ecpair": "^3.0.0",
     "tiny-secp256k1": "^2.2.4"
-  }
+  },
+  "homepage": "https://github.com/yordank/BTCNotar#readme"
 }

package/src/client.js

@@ -0,0 +1,68 @@
+import crypto from "node:crypto";
+import axios from "axios";
+import { MempoolProvider } from "./bitcoin.js";
+import { verifyProof } from "./verify.js";
+
+/** SHA-256 of a string (UTF-8) or Buffer, as hex. */
+export function sha256Hex(data) {
+    return crypto.createHash("sha256").update(data).digest("hex");
+}
+
+/** The free public BTCNotar server (used when no serverUrl is given). */
+export const DEFAULT_SERVER_URL = "https://proofofexistance-production.up.railway.app";
+
+function checkHash(hashHex) {
+    const hash = String(hashHex || "").trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(hash)) throw new Error(`hash must be 64 hex chars (SHA-256), got "${hashHex}"`);
+    return hash;
+}
+
+/**
+ * Client for a public BTCNotar server. No private key and no bitcoin needed:
+ * the server anchors queued hashes on-chain and pays the fee.
+ *
+ *   const client = new BTCNotarClient();   // free public server by default
+ *   await client.submit(sha256Hex("my document"));   // queued
+ *   ...after the next settlement...
+ *   await client.verify(hash);   // { valid, confirmed, txid, blockHeight, date }
+ *
+ * verify() does not trust the server: it takes the proof from the server and
+ * checks it against the blockchain itself (via mempool.space by default).
+ */
+export class BTCNotarClient {
+    constructor({ serverUrl = DEFAULT_SERVER_URL, network = "mainnet", provider, timeoutMs = 20_000 } = {}) {
+        this.serverUrl = serverUrl.replace(/\/+$/, "");
+        this.provider = provider || new MempoolProvider({ network });
+        this.http = axios.create({ baseURL: this.serverUrl, timeout: timeoutMs, validateStatus: () => true });
+    }
+
+    /** Send a hash to the server's queue. Returns { hash, addedAt, nextSettleAt, ... }. */
+    async submit(hashHex) {
+        const hash = checkHash(hashHex);
+        const res = await this.http.post("/api/notary/hash", { hashHex: hash });
+        if (res.status >= 400) throw new Error(`server error ${res.status}: ${res.data?.error || res.statusText}`);
+        return res.data;
+    }
+
+    /**
+     * Ask the server for the proof.
+     * Returns the proof record, { status: "pending", ... } while waiting, or null if the server doesn't know the hash.
+     */
+    async getProof(hashHex) {
+        const hash = checkHash(hashHex);
+        const res = await this.http.get(`/api/notary/proof/${hash}`);
+        if (res.status === 404) return null;
+        if (res.status === 202) return { status: "pending", ...res.data };
+        if (res.status >= 400) throw new Error(`server error ${res.status}: ${res.data?.error || res.statusText}`);
+        return res.data;
+    }
+
+    /** Get the proof from the server and verify it against the blockchain yourself. */
+    async verify(hashHex) {
+        const hash = checkHash(hashHex);
+        const record = await this.getProof(hash);
+        if (!record) return { valid: false, reason: "unknown-hash" };
+        if (record.status === "pending") return { valid: false, reason: "pending", nextSettleAt: record.nextSettleAt ?? null };
+        return verifyProof(hash, record, this.provider);
+    }
+}

package/src/notary.js

@@ -3,7 +3,8 @@ import * as bitcoin from "bitcoinjs-lib";
 import * as ecc from "tiny-secp256k1";
 import { ECPairFactory } from "ecpair";
 import { MerkleTree } from "./merkle.js";
-import { MempoolProvider, createOpReturnTx, encodeOpReturnPayload, extractOpReturnData } from "./bitcoin.js";
+import { MempoolProvider, createOpReturnTx, encodeOpReturnPayload } from "./bitcoin.js";
+import { verifyProof } from "./verify.js";
 import { MemoryStore } from "./store.js";
 
 bitcoin.initEccLib(ecc);
@@ -195,6 +196,26 @@ export class BTCNotar {
         };
     }
 
+    /** When the queue will be anchored next (oldest pending addedAt + intervalMs), or null if empty. */
+    async nextSettleAt() {
+        const pending = await this.store.listPending();
+        if (!pending.length) return null;
+        const oldest = Math.min(...pending.map((p) => Date.parse(p.addedAt) || Date.now()));
+        return new Date(oldest + this.intervalMs).toISOString();
+    }
+
+    /**
+     * Where is this hash? { status: "anchored", ...proof } | { status: "pending", addedAt, nextSettleAt } | null
+     */
+    async getStatus(hashHex) {
+        const hash = String(hashHex).toLowerCase();
+        const proof = await this.getProof(hash);
+        if (proof) return { status: "anchored", ...proof };
+        const queued = (await this.store.listPending()).find((p) => p.hash === hash);
+        if (queued) return { status: "pending", hash, addedAt: queued.addedAt, nextSettleAt: await this.nextSettleAt() };
+        return null;
+    }
+
     /** Re-fetch a batch's anchoring transaction and update its confirmation status. */
     async refreshStatus(batchId) {
         const batch = await this.store.getBatch(batchId);
@@ -221,31 +242,7 @@ export class BTCNotar {
      * the transaction id, block hash/height and date.
      */
     async verify(hashHex, proofRecord) {
-        const hash = hashHex.toLowerCase();
-        const record = proofRecord || (await this.getProof(hash));
-        if (!record) return { valid: false, reason: "no-proof-found" };
-
-        if (!MerkleTree.verifyProof(hash, record.proof, record.merkleRoot)) {
-            return { valid: false, reason: "merkle-proof-mismatch" };
-        }
-
-        const tx = await this.provider.fetchTransaction(record.txid);
-        if (!tx) return { valid: false, reason: "transaction-not-found", txid: record.txid };
-
-        const onChainRoot = extractOpReturnData(tx);
-        if (!onChainRoot || onChainRoot !== record.merkleRoot) {
-            return { valid: false, reason: "on-chain-data-mismatch", txid: record.txid };
-        }
-
-        return {
-            valid: true,
-            confirmed: !!tx.confirmed,
-            txid: record.txid,
-            merkleRoot: record.merkleRoot,
-            blockHeight: tx.blockHeight ?? null,
-            blockHash: tx.blockHash ?? null,
-            blockTime: tx.blockTime ?? null,
-            date: tx.blockTime ? new Date(tx.blockTime * 1000).toISOString() : null,
-        };
+        const record = proofRecord || (await this.getProof(hashHex));
+        return verifyProof(hashHex, record, this.provider);
     }
 }

package/src/verify.js

@@ -0,0 +1,40 @@
+import { MerkleTree } from "./merkle.js";
+import { extractOpReturnData } from "./bitcoin.js";
+
+/**
+ * Verify a proof record against the live blockchain, trusting nobody:
+ * (1) recompute the Merkle root from the hash + proof,
+ * (2) fetch the transaction from the chain and check its OP_RETURN carries that root.
+ *
+ * record: { merkleRoot, proof, txid }  (as returned by getProof / a notary server)
+ * provider: anything with fetchTransaction(txid), e.g. MempoolProvider
+ */
+export async function verifyProof(hashHex, record, provider) {
+    const hash = String(hashHex).toLowerCase();
+    if (!record || !record.merkleRoot || !record.txid || !Array.isArray(record.proof)) {
+        return { valid: false, reason: "no-proof-found" };
+    }
+
+    if (!MerkleTree.verifyProof(hash, record.proof, record.merkleRoot)) {
+        return { valid: false, reason: "merkle-proof-mismatch" };
+    }
+
+    const tx = await provider.fetchTransaction(record.txid);
+    if (!tx) return { valid: false, reason: "transaction-not-found", txid: record.txid };
+
+    const onChainRoot = extractOpReturnData(tx);
+    if (!onChainRoot || onChainRoot !== record.merkleRoot) {
+        return { valid: false, reason: "on-chain-data-mismatch", txid: record.txid };
+    }
+
+    return {
+        valid: true,
+        confirmed: !!tx.confirmed,
+        txid: record.txid,
+        merkleRoot: record.merkleRoot,
+        blockHeight: tx.blockHeight ?? null,
+        blockHash: tx.blockHash ?? null,
+        blockTime: tx.blockTime ?? null,
+        date: tx.blockTime ? new Date(tx.blockTime * 1000).toISOString() : null,
+    };
+}