refactor: make proving-capability correct for proving

closes #576

TxProvingCapability was being used by ProofBuilder and by ProvingJob but its
variants were logically incorrect for these usages because these types only care
about NeptuneProof, not about TransactionProof variants, which
TxProvingCapability mirrored.

This commit fixes that by renaming enum TxProvingCapability to struct
VmProvingCapability which is a newtype for log2(padded_height).

Some impl<From> are added to TransactionProofType that make it easy to convert
to a VmProvingCapability and vice-versa.

capability detection is moved from cli_args::Args into
VmProvingCapability::auto_detect().  Proof-collection is now log2-padded-height
of 15, rather than 11.  This is because some tests were failing and required 15
so it is experimentally determined.

changes --tx-proving-capability to --vm-proving-capability <int>.

removes --max_log2_padded_height_for_proofs as --vm-proving-capability has the
same meaning.

removes fields proof_type and max_log2_padded_height from ProverJobSettings, as
they are no longer relevant.  proof_type makes no sense there and
max_log2_padded_height is present inside vm_proving_capability.

adds method transaction_proof_type() to TransactionProofBuilder, where it
actually does make sense.

updates tests, adds docs and examples.

Squashed:

+ removed proof_type and max_log2_padded_height from ProverJobSettings.
  Added transaction_proof_type to TransactionProofBuilder.
+ re-implemented TxProvingCapability as struct, not enum.
+ rename TxProvingCapability VmProvingCapability
+ default tx_proof_type to best proof capable of.  other misc
+ move capability auto-detection from Args into VmProvingCapability
+ ProofCollection now 15 instead of 11

Author: dan-da

scripts/php/find_slow_tests.php

@@ -0,0 +1,99 @@
+#!/usr/bin/env php
+<?php
+
+// This script is useful for finding slow unit tests.
+//
+// The script sorts the output of `cargo test` by duration of
+// each test, and then prints the results in descending order.
+//
+// It also prints stats at the bottom, eg:
+//
+// --- unit test stats ---
+// Count: 733
+// Total: 974.801
+// Min:   0.000
+// Max:   104.073
+// Mean:  1.3298785811733
+// Median: 0.118
+// ----------------------
+//
+// As of this writing, it is necessary to use the nightly compiler
+// in order to obtain timing for each test.
+//
+// Here is example usage:
+//
+// cargo +nightly test -- -Z unstable-options --report-time 2>&1 | tee tests.out
+// sort_tests.php tests.out
+
+$file = @$argv[1];
+
+if(!$file || !file_exists($file)) {
+    die("please provide a file with output of cargo test, eg:\n cargo +nightly test -- -Z unstable-options --report-time 2>&1 | tee tests.out");
+}
+
+$lines = file($file);
+
+$a = [];
+foreach($lines as $line) {
+	$fields = explode(' ', $line);
+	$key = $fields[count($fields)-1];
+	$key_new = trim(str_replace(['<', '>', 's'], '', $key));
+	if($key_new != $key && is_numeric($key_new) && substr($line, 0, 5) == "test " && !strstr($line, "finished in")) {
+		$a[$line] = $key_new;
+	} else {
+//		echo "skipping $line";
+	}
+}
+
+arsort($a);
+
+foreach($a as $line => $time) {
+	echo $line ;
+}
+
+echo "\n\n\n";
+analyze_float_array(array_values($a));
+
+
+
+function analyze_float_array(array $numbers): void {
+    if (empty($numbers)) {
+        echo "Error: The input array is empty. Cannot calculate statistics.\n";
+        return;
+    }
+
+    // --- Min and Max ---
+    $min = min($numbers);
+    $max = max($numbers);
+
+    // --- Mean (Average) ---
+    $sum = array_sum($numbers);
+    $count = count($numbers);
+    $mean = $sum / $count;
+
+    // --- Median ---
+    // 1. Sort the array numerically.
+    sort($numbers);
+
+    // 2. Determine the middle index(es).
+    $middleIndex = floor($count / 2);
+
+    if ($count % 2 === 1) {
+        // Odd number of elements: median is the middle element.
+        $median = $numbers[$middleIndex];
+    } else {
+        // Even number of elements: median is the average of the two middle elements.
+        $median = ($numbers[$middleIndex - 1] + $numbers[$middleIndex]) / 2;
+    }
+
+    // --- Print Results ---
+    echo "--- unit test stats ---\n";
+    echo "Count: " . $count . "\n";
+    echo "Total: " . $sum . "\n";
+    echo "Min:   " . $min . "\n";
+    echo "Max:   " . $max . "\n";
+    echo "Mean:  " . $mean . "\n";
+    echo "Median: " . $median . "\n";
+    echo "----------------------\n";
+}
+

src/api/export.rs

@@ -18,7 +18,7 @@ pub use crate::models::proof_abstractions::timestamp::Timestamp;
 pub use crate::models::state::transaction_details::TransactionDetails;
 pub use crate::models::state::transaction_kernel_id::TransactionKernelId;
 pub use crate::models::state::tx_creation_artifacts::TxCreationArtifacts;
-pub use crate::models::state::tx_proving_capability::TxProvingCapability;
+pub use crate::models::state::vm_proving_capability::VmProvingCapability;
 pub use crate::models::state::wallet::address::generation_address::GenerationSpendingKey;
 pub use crate::models::state::wallet::address::symmetric_key::SymmetricKey;
 pub use crate::models::state::wallet::address::KeyType;

src/api/tx_initiation/builder/mod.rs

@@ -74,18 +74,11 @@
 //!        .await?;
 //!    drop(state_lock); // release lock asap.
 //!
-//!    // use cli options for building proof, but override proof-type
-//!    let options = TritonVmProofJobOptionsBuilder::new()
-//!        .template(&gsl.cli().into())
-//!        .proof_type(TransactionProofType::PrimitiveWitness)
-//!        .build();
-//!
 //!    // generate simplistic PrimitiveWitness "proof"
 //!    // This exposes secrets, so tx cannot be broadcast until
 //!    // proof is upgraded to ProofCollection.
 //!    let proof = TransactionProofBuilder::new()
 //!        .transaction_details(&tx_details)
-//!        .job_queue(vm_job_queue())
 //!        .proof_job_options(gsl.cli().into())
 //!        .build()
 //!        .await?;
@@ -127,17 +120,12 @@
 //!
 //! # async fn example(tx_details: TransactionDetails, gsl: GlobalStateLock) -> anyhow::Result<TransactionProof> {
 //!
-//! // specify target proof-type = SingleProof
-//! let options = TritonVmProofJobOptionsBuilder::new()
-//!     .template(&gsl.cli().into())
-//!     .proof_type(TransactionProofType::SingleProof)
-//!     .build();
-//!
 //! // This will take minutes even on a very powerful machine.
 //! let proof = TransactionProofBuilder::new()
 //!     .transaction_details(&tx_details)
+//!     .transaction_proof_type(TransactionProofType::SingleProof)
 //!     .job_queue(vm_job_queue())
-//!     .proof_job_options(options)
+//!     .proof_job_options(gsl.cli().into())
 //!     .build()
 //!     .await?;
 //! # Ok(proof)

src/api/tx_initiation/builder/proof_builder.rs

@@ -196,18 +196,11 @@ impl<'a> ProofBuilder<'a> {
         // building a real proof.
         let nondeterminism = nondeterminism_callback();
 
-        let proof_type = proof_job_options.job_settings.proof_type;
-        let capability = proof_job_options.job_settings.tx_proving_capability;
-        if !capability.can_prove(proof_type) {
-            return Err(CreateProofError::TooWeak {
-                proof_type,
-                capability,
-            });
-        }
-        // this builder only supports proofs that can be executed in triton-vm.
-        if !proof_type.executes_in_vm() {
-            return Err(CreateProofError::NotVmProof(proof_type));
-        }
+        proof_job_options
+            .job_settings
+            .vm_proving_capability
+            .check_if_capable_async(program.clone(), claim.clone(), nondeterminism.clone())
+            .await?;
 
         let job_queue = job_queue.unwrap_or_else(vm_job_queue);
 

src/api/tx_initiation/builder/transaction_proof_builder.rs

@@ -62,6 +62,7 @@ pub struct TransactionProofBuilder<'a> {
     job_queue: Option<Arc<TritonVmJobQueue>>,
     proof_job_options: Option<TritonVmProofJobOptions>,
     valid_mock: Option<bool>,
+    transaction_proof_type: Option<TransactionProofType>,
 }
 
 impl<'a> TransactionProofBuilder<'a> {
@@ -161,6 +162,14 @@ impl<'a> TransactionProofBuilder<'a> {
         self
     }
 
+    /// specify type of proof to build (optional)
+    ///
+    /// default = best proof possible based on [VmProvingCapability](crate::api::export::VmProvingCapability)
+    pub fn transaction_proof_type(mut self, transaction_proof_type: TransactionProofType) -> Self {
+        self.transaction_proof_type = Some(transaction_proof_type);
+        self
+    }
+
     /// generate the proof.
     ///
     /// ## Required (one-of)
@@ -241,16 +250,19 @@ impl<'a> TransactionProofBuilder<'a> {
             job_queue,
             proof_job_options,
             valid_mock,
+            transaction_proof_type,
         } = self;
 
         let proof_job_options = proof_job_options.ok_or(ProofRequirement::ProofJobOptions)?;
+        let transaction_proof_type = transaction_proof_type
+            .unwrap_or_else(|| proof_job_options.job_settings.vm_proving_capability.into());
 
         let valid_mock = valid_mock.unwrap_or(true);
         let job_queue = job_queue.unwrap_or_else(vm_job_queue);
 
         // note: evaluation order must match order stated in the method doc-comment.
 
-        if proof_job_options.job_settings.proof_type.is_single_proof() {
+        if transaction_proof_type.is_single_proof() {
             // claim, nondeterminism --> single proof
             if let Some((c, nd)) = claim_and_nondeterminism {
                 return gen_single(c, || nd, job_queue, proof_job_options, valid_mock).await;
@@ -284,16 +296,37 @@ impl<'a> TransactionProofBuilder<'a> {
 
         // owned primitive witness --> proof_type
         if let Some(w) = primitive_witness {
-            return from_witness(Cow::Owned(w), job_queue, proof_job_options, valid_mock).await;
+            return from_witness(
+                Cow::Owned(w),
+                job_queue,
+                proof_job_options,
+                transaction_proof_type,
+                valid_mock,
+            )
+            .await;
         }
         // primitive witness reference --> proof_type
         else if let Some(w) = primitive_witness_ref {
-            return from_witness(Cow::Borrowed(w), job_queue, proof_job_options, valid_mock).await;
+            return from_witness(
+                Cow::Borrowed(w),
+                job_queue,
+                proof_job_options,
+                transaction_proof_type,
+                valid_mock,
+            )
+            .await;
         }
         // transaction_details --> proof_type
         else if let Some(d) = transaction_details {
             let w = d.primitive_witness();
-            return from_witness(Cow::Owned(w), job_queue, proof_job_options, valid_mock).await;
+            return from_witness(
+                Cow::Owned(w),
+                job_queue,
+                proof_job_options,
+                transaction_proof_type,
+                valid_mock,
+            )
+            .await;
         }
 
         Err(ProofRequirement::TransactionProofInput.into())
@@ -333,14 +366,12 @@ async fn from_witness(
     witness_cow: Cow<'_, PrimitiveWitness>,
     job_queue: Arc<TritonVmJobQueue>,
     proof_job_options: TritonVmProofJobOptions,
+    transaction_proof_type: TransactionProofType,
     valid_mock: bool,
 ) -> Result<TransactionProof, CreateProofError> {
-    let capability = proof_job_options.job_settings.tx_proving_capability;
-    let proof_type = proof_job_options.job_settings.proof_type;
-
     // generate mock proof, if network uses mock proofs.
     if proof_job_options.job_settings.network.use_mock_proof() {
-        let proof = match proof_type {
+        let proof = match transaction_proof_type {
             TransactionProofType::PrimitiveWitness => {
                 TransactionProof::Witness(witness_cow.into_owned())
             }
@@ -356,16 +387,16 @@ async fn from_witness(
         return Ok(proof);
     }
 
-    // abort early if machine is too weak
-    if !capability.can_prove(proof_type) {
-        return Err(CreateProofError::TooWeak {
-            proof_type,
-            capability,
-        });
-    }
+    // abort early if machine is too weak.
+    //
+    // note: the fallible calls below eventually call ProofBuilder::build()
+    // which would perform a more expensive verification.  Since we know the
+    // transaction_proof_type here, we can perform this quick check.
+    let capability = proof_job_options.job_settings.vm_proving_capability;
+    capability.can_prove(transaction_proof_type)?;
 
     // produce proof of requested type
-    let transaction_proof = match proof_type {
+    let transaction_proof = match transaction_proof_type {
         TransactionProofType::PrimitiveWitness => {
             TransactionProof::Witness(witness_cow.into_owned())
         }