SDK

Software Development Kit for Aqua Protocol integration

Getting Started with Aqua Protocol SDK

Installation

npm install aqua-js-sdk

Basic Concepts

The Aqua Protocol SDK provides a system for file notarization and verification using three main operations:

Notarization

Creating a genesis revision for your file

Signing

Adding cryptographic signatures using various methods

Witnessing

Recording the file state on different platforms

Verification

Validating the authenticity of files

Quick Start

Using the Chainable API (Recommended)

import { AquafierChainable } from 'aqua-js-sdk';

// Prepare your file object
const fileObject = {
  name: "document.pdf",
  hash: "0x...", // File hash
  content: "..." // Optional file content
};

// Create credentials (example for MetaMask)
const credentials = {
  mnemonic: "",      // For CLI signing
  nostr_sk: "",      // For Nostr witnessing
  did_key: "",       // For DID signing
  alchemy_key: "",   // For Ethereum operations
  witness_eth_network: "sepolia",
  witness_method: "metamask"
};

// Create and process your file
const aqua = new AquafierChainable(null);
const result = await aqua
  .notarize(fileObject)
  .sign("metamask", credentials)
  .witness("eth", "sepolia", "metamask", credentials)
  .verify();

// Get results
const tree = result.getValue();
const logs = result.getLogs();

Using the Standard API

import { Aquafier } from 'aqua-js-sdk';

const aqua = new Aquafier();

// Create genesis revision
const genesis = await aqua.createGenesisRevision(fileObject);

// Sign the tree
const signed = await aqua.signAquaTree(genesis.data.aquaTree, "metamask", credentials);

// Witness the tree
const witnessed = await aqua.witnessAquaTree(
  signed.data.aquaTree,
  "eth",
  "sepolia",
  "metamask",
  credentials
);

// Verify the tree
const verified = await aqua.verifyAquaTree(witnessed.data.aquaTree, [fileObject]);

Next Steps

Core Concepts

Read about Core Concepts to understand the system better

Common Use Cases

Check out Common Use Cases for practical examples

API Reference

Review the API Reference for detailed documentation

Quickstart Guide

Get started with our comprehensive quickstart guide

SDK Features

Chainable API

The chainable API provides a fluent interface for building Aqua operations:

const result = await aqua
  .notarize(fileObject)           // Create genesis revision
  .sign("metamask", credentials)  // Add signature
  .witness("eth", "sepolia", "metamask", credentials)  // Add witness
  .verify();                     // Verify the complete tree

Standard API

The standard API provides individual methods for each operation:

// Step-by-step approach
const genesis = await aqua.createGenesisRevision(fileObject);
const signed = await aqua.signAquaTree(genesis.data.aquaTree, "metamask", credentials);
const witnessed = await aqua.witnessAquaTree(signed.data.aquaTree, "eth", "sepolia", "metamask", credentials);
const verified = await aqua.verifyAquaTree(witnessed.data.aquaTree, [fileObject]);

Credentials Configuration

The SDK supports multiple authentication methods:

MetaMask

Browser-based wallet integration for web applications

CLI Signing

Command-line interface with mnemonic-based signing

DID Keys

Decentralized identity key management

Nostr

Nostr protocol integration for witnessing

Supported Networks

Ethereum Mainnet

Production network for mainnet witnessing

Sepolia Testnet

Test network for development and testing

Nostr

Decentralized social protocol for witnessing

TSA RFC3161

Timestamp authority for cryptographic timestamps

Error Handling

The SDK provides comprehensive error handling and logging:

try {
  const result = await aqua
    .notarize(fileObject)
    .sign("metamask", credentials)
    .witness("eth", "sepolia", "metamask", credentials)
    .verify();
    
  // Success
  const tree = result.getValue();
  const logs = result.getLogs();
  
} catch (error) {
  // Handle errors
  console.error('Aqua operation failed:', error.message);
  
  // Get detailed logs
  const logs = result.getLogs();
  console.log('Operation logs:', logs);
}

Best Practices

Follow these best practices for optimal SDK usage:

• Use the chainable API for simple workflows
• Handle errors gracefully with try-catch blocks
• Validate credentials before making operations
• Use appropriate networks (testnet for development, mainnet for production)
• Store sensitive credentials securely (environment variables, secure vaults)
• Monitor operation logs for debugging and auditing

Advanced Usage

Custom File Objects

const customFileObject = {
  name: "contract.sol",
  hash: "0x1234567890abcdef...",
  content: "pragma solidity ^0.8.0; ...",
  metadata: {
    type: "smart-contract",
    version: "1.0.0",
    author: "[e-mail]"
  }
};

Batch Operations

// Process multiple files
const files = [file1, file2, file3];
const results = await Promise.all(
  files.map(file => 
    aqua.notarize(file).sign("metamask", credentials).verify()
  )
);

Custom Witnessing

// Custom witness configuration
const customCredentials = {
  alchemy_key: "your-alchemy-key",
  witness_eth_network: "mainnet",
  witness_method: "metamask",
  custom_witness_options: {
    gas_limit: 100000,
    gas_price: "20000000000"
  }
};