xoonya 1.0.0

package/proof_sdk.js

@@ -0,0 +1,745 @@
+"use strict";
+
+const crypto = require("crypto");
+
+const MAGIC_HEX = "50524654";
+const VERSION_V1_HEX = "01";
+const VERSION_V2_HEX = "02";
+const TYPE_REGISTER = "01";
+const VALID_TYPES = new Set(["01", "02", "03"]);
+const ZERO_HASH32 = "00".repeat(32);
+const ZERO_CONTEXT12 = "00".repeat(12);
+const PROOF_ENVELOPE_VERSION = "proof-envelope-v1";
+const ECONOMIC_RECEIPT_PROFILE_VERSION = "economic-receipt-profile-v1";
+const REGISTRY_PROFILE_VERSION = "registry-profile-v1";
+const CANONICAL_EVENT_BUNDLE_VERSION = "canonical-event-bundle/v1";
+const CANONICAL_RECEIPT_VERSION = "receipt/v1";
+const PROOF_BUNDLE_VERSION = "proof-bundle/v1";
+const REGISTRY_EVENT_TO_TYPE = {
+  register: "01",
+  update: "02",
+  revoke: "03"
+};
+
+function sha256Hex(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+function hash160Hex(buf) {
+  const sha = crypto.createHash("sha256").update(buf).digest();
+  return crypto.createHash("ripemd160").update(sha).digest("hex");
+}
+
+function assertHex(hex, expectedLen, label) {
+  const normalized = String(hex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(normalized) || normalized.length !== expectedLen) {
+    throw new Error(`${label} must be ${expectedLen / 2} byte hex`);
+  }
+  return normalized;
+}
+
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => canonicalize(item)).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function canonicalJsonSha256Hex(value) {
+  return sha256Hex(Buffer.from(canonicalize(value), "utf8"));
+}
+
+function normalizeString(value) {
+  return String(value == null ? "" : value).trim();
+}
+
+function normalizeStringArray(values, label) {
+  if (values == null) return undefined;
+  if (!Array.isArray(values)) {
+    throw new Error(`${label} must be an array`);
+  }
+  const normalized = values
+    .map((value) => normalizeString(value))
+    .filter(Boolean);
+  return normalized.length ? normalized : undefined;
+}
+
+function normalizePlainObject(value, label) {
+  if (value == null) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value;
+}
+
+function canonicalizeEvent(event) {
+  if (!event || typeof event !== "object" || Array.isArray(event)) {
+    throw new Error("event must be an object");
+  }
+  const normalized = {
+    version: normalizeString(event.version || CANONICAL_EVENT_BUNDLE_VERSION),
+    domain_id: normalizeString(event.domain_id),
+    sequence: normalizeString(event.sequence),
+    actor_id: normalizeString(event.actor_id),
+    adapter_source: normalizeString(event.adapter_source),
+    event_type: normalizeString(event.event_type),
+    event_hash: normalizeString(event.event_hash).toLowerCase()
+  };
+  Object.entries(normalized).forEach(([key, value]) => {
+    if (!value) {
+      throw new Error(`event.${key} required`);
+    }
+  });
+  if (normalized.version !== CANONICAL_EVENT_BUNDLE_VERSION) {
+    throw new Error(`event.version must be ${CANONICAL_EVENT_BUNDLE_VERSION}`);
+  }
+  assertHex(normalized.event_hash, 64, "event.event_hash");
+
+  const timestampNs = normalizeString(event.timestamp_ns);
+  if (timestampNs) {
+    normalized.timestamp_ns = timestampNs;
+  }
+
+  const parentRefs = normalizeStringArray(event.parent_refs, "event.parent_refs");
+  if (parentRefs) {
+    normalized.parent_refs = parentRefs;
+  }
+
+  const capabilityRefs = normalizeStringArray(event.capability_refs, "event.capability_refs");
+  if (capabilityRefs) {
+    normalized.capability_refs = capabilityRefs;
+  }
+
+  const attestationRef = normalizeString(event.attestation_ref);
+  if (attestationRef) {
+    normalized.attestation_ref = attestationRef;
+  }
+
+  const semanticSlots = normalizePlainObject(event.semantic_slots, "event.semantic_slots");
+  if (semanticSlots) {
+    normalized.semantic_slots = semanticSlots;
+  }
+
+  return normalized;
+}
+
+function hashEvent(event) {
+  return canonicalJsonSha256Hex(canonicalizeEvent(event));
+}
+
+function buildCanonicalReceiptSigningMaterial(receipt) {
+  return {
+    agent_identity: receipt.agent_identity,
+    domain_id: receipt.domain_id,
+    event_commitment: receipt.event_commitment,
+    receipt_id: receipt.receipt_id,
+    sequence: receipt.sequence,
+    version: receipt.version
+  };
+}
+
+function emitReceipt(event, options = {}) {
+  const canonicalEvent = canonicalizeEvent(event);
+  const eventCommitment = hashEvent(canonicalEvent);
+  const agentIdentity = normalizeString(options.agent_identity || options.agentIdentity || canonicalEvent.actor_id);
+  if (!agentIdentity) {
+    throw new Error("agent_identity required");
+  }
+
+  const legacyIdentityMaterialHex = options.legacy_identity_material_hex == null
+    ? null
+    : String(options.legacy_identity_material_hex).trim().toLowerCase();
+  let compatibility = null;
+  if (legacyIdentityMaterialHex) {
+    const legacyReceipt = createReceipt(legacyIdentityMaterialHex, Buffer.from(canonicalize(canonicalEvent), "utf8"));
+    compatibility = {
+      legacy_receipt: {
+        agent_id: legacyReceipt.agent_id,
+        opreturn_hex: legacyReceipt.opreturn_hex,
+        payload_hash: legacyReceipt.payload_hash,
+        spec_version: legacyReceipt.spec_version
+      }
+    };
+  }
+
+  const receiptId = sha256Hex(Buffer.from(
+    canonicalize({
+      agent_identity: agentIdentity,
+      domain_id: canonicalEvent.domain_id,
+      event_commitment: eventCommitment,
+      sequence: canonicalEvent.sequence,
+      version: CANONICAL_RECEIPT_VERSION
+    }),
+    "utf8"
+  ));
+
+  const unsignedReceipt = {
+    version: CANONICAL_RECEIPT_VERSION,
+    receipt_id: receiptId,
+    agent_identity: agentIdentity,
+    domain_id: canonicalEvent.domain_id,
+    sequence: canonicalEvent.sequence,
+    event_commitment: eventCommitment,
+    algorithm: normalizeString(options.algorithm || (compatibility ? "legacy-opreturn-v1" : "none"))
+  };
+
+  if (compatibility) {
+    unsignedReceipt.compatibility = compatibility;
+  }
+
+  let signature = options.signature == null ? "" : normalizeString(options.signature);
+  if (!signature && typeof options.signer === "function") {
+    signature = normalizeString(options.signer(buildCanonicalReceiptSigningMaterial(unsignedReceipt), canonicalEvent));
+  }
+  if (!signature && compatibility) {
+    signature = compatibility.legacy_receipt.opreturn_hex;
+  }
+  if (!signature) {
+    throw new Error("signature, signer, or legacy_identity_material_hex required");
+  }
+
+  return {
+    ...unsignedReceipt,
+    signature
+  };
+}
+
+function buildProofBundle(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("input must be an object");
+  }
+  const ceb = canonicalizeEvent(input.ceb || input.event);
+  const receipt = input.receipt || emitReceipt(ceb, input.receipt_options || {});
+  return {
+    version: PROOF_BUNDLE_VERSION,
+    ceb,
+    receipt,
+    anchors: Array.isArray(input.anchors) ? input.anchors : undefined,
+    attestations: Array.isArray(input.attestations) ? input.attestations : undefined,
+    evidence_refs: Array.isArray(input.evidence_refs) ? input.evidence_refs : undefined,
+    batch_refs: Array.isArray(input.batch_refs) ? input.batch_refs : undefined,
+    metadata: input.metadata && typeof input.metadata === "object" && !Array.isArray(input.metadata) ? input.metadata : undefined
+  };
+}
+
+function verifyProofBundle(bundle) {
+  try {
+    if (!bundle || typeof bundle !== "object" || Array.isArray(bundle)) {
+      return { valid: false, reason: "bundle_not_object" };
+    }
+    if (normalizeString(bundle.version) !== PROOF_BUNDLE_VERSION) {
+      return { valid: false, reason: "bad_bundle_version" };
+    }
+    const ceb = canonicalizeEvent(bundle.ceb);
+    const receipt = bundle.receipt;
+    if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+      return { valid: false, reason: "receipt_not_object" };
+    }
+    if (normalizeString(receipt.version) !== CANONICAL_RECEIPT_VERSION) {
+      return { valid: false, reason: "bad_receipt_version" };
+    }
+    if (normalizeString(receipt.domain_id) !== ceb.domain_id) {
+      return { valid: false, reason: "receipt_domain_mismatch" };
+    }
+    if (normalizeString(receipt.sequence) !== ceb.sequence) {
+      return { valid: false, reason: "receipt_sequence_mismatch" };
+    }
+    const expectedCommitment = hashEvent(ceb);
+    if (normalizeString(receipt.event_commitment).toLowerCase() !== expectedCommitment) {
+      return { valid: false, reason: "event_commitment_mismatch" };
+    }
+    const expectedReceiptId = sha256Hex(Buffer.from(
+      canonicalize({
+        agent_identity: normalizeString(receipt.agent_identity),
+        domain_id: ceb.domain_id,
+        event_commitment: expectedCommitment,
+        sequence: ceb.sequence,
+        version: CANONICAL_RECEIPT_VERSION
+      }),
+      "utf8"
+    ));
+    if (normalizeString(receipt.receipt_id).toLowerCase() !== expectedReceiptId) {
+      return { valid: false, reason: "receipt_id_mismatch" };
+    }
+    if (!normalizeString(receipt.agent_identity)) {
+      return { valid: false, reason: "agent_identity_missing" };
+    }
+    if (!normalizeString(receipt.signature)) {
+      return { valid: false, reason: "signature_missing" };
+    }
+
+    const legacyReceipt = receipt.compatibility && receipt.compatibility.legacy_receipt;
+    if (legacyReceipt) {
+      const legacyVerification = verifyReceipt(
+        legacyReceipt.opreturn_hex,
+        Buffer.from(canonicalize(ceb), "utf8")
+      );
+      if (!legacyVerification.valid) {
+        return { valid: false, reason: `legacy_receipt_${legacyVerification.reason}` };
+      }
+      if (normalizeString(legacyReceipt.agent_id).toLowerCase() !== normalizeString(legacyVerification.agent_id).toLowerCase()) {
+        return { valid: false, reason: "legacy_agent_id_mismatch" };
+      }
+      if (normalizeString(receipt.signature).toLowerCase() !== normalizeString(legacyReceipt.opreturn_hex).toLowerCase()) {
+        return { valid: false, reason: "signature_legacy_mismatch" };
+      }
+    }
+
+    return {
+      valid: true,
+      reason: null,
+      version: PROOF_BUNDLE_VERSION,
+      event_commitment: expectedCommitment,
+      receipt_id: expectedReceiptId
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+function parseReceipt(opreturnHex) {
+  const hex = String(opreturnHex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(hex)) {
+    throw new Error("opreturnHex must be hex");
+  }
+  if (hex.length !== 116 && hex.length !== 140) {
+    throw new Error("opreturnHex must be a supported v1 or v2 receipt");
+  }
+  const magic = hex.slice(0, 8);
+  const version = hex.slice(8, 10);
+  const recordType = hex.slice(10, 12);
+  const agentId = hex.slice(12, 52);
+  const payloadHash = hex.slice(52, 116);
+  if (magic !== MAGIC_HEX) {
+    throw new Error("opreturnHex has bad receipt magic");
+  }
+  if (!VALID_TYPES.has(recordType)) {
+    throw new Error("opreturnHex has unsupported record type");
+  }
+  if (version === VERSION_V1_HEX && hex.length === 116) {
+    return {
+      spec_version: "v1",
+      record_type_hex: recordType,
+      agent_id: agentId,
+      payload_hash_sha256: payloadHash,
+      receipt_hash_sha256: sha256Hex(Buffer.from(hex, "hex")),
+      opreturn_hex: hex
+    };
+  }
+  if (version === VERSION_V2_HEX && hex.length === 140) {
+    return {
+      spec_version: "v2",
+      record_type_hex: recordType,
+      agent_id: agentId,
+      payload_hash_sha256: payloadHash,
+      context_hash12: hex.slice(116, 140),
+      receipt_hash_sha256: sha256Hex(Buffer.from(hex, "hex")),
+      opreturn_hex: hex
+    };
+  }
+  throw new Error("opreturnHex/version length mismatch");
+}
+
+function normalizeProofEntry(proof, index) {
+  if (!proof || typeof proof !== "object" || Array.isArray(proof)) {
+    throw new Error(`proofs[${index}] must be an object`);
+  }
+  const normalized = {
+    proof_id: String(proof.proof_id || "").trim(),
+    proof_type: String(proof.proof_type || "").trim(),
+    role: String(proof.role || "").trim(),
+    media_type: String(proof.media_type || "").trim(),
+    proof_hash_sha256: assertHex(proof.proof_hash_sha256, 64, `proofs[${index}].proof_hash_sha256`),
+    locator: String(proof.locator || "").trim()
+  };
+  if (!normalized.proof_id) throw new Error(`proofs[${index}].proof_id required`);
+  if (!normalized.proof_type) throw new Error(`proofs[${index}].proof_type required`);
+  if (!normalized.role) throw new Error(`proofs[${index}].role required`);
+  if (!normalized.media_type) throw new Error(`proofs[${index}].media_type required`);
+  if (!normalized.locator) throw new Error(`proofs[${index}].locator required`);
+  return normalized;
+}
+
+function makeProofEnvelopeBindingMaterial(receiptRef, proofs) {
+  return {
+    envelope_version: PROOF_ENVELOPE_VERSION,
+    payload_hash_sha256: receiptRef.payload_hash_sha256,
+    proofs: proofs.map((proof) => ({
+      locator: proof.locator,
+      media_type: proof.media_type,
+      proof_hash_sha256: proof.proof_hash_sha256,
+      proof_id: proof.proof_id,
+      proof_type: proof.proof_type,
+      role: proof.role
+    })),
+    receipt_hash_sha256: receiptRef.receipt_hash_sha256
+  };
+}
+
+function makeIdentityMaterial(typePrefixHex, rawBytesHex) {
+  const typeHex = assertHex(typePrefixHex, 2, "typePrefixHex");
+  const rawHex = String(rawBytesHex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(rawHex) || rawHex.length === 0) {
+    throw new Error("rawBytesHex must be hex");
+  }
+  return typeHex + rawHex;
+}
+
+function createIdentity(identityMaterialHex) {
+  const materialHex = String(identityMaterialHex || "").trim().toLowerCase();
+  if (!materialHex) {
+    throw new Error("identityMaterialHex required (type_prefix || raw_bytes)");
+  }
+  const material = Buffer.from(materialHex, "hex");
+  const agentId = hash160Hex(material);
+  return { identity_material_hex: materialHex, agent_id: agentId };
+}
+
+function createReceipt(identityMaterialHex, payloadBytes, typeHex = TYPE_REGISTER) {
+  const materialHex = String(identityMaterialHex || "").trim().toLowerCase();
+  if (!materialHex) {
+    throw new Error("identityMaterialHex required (type_prefix || raw_bytes)");
+  }
+  const type = assertHex(typeHex, 2, "typeHex");
+  if (!VALID_TYPES.has(type)) {
+    throw new Error("typeHex must be 01, 02, or 03");
+  }
+  const agentId = hash160Hex(Buffer.from(materialHex, "hex"));
+  const payloadHash = payloadBytes && payloadBytes.length
+    ? sha256Hex(Buffer.from(payloadBytes))
+    : ZERO_HASH32;
+  const opreturnHex = MAGIC_HEX + VERSION_V1_HEX + type + agentId + payloadHash;
+  return {
+    opreturn_hex: opreturnHex,
+    agent_id: agentId,
+    payload_hash: payloadHash,
+    spec_version: "v1"
+  };
+}
+
+function createReceiptV2(identityMaterialHex, payloadBytes, contextHash12Hex, typeHex = TYPE_REGISTER) {
+  const materialHex = String(identityMaterialHex || "").trim().toLowerCase();
+  if (!materialHex) {
+    throw new Error("identityMaterialHex required (type_prefix || raw_bytes)");
+  }
+  const type = assertHex(typeHex, 2, "typeHex");
+  if (!VALID_TYPES.has(type)) {
+    throw new Error("typeHex must be 01, 02, or 03");
+  }
+  const context = assertHex(contextHash12Hex, 24, "contextHash12Hex");
+  if (context === ZERO_CONTEXT12) {
+    throw new Error("contextHash12Hex cannot be all-zero");
+  }
+  const agentId = hash160Hex(Buffer.from(materialHex, "hex"));
+  const payloadHash = payloadBytes && payloadBytes.length
+    ? sha256Hex(Buffer.from(payloadBytes))
+    : ZERO_HASH32;
+  const opreturnHex = MAGIC_HEX + VERSION_V2_HEX + type + agentId + payloadHash + context;
+  return {
+    opreturn_hex: opreturnHex,
+    agent_id: agentId,
+    payload_hash: payloadHash,
+    context_hash12: context,
+    spec_version: "v2"
+  };
+}
+
+function verifyReceipt(opreturnHex, payloadBytes) {
+  const hex = String(opreturnHex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(hex)) {
+    return { valid: false, reason: "non_hex", spec_version: "v1", compliance_hash: null };
+  }
+  if (hex.length !== 116) {
+    return { valid: false, reason: "invalid_length", spec_version: "v1", compliance_hash: null };
+  }
+  const magic = hex.slice(0, 8);
+  const version = hex.slice(8, 10);
+  const type = hex.slice(10, 12);
+  const agentId = hex.slice(12, 52);
+  const payloadHash = hex.slice(52, 116);
+  if (magic !== MAGIC_HEX) return { valid: false, reason: "bad_magic", spec_version: "v1", compliance_hash: null };
+  if (version !== VERSION_V1_HEX) return { valid: false, reason: "bad_version", spec_version: "v1", compliance_hash: null };
+  if (!VALID_TYPES.has(type)) return { valid: false, reason: "bad_type", spec_version: "v1", compliance_hash: null };
+  const expectedPayload = payloadBytes && payloadBytes.length
+    ? sha256Hex(Buffer.from(payloadBytes))
+    : ZERO_HASH32;
+  if (expectedPayload !== payloadHash) {
+    return { valid: false, reason: "payload_mismatch", spec_version: "v1", compliance_hash: null };
+  }
+  return {
+    valid: true,
+    reason: null,
+    spec_version: "v1",
+    compliance_hash: sha256Hex(Buffer.from(hex, "hex")),
+    agent_id: agentId
+  };
+}
+
+function verifyReceiptV2(opreturnHex, payloadBytes) {
+  const hex = String(opreturnHex || "").trim().toLowerCase();
+  if (!/^[a-f0-9]+$/.test(hex)) {
+    return { valid: false, reason: "non_hex", spec_version: "v2", compliance_hash: null };
+  }
+  if (hex.length !== 140) {
+    return { valid: false, reason: "invalid_length", spec_version: "v2", compliance_hash: null };
+  }
+  const magic = hex.slice(0, 8);
+  const version = hex.slice(8, 10);
+  const type = hex.slice(10, 12);
+  const agentId = hex.slice(12, 52);
+  const payloadHash = hex.slice(52, 116);
+  const contextHash12 = hex.slice(116, 140);
+  if (magic !== MAGIC_HEX) return { valid: false, reason: "bad_magic", spec_version: "v2", compliance_hash: null };
+  if (version !== VERSION_V2_HEX) return { valid: false, reason: "bad_version", spec_version: "v2", compliance_hash: null };
+  if (!VALID_TYPES.has(type)) return { valid: false, reason: "bad_type", spec_version: "v2", compliance_hash: null };
+  if (contextHash12 === ZERO_CONTEXT12) return { valid: false, reason: "context_zero_forbidden", spec_version: "v2", compliance_hash: null };
+  const expectedPayload = payloadBytes && payloadBytes.length
+    ? sha256Hex(Buffer.from(payloadBytes))
+    : ZERO_HASH32;
+  if (expectedPayload !== payloadHash) {
+    return { valid: false, reason: "payload_mismatch", spec_version: "v2", compliance_hash: null };
+  }
+  return {
+    valid: true,
+    reason: null,
+    spec_version: "v2",
+    compliance_hash: sha256Hex(Buffer.from(hex, "hex")),
+    agent_id: agentId,
+    context_hash12: contextHash12
+  };
+}
+
+function createProofEnvelopeV1(opreturnHex, proofs, metadata = {}) {
+  const receiptRef = parseReceipt(opreturnHex);
+  const normalizedProofs = Array.isArray(proofs) ? proofs.map(normalizeProofEntry) : [];
+  if (normalizedProofs.length === 0) throw new Error("proofs must be a non-empty array");
+  const proofIds = new Set();
+  normalizedProofs.forEach((proof) => {
+    if (proofIds.has(proof.proof_id)) throw new Error(`duplicate proof_id: ${proof.proof_id}`);
+    proofIds.add(proof.proof_id);
+  });
+  return {
+    envelope_version: PROOF_ENVELOPE_VERSION,
+    receipt_ref: {
+      opreturn_hex: receiptRef.opreturn_hex,
+      spec_version: receiptRef.spec_version,
+      receipt_hash_sha256: receiptRef.receipt_hash_sha256,
+      payload_hash_sha256: receiptRef.payload_hash_sha256
+    },
+    proofs: normalizedProofs,
+    binding_hash_sha256: canonicalJsonSha256Hex(makeProofEnvelopeBindingMaterial(receiptRef, normalizedProofs)),
+    metadata: metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : {}
+  };
+}
+
+function verifyProofEnvelopeV1(envelope) {
+  try {
+    if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+      return { valid: false, reason: "envelope_not_object" };
+    }
+    if (envelope.envelope_version !== PROOF_ENVELOPE_VERSION) {
+      return { valid: false, reason: "bad_envelope_version" };
+    }
+    const receiptRef = parseReceipt(envelope.receipt_ref && envelope.receipt_ref.opreturn_hex);
+    if (String((envelope.receipt_ref && envelope.receipt_ref.spec_version) || "") !== receiptRef.spec_version) {
+      return { valid: false, reason: "receipt_spec_version_mismatch" };
+    }
+    if (String((envelope.receipt_ref && envelope.receipt_ref.receipt_hash_sha256) || "").toLowerCase() !== receiptRef.receipt_hash_sha256) {
+      return { valid: false, reason: "receipt_hash_mismatch" };
+    }
+    if (String((envelope.receipt_ref && envelope.receipt_ref.payload_hash_sha256) || "").toLowerCase() !== receiptRef.payload_hash_sha256) {
+      return { valid: false, reason: "payload_hash_mismatch" };
+    }
+    const proofs = Array.isArray(envelope.proofs) ? envelope.proofs.map(normalizeProofEntry) : [];
+    if (proofs.length === 0) return { valid: false, reason: "proofs_empty" };
+    const proofIds = new Set();
+    for (const proof of proofs) {
+      if (proofIds.has(proof.proof_id)) return { valid: false, reason: "proof_duplicate_id" };
+      proofIds.add(proof.proof_id);
+    }
+    const expectedBindingHash = canonicalJsonSha256Hex(makeProofEnvelopeBindingMaterial(receiptRef, proofs));
+    if (String(envelope.binding_hash_sha256 || "").toLowerCase() !== expectedBindingHash) {
+      return { valid: false, reason: "binding_hash_mismatch" };
+    }
+    return {
+      valid: true,
+      reason: null,
+      envelope_version: PROOF_ENVELOPE_VERSION,
+      binding_hash_sha256: expectedBindingHash
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+function createEconomicReceiptProfileV1(opreturnHex, payload, proofBinding) {
+  const receiptRef = parseReceipt(opreturnHex);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) throw new Error("payload must be an object");
+  const normalizedPayload = {
+    agent_id: assertHex(payload.agent_id, 40, "payload.agent_id"),
+    counterparty_id: String(payload.counterparty_id || "").trim(),
+    event_class: String(payload.event_class || "").trim(),
+    event_id: String(payload.event_id || "").trim(),
+    meter_profile_id: String(payload.meter_profile_id || "").trim(),
+    quantity: String(payload.quantity || "").trim(),
+    unit: String(payload.unit || "").trim(),
+    usage_hash_sha256: assertHex(payload.usage_hash_sha256, 64, "payload.usage_hash_sha256"),
+    window_end_unix_ns: String(payload.window_end_unix_ns || "").trim(),
+    window_start_unix_ns: String(payload.window_start_unix_ns || "").trim()
+  };
+  const start = BigInt(normalizedPayload.window_start_unix_ns);
+  const end = BigInt(normalizedPayload.window_end_unix_ns);
+  if (end < start) throw new Error("window_order_invalid");
+  const payloadHash = canonicalJsonSha256Hex(normalizedPayload);
+  if (payloadHash !== receiptRef.payload_hash_sha256) throw new Error("payload_hash_mismatch");
+  if (!proofBinding || typeof proofBinding !== "object" || Array.isArray(proofBinding)) throw new Error("proofBinding must be an object");
+  const bindingHash = assertHex(proofBinding.binding_hash_sha256, 64, "proofBinding.binding_hash_sha256");
+  const envelopeVersion = String(proofBinding.envelope_version || "").trim();
+  if (envelopeVersion !== PROOF_ENVELOPE_VERSION) throw new Error("bad_proof_binding_envelope_version");
+  return {
+    profile_version: ECONOMIC_RECEIPT_PROFILE_VERSION,
+    receipt_ref: {
+      opreturn_hex: receiptRef.opreturn_hex,
+      spec_version: receiptRef.spec_version,
+      receipt_hash_sha256: receiptRef.receipt_hash_sha256,
+      payload_hash_sha256: receiptRef.payload_hash_sha256
+    },
+    payload: normalizedPayload,
+    payload_hash_sha256: payloadHash,
+    proof_binding: {
+      binding_hash_sha256: bindingHash,
+      envelope_version: envelopeVersion
+    }
+  };
+}
+
+function verifyEconomicReceiptProfileV1(profile) {
+  try {
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+      return { valid: false, reason: "profile_not_object" };
+    }
+    if (profile.profile_version !== ECONOMIC_RECEIPT_PROFILE_VERSION) {
+      return { valid: false, reason: "bad_profile_version" };
+    }
+    const rebuilt = createEconomicReceiptProfileV1(profile.receipt_ref && profile.receipt_ref.opreturn_hex, profile.payload, profile.proof_binding);
+    if (String(profile.payload_hash_sha256 || "").toLowerCase() !== rebuilt.payload_hash_sha256) {
+      return { valid: false, reason: "payload_hash_mismatch" };
+    }
+    return {
+      valid: true,
+      reason: null,
+      profile_version: ECONOMIC_RECEIPT_PROFILE_VERSION,
+      payload_hash_sha256: rebuilt.payload_hash_sha256
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+function createRegistryProfileV1(opreturnHex, eventType, lifecycle = {}, payloadProfileHint = null) {
+  const receiptRef = parseReceipt(opreturnHex);
+  const normalizedEventType = String(eventType || "").trim();
+  if (!REGISTRY_EVENT_TO_TYPE[normalizedEventType]) throw new Error("event_type_invalid");
+  if (receiptRef.record_type_hex !== REGISTRY_EVENT_TO_TYPE[normalizedEventType]) throw new Error("event_type_mapping_invalid");
+  const sequence = String(lifecycle.sequence || "").trim();
+  if (!/^[1-9][0-9]*$/.test(sequence)) throw new Error("sequence_invalid");
+  const normalizedLifecycle = { sequence };
+  const previous = lifecycle.previous_receipt_hash_sha256 == null ? "" : String(lifecycle.previous_receipt_hash_sha256).trim().toLowerCase();
+  if (normalizedEventType === "register") {
+    if (previous) throw new Error("register_previous_forbidden");
+  } else {
+    normalizedLifecycle.previous_receipt_hash_sha256 = assertHex(previous, 64, "lifecycle.previous_receipt_hash_sha256");
+  }
+  const rotationFrom = lifecycle.rotation_from_agent_id == null ? "" : String(lifecycle.rotation_from_agent_id).trim().toLowerCase();
+  if (rotationFrom) {
+    if (normalizedEventType !== "update") throw new Error("rotation_from_only_update");
+    normalizedLifecycle.rotation_from_agent_id = assertHex(rotationFrom, 40, "lifecycle.rotation_from_agent_id");
+  }
+  if (lifecycle.rotation_proof_binding != null) {
+    if (normalizedEventType !== "update") throw new Error("rotation_binding_only_update");
+    const binding = lifecycle.rotation_proof_binding;
+    if (!binding || typeof binding !== "object" || Array.isArray(binding)) throw new Error("rotation_binding_invalid");
+    normalizedLifecycle.rotation_proof_binding = {
+      binding_hash_sha256: assertHex(binding.binding_hash_sha256, 64, "lifecycle.rotation_proof_binding.binding_hash_sha256"),
+      envelope_version: String(binding.envelope_version || "").trim()
+    };
+    if (normalizedLifecycle.rotation_proof_binding.envelope_version !== PROOF_ENVELOPE_VERSION) {
+      throw new Error("bad_rotation_proof_binding_envelope_version");
+    }
+  }
+  return {
+    profile_version: REGISTRY_PROFILE_VERSION,
+    event_type: normalizedEventType,
+    receipt_ref: {
+      opreturn_hex: receiptRef.opreturn_hex,
+      spec_version: receiptRef.spec_version,
+      receipt_hash_sha256: receiptRef.receipt_hash_sha256,
+      agent_id: receiptRef.agent_id,
+      record_type_hex: receiptRef.record_type_hex,
+      payload_hash_sha256: receiptRef.payload_hash_sha256
+    },
+    lifecycle: normalizedLifecycle,
+    payload_profile_hint: payloadProfileHint == null ? undefined : String(payloadProfileHint)
+  };
+}
+
+function verifyRegistryProfileV1(profile) {
+  try {
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+      return { valid: false, reason: "profile_not_object" };
+    }
+    if (profile.profile_version !== REGISTRY_PROFILE_VERSION) {
+      return { valid: false, reason: "bad_profile_version" };
+    }
+    const rebuilt = createRegistryProfileV1(
+      profile.receipt_ref && profile.receipt_ref.opreturn_hex,
+      profile.event_type,
+      profile.lifecycle,
+      profile.payload_profile_hint
+    );
+    if (String((profile.receipt_ref && profile.receipt_ref.receipt_hash_sha256) || "").toLowerCase() !== rebuilt.receipt_ref.receipt_hash_sha256) {
+      return { valid: false, reason: "receipt_hash_mismatch" };
+    }
+    if (String((profile.receipt_ref && profile.receipt_ref.agent_id) || "").toLowerCase() !== rebuilt.receipt_ref.agent_id) {
+      return { valid: false, reason: "agent_id_mismatch" };
+    }
+    if (String((profile.receipt_ref && profile.receipt_ref.record_type_hex) || "").toLowerCase() !== rebuilt.receipt_ref.record_type_hex) {
+      return { valid: false, reason: "record_type_mismatch" };
+    }
+    if (String((profile.receipt_ref && profile.receipt_ref.payload_hash_sha256) || "").toLowerCase() !== rebuilt.receipt_ref.payload_hash_sha256) {
+      return { valid: false, reason: "payload_hash_mismatch" };
+    }
+    return {
+      valid: true,
+      reason: null,
+      profile_version: REGISTRY_PROFILE_VERSION
+    };
+  } catch (error) {
+    return { valid: false, reason: error.message };
+  }
+}
+
+module.exports = {
+  canonicalizeEvent,
+  hashEvent,
+  emitReceipt,
+  buildProofBundle,
+  verifyProofBundle,
+  parseReceipt,
+  makeIdentityMaterial,
+  createIdentity,
+  createReceipt,
+  verifyReceipt,
+  createReceiptV2,
+  verifyReceiptV2,
+  createProofEnvelopeV1,
+  verifyProofEnvelopeV1,
+  createEconomicReceiptProfileV1,
+  verifyEconomicReceiptProfileV1,
+  createRegistryProfileV1,
+  verifyRegistryProfileV1
+};