Mutant: Decentralized P2P Mutable Key-Value Storage forAutonomi

Table of Contents

Core Concepts

Installation

curl https://raw.githubusercontent.com/Champii/Mutant/refs/heads/master/install.sh| bash

Quick start demo

$> mutant get -p a420224971527d61ce6ee21d850a07c243498c95808697e8fac23f461545656933016697d10b805c0fa26b50eb3532b2 daily_meme.jpg

Command-Line Interface (CLI)

$> mutant --help

Usage: mutant [OPTIONS] [COMMAND]Commands:  put           Store a value associated with a key  get           Retrieve a value associated with a key  rm            Remove a key-value pair  ls            List stored keys  stats         Show storage statistics  tasks         Manage background tasks  daemon        Manage the daemon  sync          Synchronize local index cache with remote storage  purge         Perform a get check on scratchpads that should have been created but failed at some point. Removes the pads that are not found.  import        Import scratchpad private key from a file  export        Export all scratchpad private key to a file  health-check  Perform a health check on scratchpads that should have been created but cannot be retrieved. Recycles the pads that are not found.  help          Print this message or the help of the given subcommand(s)Options:  -q, --quiet    Suppress progress bar output  -h, --help     Print help  -V, --version  Print version

Store/fetch private data

# Store a the file `data.txt` under the name `mykey`$> mutant put mykey data.txt# Get a value and save to a file$> mutant get mykey fetched_data.txt# Run operations in the background$> mutant put my_file large_file.zip --background# Remove a value$> mutant rm mykey

Store/fetch public data

# Store data publicly (no encryption) under a name$> mutant put -p my_key my_file.ext1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef# Get your own public data by name$> mutant get my_key output.txt# Get public data by address$> mutant get -p 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef output.txt# You can update public data by using the same key$> mutant put -p my_key my_updated_file.ext

Daemon and task management

# Start the daemon (happens automatically when needed)$> mutant daemon start# Check daemon status$> mutant daemon status# List background tasks$> mutant tasks list# Get details of a specific task$> mutant tasks get<task_id># Stop a running task$> mutant tasks stop<task_id>

Stats and management

# List stored keys$> mutant ls Key                   Pads       Size Status       Address/Info---------------------------------------------------------------------- dwarf                  265   1.03 GiB Ready        Private nothing_here             2   3.28 KiB Ready        Public: ac09242b5c5658dd313e37b08cba4810346bc8ce75f32d9330b20f142c941fa47a396077e91acfb990edab5430e3245 zorglub                 10 100.00 KiB 61% (6/10)   Private# List stored keys with fetch history$> mutant ls --history# Sync local index with remote storage$> mutant sync# View storage statistics$> mutant statsStorage Statistics:-------------------Total Keys: 2Total Pads Managed:    270  Occupied (Private):  267  Free Pads:           3  Pending Verify Pads: 0# Perform health check on a specific key with recycling enabled$> mutant health-check mykey --recycle

Library Usage

[dependencies]mutant-lib ="0.6.2"# Or the version you needtokio = {version ="1",features = ["full"] }

use mutant_lib::{MutAnt,MutAntConfig,Error};#[tokio::main]asyncfnmain() -> anyhow::Result<()>{// Replace with your actual private key (hex format, with or without 0x prefix)let private_key_hex ="0xYOUR_PRIVATE_KEY_HEX";letmut mutant =MutAnt::init(private_key_hex).await?;    mutant.put("greeting",b"hello world",StorageMode::Medium,false).await?;let fetched_value = mutant.get("greeting").await?;println!("Fetched value: {}",String::from_utf8_lossy(&fetched_value));    mutant.rm("greeting").await?;Ok(())}

Fetching Public Data (Keyless Initialization)

use mutant_lib::{MutAnt,Error};use mutant_lib::storage::ScratchpadAddress;use anyhow::Result;#[tokio::main]asyncfnmain() ->Result<()>{// Initialize a public fetcher instance (defaults to Mainnet)let public_fetcher =MutAnt::init_public().await?;// Assume you have the public address from elsewherelet address_hex ="...";// Replace with actual public address hexlet public_address =ScratchpadAddress::from_hex(address_hex)?;// Fetch the public datamatch public_fetcher.get_public(public_address).await{Ok(data) =>println!("Fetched public data: {} bytes", data.len()),Err(e) =>eprintln!("Failed to fetch public data: {}", e),}Ok(())}This keyless instance is optimized for fetching public data and cannot perform operations requiring a privatekey(like `put`, `rm`, `ls`, etc).###Using theDaemon andClientFor most applications, it's recommended to use the daemon architecture:```rustuse mutant_client::MutantClient;use anyhow::Result;#[tokio::main]asyncfnmain() ->Result<()>{// Connect to the daemon (must be running)letmut client =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(asyncmove{whileletOk(progress) = progress_rx.recv().await{println!("Progress: {:?}", progress);}});// Wait for the task to completelet result = start_task.await?;println!("Task completed: {:?}", result);Ok(())}

Donate