We provide a Cargo-based CLI paralleling the OpenVM CLI to make it easier to work with the Axiom Proving API while developing and deploying a guest program.

​
Installation and Authentication

The Axiom Proving API currently requires building from source using the following commands:

cargo install --locked --git https://github.com/axiom-crypto/axiom-api-cli.git --tag v0.3.0 cargo-axiom

You can verify the installation afterwards by listing available commands using:

cargo axiom --help

To authenticate with the Axiom Proving API, run

cargo axiom init --api-key <API_KEY>

The API key can be passed in directly or by setting the AXIOM_API_KEY environment variable in a .env file.

AXIOM_API_KEY=<API_KEY>

Note that cargo axiom init should be run in the directory containing the .env file.

Throughout the CLI, --config-id is optional and defaults to the system default config id.

​
Downloading VM Configs

​
cargo axiom keygen download --config-id <ID> --key-type <TYPE>

This command allows users to download proving keys for different VM configurations. At present, only a single ID is supported, and the possible options for TYPE are:

  • app_vm: Proving key for application VM.
  • leaf_vm: Proving key for leaf VM.
  • internal_vm: Proving key for internal aggregation VM.
  • root_verifier: Proving key for root verifier VM.
  • halo2_outer: Proving key for outer halo2 verifier.
  • halo2_wrapper: Proving key for final halo2 verifier.
  • app_vm_commit: The application VM commitment for the given VM configuration, as bytes.
  • evm_verifier: The EVM verifier for the given VM configuration, as a .json file.
  • config: The complete config as a .toml file.

For proving keys, the response will be a download URL because the key files are large. For the smaller app_vm_commit, evm_verifier, and config types, the response will be a direct file download.

​
Building Programs

​
cargo axiom build --config-id <ID>

This command allows users to register programs to be proven on the Axiom Proving API. The requirements on the directory structure are:

  • It must be a git repository, and the required local files must be tracked by git
  • Both Cargo.toml and Cargo.lock must be present and tracked by git
  • This command must be run in the guest program directory so we know which binary is the guest program.
  • There can only be one binary target under the guest program directory.

This command will first pre-fetch all dependencies and then upload dependencies and files tracked by git to the Axiom Proving API. If your program needs some additional files that are not tracked by git, you can specify the --include_dirs flag to include them. Note that the value of --include_dirs should be relative to the git repository root (despite the fact that the command is run in the guest program directory).

​
cargo axiom build status --program-id <ID>

This command allows users to check on the status of the reproducible OpenVM build triggered by cargo axiom build.

​
cargo axiom build logs --program-id <ID>

Download the log files of the build process.

​
cargo axiom build download --program-id <ID> --program-type <TYPE>

This command allows users to download the program artifacts for the given program ID. The accepted values for TYPE are: elf, and exe.

​
cargo axiom build list

List the programs that are accessible by the API key.

​
Generating Proofs

​
cargo axiom prove --program-id <ID> --input <INPUT>

This command allows users to request proofs for the registered program with ID with input INPUT. The INPUT field needs to either be a single hex string or a file path to a JSON file that contains the key input and an array of hex strings. If your hex string represents a single number, it should be written in little-endian format (as this is what OpenVM expects). In addition, if you need multiple input streams, only the file path option is supported. Each hex string (either in the JSON file or as direct input) is either:

  • A hex string of bytes prefixed with 0x01
  • A hex string of native field elements (represented as concatenated u32 in little endian encoding) prefixed with 0x02

See the OpenVM documentation for more details.

​
cargo axiom prove status --proof-id <ID>

This command allows users to check on the status of proof generation for proof ID.

​
cargo axiom prove logs --proof-id <ID>

This command allows users to download proof logs.

​
cargo axiom prove download --proof-id <ID> --type <TYPE> --output <FILE>

This command allows users to download proof artifacts from a proving job identified by ID. The command TYPE identifies the artifact type and FILE identifies the output directory. The possible options for TYPE are:

  • stark: The final STARK proof generated by OpenVM.
  • evm: The halo2 proof ready for EVM verification.

​
cargo axiom prove list --program-id <ID>

List the proofs that are run for the given program ID.

​
Verifying Proofs

​
cargo axiom verify --config-id <ID> --proof <FILE>

This command is a convenience which allows users to verify OpenVM proofs. The VM configuration is identified by ID and the proof should be in FILE.

​
cargo axiom verify status --verify-id <ID>

This command allows users to check the status of a verification request identified by ID.