valida_vm_api_linux_x86/

lib.rs

//! # Valida VM API
//!
//! Lita’s Valida zk-VM stack sets a new standard in zero-knowledge proving,
//! leading in speed, efficiency, modularity and development productivity.
//!
//! See [Valida documentation](https://lita.gitbook.io/lita-documentation)
//!
//! This crate is a wrapper around `valida` executable and facilitates
//! usage of `valida` by providing Rust API for
//! running, proving and verification of Valida programs.
//!
//! Two examples are attached.
//! The first one proves `program1`. The other one proves `program2`.
//! Their sources and prebuilt versions are included in the crate
//! in the folder `test_data`.
//!
//! `program1` reads an integer from stdin, increments it and prints result to stdout.
//!
//! `program2` just unconditionally terminates execution with `__valida_builtin_fail()`.
//!
//! **IMPORTANT**
//!
//! Before copying the examples change `valida_vm_api` to
//! `valida-vm-api-linux-x86` / `valida-vm-api-linux-arm` in use declarations
//!
//! # Example 1
//!
//! ```
//! use valida_vm_api::*;
//! use tempfile::NamedTempFile;
//! use tmpfile_helper::*;
//! use std::fs;
//! use std::path::Path;
//! use std::default;
//!
//! let program = Path::new("test_data").join("program1");
//!
//! let valida = create_valida().unwrap();
//!
//! // stdin is an ASCII representation of character 'a'
//! let stdin = bytes_to_temp_file("a".as_bytes()).unwrap();
//! let stdout = NamedTempFile::new().unwrap();
//!
//! let run_status = valida.run(
//!     &program,
//!     stdout.as_ref(),
//!     stdin.as_ref(),
//!     Default::default(),
//!     Default::default());
//!
//! // Check that program terminated with success, i.e. STOP opcode
//! assert_eq!(run_status, RunStatus::TerminatedWithStop);
//!
//! let stdout_content = fs::read_to_string(stdout.as_ref()).unwrap();
//! // Check that stdout contains ('a' + 1)
//! assert_eq!(stdout_content, "b");
//!
//! let proof = NamedTempFile::new().unwrap();
//! let prove_status = valida.prove(
//!     &program, proof.as_ref(),
//!     stdin.as_ref(),
//!     Default::default(),
//!     Default::default(),
//!     Default::default());
//!
//! // Proving of a program that terminates with STOP opcode must succeed
//! assert_eq!(prove_status, ProveStatus::Success);
//!
//! let verify_status_correct_statement = valida.verify(
//!     &program,
//!     proof.as_ref(),
//!     stdout.as_ref(),
//!     Default::default(),
//!     Default::default(),
//!     Default::default());
//!
//! // Verification of a program that terminates with STOP opcode and outputs 'b' must succeed
//! assert_eq!(verify_status_correct_statement, VerifyStatus::Success);
//!
//! let incorrect_stdout = bytes_to_temp_file("c".as_bytes()).unwrap();
//! let verify_status_incorrect_statement = valida.verify(
//!     &program,
//!     proof.as_ref(),
//!     incorrect_stdout.as_ref(),
//!     Default::default(),
//!     Default::default(),
//!     Default::default());
//!
//! // Verification of a program that terminates with STOP opcode
//! // and outputs something else than `b` must fail
//! assert_eq!(verify_status_incorrect_statement, VerifyStatus::Failure);
//! ```
//!
//! # Example 2
//!
//! ```
//! use valida_vm_api::*;
//! use tempfile::NamedTempFile;
//! use tmpfile_helper::*;
//! use std::fs;
//! use std::path::Path;
//! use std::default;
//!
//! let program = Path::new("test_data").join("program2");
//!
//! let valida = create_valida().unwrap();
//!
//! // stdin and stdout do not matter for this program
//! let stdin = bytes_to_temp_file("".as_bytes()).unwrap();
//! let stdout = NamedTempFile::new().unwrap();
//!
//! let run_status = valida.run(
//!     &program,
//!     stdout.as_ref(),
//!     stdin.as_ref(),
//!     Default::default(),
//!     Default::default());
//!
//! // Check that program terminated with failure, i.e. FAIL opcode
//! assert_eq!(run_status, RunStatus::TerminatedWithFail);
//!
//! let proof = NamedTempFile::new().unwrap();
//! let prove_status = valida.prove(
//!     &program,
//!     proof.as_ref(),
//!     stdin.as_ref(),
//!     Default::default(),
//!     Default::default(),
//!     Default::default());
//!
//! // Proving of a program that terminates with STOP opcode may succeed
//! assert!(prove_status == ProveStatus::Success || prove_status == ProveStatus::Failure);
//!
//! let verify_status = valida.verify(
//!     &program,
//!     proof.as_ref(),
//!     stdout.as_ref(),
//!     Default::default(),
//!     Default::default(),
//!     Default::default());
//!
//! // Verification of a program that terminates with FAIL opcode must fail
//! assert_eq!(verify_status, VerifyStatus::Failure);
//! ```

use std::fs::remove_file;
use std::io::{self};
use std::path::{Path, PathBuf};
use std::process::{Command, ExitStatus, Stdio};

pub mod optional_arg;
use optional_arg::*;

mod extract_executable;
use extract_executable::*;

pub mod tmpfile_helper;

pub use tempfile;

/// The key structure that supports methods for running, proving and verification.
pub struct Valida {
    path: PathBuf,
}

#[derive(PartialEq, Eq, Debug)]
pub enum RunStatus {
    TerminatedWithStop,
    TerminatedWithFail,
    VMError,
}

#[derive(PartialEq, Eq, Debug)]
pub enum ProveStatus {
    Success,
    Failure,
    VMError,
}

#[derive(PartialEq, Eq, Debug)]
pub enum VerifyStatus {
    Success,
    Failure,
    VMError,
}

#[derive(PartialEq, Eq, Debug)]
pub enum PreprocessStatus {
    Success,
    Failure,
    VMError,
}

impl Valida {
    fn execute(
        &self,
        command: &str,
        optional_args: &[&str],
        mandatory_args: &[&str],
    ) -> std::io::Result<ExitStatus> {
        let args = [&[command], optional_args, mandatory_args];

        Command::new(self.path.as_os_str())
            .args(args.to_vec().concat())
            .stdin(Stdio::null())
            .stdout(Stdio::null())
            .status()
    }

    /// This is a wrapper for [valida run --fast](https://lita.gitbook.io/lita-documentation/quick-start/valida-zk-vm#executing-input-from-a-file)
    /// See `create_valida` documentation for example usage.
    pub fn run(
        &self,
        program: &Path,
        stdout: &Path,
        stdin: &Path,
        initial_fp: Option<InitialFp>,
        memory_backend: Option<MemoryBackend>,
    ) -> RunStatus {
        let binding = prepare_args(&[
            as_dyn_arg(&initial_fp),
            as_dyn_arg(&Some(FastMode(true))),
            as_dyn_arg(&memory_backend),
        ]);
        let optional_args: Vec<_> = binding.iter().map(String::as_str).collect();

        let status = self
            .execute(
                "run",
                &optional_args,
                &[
                    program.to_str().unwrap(),
                    stdout.to_str().unwrap(),
                    stdin.to_str().unwrap(),
                ],
            )
            .map(|t| t.code());

        match status {
            Ok(Some(code)) => match code {
                0 => RunStatus::TerminatedWithStop,
                1 => RunStatus::TerminatedWithFail,
                _ => RunStatus::VMError,
            },
            _ => RunStatus::VMError,
        }
    }

    /// This is a wrapper for [valida prove](https://lita.gitbook.io/lita-documentation/quick-start/valida-zk-vm#proving-input-from-a-file)
    /// See `create_valida` documentation for example usage.
    pub fn prove(
        &self,
        program: &Path,
        proof: &Path,
        stdin: &Path,
        proving_key: Option<ProvingKey>,
        initial_fp: Option<InitialFp>,
        memory_backend: Option<MemoryBackend>,
    ) -> ProveStatus {
        let binding = prepare_args(&[
            as_dyn_arg(&proving_key),
            as_dyn_arg(&initial_fp),
            as_dyn_arg(&memory_backend),
        ]);
        let optional_args: Vec<_> = binding.iter().map(String::as_str).collect();

        let status = self
            .execute(
                "prove",
                &optional_args,
                &[
                    program.to_str().unwrap(),
                    proof.to_str().unwrap(),
                    stdin.to_str().unwrap(),
                ],
            )
            .map(|t| t.code());

        match status {
            Ok(Some(code)) => match code {
                0 => ProveStatus::Success,
                _ => ProveStatus::Failure,
            },
            _ => ProveStatus::VMError,
        }
    }

    /// This is a wrapper for [valida verify](https://lita.gitbook.io/lita-documentation/quick-start/valida-zk-vm#verifying-a-proof)
    /// See `create_valida` documentation for example usage.
    pub fn verify(
        &self,
        program: &Path,
        proof: &Path,
        stdout: &Path,
        verifying_key: Option<VerifyingKey>,
        initial_fp: Option<InitialFp>,
        memory_backend: Option<MemoryBackend>,
    ) -> VerifyStatus {
        let binding = prepare_args(&[
            as_dyn_arg(&verifying_key),
            as_dyn_arg(&initial_fp),
            as_dyn_arg(&memory_backend),
        ]);
        let optional_args: Vec<_> = binding.iter().map(String::as_str).collect();

        let status = self
            .execute(
                "verify",
                &optional_args,
                &[
                    program.to_str().unwrap(),
                    proof.to_str().unwrap(),
                    stdout.to_str().unwrap(),
                ],
            )
            .map(|t| t.code());

        match status {
            Ok(Some(code)) => match code {
                0 => VerifyStatus::Success,
                _ => VerifyStatus::Failure,
            },
            _ => VerifyStatus::VMError,
        }
    }

    /// This is a wrapper for [valida preprocess](https://lita.gitbook.io/lita-documentation/advanced-usage/zk-vm-advanced-usage#separate-preprocessing-stage)
    pub fn preprocess(
        &self,
        program: &Path,
        name: String,
        memory_backend: Option<MemoryBackend>,
    ) -> PreprocessStatus {
        let binding = prepare_args(&[as_dyn_arg(&memory_backend)]);
        let optional_args: Vec<_> = binding.iter().map(String::as_str).collect();

        let status = self
            .execute(
                "verify",
                &optional_args,
                &[program.to_str().unwrap(), name.as_str()],
            )
            .map(|t| t.code());

        match status {
            Ok(Some(code)) => match code {
                0 => PreprocessStatus::Success,
                _ => PreprocessStatus::Failure,
            },
            _ => PreprocessStatus::VMError,
        }
    }
}

/// This function creates a wrapper for `valida` executable.
///
/// Call this function just once in your program.
/// Calling it is expensive because it extracts the bundled `valida binary`
/// and decompresses it to a temporary file.
pub fn create_valida() -> io::Result<Valida> {
    let pathbuf = extract_executable()?;

    Ok(Valida { path: pathbuf })
}

impl Drop for Valida {
    fn drop(&mut self) {
        remove_file(self.path.as_mut_os_str()).unwrap();
    }
}