algovoi-cancellation-receipt 0.1.0

AlgoVoi mandate cancellation receipt format reference implementation -- four-state termination outcome under urn:x402:canonicalisation:jcs-rfc8785-v1, companion to algovoi-substrate compliance receipts, settlement attestations, and refund receipts

algovoi-cancellation-receipt

AlgoVoi-authored reference implementation for the mandate cancellation receipt format specified in IETF Internet-Draft draft-hopley-x402-cancellation-receipt-00 (Independent Submission, Informational).

Four-state mandate-termination outcome under the JCS RFC 8785 canonicalisation discipline (urn:x402:canonicalisation:jcs-rfc8785-v1). Companion to the AlgoVoi compliance receipt, settlement attestation, and refund receipt I-Ds -- closes the lifecycle gap between recurring execution and mandate termination.

Python and TypeScript reference implementations, byte-for-byte parity, Apache 2.0.

Lifecycle position

admission       settlement       cancellation     refund (if owed)
compliance  --> settlement   --> cancellation --> refund
receipt         attestation      receipt          receipt

All four formats anchor to the same canonicalisation discipline. A verifier walking the audit chain confirms admission -> recurring execution -> termination -> (optional) refund under one byte-deterministic pin.

Packages

Language	Package	Install
Python	algovoi-cancellation-receipt	pip install algovoi-cancellation-receipt
TypeScript	@algovoi/cancellation-receipt	npm install @algovoi/cancellation-receipt

Both depend on algovoi-substrate / @algovoi/substrate for the JCS canonicalisation primitive.

Quick start

Python

from algovoi_cancellation_receipt import build_cancellation_receipt
from algovoi_substrate import sha256_jcs

r = build_cancellation_receipt(
    cancellation_reason="USER_REQUESTED",
    cancellation_timestamp_ms=1716494400000,
    effective_from_ms=1716537600000,
    cancellation_provider_did="did:web:api.algovoi.co.uk",
    mandate_ref="sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
    jurisdiction_flags=["UK", "EU"],
)
print(sha256_jcs(dict(r)))

TypeScript

import { buildCancellationReceipt } from "@algovoi/cancellation-receipt";
import { sha256Jcs } from "@algovoi/substrate";

const r = buildCancellationReceipt({
  cancellation_reason: "USER_REQUESTED",
  cancellation_timestamp_ms: 1716494400000,
  effective_from_ms: 1716537600000,
  cancellation_provider_did: "did:web:api.algovoi.co.uk",
  mandate_ref:
    "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
  jurisdiction_flags: ["UK", "EU"],
});
console.log(sha256Jcs(r));

Receipt format

Seven-field JSON object canonicalised under RFC 8785 (JCS):

Field	Type	Description
canon_version	string	jcs-rfc8785-v1
cancellation_provider_did	string	DID URI of the issuing party
cancellation_reason	string (closed enum)	USER_REQUESTED / MERCHANT_REQUESTED / COMPLIANCE_TERMINATED / EXPIRED
cancellation_timestamp_ms	integer	Epoch ms when cancellation event was recorded (Substrate Rule 2)
effective_from_ms	integer	Epoch ms when cancellation takes legal effect; MUST be >= cancellation_timestamp_ms
jurisdiction_flags	ordered array	ISO-3166-1 codes; primary jurisdiction first
mandate_ref	string	sha256:<hex> reference to mandate setup record

Closed enumeration: cancellation_reason

Value	Initiator	Regulatory significance
USER_REQUESTED	Payer	PSD2 Article 64 right of revocation. UK Consumer Rights Act. May trigger refund obligation under Article 64 if recent debits already settled.
MERCHANT_REQUESTED	Payee	PSD2 Article 72 + contractual terms. Does not trigger consumer-revocation refund-window obligations.
COMPLIANCE_TERMINATED	Operator	Sanctions / KYC / AML / court order. Triggers POCA s.330 / AML 5+6 evidence chain.
EXPIRED	None	Mandate's own time-based end-state. Standard record-keeping only.

The four-value enum is one wider than the three-value enums used in sibling formats (compliance, refund, settlement) because the regulatorily-load-bearing distinctions in mandate termination are genuinely four-state: payer vs payee vs operator vs time.

Two timestamps

cancellation_timestamp_ms and effective_from_ms are recorded separately to support PSD2 Article 64(3)(a) timing: direct-debit revocations are typically effective by end-of-business-day prior to the next scheduled execution, which differs from the recording time. For most cancellations the two timestamps are equal.

effective_from_ms MUST be >= cancellation_timestamp_ms.

Conformance vectors

8 byte-level reference vectors + 7 pair invariants + 3 chain invariants at vectors/cancellation_receipt_v1/.

Companion IETF Internet-Draft

draft-hopley-x402-cancellation-receipt-00 (Independent Submission, Informational). AlgoVoi-authored. Welcomes downstream-adopter contributions per the Appendix C "Known Adopters" pattern.

Related AlgoVoi packages

Package	Purpose
algovoi-substrate / @algovoi/substrate	JCS RFC 8785 canonicalisation, action_ref, compliance receipts
algovoi-refund-receipt / @algovoi/refund-receipt	Refund receipt format
algovoi-settlement-attestation / @algovoi/settlement-attestation	Settlement attestation format
algovoi-cancellation-receipt / @algovoi/cancellation-receipt	This package. Mandate cancellation receipt format

Licence

Apache 2.0.