From 4689c59f3e35157d9c2ba3e429a999e90d2fe816 Mon Sep 17 00:00:00 2001 From: str4d Date: Fri, 15 Jul 2022 00:22:31 +0100 Subject: [PATCH] Improve bundlecache documentation Co-authored-by: Daira Hopwood --- src/rust/src/orchard_ffi.rs | 7 ++++--- src/rust/src/sapling.rs | 17 +++++++++++++++++ 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/src/rust/src/orchard_ffi.rs b/src/rust/src/orchard_ffi.rs index 6ec479e63..1c198e6ba 100644 --- a/src/rust/src/orchard_ffi.rs +++ b/src/rust/src/orchard_ffi.rs @@ -238,9 +238,10 @@ pub extern "C" fn orchard_batch_validate(batch: *mut BatchValidator) -> bool { let vk = unsafe { crate::ORCHARD_VK.as_ref() }.expect("ORCHARD_VK should have been initialized"); if batch.validator.validate(vk, OsRng) { - // `Self::validate()` is only called if every `Self::check_bundle()` - // returned `true`, so at this point every bundle that was added to - // `inner.queued_entries` has valid authorization. + // `BatchValidator::validate()` is only called if every + // `BatchValidator::check_bundle()` returned `true`, so at this point + // every bundle that was added to `inner.queued_entries` has valid + // authorization. orchard_bundle_validity_cache_mut().insert(batch.queued_entries); true } else { diff --git a/src/rust/src/sapling.rs b/src/rust/src/sapling.rs index 5ed35e561..9c25628fc 100644 --- a/src/rust/src/sapling.rs +++ b/src/rust/src/sapling.rs @@ -364,6 +364,10 @@ impl BatchValidator { /// it fails other consensus rules. /// /// `sighash` must be for the transaction this bundle is within. + /// + /// If this batch was configured to not cache the results, then if the bundle was in + /// the global bundle validity cache, it will have been removed (and this method will + /// return `true`). #[allow(clippy::boxed_local)] fn check_bundle(&mut self, bundle: Box, sighash: [u8; 32]) -> bool { if let Some(inner) = &mut self.0 { @@ -395,6 +399,19 @@ impl BatchValidator { } } + /// Batch-validates the accumulated bundles. + /// + /// Returns `true` if every proof and signature in every bundle added to the batch + /// validator is valid, or `false` if one or more are invalid. No attempt is made to + /// figure out which of the accumulated bundles might be invalid; if that information + /// is desired, construct separate [`BatchValidator`]s for sub-batches of the bundles. + /// + /// This method MUST NOT be called if any prior call to `Self::check_bundle` returned + /// `false`. + /// + /// If this batch was configured to cache the results, then if this method returns + /// `true` every bundle added to the batch will have also been added to the global + /// bundle validity cache. fn validate(&mut self) -> bool { if let Some(inner) = self.0.take() { if inner.validator.validate(