> ## Documentation Index
> Fetch the complete documentation index at: https://docs.algovoi.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancellation Receipt (lite)

> Content addressed cancellation references for the AlgoVoi substrate: bind a mandate_ref and a cancellation reason into a deterministic cancellation_ref.

[![Keystone Enabled](https://img.shields.io/badge/Keystone-enabled-5cb9f8)](/keystone)

A spend authority that gets cancelled needs a record a verifier can pin: which authority was cancelled, and why. Passed around as plain fields, the cancellation can be re-pointed to a different mandate, or its reason quietly changed, and a stale reference gives no signal.

**Cancellation Receipt (lite)** closes that gap. It content-addresses the cancellation of a spend authority into a deterministic, recomputable `cancellation_ref`. Crucially, the `mandate_ref` it binds is exactly the same `mandate_ref` [Payment Mandate (lite)](/payment-mandate-lite) produces and [Spend Guardrail (lite)](/spend-guardrail-lite) binds, so the cancellation composes onto the open pre-payment decision chain and closes the lifecycle on the authority side. It is **strictly additive over the frozen Layer 1**: no new cryptographic primitive, the same RFC 8785 JCS + SHA-256.

<Info>
  **Apache-2.0 open source.** Install via `pip install algovoi-cancellation-receipt-lite`. Python and TypeScript are byte-for-byte identical on the same input. This is the **lite** tier, content-addressed with no signature; the commercial [Cancellation Receipt](/cancellation-receipt) issues Falcon-1024 post-quantum signed receipts with effective-from timing, provider and jurisdiction, and propagates the cancellation across the settlement and retention chains.
</Info>

## How it works

One reference, computed with RFC 8785 JCS canonicalisation and SHA-256:

```
cancellation_ref = "sha256:" + SHA-256(JCS({ cancellation_reason, mandate_ref }))
```

* **`mandate_ref`** is the spend authority being cancelled, imported by hash.
* **`cancellation_reason`** is a closed enum: `USER_REQUESTED`, `MERCHANT_REQUESTED`, `COMPLIANCE_TERMINATED`, `EXPIRED`.

Both fields are **byte-load-bearing**: change the mandate or the reason and the `cancellation_ref` diverges, so a cancellation cannot be silently re-pointed to another authority and the reason cannot be swapped. A reason outside the enum, or an empty `mandate_ref`, is rejected, not hashed.

## Use

```python theme={null}
from algovoi_cancellation_receipt_lite import cancellation_ref

ref = cancellation_ref(
    mandate_ref="sha256:a4f8cb5ee09b29478ac1cc2f468d66e16d3d25f7a229a31d22ad521e11d04d35",
    cancellation_reason="USER_REQUESTED",
)
```

```ts theme={null}
import { cancellationRef } from '@algovoi/cancellation-receipt-lite';

const ref = cancellationRef(
  'sha256:a4f8cb5ee09b29478ac1cc2f468d66e16d3d25f7a229a31d22ad521e11d04d35',
  'USER_REQUESTED',
);
```

## The lifecycle

Cancellation Receipt (lite) closes the open decision chain on the authority side. The chain is: agent identity ([Agent Passport](/agent-passport-lite) `passport_ref`) + spend authority ([Payment Mandate](/payment-mandate-lite) `mandate_ref`) + policy in force ([Policy Binding](/policy-binding) `policy_bound_ref`) recompute into one pre-payment decision ([Spend Guardrail](/spend-guardrail-lite) `guardrail_ref`). A `cancellation_ref` over the same `mandate_ref` cancels that authority, and recomputes byte-for-byte alongside the decision — proven end to end in the [decision-chain keystone](/spend-decision-chain).

## Lite vs commercial

|             | Lite (this package)                  | [Cancellation Receipt](/cancellation-receipt) (commercial) |
| ----------- | ------------------------------------ | ---------------------------------------------------------- |
| Licence     | Apache-2.0, open                     | Commercial OEM                                             |
| Reference   | content-addressed `cancellation_ref` | the same, **Falcon-1024 signed receipt**                   |
| Carries     | reason + mandate (by hash)           | + effective-from timing, provider, jurisdiction            |
| Propagation | bring your own                       | across settlement + retention chains                       |
| Verifier    | recompute offline                    | maintained verifier                                        |

## Adopters

If you build on `algovoi-cancellation-receipt-lite`, pin `==0.1.0`, anchor a canonical `cancellation_ref` vector hash from `cancellation_receipt_lite_v1`, and keep the `NOTICE`, you qualify for a free **v0 licence key** for `algovoi-mandate-auditor`. The gate is `scripts/check_v0_adoption.py` (dependency + canonical hash anchor + NOTICE + version pin, returning ISSUE\_V0\_KEY). Apply: email [chopmob@gmail.com](mailto:chopmob@gmail.com) with your import-by-hash evidence and a copy of the NOTICE.

## Conformance

The `cancellation_receipt_lite_v1` vector set (10 vectors) is published in the public corpus —
[chopmob-cloud/algovoi-jcs-conformance-vectors](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors) —
with Python and Node runners. It covers the positive references, reason/mandate divergence, invalid-enum and empty-field rejection, and the field-distinctness invariant. `cn-001`, `cn-002` and `cn-003` cancel `mandate_1`, the `mandate_ref` in `spend_guardrail_lite_v1`. Python and TypeScript reproduce every value byte-for-byte.

## Relationship to the open substrate

Cancellation Receipt (lite) sits directly on top of the open [JCS Canonicalisation Substrate](/canonicalisation-substrate) and composes with [Payment Mandate (lite)](/payment-mandate-lite), [Spend Guardrail (lite)](/spend-guardrail-lite), and the [decision-chain keystone](/spend-decision-chain). It uses the same RFC 8785 JCS and SHA-256 primitives, with no additional cryptographic dependencies. Additive over the frozen canonicalisation substrate, sole AlgoVoi authorship.