ocp-verify 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Damon Zwicker
+
+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 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

@@ -0,0 +1,332 @@
+# Observation Commitment Protocol (OCP)
+
+If one byte changes, verification fails — across any chain, any system.
+
+A chain-agnostic primitive for independently verifying that a specific byte sequence was committed to a public ledger.
+
+Minimal. Verifiable. System-independent.
+
+---
+
+## ⚡ 30-Second Demo (start here)
+
+```bash
+cd examples/oh-shit-demo
+./run-demo.sh
+```
+
+Expected:
+
+```
+VALID  
+INVALID  
+```
+
+If one byte changes, verification fails — across any system.
+
+---
+
+## 🔌 Integrate in 2 Minutes
+
+### 1) Commit (produce a proof)
+
+```bash
+npx ocp-commit report.txt
+```
+
+This automatically creates:
+
+```bash
+report.proof.json
+```
+
+### 2) Verify (anywhere, later)
+
+```bash
+npx ocp-verify report.txt
+```
+
+Expected:
+
+```
+VALID
+```
+
+If any byte changes:
+
+```
+INVALID: hash mismatch
+```
+
+### 3) Test tampering (optional)
+
+```bash
+npx ocp-verify tampered.txt report.proof.json
+```
+
+### 4) Use in your system
+
+- Save the file + proof together
+- Or store the proof alongside records/logs
+- Verification requires only the file and the proof
+
+No API. No platform dependency.
+
+---
+
+## The Problem
+
+Every AI system running today has the same problem.
+
+You can't verify what it did.
+
+Not really. You can ask the platform. You can trust the logs. You can hope the provider is telling the truth. But there is no independent, tamper-proof record of what an AI received, what it produced, and whether anything was changed in between.
+
+Most digital systems can prove things — but only **inside themselves**.
+
+Step outside the system, and verification depends on:
+- APIs
+- platforms
+- intermediaries
+
+OCP eliminates that dependency entirely.
+
+---
+
+## Where This Breaks Without OCP
+
+- AI outputs cannot be independently verified
+- Legal evidence depends on originating systems
+- APIs and platforms are non-permanent
+- Digital artifacts become disputable over time
+
+Without a system-independent verification boundary,
+"what actually happened" becomes ambiguous.
+
+---
+
+## Use Cases
+
+OCP can be used anywhere a digital artifact may need to be independently verified later:
+
+- AI outputs and execution traces
+- Legal evidence and filings
+- Audit logs and compliance records
+- Media provenance
+- File integrity
+- Institutional records
+
+### Example: Verifying an AI Output
+
+An AI system generates a report:
+
+```text
+AI Risk Assessment: MEDIUM_RISK
+Approved for internal review.
+```
+
+That output is committed using OCP.
+
+Later, the report is modified:
+
+```text
+AI Risk Assessment: LOW_RISK
+Approved for internal review.
+```
+
+Using the original proof:
+
+- the original output verifies as VALID
+- the modified output returns INVALID
+
+The difference is one word.
+
+Verification does not depend on the AI system, API, or platform.
+
+It depends only on the bytes.
+
+---
+
+## The Protocol
+
+An observation is any byte sequence.
+
+```
+data → digest → public commitment
+```
+
+Verification reduces to:
+
+```
+recompute → compare → confirm inclusion
+```
+
+A verifier:
+- recomputes the digest
+- compares it to the committed value
+- confirms that the digest exists in a referenced transaction
+
+No API. No platform dependency. No trust in the originating system.
+
+---
+
+## Proof Envelope
+
+OCP proofs are self-describing, chain-agnostic JSON artifacts. A valid proof envelope is verifiable against raw ledger data — no SDK, no RPC provider, no indexer required.
+
+```json
+{
+  "ocp": "1.0",
+  "chain": {
+    "id": "eip155:84532",
+    "namespace": "evm"
+  },
+  "commitment": {
+    "digest": "14cca453684a18c1ef3e1c0b9a7744cfa06942660719bba373ef5fc36208bf73",
+    "hash_function": "sha2-256",
+    "serialization": "raw-bytes"
+  },
+  "ledger_ref": {
+    "transaction_id": "0xf2e1f6c085768b4e3d60463717d52bb2a338803a74a4cfd48aea5738d2595ddd",
+    "block_height": 41658348,
+    "block_hash": "0x...",
+    "finality": {
+      "depth": 3,
+      "assertion_time_utc": "2026-05-17T12:00:00Z"
+    }
+  },
+  "extraction": {
+    "rule_id": "evm/event-log",
+    "rule_version": "1.0.0"
+  },
+  "meta": {
+    "created_utc": "2026-05-17T12:00:05Z",
+    "envelope_version": "1.0"
+  }
+}
+```
+
+---
+
+## Reference Implementation — Live on Base Sepolia
+
+Contract: `0x0963Fd33DF80c94360F2DC22e5c09517AeE7ED5c`
+
+```solidity
+contract ObservationCommitment {
+    event Recorded(bytes32 indexed digest, address indexed recorder);
+
+    function record(bytes32 digest) external {
+        emit Recorded(digest, msg.sender);
+    }
+}
+```
+
+Live verification — zero dependencies, Node.js stdlib only:
+
+```
+  hash      MATCH  14cca453684a18c1ef3e1c0b9a7744cfa06942660719bba373ef5fc36208bf73
+  chain     eip155:84532
+  rpc       https://sepolia.base.org
+  tx        0xf2e1f6c085768b4e3d60463717d52bb2a338803a74a4cfd48aea5738d2595ddd
+  logs      found 1 Recorded event(s)
+  digest    MATCH  14cca453684a18c1ef3e1c0b9a7744cfa06942660719bba373ef5fc36208bf73
+
+VALID
+```
+
+---
+
+## What OCP Defines
+
+- A minimal verification model
+- A system-independent verification boundary
+- A portable, self-describing proof envelope (chain-agnostic)
+- A formal extraction rule registry (`evm/event-log`, `solana/instruction-data`)
+
+---
+
+## What OCP Does Not Define
+
+- Storage
+- Identity
+- Authorship
+- Canonical encoding
+- Application-layer semantics
+- Sanitization or preprocessing pipelines
+
+---
+
+## In the Wild
+
+OCP is being adopted as the Layer 3 commitment primitive in the ERC-8004 Universal AI Inference Verification Registry stack:
+
+```
+L2 — input provenance:  raw → sanitize → commit
+L3 — OCP:              digest → on-chain → verify from raw block
+L4 — EIP-712 signed inference attestation
+L5 — registry routes to zkML / opML / TEE
+```
+
+The identity pipeline sentinel hash has been confirmed between two independent implementations:
+
+```
+8116eec29078e8f57c07077d5e8080a35bde73036581df3abb93755d1b1a16ea
+```
+
+The full stack is live in production. L3 tx on Base Sepolia, block 41731493:
+https://sepolia.basescan.org/tx/0xc3aeb16d0aef167e2ebc6d4afc9333fcd13a71b8c02e5485bc6be7491e393319
+
+Thread: https://ethereum-magicians.org/t/draft-erc-universal-ai-inference-verification-registry/28083/20
+
+---
+
+## Why It Matters
+
+OCP separates **verification from systems**.
+
+A verifier does not ask what's true —
+they compute it.
+
+The network only confirms that a commitment exists.
+
+---
+
+## Start Here
+
+- 📄 Core Specification → `/docs/spec/ocp-v1.0.0.md`
+- 🗂️ Proof Envelope → `/docs/spec/ocp-proof-envelope-v1.0.0.md`
+- ⛓️ EVM Extraction Rule → `/docs/spec/appendix-evm-r.md`
+- 🔗 Solana Extraction Rule → `/docs/spec/appendix-solana-r.md`
+- 🤖 AI Inference Attestation → `/docs/spec/appendix-ai-inference-attestation.md`
+- 🧾 Proof Format → `/docs/spec/proof-format-v1.md`
+- 🔍 Examples → `/examples`
+- ⚙️ Contracts → `/contracts`
+- 🌐 Live Demo → https://observation-commitment-protocol.vercel.app/
+
+Reference implementation (VeraFile):
+https://github.com/damonzwicker/verafile
+
+---
+
+## Quick Verify
+
+```bash
+npx ocp-verify examples/example-observation.txt
+```
+
+Expected output:
+
+```
+VALID
+```
+
+---
+
+## Status
+
+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  
+First external contribution merged — dinamic.eth / ERC-8004 (PR #1)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "ocp-verify",
+  "version": "1.0.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",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "bin": {
+    "ocp-commit": "reference-cli/commit.js",
+    "ocp-verify": "reference-cli/verify.js"
+  },
+  "files": [
+    "reference-cli",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ocp",
+    "observation-commitment-protocol",
+    "blockchain",
+    "verification",
+    "proof",
+    "ethereum",
+    "base",
+    "solana",
+    "ai-verification",
+    "zero-dependency",
+    "cryptography"
+  ],
+  "author": "Damon Zwicker",
+  "homepage": "https://github.com/damonzwicker/observation-commitment-protocol",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/damonzwicker/observation-commitment-protocol.git"
+  },
+  "bugs": {
+    "url": "https://github.com/damonzwicker/observation-commitment-protocol/issues"
+  }
+}

package/reference-cli/README.md

@@ -0,0 +1,82 @@
+# OCP Reference Verifier
+
+A minimal, zero-dependency verifier for OCP proofs.
+
+This script demonstrates the core verification invariant:
+
+recompute → compare → confirm inclusion
+
+---
+
+## Usage
+
+Run:
+
+node verify.js <file> <proof.json>
+
+Example:
+
+node verify.js ../examples/example-observation.txt ../examples/example-proof.ocp.json
+
+---
+
+## What It Does
+
+The verifier performs:
+
+1. Computes SHA-256 hash of the file  
+2. Compares it to the `hash` field in the proof  
+3. Outputs VALID or INVALID  
+
+---
+
+## Output
+
+If the file matches the proof:
+
+VALID: file hash matches proof hash
+
+If the file has been modified:
+
+INVALID: hash mismatch
+
+---
+
+## Important
+
+This verifier checks only:
+
+- recompute  
+- compare  
+
+It does not perform:
+
+- transaction lookup  
+- extraction rule execution  
+- on-chain verification  
+
+Those steps are defined in the protocol and must be performed independently.
+
+---
+
+## Purpose
+
+This script exists to demonstrate:
+
+- minimal verification logic  
+- independence from any platform or API  
+- reproducibility of OCP proofs  
+
+It is not a production tool.
+
+---
+
+## Next Steps
+
+To fully verify a proof:
+
+1. Resolve `txHash` on the specified network  
+2. Apply `extractionRule`  
+3. Confirm the digest exists in the transaction  
+
+This completes the OCP verification process.

package/reference-cli/commit.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const crypto = require("crypto");
+
+const [, , filePath, proofArg] = process.argv;
+
+if (!filePath) {
+  console.error("Usage: ocp-commit <file> [proof.json]");
+  process.exit(1);
+}
+
+if (!fs.existsSync(filePath)) {
+  console.error(`ERROR: file not found: ${filePath}`);
+  process.exit(1);
+}
+
+const proofPath =
+  proofArg ||
+  filePath.replace(/(\.[^/.]+)?$/, ".proof.json");
+
+const fileBytes = fs.readFileSync(filePath);
+const hash = "0x" + crypto.createHash("sha256").update(fileBytes).digest("hex");
+
+const proof = {
+  version: "ocp-1",
+  hash,
+  txHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+  network: "demo-local",
+  contract: "0x0000000000000000000000000000000000000000",
+  extractionRule: "demo:proof.hash"
+};
+
+fs.writeFileSync(proofPath, JSON.stringify(proof, null, 2) + "\n");
+
+// Clean output
+console.log(`COMMITTED: ${filePath} → ${proofPath}`);

package/reference-cli/hash-browser.js

@@ -0,0 +1,67 @@
+// OCP Reference: Browser-native digest computation
+// Uses Web Crypto API — no dependencies, no libraries
+// Companion to reference-cli/verify.js (Node.js implementation)
+//
+// Spec: docs/spec/appendix-evm-r.md
+// This is the write-side primitive: observation → digest
+// The digest produced here is what gets passed to record(bytes32) on-chain
+
+"use strict";
+
+/**
+ * Compute the OCP digest of a File object.
+ *
+ * Implements the commitment procedure from appendix-evm-r.md:
+ *   - Serialization: raw-bytes (no encoding applied)
+ *   - Hash function: sha2-256
+ *   - Output: lowercase hex string, no 0x prefix
+ *
+ * @param {File} file - Any File object (browser File API)
+ * @returns {Promise<string>} SHA-256 digest as lowercase hex, no 0x prefix
+ */
+async function hashFile(file) {
+  const buffer = await file.arrayBuffer();
+  const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Compute the OCP digest of an arbitrary byte array.
+ *
+ * @param {ArrayBuffer|Uint8Array} bytes - Raw bytes
+ * @returns {Promise<string>} SHA-256 digest as lowercase hex, no 0x prefix
+ */
+async function hashBytes(bytes) {
+  const buffer = bytes instanceof ArrayBuffer ? bytes : bytes.buffer;
+  const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/**
+ * Compute the OCP digest of a UTF-8 string.
+ * Note: the string is encoded as UTF-8 before hashing.
+ * The verifier must apply the same encoding to reproduce the digest.
+ *
+ * @param {string} text - UTF-8 string
+ * @returns {Promise<string>} SHA-256 digest as lowercase hex, no 0x prefix
+ */
+async function hashString(text) {
+  const bytes = new TextEncoder().encode(text);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", bytes);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return hashArray.map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// Usage example:
+//
+// const file = document.querySelector('input[type="file"]').files[0];
+// const digest = await hashFile(file);
+// // digest is ready to pass to record(bytes32) on-chain
+// // or to include in an OCP proof envelope as commitment.digest
+
+// Node.js export (if used in a build pipeline)
+if (typeof module !== "undefined") {
+  module.exports = { hashFile, hashBytes, hashString };
+}

package/reference-cli/verify.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+// OCP Reference Verifier v2.1.0
+// Implements: evm/event-log extraction rule
+// Dependencies: zero — Node.js stdlib only (https, crypto, fs)
+// Spec: docs/spec/appendix-evm-r.md
+
+"use strict";
+
+const fs = require("fs");
+const crypto = require("crypto");
+const https = require("https");
+
+// RPC endpoints — no API key required
+const RPC = {
+  "eip155:84532":    "https://sepolia.base.org",
+  "eip155:8453":     "https://mainnet.base.org",
+  "eip155:1":        "https://cloudflare-eth.com",
+  "eip155:11155111": "https://rpc.sepolia.org",
+};
+
+// Network name to CAIP-2 chain ID (proof-format-v1 compatibility)
+const NETWORK_TO_CHAIN_ID = {
+  "base-sepolia": "eip155:84532",
+  "base":         "eip155:8453",
+  "mainnet":      "eip155:1",
+  "homestead":    "eip155:1",
+  "sepolia":      "eip155:11155111",
+};
+
+// keccak256("Recorded(bytes32,address)")
+// Confirmed from live Base Sepolia transaction logs
+const KNOWN_EVENT_TOPIC = "0xdca60c2087041cbb12d9a57628c6cad28ecbd0437e47c7ab6c3aa6e162bf4497";
+
+// Identity pipeline sentinel hash
+// Canonical identity spec: ipfs://QmTst97dG8i9tFrutdetqMbVhSHqJGJaxMmPzWCcVVTWDU
+// Confirmed independently against Dinamic.eth implementation — locked
+const IDENTITY_PIPELINE_SENTINEL = "8116eec29078e8f57c07077d5e8080a35bde73036581df3abb93755d1b1a16ea";
+
+function fail(message) {
+  console.error(`INVALID: ${message}`);
+  process.exit(1);
+}
+
+function log(message) {
+  console.log(message);
+}
+
+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 normalizeHash(h) {
+  if (!h) return null;
+  return h.toLowerCase().startsWith("0x") ? h.toLowerCase() : "0x" + h.toLowerCase();
+}
+
+function stripPrefix(h) {
+  if (!h) return null;
+  return h.toLowerCase().startsWith("0x") ? h.slice(2).toLowerCase() : h.toLowerCase();
+}
+
+function applyExtractionRule(receipt, eventTopic) {
+  const extracted = new Set();
+  if (!receipt.logs || !Array.isArray(receipt.logs)) return extracted;
+  for (const log of receipt.logs) {
+    if (!log.topics || log.topics.length < 2) continue;
+    if (normalizeHash(log.topics[0]) !== normalizeHash(eventTopic)) continue;
+    const digest = stripPrefix(log.topics[1]);
+    if (digest) extracted.add(digest);
+  }
+  return extracted;
+}
+
+async function main() {
+  const [, , filePath, proofArg] = process.argv;
+
+  if (!filePath) {
+    console.error("Usage: ocp-verify <file> [proof.json]");
+    console.error("");
+    console.error("Environment:");
+    console.error("  OCP_RPC_URL=<url>   Override RPC endpoint (optional)");
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(filePath)) fail(`file not found: ${filePath}`);
+
+  const proofPath = proofArg || filePath.replace(/(\.[^/.]+)?$/, ".proof.json");
+  if (!fs.existsSync(proofPath)) fail(`proof not found: ${proofPath}`);
+
+  const fileBytes = fs.readFileSync(filePath);
+  let proof;
+  try {
+    proof = JSON.parse(fs.readFileSync(proofPath, "utf8"));
+  } catch {
+    fail("invalid JSON in proof file");
+  }
+
+  const isEnvelope = !!proof.ocp;
+  const isV1 = proof.version === "ocp-1";
+  if (!isEnvelope && !isV1) fail("unrecognized proof format — expected ocp-1 or envelope format");
+
+  let txHash, chainId, commitmentDigest, blockHash;
+
+  if (isV1) {
+    const requiredFields = ["version", "hash", "txHash", "network", "contract", "extractionRule"];
+    for (const field of requiredFields) {
+      if (!proof[field]) fail(`missing required field: ${field}`);
+    }
+    if (!/^0x[a-f0-9]{64}$/.test(proof.hash))        fail("invalid hash format");
+    if (!/^0x[a-fA-F0-9]{64}$/.test(proof.txHash))   fail("invalid txHash format");
+    if (!/^0x[a-fA-F0-9]{40}$/.test(proof.contract)) fail("invalid contract format");
+
+    txHash           = proof.txHash;
+    chainId          = NETWORK_TO_CHAIN_ID[proof.network];
+    commitmentDigest = stripPrefix(proof.hash);
+    blockHash        = null;
+
+    if (!chainId) fail(`unknown network: ${proof.network} — add to NETWORK_TO_CHAIN_ID`);
+
+  } else {
+    if (!proof.chain?.id)                  fail("missing chain.id");
+    if (!proof.chain?.namespace)           fail("missing chain.namespace");
+    if (!proof.commitment?.digest)         fail("missing commitment.digest");
+    if (!proof.commitment?.hash_function)  fail("missing commitment.hash_function");
+    if (!proof.commitment?.serialization)  fail("missing commitment.serialization");
+    if (!proof.ledger_ref?.transaction_id) fail("missing ledger_ref.transaction_id");
+    if (!proof.ledger_ref?.block_hash)     fail("missing ledger_ref.block_hash");
+    if (!proof.extraction?.rule_id)        fail("missing extraction.rule_id");
+
+    if (proof.commitment.hash_function !== "sha2-256")
+      fail(`unsupported hash function: ${proof.commitment.hash_function}`);
+    if (proof.commitment.serialization !== "raw-bytes")
+      fail(`unsupported serialization: ${proof.commitment.serialization}`);
+    if (!proof.extraction.rule_id.startsWith("evm/"))
+      fail(`unsupported extraction rule namespace: ${proof.extraction.rule_id}`);
+
+    txHash           = proof.ledger_ref.transaction_id;
+    chainId          = proof.chain.id;
+    commitmentDigest = proof.commitment.digest.toLowerCase();
+    blockHash        = proof.ledger_ref.block_hash;
+  }
+
+  // Step 1 — Recompute digest
+  const computedHash = crypto.createHash("sha256").update(fileBytes).digest("hex");
+  if (computedHash !== commitmentDigest) {
+    fail(`hash mismatch\n  computed: ${computedHash}\n  proof:    ${commitmentDigest}`);
+  }
+  log(`  hash      MATCH  ${computedHash}`);
+
+  // Step 2 — Resolve RPC
+  const rpcUrl = process.env.OCP_RPC_URL || RPC[chainId];
+  if (!rpcUrl) fail(`no RPC endpoint for chain ${chainId} — set OCP_RPC_URL`);
+
+  log(`  chain     ${chainId}`);
+  log(`  rpc       ${rpcUrl}`);
+  log(`  tx        ${txHash}`);
+
+  // Step 3 — Fetch receipt
+  let receipt;
+  try {
+    receipt = await rpcCall(rpcUrl, "eth_getTransactionReceipt", [txHash]);
+  } catch (e) {
+    fail(`RPC call failed: ${e.message}`);
+  }
+  if (!receipt) fail(`transaction not found: ${txHash}`);
+
+  // Step 4 — Confirm block hash (envelope only)
+  if (blockHash) {
+    const receiptBlockHash  = normalizeHash(receipt.blockHash);
+    const expectedBlockHash = normalizeHash(blockHash);
+    if (receiptBlockHash !== expectedBlockHash) {
+      fail(`block hash mismatch\n  receipt: ${receiptBlockHash}\n  proof:   ${expectedBlockHash}`);
+    }
+    log(`  block     MATCH  ${receiptBlockHash}`);
+  }
+
+  // Step 5 — Apply extraction rule
+  const extracted = applyExtractionRule(receipt, KNOWN_EVENT_TOPIC);
+  if (extracted.size === 0) {
+    fail(
+      `no Recorded events found in transaction ${txHash}\n` +
+      `  event topic: ${KNOWN_EVENT_TOPIC}\n` +
+      `  logs found:  ${receipt.logs?.length ?? 0}`
+    );
+  }
+  log(`  logs      found ${extracted.size} Recorded event(s)`);
+
+  // Step 6 — Confirm inclusion
+  if (!extracted.has(commitmentDigest)) {
+    fail(
+      `digest not found in transaction logs\n` +
+      `  looking for: ${commitmentDigest}\n` +
+      `  found:       ${[...extracted].join(", ")}`
+    );
+  }
+  log(`  digest    MATCH  ${commitmentDigest}`);
+
+  // Step 7 — Report finality
+  if (isEnvelope && proof.ledger_ref?.finality) {
+    const { depth, assertion_time_utc } = proof.ledger_ref.finality;
+    log(`  finality  depth=${depth} at ${assertion_time_utc}`);
+    if (depth < 3) log(`  WARNING   finality depth ${depth} is below recommended minimum (3)`);
+  }
+
+  log("");
+  log("VALID");
+}
+
+main().catch((e) => {
+  console.error(`ERROR: ${e.message}`);
+  process.exit(1);
+});