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.