Aqua Protocol v3 Concepts

Understanding the core concepts of Aqua Protocol v3 is essential for effectively using the SDK and building applications. This guide covers the fundamental ideas, terminology, and patterns used throughout the protocol.

AquaTree

The AquaTree is the primary data structure in v3. It represents a complete, self-contained collection of revisions with their relationships and metadata.

Structure

Code

typescript

1interface AquaTree {
2  revisions: Revisions      // All revisions indexed by hash
3  file_index: FileIndex     // Maps file hashes to filenames
4  tree?: RevisionTree       // Tree structure of revisions
5  treeMapping?: TreeMapping // Path mappings for navigation
6}

Components

1. Revisions

A flat map of all revisions, keyed by their verification hash:

Code

typescript

1{
2  "0xabc123...": {
3    previous_verification_hash: "0xdef456...",
4    local_timestamp: "2024-01-01T12:00:00",
5    revision_type: "file",
6    // ... other fields
7  },
8  "0xdef456...": {
9    // ... another revision
10  }
11}

2. File Index

Maps file content hashes to filenames for reference:

Code

typescript

1{
2  "0xfile_hash_1": "document.pdf",
3  "0xfile_hash_2": "image.png"
4}

3. Tree Structure (Optional)

Hierarchical representation showing parent-child relationships:

Code

typescript

1{
2  hash: "0xabc123...",  // Root revision
3  children: [
4    {
5      hash: "0xdef456...",
6      children: [...]
7    }
8  ]
9}

4. Tree Mapping (Optional)

Path information for each revision:

Code

typescript

1{
2  paths: {
3    "0xabc123": ["0xroot", "0xabc123"],
4    "0xdef456": ["0xroot", "0xabc123", "0xdef456"]
5  },
6  latestHash: "0xdef456..."  // Most recent revision
7}

Revisions

A Revision is a single entry in the AquaTree representing an operation or state change.

Common Fields

All revisions share these base fields:

Field	Type	Description
`previous_verification_hash`	string	Hash linking to previous revision (empty string for genesis)
`local_timestamp`	string	ISO 8601 timestamp when revision was created
`revision_type`	string	One of: `"file"`, `"form"`, `"signature"`, `"witness"`, `"link"`
`version`	string	Protocol version with method: `https://aqua-protocol.org/docs/v3/schema_2 \| SHA256 \| Method: scalar/tree`

Genesis Revision

The genesis revision is the first revision in a chain:

previous_verification_hash is an empty string ""
Typically a file or form revision
Establishes the initial state

Verification Hash

Each revision has a unique verification hash computed from its canonical form:

Code

typescript

1hash = SHA256(canonicalized_revision_data)

This hash serves as:

Unique identifier for the revision
Key in the revisions map
Reference in previous_verification_hash fields

Revision Types

1. File Revision

Stores file metadata and optionally content.

Purpose: Document file presence and content integrity

Fields:

file_hash: SHA256 hash of file content
file_nonce: Random nonce for uniqueness
content: Optional file content (text or binary)
leaves: Array of hashes (tree mode only)

Example:

Code

json

1{
2  "previous_verification_hash": "",
3  "local_timestamp": "2024-01-01T12:00:00",
4  "revision_type": "file",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "file_hash": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
7  "file_nonce": "0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c"
8}

2. Form Revision

Stores structured key-value data.

Purpose: Capture form submissions, structured data, or metadata

Fields:

file_hash: Hash of form data
file_nonce: Random nonce
content: Form data as key-value object
leaves: Array of hashes (tree mode only)

Example:

Code

json

1{
2  "previous_verification_hash": "",
3  "local_timestamp": "2024-01-01T12:00:00",
4  "revision_type": "form",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: tree",
6  "file_hash": "0xabc123...",
7  "file_nonce": "0x123abc...",
8  "content": {
9    "name": "John Doe",
10    "email": "john@example.com",
11    "status": "approved"
12  },
13  "leaves": ["0x...", "0x...", "0x..."]
14}

3. Signature Revision

Adds cryptographic signature to prove authenticity.

Purpose: Authenticate revisions and establish authorship

Fields:

signature: Signature value (format depends on type)
signature_type: One of "cli", "metamask", "did", "p12", "inline"
signature_wallet_address: Ethereum address (for cli/metamask)
signature_public_key: Public key (for p12)

Example (MetaMask):

Code

json

1{
2  "previous_verification_hash": "0xabc123...",
3  "local_timestamp": "2024-01-01T12:01:00",
4  "revision_type": "signature",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "signature_type": "metamask",
7  "signature": "0x8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f...",
8  "signature_wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
9}

Example (DID):

Code

json

1{
2  "previous_verification_hash": "0xabc123...",
3  "local_timestamp": "2024-01-01T12:01:00",
4  "revision_type": "signature",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "signature_type": "did",
7  "signature": {
8    "payload": "eyJhbGciOi...",
9    "signatures": [{
10      "protected": "eyJhbGci...",
11      "signature": "..."
12    }]
13  }
14}

4. Witness Revision

Anchors revision to external timestamping service.

Purpose: Prove existence at specific time via blockchain or TSA

Fields:

witness_merkle_root: Root hash of Merkle tree
witness_timestamp: Unix timestamp from witness service
witness_network: Network used ("mainnet", "sepolia", "holesky", "tsa", "nostr")
witness_smart_contract_address: Contract address (Ethereum)
witness_transaction_hash: Transaction hash
witness_sender_account_address: Account that witnessed
witness_merkle_proof: Merkle proof array

Example (Ethereum):

Code

json

1{
2  "previous_verification_hash": "0xabc123...",
3  "local_timestamp": "2024-01-01T12:02:00",
4  "revision_type": "witness",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "witness_merkle_root": "0xdef456...",
7  "witness_timestamp": 1704110520,
8  "witness_network": "sepolia",
9  "witness_smart_contract_address": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
10  "witness_transaction_hash": "0x9f86d081...",
11  "witness_sender_account_address": "0x742d35Cc...",
12  "witness_merkle_proof": []
13}

5. Link Revision

Connects to other AquaTree chains.

Purpose: Establish relationships between separate chains

Fields:

link_type: Type of link relationship (application-specific)
link_verification_hashes: Array of hashes from other chains
link_file_hashes: Array of corresponding file hashes

Example:

Code

json

1{
2  "previous_verification_hash": "0xabc123...",
3  "local_timestamp": "2024-01-01T12:03:00",
4  "revision_type": "link",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "link_type": "dependency",
7  "link_verification_hashes": [
8    "0x111...",
9    "0x222...",
10    "0x333..."
11  ],
12  "link_file_hashes": [
13    "0xaaa...",
14    "0xbbb...",
15    "0xccc..."
16  ]
17}

Methods: Scalar vs Tree

V3 supports two canonicalization methods, specified in the version string.

Scalar Method

Format: Method: scalar

How it works:

Revision is serialized as-is
Hash computed directly from canonical JSON
Simple, straightforward

When to use:

Small revisions
Simple file/form data
Quick operations

Example:

Code

typescript

1version: "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar"
2// No leaves field

Tree Method

Format: Method: tree

How it works:

Content broken into key-value leaves
Each leaf hashed individually
Merkle tree constructed from leaves
Root becomes the verification hash

When to use:

Large files or forms
Selective disclosure needed
Proof of specific fields

Example:

Code

typescript

1version: "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: tree"
2leaves: [
3  "0xhash_of_key_value_1",
4  "0xhash_of_key_value_2",
5  "0xhash_of_key_value_3"
6]

Leaf Generation:

Code

typescript

1// For form data: { "name": "John", "email": "john@example.com" }
2leaves = [
3  SHA256("name:John"),
4  SHA256("email:john@example.com")
5]

Chains and Trees

Linear Chain

Simple sequence of revisions:

Genesis � Signature � Witness � Update � Signature � Witness

Each revision references the previous one.

Branching Tree

Multiple paths from a common ancestor:

            Genesis
               �
          Signature
             /  \
        Branch A  Branch B
           �        �
        Update 1  Update 2

V3 supports branching, allowing parallel development paths.

Path Mapping

The treeMapping provides paths to each revision:

Code

typescript

1{
2  paths: {
3    "genesis_hash": ["genesis_hash"],
4    "sig_hash": ["genesis_hash", "sig_hash"],
5    "branch_a_hash": ["genesis_hash", "sig_hash", "branch_a_hash"],
6    "branch_b_hash": ["genesis_hash", "sig_hash", "branch_b_hash"]
7  },
8  latestHash: "branch_a_hash"  // Longest path
9}

File Object

Input format for creating revisions:

Code

typescript

1interface FileObject {
2  fileName: string           // Display name
3  fileContent: string |      // Text content
4                AquaTree |   // Linked tree
5                Uint8Array | // Binary data
6                Record<string, string> | // Form data
7                object       // Structured data
8  path: string              // File path
9  fileSize?: number         // Size in bytes
10}

Content Types

Text: Plain text, HTML, JSON

Code

typescript

1{
2  fileName: "doc.txt",
3  fileContent: "Hello World",
4  path: "/docs/doc.txt"
5}

Binary: Images, PDFs, any binary file

Code

typescript

1{
2  fileName: "image.png",
3  fileContent: new Uint8Array([...]),
4  path: "/images/image.png"
5}

Form: Key-value structured data

Code

typescript

1{
2  fileName: "form.json",
3  fileContent: {
4    "field1": "value1",
5    "field2": "value2"
6  },
7  path: "/forms/form.json"
8}

Link: Reference to another AquaTree

Code

typescript

1{
2  fileName: "linked.json",
3  fileContent: anotherAquaTree,
4  path: "/links/linked.json"
5}

Verification Graph

Result of verification includes a graph structure:

Code

typescript

1interface VerificationGraphData {
2  hash: string
3  previous_verification_hash: string
4  timestamp: string
5  isValidationSuccessful: boolean
6  revisionType: RevisionType
7  info: RevisionGraphInfo  // Type-specific details
8  verificationGraphData: VerificationGraphData[]      // Children
9  linkVerificationGraphData: VerificationGraphData[]  // Links
10}

Traversing the Graph

Code

typescript

1function printVerification(graph: VerificationGraphData, depth = 0) {
2  const indent = "  ".repeat(depth);
3  const status = graph.isValidationSuccessful ? "" : "";
4  console.log(`${indent}${status} ${graph.revisionType} (${graph.hash.slice(0, 10)}...)`);
5 
6  // Traverse children
7  graph.verificationGraphData.forEach(child => {
8    printVerification(child, depth + 1);
9  });
10 
11  // Traverse links
12  graph.linkVerificationGraphData.forEach(link => {
13    console.log(`${indent}  � Linked:`);
14    printVerification(link, depth + 2);
15  });
16}

Credentials

Configuration for signing and witnessing:

Code

typescript

1interface CredentialsData {
2  mnemonic: string             // BIP39 mnemonic for CLI signing
3  nostr_sk: string             // Nostr secret key
4  did_key: string              // DID key for DID signing
5  alchemy_key: string          // Alchemy API key for verification
6  witness_eth_network: string  // "mainnet", "sepolia", "holesky"
7  witness_method: string       // "cli" or "metamask"
8  p12_password?: string        // P12 certificate password
9  p12_content?: string         // P12 certificate content
10}

Logging

V3 uses typed logging throughout:

Code

typescript

1enum LogType {
2  SUCCESS = "success",
3  INFO = "info",
4  ERROR = "error",
5  WARNING = "warning",
6  HINT = "hint",
7  DEBUGDATA = "debug_data",
8  // ... revision types with emojis
9  FILE = "file",      // =�
10  LINK = "link",      // =
11  SIGNATURE = "signature",  // =
12  WITNESS = "witness",      // =@
13  FORM = "form"            // =�
14}

Each operation returns logs for debugging and user feedback.

Best Practices

1. Genesis Patterns

Single File:

File Genesis � Sign � Witness

Form Data:

Form Genesis � Sign � Witness

2. Update Patterns

Content Update:

... � New File Revision � Sign � Witness

Multi-Party:

... � Sign (Party 1) � Sign (Party 2) � Witness

3. Linking Patterns

Dependencies:

Main Document � Link (to dependencies) � Sign � Witness

Aggregation:

Component 1 
Component 2 � Aggregation Link � Sign � Witness
Component 3

4. Verification Patterns

Full Chain:

Code

typescript

1const result = await aquafier.verifyRevisionChain(aquaTree);

Specific Revision:

Code

typescript

1const revision = aquaTree.revisions[specificHash];
2// Manually verify hash computation

5. Storage Patterns

Database: Store serialized AquaTree JSON

Code

typescript

1const json = JSON.stringify(aquaTree);
2db.save(documentId, json);

File System: Save as .aqua.json file

Code

typescript

1fs.writeFileSync('document.aqua.json', JSON.stringify(aquaTree, null, 2));

Common Patterns

Document Lifecycle

1. Create � File Genesis
2. Review � Sign (Reviewer)
3. Approve � Sign (Approver)
4. Timestamp � Witness (Ethereum)
5. Archive � Store AquaTree
6. Verify � Check entire chain

Multi-Document Project

1. Create each document � Individual AquaTrees
2. Link together � Link Revision in main tree
3. Sign project � Sign main tree
4. Witness � Witness main tree
5. All documents timestamped through link

Aqua Protocol v3 Concepts

AquaTree

The AquaTree is the primary data structure in v3. It represents a complete, self-contained collection of revisions with their relationships and metadata.

Structure

Code

typescript

1interface AquaTree {
2  revisions: Revisions      // All revisions indexed by hash
3  file_index: FileIndex     // Maps file hashes to filenames
4  tree?: RevisionTree       // Tree structure of revisions
5  treeMapping?: TreeMapping // Path mappings for navigation
6}

Components

1. Revisions

A flat map of all revisions, keyed by their verification hash:

Code

typescript

1{
2  "0xabc123...": {
3    previous_verification_hash: "0xdef456...",
4    local_timestamp: "2024-01-01T12:00:00",
5    revision_type: "file",
6    // ... other fields
7  },
8  "0xdef456...": {
9    // ... another revision
10  }
11}

2. File Index

Maps file content hashes to filenames for reference:

Code

typescript

1{
2  "0xfile_hash_1": "document.pdf",
3  "0xfile_hash_2": "image.png"
4}

3. Tree Structure (Optional)

Hierarchical representation showing parent-child relationships:

Code

typescript

1{
2  hash: "0xabc123...",  // Root revision
3  children: [
4    {
5      hash: "0xdef456...",
6      children: [...]
7    }
8  ]
9}

4. Tree Mapping (Optional)

Path information for each revision:

Code

typescript

1{
2  paths: {
3    "0xabc123": ["0xroot", "0xabc123"],
4    "0xdef456": ["0xroot", "0xabc123", "0xdef456"]
5  },
6  latestHash: "0xdef456..."  // Most recent revision
7}

Revisions

A Revision is a single entry in the AquaTree representing an operation or state change.

Common Fields

All revisions share these base fields:

Field	Type	Description
`previous_verification_hash`	string	Hash linking to previous revision (empty string for genesis)
`local_timestamp`	string	ISO 8601 timestamp when revision was created
`revision_type`	string	One of: `"file"`, `"form"`, `"signature"`, `"witness"`, `"link"`
`version`	string	Protocol version with method: `https://aqua-protocol.org/docs/v3/schema_2 \| SHA256 \| Method: scalar/tree`

Genesis Revision

The genesis revision is the first revision in a chain:

previous_verification_hash is an empty string ""
Typically a file or form revision
Establishes the initial state

Verification Hash

Each revision has a unique verification hash computed from its canonical form:

Code

typescript

1hash = SHA256(canonicalized_revision_data)

This hash serves as:

Unique identifier for the revision
Key in the revisions map
Reference in previous_verification_hash fields

Revision Types

1. File Revision

Stores file metadata and optionally content.

Purpose: Document file presence and content integrity

Fields:

file_hash: SHA256 hash of file content
file_nonce: Random nonce for uniqueness
content: Optional file content (text or binary)
leaves: Array of hashes (tree mode only)

Example:

Code

json

1{
2  "previous_verification_hash": "",
3  "local_timestamp": "2024-01-01T12:00:00",
4  "revision_type": "file",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "file_hash": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
7  "file_nonce": "0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c"
8}

2. Form Revision

Stores structured key-value data.

Purpose: Capture form submissions, structured data, or metadata

Fields:

file_hash: Hash of form data
file_nonce: Random nonce
content: Form data as key-value object
leaves: Array of hashes (tree mode only)

Example:

Code

json

1{
2  "previous_verification_hash": "",
3  "local_timestamp": "2024-01-01T12:00:00",
4  "revision_type": "form",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: tree",
6  "file_hash": "0xabc123...",
7  "file_nonce": "0x123abc...",
8  "content": {
9    "name": "John Doe",
10    "email": "john@example.com",
11    "status": "approved"
12  },
13  "leaves": ["0x...", "0x...", "0x..."]
14}

3. Signature Revision

Adds cryptographic signature to prove authenticity.

Purpose: Authenticate revisions and establish authorship

Fields:

signature: Signature value (format depends on type)
signature_type: One of "cli", "metamask", "did", "p12", "inline"
signature_wallet_address: Ethereum address (for cli/metamask)
signature_public_key: Public key (for p12)

Example (MetaMask):

Code

json

1{
2  "previous_verification_hash": "0xabc123...",
3  "local_timestamp": "2024-01-01T12:01:00",
4  "revision_type": "signature",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "signature_type": "metamask",
7  "signature": "0x8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f...",
8  "signature_wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
9}

Example (DID):

Code

json

1{
2  "previous_verification_hash": "0xabc123...",
3  "local_timestamp": "2024-01-01T12:01:00",
4  "revision_type": "signature",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "signature_type": "did",
7  "signature": {
8    "payload": "eyJhbGciOi...",
9    "signatures": [{
10      "protected": "eyJhbGci...",
11      "signature": "..."
12    }]
13  }
14}

4. Witness Revision

Anchors revision to external timestamping service.

Purpose: Prove existence at specific time via blockchain or TSA

Fields:

witness_merkle_root: Root hash of Merkle tree
witness_timestamp: Unix timestamp from witness service
witness_network: Network used ("mainnet", "sepolia", "holesky", "tsa", "nostr")
witness_smart_contract_address: Contract address (Ethereum)
witness_transaction_hash: Transaction hash
witness_sender_account_address: Account that witnessed
witness_merkle_proof: Merkle proof array

Example (Ethereum):

Code

json

1{
2  "previous_verification_hash": "0xabc123...",
3  "local_timestamp": "2024-01-01T12:02:00",
4  "revision_type": "witness",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "witness_merkle_root": "0xdef456...",
7  "witness_timestamp": 1704110520,
8  "witness_network": "sepolia",
9  "witness_smart_contract_address": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
10  "witness_transaction_hash": "0x9f86d081...",
11  "witness_sender_account_address": "0x742d35Cc...",
12  "witness_merkle_proof": []
13}

5. Link Revision

Connects to other AquaTree chains.

Purpose: Establish relationships between separate chains

Fields:

link_type: Type of link relationship (application-specific)
link_verification_hashes: Array of hashes from other chains
link_file_hashes: Array of corresponding file hashes

Example:

Code

json

1{
2  "previous_verification_hash": "0xabc123...",
3  "local_timestamp": "2024-01-01T12:03:00",
4  "revision_type": "link",
5  "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
6  "link_type": "dependency",
7  "link_verification_hashes": [
8    "0x111...",
9    "0x222...",
10    "0x333..."
11  ],
12  "link_file_hashes": [
13    "0xaaa...",
14    "0xbbb...",
15    "0xccc..."
16  ]
17}

Methods: Scalar vs Tree

V3 supports two canonicalization methods, specified in the version string.

Scalar Method

Format: Method: scalar

How it works:

Revision is serialized as-is
Hash computed directly from canonical JSON
Simple, straightforward

When to use:

Small revisions
Simple file/form data
Quick operations

Example:

Code

typescript

1version: "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar"
2// No leaves field

Tree Method

Format: Method: tree

How it works:

Content broken into key-value leaves
Each leaf hashed individually
Merkle tree constructed from leaves
Root becomes the verification hash

When to use:

Large files or forms
Selective disclosure needed
Proof of specific fields

Example:

Code

typescript

1version: "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: tree"
2leaves: [
3  "0xhash_of_key_value_1",
4  "0xhash_of_key_value_2",
5  "0xhash_of_key_value_3"
6]

Leaf Generation:

Code

typescript

1// For form data: { "name": "John", "email": "john@example.com" }
2leaves = [
3  SHA256("name:John"),
4  SHA256("email:john@example.com")
5]

Chains and Trees

Linear Chain

Simple sequence of revisions:

Genesis � Signature � Witness � Update � Signature � Witness

Each revision references the previous one.

Branching Tree

Multiple paths from a common ancestor:

            Genesis
               �
          Signature
             /  \
        Branch A  Branch B
           �        �
        Update 1  Update 2

V3 supports branching, allowing parallel development paths.

Path Mapping

The treeMapping provides paths to each revision:

Code

typescript

1{
2  paths: {
3    "genesis_hash": ["genesis_hash"],
4    "sig_hash": ["genesis_hash", "sig_hash"],
5    "branch_a_hash": ["genesis_hash", "sig_hash", "branch_a_hash"],
6    "branch_b_hash": ["genesis_hash", "sig_hash", "branch_b_hash"]
7  },
8  latestHash: "branch_a_hash"  // Longest path
9}

File Object

Input format for creating revisions:

Code

typescript

1interface FileObject {
2  fileName: string           // Display name
3  fileContent: string |      // Text content
4                AquaTree |   // Linked tree
5                Uint8Array | // Binary data
6                Record<string, string> | // Form data
7                object       // Structured data
8  path: string              // File path
9  fileSize?: number         // Size in bytes
10}

Content Types

Text: Plain text, HTML, JSON

Code

typescript

1{
2  fileName: "doc.txt",
3  fileContent: "Hello World",
4  path: "/docs/doc.txt"
5}

Binary: Images, PDFs, any binary file

Code

typescript

1{
2  fileName: "image.png",
3  fileContent: new Uint8Array([...]),
4  path: "/images/image.png"
5}

Form: Key-value structured data

Code

typescript

1{
2  fileName: "form.json",
3  fileContent: {
4    "field1": "value1",
5    "field2": "value2"
6  },
7  path: "/forms/form.json"
8}

Link: Reference to another AquaTree

Code

typescript

1{
2  fileName: "linked.json",
3  fileContent: anotherAquaTree,
4  path: "/links/linked.json"
5}

Verification Graph

Result of verification includes a graph structure:

Code

typescript

1interface VerificationGraphData {
2  hash: string
3  previous_verification_hash: string
4  timestamp: string
5  isValidationSuccessful: boolean
6  revisionType: RevisionType
7  info: RevisionGraphInfo  // Type-specific details
8  verificationGraphData: VerificationGraphData[]      // Children
9  linkVerificationGraphData: VerificationGraphData[]  // Links
10}

Traversing the Graph

Code

typescript

1function printVerification(graph: VerificationGraphData, depth = 0) {
2  const indent = "  ".repeat(depth);
3  const status = graph.isValidationSuccessful ? "" : "";
4  console.log(`${indent}${status} ${graph.revisionType} (${graph.hash.slice(0, 10)}...)`);
5 
6  // Traverse children
7  graph.verificationGraphData.forEach(child => {
8    printVerification(child, depth + 1);
9  });
10 
11  // Traverse links
12  graph.linkVerificationGraphData.forEach(link => {
13    console.log(`${indent}  � Linked:`);
14    printVerification(link, depth + 2);
15  });
16}

Credentials

Configuration for signing and witnessing:

Code

typescript

1interface CredentialsData {
2  mnemonic: string             // BIP39 mnemonic for CLI signing
3  nostr_sk: string             // Nostr secret key
4  did_key: string              // DID key for DID signing
5  alchemy_key: string          // Alchemy API key for verification
6  witness_eth_network: string  // "mainnet", "sepolia", "holesky"
7  witness_method: string       // "cli" or "metamask"
8  p12_password?: string        // P12 certificate password
9  p12_content?: string         // P12 certificate content
10}

Logging

V3 uses typed logging throughout:

Code

typescript

1enum LogType {
2  SUCCESS = "success",
3  INFO = "info",
4  ERROR = "error",
5  WARNING = "warning",
6  HINT = "hint",
7  DEBUGDATA = "debug_data",
8  // ... revision types with emojis
9  FILE = "file",      // =�
10  LINK = "link",      // =
11  SIGNATURE = "signature",  // =
12  WITNESS = "witness",      // =@
13  FORM = "form"            // =�
14}

Each operation returns logs for debugging and user feedback.

Best Practices

1. Genesis Patterns

Single File:

File Genesis � Sign � Witness

Form Data:

Form Genesis � Sign � Witness

2. Update Patterns

Content Update:

... � New File Revision � Sign � Witness

Multi-Party:

... � Sign (Party 1) � Sign (Party 2) � Witness

3. Linking Patterns

Dependencies:

Main Document � Link (to dependencies) � Sign � Witness

Aggregation:

Component 1 
Component 2 � Aggregation Link � Sign � Witness
Component 3

4. Verification Patterns

Full Chain:

Code

typescript

1const result = await aquafier.verifyRevisionChain(aquaTree);

Specific Revision:

Code

typescript

1const revision = aquaTree.revisions[specificHash];
2// Manually verify hash computation

5. Storage Patterns

Database: Store serialized AquaTree JSON

Code

typescript

1const json = JSON.stringify(aquaTree);
2db.save(documentId, json);

File System: Save as .aqua.json file

Code

typescript

1fs.writeFileSync('document.aqua.json', JSON.stringify(aquaTree, null, 2));

Common Patterns

Document Lifecycle

1. Create � File Genesis
2. Review � Sign (Reviewer)
3. Approve � Sign (Approver)
4. Timestamp � Witness (Ethereum)
5. Archive � Store AquaTree
6. Verify � Check entire chain

Multi-Document Project

1. Create each document � Individual AquaTrees
2. Link together � Link Revision in main tree
3. Sign project � Sign main tree
4. Witness � Witness main tree
5. All documents timestamped through link

Documentation

Concepts

Aqua Protocol v3 Concepts

AquaTree

Structure

Components

1. Revisions

2. File Index

3. Tree Structure (Optional)

4. Tree Mapping (Optional)

Revisions

Common Fields

Genesis Revision

Verification Hash

Revision Types

1. File Revision

2. Form Revision

3. Signature Revision

4. Witness Revision

5. Link Revision

Methods: Scalar vs Tree

Scalar Method

Tree Method

Chains and Trees

Linear Chain

Branching Tree

Path Mapping

File Object

Content Types

Verification Graph

Traversing the Graph

Credentials

Logging

Best Practices

1. Genesis Patterns

2. Update Patterns

3. Linking Patterns

4. Verification Patterns

5. Storage Patterns

Common Patterns

Document Lifecycle

Multi-Document Project

See Also

Documentation

Concepts

Aqua Protocol v3 Concepts

AquaTree

Structure

Components

1. Revisions

2. File Index

3. Tree Structure (Optional)

4. Tree Mapping (Optional)

Revisions

Common Fields

Genesis Revision

Verification Hash

Revision Types

1. File Revision

2. Form Revision

3. Signature Revision

4. Witness Revision

5. Link Revision

Methods: Scalar vs Tree

Scalar Method

Tree Method

Chains and Trees

Linear Chain

Branching Tree

Path Mapping

File Object

Content Types

Verification Graph

Traversing the Graph

Credentials

Logging

Best Practices

1. Genesis Patterns

2. Update Patterns

3. Linking Patterns