§MutAnt

MutAnt is a decentralized P2P mutable key-value storage system built on the Autonomi network, offering resilient, cost-efficient, and async-first storage with chunking, encryption, resumable uploads, and pad recycling.

§Why MutAnt?

Addressing on-chain storage limitations, MutAnt:

• Splits large data into scratchpad-sized chunks.
• Resumes interrupted transfers automatically.
• Recycles freed pads to reduce costs.
• Caches index locally for fast lookups and syncs remotely.
• Encrypts private data for secure storage.
• Processes operations in the background with task management.
• Adapts to business logic with pluggable backends.

§Key Highlights

• Chunk Management: Configurable pad sizes with automatic chunking and reassembly.
• Resumption & Retries: Transparent retry logic and transfer continuation.
• Cost Efficiency: Reuses freed pads to minimize redundant on-chain writes.
• Daemon Architecture: Persistent daemon process handles network connections and operations.
• Background Processing: Run operations in the background with task management.
• Public/Private Storage: Store data publicly to share with others or privately with encryption.
• Health Checks: Verify and repair stored data with automatic pad recycling.
• Flexible Interfaces: Rust SDK (mutant-lib), WebSocket client (mutant-client), and CLI tool (mutant).
• Async-First: Built ontokio andasync/await.
• Extensible Architecture: Modular design allows custom network layers.

§Ecosystem Components

MutAnt consists of several components that work together:

• mutant-lib: Core library handling chunking, encryption, and storage operations
• mutant-protocol: Shared communication format definitions
• mutant-daemon: Background service maintaining Autonomi connection
• mutant-client: WebSocket client library for communicating with the daemon
• mutant-cli: Command-line interface for end users

§Quickstart

Add toCargo.toml:

mutant-lib = "0.6.0"

usemutant_lib::MutAnt;usemutant_lib::storage::StorageMode;useanyhow::Result;#[tokio::main]async fnmain() ->Result<()> {// Use a dummy private key for doctest purposes.letkey_hex ="000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f";letmutant = MutAnt::init(key_hex).await?;// Store data with medium storage mode (2MB chunks)ant.put("file1",b"hello", StorageMode::Medium,false).await?;// Retrieve the stored dataletdata = ant.get("file1").await?;println!("Fetched: {}", String::from_utf8_lossy(&data));Ok(())}

§Fetching Public Data (without a private key)

If you only need to fetch data that was stored publicly (usingput with the public flag), you caninitialize a lightweightMutAnt instance without providing a private key:

usemutant_lib::MutAnt;usemutant_lib::storage::ScratchpadAddress;useanyhow::Result;#[tokio::main]async fnmain() ->Result<()> {// Initialize for public fetching (defaults to Mainnet)letpublic_fetcher = MutAnt::init_public().await?;// You need the public address of the data (obtained elsewhere)letpublic_address = ScratchpadAddress::from_hex("...")?;// Fetch the public dataletdata = public_fetcher.get_public(&public_address).await?;println!("Fetched public data: {} bytes", data.len());Ok(())}

Note: An instance created withinit_public canonly be used forget_public.Other operations requiring a private key (likeput,get,remove, etc.)will fail.

§Using the Daemon and Client

For most applications, it’s recommended to use the daemon architecture:

usemutant_client::MutantClient;useanyhow::Result;#[tokio::main]async fnmain() ->Result<()> {// Connect to the daemon (must be running)letmutclient = MutantClient::new();    client.connect("ws://localhost:3030/ws").await?;// Start a put operation in the backgroundlet(start_task, progress_rx) = client.put("my_key","path/to/file.txt",        mutant_protocol::StorageMode::Medium,false,// not publicfalse,// verify).await?;// Monitor progress (optional)tokio::spawn(async move{while letOk(progress) = progress_rx.recv().await{println!("Progress: {:?}", progress);        }    });// Wait for the task to completeletresult = start_task.await?;println!("Task completed: {:?}", result);Ok(())}

§Resources & Support

• API docs : https://docs.rs/mutant_lib
• CLI help :mutant --help
• Repository : https://github.com/Champii/MutAnt
• Issues : https://github.com/Champii/MutAnt/issues