CLI Tool

Command-line interface for Aqua Protocol operations

AQUA CLI Tool

The AQUA CLI tool (aqua-js-cli) is a command-line interface for interacting with the AQUA protocol. It provides functionality for notarizing, signing, witnessing, and verifying files in the AQUA system.

What is Notarization?

Notarization in AQUA is the process of creating an immutable record of a file or document on the blockchain. When you notarize a file:

• A unique hash of the file is generated
• The hash is recorded on the blockchain
• A proof of existence is created
• The file’s integrity can be verified at any time

This process ensures that the document existed at a specific point in time and hasn’t been modified since.

Getting Started

Clone the Repository

git clone https://github.com/inblockio/aqua-js-cli.git
cd aqua-js-cli

Requirements

• Node.js 14.x+ (latest version recommended)
• npm (Node Package Manager)

Installation

Install dependencies:

npm install

Build the project:

npm run build

Usage

1. Notarizing, Signing, and Witnessing

Basic Notarization

./notarize.js <FILE_PATH>

Signing Files

Sign files using different methods (cli, metamask, or did):

./notarize.js --sign [cli|metamask|did] <FILE_PATH>

Witnessing Files

Witness files using different methods (eth, nostr, or tsa):

./notarize.js [--witness eth|--witness nostr|--witness tsa] <FILE_PATH>

Multiple Chain Witnessing

Witness multiple AQUA chains:

./notarize.js FILE1,FILE2 --witness eth --vtree --type sepolia

Witness specific revisions:

./notarize.js FILE1@0x_revision_,FILE2@0x_revision_ --witness eth --type cli --vtree

2. Verification

Basic Verification

./verify.js <AQUA_CHAIN_FILE_PATH>

Verification Options

Verbose output:

./verify.js <FILE_PATH>.aqua.json -v

Skip merkle proof verification (faster):

./verify.js <FILE_PATH>.aqua.json --ignore-merkle-proof

3. Managing Revisions

Delete Last Revision

./notarize.js --remove <FILE_PATH>

Link AQUA Chains

Link one AQUA chain to another:

./notarize.js <FILE_PATH> --link <TARGET_FILE_PATH.aqua.json>

4. Content Management

Generate Content Revision

./notarize.js --content <FILE_PATH>

Generate Scalar Revision

./notarize.js --scalar <FILE_PATH>

5. Forms Management

Create Genesis Form

./notarize.js example-form.json --form example-form.json

For genesis, the filename must match the form name.

Create Form Revision

./notarize.js <FILE_PATH> --form example-form.json

Update Forms

Delete a form entry:

./form_updater.js example-form.json.aqua.json@<revision> --delete <field>

Update/restore a form entry:

./form_updater.js example-form.json.aqua.json --update <form_field> <value>

Form operations include:

• File validation for .aqua.json files
• Form key detection (exact and partial matches)
• Handling deleted fields
• Non-destructive updates preserving original structure

Use Cases

A Payment Infrastructure Prototype

This prototype implements a paper-cheque equivalent using the Aqua Protocol for offline data verification, WAVs as a gateway for distributed computation and on-chain triggers, and a smart contract to manage funds securely. It enables a sender to issue a “cheque” and a receiver to cash it out via cryptographic signatures and verification.

GitHub: aqua-cheques
WAVs Gateway: wavs-demos

Core Workflow

The system mimics a traditional cheque:

1. Sender creates a cheque with payment details.
2. Sender signs it cryptographically.
3. Receiver updates the cheque with their address and signs it.
4. The signed cheque is verified offline via Aqua and executed on-chain via WAVs.

Step-by-Step Process

1. Create the Initial Aqua Form (Sender)

The sender defines the payment in an Aqua JSON object:

{
  "sender": "0xbdc64c49bf736cfe1b8233b083d3d632f26feb27",
  "receiver": "",
  "amount": "0.3",
  "currency": "ETH"
}

• sender: Ethereum address of the payer.
• receiver: Left blank initially (filled by the receiver later).
• amount: Payment amount in the specified currency.
• currency: Token or coin type (e.g., ETH).

2. Sender Signs the Form

The sender signs the JSON using an Ethereum EIP-191 signature. This is appended to the Aqua revision history.

3. Receiver Updates the Form

The receiver adds their address to the JSON:

{
  "sender": "0xbdc64c49bf736cfe1b8233b083d3d632f26feb27",
  "receiver": "0x4a79b0d4b8feda7af5902da2d15d73a7e5fdefd4",
  "amount": "0.3",
  "currency": "ETH"
}

4. Receiver Signs the Form

The receiver signs the updated JSON, also using EIP-191, completing the cheque.

5. Verification and Execution

The signed JSON is uploaded to the WAVs gateway. WAVs runs the Aqua library (Rust API) to verify:

• Sender and receiver signatures.
• Consistency of fields (e.g., amount and currency match between revisions).

If valid, WAVs triggers the on-chain smart contract to transfer funds from the sender to the receiver.

Interface Design

The system assumes two user-facing views interacting with the WAVs gateway:

Cheque Registration

Purpose: Sender uploads the initial signed JSON.

Requirements:

• Smart contract whitelists the sender’s address to accept the cheque.
• Interface submits the JSON to the WAVs instance via an API call.

Cheque Cashout

Purpose: Receiver uploads the fully signed JSON for verification and payout.

Requirements:

• Interface submits the updated JSON to WAVs.
• WAVs verifies signatures and triggers the smart contract.

API Integration

WAVs may provide a built-in interface (TBD—cheque wavs-demos).

If not, your interface must:

• Package the JSON with signatures.
• Send it to the WAVs endpoint (e.g., POST /verify).
• Handle the response (success triggers payout; failure returns an error).

Example API Call (hypothetical):

curl -X POST https://wavs-instance.example.com/verify \
  -H "Content-Type: application/json" \
  -d '{"aqua_json": <signed_json>}'

Aqua Revisions with Signatures

Aqua tracks changes and signatures in a revision tree. Below is an example of a fully signed cheque:

{
  "revisions": {
    "0xd453ccae56945ce381f1adb57feef37ba77e215604fe078faa2d9527159c9c76": {
      "previous_verification_hash": "",
      "local_timestamp": "20250306172550",
      "revision_type": "form",
      "file_hash": "dd056a2c7c877716e2fd9f4f1aecfff05da6aae0158c0aa60775afa88cc1daf3",
      "forms_sender": "0xbdc64c49bf736cfe1b8233b083d3d632f26feb27",
      "forms_receiver": "",
      "forms_amount": "0.3",
      "forms_currency": "ETH",
      "version": "https://aqua-protocol.org/docs/v3/schema_2 | SHA256 | Method: tree"
    },
    "0x1ea148be50e98f45996353a8b2b1eb5b8e379c2bc02c18fe875e6c52bd1ccd08": {
      "previous_verification_hash": "0xd453ccae56945ce381f1adb57feef37ba77e215604fe078faa2d9527159c9c76",
      "revision_type": "signature",
      "signature": "0xd3984892d212c2613fbbea69ed669449e378f5d085326c6e2770f69e5420408515a1975a9308e058f8d33dee700b8018e372b622e8ea12934ebc0b1c1e9832f21b",
      "signature_wallet_address": "0xbdc64c49bf736cfe1b8233b083d3d632f26feb27",
      "signature_type": "ethereum:eip-191"
    },
    "0x6548c5d222c4c4382e430aff84432896ce64e5c1fb465c907a4a91a927ce4a9c": {
      "previous_verification_hash": "",
      "revision_type": "form",
      "file_hash": "00bf727b9503eeb95283eb315595a4340aae9db9abc15e77caab0a27ebb62f93",
      "forms_sender": "0xbdc64c49bf736cfe1b8233b083d3d632f26feb27",
      "forms_receiver": "0x4a79b0d4b8feda7af5902da2d15d73a7e5fdefd4",
      "forms_amount": "0.3",
      "forms_currency": "ETH"
    },
    "0x9c234109372fe09e1193f9637536eb555cfbe7803cdf17067dfad0d76fc52a86": {
      "previous_verification_hash": "0x6548c5d222c4c4382e430aff84432896ce64e5c1fb465c907a4a91a927ce4a9c",
      "revision_type": "signature",
      "signature": "0xabdacd337ae491914b6f2afb2e53249709983c3c98c54c66fcf07fed186a5fb751a6b29e1444bec134695ee01da8fc12b56d71b89df7801c49ce67f2068cc30d1b",
      "signature_wallet_address": "0x4a79b0d4b8feda7af5902da2d15d73a7e5fdefd4",
      "signature_type": "ethereum:eip-191"
    }
  },
  "tree": {
    "hash": "0x9c234109372fe09e1193f9637536eb555cfbe7803cdf17067dfad0d76fc52a86",
    "children": []
  }
}

Verification Rules

• forms_sender, forms_amount, and forms_currency must match between revisions.
• Only forms_receiver can differ (updated by the receiver).
• Signatures must validate against the respective wallet addresses.

Additional Milestones (Aqua-Dev-Team)

Aqua Library

Integrate the Rust-based Aqua API for offline verification (see aqua-cheques).

WAVs Setup

Deploy a WAVs instance or use an existing one. Ensure it can:

• Accept JSON submissions.
• Run Aqua verification.
• Trigger the smart contract.

Smart Contract

Deploy an escrow contract with:

• Whitelisting for sender addresses.
• Locking cheque amount with revision hash and amount for possible revocation.
• A cashout function triggered by WAVs.