Aqua Protocol Schema Reference

This section provides the complete technical specification for Aqua Protocol v4. Here you'll find detailed documentation on data structures, revision types, validation rules, and implementation requirements.

What is Aqua Protocol?

Aqua Protocol is a cryptographic protocol for creating verifiable, timestamped chains of revisions with signatures and blockchain anchoring. It enables:

• Tamper-Proof Records: Cryptographic hashes ensure any modification is detectable
• Multi-Party Signatures: Multiple parties can sign revisions for authentication
• Blockchain Timestamping: Anchor revisions to Ethereum, Nostr, or TSA for provable timestamps
• Provenance Tracking: Link revisions to track data flow and transformations
• Template Validation: Enforce data schemas with JSON Schema

Core Data Structure

When you notarize content with Aqua Protocol, the output is a JSON file called an Aqua Tree.

Aqua Tree Structure

1{
2  "revisions": {
3    "0xhash1...": { /* revision object */ },
4    "0xhash2...": { /* revision object */ }
5  },
6  "file_index": {
7    "0xcontenthash1...": "document.pdf",
8    "0xcontenthash2...": "image.png"
9  }
10}

The Aqua Tree contains two primary components:

• Revisions: Map of verification hashes to revision objects
• File Index: Map of content hashes to filenames

See the Aqua Tree documentation for complete details.

Revision Types

Aqua Protocol v4 defines five revision types, each serving a specific purpose:

1. Object Revision

Purpose: Store data content (documents, files, structured data)

Use for:

• Genesis revisions (first revision in a chain)
• Document updates and modifications
• Data snapshots

Learn more: Object Revision Reference

2. Template Revision

Purpose: Define data schemas and validation rules

Use for:

• Enforcing data structure with JSON Schema
• Creating reusable data models
• Validating object revision content

Learn more: Template Revision Reference

3. Signature Revision

Purpose: Add cryptographic signatures for authentication

Use for:

• Proving authorship and authorization
• Multi-party approval workflows
• Non-repudiation

Signature Types:

• RSA: Traditional RSA signatures
• EIP-191: Ethereum-style signatures
• DID:JWS: Decentralized identifier signatures

Learn more: Signature Revision Reference

4. Witness Revision

Purpose: Anchor revisions to blockchain for timestamping

Use for:

• Proving existence at specific time
• Creating tamper-proof timestamps
• Regulatory compliance

Networks Supported:

• Ethereum (mainnet, Sepolia, Holesky)
• Nostr
• TSA (RFC 3161 Timestamping Authorities)

Learn more: Witness Revision Reference

5. Link Revision

Purpose: Connect to other Aqua Trees

Use for:

• Referencing dependencies
• Building composite documents
• Creating provenance graphs

Learn more: Link Revision Reference

Common Revision Fields

All revision types share these common fields:

Additional fields depend on the specific revision type.

Canonicalization Methods

Aqua Protocol v4 supports two methods for computing revision hashes:

Scalar Method

Best for: Simple, straightforward hashing

1{
2  "method": "scalar",
3  // Content hashed as-is
4}

The entire revision is serialized and hashed directly.

Tree Method

Best for: Selective disclosure, large content

1{
2  "method": "tree",
3  "leaves": [
4    "0xleaf1hash...",
5    "0xleaf2hash..."
6  ]
7}

Content is broken into leaves, each hashed separately, then combined in a Merkle tree.

Verification Hash

Each revision has a verification hash computed from its canonical form using SHA3-256:

This hash serves as:

• Unique identifier for the revision
• Key in the revisions map
• Reference in previous_hash fields
• Proof of integrity

Revision Chains

Revisions form chains through previous_hash references:

Genesis Revision

The first revision in a chain:

• Has no previous_hash field (or previous_hash: null)
• Typically an object or template revision
• Establishes the chain's starting point

Subsequent Revisions

All revisions after genesis:

• Must have previous_hash pointing to an existing revision
• Build upon the chain's history
• Can be any revision type

Example: Complete Aqua Tree

Here's a minimal example showing a document with signature and witness:

1{
2  "revisions": {
3    "0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e": {
4      "revision_type": "0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e",
5      "nonce": "0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c",
6      "local_timestamp": 1704067200,
7      "version": "https://aqua-protocol.org/docs/v4/schema",
8      "method": "scalar",
9      "hash_type": "FIPS_202-SHA3-256",
10      "payload": {
11        "payload_type": "application/pdf",
12        "hash": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
13        "hash_type": "FIPS_202-SHA3-256",
14        "descriptor": "Contract Document"
15      }
16    },
17    "0x8e5b2f9c4d3a1e7b6c8f9d0e2a5b3c4d1e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b": {
18      "revision_type": "0x8e5b2f9c4d3a1e7b6c8f9d0e2a5b3c4d1e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
19      "nonce": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
20      "local_timestamp": 1704067260,
21      "version": "https://aqua-protocol.org/docs/v4/schema",
22      "method": "scalar",
23      "hash_type": "FIPS_202-SHA3-256",
24      "previous_hash": "0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e",
25      "signature_type": "eip191",
26      "signature": "0x8c9d0e1f...",
27      "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
28    },
29    "0x1c3e5a7b9d2f4e6a8c0b1d3f5e7a9c2b4d6e8f0a1c3e5a7b9d2f4e6a8c0b1d3f": {
30      "revision_type": "0x1c3e5a7b9d2f4e6a8c0b1d3f5e7a9c2b4d6e8f0a1c3e5a7b9d2f4e6a8c0b1d3f",
31      "nonce": "0x2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e",
32      "local_timestamp": 1704067320,
33      "version": "https://aqua-protocol.org/docs/v4/schema",
34      "method": "scalar",
35      "hash_type": "FIPS_202-SHA3-256",
36      "previous_hash": "0x8e5b2f9c4d3a1e7b6c8f9d0e2a5b3c4d1e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
37      "merkle_root": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
38      "timestamp": 1704067320,
39      "network": "sepolia",
40      "smart_contract_address": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
41      "transaction_hash": "0x3b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9",
42      "sender_account_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
43      "merkle_proof": []
44    }
45  },
46  "file_index": {
47    "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08": "contract.pdf"
48  }
49}

This tree contains:

1. Object Revision (genesis): Document content hash
2. Signature Revision: EIP-191 signature from wallet
3. Witness Revision: Ethereum Sepolia timestamp

Built-in Templates

Aqua Protocol v4 includes several built-in templates:

Each built-in template has a specific hash that serves as its revision_type identifier.

Hash Format

All hashes in Aqua Protocol v4 use consistent formatting:

• Algorithm: SHA3-256 (FIPS 202)
• Format: Hex string prefixed with 0x
• Length: 66 characters (0x + 64 hex digits)
• Example: 0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Timestamp Format

Timestamps use Unix epoch format:

• Type: Integer (seconds since January 1, 1970 UTC)
• Example: 1704067200 = January 1, 2024 00:00:00 UTC

Validation Rules

An Aqua Tree is valid if:

1. All revisions have valid hashes: Computed hash matches the key
2. Previous hashes exist: All previous_hash values reference existing revisions (except genesis)
3. No cycles: Following previous_hash eventually reaches genesis
4. Signatures verify: All signature revisions have valid cryptographic signatures
5. Templates validate: Object revisions with templates match their schema
6. Witnesses exist: Witness revisions reference valid blockchain transactions

Schema Version

All revisions in Aqua Protocol v4 use:

1{
2  "version": "https://aqua-protocol.org/docs/v4/schema"
3}

This identifies the protocol version and schema specification.

Implementation Guidelines

Creating Revisions

1. Generate nonce: Create random 16-byte hex string
2. Set timestamp: Use current Unix timestamp
3. Add content: Include revision-specific fields
4. Set previous_hash: Reference prior revision (if not genesis)
5. Compute hash: Canonicalize and hash the revision
6. Use hash as key: Store in revisions map with hash as key

Verifying Chains

1. Find genesis: Locate revision with no previous_hash
2. Traverse chain: Follow previous_hash references
3. Verify hashes: Recompute and compare each verification hash
4. Check signatures: Validate all cryptographic signatures
5. Verify witnesses: Check blockchain transactions
6. Validate templates: Ensure object data matches schemas

File Storage

Aqua Trees are typically stored as JSON files:

1document.aqua.json
2contract-2024-01-01.aqua.json

The .aqua.json extension identifies Aqua Protocol files.

Use Cases

Aqua Protocol v4 schema supports diverse applications:

• Document Notarization: Legal documents, contracts, agreements
• Supply Chain: Product tracking, provenance verification
• Credentials: Diplomas, certificates, licenses
• Data Integrity: Scientific data, audit logs, compliance records
• Multi-Party Workflows: Approvals, reviews, collaborative editing

Navigation

Explore the detailed specifications for each component:

Additional Resources

• Quick Start Guide - Get started with Aqua Protocol
• Use Cases - Real-world applications
• Aqua SDK - Rust SDK for implementation
• Aqua CLI - Command-line tool

Version History

Current Version: 4.0.0 (Beta)

Aqua Protocol v4 introduces:

• Template system with JSON Schema validation
• Enhanced revision type system
• Improved canonicalization methods
• Better support for complex data structures

For previous versions, see:

• Version 3 Documentation - JavaScript SDK (Stable)
• Version 2 Documentation - Legacy
• Version 1 Documentation - Legacy