> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sumvin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# The mandate language
> How a Stamped Mandate is written: scopes say what an agent may do, resources say what it is bound to, and parameters and conditions set the limits.
A Stamped Mandate is written in a small language of identifiers. Every part of a mandate that says what is allowed is one of these identifiers, so a mandate reads the same to you on the approval page, to your agent, and to whoever checks it.
The language is about to be open-sourced, so that others can propose and contribute new use cases. These pages are its public description.
## The parts of a mandate
| Part | Written as | Says |
| -------------- | ---------------------------------- | -------------------------------------------------------------------------- |
| **Scopes** | One or more scope identifiers | What the agent may do, each with its own limits. At least one is required. |
| **Resources** | Zero or more resource identifiers | What the mandate is bound to, such as one errand. |
| **Conditions** | Zero or more condition identifiers | Facts that must hold before a purchase goes ahead, such as a price. |
| **Audience** | A party identifier or a hostname | Who the mandate is addressed to. |
| **Expiry** | A time | When the mandate stops standing. |
A mandate grants only what its scopes grant, and only within their parameters, its resources, its conditions and its expiry. Anything not written in it is not permitted.
## Identifiers
Every identifier starts with the scheme `sr` and a region, separated by colons:
```text theme={null}
sr:{region}:{family}:...
```
The region is `us` for everything Sumvin issues today. The third segment names the family, and each family has its own shape:
| Family | Shape | Used for |
| --------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Scope | `sr:us:pint:{domain}:{action}[?{params}]` | What an agent may do. See [Scopes](/concepts/mandates/scopes). |
| Mandate | `sr:us:pint:{id}` | One specific mandate. |
| Errand | `sr:us:errand:{id}` | One specific errand. |
| Person | `sr:us:person:...` | A person's own account. |
| Condition | `sr:us:condition:{type}?{params}` | A fact that must hold. See [Resources and conditions](/concepts/mandates/resources#conditions). |
Scopes and mandates share a family. A scope has five segments, a domain and an action; a mandate identifier has four, ending in an opaque id. The two are never confused: a five-segment identifier is always a scope, never a thing a mandate is bound to.
**On the wire.** The third segment of a scope or mandate identifier is the literal word `pint`. A Stamped Mandate was previously called a PINT, and the identifiers keep that segment. `sr:us:pint:spend:visa_checkout` is a scope; `sr:us:pint:3f9c2a7e5b1d4c8e9a6f0b2d7e4c1a58` is a mandate.
## Scope syntax
```text theme={null}
sr:us:pint:{domain}:{action}?{key}={value}&{key}={value}
```
| Piece | Rules |
| ---------- | ------------------------------------------------------------------------------ |
| `domain` | The area the scope covers, such as `sigil`, `spend`, `errand` or `accounts`. |
| `action` | What may be done there, such as `read`, `manage`, `search` or `visa_checkout`. |
| Parameters | Optional, after a single `?`, as `key=value` pairs joined by `&`. |
The rules a scope must pass before anyone can sign it:
* **Exactly five segments** before any `?`: `sr`, a region, `pint`, a domain and an action. None may be empty.
* **Known name.** The domain and action must be a scope in the [catalogue](/concepts/mandates/scopes). An unknown name is refused, not ignored.
* **Declared parameters only.** Each scope declares the parameters it accepts. An undeclared key is refused.
* **Required parameters present.** Some scopes can't be signed without certain parameters. `spend:visa_checkout` needs both `max` and `currency`.
* **No empty values.** `max=` is refused.
* **Values of the right type.** See the table below.
## Parameter types
| Type | Written as | Example |
| --------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| Amount | A plain decimal number in the display unit of the currency or asset the scope names. No exponent, no spaces, ASCII digits only. | `max=25.50` |
| Integer | ASCII digits. | `time=604800` |
| Timestamp | Unix time in seconds, as an integer. | `from_date=1788220800` |
| Currency | An ISO 4217 code. | `currency=USD` |
| Provider | Lowercase letters, digits and `_`, from the scope's own list. | `provider=meld` |
| Text | Free text, or one of a fixed list where the scope declares one. | `doc_type=passport` |
Amounts are covered in full in [Limits and narrowing](/concepts/mandates/limits#spending-ceilings).
Numbers are read only from ASCII digits. A digit from another script is refused, so a number in a signed mandate reads the same to every person and every program.
## How the parts combine
* **Scopes add up.** A mandate with two scopes grants both, and each scope keeps its own limits. `accounts:read` plus `transactions:read?from_date=…` lets an agent read your accounts, and your transactions only in that range.
* **Parameters narrow a scope.** A scope with no parameters grants its whole action. Each parameter you add can only take something away.
* **Resources and conditions narrow the whole mandate.** A mandate bound to one errand can be used for that errand only. A mandate with conditions can't complete a purchase until all of them hold.
* **One spending limit per mandate.** A spending mandate carries exactly one scope that states a ceiling.
* **What you sign is what is checked.** Scopes, resources and conditions are signed exactly as written: in the same order, with nothing removed, merged or reordered. When your agent drafts a spending mandate, its scopes are sorted and duplicates removed once, before you see the approval page, so the page shows the form you sign.
* **Additive to the service's own rules.** A mandate restricts what an agent may do. It never lifts a check the service already makes, such as requiring you to be verified.
## Older names
Some scopes were renamed. The older names are still accepted in mandates signed before the rename, and they mean exactly the same as the new ones. Use the new names.
| Older name | Current name |
| ----------------------------------------- | -------------------------------------- |
| `sr:us:pint:perpetual:search` | `sr:us:pint:errand:search` |
| `sr:us:pint:identity:kyc_status` | `sr:us:pint:sigil:kyc_status` |
| `sr:us:pint:identity:kyc_read` | `sr:us:pint:sigil:kyc_read` |
| `sr:us:pint:identity:proof_of_personhood` | `sr:us:pint:sigil:proof_of_personhood` |
| `sr:us:pint:identity:age_over_18` | `sr:us:pint:sigil:age_over_18` |
## Next
Every scope family and what it grants.
What a mandate is bound to, and what must hold.
Ceilings, units, expiry, and why a mandate only narrows.
The answer a counterparty gets.