Aqua Protocol v3 - Schema Reference

This document provides comprehensive technical specifications for all revision types in Aqua Protocol v3. Each revision type has specific fields and validation rules.

Version String Format

https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: {scalar|tree}

Components:

Protocol URL: https://aqua-protocol.org/docs/v3/schema_2
Hash Algorithm: SHA256
Canonicalization Method: scalar or tree

Common Fields

All revisions share these mandatory fields:

Field	Type	Description	Validation
`previous_verification_hash`	string	Hash of previous revision	Empty string for genesis, otherwise 64-char hex with `0x` prefix
`local_timestamp`	string	ISO 8601 timestamp	Valid ISO 8601 format: `YYYY-MM-DDTHH:mm:ss`
`revision_type`	string	Type of revision	One of: `"file"`, `"form"`, `"signature"`, `"witness"`, `"link"`
`version`	string	Protocol version and method	Must match format above

File Revision

Represents a file with metadata and optional content.

Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Previous revision hash (empty for genesis)
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"file"`
`version`	string	Yes	Protocol version string
`file_hash`	string	Yes	SHA256 hash of file content (hex with `0x`)
`file_nonce`	string	Yes	Random 16-byte nonce (hex with `0x`)
`content`	string/Uint8Array	No	Optional file content
`leaves`	string[]	Conditional	Required if `Method: tree`, array of leaf hashes

Genesis File Revision (Scalar)

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}

Genesis File Revision (Tree)

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: tree",
6  "file_hash": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
7  "file_nonce": "0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c",
8  "leaves": [
9    "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
10    "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
11  ]
12}

With Content

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  "content": "This is the file content as a string"
9}

Validation Rules

file_hash must match SHA256 of file content
file_nonce must be exactly 16 bytes (32 hex chars + 0x)
If Method: tree, leaves array must be present
If Method: scalar, leaves must be absent
content is optional but if present, hash must match file_hash

Form Revision

Stores structured key-value data.

Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Previous revision hash (empty for genesis)
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"form"`
`version`	string	Yes	Protocol version string
`file_hash`	string	Yes	SHA256 hash of form data
`file_nonce`	string	Yes	Random 16-byte nonce
`content`	object	Yes	Form data as key-value pairs
`leaves`	string[]	Conditional	Required if `Method: tree`

Example (Scalar)

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: scalar",
6  "file_hash": "0xabc123def456...",
7  "file_nonce": "0x7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
8  "content": {
9    "name": "John Doe",
10    "email": "john@example.com",
11    "organization": "Example Corp",
12    "role": "Developer"
13  }
14}

Example (Tree)

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": "0xabc123def456...",
7  "file_nonce": "0x7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
8  "content": {
9    "name": "John Doe",
10    "email": "john@example.com",
11    "organization": "Example Corp",
12    "role": "Developer"
13  },
14  "leaves": [
15    "0x...",  // SHA256("name:John Doe")
16    "0x...",  // SHA256("email:john@example.com")
17    "0x...",  // SHA256("organization:Example Corp")
18    "0x..."   // SHA256("role:Developer")
19  ]
20}

Leaf Computation (Tree Mode)

For each key-value pair in content:

Code

typescript

1leaf_hash = SHA256(`${key}:${value}`)

Validation Rules

content must be a valid JSON object
All values in content must be strings
file_hash must match hash of canonicalized content
If Method: tree, number of leaves must match number of keys in content

Signature Revision

Adds cryptographic signature to verify authenticity.

Common Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Hash of revision being signed
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"signature"`
`version`	string	Yes	Protocol version string
`signature_type`	string	Yes	Type: `"cli"`, `"metamask"`, `"did"`, `"p12"`, `"inline"`

CLI / MetaMask Signature

Additional Fields:

Field	Type	Required	Description
`signature`	string	Yes	Hex-encoded signature (65 bytes for ECDSA)
`signature_wallet_address`	string	Yes	Ethereum address (EIP-55 checksummed)

Example:

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": "cli",
7  "signature": "0x8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d1c",
8  "signature_wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
9}

DID Signature

Additional Fields:

Field	Type	Required	Description
`signature`	object	Yes	JWS (JSON Web Signature) object

Signature Object Structure:

Code

typescript

1{
2  payload: string;       // Base64url-encoded payload
3  signatures: [{
4    protected: string;   // Base64url-encoded protected header
5    signature: string;   // Base64url-encoded signature
6  }]
7}

Example:

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": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19",
9    "signatures": [{
10      "protected": "eyJhbGciOiJFZERTQSJ9",
11      "signature": "kKvXJ_qjJRtGQFLpRvQlCdXMFD8sSE4DTlbMmLqg0BJ9FQKLHvX7y_z5Pr8u0xT8D2vCj9qL1KzN4rP2MzKfBQ"
12    }]
13  }
14}

P12 Certificate Signature

Additional Fields:

Field	Type	Required	Description
`signature`	string	Yes	Hex-encoded signature
`signature_public_key`	string	Yes	Hex-encoded DER public key

Example:

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": "p12",
7  "signature": "0x...",
8  "signature_public_key": "0x308201a2300d06092a864886f70d01010105000382018f..."
9}

Inline Signature

Same as CLI/MetaMask but with pre-computed signature.

Validation Rules

Signature must be verifiable using provided credentials
For CLI/MetaMask: Address must be recoverable from signature
For DID: JWS must be valid and verifiable
For P12: Signature must verify with public key
Signature must be computed over previous_verification_hash

Witness Revision

Anchors revision to blockchain or timestamping service.

Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Hash being witnessed
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"witness"`
`version`	string	Yes	Protocol version string
`witness_merkle_root`	string	Yes	Root hash of Merkle tree
`witness_timestamp`	number	Yes	Unix timestamp from witness service
`witness_network`	string	Yes	Network: `"mainnet"`, `"sepolia"`, `"holesky"`, `"tsa"`, `"nostr"`
`witness_smart_contract_address`	string	Conditional	Required for Ethereum
`witness_transaction_hash`	string	Yes	Transaction or event hash
`witness_sender_account_address`	string	Conditional	Required for Ethereum
`witness_merkle_proof`	string[]	Yes	Merkle proof (empty for single witness)

Ethereum Witness Example

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": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
11  "witness_sender_account_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
12  "witness_merkle_proof": []
13}

Batched Witness Example

Multiple revisions witnessed in single transaction:

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": "0xroot...",
7  "witness_timestamp": 1704110520,
8  "witness_network": "mainnet",
9  "witness_smart_contract_address": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
10  "witness_transaction_hash": "0x9f86d081...",
11  "witness_sender_account_address": "0x742d35Cc...",
12  "witness_merkle_proof": [
13    "0xsibling_hash_1",
14    "0xsibling_hash_2",
15    "0xsibling_hash_3"
16  ]
17}

Nostr Witness Example

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": "0xabc123...",
7  "witness_timestamp": 1704110520,
8  "witness_network": "nostr",
9  "witness_smart_contract_address": "",
10  "witness_transaction_hash": "nevent1qqsw...",
11  "witness_sender_account_address": "npub1...",
12  "witness_merkle_proof": []
13}

TSA Witness Example

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": "0xabc123...",
7  "witness_timestamp": 1704110520,
8  "witness_network": "tsa",
9  "witness_smart_contract_address": "https://timestamp.digicert.com",
10  "witness_transaction_hash": "base64_tsa_response",
11  "witness_sender_account_address": "",
12  "witness_merkle_proof": []
13}

Validation Rules

For single witness: witness_merkle_proof must be empty array
For single witness: witness_merkle_root equals previous_verification_hash
For batched: Merkle proof must verify back to witness_merkle_root
Transaction must exist and be confirmed on specified network
witness_timestamp should match blockchain/service timestamp
For Ethereum: Contract address and sender address required

Link Revision

Connects to other AquaTree chains.

Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Previous revision in this chain
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"link"`
`version`	string	Yes	Protocol version string
`link_type`	string	No	Application-specific link type
`link_verification_hashes`	string[]	Yes	Array of hashes from other chains
`link_file_hashes`	string[]	No	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": "dependencies",
7  "link_verification_hashes": [
8    "0x111222333444555666777888999000aaabbbcccdddeeefff000111222333444",
9    "0x222333444555666777888999000aaabbbcccdddeeefff000111222333444555",
10    "0x333444555666777888999000aaabbbcccdddeeefff000111222333444555666"
11  ],
12  "link_file_hashes": [
13    "0xfileHash1...",
14    "0xfileHash2...",
15    "0xfileHash3..."
16  ]
17}

Validation Rules

link_verification_hashes must be non-empty array
Each hash in array must be valid revision hash
If link_file_hashes present, must have same length as link_verification_hashes
Referenced revisions should exist (optional strict validation)

Hash Computation

Scalar Method

Serialize revision as canonical JSON (sorted keys)
Compute SHA256 hash of serialized string
Prefix with 0x

Code

typescript

1const canonical = JSON.stringify(sortKeys(revision));
2const hash = "0x" + sha256(canonical).toString('hex');

Tree Method

Extract leaves array from revision
Build Merkle tree from leaves
Root hash becomes verification hash

Code

typescript

1const leaves = revision.leaves;
2const tree = new MerkleTree(leaves, sha256);
3const hash = "0x" + tree.getRoot().toString('hex');

AquaTree Storage Format

Complete AquaTree structure for storage/transmission:

Code

json

1{
2  "revisions": {
3    "0xgenesis_hash": {
4      "previous_verification_hash": "",
5      "local_timestamp": "2024-01-01T12:00:00",
6      "revision_type": "file",
7      "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
8      "file_hash": "0x...",
9      "file_nonce": "0x..."
10    },
11    "0xsignature_hash": {
12      "previous_verification_hash": "0xgenesis_hash",
13      "local_timestamp": "2024-01-01T12:01:00",
14      "revision_type": "signature",
15      "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
16      "signature_type": "cli",
17      "signature": "0x...",
18      "signature_wallet_address": "0x..."
19    },
20    "0xwitness_hash": {
21      "previous_verification_hash": "0xsignature_hash",
22      "local_timestamp": "2024-01-01T12:02:00",
23      "revision_type": "witness",
24      "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
25      "witness_merkle_root": "0x...",
26      "witness_timestamp": 1704110520,
27      "witness_network": "sepolia",
28      "witness_smart_contract_address": "0x...",
29      "witness_transaction_hash": "0x...",
30      "witness_sender_account_address": "0x...",
31      "witness_merkle_proof": []
32    }
33  },
34  "file_index": {
35    "0xfile_hash": "document.pdf"
36  },
37  "tree": {
38    "hash": "0xgenesis_hash",
39    "children": [
40      {
41        "hash": "0xsignature_hash",
42        "children": [
43          {
44            "hash": "0xwitness_hash",
45            "children": []
46          }
47        ]
48      }
49    ]
50  },
51  "treeMapping": {
52    "paths": {
53      "0xgenesis_hash": ["0xgenesis_hash"],
54      "0xsignature_hash": ["0xgenesis_hash", "0xsignature_hash"],
55      "0xwitness_hash": ["0xgenesis_hash", "0xsignature_hash", "0xwitness_hash"]
56    },
57    "latestHash": "0xwitness_hash"
58  }
59}

Field Constraints

Hashes

Format: Lowercase hexadecimal with 0x prefix
Length: 64 characters (32 bytes) + 2-char prefix = 66 total
Example: 0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Timestamps

Format: ISO 8601
Pattern: YYYY-MM-DDTHH:mm:ss
Example: 2024-01-01T12:00:00

Ethereum Addresses

Format: EIP-55 checksummed
Length: 42 characters (20 bytes + 0x)
Mixed case for checksum
Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8

Nonces

Length: Exactly 16 bytes (32 hex chars + 0x)
Format: Lowercase hexadecimal with 0x prefix
Example: 0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c

Version Compatibility

v3.2.x: Current version, fully compatible
v3.1.x: Compatible, minor improvements
v3.0.x: Compatible, initial TypeScript release
v2.x: Not compatible, different schema

Aqua Protocol v3 - Schema Reference

This document provides comprehensive technical specifications for all revision types in Aqua Protocol v3. Each revision type has specific fields and validation rules.

Version String Format

https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: {scalar|tree}

Components:

Protocol URL: https://aqua-protocol.org/docs/v3/schema_2
Hash Algorithm: SHA256
Canonicalization Method: scalar or tree

Common Fields

All revisions share these mandatory fields:

Field	Type	Description	Validation
`previous_verification_hash`	string	Hash of previous revision	Empty string for genesis, otherwise 64-char hex with `0x` prefix
`local_timestamp`	string	ISO 8601 timestamp	Valid ISO 8601 format: `YYYY-MM-DDTHH:mm:ss`
`revision_type`	string	Type of revision	One of: `"file"`, `"form"`, `"signature"`, `"witness"`, `"link"`
`version`	string	Protocol version and method	Must match format above

File Revision

Represents a file with metadata and optional content.

Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Previous revision hash (empty for genesis)
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"file"`
`version`	string	Yes	Protocol version string
`file_hash`	string	Yes	SHA256 hash of file content (hex with `0x`)
`file_nonce`	string	Yes	Random 16-byte nonce (hex with `0x`)
`content`	string/Uint8Array	No	Optional file content
`leaves`	string[]	Conditional	Required if `Method: tree`, array of leaf hashes

Genesis File Revision (Scalar)

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}

Genesis File Revision (Tree)

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: tree",
6  "file_hash": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
7  "file_nonce": "0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c",
8  "leaves": [
9    "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
10    "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
11  ]
12}

With Content

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  "content": "This is the file content as a string"
9}

Validation Rules

file_hash must match SHA256 of file content
file_nonce must be exactly 16 bytes (32 hex chars + 0x)
If Method: tree, leaves array must be present
If Method: scalar, leaves must be absent
content is optional but if present, hash must match file_hash

Form Revision

Stores structured key-value data.

Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Previous revision hash (empty for genesis)
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"form"`
`version`	string	Yes	Protocol version string
`file_hash`	string	Yes	SHA256 hash of form data
`file_nonce`	string	Yes	Random 16-byte nonce
`content`	object	Yes	Form data as key-value pairs
`leaves`	string[]	Conditional	Required if `Method: tree`

Example (Scalar)

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: scalar",
6  "file_hash": "0xabc123def456...",
7  "file_nonce": "0x7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
8  "content": {
9    "name": "John Doe",
10    "email": "john@example.com",
11    "organization": "Example Corp",
12    "role": "Developer"
13  }
14}

Example (Tree)

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": "0xabc123def456...",
7  "file_nonce": "0x7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f",
8  "content": {
9    "name": "John Doe",
10    "email": "john@example.com",
11    "organization": "Example Corp",
12    "role": "Developer"
13  },
14  "leaves": [
15    "0x...",  // SHA256("name:John Doe")
16    "0x...",  // SHA256("email:john@example.com")
17    "0x...",  // SHA256("organization:Example Corp")
18    "0x..."   // SHA256("role:Developer")
19  ]
20}

Leaf Computation (Tree Mode)

For each key-value pair in content:

Code

typescript

1leaf_hash = SHA256(`${key}:${value}`)

Validation Rules

content must be a valid JSON object
All values in content must be strings
file_hash must match hash of canonicalized content
If Method: tree, number of leaves must match number of keys in content

Signature Revision

Adds cryptographic signature to verify authenticity.

Common Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Hash of revision being signed
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"signature"`
`version`	string	Yes	Protocol version string
`signature_type`	string	Yes	Type: `"cli"`, `"metamask"`, `"did"`, `"p12"`, `"inline"`

CLI / MetaMask Signature

Additional Fields:

Field	Type	Required	Description
`signature`	string	Yes	Hex-encoded signature (65 bytes for ECDSA)
`signature_wallet_address`	string	Yes	Ethereum address (EIP-55 checksummed)

Example:

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": "cli",
7  "signature": "0x8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d1c",
8  "signature_wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8"
9}

DID Signature

Additional Fields:

Field	Type	Required	Description
`signature`	object	Yes	JWS (JSON Web Signature) object

Signature Object Structure:

Code

typescript

1{
2  payload: string;       // Base64url-encoded payload
3  signatures: [{
4    protected: string;   // Base64url-encoded protected header
5    signature: string;   // Base64url-encoded signature
6  }]
7}

Example:

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": "eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19",
9    "signatures": [{
10      "protected": "eyJhbGciOiJFZERTQSJ9",
11      "signature": "kKvXJ_qjJRtGQFLpRvQlCdXMFD8sSE4DTlbMmLqg0BJ9FQKLHvX7y_z5Pr8u0xT8D2vCj9qL1KzN4rP2MzKfBQ"
12    }]
13  }
14}

P12 Certificate Signature

Additional Fields:

Field	Type	Required	Description
`signature`	string	Yes	Hex-encoded signature
`signature_public_key`	string	Yes	Hex-encoded DER public key

Example:

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": "p12",
7  "signature": "0x...",
8  "signature_public_key": "0x308201a2300d06092a864886f70d01010105000382018f..."
9}

Inline Signature

Same as CLI/MetaMask but with pre-computed signature.

Validation Rules

Signature must be verifiable using provided credentials
For CLI/MetaMask: Address must be recoverable from signature
For DID: JWS must be valid and verifiable
For P12: Signature must verify with public key
Signature must be computed over previous_verification_hash

Witness Revision

Anchors revision to blockchain or timestamping service.

Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Hash being witnessed
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"witness"`
`version`	string	Yes	Protocol version string
`witness_merkle_root`	string	Yes	Root hash of Merkle tree
`witness_timestamp`	number	Yes	Unix timestamp from witness service
`witness_network`	string	Yes	Network: `"mainnet"`, `"sepolia"`, `"holesky"`, `"tsa"`, `"nostr"`
`witness_smart_contract_address`	string	Conditional	Required for Ethereum
`witness_transaction_hash`	string	Yes	Transaction or event hash
`witness_sender_account_address`	string	Conditional	Required for Ethereum
`witness_merkle_proof`	string[]	Yes	Merkle proof (empty for single witness)

Ethereum Witness Example

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": "0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
11  "witness_sender_account_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8",
12  "witness_merkle_proof": []
13}

Batched Witness Example

Multiple revisions witnessed in single transaction:

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": "0xroot...",
7  "witness_timestamp": 1704110520,
8  "witness_network": "mainnet",
9  "witness_smart_contract_address": "0x5FbDB2315678afecb367f032d93F642f64180aa3",
10  "witness_transaction_hash": "0x9f86d081...",
11  "witness_sender_account_address": "0x742d35Cc...",
12  "witness_merkle_proof": [
13    "0xsibling_hash_1",
14    "0xsibling_hash_2",
15    "0xsibling_hash_3"
16  ]
17}

Nostr Witness Example

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": "0xabc123...",
7  "witness_timestamp": 1704110520,
8  "witness_network": "nostr",
9  "witness_smart_contract_address": "",
10  "witness_transaction_hash": "nevent1qqsw...",
11  "witness_sender_account_address": "npub1...",
12  "witness_merkle_proof": []
13}

TSA Witness Example

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": "0xabc123...",
7  "witness_timestamp": 1704110520,
8  "witness_network": "tsa",
9  "witness_smart_contract_address": "https://timestamp.digicert.com",
10  "witness_transaction_hash": "base64_tsa_response",
11  "witness_sender_account_address": "",
12  "witness_merkle_proof": []
13}

Validation Rules

For single witness: witness_merkle_proof must be empty array
For single witness: witness_merkle_root equals previous_verification_hash
For batched: Merkle proof must verify back to witness_merkle_root
Transaction must exist and be confirmed on specified network
witness_timestamp should match blockchain/service timestamp
For Ethereum: Contract address and sender address required

Link Revision

Connects to other AquaTree chains.

Fields

Field	Type	Required	Description
`previous_verification_hash`	string	Yes	Previous revision in this chain
`local_timestamp`	string	Yes	ISO 8601 timestamp
`revision_type`	string	Yes	Must be `"link"`
`version`	string	Yes	Protocol version string
`link_type`	string	No	Application-specific link type
`link_verification_hashes`	string[]	Yes	Array of hashes from other chains
`link_file_hashes`	string[]	No	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": "dependencies",
7  "link_verification_hashes": [
8    "0x111222333444555666777888999000aaabbbcccdddeeefff000111222333444",
9    "0x222333444555666777888999000aaabbbcccdddeeefff000111222333444555",
10    "0x333444555666777888999000aaabbbcccdddeeefff000111222333444555666"
11  ],
12  "link_file_hashes": [
13    "0xfileHash1...",
14    "0xfileHash2...",
15    "0xfileHash3..."
16  ]
17}

Validation Rules

link_verification_hashes must be non-empty array
Each hash in array must be valid revision hash
If link_file_hashes present, must have same length as link_verification_hashes
Referenced revisions should exist (optional strict validation)

Hash Computation

Scalar Method

Serialize revision as canonical JSON (sorted keys)
Compute SHA256 hash of serialized string
Prefix with 0x

Code

typescript

1const canonical = JSON.stringify(sortKeys(revision));
2const hash = "0x" + sha256(canonical).toString('hex');

Tree Method

Extract leaves array from revision
Build Merkle tree from leaves
Root hash becomes verification hash

Code

typescript

1const leaves = revision.leaves;
2const tree = new MerkleTree(leaves, sha256);
3const hash = "0x" + tree.getRoot().toString('hex');

AquaTree Storage Format

Complete AquaTree structure for storage/transmission:

Code

json

1{
2  "revisions": {
3    "0xgenesis_hash": {
4      "previous_verification_hash": "",
5      "local_timestamp": "2024-01-01T12:00:00",
6      "revision_type": "file",
7      "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
8      "file_hash": "0x...",
9      "file_nonce": "0x..."
10    },
11    "0xsignature_hash": {
12      "previous_verification_hash": "0xgenesis_hash",
13      "local_timestamp": "2024-01-01T12:01:00",
14      "revision_type": "signature",
15      "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
16      "signature_type": "cli",
17      "signature": "0x...",
18      "signature_wallet_address": "0x..."
19    },
20    "0xwitness_hash": {
21      "previous_verification_hash": "0xsignature_hash",
22      "local_timestamp": "2024-01-01T12:02:00",
23      "revision_type": "witness",
24      "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: scalar",
25      "witness_merkle_root": "0x...",
26      "witness_timestamp": 1704110520,
27      "witness_network": "sepolia",
28      "witness_smart_contract_address": "0x...",
29      "witness_transaction_hash": "0x...",
30      "witness_sender_account_address": "0x...",
31      "witness_merkle_proof": []
32    }
33  },
34  "file_index": {
35    "0xfile_hash": "document.pdf"
36  },
37  "tree": {
38    "hash": "0xgenesis_hash",
39    "children": [
40      {
41        "hash": "0xsignature_hash",
42        "children": [
43          {
44            "hash": "0xwitness_hash",
45            "children": []
46          }
47        ]
48      }
49    ]
50  },
51  "treeMapping": {
52    "paths": {
53      "0xgenesis_hash": ["0xgenesis_hash"],
54      "0xsignature_hash": ["0xgenesis_hash", "0xsignature_hash"],
55      "0xwitness_hash": ["0xgenesis_hash", "0xsignature_hash", "0xwitness_hash"]
56    },
57    "latestHash": "0xwitness_hash"
58  }
59}

Field Constraints

Hashes

Format: Lowercase hexadecimal with 0x prefix
Length: 64 characters (32 bytes) + 2-char prefix = 66 total
Example: 0x9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08

Timestamps

Format: ISO 8601
Pattern: YYYY-MM-DDTHH:mm:ss
Example: 2024-01-01T12:00:00

Ethereum Addresses

Format: EIP-55 checksummed
Length: 42 characters (20 bytes + 0x)
Mixed case for checksum
Example: 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb8

Nonces

Length: Exactly 16 bytes (32 hex chars + 0x)
Format: Lowercase hexadecimal with 0x prefix
Example: 0x3fa8b1c2d3e4f5a67b8c9d0e1f2a3b4c

Version Compatibility

v3.2.x: Current version, fully compatible
v3.1.x: Compatible, minor improvements
v3.0.x: Compatible, initial TypeScript release
v2.x: Not compatible, different schema

Documentation

Schema Reference

Aqua Protocol v3 - Schema Reference

Version String Format

Common Fields

File Revision

Fields

Genesis File Revision (Scalar)

Genesis File Revision (Tree)

With Content

Validation Rules

Form Revision

Fields

Example (Scalar)

Example (Tree)

Leaf Computation (Tree Mode)

Validation Rules

Signature Revision

Common Fields

CLI / MetaMask Signature

DID Signature

P12 Certificate Signature

Inline Signature

Validation Rules

Witness Revision

Fields

Ethereum Witness Example

Batched Witness Example

Nostr Witness Example

TSA Witness Example

Validation Rules

Link Revision

Fields

Example

Validation Rules

Hash Computation

Scalar Method

Tree Method

AquaTree Storage Format

Field Constraints

Hashes

Timestamps

Ethereum Addresses

Nonces

Version Compatibility

See Also

Documentation

Schema Reference

Aqua Protocol v3 - Schema Reference

Version String Format

Common Fields

File Revision

Fields

Genesis File Revision (Scalar)

Genesis File Revision (Tree)

With Content

Validation Rules

Form Revision

Fields

Example (Scalar)

Example (Tree)

Leaf Computation (Tree Mode)

Validation Rules

Signature Revision

Common Fields

CLI / MetaMask Signature

DID Signature

P12 Certificate Signature

Inline Signature

Validation Rules

Witness Revision

Fields

Ethereum Witness Example

Batched Witness Example

Nostr Witness Example

TSA Witness Example

Validation Rules

Link Revision

Fields

Example