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

# Delegation Ref

> Open, content-addressed delegation references for the AlgoVoi substrate. Bind a cross-party authority delegation (delegator + delegate + scope + integer-millisecond validity + prev_delegation_ref chain link) into a tamper-evident delegation_ref. Apache-2.0. Python + TypeScript byte-for-byte identical. The open binding the Keystone Orchestrator proves cross-party scope consistency over.

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

A receipt proves an action happened. It does not prove the agent was allowed to take it, and that gap widens the moment authority is delegated from one party to another. When agent A hands a slice of its authority to agent B at another organization, a verifier needs to know two things a label cannot tell it: that B never widened what A granted, and that the hand-off was between the right parties inside the window A allowed.

**Delegation Ref** is the open, tamper-evident binding for each hand-off. It content-addresses a delegation envelope into a deterministic, recomputable `delegation_ref`, so widening the scope, extending the expiry, or swapping the delegate changes the reference and is detectable offline. Delegations chain A to B to C via `prev_delegation_ref`, giving a tamper-evident authority chain. 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-delegation-ref`. Python and TypeScript are byte-for-byte identical on the same input. This is the open **binding** tier, content-addressed with no signature. The cross-party scope-consistency proof (that the executed scope is a subset of the delegated scope at every hop, end to end) is the [Keystone Orchestrator](/keystone) capability, available on request.
</Info>

## How it works

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

```
delegation_ref = "sha256:" + SHA-256(JCS({
    delegate_id, delegator_id, not_after_ms, not_before_ms,
    prev_delegation_ref, scope }))
```

* **`delegator_id` / `delegate_id`** are the two parties: who grants and who receives.
* **`scope`** is the authority delegated.
* **`not_before_ms` / `not_after_ms`** are the validity window, in **integer milliseconds**; `not_after_ms` must exceed `not_before_ms`.
* **`prev_delegation_ref`** is `""` for the root link, or the prior link's `delegation_ref`, which chains the hand-offs A to B to C.

Every field is **byte-load-bearing**: change a party, the scope, a bound, or a chain link and the `delegation_ref` diverges. A malformed validity bound (for example an RFC 3339 string instead of an integer millisecond) is rejected at validation, never minted into a clean-looking reference.

## Use

```python theme={null}
from algovoi_delegation_ref import delegation_ref, tamper_detected, verify_chain

root = {
    "delegator_id": "did:web:org.example",
    "delegate_id":  "did:web:agent-1.example",
    "scope":        "payments:usdc:<=100",
    "not_before_ms": 1716494400000,
    "not_after_ms":  1716498000000,
    "prev_delegation_ref": "",
}
ref = delegation_ref(root)
verify_chain([root, next_link])   # raises on a broken or forged link
```

```ts theme={null}
import { delegationRef, verifyChain } from '@algovoi/delegation-ref';

const ref = delegationRef(root);
verifyChain([root, nextLink]);    // throws on a broken or forged link
```

## Authority across parties

The lite binding proves a delegation was not tampered and that a chain is linked. It deliberately stops there. Proving that nobody *exceeded* what they were granted is the [Keystone Orchestrator](/keystone) capability that `delegation_ref` feeds.

A worked example. A treasury agent **A**, authorized to move payments up to 1000 across GB and US, delegates a slice to a vendor agent **B** at another company for a fixed window. B makes its own decision under that delegation, deliberately narrower (a USDC transfer up to 500, GB only), and executes it. The Orchestrator composes A's authority, the delegation, B's decision and B's execution into one signed verdict: *authority flowed correctly across the A to B boundary and nothing was exceeded*, recomputable offline and rendered as a signed credential a counterparty, auditor, or regulator verifies with no AlgoVoi software. If B instead executes for 2000, the verdict is **BROKEN**: a signed receipt would still look valid, the composed proof does not.

At runtime the relationship runs the other way: the Orchestrator composes and proves the authority is sound, then delegates onward via a fresh `delegation_ref` for the next task, which can be proved again, and so on.

## Lite vs Orchestrator

|           | Delegation Ref (this package)                        | [Keystone Orchestrator](/keystone)                          |
| --------- | ---------------------------------------------------- | ----------------------------------------------------------- |
| Licence   | Apache-2.0, open                                     | Commercial, gated                                           |
| Proves    | the delegation was not tampered; the chain is linked | nobody exceeded their grant, end to end across parties      |
| Mechanism | recompute the content address offline                | cross-party scope consistency over the whole chain          |
| Output    | the `delegation_ref` binding                         | a signed verdict (native + JWS + W3C Verifiable Credential) |
| Access    | `pip` / `npm` install                                | composition proofs on request                               |

## Adopters

If you build on `algovoi-delegation-ref`, pin `==0.1.0`, anchor a canonical `delegation_ref` vector hash from `delegation_ref_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 `delegation_ref_v1` vector set (10 checks) 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 (including the reordered-key case JCS absorbs and a chained second link), the negatives (scope widen, expiry extend, delegate swap and chain-link break which must differ, a malformed validity bound which must reject), and two invariants (key-order invariance, chain integrity). Python and TypeScript reproduce every value byte-for-byte.

## Relationship to the open substrate

Delegation Ref sits directly on top of the open [JCS Canonicalisation Substrate](/canonicalisation-substrate) and is the multi-party extension of 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.