Rust Client SDK - Axiom API Documentation

Overview

The Axiom Rust SDK is a library for interacting with the Axiom Proving API. It is built on top of the Axiom Proving API and provides a higher-level interface for interacting with the API. This guide covers installation, configuration, and usage of all SDK features.

Installation

Add the Axiom SDK to your Cargo.toml:

Configuration

Setting Up Your API Key

Before using the SDK, you need to configure your API key. You can do this in several ways:

Option 1: Using the CLI (Recommended)

cargo axiom register --api-key <YOUR_API_KEY>

Option 2: Manual Configuration

Create a configuration file at ~/.axiom/config.json:

{
  "api_url": "https://api.axiom.xyz/v1",
  "api_key": "your-api-key-here",
  "config_id": "your-config-id-here"
}

Option 3: Programmatic Configuration

use axiom_sdk::{AxiomSdk, AxiomConfig};

let config = AxiomConfig::new(
    "https://api.axiom.xyz/v1".to_string(),
    Some("your-api-key".to_string()),
    Some("your-config-id".to_string()),
);
let sdk = AxiomSdk::new(config);

Progress Callbacks

The SDK supports custom progress callbacks for user feedback during long-running operations:

use axiom_sdk::{AxiomSdk, ProgressCallback};

struct MyCallback;

impl ProgressCallback for MyCallback {
    fn on_success(&self, text: &str) {
        println!("✓ {}", text);
    }
    
    fn on_error(&self, text: &str) {
        eprintln!("✗ {}", text);
    }
    
    fn on_progress_start(&self, message: &str, total: Option<u64>) {
        if let Some(total) = total {
            println!("Starting: {} (total: {})", message, total);
        } else {
            println!("Starting: {}", message);
        }
    }
    
    // Implement other required methods...
    fn on_header(&self, text: &str) { println!("\n=== {} ===", text); }
    fn on_info(&self, text: &str) { println!("ℹ {}", text); }
    fn on_warning(&self, text: &str) { println!("⚠ {}", text); }
    fn on_section(&self, title: &str) { println!("\n--- {} ---", title); }
    fn on_field(&self, key: &str, value: &str) { println!("{}: {}", key, value); }
    fn on_status(&self, text: &str) { print!("\r{}", text); }
    fn on_progress_update(&self, current: u64) { print!("\rProgress: {}", current); }
    fn on_progress_update_message(&self, message: &str) { print!("\r{}", message); }
    fn on_progress_finish(&self, message: &str) { println!("\r{}", message); }
    fn on_clear_line(&self) { print!("\r\x1b[K"); }
    fn on_clear_line_and_reset(&self) { print!("\r\x1b[K"); }
}

// Use your custom callback
let config = load_config()?;
let sdk = AxiomSdk::new(config).with_callback(MyCallback);

Building Programs

The BuildSdk trait provides functionality for building OpenVM guest programs on Axiom’s cloud infrastructure.

Basic Build

use axiom_sdk::build::{BuildSdk, BuildArgs, ConfigSource};
use std::path::Path;

let program_dir = Path::new("./my-openvm-guest-program");
let args = BuildArgs {
    config_source: None, // Use default config
    bin: None, // Auto-detect binary
    keep_tarball: Some(false),
    exclude_files: None,
    include_dirs: None,
    project_id: None,
    project_name: Some("My Project".to_string()),
};

let program_id = sdk.register_new_program(program_dir, args)?;
println!("Build started with program ID: {}", program_id);

// Wait for completion
sdk.wait_for_build_completion(&program_id)?;

Build with Custom Configuration

The SDK provides extensive customization options for program builds through the BuildArgs struct. This allows you to fine-tune the build process, control which files are included, and manage project organization.

Configuration Source

You can specify a custom OpenVM configuration file instead of using the system default. This is useful when you need to use a specific VM configuration that differs from the standard setup, for example when using specialized VM extensions.

use axiom_sdk::build::{BuildArgs, ConfigSource};

let args = BuildArgs {
    config_source: Some(ConfigSource::ConfigPath("./openvm.toml".to_string())),
    bin: Some("my-binary".to_string()),
    keep_tarball: Some(true),
    exclude_files: Some("*.log,temp/*".to_string()),
    include_dirs: Some("assets,data".to_string()),
    project_id: Some("existing-project-id".to_string()),
    project_name: None,
};

let program_id = sdk.register_new_program("./my-program", args)?;

Binary Target Selection

When your Cargo.toml contains multiple targets (such as both a library and binary), you can specify which binary to build. This is particularly useful in workspace setups where you have multiple crates or when you want to build a specific executable target.

File Management

The build system provides granular control over which files are included or excluded from your build:

Exclude files: Use glob patterns to exclude temporary files, logs, or other build artifacts that aren’t needed for the final program. This helps reduce upload size and keeps your builds clean.
Include directories: Specify additional directories that contain resources your program needs but aren’t tracked by git. This is essential for including assets, configuration files, or data that your program requires at runtime.

Project Organization

You can control how your programs are organized by either creating new projects or adding programs to existing ones. This is useful for maintaining logical groupings of related programs or when you want to keep all your experimental builds separate from production code.

Build Artifacts

The keep_tarball option allows you to retain the source archive after upload, which can be valuable for debugging build issues or auditing what was actually included in your build.

Managing Build Artifacts

Once you’ve initiated a build, the SDK provides comprehensive tools to monitor progress, inspect results, and download the generated artifacts. This section covers the various ways to interact with your build results.

Listing and Inspecting Programs

The SDK allows you to retrieve information about all your programs, including their current status and any error messages.

// List all programs
let programs = sdk.list_programs()?;
for program in programs {
    println!("Program: {} ({})", program.name, program.id);
    println!("Status: {}", program.status);
    if let Some(error) = program.error_message {
        println!("Error: {}", error);
    }
}

Program Information Available:

Name: Human-readable identifier for your program
ID: Unique identifier used for API operations
Status: Current build state (pending, building, ready, failed)
Error Messages: Detailed error information if the build failed

Monitoring Build Status

You can check the status of a specific build to determine when it’s ready or if it has encountered any issues.

// Get specific build status
let build_status = sdk.get_build_status("program-id")?;
println!("Build status: {}", build_status.status);

Build Status Types:

Pending: Build is queued and waiting to start
Building: Build is currently in progress
Ready: Build completed successfully and artifacts are available
Failed: Build encountered an error and cannot proceed

Downloading Build Artifacts

Once a build is complete, you can download various artifacts that were generated during the build process.

// Download build artifacts
sdk.download_program("program-id", "elf")?;
sdk.download_program("program-id", "exe")?;
sdk.download_build_logs("program-id")?;

Generating Proofs

The ProveSdk trait handles proof generation for your built programs.

Basic Proof Generation

use axiom_sdk::{prove::{ProveSdk, ProveArgs}, ProofType};
use cargo_openvm::input::Input;

let args = ProveArgs {
    program_id: Some("your-program-id".to_string()),
    input: Some(Input::HexBytes("0x01".to_string())), // Bytes input
    proof_type: Some(ProofType::Stark),
};

let proof_id = sdk.generate_new_proof(args)?;
println!("Proof generation started: {}", proof_id);

// Wait for completion
sdk.wait_for_proof_completion(&proof_id)?;

Input Formats

The SDK supports multiple input formats:

use cargo_openvm::input::Input;
use std::path::PathBuf;

// Hex bytes input (must start with 0x01 for bytes or 0x02 for field elements)
let hex_input = Input::HexBytes("0x01010101".to_string());

// JSON file input
let file_input = Input::FilePath(PathBuf::from("./input.json"));

// The JSON file should contain:
// {
//   "input": [
//     "0x01010101",   // bytes
//     "0x02123456"    // field elements
//   ]
// }

EVM Proof Generation

let args = ProveArgs {
    program_id: Some("your-program-id".to_string()),
    input: Some(Input::FilePath(PathBuf::from("./input.json"))),
    proof_type: Some(ProofType::Evm),
};

let proof_id = sdk.generate_new_proof(args)?;
sdk.wait_for_proof_completion(&proof_id)?;

Managing Proofs

Once you’ve initiated proof generation, the SDK provides comprehensive tools to monitor progress, inspect results, and download the generated proofs. This section covers the various ways to interact with your proof generation jobs and retrieve the final artifacts.

Listing and Inspecting Proofs

The SDK allows you to retrieve information about all proofs generated for a specific program.

// List proofs for a program
let proofs = sdk.list_proofs("program-id")?;
for proof in proofs {
    println!("Proof: {} ({})", proof.id, proof.state);
    println!("Type: {}", proof.proof_type);
    if let Some(error) = proof.error_message {
        println!("Error: {}", error);
    }
}

Proof Information Available:

ID: Unique identifier for the proof generation job
State: Current status of the proof generation (pending, proving, ready, failed)
Type: The type of proof being generated (STARK or EVM)
Error Messages: Detailed error information if the proof generation failed

Downloading Proof Artifacts

Once proof generation is complete, you can download the generated proofs in various formats. The SDK provides flexibility in how and where you save these artifacts.

// Download proof artifacts
use std::path::PathBuf;

sdk.get_generated_proof("proof-id", &ProofType::Stark, None)?; // Auto path
sdk.get_generated_proof(
    "proof-id", 
    &ProofType::Evm, 
    Some(PathBuf::from("./my-proof.json"))
)?; // Custom path

// Download proof logs
sdk.get_proof_logs("proof-id")?;

Running Programs

The RunSdk trait allows you to execute programs without generating proofs, useful for testing and debugging.

Basic Execution

use axiom_sdk::run::{RunSdk, RunArgs};
use cargo_openvm::input::Input;

let args = RunArgs {
    program_id: Some("your-program-id".to_string()),
    input: Some(Input::HexBytes("0x01010101".to_string())),
};

let execution_id = sdk.execute_program(args)?;
println!("Execution started: {}", execution_id);

// Wait for completion
sdk.wait_for_execution_completion(&execution_id)?;

Handling Execution Results

// Get execution status
let execution = sdk.get_execution_status("execution-id")?;
println!("Status: {}", execution.status);

if let Some(cycles) = execution.total_cycle {
    println!("Total cycles: {}", cycles);
}

if let Some(ticks) = execution.total_tick {
    println!("Total ticks: {}", ticks);
}

if let Some(public_values) = &execution.public_values {
    println!("Public values: {}", serde_json::to_string_pretty(public_values)?);
}

// Save results to file
if let Some(results_path) = sdk.save_execution_results(&execution) {
    println!("Results saved to: {}", results_path);
}

Verifying Proofs

The VerifySdk trait provides proof verification capabilities.

EVM Proof Verification

use axiom_sdk::verify::VerifySdk;
use std::path::PathBuf;

let proof_path = PathBuf::from("./evm-proof.json");
let verify_id = sdk.verify_evm(None, proof_path)?; // Use default config
println!("Verification started: {}", verify_id);

// Wait for completion
sdk.wait_for_evm_verify_completion(&verify_id)?;

Custom Configuration for EVM Verification

let verify_id = sdk.verify_evm(
    Some("custom-config-id"), 
    PathBuf::from("./proof.json")
)?;

STARK Proof Verification

let proof_path = PathBuf::from("./stark-proof.json");
let verify_id = sdk.verify_stark("program-id", proof_path)?;
sdk.wait_for_stark_verify_completion(&verify_id)?;

Configuration Management

The ConfigSdk trait provides access to VM configurations and related artifacts.

Getting Configuration Metadata

use axiom_sdk::config::ConfigSdk;

let metadata = sdk.get_vm_config_metadata(None)?; // Use default config
println!("OpenVM Version: {}", metadata.openvm_version);
println!("Status: {}", metadata.status);
println!("Active: {}", metadata.active);

// Get specific config
let metadata = sdk.get_vm_config_metadata(Some("config-id"))?;

Downloading Configuration Artifacts

use std::path::PathBuf;

// Download EVM verifier contract
sdk.get_evm_verifier(None, None)?; // Auto path
sdk.get_evm_verifier(
    Some("config-id"), 
    Some(PathBuf::from("./verifier.json"))
)?; // Custom path

// Download VM commitment
sdk.get_vm_commitment(None, None)?;

// Download configuration file
sdk.download_config(None, None)?;

Working with Proving Keys

// Get proving key downloader
let pk_downloader = sdk.get_proving_keys(None, "app_pk")?;

// Download with default callback
pk_downloader.download_pk("./app_pk")?;

// Download with custom callback
struct MyCallback;
impl ProgressCallback for MyCallback {
    // ... implement methods
}

pk_downloader.download_pk_with_callback("./app_pk", &MyCallback)?;

Project Management

The ProjectSdk trait helps organize your programs into projects.

Creating and Managing Projects

use axiom_sdk::projects::ProjectSdk;

// Create a new project
let project = sdk.create_project("My New Project")?;
println!("Created project: {}", project.id);

// List projects
let projects = sdk.list_projects(Some(1), Some(20))?; // page 1, 20 items
for project in projects.items {
    println!("Project: {} ({})", project.name, project.id);
    println!("Programs: {}", project.program_count);
    println!("Total proofs: {}", project.total_proofs_run);
}

// Get specific project
let project = sdk.get_project("project-id")?;
println!("Project: {}", project.name);

Managing Project Programs

// List programs in a project
let programs = sdk.list_project_programs("project-id", None, None)?;
for program in programs.items {
    println!("Program: {} in project {}", program.id, program.project_name);
}

// Move program to different project
sdk.move_program_to_project("program-id", "new-project-id")?;

Troubleshooting

This section covers common issues you may encounter when using the Axiom Rust Client SDK, along with detailed solutions and preventive measures. 1. CLI not initialized Error

# Solution: Register your API key
cargo axiom register --api-key <YOUR_API_KEY>

2. API key not valid or inactive Error

Check that your API key is correct
Verify your API key is active in the Axiom dashboard
Ensure you’re using the correct API endpoint

3. Not in a git repository Error

Ensure your program directory is in a git repository
Make sure Cargo.toml and Cargo.lock are tracked by git

4. Build Failures

// Download build logs for debugging
sdk.download_build_logs(&program_id)?;

5. Input Validation Errors

Hex strings must start with 0x01 (bytes) or 0x02 (field elements)
JSON input files must have an "input" array
All input values must be valid hex strings

API Reference

Core Types

AxiomSdk: Main SDK struct
AxiomConfig: Configuration for API endpoint, key, and default config ID
ProgressCallback: Trait for handling progress events
NoopCallback: Silent progress callback implementation

Traits

BuildSdk: Program building functionality
ProveSdk: Proof generation functionality
RunSdk: Program execution functionality
VerifySdk: Proof verification functionality
ConfigSdk: Configuration management functionality
ProjectSdk: Project management functionality

Enums

ProofType: Evm or Stark
ConfigSource: ConfigId(String) or ConfigPath(String)

Using the API

REST APIs

SDKs

Support and Configuration

Documentation Index

​Overview

​Installation

​Configuration

​Setting Up Your API Key

​Option 1: Using the CLI (Recommended)

​Option 2: Manual Configuration

​Option 3: Programmatic Configuration

​Progress Callbacks

​Building Programs

​Basic Build

​Build with Custom Configuration

​Configuration Source

​Binary Target Selection

​File Management

​Project Organization

​Build Artifacts

​Managing Build Artifacts

​Listing and Inspecting Programs

​Monitoring Build Status

​Downloading Build Artifacts

​Generating Proofs

​Basic Proof Generation

​Input Formats

​EVM Proof Generation

​Managing Proofs

​Listing and Inspecting Proofs

​Downloading Proof Artifacts

​Running Programs

​Basic Execution

​Handling Execution Results

​Verifying Proofs

​EVM Proof Verification

​Custom Configuration for EVM Verification

​STARK Proof Verification

​Configuration Management

​Getting Configuration Metadata

​Downloading Configuration Artifacts

​Working with Proving Keys

​Project Management

​Creating and Managing Projects

​Managing Project Programs

​Troubleshooting

​API Reference

​Core Types

​Traits

​Enums