ocp-verify 1.0.0 → 1.2.0

package/README.md

@@ -28,6 +28,18 @@ If one byte changes, verification fails — across any system.
 
 ## 🔌 Integrate in 2 Minutes
 
+### Install
+
+```bash
+npm install -g ocp-verify
+```
+
+Or use without installing:
+
+```bash
+npx ocp-verify myfile.txt myfile.proof.json
+```
+
 ### 1) Commit (produce a proof)
 
 ```bash
@@ -301,6 +313,7 @@ The network only confirms that a commitment exists.
 - 🤖 AI Inference Attestation → `/docs/spec/appendix-ai-inference-attestation.md`
 - 🧾 Proof Format → `/docs/spec/proof-format-v1.md`
 - 🔍 Examples → `/examples`
+- ✅ Conformance Suite → `/conformance/run-conformance.sh`
 - ⚙️ Contracts → `/contracts`
 - 🌐 Live Demo → https://observation-commitment-protocol.vercel.app/
 
@@ -328,5 +341,59 @@ VALID
 v1.0.0 — Cross-Chain Primitive  
 Phase 1 complete — proof envelope schema  
 Phase 2 complete — EVM reference implementation live  
-Phase 3 complete — Solana appendix, chain-agnostic claim validated  
+Phase 3 complete — Solana devnet live, Gate 3 verified — same observation committed on EVM and Solana
+Phase 4 complete — ocp-verify published to npm, zero dependencies
+Phase 5 complete — conformance suite, 11/11 tests pass  
 First external contribution merged — dinamic.eth / ERC-8004 (PR #1)
+
+
+---
+
+## Revocation Extension (v1.1.0)
+
+OCP now includes an optional revocation layer. Original commitments are never deleted or mutated — revocation is additive, represented as a new on-chain commitment referencing a prior digest.
+
+```js
+const { verifyWithRevocation } = require('ocp-verify/reference-cli/revoke.js');
+
+const status = await verifyWithRevocation(
+  digest,
+  asOfTimestamp,
+  'eip155:84532'
+);
+// returns VALID | REVOKED | NOT_FOUND
+```
+
+- 📄 Revocation Spec → `/docs/spec/appendix-revocation-r.md`
+- ⛓️ Deployed Contract → `0x2fa07c85439850ff6C5688d926bDa6DaEe62Db15` (Base Sepolia)
+- ✅ Revocation Conformance → `/conformance/revocation/run-revocation-conformance.sh`
+- 🔑 Event Topic → `0xc19951599a519bc320c0f352b2f92f315e8a2368bd0efb2e5dca3b1196e76112`
+
+---
+
+## Status
+
+v1.1.0 — Revocation Extension
+Phase 6 complete — additive revocation primitive, 8/8 conformance tests pass
+
+## Temporal Bounds Extension (v1.2.0)
+
+OCP now includes an optional temporal bounds layer. Derives a finality-bounded existence proof from on-chain state — no oracles, no trusted time servers.
+
+```js
+const { getTemporalBound } = require('ocp-verify/reference-cli/temporal-bounds.js');
+
+const result = await getTemporalBound(txHash, 'eip155:84532');
+// result.upper_bound_iso — observation existed no later than this time
+// result.finalized — whether safe finality depth has been reached
+```
+
+- 📄 Temporal Bounds Spec → `/docs/spec/appendix-temporal-bounds-r.md`
+- ✅ Conformance → `/conformance/temporal-bounds/run-temporal-bounds-conformance.sh`
+
+---
+
+## Status
+
+v1.2.0 — Temporal Bounds Extension
+Phase 7 complete — finality-derived temporal bounds, 8/8 conformance tests pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ocp-verify",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Zero-dependency verifier for the Observation Commitment Protocol — independently verify that a file was committed to a public blockchain",
   "license": "MIT",
   "type": "commonjs",
@@ -33,9 +33,9 @@
   "homepage": "https://github.com/damonzwicker/observation-commitment-protocol",
   "repository": {
     "type": "git",
-    "url": "https://github.com/damonzwicker/observation-commitment-protocol.git"
+    "url": "git+https://github.com/damonzwicker/observation-commitment-protocol.git"
   },
   "bugs": {
     "url": "https://github.com/damonzwicker/observation-commitment-protocol/issues"
   }
-}
+}

package/reference-cli/revoke.js

@@ -0,0 +1,148 @@
+// revoke.js — zero-dependency revocation helpers for OCP
+// CommonJS, Node.js >=18
+// Spec: docs/spec/appendix-revocation-r.md
+
+"use strict";
+
+const crypto = require("crypto");
+const https  = require("https");
+
+// Deployed contract addresses
+const REVOCATION_CONTRACTS = {
+  "eip155:84532": "0x2fa07c85439850ff6C5688d926bDa6DaEe62Db15",
+};
+
+// RPC endpoints — no API key required
+const RPC = {
+  "eip155:84532": "https://sepolia.base.org",
+  "eip155:8453":  "https://mainnet.base.org",
+};
+
+// keccak256("RevocationCommitted(bytes32,bytes32,address,uint256)")
+const REVOCATION_EVENT_TOPIC = "0xc19951599a519bc320c0f352b2f92f315e8a2368bd0efb2e5dca3b1196e76112";
+
+// getRevocation(bytes32) selector
+const GET_REVOCATION_SELECTOR = "0x8d4b2a4d";
+
+function normalizeHexDigest(value, fieldName) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${fieldName} must be a string`);
+  }
+  if (!/^0x[0-9a-fA-F]{64}$/.test(value)) {
+    throw new Error(`${fieldName} must be a 0x-prefixed 32-byte hex digest`);
+  }
+  return value.toLowerCase();
+}
+
+function stableJson(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+}
+
+function rpcCall(url, method, params) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method, params });
+    const urlObj = new URL(url);
+    const options = {
+      hostname: urlObj.hostname,
+      path: urlObj.pathname,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+      },
+    };
+    const req = https.request(options, (res) => {
+      let data = "";
+      res.on("data", (chunk) => { data += chunk; });
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.error) reject(new Error(`RPC error: ${parsed.error.message}`));
+          else resolve(parsed.result);
+        } catch (e) {
+          reject(new Error(`Failed to parse RPC response: ${data}`));
+        }
+      });
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+function decodeRevocationRecord(hex) {
+  const data = hex.startsWith("0x") ? hex.slice(2) : hex;
+  const revocationDigest = "0x" + data.slice(0, 64);
+  const revoker          = "0x" + data.slice(64, 128).slice(24);
+  const timestamp        = parseInt(data.slice(128, 192), 16);
+  const exists           = data.slice(192, 256) !== "0".repeat(64);
+  return { revocationDigest, revoker, timestamp, exists };
+}
+
+async function buildRevocationDigest(originalDigest, metadata = {}) {
+  const normalizedOriginalDigest = normalizeHexDigest(originalDigest, "originalDigest");
+  const payload = { originalDigest: normalizedOriginalDigest, ...metadata };
+  const encoded = stableJson(payload);
+  return `0x${crypto.createHash("sha256").update(encoded).digest("hex")}`;
+}
+
+async function checkRevocationStatus(originalDigest, chainId, rpcUrl, contractAddress) {
+  normalizeHexDigest(originalDigest, "originalDigest");
+
+  const resolvedRpc      = rpcUrl      || RPC[chainId];
+  const resolvedContract = contractAddress || REVOCATION_CONTRACTS[chainId];
+
+  if (!resolvedRpc)      throw new Error(`no RPC endpoint for chain ${chainId} — pass rpcUrl explicitly`);
+  if (!resolvedContract) throw new Error(`no contract address for chain ${chainId} — pass contractAddress explicitly`);
+
+  const digestHex = originalDigest.slice(2).toLowerCase();
+  const calldata  = GET_REVOCATION_SELECTOR + digestHex;
+
+  let result;
+  try {
+    result = await rpcCall(resolvedRpc, "eth_call", [
+      { to: resolvedContract, data: calldata },
+      "latest",
+    ]);
+  } catch (e) {
+    throw new Error(`RPC call failed: ${e.message}`);
+  }
+
+  if (!result || result === "0x") return { status: "NOT_FOUND", record: null };
+
+  const record = decodeRevocationRecord(result);
+  if (!record.exists) return { status: "NOT_FOUND", record: null };
+
+  return { status: "REVOKED", record };
+}
+
+async function verifyWithRevocation(originalDigest, asOfTimestamp, chainId, rpcUrl, contractAddress) {
+  normalizeHexDigest(originalDigest, "originalDigest");
+
+  if (typeof asOfTimestamp !== "number") {
+    throw new TypeError("asOfTimestamp must be a number (Unix seconds)");
+  }
+
+  const { status, record } = await checkRevocationStatus(
+    originalDigest, chainId, rpcUrl, contractAddress
+  );
+
+  if (status === "NOT_FOUND") return "NOT_FOUND";
+  if (record.timestamp <= asOfTimestamp) return "REVOKED";
+  return "VALID";
+}
+
+module.exports = {
+  buildRevocationDigest,
+  checkRevocationStatus,
+  verifyWithRevocation,
+  stableJson,
+  REVOCATION_EVENT_TOPIC,
+};

package/reference-cli/temporal-bounds.js

@@ -0,0 +1,164 @@
+// temporal-bounds.js — zero-dependency temporal bound helper for OCP
+// CommonJS, Node.js >=18
+// Spec: docs/spec/appendix-temporal-bounds-r.md
+
+"use strict";
+
+const https = require("https");
+
+// RPC endpoints — no API key required
+const RPC = {
+  "eip155:1":        "https://cloudflare-eth.com",
+  "eip155:8453":     "https://mainnet.base.org",
+  "eip155:84532":    "https://sepolia.base.org",
+  "eip155:11155111": "https://rpc.sepolia.org",
+};
+
+// Finality table — F(L) per network
+// Source: docs/spec/appendix-temporal-bounds-r.md
+const FINALITY = {
+  "eip155:1": {
+    safe_depth: 64,
+    finality_window_seconds: 720,
+    validator_influence_window: 12,
+    finality_model: "Casper FFG — 2 epochs",
+  },
+  "eip155:8453": {
+    safe_depth: 32,
+    finality_window_seconds: 420,
+    validator_influence_window: 2,
+    finality_model: "L2 soft finality",
+    l1_chain_id: "eip155:1",
+  },
+  "eip155:84532": {
+    safe_depth: 32,
+    finality_window_seconds: 420,
+    validator_influence_window: 2,
+    finality_model: "L2 soft finality",
+    l1_chain_id: "eip155:11155111",
+  },
+  "eip155:11155111": {
+    safe_depth: 64,
+    finality_window_seconds: 720,
+    validator_influence_window: 12,
+    finality_model: "Casper FFG — 2 epochs",
+  },
+};
+
+function rpcCall(url, method, params) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({ jsonrpc: "2.0", id: 1, method, params });
+    const urlObj = new URL(url);
+    const options = {
+      hostname: urlObj.hostname,
+      path: urlObj.pathname,
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(body),
+      },
+    };
+    const req = https.request(options, (res) => {
+      let data = "";
+      res.on("data", (chunk) => { data += chunk; });
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(data);
+          if (parsed.error) reject(new Error(`RPC error: ${parsed.error.message}`));
+          else resolve(parsed.result);
+        } catch (e) {
+          reject(new Error(`Failed to parse RPC response: ${data}`));
+        }
+      });
+    });
+    req.on("error", reject);
+    req.write(body);
+    req.end();
+  });
+}
+
+function toIso8601(unixSeconds) {
+  return new Date(unixSeconds * 1000).toISOString();
+}
+
+function normalizeHexDigest(value, fieldName) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${fieldName} must be a string`);
+  }
+  if (!/^0x[0-9a-fA-F]{64}$/.test(value)) {
+    throw new Error(`${fieldName} must be a 0x-prefixed 32-byte hex digest`);
+  }
+  return value.toLowerCase();
+}
+
+async function getTemporalBound(txHash, chainId, rpcUrl) {
+  if (!txHash || !/^0x[0-9a-fA-F]{64}$/.test(txHash)) {
+    throw new Error("txHash must be a 0x-prefixed 32-byte hex string");
+  }
+
+  const finality = FINALITY[chainId];
+  if (!finality) {
+    throw new Error(`unsupported chainId: ${chainId} — add to FINALITY table`);
+  }
+
+  const resolvedRpc = rpcUrl || RPC[chainId];
+  if (!resolvedRpc) {
+    throw new Error(`no RPC endpoint for chain ${chainId} — pass rpcUrl explicitly`);
+  }
+
+  // Step 1 — fetch transaction receipt to get block number
+  let receipt;
+  try {
+    receipt = await rpcCall(resolvedRpc, "eth_getTransactionReceipt", [txHash]);
+  } catch (e) {
+    throw new Error(`RPC call failed: ${e.message}`);
+  }
+  if (!receipt) throw new Error(`transaction not found: ${txHash}`);
+
+  const blockNumber = parseInt(receipt.blockNumber, 16);
+
+  // Step 2 — fetch block to get timestamp
+  let block;
+  try {
+    block = await rpcCall(resolvedRpc, "eth_getBlockByNumber", [receipt.blockNumber, false]);
+  } catch (e) {
+    throw new Error(`RPC call failed fetching block: ${e.message}`);
+  }
+  if (!block) throw new Error(`block not found: ${receipt.blockNumber}`);
+
+  const blockTimestamp = parseInt(block.timestamp, 16);
+
+  // Step 3 — fetch current block number to compute finality depth
+  let currentBlockHex;
+  try {
+    currentBlockHex = await rpcCall(resolvedRpc, "eth_blockNumber", []);
+  } catch (e) {
+    throw new Error(`RPC call failed fetching current block: ${e.message}`);
+  }
+  const currentBlock = parseInt(currentBlockHex, 16);
+  const depth = currentBlock - blockNumber;
+  const finalized = depth >= finality.safe_depth;
+
+  // Step 4 — compute upper bound
+  const upperBound = blockTimestamp + finality.validator_influence_window;
+
+  return {
+    tx_hash: txHash,
+    chain_id: chainId,
+    block_number: blockNumber,
+    block_timestamp: blockTimestamp,
+    block_timestamp_iso: toIso8601(blockTimestamp),
+    finality_depth_confirmed: depth,
+    finality_depth_required: finality.safe_depth,
+    finality_model: finality.finality_model,
+    finalized,
+    validator_influence_window: finality.validator_influence_window,
+    upper_bound: upperBound,
+    upper_bound_iso: toIso8601(upperBound),
+  };
+}
+
+module.exports = {
+  getTemporalBound,
+  FINALITY,
+};