15261546953

Committed 26 May 2025 04:35PM UTC coverage: 71.839% (+0.1%) from 71.731%

Build # 15261546953

Build Type

push

github

Committed by

jan-ferdinand

Commit Message

ci: Fix coverage workflow

Due to a regression (?) in the rustc compiler, the code coverage
workflow has been failing since 2025-05-20. Temporarily use a version of
nightly that is known to work, until the underlying issue has been
resolved.

Run Details

20196 of 28113 relevant lines covered (71.84%)

405411.65 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

76.39

/src/api/tx_initiation/builder/proof_builder.rs

//! This module implements a builder for neptune proofs
//!
//! A neptune proof is a mockable triton-vm proof.
use std::fmt;
use std::sync::Arc;

use crate::api::tx_initiation::error::CreateProofError;
use crate::api::tx_initiation::error::ProofRequirement;
use crate::models::blockchain::transaction::validity::neptune_proof::Proof;
use crate::models::proof_abstractions::tasm::program::prove_consensus_program;
use crate::models::proof_abstractions::tasm::program::TritonVmProofJobOptions;
use crate::triton_vm::prelude::Program;
use crate::triton_vm::proof::Claim;
use crate::triton_vm::vm::NonDeterminism;
use crate::triton_vm_job_queue::vm_job_queue;
use crate::triton_vm_job_queue::TritonVmJobQueue;

/// a builder for [Proof]
///
/// Facilitates building a proof directly from a triton-vm program, a claim, and
/// nondeterminism.
///
/// This is a lower level builder than `TransactionProofBuilder` which should
/// typically be used when initiating transactions.
///
/// Example:
///
/// ```
/// use neptune_cash::api::export::NeptuneProof;
/// use neptune_cash::api::export::GlobalStateLock;
/// use neptune_cash::api::export::Program;
/// use neptune_cash::api::export::Claim;
/// use neptune_cash::api::export::NonDeterminism;
/// use neptune_cash::api::tx_initiation::builder::proof_builder::ProofBuilder;
/// use neptune_cash::api::tx_initiation::error::CreateProofError;
/// use neptune_cash::triton_vm_job_queue::vm_job_queue;
///
/// async fn prove_claim(program: Program, claim: Claim, nondeterminism: NonDeterminism, gsl: &GlobalStateLock) -> Result<NeptuneProof, CreateProofError> {
///
///     // generate a proof
///     ProofBuilder::new()
///         .program(program)
///         .claim(claim)
///         .nondeterminism(|| nondeterminism)
///         .job_queue(vm_job_queue())
///         .proof_job_options(gsl.cli().into())
///         .build()
///         .await
/// }
/// ```
#[derive(Default)]
pub struct ProofBuilder<'a> {
    program: Option<Program>,
    claim: Option<Claim>,
    nondeterminism_callback: Option<Box<dyn FnOnce() -> NonDeterminism + Send + Sync + 'a>>,
    job_queue: Option<Arc<TritonVmJobQueue>>,
    proof_job_options: Option<TritonVmProofJobOptions>,
    valid_mock: Option<bool>,
}

impl fmt::Debug for ProofBuilder<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("ProofBuilder")
            .field("program", &self.program)
            .field("claim", &self.claim)
            // skip nondeterminism_callback
            .field("job_queue", &self.job_queue)
            .field("proof_job_options", &self.proof_job_options)
            .field("valid_mock", &self.valid_mock)
            .finish()
    }
}

impl<'a> ProofBuilder<'a> {
    /// instantiate
    pub fn new() -> Self {
        Default::default()
    }

    /// add program (required)
    pub fn program(mut self, program: Program) -> Self {
        self.program = Some(program);
        self
    }

    /// add claim (required)
    pub fn claim(mut self, claim: Claim) -> Self {
        self.claim = Some(claim);
        self
    }

    /// add nondeterminism via callback or closure (required)
    ///
    /// when build() is called, the builder will invoke the callback for real
    /// proofs but not for mock proofs.
    pub fn nondeterminism<F>(mut self, callback: F) -> Self
    where
        F: FnOnce() -> NonDeterminism + Send + Sync + 'a,
    {
        self.nondeterminism_callback = Some(Box::new(callback));
        self
    }

    /// add job queue (optional)
    ///
    /// if not provided then the process-wide [vm_job_queue()] will be used.
    pub fn job_queue(mut self, job_queue: Arc<TritonVmJobQueue>) -> Self {
        self.job_queue = Some(job_queue);
        self
    }

    /// add job options. (required)
    ///
    /// note: can be obtained via `TritonVmProofJobOptions::from(Args)`
    ///
    /// There is also `TritonVmProofJobOptionsBuilder`
    pub fn proof_job_options(mut self, proof_job_options: TritonVmProofJobOptions) -> Self {
        self.proof_job_options = Some(proof_job_options);
        self
    }

    /// create valid or invalid mock proof. (optional)
    ///
    /// default = true
    ///
    /// only applies if the network uses mock proofs, eg regtest.
    ///
    /// does not apply to TransactionProof::PrimitiveWitness
    pub fn valid_mock(mut self, valid_mock: bool) -> Self {
        self.valid_mock = Some(valid_mock);
        self
    }

    /// generate the proof.
    ///
    /// if the network uses mock proofs (eg Network::RegTest), this will return
    /// immediately with a mock [Proof].
    ///
    /// otherwise it will initiate an async job that could take many minutes.
    ///
    /// note that these jobs occur in a global (per process) job queue that only
    /// permits one VM job to process at a time.  This prevents parallel jobs
    /// from bringing the machine to its knees when each is using all available
    /// CPU cores and RAM.
    ///
    /// Given the serialized nature of the job-queue, it is possible or even likely
    /// that other jobs may precede this one.
    ///
    /// One can query the job_queue to determine how many jobs are in the queue.
    ///
    /// RegTest mode:
    ///
    /// mock proofs are used on the regtest network (only) because
    /// they can be generated instantly.
    ///
    /// External Process:
    ///
    /// Proofs are generated in the Triton VM. The proof generation occurs in a
    /// separate executable, `triton-vm-prover`, which is spawned by the
    /// job-queue for each proving job.  Only one `triton-vm-prover` process
    /// should be executing at a time for a given neptune-core instance.
    ///
    /// If the external process is killed for any reason, the proof-generation job will fail
    /// and this method will return an error.
    ///
    /// Cancellation:
    ///
    /// See [TritonVmProofJobOptions::cancel_job_rx].
    ///
    /// note that cancelling the future returned by build() will NOT cancel the
    /// job in the job-queue, as that runs in a separately spawned tokio task
    /// managed by the job-queue.
    pub async fn build(self) -> Result<Proof, CreateProofError> {
        let Self {
            program,
            claim,
            nondeterminism_callback,
            job_queue,
            proof_job_options,
            valid_mock,
        } = self;

        let program = program.ok_or(ProofRequirement::Program)?;
        let claim = claim.ok_or(ProofRequirement::Claim)?;
        let nondeterminism_callback =
            nondeterminism_callback.ok_or(ProofRequirement::NonDeterminism)?;
        let proof_job_options = proof_job_options.ok_or(ProofRequirement::ProofJobOptions)?;

        if proof_job_options.job_settings.network.use_mock_proof() {
            let proof = Proof::mock(valid_mock.unwrap_or(true));
            return Ok(proof);
        }

        // non-determinism cannot reliably be obtained for mock proofs, so
        // we invoke a callback to obtain it here only once certain we are
        // 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));
        }

        let job_queue = job_queue.unwrap_or_else(vm_job_queue);

        prove_consensus_program(program, claim, nondeterminism, job_queue, proof_job_options).await
    }
}

1	//! This module implements a builder for neptune proofs
2	//!
3	//! A neptune proof is a mockable triton-vm proof.
4	use std::fmt;
5	use std::sync::Arc;
6
7	use crate::api::tx_initiation::error::CreateProofError;
8	use crate::api::tx_initiation::error::ProofRequirement;
9	use crate::models::blockchain::transaction::validity::neptune_proof::Proof;
10	use crate::models::proof_abstractions::tasm::program::prove_consensus_program;
11	use crate::models::proof_abstractions::tasm::program::TritonVmProofJobOptions;
12	use crate::triton_vm::prelude::Program;
13	use crate::triton_vm::proof::Claim;
14	use crate::triton_vm::vm::NonDeterminism;
15	use crate::triton_vm_job_queue::vm_job_queue;
16	use crate::triton_vm_job_queue::TritonVmJobQueue;
17
18	/// a builder for [Proof]
19	///
20	/// Facilitates building a proof directly from a triton-vm program, a claim, and
21	/// nondeterminism.
22	///
23	/// This is a lower level builder than `TransactionProofBuilder` which should
24	/// typically be used when initiating transactions.
25	///
26	/// Example:
27	///
28	/// ```
29	/// use neptune_cash::api::export::NeptuneProof;
30	/// use neptune_cash::api::export::GlobalStateLock;
31	/// use neptune_cash::api::export::Program;
32	/// use neptune_cash::api::export::Claim;
33	/// use neptune_cash::api::export::NonDeterminism;
34	/// use neptune_cash::api::tx_initiation::builder::proof_builder::ProofBuilder;
35	/// use neptune_cash::api::tx_initiation::error::CreateProofError;
36	/// use neptune_cash::triton_vm_job_queue::vm_job_queue;
37	///
38	/// async fn prove_claim(program: Program, claim: Claim, nondeterminism: NonDeterminism, gsl: &GlobalStateLock) -> Result<NeptuneProof, CreateProofError> {
39	///
40	/// // generate a proof
41	/// ProofBuilder::new()
42	/// .program(program)
43	/// .claim(claim)
44	/// .nondeterminism(\|\| nondeterminism)
45	/// .job_queue(vm_job_queue())
46	/// .proof_job_options(gsl.cli().into())
47	/// .build()
48	/// .await
49	/// }
50	/// ```
51	#[derive(Default)]
52	pub struct ProofBuilder<'a> {
53	program: Option<Program>,
54	claim: Option<Claim>,
55	nondeterminism_callback: Option<Box<dyn FnOnce() -> NonDeterminism + Send + Sync + 'a>>,
56	job_queue: Option<Arc<TritonVmJobQueue>>,
57	proof_job_options: Option<TritonVmProofJobOptions>,
58	valid_mock: Option<bool>,
59	}
60
61	impl fmt::Debug for ProofBuilder<'_> {
62	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {	×
63	f.debug_struct("ProofBuilder")	×
64	.field("program", &self.program)	×
65	.field("claim", &self.claim)	×
66	// skip nondeterminism_callback	×
67	.field("job_queue", &self.job_queue)	×
68	.field("proof_job_options", &self.proof_job_options)	×
69	.field("valid_mock", &self.valid_mock)	×
70	.finish()	×
71	}	×
72	}
73
74	impl<'a> ProofBuilder<'a> {
75	/// instantiate
76	pub fn new() -> Self {	1,295✔
77	Default::default()	1,295✔
78	}	1,295✔
79
80	/// add program (required)
81	pub fn program(mut self, program: Program) -> Self {	1,295✔
82	self.program = Some(program);	1,295✔
83	self	1,295✔
84	}	1,295✔
85
86	/// add claim (required)
87	pub fn claim(mut self, claim: Claim) -> Self {	1,295✔
88	self.claim = Some(claim);	1,295✔
89	self	1,295✔
90	}	1,295✔
91
92	/// add nondeterminism via callback or closure (required)
93	///
94	/// when build() is called, the builder will invoke the callback for real
95	/// proofs but not for mock proofs.
96	pub fn nondeterminism<F>(mut self, callback: F) -> Self	1,295✔
97	where	1,295✔
98	F: FnOnce() -> NonDeterminism + Send + Sync + 'a,	1,295✔
99	{
100	self.nondeterminism_callback = Some(Box::new(callback));	1,295✔
101	self	1,295✔
102	}	1,295✔
103
104	/// add job queue (optional)
105	///
106	/// if not provided then the process-wide [vm_job_queue()] will be used.
107	pub fn job_queue(mut self, job_queue: Arc<TritonVmJobQueue>) -> Self {	1,295✔
108	self.job_queue = Some(job_queue);	1,295✔
109	self	1,295✔
110	}	1,295✔
111
112	/// add job options. (required)
113	///
114	/// note: can be obtained via `TritonVmProofJobOptions::from(Args)`
115	///
116	/// There is also `TritonVmProofJobOptionsBuilder`
117	pub fn proof_job_options(mut self, proof_job_options: TritonVmProofJobOptions) -> Self {	1,295✔
118	self.proof_job_options = Some(proof_job_options);	1,295✔
119	self	1,295✔
120	}	1,295✔
121
122	/// create valid or invalid mock proof. (optional)
123	///
124	/// default = true
125	///
126	/// only applies if the network uses mock proofs, eg regtest.
127	///
128	/// does not apply to TransactionProof::PrimitiveWitness
129	pub fn valid_mock(mut self, valid_mock: bool) -> Self {	70✔
130	self.valid_mock = Some(valid_mock);	70✔
131	self	70✔
132	}	70✔
133
134	/// generate the proof.
135	///
136	/// if the network uses mock proofs (eg Network::RegTest), this will return
137	/// immediately with a mock [Proof].
138	///
139	/// otherwise it will initiate an async job that could take many minutes.
140	///
141	/// note that these jobs occur in a global (per process) job queue that only
142	/// permits one VM job to process at a time. This prevents parallel jobs
143	/// from bringing the machine to its knees when each is using all available
144	/// CPU cores and RAM.
145	///
146	/// Given the serialized nature of the job-queue, it is possible or even likely
147	/// that other jobs may precede this one.
148	///
149	/// One can query the job_queue to determine how many jobs are in the queue.
150	///
151	/// RegTest mode:
152	///
153	/// mock proofs are used on the regtest network (only) because
154	/// they can be generated instantly.
155	///
156	/// External Process:
157	///
158	/// Proofs are generated in the Triton VM. The proof generation occurs in a
159	/// separate executable, `triton-vm-prover`, which is spawned by the
160	/// job-queue for each proving job. Only one `triton-vm-prover` process
161	/// should be executing at a time for a given neptune-core instance.
162	///
163	/// If the external process is killed for any reason, the proof-generation job will fail
164	/// and this method will return an error.
165	///
166	/// Cancellation:
167	///
168	/// See [TritonVmProofJobOptions::cancel_job_rx].
169	///
170	/// note that cancelling the future returned by build() will NOT cancel the
171	/// job in the job-queue, as that runs in a separately spawned tokio task
172	/// managed by the job-queue.
173	pub async fn build(self) -> Result<Proof, CreateProofError> {	1,295✔
174	let Self {	1,295✔
175	program,	1,295✔
176	claim,	1,295✔
177	nondeterminism_callback,	1,295✔
178	job_queue,	1,295✔
179	proof_job_options,	1,295✔
180	valid_mock,	1,295✔
181	} = self;	1,295✔
182
183	let program = program.ok_or(ProofRequirement::Program)?;	1,295✔
184	let claim = claim.ok_or(ProofRequirement::Claim)?;	1,295✔
185	let nondeterminism_callback =	1,295✔
186	nondeterminism_callback.ok_or(ProofRequirement::NonDeterminism)?;	1,295✔
187	let proof_job_options = proof_job_options.ok_or(ProofRequirement::ProofJobOptions)?;	1,295✔
188
189	if proof_job_options.job_settings.network.use_mock_proof() {	1,295✔
190	let proof = Proof::mock(valid_mock.unwrap_or(true));	×
191	return Ok(proof);	×
192	}	1,295✔
193
194	// non-determinism cannot reliably be obtained for mock proofs, so
195	// we invoke a callback to obtain it here only once certain we are
196	// building a real proof.
197	let nondeterminism = nondeterminism_callback();	1,295✔
198
199	let proof_type = proof_job_options.job_settings.proof_type;	1,295✔
200	let capability = proof_job_options.job_settings.tx_proving_capability;	1,295✔
201	if !capability.can_prove(proof_type) {	1,295✔
202	return Err(CreateProofError::TooWeak {	×
203	proof_type,	×
204	capability,	×
205	});	×
206	}	1,295✔
207	// this builder only supports proofs that can be executed in triton-vm.
208	if !proof_type.executes_in_vm() {	1,295✔
209	return Err(CreateProofError::NotVmProof(proof_type));	×
210	}	1,295✔
211
212	let job_queue = job_queue.unwrap_or_else(vm_job_queue);	1,295✔
213
214	prove_consensus_program(program, claim, nondeterminism, job_queue, proof_job_options).await	1,295✔
215	}	1,295✔
216	}

Neptune-Crypto / neptune-core / 15261546953

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous