btcnotar 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yordan Karparov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,207 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# btcnotar
+
+Batch Bitcoin notarization for Node.js.
+
+`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.
+
+## Why batching
+
+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.
+
+## Install
+
+```bash
+npm install btcnotar
+```
+
+## Quick start
+
+```js
+import { BTCNotar, FileStore } from "btcnotar";
+
+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)
+});
+
+// 1. Queue hashes as documents come in (e.g. sha256 of a file)
+await notary.addHash("2d711642b726b04401627ca9fbac32f5c8530fb1903cc4db02258717921a4881");
+
+// 2. Start automatic daily settlement (builds the Merkle tree + broadcasts
+//    one OP_RETURN transaction anchoring the root)
+notary.start();
+
+// ... later, anywhere, even in a different process that only has the hash ...
+
+const proof = await notary.getProof(hash);
+// { hash, merkleRoot, proof, txid, batchId, blockHeight, blockHash, blockTime, ... }
+
+const result = await notary.verify(hash);
+// {
+//   valid: true,
+//   confirmed: true,
+//   txid: "…",
+//   blockHeight: 912345,
+//   blockHash: "…",
+//   date: "2026-09-10T00:00:00.000Z",
+//   merkleRoot: "…",
+// }
+```
+
+`verify()` does two independent checks before it reports `valid: true`:
+
+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.
+
+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.
+
+## Free public server (no key, no bitcoin)
+
+Don't want to run your own notary? Send hashes to the free public BTCNotar server
+(`https://proofofexistance-production.up.railway.app`, used by default).
+The server batches them and pays the fee (one transaction per batch).
+You verify the result yourself against the blockchain, so you don't have to trust the server.
+
+```js
+import { BTCNotarClient, sha256Hex } from "btcnotar";
+
+const client = new BTCNotarClient();   // or { serverUrl: "https://your-own-server" }
+
+const hash = sha256Hex(fs.readFileSync("contract.pdf"));
+await client.submit(hash);        // { status: "pending", nextSettleAt: "..." }
+
+// after the next settlement (see nextSettleAt):
+await client.verify(hash);        // { valid: true, confirmed: true, txid, blockHeight, date }
+```
+
+- `submit(hash)` — add the hash to the server queue.
+- `getProof(hash)` — proof record, `{ status: "pending" }` while waiting, or `null`.
+- `verify(hash)` — gets the proof from the server and checks it on-chain (mempool.space by default, or pass your own `provider`).
+
+From the command line:
+
+```
+npx btcnotar submit "any text or a sha256 hash"
+npx btcnotar check  "any text or a sha256 hash"
+# own server: add --server https://your-own-server
+```
+
+## API
+
+### `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`.
+- `getStatus(hash)` — `{ status: "anchored", ...proof }`, `{ status: "pending", addedAt, nextSettleAt }` or `null`.
+- `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:
+
+```js
+import { MerkleTree } from "btcnotar";
+
+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
+```
+
+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).
+
+### Storage
+
+`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.
+
+### Chain provider
+
+`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).
+
+## CLI
+
+The package also installs a `btcnotar` command:
+
+```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
+```
+
+`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
+
+Each settlement broadcasts one transaction with a zero-value `OP_RETURN`
+output carrying:
+
+```
+"BTN1" (4 bytes, protocol magic)  ||  Merkle root (32 bytes)
+```
+
+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.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { BTCNotar, BTCNotarClient, sha256Hex } from "../index.js";
+import { FileStore } from "../src/store.js";
+
+function usage() {
+    console.log(`btcnotar - batch Bitcoin notarization CLI
+
+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
+  btcnotar verify <hash>     Verify a hash against the live blockchain
+  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)
+`);
+}
+
+function buildNotary() {
+    const wif = process.env.BTCNOTAR_WIF;
+    if (!wif) {
+        console.error("Missing BTCNOTAR_WIF environment variable.");
+        process.exit(1);
+    }
+    const network = process.env.BTCNOTAR_NETWORK || "mainnet";
+    const filePath = process.env.BTCNOTAR_STORE || "./.btcnotar/store.json";
+    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 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);
+        return;
+    }
+
+    if (cmd === "add") {
+        if (!arg) throw new Error("usage: btcnotar add <hash>");
+        const notary = buildNotary();
+        const entry = await notary.addHash(arg);
+        console.log(JSON.stringify(entry, null, 2));
+        return;
+    }
+
+    if (cmd === "settle") {
+        const notary = buildNotary();
+        const batch = await notary.settle();
+        console.log(batch ? JSON.stringify(batch, null, 2) : "Nothing pending.");
+        return;
+    }
+
+    if (cmd === "proof") {
+        if (!arg) throw new Error("usage: btcnotar proof <hash>");
+        const notary = buildNotary();
+        const proof = await notary.getProof(arg);
+        console.log(proof ? JSON.stringify(proof, null, 2) : "No proof found for that hash.");
+        return;
+    }
+
+    if (cmd === "verify") {
+        if (!arg) throw new Error("usage: btcnotar verify <hash>");
+        const notary = buildNotary();
+        const result = await notary.verify(arg);
+        console.log(JSON.stringify(result, null, 2));
+        process.exit(result.valid ? 0 : 1);
+        return;
+    }
+
+    console.error(`Unknown command: ${cmd}`);
+    usage();
+    process.exit(1);
+}
+
+main().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+});

package/index.js

@@ -0,0 +1,15 @@
+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 {
+    MempoolProvider,
+    createOpReturnTx,
+    buildOpReturnScript,
+    encodeOpReturnPayload,
+    decodeOpReturnPayload,
+    extractOpReturnData,
+    MAGIC,
+    OP_RETURN_MAX_BYTES,
+} from "./src/bitcoin.js";

package/package.json

@@ -1,6 +1,49 @@
-{
-  "name": "btcnotar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "btcnotar",
+  "version": "0.2.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).",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "btcnotar": "./bin/cli.js"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "bitcoin",
+    "merkle-tree",
+    "notarization",
+    "timestamping",
+    "op_return",
+    "proof-of-existence",
+    "blockchain"
+  ],
+  "author": "Yordan Karparov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yordank/BTCNotar.git",
+    "directory": "packages/btcnotar"
+  },
+  "dependencies": {
+    "axios": "^1.13.2",
+    "bitcoinjs-lib": "^7.0.1",
+    "dotenv": "^17.2.3",
+    "ecpair": "^3.0.0",
+    "tiny-secp256k1": "^2.2.4"
+  }
+}

package/src/bitcoin.js

@@ -0,0 +1,133 @@
+import axios from "axios";
+import * as bitcoin from "bitcoinjs-lib";
+
+// Protocol magic so an OP_RETURN payload can be recognized as a BTCNotar
+// anchor (as opposed to some other protocol's data) before trusting its
+// contents as a Merkle root. "BTN1" = format version 1.
+export const MAGIC = Buffer.from("BTN1", "ascii");
+export const OP_RETURN_MAX_BYTES = 80;
+
+/** Pack a 32-byte Merkle root (hex) into the on-chain OP_RETURN payload. */
+export function encodeOpReturnPayload(merkleRootHex) {
+    const root = Buffer.from(merkleRootHex, "hex");
+    if (root.length !== 32) throw new Error("merkle root must be 32 bytes");
+    const payload = Buffer.concat([MAGIC, root]);
+    if (payload.length > OP_RETURN_MAX_BYTES) throw new Error("OP_RETURN payload too large");
+    return payload;
+}
+
+/** Inverse of encodeOpReturnPayload. Returns null if the magic doesn't match. */
+export function decodeOpReturnPayload(payload) {
+    if (!Buffer.isBuffer(payload) || payload.length !== MAGIC.length + 32) return null;
+    if (!payload.subarray(0, MAGIC.length).equals(MAGIC)) return null;
+    return payload.subarray(MAGIC.length).toString("hex");
+}
+
+export function buildOpReturnScript(dataBuffer) {
+    if (dataBuffer.length > OP_RETURN_MAX_BYTES) throw new Error("OP_RETURN > 80 bytes");
+    return bitcoin.script.compile([bitcoin.opcodes.OP_RETURN, dataBuffer]);
+}
+
+/**
+ * Build, sign and serialize a single-input OP_RETURN transaction spending
+ * one P2WPKH UTXO, with the (optional) change sent back to the same address.
+ */
+export function createOpReturnTx({ keyPair, fromAddress, utxo, dataBuffer, feeSat, network }) {
+    const p2wpkh = bitcoin.payments.p2wpkh({ pubkey: keyPair.publicKey, network });
+    const psbt = new bitcoin.Psbt({ network });
+
+    psbt.addInput({
+        hash: utxo.txid,
+        index: utxo.vout,
+        witnessUtxo: { script: p2wpkh.output, value: BigInt(utxo.value) },
+    });
+
+    psbt.addOutput({ script: buildOpReturnScript(dataBuffer), value: 0n });
+
+    const DUST_LIMIT = 1000n;
+    let change = BigInt(utxo.value) - BigInt(feeSat);
+    if (change <= 0n) throw new Error("Insufficient funds for fee");
+    if (change < DUST_LIMIT) change = 0n;
+    if (change > 0n) psbt.addOutput({ address: fromAddress, value: change });
+
+    psbt.signAllInputs(keyPair);
+    psbt.finalizeAllInputs();
+
+    const tx = psbt.extractTransaction();
+    return { rawHex: tx.toHex(), txid: tx.getId() };
+}
+
+/**
+ * Given a fetched transaction (as returned by a provider's
+ * fetchTransaction), locate its OP_RETURN output and decode a BTCNotar
+ * Merkle root from it, if present. This is what lets verification check
+ * the *actual* on-chain data rather than trusting a locally stored copy.
+ */
+export function extractOpReturnData(tx) {
+    for (const out of tx.vout || []) {
+        const scriptHex = out.scriptpubkey;
+        if (!scriptHex || !scriptHex.startsWith("6a")) continue; // 0x6a == OP_RETURN
+        const decompiled = bitcoin.script.decompile(Buffer.from(scriptHex, "hex"));
+        const data = (decompiled || []).find((el) => Buffer.isBuffer(el));
+        if (!data) continue;
+        const root = decodeOpReturnPayload(data);
+        if (root) return root;
+    }
+    return null;
+}
+
+/**
+ * Chain data provider backed by the public mempool.space REST API.
+ * Swap for a different implementation (e.g. a local bitcoind/Electrum
+ * client) as long as it exposes the same four methods.
+ */
+export class MempoolProvider {
+    constructor({ network = "mainnet", apiBase } = {}) {
+        this.network = network;
+        this.apiBase = apiBase || (network === "mainnet" ? "https://mempool.space/api" : `https://mempool.space/${network}/api`);
+    }
+
+    async fetchUtxos(address) {
+        const res = await axios.get(`${this.apiBase}/address/${address}/utxo`);
+        return res.data;
+    }
+
+    async fetchFeeRateSatVb() {
+        try {
+            const res = await axios.get(`${this.apiBase}/v1/fees/recommended`);
+            return Number(res.data?.halfHourFee ?? 10);
+        } catch {
+            return 10;
+        }
+    }
+
+    async broadcastTx(rawHex) {
+        const res = await axios.post(`${this.apiBase}/tx`, rawHex, {
+            headers: { "Content-Type": "text/plain" },
+        });
+        return res.data; // txid
+    }
+
+    /**
+     * Normalized transaction lookup: { txid, confirmed, blockHeight,
+     * blockHash, blockTime, vout: [{ scriptpubkey, value }] }.
+     * Returns null if the transaction is not (yet) known to the indexer.
+     */
+    async fetchTransaction(txid) {
+        try {
+            const res = await axios.get(`${this.apiBase}/tx/${txid}`);
+            const tx = res.data;
+            return {
+                txid: tx.txid,
+                confirmed: !!tx.status?.confirmed,
+                blockHeight: tx.status?.block_height ?? null,
+                blockHash: tx.status?.block_hash ?? null,
+                blockTime: tx.status?.block_time ?? null,
+                vout: (tx.vout || []).map((o) => ({ scriptpubkey: o.scriptpubkey, value: o.value })),
+            };
+        } catch (e) {
+            if (e?.response?.status === 404) return null;
+            throw e;
+        }
+    }
+}

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/merkle.js

@@ -0,0 +1,122 @@
+import crypto from "node:crypto";
+
+// Domain-separation prefixes so a leaf hash can never be replayed as an
+// internal node (and vice versa) when reconstructing a root from a proof.
+const LEAF_PREFIX = Buffer.from([0x00]);
+const NODE_PREFIX = Buffer.from([0x01]);
+
+function sha256(buf) {
+    return crypto.createHash("sha256").update(buf).digest();
+}
+
+function toBuffer(hashHex) {
+    if (typeof hashHex !== "string" || !/^[0-9a-fA-F]+$/.test(hashHex) || hashHex.length % 2 !== 0) {
+        throw new Error(`Invalid hash: expected a hex string, got "${hashHex}"`);
+    }
+    return Buffer.from(hashHex, "hex");
+}
+
+function hashLeaf(hashHex) {
+    return sha256(Buffer.concat([LEAF_PREFIX, toBuffer(hashHex)]));
+}
+
+function hashNode(left, right) {
+    return sha256(Buffer.concat([NODE_PREFIX, left, right]));
+}
+
+/**
+ * A Merkle tree over a list of document hashes.
+ *
+ * - Leaves are domain-separated (0x00 prefix) so they can't collide with
+ *   internal nodes (0x01 prefix) — this prevents the classic
+ *   leaf/node-confusion forgery against naive Merkle proofs.
+ * - An unpaired node at the end of a level is carried up unchanged
+ *   (no duplication), which avoids the CVE-2012-2459-style duplicate-leaf
+ *   ambiguity that affects Bitcoin's own block Merkle tree.
+ */
+export class MerkleTree {
+    /** @param {string[]} hashesHex - document hashes (hex-encoded) to anchor */
+    constructor(hashesHex) {
+        if (!Array.isArray(hashesHex) || hashesHex.length === 0) {
+            throw new Error("MerkleTree requires a non-empty array of hex hashes");
+        }
+        this.leaves = hashesHex.map((h) => h.toLowerCase());
+        this.layers = MerkleTree.buildLayers(this.leaves.map(hashLeaf));
+    }
+
+    static buildLayers(leafBuffers) {
+        const layers = [leafBuffers];
+        let current = leafBuffers;
+        while (current.length > 1) {
+            const next = [];
+            for (let i = 0; i < current.length; i += 2) {
+                if (i + 1 < current.length) {
+                    next.push(hashNode(current[i], current[i + 1]));
+                } else {
+                    next.push(current[i]); // odd one out, carried up untouched
+                }
+            }
+            layers.push(next);
+            current = next;
+        }
+        return layers;
+    }
+
+    /** Merkle root, hex-encoded. */
+    get root() {
+        const top = this.layers[this.layers.length - 1];
+        return top[0].toString("hex");
+    }
+
+    /**
+     * Inclusion proof for the leaf at `index`: an ordered list of sibling
+     * steps needed to recompute the root from that leaf's hash.
+     * @returns {{position: "left"|"right", hash: string}[]}
+     */
+    getProof(index) {
+        if (!Number.isInteger(index) || index < 0 || index >= this.leaves.length) {
+            throw new Error(`index out of range: ${index}`);
+        }
+        const proof = [];
+        let idx = index;
+        for (let level = 0; level < this.layers.length - 1; level++) {
+            const layer = this.layers[level];
+            const isRightNode = idx % 2 === 1;
+            const siblingIdx = isRightNode ? idx - 1 : idx + 1;
+            if (siblingIdx < layer.length) {
+                proof.push({
+                    position: isRightNode ? "left" : "right",
+                    hash: layer[siblingIdx].toString("hex"),
+                });
+            }
+            idx = Math.floor(idx / 2);
+        }
+        return proof;
+    }
+
+    /** Proof for the first leaf equal to `hashHex`. Throws if not found. */
+    getProofForHash(hashHex) {
+        const index = this.leaves.indexOf(hashHex.toLowerCase());
+        if (index === -1) throw new Error(`hash not found in this tree: ${hashHex}`);
+        return this.getProof(index);
+    }
+
+    /**
+     * Recompute a root from a leaf hash + proof and compare it to `rootHex`.
+     * This is the reversibility primitive: anyone holding only the original
+     * document hash and its proof can independently verify inclusion,
+     * without needing the full batch.
+     */
+    static verifyProof(hashHex, proof, rootHex) {
+        try {
+            let node = hashLeaf(hashHex);
+            for (const step of proof) {
+                const sibling = toBuffer(step.hash);
+                node = step.position === "left" ? hashNode(sibling, node) : hashNode(node, sibling);
+            }
+            return node.toString("hex") === rootHex.toLowerCase();
+        } catch {
+            return false;
+        }
+    }
+}

package/src/notary.js

@@ -0,0 +1,248 @@
+import crypto from "node:crypto";
+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 } from "./bitcoin.js";
+import { verifyProof } from "./verify.js";
+import { MemoryStore } from "./store.js";
+
+bitcoin.initEccLib(ecc);
+const ECPair = ECPairFactory(ecc);
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+// Size of our tx: 1 P2WPKH input + OP_RETURN (36 bytes) + change ≈ 157 vB.
+const ANCHOR_TX_VBYTES = 160;
+
+function isHex(s) {
+    return typeof s === "string" && /^[0-9a-fA-F]+$/.test(s) && s.length % 2 === 0;
+}
+
+/**
+ * BTCNotar batches document hashes, anchors each batch's Merkle root to
+ * Bitcoin via a single OP_RETURN transaction, and hands back per-hash
+ * proofs that can be independently and unambiguously verified later
+ * against the live chain (which transaction, which block, which date).
+ *
+ * Typical usage:
+ *   const notary = new BTCNotar({ wif, network: "mainnet", store });
+ *   await notary.addHash(sha256HexOfSomeDocument);
+ *   notary.start();                    // settle once every 24h automatically
+ *   ...
+ *   const proof = await notary.getProof(hash);
+ *   const result = await notary.verify(hash);  // { valid, confirmed, txid, blockHeight, date, ... }
+ */
+export class BTCNotar {
+    constructor({ wif, network = "mainnet", store, provider, feeRateSatVb, intervalMs = DAY_MS } = {}) {
+        if (!wif) throw new Error("wif (private key, WIF format) is required");
+        this.network = network === "mainnet" ? bitcoin.networks.bitcoin : bitcoin.networks.testnet;
+        this.keyPair = ECPair.fromWIF(wif, this.network);
+        this.address = bitcoin.payments.p2wpkh({ pubkey: this.keyPair.publicKey, network: this.network }).address;
+        this.store = store || new MemoryStore();
+        this.provider = provider || new MempoolProvider({ network });
+        this.feeRateSatVb = feeRateSatVb || null;
+        this.intervalMs = intervalMs;
+        this._timer = null;
+    }
+
+    /** Queue a document hash for the next settlement batch. */
+    async addHash(hashHex) {
+        if (!isHex(hashHex)) throw new Error(`hash must be a hex string, got "${hashHex}"`);
+        const hash = hashHex.toLowerCase();
+        const queued = (await this.store.listPending()).find((p) => p.hash === hash);
+        if (queued) return queued; // already waiting: don't add it twice
+        const entry = { id: crypto.randomUUID(), hash, addedAt: new Date().toISOString() };
+        await this.store.addPending(entry);
+        return entry;
+    }
+
+    /** How many hashes are waiting for the next settlement. */
+    async pendingCount() {
+        return (await this.store.listPending()).length;
+    }
+
+    /**
+     * Build a Merkle tree over all currently pending hashes and anchor its
+     * root on-chain in one OP_RETURN transaction. Returns the settled batch
+     * (including a proof per hash), or null if there was nothing pending.
+     */
+    settle() {
+        // Run settlements one after another (timer + manual call at the same time
+        // would otherwise try to spend the same UTXO twice).
+        const run = (this._settleChain || Promise.resolve()).then(() => this._settle());
+        this._settleChain = run.catch(() => {});
+        return run;
+    }
+
+    async _settle() {
+        const pending = await this.store.listPending();
+        if (!pending.length) return null;
+
+        const hashes = pending.map((p) => p.hash);
+        const tree = new MerkleTree(hashes);
+        const merkleRoot = tree.root;
+
+        const utxos = await this.provider.fetchUtxos(this.address);
+        if (!utxos.length) throw new Error(`No UTXOs available. Fund address: ${this.address}`);
+
+        const feeRate = this.feeRateSatVb || (await this.provider.fetchFeeRateSatVb());
+        const feeSat = Math.ceil(ANCHOR_TX_VBYTES * feeRate);
+        const utxo = utxos[0];
+
+        const payload = encodeOpReturnPayload(merkleRoot);
+        const { rawHex, txid } = createOpReturnTx({
+            keyPair: this.keyPair,
+            fromAddress: this.address,
+            utxo,
+            dataBuffer: payload,
+            feeSat,
+            network: this.network,
+        });
+        const broadcastTxid = await this.provider.broadcastTx(rawHex);
+
+        const proofs = {};
+        hashes.forEach((h, i) => {
+            if (!(h in proofs)) proofs[h] = tree.getProof(i);
+        });
+
+        const batch = {
+            batchId: merkleRoot,
+            merkleRoot,
+            txid: broadcastTxid || txid,
+            createdAt: new Date().toISOString(),
+            hashes,
+            proofs,
+            status: "broadcast",
+            blockHeight: null,
+            blockHash: null,
+            blockTime: null,
+        };
+
+        await this.store.saveBatch(batch);
+        await this.store.clearPending(pending.map((p) => p.id));
+        return batch;
+    }
+
+    /**
+     * Start automatic settlement. A batch is anchored as soon as the OLDEST
+     * pending hash has waited `intervalMs` (default: one day). Nothing is sent
+     * while the queue is empty. Because the wait is measured from the stored
+     * `addedAt` time, a server restart does not reset it.
+     */
+    start({ intervalMs } = {}) {
+        if (this._timer) return;
+        if (intervalMs) this.intervalMs = intervalMs;
+        const checkMs = Math.min(this.intervalMs, 60_000);
+        this._timer = setInterval(() => {
+            this.settleIfDue().catch((err) => console.error("[btcnotar] scheduled settle() failed:", err));
+        }, checkMs);
+        this._timer.unref?.();
+    }
+
+    /**
+     * Anchor one hash right now (plus anything else already queued) and
+     * return its proof. If the hash is already anchored, returns the existing
+     * proof without a new transaction (`alreadyAnchored: true`).
+     */
+    async anchorNow(hashHex) {
+        if (!isHex(hashHex)) throw new Error(`hash must be a hex string, got "${hashHex}"`);
+        const hash = hashHex.toLowerCase();
+        const existing = await this.getProof(hash);
+        if (existing) return { ...existing, alreadyAnchored: true };
+        await this.addHash(hash);
+        await this.settle();
+        const proof = await this.getProof(hash);
+        if (!proof) throw new Error("anchoring failed: hash not found in any batch");
+        return { ...proof, alreadyAnchored: false };
+    }
+
+    /** Settle only if the oldest pending hash has waited at least `intervalMs`. Returns the batch or null. */
+    async settleIfDue(now = Date.now()) {
+        if (this._settling) return null;
+        this._settling = true; // set before any await, so two calls can never both pass
+        try {
+            const pending = await this.store.listPending();
+            if (!pending.length) return null;
+            const oldest = Math.min(...pending.map((p) => Date.parse(p.addedAt) || now));
+            if (now - oldest < this.intervalMs) return null;
+            return await this.settle();
+        } finally {
+            this._settling = false;
+        }
+    }
+
+    stop() {
+        if (this._timer) {
+            clearInterval(this._timer);
+            this._timer = null;
+        }
+    }
+
+    /** Look up the stored proof + anchor info for a given document hash. */
+    async getProof(hashHex) {
+        const hash = hashHex.toLowerCase();
+        const batch = await this.store.findBatchByHash(hash);
+        if (!batch) return null;
+        return {
+            hash,
+            merkleRoot: batch.merkleRoot,
+            proof: batch.proofs[hash],
+            txid: batch.txid,
+            batchId: batch.batchId,
+            createdAt: batch.createdAt,
+            blockHeight: batch.blockHeight,
+            blockHash: batch.blockHash,
+            blockTime: batch.blockTime,
+        };
+    }
+
+    /** 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);
+        if (!batch) return null;
+        const tx = await this.provider.fetchTransaction(batch.txid);
+        if (tx) {
+            batch.status = tx.confirmed ? "confirmed" : "pending";
+            batch.blockHeight = tx.blockHeight;
+            batch.blockHash = tx.blockHash;
+            batch.blockTime = tx.blockTime;
+            await this.store.saveBatch(batch);
+        }
+        return batch;
+    }
+
+    /**
+     * The reversibility check: given a document hash, prove — or disprove —
+     * that it is anchored on the Bitcoin blockchain.
+     *
+     * This (1) recomputes the Merkle root from the hash + its stored proof
+     * and (2) fetches the anchoring transaction live from the chain and
+     * confirms its OP_RETURN output actually carries that same root. Only
+     * when both checks agree is the result reported as valid, together with
+     * the transaction id, block hash/height and date.
+     */
+    async verify(hashHex, proofRecord) {
+        const record = proofRecord || (await this.getProof(hashHex));
+        return verifyProof(hashHex, record, this.provider);
+    }
+}

package/src/store.js

@@ -0,0 +1,109 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * In-memory store: hashes waiting for the next settlement batch, and
+ * settled batches keyed by batchId (= their Merkle root), indexed by the
+ * individual document hashes they contain. This is also the base class
+ * for FileStore below.
+ */
+export class MemoryStore {
+    constructor() {
+        this.pending = [];
+        this.batches = new Map();
+        this.hashIndex = new Map();
+    }
+
+    async addPending(entry) {
+        this.pending.push(entry);
+        return entry;
+    }
+
+    async listPending() {
+        return [...this.pending];
+    }
+
+    async clearPending(ids) {
+        const remove = new Set(ids);
+        this.pending = this.pending.filter((e) => !remove.has(e.id));
+    }
+
+    async saveBatch(batch) {
+        this.batches.set(batch.batchId, batch);
+        for (const h of batch.hashes) this.hashIndex.set(h, batch.batchId);
+        return batch;
+    }
+
+    async getBatch(batchId) {
+        return this.batches.get(batchId) || null;
+    }
+
+    async findBatchByHash(hashHex) {
+        const batchId = this.hashIndex.get(hashHex.toLowerCase());
+        return batchId ? this.batches.get(batchId) || null : null;
+    }
+
+    async listBatches() {
+        return [...this.batches.values()];
+    }
+}
+
+/**
+ * JSON-file-backed store: same interface as MemoryStore, persisted to disk
+ * after every write so pending hashes and settled batches survive process
+ * restarts. Fine for a single-process daemon; swap in a real database for
+ * anything with concurrent writers.
+ */
+export class FileStore extends MemoryStore {
+    constructor({ filePath }) {
+        super();
+        if (!filePath) throw new Error("FileStore requires a filePath");
+        this.filePath = filePath;
+        this._load();
+    }
+
+    _load() {
+        try {
+            const raw = fs.readFileSync(this.filePath, "utf8");
+            const data = JSON.parse(raw);
+            this.pending = data.pending || [];
+            this.batches = new Map(Object.entries(data.batches || {}));
+            this._reindex();
+        } catch (e) {
+            if (e.code !== "ENOENT") throw e;
+        }
+    }
+
+    _reindex() {
+        this.hashIndex = new Map();
+        for (const batch of this.batches.values()) {
+            for (const h of batch.hashes) this.hashIndex.set(h, batch.batchId);
+        }
+    }
+
+    _persist() {
+        const data = {
+            pending: this.pending,
+            batches: Object.fromEntries(this.batches),
+        };
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        fs.writeFileSync(this.filePath, JSON.stringify(data, null, 2));
+    }
+
+    async addPending(entry) {
+        await super.addPending(entry);
+        this._persist();
+        return entry;
+    }
+
+    async clearPending(ids) {
+        await super.clearPending(ids);
+        this._persist();
+    }
+
+    async saveBatch(batch) {
+        await super.saveBatch(batch);
+        this._persist();
+        return batch;
+    }
+}

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,
+    };
+}