feat: command to prepare deferral input

crates/cli/src/commands/deferral.rs

@@ -0,0 +1,93 @@
+use std::path::PathBuf;
+
+use axiom_sdk::{
+    AxiomSdk,
+    deferral::{DeferralPrepareArgs, DeferralSdk},
+};
+use clap::{Args, Subcommand};
+use eyre::Result;
+
+use crate::progress::CliProgressCallback;
+
+#[derive(Args, Debug)]
+pub struct DeferralCmd {
+    #[command(subcommand)]
+    command: DeferralSubcommand,
+}
+
+#[derive(Debug, Subcommand)]
+enum DeferralSubcommand {
+    /// Derive the parent-job inputs for a verify_stark deferral job from a
+    /// completed child stark proof.
+    ///
+    /// Downloads what it needs from the Axiom API (the config's openvm.toml
+    /// and agg verifying key, and the parent program's verification baseline),
+    /// verifies the child proof locally, and writes the two artifacts a parent
+    /// submission needs: the child proof re-encoded as openvm-codec bytes
+    /// (pass to `cargo axiom prove --deferred-proof`) and the parent's input
+    /// JSON body (pass to `cargo axiom prove --input`).
+    ///
+    /// The first run for a config derives its deferral commitments locally
+    /// (several CPU-minutes); the result is cached under ~/.axiom/cache/ and
+    /// reused on later runs.
+    Prepare {
+        /// The child stark proof: the JSON from
+        /// `cargo axiom prove download --type stark`, or its openvm-codec
+        /// binary encoding
+        #[clap(long, value_name = "FILE")]
+        child_proof: PathBuf,
+
+        /// The config ID (defaults to the configured config_id)
+        #[clap(long, value_name = "ID")]
+        config_id: Option<String>,
+
+        /// The PARENT program ID (the verify_stark guest the parent job will
+        /// prove)
+        #[clap(long, value_name = "ID")]
+        program_id: String,
+
+        /// Output: the child proof as openvm-codec bytes, ready for
+        /// `cargo axiom prove --deferred-proof`
+        #[clap(long, value_name = "FILE")]
+        out_child_bin: PathBuf,
+
+        /// Output: the parent submission's input JSON body, ready for
+        /// `cargo axiom prove --input`
+        #[clap(long, value_name = "FILE")]
+        out_input_json: PathBuf,
+    },
+}
+
+impl DeferralCmd {
+    pub fn run(self) -> Result<()> {
+        let config = axiom_sdk::load_config()?;
+        let sdk = AxiomSdk::new(config).with_callback(CliProgressCallback::new());
+
+        match self.command {
+            DeferralSubcommand::Prepare {
+                child_proof,
+                config_id,
+                program_id,
+                out_child_bin,
+                out_input_json,
+            } => {
+                let args = DeferralPrepareArgs {
+                    child_proof,
+                    config_id,
+                    program_id,
+                    out_child_bin: out_child_bin.clone(),
+                    out_input_json: out_input_json.clone(),
+                };
+                let input_commit = sdk.prepare_deferral(&args)?;
+                println!("input_commit: {input_commit}");
+                println!(
+                    "Submit the parent job with:\n  cargo axiom prove --program-id <parent> \
+                     --input {} --deferred-proof {}",
+                    out_input_json.display(),
+                    out_child_bin.display()
+                );
+                Ok(())
+            }
+        }
+    }
+}

crates/cli/src/commands/mod.rs

@@ -1,5 +1,6 @@
 pub mod build;
 pub mod config;
+pub mod deferral;
 pub mod init;
 pub mod projects;
 pub mod prove;
@@ -11,6 +12,7 @@ pub mod version;
 
 pub use build::BuildCmd;
 pub use config::ConfigCmd;
+pub use deferral::DeferralCmd;
 pub use init::InitCmd;
 pub use projects::ProjectsCmd;
 pub use prove::ProveCmd;

crates/cli/src/main.rs

@@ -11,8 +11,8 @@ mod formatting;
 mod progress;
 
 use commands::{
-    BuildCmd, ConfigCmd, InitCmd, ProjectsCmd, ProveCmd, RegisterCmd, RunCmd, UploadExeCmd,
-    VerifyCmd, VersionCmd,
+    BuildCmd, ConfigCmd, DeferralCmd, InitCmd, ProjectsCmd, ProveCmd, RegisterCmd, RunCmd,
+    UploadExeCmd, VerifyCmd, VersionCmd,
 };
 
 #[derive(Parser)]
@@ -49,6 +49,8 @@ enum AxiomCommands {
     Config(ConfigCmd),
     /// Verify a proof using the Axiom Verifying Service
     Verify(VerifyCmd),
+    /// Prepare deferral (verify_stark) submissions
+    Deferral(DeferralCmd),
     /// Manage projects
     Projects(ProjectsCmd),
     /// Upload pre-built VMEXE to Axiom Proving Service
@@ -151,6 +153,7 @@ fn main() {
         AxiomCommands::Run(cmd) => cmd.run(),
         AxiomCommands::Config(cmd) => cmd.run(),
         AxiomCommands::Verify(cmd) => cmd.run(),
+        AxiomCommands::Deferral(cmd) => cmd.run(),
         AxiomCommands::Projects(cmd) => cmd.run(),
         AxiomCommands::UploadExe(cmd) => cmd.run(),
         AxiomCommands::Version(cmd) => cmd.run(),

crates/sdk/Cargo.toml

@@ -24,3 +24,21 @@ url = "2.5"
 scopeguard = "1.2"
 chrono = { version = "0.4", features = ["serde"] }
 hex = "0.4"
+sha2 = "0.10"
+tempfile = "3"
+toml = "0.9"
+
+# openvm pinned to the v2.0.0 release tag, matching what the proving backend's
+# keygen runs (cloud-proving-backend/workloads_v2). stark-backend must match
+# what openvm v2.0.0 pins (also tag v2.0.0) so both resolve to one tagged
+# source. Used by the `deferral` module to derive deferral commits and the
+# verify_stark parent input client-side.
+openvm-sdk = { git = "https://github.com/openvm-org/openvm.git", default-features = false, tag = "v2.0.0", features = [
+    "parallel",
+] }
+openvm-sdk-config = { git = "https://github.com/openvm-org/openvm.git", default-features = false, tag = "v2.0.0" }
+openvm-continuations = { git = "https://github.com/openvm-org/openvm.git", default-features = false, tag = "v2.0.0" }
+openvm-verify-stark-host = { git = "https://github.com/openvm-org/openvm.git", default-features = false, tag = "v2.0.0" }
+openvm-verify-stark-circuit = { git = "https://github.com/openvm-org/openvm.git", default-features = false, tag = "v2.0.0" }
+openvm-stark-backend = { git = "https://github.com/openvm-org/stark-backend.git", default-features = false, tag = "v2.0.0" }
+openvm-stark-sdk = { git = "https://github.com/openvm-org/stark-backend.git", default-features = false, tag = "v2.0.0" }