Aqua Protocol v3

Aqua Protocol v3 is a mature version of the protocol with a comprehensive JavaScript/TypeScript SDK. It provides a robust framework for creating verifiable revision chains with support for files, forms, signatures, witnesses, and links.

Overview

Version 3 represents a stable, production-ready implementation of the Aqua Protocol specifically designed for JavaScript/TypeScript environments. It offers:

• Cross-Platform Support: Node.js, Web browsers, and React Native
• Type Safety: Full TypeScript support with comprehensive type definitions
• Flexible Revision Types: File, Form, Signature, Witness, and Link revisions
• Multiple Signing Methods: CLI, MetaMask, DID, and P12 certificate signing
• Multi-Network Witnessing: Ethereum (mainnet, Sepolia, Holesky), Nostr, and TSA
• Tree Structure: Native support for revision trees and path mapping

Version Identifier

Core Components

AquaTree Structure

The AquaTree is the core data structure in v3:

1interface AquaTree {
2  revisions: Revisions      // Map of revision hash to revision data
3  file_index: FileIndex     // Map of file hash to filename
4  tree?: RevisionTree       // Tree structure representation
5  treeMapping?: TreeMapping // Path mappings for navigation
6}

Revision Types

V3 supports five types of revisions:

1. File Revision - Store file metadata and content hashes
2. Form Revision - Store structured form data with key-value pairs
3. Signature Revision - Add cryptographic signatures
4. Witness Revision - Timestamp via blockchain or TSA
5. Link Revision - Connect to other AquaTree chains

Key Features

1. Dual Mode Support

Scalar Mode: Direct hash computation

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

Tree Mode: Merkle tree-based with leaves

1version: "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: tree"
2leaves: ["hash1", "hash2", "hash3", ...]

2. Platform Flexibility

1// Node.js
2import Aquafier from 'aqua-js-sdk';
3 
4// Web Browser
5import Aquafier from 'aqua-js-sdk/web';
6 
7// React Native
8import Aquafier from 'aqua-js-sdk/react-native';

3. Comprehensive Signing

• CLI Signing: Uses mnemonic phrase
• MetaMask: Browser extension integration
• DID: Decentralized identifiers with JWS
• P12: Certificate-based signing
• Inline: Pre-computed signatures

4. Multi-Network Witnessing

• Ethereum: Mainnet, Sepolia, Holesky testnets
• Nostr: Decentralized social network
• TSA: RFC 3161 timestamp authorities

5. Content Flexibility

File content can be:

• Text: HTML, plain text, JSON
• Binary: Images, PDFs, any file type (as Uint8Array)
• Forms: Key-value structured data
• Links: References to other AquaTrees

Quick Start Example

1import Aquafier, { FileObject } from 'aqua-js-sdk';
2 
3// Initialize Aquafier
4const aquafier = new Aquafier();
5 
6// Create file object
7const fileObject: FileObject = {
8  fileName: "document.txt",
9  fileContent: "Important document content",
10  path: "/documents/document.txt"
11};
12 
13// Create genesis revision
14const result = await aquafier.createGenesisRevision(fileObject);
15 
16if (result.isErr) {
17  console.error("Error creating revision");
18  result.logs.forEach(log => console.log(log));
19  return;
20}
21 
22// Access the AquaTree
23const aquaTree = result.data.aquaTree;
24 
25// Sign the revision
26const signResult = await aquafier.signRevision(
27  aquaTree,
28  "cli",  // or "metamask", "did", "p12"
29  credentials
30);
31 
32// Witness to blockchain
33const witnessResult = await aquafier.witnessRevision(
34  signResult.data.aquaTree,
35  "eth",  // or "nostr", "tsa"
36  witnessConfig
37);
38 
39// Save aquaTree JSON for storage/transmission
40const json = JSON.stringify(witnessResult.data.aquaTree);

Architecture

Revision Chain Structure

Tree Branching

V3 supports tree structures for branching revisions:

Common Fields

All revisions share these core fields:

Installation

1npm install aqua-js-sdk

Requirements

• Node.js v20.9.0 or later
• TypeScript 5.3+ (optional, for type checking)

Peer Dependencies

• ethers ^6.7.1 (for Ethereum operations)
• react-native-fs (optional, for React Native)
• @react-native-async-storage/async-storage (optional, for React Native)

Use Cases

Document Notarization

Form Data Accountability

Multi-Party Approval

Supply Chain Tracking

Content Versioning

Verification

V3 includes comprehensive verification capabilities:

1// Verify entire chain
2const verification = await aquafier.verifyRevisionChain(aquaTree);
3 
4// Check results
5verification.verificationGraphData.forEach(node => {
6  console.log(`${node.revisionType}: ${node.isValidationSuccessful ? '✓' : '✗'}`);
7});

Key Differences from v4

Migration Considerations

From v3 to v4

• Breaking Changes: Schema structure differs significantly
• No Direct Migration: v3 and v4 chains are not directly compatible
• Use Case: Continue using v3 for JavaScript-first projects
• Future: v4 offers more structure and cross-platform consistency

When to Use v3

• Existing JavaScript/TypeScript projects
• React Native applications
• Need for form revision type
• Mature, stable implementation required
• Quick prototyping and development

When to Use v4

• New projects requiring maximum interoperability
• Need for formal schema validation
• Rust or multi-language environments
• WASM compilation for web
• Template-based data structures

Community and Support

• GitHub: aqua-verifier-js-lib
• Issues: Report bugs and request features on GitHub
• Documentation: Examples in /examples directory

Next Steps

• Concepts - Core concepts and terminology
• Tooling - SDK usage and API reference
• Schema Reference - Detailed revision specifications
• Examples - Code examples

Version History

• 3.2.1: Current stable release
• 3.2.0: React Native support added
• 3.1.x: Performance improvements
• 3.0.0: Major release with TypeScript rewrite

For detailed changelog, see the GitHub releases.