Compliance Receipt Format

​

Protocol coverage

• TypeScript: @algovoi/substrate — buildComplianceReceipt() (live, v0.3.0)
• Python: algovoi-substrate — build_compliance_receipt() (live, v0.3.0)

​

Lifecycle position

admission         settlement        refund
compliance   -->  settlement   -->  refund
receipt           attestation       receipt

​

Receipt shape

{
  "canon_version": "jcs-rfc8785-v1",
  "jurisdiction_flags": ["UK", "EU"],
  "payer_ref": "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  "screen_provider_did": "did:web:api.algovoi.co.uk",
  "screen_result": "ALLOW",
  "screen_timestamp_ms": 1716494400000
}

​

The closed enumeration: screen_result

​

payer_ref construction

import hashlib
payer_ref = "sha256:" + hashlib.sha256(f"{network}:{address}".encode()).hexdigest()

​

Why this format

• Under AMLD6 / AMLR Article 56, operators must retain records of every transaction screening decision with enough detail to reconstruct the decision at audit time.
• Under SAMLA 2018 s.20 (UK), the reason for a DENY must not be disclosed to the payer. The receipt records the categorical outcome; the screening detail stays in the operator’s internal records.
• Under PSD2 Article 74 (Directive 2015/2366), transaction monitoring records must be available to competent authorities. A content_hash-chained receipt that a third party can verify without operator runtime access satisfies this without exposing operator internals.

​

Audit chain linkage

content_hash_n = sha256(jcs(receipt_n))
prev_hash_n    = content_hash_(n-1)

​

Conformance vectors

git clone https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors
cd algovoi-jcs-conformance-vectors/vectors/compliance_receipt_v1
python runner_python.py   # expects: PASS 8 vectors + 5 pair + 3 chain
node runner_node.js       # expects: PASS

​

Quick start

​

TypeScript

import { buildComplianceReceipt } from "@algovoi/substrate";
import { sha256Jcs } from "@algovoi/substrate";

const receipt = buildComplianceReceipt({
  payer_ref: "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  screen_result: "ALLOW",
  screen_timestamp_ms: 1716494400000,
  screen_provider_did: "did:web:api.algovoi.co.uk",
  jurisdiction_flags: ["UK", "EU"],
});
console.log(sha256Jcs(receipt));
// content_hash suitable for audit chain linkage

​

Python

from algovoi_substrate import build_compliance_receipt, sha256_jcs

receipt = build_compliance_receipt(
    payer_ref="sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
    screen_result="ALLOW",
    screen_timestamp_ms=1716494400000,
    screen_provider_did="did:web:api.algovoi.co.uk",
    jurisdiction_flags=["UK", "EU"],
)
print(sha256_jcs(receipt))

​

What this is NOT

• Not a risk score. The receipt records a categorical admission decision, not a continuous risk signal. Upstream risk models emit scores; the receipt records the policy outcome of applying those scores.
• Not a KYC certificate. The receipt records that a compliance screen was performed and its outcome. Full KYC documentation is held in the operator’s internal records, not in the canonical receipt.
• Not a payment confirmation. The compliance receipt records admission. Settlement is recorded separately in the settlement attestation.

​

Companion IETF Internet-Draft

​

See also

• Canonicalisation substrate — the JCS discipline
• Settlement attestation — post-admission counterpart
• Refund receipt — post-settlement counterpart
• Payment Evidence Frame — wraps all receipt types into one verifiable artefact
• Conformance vectors — full vector corpus
• Substrate authorship and provenance — citable AlgoVoi authorship record
• Verifiable x402 receipts — the full x402 receipt chain (compliance, settlement, refund)
• No-PII compliance receipts — how the payer reference is hashed so no wallet address appears in the canonical bytes