Aqua Tree

The Aqua Tree is the primary data structure in Aqua Protocol. It serves as the container for all revisions, their relationships, and associated metadata. An Aqua Tree represents a complete, self-contained unit that can be stored, transmitted, and verified independently.

Why "Tree" and Not "Chain"?

The term "tree" is intentional. While revisions form chains through their previous_hash references, the structure supports branching where a single revision can have multiple children. This creates a tree topology rather than a simple linear chain.

1Genesis Revision
2      |
3  Revision A
4    /    \
5Rev B    Rev C  ← Branching creates a tree
6  |        |
7Rev D    Rev E

Structure

An Aqua Tree consists of two primary components:

Core Fields

Complete Structure

1{
2  "revisions": {
3    "0xabc123...": {
4      "revision_type": "0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e",
5      "nonce": "0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c",
6      "local_timestamp": 1704067200,
7      "version": "https://aqua-protocol.org/docs/v4/schema",
8      // ... revision-specific fields
9    },
10    "0xdef456...": {
11      // ... another revision
12    }
13  },
14  "file_index": {
15    "0xe1bcaa92b0ea2f0eb1f046ca4fc877f26726e5bec8b1a5cf25504a29bc4e0f28": "document.pdf",
16    "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08": "contract.txt"
17  }
18}

Revisions Map

The revisions field is an object where:

• Keys: Verification hashes of revisions (hex strings prefixed with 0x)
• Values: Complete revision objects

Each revision is indexed by its verification hash, which is computed from the revision's canonical form. This allows O(1) lookup of any revision by its hash.

Revision Hash as Key

1{
2  "revisions": {
3    "0xabc123...": { /* revision object */ },
4    "0xdef456...": { /* revision object */ }
5  }
6}

The hash serves as:

• Unique identifier for the revision
• Key for efficient lookups
• Reference in previous_hash fields to build the chain

File Index

The file_index maps content hashes to human-readable filenames. This provides context about what content each hash represents.

See the File Index documentation for detailed information.

Complete Example

Here's a minimal Aqua Tree with a genesis object revision and a signature:

1 
2{
3  "revisions": {
4    "0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e": {
5      "revision_type": "0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e",
6      "nonce": "0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c",
7      "local_timestamp": 1704067200,
8      "version": "https://aqua-protocol.org/docs/v4/schema",
9      "method": "scalar",
10      "hash_type": "FIPS_202-SHA3-256",
11      "payload": {
12        "payload_type": "text/plain",
13        "hash": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
14        "hash_type": "FIPS_202-SHA3-256",
15        "descriptor": "Initial Document"
16      }
17    },
18    "0xsig123...": {
19      "revision_type": "0x8e5b2f9c4d3a1e7b6c8f9d0e2a5b3c4d1e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
20      "nonce": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
21      "local_timestamp": 1704067260,
22      "version": "https://aqua-protocol.org/docs/v4/schema",
23      "method": "scalar",
24      "hash_type": "FIPS_202-SHA3-256",
25      "previous_hash": "0x742b74c87ccd7bfc76eaec416027a0bc039b59b9c2d452ea55a5c0e9b0e3f08e",
26      "signature_type": "eip191",
27      "signature": "0x8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c901",
28      "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
29    }
30  },
31  "file_index": {
32    "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08": "document.txt"
33  }
34}
35 

Navigating the Tree

Finding the Genesis Revision

The genesis revision has no previous_hash field or has previous_hash: null. To find it:

1const genesis = Object.values(aquaTree.revisions).find(
2  rev => !rev.previous_hash
3);

Following the Chain

To traverse from genesis to latest:

1function getChain(aquaTree, startHash) {
2  const chain = [];
3  let current = aquaTree.revisions[startHash];
4 
5  while (current) {
6    chain.push(current);
7 
8    // Find child (revision that references this one)
9    const childHash = Object.keys(aquaTree.revisions).find(hash =>
10      aquaTree.revisions[hash].previous_hash === currentHash
11    );
12 
13    current = childHash ? aquaTree.revisions[childHash] : null;
14  }
15 
16  return chain;
17}

Finding All Branches

For trees with branches:

1function findChildren(aquaTree, parentHash) {
2  return Object.entries(aquaTree.revisions)
3    .filter(([_, rev]) => rev.previous_hash === parentHash)
4    .map(([hash, rev]) => ({ hash, revision: rev }));
5}

Storage and Transmission

File Storage

Aqua Trees are typically stored as JSON files with .aqua.json extension:

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

Size Considerations

• Each revision: ~200-500 bytes (depending on type and content)
• Typical Aqua Tree: 1-10 KB for simple documents
• Large trees with many revisions: Up to several MB

Compression

For large trees, consider gzip compression:

1gzip document.aqua.json
2# Results in document.aqua.json.gz

Validation

An Aqua Tree is valid if:

1. All revisions have valid hashes: Each revision's hash matches its computed verification hash
2. Previous hashes reference existing revisions: All previous_hash values point to revisions in the tree (except genesis)
3. No circular references: Following previous_hash links eventually reaches genesis
4. Signatures are valid: All signature revisions have valid cryptographic signatures
5. File index matches: All hashes in file_index correspond to content referenced in revisions

Use Cases

Document Management

Store a document's complete revision history:

• Genesis: Initial document creation
• Updates: Each modification as new object revision
• Signatures: Approvals from stakeholders
• Witnesses: Blockchain timestamps for legal proof

Multi-Document Projects

Use link revisions to connect related Aqua Trees:

• Main project tree links to component trees
• Each component has its own revision history
• Verification cascades through linked trees

Credential Issuance

Issue verifiable credentials:

• Genesis: Credential data (degree, certificate, license)
• Signature: Issuing authority signs
• Witness: Blockchain timestamp for verification
• File index: Maps credential hash to recipient identifier

Performance Considerations

Lookup Performance

• Hash-based lookup: O(1)
• Finding children: O(n) where n is number of revisions
• Full chain traversal: O(m) where m is chain length

Optimization Strategies

For large trees:

1. Index children separately: Maintain a children map for each revision
2. Cache traversals: Store pre-computed chain paths
3. Lazy loading: Load only needed revisions for verification
4. Prune old revisions: Archive historical revisions separately

Related Documentation

• Revision Types - Overview of all revision types
• Object Revision - Genesis and data revisions
• Signature Revision - Cryptographic signatures
• Witness Revision - Blockchain anchoring
• Link Revision - Connecting trees
• File Index - Content hash mapping