ocp-verify 1.2.0 → 2.0.0

package/src/hash.js

@@ -0,0 +1,205 @@
+// SPDX-License-Identifier: CC0-1.0
+// ERC-8281 Hash Function Registry implementations — dependency-free.
+//
+// sha2-256:    node:crypto (built-in)
+// keccak-256:  pure JS (original Keccak padding 0x01, rate 1088), BigInt lanes
+// blake2b-256: pure JS RFC 7693 BLAKE2b with digest_length = 32.
+//              NOTE: this is the PARAMETERIZED form — digest length is part of
+//              the parameter block XORed into the IV. It is NOT a truncation
+//              of BLAKE2b-512 and produces a different digest, per the
+//              Hash Function Registry note in ERC-8281.
+
+'use strict';
+
+const { createHash } = require('node:crypto');
+
+// ---------------------------------------------------------------------------
+// Keccak-256
+// ---------------------------------------------------------------------------
+
+const KECCAK_RC = [
+  0x0000000000000001n, 0x0000000000008082n, 0x800000000000808an, 0x8000000080008000n,
+  0x000000000000808bn, 0x0000000080000001n, 0x8000000080008081n, 0x8000000000008009n,
+  0x000000000000008an, 0x0000000000000088n, 0x0000000080008009n, 0x000000008000000an,
+  0x000000008000808bn, 0x800000000000008bn, 0x8000000000008089n, 0x8000000000008003n,
+  0x8000000000008002n, 0x8000000000000080n, 0x000000000000800an, 0x800000008000000an,
+  0x8000000080008081n, 0x8000000000008080n, 0x0000000080000001n, 0x8000000080008008n,
+];
+const KECCAK_ROT = [
+  [0n, 36n, 3n, 41n, 18n],
+  [1n, 44n, 10n, 45n, 2n],
+  [62n, 6n, 43n, 15n, 61n],
+  [28n, 55n, 25n, 21n, 56n],
+  [27n, 20n, 39n, 8n, 14n],
+];
+const M64 = (1n << 64n) - 1n;
+const rol64 = (x, n) => (n === 0n ? x : (((x << n) | (x >> (64n - n))) & M64));
+
+function keccakF(A) {
+  for (let r = 0; r < 24; r++) {
+    const C = [], D = [];
+    for (let x = 0; x < 5; x++) C[x] = A[x][0] ^ A[x][1] ^ A[x][2] ^ A[x][3] ^ A[x][4];
+    for (let x = 0; x < 5; x++) D[x] = C[(x + 4) % 5] ^ rol64(C[(x + 1) % 5], 1n);
+    for (let x = 0; x < 5; x++) for (let y = 0; y < 5; y++) A[x][y] ^= D[x];
+    const B = [[], [], [], [], []];
+    for (let x = 0; x < 5; x++)
+      for (let y = 0; y < 5; y++) B[y][(2 * x + 3 * y) % 5] = rol64(A[x][y], KECCAK_ROT[x][y]);
+    for (let x = 0; x < 5; x++)
+      for (let y = 0; y < 5; y++) A[x][y] = B[x][y] ^ ((~B[(x + 1) % 5][y] & M64) & B[(x + 2) % 5][y]);
+    A[0][0] ^= KECCAK_RC[r];
+  }
+}
+
+function keccak256(bytes) {
+  const rate = 136;
+  const padLen = rate - (bytes.length % rate);
+  const p = new Uint8Array(bytes.length + padLen);
+  p.set(bytes);
+  p[bytes.length] = 0x01;
+  p[p.length - 1] |= 0x80;
+  const A = Array.from({ length: 5 }, () => [0n, 0n, 0n, 0n, 0n]);
+  for (let off = 0; off < p.length; off += rate) {
+    for (let i = 0; i < rate / 8; i++) {
+      let lane = 0n;
+      for (let b = 7; b >= 0; b--) lane = (lane << 8n) | BigInt(p[off + i * 8 + b]);
+      A[i % 5][(i / 5) | 0] ^= lane;
+    }
+    keccakF(A);
+  }
+  const out = new Uint8Array(32);
+  for (let i = 0; i < 4; i++) {
+    let lane = A[i % 5][(i / 5) | 0];
+    for (let b = 0; b < 8; b++) { out[i * 8 + b] = Number(lane & 0xffn); lane >>= 8n; }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// BLAKE2b-256 (parameterized, RFC 7693)
+// ---------------------------------------------------------------------------
+
+const B2B_IV = [
+  0x6a09e667f3bcc908n, 0xbb67ae8584caa73bn, 0x3c6ef372fe94f82bn, 0xa54ff53a5f1d36f1n,
+  0x510e527fade682d1n, 0x9b05688c2b3e6c1fn, 0x1f83d9abfb41bd6bn, 0x5be0cd19137e2179n,
+];
+const B2B_SIGMA = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+  [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+  [11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4],
+  [7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8],
+  [9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13],
+  [2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9],
+  [12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11],
+  [13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10],
+  [6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5],
+  [10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0],
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+  [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+];
+const ror64 = (x, n) => ((x >> n) | (x << (64n - n))) & M64;
+
+function b2bCompress(h, block, t, last) {
+  const m = [];
+  for (let i = 0; i < 16; i++) {
+    let w = 0n;
+    for (let b = 7; b >= 0; b--) w = (w << 8n) | BigInt(block[i * 8 + b]);
+    m[i] = w;
+  }
+  const v = h.concat(B2B_IV.slice());
+  v[12] ^= t & M64;
+  v[13] ^= 0n; // high word of t — inputs here never exceed 2^64 bytes
+  if (last) v[14] ^= M64;
+  const G = (a, b, c, d, x, y) => {
+    v[a] = (v[a] + v[b] + x) & M64; v[d] = ror64(v[d] ^ v[a], 32n);
+    v[c] = (v[c] + v[d]) & M64;     v[b] = ror64(v[b] ^ v[c], 24n);
+    v[a] = (v[a] + v[b] + y) & M64; v[d] = ror64(v[d] ^ v[a], 16n);
+    v[c] = (v[c] + v[d]) & M64;     v[b] = ror64(v[b] ^ v[c], 63n);
+  };
+  for (let r = 0; r < 12; r++) {
+    const s = B2B_SIGMA[r];
+    G(0, 4, 8, 12, m[s[0]], m[s[1]]);
+    G(1, 5, 9, 13, m[s[2]], m[s[3]]);
+    G(2, 6, 10, 14, m[s[4]], m[s[5]]);
+    G(3, 7, 11, 15, m[s[6]], m[s[7]]);
+    G(0, 5, 10, 15, m[s[8]], m[s[9]]);
+    G(1, 6, 11, 12, m[s[10]], m[s[11]]);
+    G(2, 7, 8, 13, m[s[12]], m[s[13]]);
+    G(3, 4, 9, 14, m[s[14]], m[s[15]]);
+  }
+  for (let i = 0; i < 8; i++) h[i] ^= v[i] ^ v[i + 8];
+}
+
+function blake2b256(bytes) {
+  const outLen = 32;
+  const h = B2B_IV.slice();
+  h[0] ^= 0x01010000n ^ BigInt(outLen); // param block: digest_length=32, fanout=1, depth=1
+  let t = 0n;
+  let i = 0;
+  while (bytes.length - i > 128) {
+    t += 128n;
+    b2bCompress(h, bytes.subarray(i, i + 128), t, false);
+    i += 128;
+  }
+  const lastBlock = new Uint8Array(128);
+  lastBlock.set(bytes.subarray(i));
+  t += BigInt(bytes.length - i);
+  b2bCompress(h, lastBlock, t, true);
+  const out = new Uint8Array(outLen);
+  for (let w = 0; w < 4; w++) {
+    let word = h[w];
+    for (let b = 0; b < 8; b++) { out[w * 8 + b] = Number(word & 0xffn); word >>= 8n; }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Registry dispatch + self-test
+// ---------------------------------------------------------------------------
+
+const sha256 = (bytes) => new Uint8Array(createHash('sha256').update(bytes).digest());
+
+const ALLOWED_HASH_FUNCTIONS = Object.freeze(['sha2-256', 'keccak-256', 'blake2b-256']);
+
+/** Compute the digest for a registry hash function. Returns null for
+ *  identifiers not in the allowed set (the caller MUST reject). */
+function computeDigest(hashFunction, bytes) {
+  switch (hashFunction) {
+    case 'sha2-256':    return sha256(bytes);
+    case 'keccak-256':  return keccak256(bytes);
+    case 'blake2b-256': return blake2b256(bytes);
+    default:            return null;
+  }
+}
+
+const toHex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, '0')).join('');
+
+/** Validate all three implementations against known test vectors.
+ *  Throws on any mismatch. Run automatically by the test suite. */
+function selfTest() {
+  const enc = (s) => new TextEncoder().encode(s);
+  const checks = [
+    [sha256(enc('abc')),
+     'ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad',
+     'sha2-256("abc") — FIPS 180-4 vector'],
+    [keccak256(enc('')),
+     'c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470',
+     'keccak-256("") — canonical empty-string vector'],
+    [keccak256(enc('Transfer(address,address,uint256)')),
+     'ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
+     'keccak-256(ERC-20 Transfer signature) — canonical topic-0'],
+    [blake2b256(enc('abc')),
+     'bddd813c634239723171ef3fee98579b94964e3bb1cb3e427262c8c068d52319',
+     'blake2b-256("abc") — parameterized digest_length=32'],
+    [blake2b256(new Uint8Array(0)),
+     '0e5751c026e543b2e8ab2eb06099daa1d1e5df47778f7787faab45cdf12fe3a8',
+     'blake2b-256("") — parameterized digest_length=32'],
+  ];
+  for (const [got, want, name] of checks) {
+    if (toHex(got) !== want) {
+      throw new Error(`hash self-test FAILED: ${name}\n  got  ${toHex(got)}\n  want ${want}`);
+    }
+  }
+  return true;
+}
+
+module.exports = { sha256, keccak256, blake2b256, computeDigest, ALLOWED_HASH_FUNCTIONS, selfTest };

package/src/index.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: CC0-1.0
+// ocp-verify — ERC-8281 Observation Commitment Protocol reference verifier.
+// CommonJS entry point. ESM consumers are served by src/index.mjs.
+
+'use strict';
+
+const { verify, httpProvider } = require('./verify.js');
+const { PROFILES, DEFAULT_PROFILE, resolveProfile } = require('./profiles.js');
+const {
+  sha256, keccak256, blake2b256, computeDigest, ALLOWED_HASH_FUNCTIONS, selfTest,
+} = require('./hash.js');
+const { ENVELOPE_VERSION, validateEnvelope, isValidEip55 } = require('./normalize.js');
+
+// Verified constants (ERC-8281 + Extraction Profiles extension)
+const TOPIC0_RECORDED = PROFILES.recorded.topic0;
+const TOPIC0_ERC8263_ANCHORPROOF = PROFILES['erc8263-anchorproof'].topic0;
+const ERC165_INTERFACE_ID = '0xb5c645bd'; // bytes4(keccak256("record(bytes32)"))
+
+module.exports = {
+  // core
+  verify,
+  httpProvider,
+  // profiles
+  PROFILES,
+  DEFAULT_PROFILE,
+  resolveProfile,
+  // hashes
+  sha256,
+  keccak256,
+  blake2b256,
+  computeDigest,
+  ALLOWED_HASH_FUNCTIONS,
+  selfTest,
+  // normalization
+  ENVELOPE_VERSION,
+  validateEnvelope,
+  isValidEip55,
+  // constants
+  TOPIC0_RECORDED,
+  TOPIC0_ERC8263_ANCHORPROOF,
+  ERC165_INTERFACE_ID,
+};

package/src/index.mjs

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: CC0-1.0
+// ocp-verify — ESM entry point (re-exports the CommonJS core).
+
+import cjs from './index.js';
+
+export const {
+  verify,
+  httpProvider,
+  PROFILES,
+  DEFAULT_PROFILE,
+  resolveProfile,
+  sha256,
+  keccak256,
+  blake2b256,
+  computeDigest,
+  ALLOWED_HASH_FUNCTIONS,
+  selfTest,
+  ENVELOPE_VERSION,
+  validateEnvelope,
+  isValidEip55,
+  TOPIC0_RECORDED,
+  TOPIC0_ERC8263_ANCHORPROOF,
+  ERC165_INTERFACE_ID,
+} = cjs;
+
+export default cjs;

package/src/normalize.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: CC0-1.0
+// ERC-8281 envelope field normalization and validation.
+//
+// Implements the Field Normalization Rules of the Proof Envelope Schema:
+// all comparisons are over decoded values (bytes / integers), never raw
+// strings; addresses MUST pass EIP-55 checksum validation; unknown
+// additional fields MUST be ignored.
+
+'use strict';
+
+const { keccak256, ALLOWED_HASH_FUNCTIONS } = require('./hash.js');
+
+const ENVELOPE_VERSION = 'erc8281/1';
+
+// --- encoding helpers -------------------------------------------------------
+
+const toHex = (bytes) => '0x' + Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+const hexToBytes = (s) => Uint8Array.from(s.slice(2).match(/.{2}/g) ?? [], (h) => parseInt(h, 16));
+const bytesEq = (a, b) => a.length === b.length && a.every((x, i) => x === b[i]);
+
+const isHex32 = (s) => typeof s === 'string' && /^0x[0-9a-f]{64}$/.test(s);
+const isDecimal = (s) => typeof s === 'string' && /^(0|[1-9][0-9]*)$/.test(s);
+const isAddressShape = (s) => typeof s === 'string' && /^0x[0-9a-fA-F]{40}$/.test(s);
+
+/** Decode a 0x-prefixed checksummed address to its 20-byte value. */
+const addressBytes = (address) => hexToBytes('0x' + address.slice(2).toLowerCase());
+
+/** JSON-RPC quantity (0x-hex) or envelope decimal string → BigInt. */
+const quantityToBigInt = (q) => BigInt(q);
+const decimalToBigInt = (d) => BigInt(d);
+
+// --- EIP-55 -----------------------------------------------------------------
+
+/**
+ * EIP-55 checksum validation: each hex letter is uppercase iff the
+ * corresponding nibble of keccak256(lowercase-ascii-address-without-0x)
+ * is >= 8. Addresses that fail validation MUST be rejected.
+ */
+function isValidEip55(address) {
+  if (!isAddressShape(address)) return false;
+  const lower = address.slice(2).toLowerCase();
+  const hash = toHex(keccak256(new TextEncoder().encode(lower))).slice(2);
+  for (let i = 0; i < 40; i++) {
+    const c = address[2 + i];
+    if (!/[a-fA-F]/.test(c)) continue;
+    const upper = parseInt(hash[i], 16) >= 8;
+    if (upper !== (c === c.toUpperCase())) return false;
+  }
+  return true;
+}
+
+// --- envelope validation -----------------------------------------------------
+
+/**
+ * Validate envelope schema and normalization rules.
+ * Returns null when valid, otherwise a rejection reason string.
+ * Unknown additional fields are ignored, per the spec.
+ * (The extraction_profile registry check lives in profiles.js.)
+ */
+function validateEnvelope(env) {
+  if (typeof env !== 'object' || env === null) return 'envelope_not_object';
+  if (env.version !== ENVELOPE_VERSION) return 'version_not_supported'; // exact, case-sensitive
+  if (!isHex32(env.digest)) return 'digest_format_invalid';
+  if (!ALLOWED_HASH_FUNCTIONS.includes(env.hash_function)) return 'hash_function_not_allowed';
+  if (!isDecimal(env.chain_id)) return 'chain_id_format_invalid';
+  if (!isAddressShape(env.contract)) return 'contract_format_invalid';
+  if (!isValidEip55(env.contract)) return 'eip55_checksum_invalid';
+  if (!isHex32(env.tx_hash)) return 'tx_hash_format_invalid';
+  if (!isDecimal(env.block_number)) return 'block_number_format_invalid';
+  if (!isDecimal(env.receipt_log_position)) return 'log_position_format_invalid';
+  if (!isAddressShape(env.committer)) return 'committer_format_invalid';
+  if (!isValidEip55(env.committer)) return 'eip55_checksum_invalid';
+  if (env.block_hash !== undefined && !isHex32(env.block_hash)) return 'block_hash_format_invalid';
+  if (env.extraction_profile !== undefined && typeof env.extraction_profile !== 'string')
+    return 'profile_format_invalid';
+  return null;
+}
+
+module.exports = {
+  ENVELOPE_VERSION,
+  validateEnvelope,
+  isValidEip55,
+  toHex,
+  hexToBytes,
+  bytesEq,
+  addressBytes,
+  quantityToBigInt,
+  decimalToBigInt,
+};

package/src/profiles.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: CC0-1.0
+// ERC-8281 Extraction Profile Registry.
+//
+// A profile is a fixed, spec-registered parameterization of the extraction
+// rule. Profiles are defined only in ERC-8281 or successor ERCs; proof
+// envelopes MUST NOT carry inline extraction parameters. No two registered
+// profiles share a topic-0 value, so any given log can satisfy at most one
+// registered profile.
+//
+// All topic-0 literals below are computationally verified against their
+// signature strings (see test suite, "constants" vector).
+
+'use strict';
+
+const DEFAULT_PROFILE = 'recorded';
+
+const PROFILES = Object.freeze({
+  /**
+   * Default profile — the canonical ERC-8281 event.
+   * An envelope that omits `extraction_profile` MUST be processed under
+   * this profile.
+   */
+  recorded: Object.freeze({
+    id: 'recorded',
+    eventSignature: 'Recorded(bytes32,address)',
+    topic0: '0xdca60c2087041cbb12d9a57628c6cad28ecbd0437e47c7ab6c3aa6e162bf4497',
+    topicCount: 3,
+    digestTopicIndex: 1,
+    committerTopicIndex: 2,
+    // No profile-specific assertions.
+    assertions: Object.freeze([]),
+  }),
+
+  /**
+   * ERC-8263 TruthAnchor profile.
+   * Event: AnchorProof(uint8,bytes32,bytes32,address,bytes)
+   *   topics[1] = agentId      (NOT authenticated by this procedure)
+   *   topics[2] = proofHash    (the committed digest)
+   *   topics[3] = operator     (maps to the envelope `committer` field)
+   * The data field contains ABI-encoded (agentIdScheme, aux) and is ignored.
+   *
+   * Verification under this profile authenticates ONLY the digest and the
+   * committer. It does NOT authenticate agentId, agentIdScheme, or aux, and
+   * establishes no binding between the digest and an agent identity —
+   * agentId resolution is defined by ERC-8263/ERC-8004 and is out of scope.
+   */
+  'erc8263-anchorproof': Object.freeze({
+    id: 'erc8263-anchorproof',
+    eventSignature: 'AnchorProof(uint8,bytes32,bytes32,address,bytes)',
+    topic0: '0x9fe832d83a52f83bd7d54181e4cc7ff8b4e227cc1d3a0144376894b5df6c23cc',
+    topicCount: 4,
+    digestTopicIndex: 2,
+    committerTopicIndex: 3,
+    // Mirrors the ERC-8263 canonical-form guard: proofHash != bytes32(0).
+    assertions: Object.freeze([
+      {
+        name: 'nonzero_digest',
+        reason: 'profile_assertion_failed',
+        check: (ctx) => !ctx.onChainDigest.every((b) => b === 0),
+      },
+    ]),
+  }),
+});
+
+/**
+ * Resolve the profile declared by an envelope.
+ * Returns { profile } on success, { error } on rejection.
+ * Absence of the field and the explicit value "recorded" are equivalent.
+ */
+function resolveProfile(envelope) {
+  const id = envelope.extraction_profile === undefined ? DEFAULT_PROFILE : envelope.extraction_profile;
+  if (typeof id !== 'string') return { error: 'profile_format_invalid' };
+  const profile = Object.prototype.hasOwnProperty.call(PROFILES, id) ? PROFILES[id] : undefined;
+  if (!profile) return { error: 'profile_not_registered' };
+  return { profile };
+}
+
+module.exports = { PROFILES, DEFAULT_PROFILE, resolveProfile };

package/src/verify.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: CC0-1.0
+// ERC-8281 verification invariant, profile-parameterized.
+//
+//   1. Recompute  — hash the supplied observation bytes with the declared hash_function
+//   2. Compare    — H_prime == digest
+//   3. Confirm inclusion — extraction rule under the declared profile:
+//        chain check → receipt fetch (status==1) → log selection by
+//        receipt_log_position (array position, NOT JSON-RPC logIndex) →
+//        address assertion → topic-0 + topic-count assertions →
+//        digest extraction → profile-specific assertions
+//   4. Confirm committer — committer topic == envelope committer
+//   5. Confirm block     — receipt.blockNumber == envelope block_number
+//   plus block_hash, MUST-when-present, against the receipt's blockHash.
+//
+// All failures return { valid: false, reason } — partial verification is
+// never reported as success.
+
+'use strict';
+
+const { computeDigest } = require('./hash.js');
+const { resolveProfile } = require('./profiles.js');
+const {
+  validateEnvelope,
+  hexToBytes,
+  bytesEq,
+  addressBytes,
+  quantityToBigInt,
+  decimalToBigInt,
+} = require('./normalize.js');
+
+/**
+ * Verify a proof envelope against supplied observation bytes.
+ *
+ * @param {object} envelope - ERC-8281 proof envelope (erc8281/1)
+ * @param {Uint8Array} observationBytes - the observation, supplied out-of-band;
+ *   verification is performed over exactly these bytes as provided
+ * @param {object} provider - RPC access:
+ *   { eth_chainId(): Promise<string>,                       // 0x-hex quantity
+ *     eth_getTransactionReceipt(txHash): Promise<object|null> }
+ * @returns {Promise<{valid: true} | {valid: false, reason: string}>}
+ */
+async function verify(envelope, observationBytes, provider) {
+  const reject = (reason) => ({ valid: false, reason });
+
+  // Envelope schema + normalization (version, formats, registry, EIP-55)
+  const schemaError = validateEnvelope(envelope);
+  if (schemaError) return reject(schemaError);
+
+  // Profile resolution (closed registry; absent field == 'recorded')
+  const resolved = resolveProfile(envelope);
+  if (resolved.error) return reject(resolved.error);
+  const P = resolved.profile;
+
+  // Step 1 — Recompute
+  const hPrime = computeDigest(envelope.hash_function, observationBytes);
+  if (hPrime === null) return reject('hash_function_not_allowed');
+
+  // Step 2 — Compare (decoded bytes)
+  const envelopeDigest = hexToBytes(envelope.digest);
+  if (!bytesEq(hPrime, envelopeDigest)) return reject('digest_mismatch');
+
+  // Step 3 — Confirm inclusion (extraction rule under profile P)
+
+  // 3.1 The endpoint MUST serve the declared chain (decoded integers).
+  const endpointChainId = quantityToBigInt(await provider.eth_chainId());
+  if (endpointChainId !== decimalToBigInt(envelope.chain_id)) return reject('chain_id_mismatch');
+
+  // 3.2 Fetch the receipt; MUST exist; MUST have status == 1.
+  const receipt = await provider.eth_getTransactionReceipt(envelope.tx_hash);
+  if (!receipt) return reject('receipt_not_found');
+  if (quantityToBigInt(receipt.status) !== 1n) return reject('receipt_reverted');
+
+  // 3.3 Select the log by ARRAY POSITION within receipt.logs (zero-indexed).
+  // NOT the JSON-RPC logIndex field, which is block-scoped.
+  const position = Number(decimalToBigInt(envelope.receipt_log_position));
+  const log = receipt.logs[position];
+  if (log === undefined) return reject('log_position_out_of_range');
+
+  // 3.4 The selected log's address MUST match `contract` (20-byte compare).
+  if (!bytesEq(addressBytes(log.address), addressBytes(envelope.contract)))
+    return reject('contract_mismatch');
+
+  // 3.5 topics[0] MUST equal the profile's topic-0, and the log MUST contain
+  // exactly the profile's topic count. A log with the right topic-0 but the
+  // wrong count MUST be rejected. The data field is never used.
+  if (!Array.isArray(log.topics) || log.topics.length === 0) return reject('topic_count_invalid');
+  if (!bytesEq(hexToBytes(log.topics[0].toLowerCase()), hexToBytes(P.topic0)))
+    return reject('topic0_mismatch');
+  if (log.topics.length !== P.topicCount) return reject('topic_count_invalid');
+
+  // 3.6 The digest topic contains the digest verbatim (indexed fixed-size type).
+  const onChainDigest = hexToBytes(log.topics[P.digestTopicIndex].toLowerCase());
+  if (!bytesEq(onChainDigest, envelopeDigest)) return reject('onchain_digest_mismatch');
+
+  // 3.7 Profile-specific assertions.
+  const ctx = { onChainDigest, log, envelope };
+  for (const assertion of P.assertions) {
+    if (!assertion.check(ctx)) return reject(assertion.reason);
+  }
+
+  // Step 4 — Confirm committer (address right-aligned in the 32-byte topic).
+  const onChainCommitter = hexToBytes(log.topics[P.committerTopicIndex].toLowerCase()).slice(12);
+  if (!bytesEq(onChainCommitter, addressBytes(envelope.committer))) return reject('committer_mismatch');
+
+  // Step 5 — Confirm block (decoded integers).
+  if (quantityToBigInt(receipt.blockNumber) !== decimalToBigInt(envelope.block_number))
+    return reject('block_number_mismatch');
+
+  // block_hash — MUST-when-present, against the receipt's own blockHash.
+  if (envelope.block_hash !== undefined) {
+    if (!bytesEq(hexToBytes(receipt.blockHash.toLowerCase()), hexToBytes(envelope.block_hash)))
+      return reject('block_hash_mismatch');
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Minimal JSON-RPC HTTP provider (uses global fetch, Node 18+).
+ * For stronger guarantees, supply your own provider that cross-checks
+ * multiple endpoints or verifies receipts against light-client headers.
+ */
+function httpProvider(rpcUrl) {
+  let id = 0;
+  const call = async (method, params) => {
+    const res = await fetch(rpcUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', id: ++id, method, params }),
+    });
+    const body = await res.json();
+    if (body.error) throw new Error(`${method}: ${body.error.message}`);
+    return body.result;
+  };
+  return {
+    eth_chainId: () => call('eth_chainId', []),
+    eth_getTransactionReceipt: (txHash) => call('eth_getTransactionReceipt', [txHash]),
+  };
+}
+
+module.exports = { verify, httpProvider };

package/LICENSE

@@ -1,20 +0,0 @@
-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/reference-cli/README.md

@@ -1,82 +0,0 @@
-# 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.