# The Annon protocol

The protocol is the specification and its test vectors. defdone maintains a reference implementation: the NEAR contract, the SDK, the command line and the MCP server. Anyone can implement it or run their own contract.

**Drafts.** [What changed](/changelog) · [Propose a change](https://github.com/defdone/annon/discussions)

## Documents

To write your own implementation, read them in this order and check your output against the test vectors. Each is a page here and plain Markdown at the same address plus `.md`.

| Document | Defines | Version | Markdown |
|---|---|---|---|
| [Settlement on NEAR](/spec/near-settlement) | Identities, terms, the purchase commitment, settlement, refunds, recovery | Draft 3, 11 Nov 2026 | [near-settlement.md](/spec/near-settlement.md) |
| [PAY2 file format](/spec/pay2) | The encrypted file format | PAY2 version 2 | [pay2.md](/spec/pay2.md) |
| [Nonces](/spec/nonce) | The purchase ID and the Base payment nonce | Domains `annon/purchase/v2`, `annon/base-payment/v2` | [nonce.md](/spec/nonce.md) |
| [x402 profile](/spec/x402-annon) | The Annon profile for x402 v2 | Extension version 3 | [x402-annon.md](/spec/x402-annon.md) |
| [Downloads](/spec/download) | Downloads proved by a purchase grant | Follows near-settlement.md | [download.md](/spec/download.md) |

## Status and versions

All documents are drafts. They describe what the contract `v1.annon.defdone.near` and the `0.1.0-alpha.N` packages do today.

### An incompatible change is still possible

During the alpha the contract can be upgraded ([SECURITY.md](/docs/security-policy)), so an incompatible change is still possible. Our versioning rule: an incompatible format change gets a new version number (PAY2 byte 4, `extensions.annon.info.version` or a hash domain string), and an old number never gets a new meaning. Clients refuse versions they do not know.

The documents become stable when the contract is locked after an independent audit. The formats of a locked contract do not change; a new protocol version comes with a new contract.

[Security and the upgrade key](/security)

### Proposing changes

Annon is an open protocol. Start a [discussion](https://github.com/defdone/annon/discussions) with a proposal for a specification or the contract. We review every proposal and either adopt it or work it out there in the open. Security problems go through private reporting ([SECURITY.md](/docs/security-policy)).

## Test vectors

Bytes, texts and hashes every implementation must reproduce, valid and invalid. A spec that cites `vectors/pay2.json` means the file below. The generators that write them are in the [source on GitHub](https://github.com/defdone/annon/tree/master/specs/vectors).

- [base-headers.json](/spec/vectors/base-headers.json): sha256 `35c5f3e30b3747c12d498ffd207ac6af52bbd999c4b1d7d3a10f57febe5e3b55`
- [buyer-proof.json](/spec/vectors/buyer-proof.json): sha256 `97154cc40d77c61090b401b2d48c194ac2108271c7afa91a763102766919b932`
- [ckd-near-mpc.json](/spec/vectors/ckd-near-mpc.json): sha256 `1c5f63198d9a85b907f95f0f0c6844acfa381840cf7d8f10a46f4504b173eb03`
- [near-settlement.json](/spec/vectors/near-settlement.json): sha256 `742fec8dd3f032328e3d79cb6d458189cf9c8a7f742ee90c2834a681a118b8e0`
- [nonce.json](/spec/vectors/nonce.json): sha256 `979765247688aee326ba56b69b94a757e33d5ab2ae16a0e0040cee48040a7435`
- [pay2.json](/spec/vectors/pay2.json): sha256 `b943d72ed08cee469e1483c567897962d8e61641703cec2cf2a7065bb88f80a1`
- [texts.json](/spec/vectors/texts.json): sha256 `7b96333ba8f0ccecb04f3b527f70c64b015054754db8f936a2af2f0df9e797ee`
- [upload.json](/spec/vectors/upload.json): sha256 `bfeaa3c6eeb7cfb298fc741d1d3ffeb31a107fe0a29a9e37ce31f8bf7485e74a`

The NEAR MPC vectors are MIT licensed: [LICENSE-near-mpc.txt](/spec/vectors/LICENSE-near-mpc.txt)

## Implementations

An implementation must follow the specification, reproduce every valid test vector and reject every invalid one. Built your own? Start a [discussion](https://github.com/defdone/annon/discussions) to have it listed here.

- [NEAR contract](https://github.com/defdone/annon/tree/master/contracts/annon): v1.annon.defdone.near, Rust
- [SDK](https://github.com/defdone/annon/tree/master/packages/annon): @defdone/annon, TypeScript
- [Command line and MCP](https://github.com/defdone/annon/tree/master/packages/annon-mcp): annon, @defdone/annon-mcp

Reference, by defdone

---

HTML page: https://annon.dev/spec. Every page for agents: https://annon.dev/llms.txt.
