btcnotar 0.1.0 → 0.2.0

package/README.md

@@ -74,6 +74,37 @@ 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)`
@@ -97,6 +128,7 @@ blockchain, and when/where" has one unambiguous answer.
   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).

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,6 +1,6 @@
 {
   "name": "btcnotar",
-  "version": "0.1.0",
+  "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",

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