@choiceproof/sdk

ChoiceProof's TypeScript SDK creates, signs, publishes, and independently verifies enterprise receipt commitments. The complete receipt remains inside the enterprise environment. Only its signed commitment and minimal public metadata are intended for publication.

The SDK also normalizes activity observed at integrated agent, MCP, wallet, payment, ERP, API, and guardrail boundaries into the common choiceproof.evidenceEvent.v0.1 private receipt format.

Release status

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. Pin the exact version when reproducibility matters. The stable package includes Evidence Envelope v2 source adapters, the public-artifact Gateway client, the Base external-finality collector/verifier, the agent-neutral economic-evidence surface, and the offline independent verifiers described below.

The registry tarball includes the packaged Evidence v2 guide, runnable example, economic-evidence fixed vector, JavaScript entrypoint, and TypeScript declarations. The protected release check installs and imports the packed tarball before publication.

The published public-product surface includes the receipt commitment API exported from @choiceproof/sdk:

• createSignedReceiptCommitment
• createReceiptCommitmentPublisher
• verifyReceiptCommitmentArtifact
• canonicalizeReceiptCommitmentJson
• hashReceiptCommitmentJson
• parsePortableReceiptCommitment
• receiptCommitmentTypedData

The stable 2.2.1 package additionally exposes the evidence-capture surface:

• defineEvidenceCaptureAdapter
• buildEvidenceEvent
• createSignedEvidenceEvent
• createEvidenceCapturePipeline
• verifyEvidenceCaptureArtifact
• agentEvidenceAdapter
• mcpEvidenceAdapter
• walletEvidenceAdapter
• paymentEvidenceAdapter
• erpEvidenceAdapter
• apiEvidenceAdapter
• guardrailEvidenceAdapter

The same published candidate exposes the active Evidence v2 path:

• createGenericJsonEvidenceAdapter
• attestLegacyEvidenceEventV01AsV2
• createEvidenceEnvelopeV2
• buildOrderedEvidenceMerkleTreeV2
• signEvidenceCheckpointV2
• createEvidenceInclusionProofV2
• verifyIndependentEvidenceV2
• createEvidenceGatewayClientV2
• collectBaseExternalFinalityEvidenceV1
• verifyBaseExternalFinalityEvidenceV1

Evidence v2 keeps complete events and envelopes enterprise-local. Only signed checkpoints, ordered inclusion proofs, and signed external-finality statements belong on the public Gateway.

Agent-neutral economic evidence

The stable SDK defines one evidence-only economic lifecycle for any agent, runtime, model, language, or tool protocol. The same API is available through the root SDK barrel and the explicit @choiceproof/sdk/economic-evidence subpath.

The stable SDK exports:

• buildEconomicActionAttempt
• buildEconomicActionTransition
• hashOpaqueEconomicPayload
• hashEconomicEvidenceCoverageManifest
• createEconomicEvidenceRecorder
• verifyEconomicEvidenceChain
• verifyEconomicEvidenceVerificationBundle

Attempt, outcome, reversal, and reconciliation records use deterministic, domain-separated identities. Transition identities commit to the stable source event identity. Economic-effect identifiers are open and namespaced; the core terms are conventions rather than a provider or action allowlist. Complete evidence remains enterprise-held, while optional publication uses only the existing strict signed receipt commitment.

ChoiceProof never invokes, approves, routes, settles, reverses, or limits the external action. The external agent retains its own tools, accounts, credentials, sessions, and execution path.

Older agent, quote, challenge, and settlement helpers may still exist for historical testnet traces. They are not the default ChoiceProof product flow.

The SDK verifies control of the signer address declared in a commitment. It does not certify that the address belongs to a legal enterprise. Integrators that require organization attribution must validate the address against their own trusted signer policy, including rotation and revocation.

Evidence-adapter boundary

The generic JSON, OTLP/HTTP JSON, and Dapr 1.18 adapters require an enterprisePrivacyDomain. Every adapter-derived identity pseudonym and safe projection commitment is domain-separated with that value, so the same input does not produce a cross-enterprise linkable digest.

The legacy EvidenceEvent v0.1 bridge requires the same privacy domain and also binds enterpriseIdHash into its v2 source-instance and evidence commitments. It always creates a fresh v2 signature; it never promotes or reuses a legacy proof.

These SHA-256 values are deterministic enterprise-domain pseudonyms and commitments, not anonymization. Low-entropy identifiers can still be guessed by an attacker with a dictionary. Where the digest itself must resist guessing, derive an opaque value with an enterprise-controlled HMAC or another keyed tokenization service before it reaches the adapter. Evidence events, v2 envelopes, and their extensions remain private enterprise artifacts; do not publish them merely because some fields are hashed.

The machine-readable privacy profile is choiceproof.minimized_enterprise_scoped.v0.2. “Minimized” does not mean hash-only: an adapter may retain explicitly allowlisted timestamps, statuses, drop counts, runtime version, or sampling metadata in its private projection.

The OTLP projection declares projectionVersion: 1 and coverageClaim: "selected_span_metadata_only". The Dapr wrapper declares the same projectionScope. Attribute, event, and link values are validated but are not exported by the safe projection; their absence must never be interpreted as proof of complete telemetry. Parsing is bounded to 250,000 decoded JSON nodes, 16 MiB of total UTF-8 string data, a hard JSON nesting depth, and an AnyValue depth no greater than 32.

transport_authenticated is caller-declared receiver provenance only. Its verified status applies to the receiver's declared transport-authentication scheme; it does not upgrade an event to source_signed, and the adapter does not synthesize a source signature.

Independent Evidence Verifier v2

verifyIndependentEvidenceV2 consumes only explicitly supplied local artifacts and a tenant-scoped trust policy. It verifies envelope signatures, exact signer/source/adapter/verifier authorization tuples, sequence continuity, independent-source corroboration, complete ordered-checkpoint inclusion, and exact trusted-provider finality statements. Hard resource limits make oversized or cyclic input fail closed.

Hostile-value checks assume standard JavaScript intrinsics. If untrusted code can replace global Object, Array, Reflect, or schema-library behavior in the same realm, run verification in a separately initialized Worker or process.

The report keeps integrity, authenticity, continuity, corroboration, and external finality separate. External finality means trusted provider-signed statements only; the core performs no RPC call and does not claim native ledger proof verification. Factual truth is always NOT_DETERMINED_BY_PROTOCOL.

Evidence v2 installed-package quickstart

In an empty directory with Node.js 20 or newer:

npm init -y
npm install --save-exact @choiceproof/sdk@next
npm explore @choiceproof/sdk -- npm run quickstart:evidence-v2

The shipped example captures a generic external-agent tool invocation and result into an enterprise-local EvidenceEvent and EvidenceEnvelopeV2, builds a signed ordered checkpoint and inclusion proof, applies an explicit tenant-scoped trust policy, and passes all five independent-verifier dimensions offline. The default run makes no network request and writes no application file.

A tarball built from this source includes the runnable example, its fixed report, and the self-contained Evidence v2 quickstart guide. The guide also documents the optional, double-gated public Gateway mode. That mode requires exact hosted-v2 readiness and runtime-release preflight before its first POST.

Receipt commitment API

Import receipt commitment builders and verifiers directly from the installed package. Keep complete receipts in enterprise-controlled storage and publish only schema-constrained portable commitments. Offline verification performs no network request unless the caller explicitly supplies an RPC transport.

Production boundary

• Treat capture coverage as integration-relative; an adapter cannot record an action that bypasses its declared boundary.
• Persist the complete evidence artifact in enterprise-controlled storage before publishing its commitment.
• Treat source attestation as provenance metadata, not as automatic proof of truth, completeness, legal identity, or policy correctness.
• Keep the complete receipt and signing key in the enterprise environment.
• Publish only the portable commitment and schema-constrained public metadata.
• Treat HMAC/API credentials as delivery authorization, separate from the enterprise EIP-712 signature.
• Use a fresh commitment nonce and a stable idempotency key for delivery.
• Verify the package tarball integrity, registry signature, and exact version before adoption. No npm provenance attestation is claimed while the source repository is private.
• Base Sepolia chain readback is optional and remains testnet-only in this release candidate.

License

Apache-2.0.