@algovoi/cancellation-receipt

algovoi-cancellation-receipt

AlgoVoi-authored reference implementation for the mandate cancellation receipt format specified in IETF Internet-Draft draft-hopley-x402-cancellation-receipt (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 (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

Conformance to the canonicalisation discipline

This package emits cancellation receipts pinned to canon_version: jcs-rfc8785-v1 on every emitted receipt. The pin is in-band; downstream verifiers (including @algovoi/audit-verifier and any conformant third-party verifier) read the pin to select the canonicalisation rule applied at emission.

The pin is the load-bearing primitive for the Substrate Adopters Registry: adopters anchoring to this discipline pin the same canon_version value in their own publicly-citable artefacts. AlgoVoi maintains the registry as a neutral observer; this package itself is recorded there as the AlgoVoi reference implementation.

Substrate adopters

AlgoVoi is recorded in the Substrate Adopters Registry as the substrate author (v1 and v2). Parties anchoring their own services or specifications to canon_version: jcs-rfc8785-v1 are recorded in the registry via the submission process. AlgoVoi validates submissions against the artefact's canonical bytes and adds qualifying entries.

Licence

Apache 2.0.