Quick Start

Choose Your SDK

Stable - Production-ready SDK for Node.js, Web, and React Native

Best for: Web applications, existing JavaScript projects

JavaScript/TypeScript Quick Start (v3)

Info

Prerequisites

Node.js version 19 or higher
npm, yarn, or pnpm package manager

Note

We recommend using TypeScript to enjoy type definitions and better development experience.

Install the SDK

Create a new project or add to an existing one:

Code

bash

1# Create new project (optional)
2mkdir my-aqua-project
3cd my-aqua-project
4npm init -y
5 
6# Install Aqua SDK
7npm install aqua-js-sdk
8 
9# For TypeScript projects, also install type support
10npm install --save-dev typescript @types/node

Create Your First Aqua Chain

Create a file called index.ts (or index.js):

Code

typescript

1import Aquafier, { FileObject } from 'aqua-js-sdk';
2 
3async function main() {
4    // Initialize Aquafier
5    const aquafier = new Aquafier();
6 
7    // Create a file object to notarize
8    const fileObject: FileObject = {
9        fileName: "hello.txt",
10        fileContent: "Hello, Aqua Protocol!",
11        path: "./hello.txt"
12    };
13 
14    // Create genesis revision (notarize the file)
15    console.log("Creating Aqua chain...");
16    const result = await aquafier.createGenesisRevision(fileObject);
17 
18    if (result.isOk()) {
19        console.log("✓ Success! Aqua chain created.");
20        console.log("Aqua Tree:", JSON.stringify(result.data.aquaTree, null, 2));
21 
22        // The aquaTree contains your notarized file
23        const aquaTree = result.data.aquaTree;
24        console.log("\nYou can now:");
25        console.log("- Sign this chain");
26        console.log("- Witness it on blockchain");
27        console.log("- Verify it anytime");
28    } else {
29        console.error("✗ Error:", result.error);
30    }
31}
32 
33main().catch(console.error);

Run Your Code

Code

bash

1# For TypeScript
2npx tsx index.ts
3 
4# Or compile and run
5npx tsc index.ts
6node index.js
7 
8# For plain JavaScript
9node index.js

You should see output showing your Aqua chain was created successfully!

Next: Add a Signature (Optional)

Extend your code to add a cryptographic signature:

Code

typescript

1// ... after creating genesis ...
2 
3if (result.isOk()) {
4    const aquaTree = result.data.aquaTree;
5 
6    // Sign with MetaMask (will prompt in browser)
7    const wrapper = {
8        aquaTree: aquaTree,
9        fileObject: fileObject,
10        revision: ""
11    };
12 
13    console.log("\nAdding signature...");
14    const signedResult = await aquafier.signAquaTree(
15        wrapper,
16        "metamask",  // or "cli", "did", "p12"
17        {},          // credentials
18        true         // auto-increment
19    );
20 
21    if (signedResult.isOk()) {
22        console.log("✓ Signature added!");
23    }
24}

Rust Quick Start (v4)

Info

Prerequisites

Rust 1.70 or higher
Cargo package manager

Create a New Project

Code

bash

1# Create a new Rust binary project
2cargo new my-aqua-project
3cd my-aqua-project
4 
5# Or for a library
6cargo new --lib my-aqua-lib

Add Aqua SDK Dependency

Add the Aqua SDK to your Cargo.toml:

Code

toml

1[dependencies]
2aqua-rs-sdk = { git = "https://github.com/inblockio/aqua-verifier-rs" }
3tokio = { version = "1", features = ["full"] }
4serde_json = "1.0"

Create Your First Aqua Chain

Update src/main.rs:

Code

rust

1use aqua_rs_sdk::primitives::Method;
2use aqua_rs_sdk::schema::file_data::FileData;
3use aqua_rs_sdk::Aquafier;
4use std::path::PathBuf;
5 
6#[tokio::main]
7async fn main() -> Result<(), Box<dyn std::error::Error>> {
8    println!("Creating Aqua chain...");
9 
10    // Read file content
11    let filename = "test.txt".to_string();
12    let file_content = tokio::fs::read(&filename).await?;
13 
14    // Create file data
15    let file_data = FileData::new(
16        filename.clone(),
17        file_content,
18        PathBuf::from(format!("./{}", filename)),
19    );
20 
21    // Initialize Aquafier
22    let aquafier = Aquafier::new(None, None);
23 
24    // Create genesis revision (notarize the file)
25    let result = aquafier.create_genesis_revision(file_data, Method::Scalar);
26 
27    match result {
28        Ok(tree) => {
29            println!("✓ Aqua chain created successfully!");
30            println!("{}", serde_json::to_string_pretty(&tree)?);
31 
32            println!("\nYou can now:");
33            println!("- Add a signature revision");
34            println!("- Witness on blockchain");
35            println!("- Verify the chain");
36        }
37        Err(e) => {
38            eprintln!("Error: {:#?}", e);
39        }
40    }
41 
42    Ok(())
43}

Build and Run

Code

bash

1cargo build
2cargo run

You should see confirmation that your object revision was created!

CLI Tool Quick Start

Info

Prerequisites

Rust and Cargo installed

Install the CLI

Code

bash

1# Clone and build
2git clone https://github.com/inblockio/aqua-cli-rs
3cd aqua-cli-rs
4cargo build --release
5 
6# The binary will be at target/release/aqua-cli

Verify an Aqua Chain

Code

bash

1./target/release/aqua-cli verify --file chain.aqua.json

Get Help

Code

bash

1./target/release/aqua-cli --help

See the CLI documentation for more commands.

Troubleshooting

What You've Learned

Congratulations! You've created your first Aqua chain. Here's what you accomplished:

✅ Installed an Aqua SDK (JavaScript or Rust)
✅ Created a genesis revision (notarized data)
✅ Understood the basic Aqua workflow
✅ Ready to add signatures and witnesses

Next Steps

Now that you have the basics, dive deeper into Aqua Protocol's features:

Signing Revisions

Add cryptographic signatures with RSA, Ethereum, or DID methods

Witnessing

Anchor your chains to Ethereum, TSA, or Nostr for timestamps

Linking Chains

Connect multiple Aqua Trees to build complex provenance graphs

Using Templates

Define data schemas with JSON Schema validation (v4 only)

Development Guide

Complete guide for signing methods, witnessing, and advanced usage

Schema Reference

Detailed technical specifications for all revision types

Use Cases

Explore real-world applications and implementation patterns

Examples

Browse complete working examples in multiple languages

Complete Workflow Example

Want to see the full workflow including signing and witnessing?

Check out the complete JavaScript example in the SDK repository.

Try Aquafier

Not ready to code yet? Try our web-based demo:

Aquafier Demo

Upload and notarize files through a web interface

Test Environment

Experiment safely in the development environment

Get Help

GitHub Issues

Report bugs or ask questions on GitHub

Email Support

Contact our team for assistance

Documentation

Browse comprehensive guides and references

Community

Join discussions with other developers

Ready to build?

Start with the Development Guide for detailed instructions on signing, witnessing, and advanced features.

JavaScript/TypeScript Quick Start (v3)

Info

Prerequisites

Node.js version 19 or higher
npm, yarn, or pnpm package manager

Note

We recommend using TypeScript to enjoy type definitions and better development experience.

Install the SDK

Create a new project or add to an existing one:

Code

bash

1# Create new project (optional)
2mkdir my-aqua-project
3cd my-aqua-project
4npm init -y
5 
6# Install Aqua SDK
7npm install aqua-js-sdk
8 
9# For TypeScript projects, also install type support
10npm install --save-dev typescript @types/node

Create Your First Aqua Chain

Create a file called index.ts (or index.js):

Code

typescript

1import Aquafier, { FileObject } from 'aqua-js-sdk';
2 
3async function main() {
4    // Initialize Aquafier
5    const aquafier = new Aquafier();
6 
7    // Create a file object to notarize
8    const fileObject: FileObject = {
9        fileName: "hello.txt",
10        fileContent: "Hello, Aqua Protocol!",
11        path: "./hello.txt"
12    };
13 
14    // Create genesis revision (notarize the file)
15    console.log("Creating Aqua chain...");
16    const result = await aquafier.createGenesisRevision(fileObject);
17 
18    if (result.isOk()) {
19        console.log("✓ Success! Aqua chain created.");
20        console.log("Aqua Tree:", JSON.stringify(result.data.aquaTree, null, 2));
21 
22        // The aquaTree contains your notarized file
23        const aquaTree = result.data.aquaTree;
24        console.log("\nYou can now:");
25        console.log("- Sign this chain");
26        console.log("- Witness it on blockchain");
27        console.log("- Verify it anytime");
28    } else {
29        console.error("✗ Error:", result.error);
30    }
31}
32 
33main().catch(console.error);

Run Your Code

Code

bash

1# For TypeScript
2npx tsx index.ts
3 
4# Or compile and run
5npx tsc index.ts
6node index.js
7 
8# For plain JavaScript
9node index.js

You should see output showing your Aqua chain was created successfully!

Next: Add a Signature (Optional)

Extend your code to add a cryptographic signature:

Code

typescript

1// ... after creating genesis ...
2 
3if (result.isOk()) {
4    const aquaTree = result.data.aquaTree;
5 
6    // Sign with MetaMask (will prompt in browser)
7    const wrapper = {
8        aquaTree: aquaTree,
9        fileObject: fileObject,
10        revision: ""
11    };
12 
13    console.log("\nAdding signature...");
14    const signedResult = await aquafier.signAquaTree(
15        wrapper,
16        "metamask",  // or "cli", "did", "p12"
17        {},          // credentials
18        true         // auto-increment
19    );
20 
21    if (signedResult.isOk()) {
22        console.log("✓ Signature added!");
23    }
24}

Rust Quick Start (v4)

Info

Prerequisites

Rust 1.70 or higher
Cargo package manager

Create a New Project

Code

bash

1# Create a new Rust binary project
2cargo new my-aqua-project
3cd my-aqua-project
4 
5# Or for a library
6cargo new --lib my-aqua-lib

Add Aqua SDK Dependency

Add the Aqua SDK to your Cargo.toml:

Code

toml

1[dependencies]
2aqua-rs-sdk = { git = "https://github.com/inblockio/aqua-verifier-rs" }
3tokio = { version = "1", features = ["full"] }
4serde_json = "1.0"

Create Your First Aqua Chain

Update src/main.rs:

Code

rust

1use aqua_rs_sdk::primitives::Method;
2use aqua_rs_sdk::schema::file_data::FileData;
3use aqua_rs_sdk::Aquafier;
4use std::path::PathBuf;
5 
6#[tokio::main]
7async fn main() -> Result<(), Box<dyn std::error::Error>> {
8    println!("Creating Aqua chain...");
9 
10    // Read file content
11    let filename = "test.txt".to_string();
12    let file_content = tokio::fs::read(&filename).await?;
13 
14    // Create file data
15    let file_data = FileData::new(
16        filename.clone(),
17        file_content,
18        PathBuf::from(format!("./{}", filename)),
19    );
20 
21    // Initialize Aquafier
22    let aquafier = Aquafier::new(None, None);
23 
24    // Create genesis revision (notarize the file)
25    let result = aquafier.create_genesis_revision(file_data, Method::Scalar);
26 
27    match result {
28        Ok(tree) => {
29            println!("✓ Aqua chain created successfully!");
30            println!("{}", serde_json::to_string_pretty(&tree)?);
31 
32            println!("\nYou can now:");
33            println!("- Add a signature revision");
34            println!("- Witness on blockchain");
35            println!("- Verify the chain");
36        }
37        Err(e) => {
38            eprintln!("Error: {:#?}", e);
39        }
40    }
41 
42    Ok(())
43}

Build and Run

Code

bash

1cargo build
2cargo run

You should see confirmation that your object revision was created!

CLI Tool Quick Start

Info

Prerequisites

Rust and Cargo installed

Install the CLI

Code

bash

1# Clone and build
2git clone https://github.com/inblockio/aqua-cli-rs
3cd aqua-cli-rs
4cargo build --release
5 
6# The binary will be at target/release/aqua-cli

Verify an Aqua Chain

Code

bash

1./target/release/aqua-cli verify --file chain.aqua.json

Get Help

Code

bash

1./target/release/aqua-cli --help

See the CLI documentation for more commands.