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 yourCargo.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)
Option 2: Manual Configuration
Create a configuration file at~/.axiom/config.json
:
Option 3: Programmatic Configuration
Progress Callbacks
The SDK supports custom progress callbacks for user feedback during long-running operations:Building Programs
TheBuildSdk
trait provides functionality for building OpenVM guest programs on Axiom’s cloud infrastructure.
Basic Build
Build with Custom Configuration
The SDK provides extensive customization options for program builds through theBuildArgs
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.Binary Target Selection
When yourCargo.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
Thekeep_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.- 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.- 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.Generating Proofs
TheProveSdk
trait handles proof generation for your built programs.
Basic Proof Generation
Input Formats
The SDK supports multiple input formats:EVM Proof Generation
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.- 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.Running Programs
TheRunSdk
trait allows you to execute programs without generating proofs, useful for testing and debugging.
Basic Execution
Handling Execution Results
Verifying Proofs
TheVerifySdk
trait provides proof verification capabilities.
EVM Proof Verification
Custom Configuration for EVM Verification
STARK Proof Verification
Configuration Management
TheConfigSdk
trait provides access to VM configurations and related artifacts.
Getting Configuration Metadata
Downloading Configuration Artifacts
Working with Proving Keys
Project Management
TheProjectSdk
trait helps organize your programs into projects.
Creating and Managing Projects
Managing Project Programs
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
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
Not in a git repository
Error
- Ensure your program directory is in a git repository
- Make sure
Cargo.toml
andCargo.lock
are tracked by git
- Hex strings must start with
0x01
(bytes) or0x02
(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 structAxiomConfig
: Configuration for API endpoint, key, and default config IDProgressCallback
: Trait for handling progress eventsNoopCallback
: Silent progress callback implementation
Traits
BuildSdk
: Program building functionalityProveSdk
: Proof generation functionalityRunSdk
: Program execution functionalityVerifySdk
: Proof verification functionalityConfigSdk
: Configuration management functionalityProjectSdk
: Project management functionality
Enums
ProofType
:Evm
orStark
ConfigSource
:ConfigId(String)
orConfigPath(String)