> ## Documentation Index
> Fetch the complete documentation index at: https://aquaprotocol.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

> [!NOTE]
>
> This process ensures that the document existed at a specific point in time and hasn't been modified since.

## Getting Started

### Clone the Repository

```bash theme={null}
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:

```bash theme={null}
npm install
```

Build the project:

```bash theme={null}
npm run build
```

## Usage

### 1. Notarizing, Signing, and Witnessing

#### Basic Notarization

```bash theme={null}
./notarize.js <FILE_PATH>
```

#### Signing Files

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

```bash theme={null}
./notarize.js --sign [cli|metamask|did] <FILE_PATH>
```

#### Witnessing Files

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

```bash theme={null}
./notarize.js [--witness eth|--witness nostr|--witness tsa] <FILE_PATH>
```

#### Multiple Chain Witnessing

Witness multiple AQUA chains:

```bash theme={null}
./notarize.js FILE1,FILE2 --witness eth --vtree --type sepolia
```

Witness specific revisions:

```bash theme={null}
./notarize.js FILE1@0x_revision_,FILE2@0x_revision_ --witness eth --type cli --vtree
```

### 2. Verification

#### Basic Verification

```bash theme={null}
./verify.js <AQUA_CHAIN_FILE_PATH>
```

#### Verification Options

Verbose output:

```bash theme={null}
./verify.js <FILE_PATH>.aqua.json -v
```

Skip merkle proof verification (faster):

```bash theme={null}
./verify.js <FILE_PATH>.aqua.json --ignore-merkle-proof
```

### 3. Managing Revisions

#### Delete Last Revision

```bash theme={null}
./notarize.js --remove <FILE_PATH>
```

#### Link AQUA Chains

Link one AQUA chain to another:

```bash theme={null}
./notarize.js <FILE_PATH> --link <TARGET_FILE_PATH.aqua.json>
```

### 4. Content Management

#### Generate Content Revision

```bash theme={null}
./notarize.js --content <FILE_PATH>
```

#### Generate Scalar Revision

```bash theme={null}
./notarize.js --scalar <FILE_PATH>
```

### 5. Forms Management

#### Create Genesis Form

```bash theme={null}
./notarize.js example-form.json --form example-form.json
```

> [!NOTE]
>
> For genesis, the filename must match the form name.

#### Create Form Revision

```bash theme={null}
./notarize.js <FILE_PATH> --form example-form.json
```

#### Update Forms

Delete a form entry:

```bash theme={null}
./form_updater.js example-form.json.aqua.json@<revision> --delete <field>
```

Update/restore a form entry:

```bash theme={null}
./form_updater.js example-form.json.aqua.json --update <form_field> <value>
```

> [!NOTE]
>
> 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](https://github.com/inblockio/aqua-cheques)\
**WAVs Gateway:** [wavs-demos](https://github.com/inblockio/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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

> [card] 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.

> [card] 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):**

```bash theme={null}
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:

```json theme={null}
{
  "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)

> [card] Aqua Library
>
> Integrate the Rust-based Aqua API for offline verification (see aqua-cheques).

> [card] WAVs Setup
>
> Deploy a WAVs instance or use an existing one. Ensure it can:
>
> * Accept JSON submissions.
> * Run Aqua verification.
> * Trigger the smart contract.

> [card] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.