> ## 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.

# SDK

> Software Development Kit for Aqua Protocol integration

# Getting Started with Aqua Protocol SDK

## Installation

```bash theme={null}
npm install aqua-js-sdk
```

## Basic Concepts

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

> [card] Notarization
>
> Creating a genesis revision for your file

> [card] Signing
>
> Adding cryptographic signatures using various methods

> [card] Witnessing
>
> Recording the file state on different platforms

> [card] Verification
>
> Validating the authenticity of files

## Quick Start

### Using the Chainable API (Recommended)

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

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

> [card] [Core Concepts](https://aquaprotocol.mintlify.site/essentials/notarization.md)
>
> Read about Core Concepts to understand the system better

> [card] [Common Use Cases](https://aquaprotocol.mintlify.site/essentials/examples.md)
>
> Check out Common Use Cases for practical examples

> [card] [API Reference](https://aquaprotocol.mintlify.site/api-reference/introduction.md)
>
> Review the API Reference for detailed documentation

> [card] [Quickstart Guide](https://aquaprotocol.mintlify.site/quickstart.md)
>
> Get started with our comprehensive quickstart guide

## SDK Features

### Chainable API

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

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

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

> [card] MetaMask
>
> Browser-based wallet integration for web applications

> [card] CLI Signing
>
> Command-line interface with mnemonic-based signing

> [card] DID Keys
>
> Decentralized identity key management

> [card] Nostr
>
> Nostr protocol integration for witnessing

### Supported Networks

> [card] Ethereum Mainnet
>
> Production network for mainnet witnessing

> [card] Sepolia Testnet
>
> Test network for development and testing

> [card] Nostr
>
> Decentralized social protocol for witnessing

> [card] TSA RFC3161
>
> Timestamp authority for cryptographic timestamps

## Error Handling

The SDK provides comprehensive error handling and logging:

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

> [!NOTE]
>
> 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

```javascript theme={null}
const customFileObject = {
  name: "contract.sol",
  hash: "0x1234567890abcdef...",
  content: "pragma solidity ^0.8.0; ...",
  metadata: {
    type: "smart-contract",
    version: "1.0.0",
    author: "developer@example.com"
  }
};
```

### Batch Operations

```javascript theme={null}
// 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

```javascript theme={null}
// 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"
  }
};
```


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