ocp-verify 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this package will be documented in this file.
+
+## [2.0.0] — 2026-06-10
+
+First release implementing ERC-8281 (`erc8281/1`) with the Extraction Profiles extension.
+
+### Added
+
+- Full 5-step verification invariant: recompute → compare → confirm inclusion → confirm committer → confirm block, with fail-closed semantics (partial verification is never reported as success).
+- Extraction profile registry with both registered profiles:
+  - `recorded` (default) — `Recorded(bytes32,address)`, 3 topics, digest at `topics[1]`, committer at `topics[2]`.
+  - `erc8263-anchorproof` — `AnchorProof(uint8,bytes32,bytes32,address,bytes)`, 4 topics, digest (`proofHash`) at `topics[2]`, committer (`operator`) at `topics[3]`, with the `proofHash != bytes32(0)` canonical-form assertion. `agentId` is not authenticated.
+- Dependency-free hash implementations for the full registry: `sha2-256` (node:crypto), `keccak-256` (pure JS), `blake2b-256` (pure JS, parameterized digest length per RFC 7693 — not truncated BLAKE2b-512), each validated against known vectors via `selfTest()`.
+- Envelope schema validation and field normalization: exact-match `erc8281/1` version check, decoded-value comparisons throughout, EIP-55 checksum validation with rejection of invalid addresses, unknown-field tolerance.
+- `eth_chainId` verification against the envelope's `chain_id` before any receipt fetch.
+- Log selection by `receipt_log_position` (receipt-array position, explicitly not the block-scoped JSON-RPC `logIndex`).
+- Strict topic-count assertions per profile (exactly 3 for `recorded`, exactly 4 for `erc8263-anchorproof`), rejecting crafted logs with a matching topic-0 but wrong shape.
+- Optional `block_hash` handled as MUST-when-present against the receipt's `blockHash` (reorg detection).
+- Rejection of unregistered extraction profiles and non-registry hash functions.
+- Verified constants exported: `TOPIC0_RECORDED` (`0xdca60c2087041cbb12d9a57628c6cad28ecbd0437e47c7ab6c3aa6e162bf4497`), `TOPIC0_ERC8263_ANCHORPROOF` (`0x9fe832d83a52f83bd7d54181e4cc7ff8b4e227cc1d3a0144376894b5df6c23cc`), `ERC165_INTERFACE_ID` (`0xb5c645bd`).
+- `httpProvider(rpcUrl)` convenience provider (global fetch, Node 18+) and injectable-provider design for multi-endpoint cross-checking or offline fixtures.
+- Dual ESM/CommonJS entry points with zero runtime dependencies; Node.js >= 18.
+- Conformance suite: ERC-8281 test vectors 1–21 plus the BLAKE2b-truncation negative companion (03b) as offline fixtures, hash self-tests, constant recomputation, EIP-55 unit vectors, and an authenticated-field mutation sweep. 26 tests.
+
+### Breaking changes from pre-release (`ocp/1.0`) tooling
+
+- Event signature is `Recorded(bytes32,address)` — the v0 `Recorded(bytes32,address,uint256)` signature and its topic-0 are not supported.
+- Envelope requires `receipt_log_position`; the v0 `timestamp` field is removed; version string is `erc8281/1`.

package/README.md

@@ -1,399 +1,123 @@
-# Observation Commitment Protocol (OCP)
+# ocp-verify
 
-If one byte changes, verification fails — across any chain, any system.
+Reference verifier for **ERC-8281 — Observation Commitment Protocol (OCP)**.
 
-A chain-agnostic primitive for independently verifying that a specific byte sequence was committed to a public ledger.
+Independently confirm that a specific byte sequence was committed on-chain — *recompute → compare → confirm inclusion* — using only an RPC endpoint or local node. No trusted SDK, gateway, or indexer.
 
-Minimal. Verifiable. System-independent.
+- Implements the full 5-step ERC-8281 verification invariant (`erc8281/1`)
+- Supports both registered extraction profiles: `recorded` (default) and `erc8263-anchorproof`
+- All three registry hash functions — `sha2-256`, `keccak-256`, `blake2b-256` — implemented dependency-free and validated against known vectors at test time
+- **Zero runtime dependencies.** Node.js 18+. ESM and CommonJS.
 
----
+## Installation
 
-## ⚡ 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
-
-### 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
-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
+```sh
+npm install ocp-verify
 ```
 
-### 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
+## Usage
 
-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);
-    }
+```js
+// ESM
+import { verify, httpProvider } from 'ocp-verify';
+
+// CommonJS
+// const { verify, httpProvider } = require('ocp-verify');
+
+const envelope = {
+  version: 'erc8281/1',
+  digest: '0x6f3a…',                 // hash of the observation bytes
+  hash_function: 'sha2-256',
+  chain_id: '42161',
+  contract: '0x0C0117AC70000000000000000000000000000001',
+  tx_hash: '0x9be1…',
+  block_number: '352800417',
+  receipt_log_position: '0',
+  committer: '0xc0Aa17dE0000000000000000000000000000beEf',
+  // optional:
+  // block_hash: '0x…',              // MUST match the receipt's blockHash when present
+  // extraction_profile: 'recorded', // defaults to 'recorded' when absent
+};
+
+const observationBytes = new Uint8Array(/* the observed bytes, supplied out-of-band */);
+
+const result = await verify(envelope, observationBytes, httpProvider('https://arb1.arbitrum.io/rpc'));
+
+if (result.valid) {
+  // the observation bytes were committed on-chain at the referenced block
+  // by the declared committer
+} else {
+  console.error('rejected:', result.reason); // e.g. 'digest_mismatch'
 }
 ```
 
-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
-
----
+The result is `{ valid: true }` or `{ valid: false, reason }`. Partial verification is never reported as success.
 
-## In the Wild
+### Custom providers
 
-OCP is being adopted as the Layer 3 commitment primitive in the ERC-8004 Universal AI Inference Verification Registry stack:
+`verify()` takes any object with `eth_chainId()` and `eth_getTransactionReceipt(txHash)`. Use this to cross-check multiple RPC endpoints, route through a light client, or run offline against fixtures (this is how the conformance suite works):
 
-```
-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`
-- ✅ Conformance Suite → `/conformance/run-conformance.sh`
-- ⚙️ 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
+```js
+const provider = {
+  eth_chainId: async () => '0xa4b1',
+  eth_getTransactionReceipt: async (txHash) => myReceiptSource(txHash),
+};
 ```
 
----
+## What verification proves — and what it doesn't
 
-## Status
+A passing verification authenticates these envelope fields: `digest`, `hash_function`, `chain_id`, `contract`, `tx_hash`, `receipt_log_position`, `committer`, `block_number`, `block_hash` (when present), and `extraction_profile` (when present). It proves the supplied observation bytes hash to a digest that the named contract emitted in an event of the declared profile's shape, in the referenced transaction and block, by the declared committer.
 
-v1.0.0 — Cross-Chain Primitive  
-Phase 1 complete — proof envelope schema  
-Phase 2 complete — EVM reference implementation live  
-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)
+It does **not** prove that the contract is a conforming ERC-8281 deployment (any contract can emit an event with the canonical signature — check ERC-165 interface ID `0xb5c645bd` or maintain a registry of trusted addresses), that the committer authored the observation, or anything about fields a profile doesn't extract (under `erc8263-anchorproof`, the `agentId` is **not** authenticated).
 
+## Envelope schema (`erc8281/1`)
 
----
+| Field | Required | Format |
+|---|---|---|
+| `version` | yes | exact string `erc8281/1` |
+| `digest` | yes | 0x-prefixed lowercase hex, 32 bytes |
+| `hash_function` | yes | `sha2-256` \| `keccak-256` \| `blake2b-256` |
+| `chain_id` | yes | decimal string, EIP-155 chain ID |
+| `contract` | yes | EIP-55 checksummed address (invalid checksums are rejected) |
+| `tx_hash` | yes | 0x-prefixed lowercase hex, 32 bytes |
+| `block_number` | yes | decimal string |
+| `receipt_log_position` | yes | decimal string — array position within `receipt.logs`. **NOT the JSON-RPC `logIndex` field**, which is block-scoped |
+| `committer` | yes | EIP-55 checksummed address |
+| `block_hash` | no | 0x-prefixed lowercase hex, 32 bytes; when present, MUST equal the receipt's `blockHash` (reorg detection) |
+| `extraction_profile` | no | registered profile identifier; defaults to `recorded` |
 
-## Revocation Extension (v1.1.0)
+Unknown additional fields are ignored. All comparisons are over decoded bytes/integers, never raw strings. `blake2b-256` is the *parameterized* form (digest length in the BLAKE2b parameter block) — not a truncation of BLAKE2b-512.
 
-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.
+## Extraction profiles
 
-```js
-const { verifyWithRevocation } = require('ocp-verify/reference-cli/revoke.js');
-
-const status = await verifyWithRevocation(
-  digest,
-  asOfTimestamp,
-  'eip155:84532'
-);
-// returns VALID | REVOKED | NOT_FOUND
-```
+| Profile | Event | Topics | Digest | Committer |
+|---|---|---|---|---|
+| `recorded` (default) | `Recorded(bytes32,address)` | exactly 3 | `topics[1]` | `topics[2]` |
+| `erc8263-anchorproof` | `AnchorProof(uint8,bytes32,bytes32,address,bytes)` | exactly 4 | `topics[2]` (`proofHash`) | `topics[3]` (`operator`) |
 
-- 📄 Revocation Spec → `/docs/spec/appendix-revocation-r.md`
-- ⛓️ Deployed Contract → `0x2fa07c85439850ff6C5688d926bDa6DaEe62Db15` (Base Sepolia)
-- ✅ Revocation Conformance → `/conformance/revocation/run-revocation-conformance.sh`
-- 🔑 Event Topic → `0xc19951599a519bc320c0f352b2f92f315e8a2368bd0efb2e5dca3b1196e76112`
+Verified topic-0 constants:
 
----
+- `recorded`: `0xdca60c2087041cbb12d9a57628c6cad28ecbd0437e47c7ab6c3aa6e162bf4497`
+- `erc8263-anchorproof`: `0x9fe832d83a52f83bd7d54181e4cc7ff8b4e227cc1d3a0144376894b5df6c23cc`
 
-## Status
+Profiles are a closed registry — envelopes cannot supply inline event signatures or topic indices, which would hand the prover control over what the verifier reads. Unregistered profile identifiers are rejected (`profile_not_registered`). The `erc8263-anchorproof` profile additionally enforces the ERC-8263 canonical-form guard `proofHash != bytes32(0)`.
 
-v1.1.0 — Revocation Extension
-Phase 6 complete — additive revocation primitive, 8/8 conformance tests pass
+## Security notes
 
-## Temporal Bounds Extension (v1.2.0)
+- **RPC trust.** A single RPC endpoint is a trusted party. `verify()` checks the endpoint's `eth_chainId` against the envelope before fetching, but an endpoint can still lie about receipts. For stronger guarantees, supply a provider that cross-checks independent endpoints or verifies receipts against light-client headers.
+- **Finality.** A commitment is only as final as its block. Require finalized blocks or a confirmation depth appropriate to the chain and the value at risk; on L2s, understand the settlement tier you're getting. Include `block_hash` in envelopes to detect post-reorg block migration.
+- **Hash allowlist.** Only the three registry functions are accepted; everything else is rejected (`hash_function_not_allowed`). This prevents a prover from declaring a weak hash and presenting a colliding observation.
+- **Low-entropy observations.** The commitment is binding but not hiding — a digest of a predictable document is a dictionary-attack target. Salt low-entropy observations before hashing and supply the salt as part of the observation bytes.
+- **Reverted transactions** carry no valid commitments; receipts with `status != 1` are rejected.
 
-OCP now includes an optional temporal bounds layer. Derives a finality-bounded existence proof from on-chain state — no oracles, no trusted time servers.
+## Conformance testing
 
-```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
+```sh
+npm test
 ```
 
-- 📄 Temporal Bounds Spec → `/docs/spec/appendix-temporal-bounds-r.md`
-- ✅ Conformance → `/conformance/temporal-bounds/run-temporal-bounds-conformance.sh`
-
----
+Runs the full ERC-8281 vector suite (vectors 1–21 plus the BLAKE2b negative companion 03b) against offline fixtures, validates all three hash implementations against known vectors, verifies the topic-0 and ERC-165 constants by recomputation, and runs a mutation sweep confirming that altering any authenticated field flips verification to rejection. No network access required.
 
-## Status
+## License
 
-v1.2.0 — Temporal Bounds Extension
-Phase 7 complete — finality-derived temporal bounds, 8/8 conformance tests pass
+CC0-1.0

package/package.json

@@ -1,41 +1,42 @@
 {
   "name": "ocp-verify",
-  "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",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "bin": {
-    "ocp-commit": "reference-cli/commit.js",
-    "ocp-verify": "reference-cli/verify.js"
+  "version": "2.0.0",
+  "description": "ERC-8281 Observation Commitment Protocol (OCP) reference verifier: recompute → compare → confirm inclusion. Dependency-free, supports the recorded and erc8263-anchorproof extraction profiles.",
+  "license": "CC0-1.0",
+  "author": "Damon Zwicker <damon@ocp-labs.org>",
+  "homepage": "https://ocp-labs.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/damonzwicker/observation-commitment-protocol"
   },
-  "files": [
-    "reference-cli",
-    "README.md",
-    "LICENSE"
-  ],
   "keywords": [
+    "erc-8281",
     "ocp",
-    "observation-commitment-protocol",
-    "blockchain",
+    "observation-commitment",
     "verification",
-    "proof",
     "ethereum",
-    "base",
-    "solana",
-    "ai-verification",
-    "zero-dependency",
-    "cryptography"
+    "proof",
+    "commitment",
+    "erc-8263"
   ],
-  "author": "Damon Zwicker",
-  "homepage": "https://github.com/damonzwicker/observation-commitment-protocol",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/damonzwicker/observation-commitment-protocol.git"
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.mjs",
+      "require": "./src/index.js"
+    }
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
   },
-  "bugs": {
-    "url": "https://github.com/damonzwicker/observation-commitment-protocol/issues"
-  }
+  "dependencies": {}
 }