> ## 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.

# Refund Receipt (lite)

> Content addressed refund references for the AlgoVoi substrate: bind a subject_ref, a result and an amount into a deterministic refund_ref. Apache 2.0.

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

A payment that gets refunded needs a record a verifier can pin: which payment was refunded, for how much, and with what outcome. Passed around as plain fields, a refund can be re-pointed to a different payment, or its amount quietly changed, and a stale reference gives no signal.

**Refund Receipt (lite)** closes that gap. It content-addresses the refund of a prior payment into a deterministic, recomputable `refund_ref`. Crucially, the `subject_ref` it refunds is exactly the `guardrail_ref` [Spend Guardrail (lite)](/spend-guardrail-lite) produces, so the refund composes onto the open pre-payment decision chain and closes the lifecycle after settlement. 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-refund-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 [Refund Receipt](/refund-receipt) issues Falcon-1024 post-quantum signed receipts with provider, timing and jurisdiction, and closes the original payment across the settlement and retention chains.
</Info>

## How it works

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

```
refund_ref = "sha256:" + SHA-256(JCS({ refund_amount, refund_result, subject_ref }))
```

* **`subject_ref`** is the prior payment or decision being refunded, imported by hash.
* **`refund_result`** is a closed enum: `FULL`, `PARTIAL`, `REJECTED`.
* **`refund_amount`** is the amount returned, as a string (`"0"` for a `REJECTED` refund).

All three fields are **byte-load-bearing**: change the subject, the result or the amount and the `refund_ref` diverges, so a refund cannot be silently re-pointed to another payment and neither the outcome nor the amount can be changed without the reference diverging. A result outside the enum, or an empty `subject_ref` or `refund_amount`, is rejected, not hashed.

## Use

```python theme={null}
from algovoi_refund_receipt_lite import refund_ref

ref = refund_ref(
    subject_ref="sha256:2a444c629892f44fde1bd004aba9be01dd6cc7fe251eecdd545b82dca9f0bf97",
    refund_result="FULL",
    refund_amount="1000",
)
```

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

const ref = refundRef(
  'sha256:2a444c629892f44fde1bd004aba9be01dd6cc7fe251eecdd545b82dca9f0bf97',
  'FULL',
  '1000',
);
```

## The lifecycle

Refund Receipt (lite) closes the open decision chain after settlement. 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 `refund_ref` whose `subject_ref` is that exact `guardrail_ref` refunds the authorized payment, and recomputes byte-for-byte alongside the decision, proven end to end in the [decision-chain keystone](/spend-decision-chain). Where [Cancellation Receipt (lite)](/cancellation-receipt-lite) closes the authority before payment, Refund Receipt closes the payment after it.

## Lite vs commercial

|             | Lite (this package)                 | [Refund Receipt](/refund-receipt) (commercial) |
| ----------- | ----------------------------------- | ---------------------------------------------- |
| Licence     | Apache-2.0, open                    | Commercial OEM                                 |
| Reference   | content-addressed `refund_ref`      | the same, **Falcon-1024 signed receipt**       |
| Carries     | result + amount + subject (by hash) | + provider, timing, jurisdiction               |
| Propagation | bring your own                      | across settlement + retention chains           |
| Verifier    | recompute offline                   | maintained verifier                            |

## Adopters

If you build on `algovoi-refund-receipt-lite`, pin `==0.1.0`, anchor a canonical `refund_ref` vector hash from `refund_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 `refund_receipt_lite_v1` vector set (11 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, result/amount/subject divergence, invalid-enum and empty-field rejection, and the field-distinctness invariant. `rf-001`, `rf-002` and `rf-003` refund the ALLOW `guardrail_ref` in `spend_guardrail_lite_v1` / `spend_decision_chain_v1`. Python and TypeScript reproduce every value byte-for-byte.

## Relationship to the open substrate

Refund Receipt (lite) sits directly on top of the open [JCS Canonicalisation Substrate](/canonicalisation-substrate) and composes with [Spend Guardrail (lite)](/spend-guardrail-lite), [Cancellation Receipt (lite)](/cancellation-receipt-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.