@choiceproof/protocol

Versioned ChoiceProof schemas, deterministic canonicalization and hashing helpers, plus the fixed choiceproof.receiptCommitment.v1 vectors.

Install

The stable 2.2.1 release is published on npm's latest channel:

pnpm add @choiceproof/[email protected]

The package is ESM-only and requires Node.js 20 or newer. Receipt commitment integrators should normally start with @choiceproof/sdk; this lower-level package is useful for independent protocol implementations and vector testing.

EvidenceEvent v0.1

choiceproof.evidenceEvent.v0.1 is the common enterprise-local schema for records observed through agent, MCP, wallet, payment, ERP, API, and guardrail adapters.

The package exports the schema, source/action/attestation types, protocol constants, and deterministic domain-separated SHA-256 domains used for event identity, deduplication, source-event references, and source-statement references.

The complete event is private enterprise evidence. It is not a ChoiceProof API request or an on-chain object. When published, the whole event is treated as the enterprise-held receipt and only its current Keccak-256/EIP-712 receipt commitment leaves the enterprise boundary.

Evidence Envelope v2 (2.2.1)

The stable package contains choiceproof.evidenceEnvelope.v2 and the ordered evidence-checkpoint protocol. Both root exports and explicit subpath exports are installed and imported from the packed tarball by the protected release workflow.

EvidenceEvent v0.1 remains unchanged. A v2 envelope binds that private event, one enterprise identity, one hashed claim, and one or more independently signed source or verifier attestations. The attestations bind source implementation, trust domain, epoch, sequence authority, completeness scope, and predecessor linkage. Continuity results describe only the supplied stream ranges; they do not prove universal completeness or the factual truth of the underlying claim.

A v2 checkpoint commits to an ordered list of envelope hashes. Its Merkle leaf hashes bind the envelope hash, leaf index, and leaf count, while signed stream ranges bind the checkpoint to gap-free per-enterprise evidence sequences. External-finality attestations record independently signed observations of service registration or chain confirmation/finalization. They do not turn registration, inclusion, or finality into a factual-truth claim.

The v2 protocol is enterprise-local. The separate hosted Gateway stores only public checkpoints, inclusion proofs, and external-finality statements; it does not accept complete envelopes, provide a managed observability dashboard, or guarantee upstream completeness.

Hashed identifiers inside an event or envelope are deterministic pseudonyms or commitments, not anonymization. An enterprise privacy domain prevents the same adapter input from being directly linked across enterprises, but low-entropy values can still be dictionary-guessed. Keep events, envelopes, and extensions inside the enterprise boundary; a hash alone does not make them safe to publish.

Fixed vectors

The package includes all synthetic fixtures under:

@choiceproof/protocol/test-vectors/receipt-commitment-v1/

They contain no production identifiers, credentials, receipts, or signing keys. The same versioned fixtures are also published by the ChoiceProof web application as a public manifest and bundle.

License

Apache-2.0.