Protocol Reference
Readable reference for the Aqua Protocol v4 core profile: data model, hashing, templates, signatures, anchors, selective disclosure, and verification
This section is the readable reference for the Aqua Protocol v4 core profile — the protocol subset implemented by aqua-rs-sdk-core. It covers the wire formats, the algorithms, and the rules a conforming producer or verifier follows: revisions and trees, hashing and canonicalization, templates, signatures, anchors and links, selective disclosure, and the verification procedure.
The normative specification lives in the SDK repository at protocol-specification/ (Status: Draft). These pages are the readable reference; on any disagreement between these pages and the specification, the specification wins. The specification itself states: "Where this document and an implementation disagree, that is a defect in one of them and must be reconciled; this document states the intended protocol."
Conformance language
The specification uses the key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL as described in RFC 2119. These pages reproduce that language where they restate normative rules.
Two conformance roles are used throughout:
- a producer creates revisions and trees;
- a verifier checks them.
A statement without an explicit role binds both.
Outside the core profile are: execution of template compute (WASM) sections, timestamping providers, identity verification beyond raw key material, and policy evaluation over stateful trees. At each of these boundaries the governing rule, quoted from the specification, is that "a core-profile verifier MUST fail closed — it never treats a capability it lacks as implicitly satisfied."
Protocol constants
| Constant | Value |
|---|---|
Wire schema version (the only legal version value) | https://aqua-protocol.org/docs/v4/schema |
| Hash algorithms | SHA3-256 (multicodec 0x16), BLAKE3-256 (multicodec 0x1e), both 32-byte digests |
| Nonce | 16 random bytes |
| Selective-disclosure KDF | HKDF with SHA3-256, extract salt "AquaSD" (ASCII) |
| Merkle domain tags | 0x00 leaf, 0x01 internal node, 0x02 value commitment, 0x03 label commitment |
| Template identity hash | Always SHA3-256, regardless of the tree's algorithm |
| Genesis bootstrap type hash | SHA3-256 of the ASCII string aqua:genesis:template_meta |
The catalog of shipped template hashes is normative and appears in the specification's 03 — Templates; the readable version is on the Templates page.
Terminology
| Term | Meaning |
|---|---|
| Tree | A set of revisions keyed by revision hash, together with an informational file index. Structurally a forest of in-trees; colloquially "an Aqua tree". |
| Revision | The atomic protocol object: a JSON object of one of four kinds, content-addressed by its revision hash. |
| Revision link | The string form of a revision hash: 0x + the lowercase hex encoding of the full multihash (70 characters for the registered algorithms). Used both to address a revision and to reference it from other revisions. |
| Kind | Which of the four wire shapes a revision has: object, template, signature, or anchor. |
| Branch | A revision not on the chain's spine. Distinct from the branch kinds (signature, anchor, timestamp) — a classification by naming value, independent of tree position. |
| Tip | A revision that no other revision names as its previous_revision. |
| Content tip | The tip that is an object or template revision, with object preferred — the natural target for extending the tree. |
The Data Model page defines all of these precisely.
Pages in this section
| Page | Scope |
|---|---|
| Data Model | Revisions and trees on the wire: common fields, the four revision kinds, kind discrimination, genesis, structural rules, chains and tips. |
| Hashing and Canonicalization | Content addressing: the Aqua multihash profile, Aqua Pointer Form, and the scalar and tree hashing methods. |
| Templates | Hash-identified types: schema validation, template derivation and narrowing, bounds, and the shipped template catalog. |
| Signatures | The signature revision, the signing pre-image, the four signature suites, and signer identity binding. |
| Anchors and Links | Structural and compositional links, genesis anchors, and cross-tree references. |
| Selective Disclosure | Field-level redaction with salted commitments, selective trees, and the disclosure presets. |
| Verification | The staged verification procedure, verification policies, and the error vocabulary. |
See also
- Data Model — the revision and tree wire formats
- Verification — how a conforming verifier checks a tree
- Core Concepts — the ideas behind the protocol, informally
- aqua-rs-sdk-core — the Rust implementation of this profile
- Quick Start — create and verify your first tree