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

# Rust Client SDK

> A reference for the Axiom Rust Client SDK.

export const AXIOM_SDK_VERSION = "v1.1.0";

## 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`:

<CodeBlock language="toml">
  {`[dependencies]
    axiom-sdk = { git = "https://github.com/axiom-crypto/axiom-api-cli.git", tag = "${AXIOM_SDK_VERSION}" }`}
</CodeBlock>

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

```bash theme={null}
cargo axiom register --api-key <YOUR_API_KEY>
```

#### Option 2: Manual Configuration

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

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

#### Option 3: Programmatic Configuration

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

```rust theme={null}
let verify_id = sdk.verify_evm(
    Some("custom-config-id"), 
    PathBuf::from("./proof.json")
)?;
```

### STARK Proof Verification

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

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

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

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

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

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

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

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