Zsa Swap Utils (#141)

This PR contains a set of additions/changes that allow ZSA Swaps to be
implemented in librustzcash:
- Adds Swap BundleType and Flag
- Adds AuthorizedWithProof trait that defines proof() method for both
Authorized and ActionGroupAuthorized
- Adds utility methods e.g. from_parts() for SwapBundle, is_empty() in
Builder
- Changes visibility of some methods e.g. dummy() for testing in
librustzcash
- Removes ActionGroup structure

Author: alexeykoren

benches/circuit.rs

@@ -8,6 +8,7 @@ use pprof::criterion::{Output, PProfProfiler};
 
 use orchard::{
     builder::{Builder, BundleType},
+    bundle::Authorization,
     circuit::{ProvingKey, VerifyingKey},
     keys::{FullViewingKey, Scope, SpendingKey},
     note::AssetBase,
@@ -86,7 +87,13 @@ fn criterion_benchmark<FL: OrchardFlavorBench>(c: &mut Criterion) {
                 .unwrap();
             assert!(bundle.verify_proof(&vk).is_ok());
             group.bench_function(BenchmarkId::new("bundle", num_recipients), |b| {
-                b.iter(|| bundle.authorization().proof().verify(&vk, &instances));
+                b.iter(|| {
+                    bundle
+                        .authorization()
+                        .proof()
+                        .unwrap()
+                        .verify(&vk, &instances)
+                });
             });
         }
     }

rustfmt.toml

@@ -0,0 +1 @@
+reorder_imports = false

src/builder.rs

@@ -75,10 +75,16 @@ impl BundleType {
         bundle_required: false,
     };
 
+    /// The default bundle with all flags enabled, including Asset Swaps.
+    pub const DEFAULT_SWAP: BundleType = BundleType::Transactional {
+        flags: Flags::ENABLED_WITH_SWAPS,
+        bundle_required: false,
+    };
+
     /// The DISABLED bundle type does not permit any bundle to be produced, and when used in the
     /// builder will prevent any spends or outputs from being added.
     pub const DISABLED: BundleType = BundleType::Transactional {
-        flags: Flags::from_parts(false, false, false),
+        flags: Flags::from_parts(false, false, false, false),
         bundle_required: false,
     };
 
@@ -654,6 +660,14 @@ impl Builder {
         }
     }
 
+    /// Returns true if the builder is empty.
+    pub fn is_empty(&self) -> bool {
+        self.spends.is_empty()
+            && self.outputs.is_empty()
+            && self.burn.is_empty()
+            && self.reference_notes.is_empty()
+    }
+
     /// Adds a note to be spent in this transaction.
     ///
     /// - `note` is a spendable note, obtained by trial-decrypting an [`Action`] using the
@@ -803,36 +817,32 @@ impl Builder {
             self.bundle_type,
             self.spends,
             self.outputs,
+            0,
             SpecificBuilderParams::BundleParams(self.burn),
         )
     }
 
     /// Builds an action group containing the given spent and output notes.
     ///
     /// The returned action group will have no proof or signatures; these can be applied with
-    /// [`ActionGroup::create_proof`] and [`ActionGroup::apply_signatures`] respectively.
+    /// [`Bundle::create_proof`] and [`Bundle::apply_signatures`] respectively.
     pub fn build_action_group<V: TryFrom<i64>>(
         self,
         rng: impl RngCore,
-        timelimit: u32,
-    ) -> Result<Option<UnauthorizedActionGroupWithMetadata<V>>, BuildError> {
+        expiry_height: u32,
+    ) -> Result<UnauthorizedBundleWithMetadata<V, OrchardZSA>, BuildError> {
         if !self.burn.is_empty() {
             return Err(BuildError::BurnNotEmptyInActionGroup);
         }
-        Ok(bundle(
+        bundle(
             rng,
             self.anchor,
             self.bundle_type,
             self.spends,
             self.outputs,
+            expiry_height,
             SpecificBuilderParams::ActionGroupParams(self.reference_notes),
-        )?
-        .map(|(action_group, metadata)| {
-            (
-                ActionGroup::from_parts(action_group, timelimit, None),
-                metadata,
-            )
-        }))
+        )
     }
 
     /// Builds a bundle containing the given spent notes and outputs along with their
@@ -1051,6 +1061,7 @@ fn build_bundle<B, R: RngCore>(
     bundle_type: BundleType,
     spends: Vec<SpendInfo>,
     outputs: Vec<OutputInfo>,
+    expiry_height: u32,
     burn: BTreeMap<AssetBase, NoteValue>,
     reference_notes: BTreeMap<AssetBase, SpendInfo>,
     specific_params: SpecificBuilderParams,
@@ -1213,6 +1224,10 @@ pub struct InProgress<P, S: InProgressSignatures> {
 
 impl<P: fmt::Debug, S: InProgressSignatures> Authorization for InProgress<P, S> {
     type SpendAuth = S::SpendAuth;
+
+    fn proof(&self) -> Option<&Proof> {
+        None
+    }
 }
 
 /// Marker for a bundle without a proof.
@@ -1302,8 +1317,8 @@ pub struct SigningMetadata {
     /// If this action is spending a dummy note, this field holds that note's spend
     /// authorizing key.
     ///
-    /// These keys are used automatically in [`Bundle<Unauthorized>::prepare`] or
-    /// [`Bundle<Unauthorized>::apply_signatures`] to sign dummy spends.
+    /// These keys are used automatically in [`Bundle<Unauthorized, _, _>::prepare`] or
+    /// [`Bundle<Unauthorized, _, _>::apply_signatures`] to sign dummy spends.
     dummy_ask: Option<SpendAuthorizingKey>,
     parts: SigningParts,
 }
@@ -1448,23 +1463,15 @@ impl<V, P: OrchardPrimitives> Bundle<InProgress<Proof, Unauthorized>, V, P> {
             })
             .finalize()
     }
-}
 
-impl<V, D: OrchardDomainCommon> Bundle<InProgress<Proof, Unauthorized>, V, D> {
-    /// Applies signatures to this action group, in order to authorize it.
+    /// Applies signatures to this bundle as an action group, in order to authorize it.
     #[allow(clippy::type_complexity)]
     pub fn apply_signatures_for_action_group<R: RngCore + CryptoRng>(
         self,
         mut rng: R,
         action_group_digest: [u8; 32],
         signing_keys: &[SpendAuthorizingKey],
-    ) -> Result<
-        (
-            redpallas::SigningKey<Binding>,
-            Bundle<ActionGroupAuthorized, V, D>,
-        ),
-        BuildError,
-    > {
+    ) -> Result<(Bundle<ActionGroupAuthorized, V, D>, SigningKey<Binding>), BuildError> {
         signing_keys
             .iter()
             .fold(
@@ -1587,20 +1594,14 @@ impl<V, D: OrchardDomainCommon> Bundle<InProgress<Proof, ActionGroupPartiallyAut
     #[allow(clippy::type_complexity)]
     pub fn finalize(
         self,
-    ) -> Result<
-        (
-            redpallas::SigningKey<Binding>,
-            Bundle<ActionGroupAuthorized, V, D>,
-        ),
-        BuildError,
-    > {
+    ) -> Result<(Bundle<ActionGroupAuthorized, V, D>, SigningKey<Binding>), BuildError> {
         let bsk = self.authorization().sigs.bsk;
         self.try_map_authorization(
             &mut (),
             |_, _, maybe| maybe.finalize(),
             |_, partial| Ok(ActionGroupAuthorized::from_parts(partial.proof)),
         )
-        .map(|bundle| (bsk, bundle))
+        .map(|bundle| (bundle, bsk))
     }
 }
 

src/bundle.rs

@@ -24,7 +24,7 @@ use memuse::DynamicUsage;
 use crate::{
     action::Action,
     address::Address,
-    bundle::commitments::{hash_bundle_auth_data, hash_bundle_txid_data},
+    bundle::commitments::{hash_bundle_auth_data, hash_bundle_txid_data, hash_action_group},
     circuit::{Instance, Proof, VerifyingKey},
     keys::{IncomingViewingKey, OutgoingViewingKey, PreparedIncomingViewingKey},
     note::{AssetBase, Note},
@@ -35,6 +35,7 @@ use crate::{
     value::{NoteValue, ValueCommitTrapdoor, ValueCommitment, ValueSum},
     Proof,
 };
+use crate::orchard_flavor::OrchardZSA;
 
 #[cfg(feature = "circuit")]
 use crate::circuit::{Instance, VerifyingKey};
@@ -77,60 +78,81 @@ pub struct Flags {
     /// If `false`,  all notes within [`Action`]s in the transaction's [`Bundle`] are
     /// guaranteed to be notes with native asset.
     zsa_enabled: bool,
+    /// Flag denoting whether Asset Swaps are enabled.
+    ///
+    /// If `false`, [`Bundle`] is guaranteed to contain only one ['ActionGroup'].
+    swaps_enabled: bool,
 }
 
 const FLAG_SPENDS_ENABLED: u8 = 0b0000_0001;
 const FLAG_OUTPUTS_ENABLED: u8 = 0b0000_0010;
 const FLAG_ZSA_ENABLED: u8 = 0b0000_0100;
-const FLAGS_EXPECTED_UNSET: u8 = !(FLAG_SPENDS_ENABLED | FLAG_OUTPUTS_ENABLED | FLAG_ZSA_ENABLED);
+const FLAG_SWAPS_ENABLED: u8 = 0b0000_1000;
+const FLAGS_EXPECTED_UNSET: u8 =
+    !(FLAG_SPENDS_ENABLED | FLAG_OUTPUTS_ENABLED | FLAG_ZSA_ENABLED | FLAG_SWAPS_ENABLED);
 
 impl Flags {
     /// Construct a set of flags from its constituent parts
     pub(crate) const fn from_parts(
         spends_enabled: bool,
         outputs_enabled: bool,
         zsa_enabled: bool,
+        swaps_enabled: bool,
     ) -> Self {
         Flags {
             spends_enabled,
             outputs_enabled,
             zsa_enabled,
+            swaps_enabled,
         }
     }
 
-    /// The flag set with both spends and outputs enabled and ZSA disabled.
+    /// The flag set with both spends and outputs enabled. ZSA and swaps are disabled.
     pub const ENABLED_WITHOUT_ZSA: Flags = Flags {
         spends_enabled: true,
         outputs_enabled: true,
         zsa_enabled: false,
+        swaps_enabled: false,
     };
 
-    /// The flags set with spends, outputs and ZSA enabled.
+    /// The flags set with spends, outputs and ZSA enabled. Swaps are disabled.
     pub const ENABLED_WITH_ZSA: Flags = Flags {
         spends_enabled: true,
         outputs_enabled: true,
         zsa_enabled: true,
+        swaps_enabled: false,
+    };
+
+    /// The flags set with spends, outputs, ZSA and swaps enabled.
+    pub const ENABLED_WITH_SWAPS: Flags = Flags {
+        spends_enabled: true,
+        outputs_enabled: true,
+        zsa_enabled: true,
+        swaps_enabled: true,
     };
 
-    /// The flag set with spends and ZSA disabled.
+    /// The flag set with spends, ZSA and swaps disabled.
     pub const SPENDS_DISABLED_WITHOUT_ZSA: Flags = Flags {
         spends_enabled: false,
         outputs_enabled: true,
         zsa_enabled: false,
+        swaps_enabled: false,
     };
 
-    /// The flag set with spends disabled and ZSA enabled.
+    /// The flag set with spends disabled and ZSA enabled. Swaps are disabled.
     pub const SPENDS_DISABLED_WITH_ZSA: Flags = Flags {
         spends_enabled: false,
         outputs_enabled: true,
         zsa_enabled: true,
+        swaps_enabled: false,
     };
 
     /// The flag set with outputs disabled and ZSA disabled.
     pub const OUTPUTS_DISABLED: Flags = Flags {
         spends_enabled: true,
         outputs_enabled: false,
         zsa_enabled: false,
+        swaps_enabled: false,
     };
 
     /// Flag denoting whether Orchard spends are enabled in the transaction.
@@ -190,6 +212,7 @@ impl Flags {
                 spends_enabled: value & FLAG_SPENDS_ENABLED != 0,
                 outputs_enabled: value & FLAG_OUTPUTS_ENABLED != 0,
                 zsa_enabled: value & FLAG_ZSA_ENABLED != 0,
+                swaps_enabled: value & FLAG_SWAPS_ENABLED != 0,
             })
         } else {
             None
@@ -201,6 +224,9 @@ impl Flags {
 pub trait Authorization: fmt::Debug {
     /// The authorization type of an Orchard action.
     type SpendAuth: fmt::Debug + Clone;
+
+    /// Return the proof component of the authorizing data.
+    fn proof(&self) -> Option<&Proof>;
 }
 
 /// A bundle of actions to be applied to the ledger.
@@ -535,6 +561,14 @@ impl Authorization for EffectsOnly {
     type SpendAuth = ();
 }
 
+impl<A: Authorization, V: Copy + Into<i64>> Bundle<A, V, OrchardZSA> {
+    /// Computes a commitment to the effects of this bundle,
+    /// assuming that the bundle represents an action group inside a swap bundle.
+    pub fn action_group_commitment(&self) -> BundleCommitment {
+        BundleCommitment(hash_action_group(self))
+    }
+}
+
 /// Authorizing data for a bundle of actions, ready to be committed to the ledger.
 #[derive(Debug, Clone)]
 pub struct Authorized {
@@ -544,6 +578,11 @@ pub struct Authorized {
 
 impl Authorization for Authorized {
     type SpendAuth = VerSpendAuthSig;
+
+    /// Return the proof component of the authorizing data.
+    fn proof(&self) -> Option<&Proof> {
+        Some(&self.proof)
+    }
 }
 
 impl Authorized {
@@ -555,11 +594,6 @@ impl Authorized {
         }
     }
 
-    /// Return the proof component of the authorizing data.
-    pub fn proof(&self) -> &Proof {
-        &self.proof
-    }
-
     /// Return the versioned binding signature.
     pub fn binding_signature(&self) -> &VerBindingSig {
         &self.binding_signature
@@ -584,6 +618,7 @@ impl<V, P: OrchardPrimitives> Bundle<Authorized, V, P> {
     pub fn verify_proof(&self, vk: &VerifyingKey) -> Result<(), halo2_proofs::plonk::Error> {
         self.authorization()
             .proof()
+            .unwrap()
             .verify(vk, &self.to_instances())
     }
 }
@@ -767,8 +802,8 @@ pub mod testing {
 
         prop_compose! {
             /// Create an arbitrary set of flags.
-            pub fn arb_flags()(spends_enabled in prop::bool::ANY, outputs_enabled in prop::bool::ANY, zsa_enabled in prop::bool::ANY) -> Flags {
-                Flags::from_parts(spends_enabled, outputs_enabled, zsa_enabled)
+            pub fn arb_flags()(spends_enabled in prop::bool::ANY, outputs_enabled in prop::bool::ANY, zsa_enabled in prop::bool::ANY, swaps_enabled in prop::bool::ANY) -> Flags {
+                Flags::from_parts(spends_enabled, outputs_enabled, zsa_enabled, swaps_enabled)
             }
         }
 
@@ -803,7 +838,7 @@ pub mod testing {
                     balances.into_iter().sum::<Result<ValueSum, _>>().unwrap(),
                     burn,
                     anchor,
-                    None,
+                    0,
                     super::EffectsOnly,
                 )
             }
@@ -836,6 +871,7 @@ pub mod testing {
                     balances.into_iter().sum::<Result<ValueSum, _>>().unwrap(),
                     burn,
                     anchor,
+                    0,
                     Authorized {
                         proof: Proof::new(fake_proof),
                         binding_signature: VerBindingSig::new(P::default_sighash_version(), sk.sign(rng, &fake_sighash)),

src/bundle/batch.rs

@@ -62,7 +62,7 @@ impl BatchValidator {
 
         bundle
             .authorization()
-            .proof()
+            .proof
             .add_to_batch(&mut self.proofs, bundle.to_instances());
     }