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

# Payment Mandate (lite)

> Content addressed spend authority references for the AlgoVoi substrate: bind payer, cap, period and revocation state into a deterministic mandate_ref.

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

A spend authority passed around as plain fields gives a verifier nothing to pin: who authorised the spend, the per-period cap, the period it applies to, and whether the authority is still live can all drift, and an old reference gives no signal that the terms changed.

**Payment Mandate (lite)** closes that gap. It content-addresses the terms of a spend authority into a deterministic, recomputable `mandate_ref`. It authorises no charge by itself; it is a recomputable handle to the terms, so two parties can pin and compare the same `mandate_ref` byte for byte. Crucially, `mandate_ref` is exactly the **`mandate_ref` that [Spend Guardrail (lite)](/spend-guardrail-lite) binds**, so a spend authority composes straight into the pre-payment decision. 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-payment-mandate-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 [Payment Mandate](/payment-mandate) issues, verifies, and authorises charges against Falcon-1024 post-quantum signed mandates, checking every pull against the per-period cap.
</Info>

## How it works

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

```
mandate_ref = "sha256:" + SHA-256(JCS({ cap, payer, period, revocation_state }))
```

* **`payer`** is who authorised the spend.
* **`cap`** is the per-period spending cap (a string, e.g. `"1000"`).
* **`period`** is the cap period (e.g. `"monthly"`).
* **`revocation_state`** is the authority's current state (e.g. `"active"`, `"revoked"`).

All four fields are **byte-load-bearing**: change the payer, the cap, the period, or the revocation state and the `mandate_ref` diverges. An empty field is rejected, not hashed.

## What a verifier can check

| Verifier holds                        | What they can check                                                                                                                  |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| A `mandate_ref` + the four fields     | That the reference is for exactly this payer, cap, period and state (`mandate_ref` recomputes)                                       |
| The same, with any one field changed  | The change is detected, since each field is byte-load-bearing                                                                        |
| A `mandate_ref` and a `guardrail_ref` | That the pre-payment decision was made against exactly this authority, since `mandate_ref` is the spend authority the decision binds |

No issuer call. No registry lookup. No AlgoVoi service. RFC 8785 JCS, SHA-256, and a JSON parser are the entire dependency.

## Use

```python theme={null}
from algovoi_payment_mandate_lite import mandate_ref

ref = mandate_ref(
    payer="0x00000000000000000000000000000000DEADBEEF",
    cap="1000",
    period="monthly",
    revocation_state="active",
)
# ref is the mandate_ref a Spend Guardrail (lite) decision binds
```

```ts theme={null}
import { mandateRef } from '@algovoi/payment-mandate-lite';

const ref = mandateRef(
  '0x00000000000000000000000000000000DEADBEEF',
  '1000',
  'monthly',
  'active',
);
```

## Conformance

The `payment_mandate_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, field-divergence and empty-field rejection, and the field-distinctness invariant. `mandate_1` and `mandate_2` equal `mandate_1` / `mandate_2` in `spend_guardrail_lite_v1`. Python and TypeScript reproduce every value byte-for-byte.

## The decision chain

Payment Mandate (lite) is the authority input to the open, pinned pre-payment decision chain. [Spend Guardrail (lite)](/spend-guardrail-lite) composes the agent (an [Agent Passport](/agent-passport-lite) `passport_ref`), the spend authority (this `mandate_ref`), and the policy in force (a [Policy Binding](/policy-binding) reference) into one recomputable decision. Because `mandate_ref` is the same authority reference the decision binds, identity, authority, and policy chain into a single offline-verifiable address.

## Lite vs commercial

|                   | Lite (this package)             | [Payment Mandate](/payment-mandate) (commercial)           |
| ----------------- | ------------------------------- | ---------------------------------------------------------- |
| Licence           | Apache-2.0, open                | Commercial OEM                                             |
| Mandate reference | content-addressed `mandate_ref` | the same, **Falcon-1024 signed mandate**                   |
| Enforcement       | bring your own verifier         | authorise-charge engine, per-period cap checks, revocation |
| Verifier          | recompute offline               | maintained verifier                                        |
| Best for          | open integrations, evaluation   | regulated production, enterprise terms                     |

## Adopters

If you build on `algovoi-payment-mandate-lite`, pin `==0.1.0`, anchor a canonical `mandate_ref` vector hash from `payment_mandate_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.

## Relationship to the open substrate

Payment Mandate (lite) sits directly on top of the open [JCS Canonicalisation Substrate](/canonicalisation-substrate) and composes with [Spend Guardrail (lite)](/spend-guardrail-lite), [Agent Passport (lite)](/agent-passport-lite), and [Policy Binding](/policy-binding). It uses the same RFC 8785 JCS and SHA-256 primitives, with no additional cryptographic dependencies.

## Specification

`mandate_ref` is a content-addressed spend-authority reference: the `mandate_ref` consumed by the Spend Guardrail pre-payment decision. It is an instance of the same content-addressed binding construction used across the substrate (a set of fields canonicalised under RFC 8785 JCS and bound by SHA-256). The normative byte-level artifact is the published [`payment_mandate_lite_v1`](https://github.com/chopmob-cloud/algovoi-jcs-conformance-vectors/tree/main/vectors/payment_mandate_lite_v1) conformance set. Additive over the frozen canonicalisation substrate, sole AlgoVoi authorship.