Add ZSA circuit

CHANGELOG.md

@@ -7,6 +7,81 @@ and this project adheres to Rust's notion of
 
 ## [Unreleased]
 
+### Added
+- `orchard::note::AssetBase`, the ZSA note type identifier:
+  - `AssetBase::zatoshi`, the asset used by every Orchard note built through this crate's
+    public APIs today.
+  - `AssetBase::{from_bytes, to_bytes}`, (de)serializing an `AssetBase`.
+  - `AssetBase::is_zatoshi`, testing whether it is the zatoshi asset.
+  - `AssetBase::cv_base`, the base point used to derive a value commitment for notes of this
+    asset.
+- `orchard::Note::asset`, returning a note's `AssetBase` (currently always
+  `AssetBase::zatoshi()`).
+- `impl subtle::ConditionallySelectable for orchard::note::RandomSeed`.
+- `orchard::bundle::Flags::zsa_enabled`, the accessor for the new ZSA flag bit. No public
+  constructor can currently set it to `true`.
+- `orchard::circuit_version` module, containing `OrchardCircuitVersion` (moved out of
+  `orchard::circuit`; see Changed) with a new `OrchardCircuitVersion::ZSA` variant selecting
+  the ZSA Action circuit.
+- `orchard::value::ValueCommitment::derive_with_asset`, deriving a value commitment for an
+  arbitrary `AssetBase`.
+- `unstable-voting-circuits`-only (not covered by the crate's semver guarantees):
+  - Constants backing the new ZSA note commitment domain and split-note nullifier derivation:
+    - `orchard::constants::fixed_bases::NOTE_ZSA_COMMITMENT_PERSONALIZATION`
+    - `orchard::constants::sinsemilla::Q_NOTE_ZSA_COMMITMENT_M_GENERATOR`
+    - `orchard::constants::sinsemilla::{OrchardHashDomains::NoteZsaCommit,
+      OrchardCommitDomains::NoteZsaCommit}` variants
+    - `orchard::constants::nullifier_l` module, with the `NULLIFIER_L` constant used to derive
+      a split note's nullifier
+  - The types carrying the ZSA-specific inputs that the gadgets now take (see Changed):
+    - `orchard::circuit::derive_nullifier::ZsaNullifierParams`
+    - `orchard::circuit::note_commit::ZsaNoteCommitParams`
+
+### Changed
+- The following already-opaque public structs gained new private fields for future ZSA
+  support (none has a public accessor beyond `Note::asset`, listed under Added):
+  - `orchard::note::Note`: `asset`, `rseed_split_note`
+  - `orchard::builder::SpendInfo`: `split_flag`
+  - `orchard::builder::OutputInfo`: `asset`
+  - `orchard::circuit::Instance`: `enable_zsa`
+- `orchard::Proof::expected_proof_size` now takes an `OrchardCircuitVersion` argument, since
+  the ZSA circuit's proof size differs from the other circuit versions'.
+- `OrchardCircuitVersion` moved from `orchard::circuit::OrchardCircuitVersion` to
+  `orchard::circuit_version::OrchardCircuitVersion`. Neither it nor
+  `orchard::bundle::BundleVersion::circuit_version` (the method that returns it) require the
+  `circuit` feature anymore, so that `orchard::Proof::expected_proof_size` can take
+  an `OrchardCircuitVersion` argument without pulling in the `circuit` feature.
+- `OrchardCircuitVersion` is now `#[non_exhaustive]`: downstream crates matching on it must
+  add a wildcard arm.
+- `orchard::circuit::Circuit` no longer implements `halo2_proofs::plonk::Circuit`. It still
+  carries the witnesses of a single action, but the `plonk::Circuit` implementations now live
+  on the crate-internal `CircuitVanilla` and `CircuitZsa` types, one per circuit variation.
+  `Proof::create`, `ProvingKey::build`, and `VerifyingKey::build` dispatch to the right one
+  internally, so callers do not need to select it themselves.
+- `orchard::Note::nullifier` now implements the split-note nullifier derivation of ZIP 226: a
+  note carrying a split seed derives $\psi$ from that seed, and its nullifier is offset by
+  $\mathcal{L}^{\mathsf{Orchard}}$. No public constructor produces a note with a split seed,
+  so the nullifier of every note that can be built today is unchanged.
+- `orchard::circuit::Config` is now generic over the `halo2_gadgets` lookup-range-check
+  strategy.
+- `unstable-voting-circuits`-only (not covered by the crate's semver guarantees):
+  - `orchard::circuit::note_commit::{NoteCommitConfig, NoteCommitChip}` are now generic over the
+    same lookup-range-check strategy, and `NoteCommitChip::configure` takes an additional
+    `is_zsa_circuit: bool` argument.
+  - Three gadgets moved out of `orchard::circuit::gadget`, each into a module of its own. Their
+    behavior is unchanged, but the old paths no longer exist (paths below are relative to
+    `orchard::circuit`):
+    - `gadget::derive_nullifier` → `derive_nullifier::gadgets::derive_nullifier`, plus a trailing
+      `zsa_params: Option<ZsaNullifierParams>` argument (`None` for vanilla behavior).
+    - `gadget::commit_ivk` → `commit_ivk::gadgets::commit_ivk`, now generic over the
+      lookup-range-check strategy and the Sinsemilla chip.
+    - `gadget::note_commit` → `note_commit::gadgets::note_commit`, now generic over the
+      lookup-range-check strategy, plus a trailing
+      `zsa_params: Option<ZsaNoteCommitParams>` argument (`None` for vanilla behavior).
+  - `orchard::constants::{OrchardHashDomains, OrchardCommitDomains}` both gained a
+    `NoteZsaCommit` variant (listed under Added) and are now `#[non_exhaustive]`, so downstream
+    matches on either must add a wildcard arm.
+
 ## [0.15.5] - 2026-08-02
 
 ### Changed

Cargo.toml

@@ -112,3 +112,8 @@ debug = true
 
 [profile.bench]
 debug = true
+
+[patch.crates-io]
+sinsemilla = { git = "https://github.com/zcash/sinsemilla", rev = "aabb707e862bc3d7b803c77d14e5a771bcee3e8c" }
+halo2_gadgets = { git = "https://github.com/QED-it/halo2", rev = "62fac855a606dc81e327c5b4dfc2277e3366eebb" }
+halo2_proofs = { git = "https://github.com/QED-it/halo2", rev = "62fac855a606dc81e327c5b4dfc2277e3366eebb" }

benches/circuit.rs

@@ -9,7 +9,8 @@ use pprof::criterion::{Output, PProfProfiler};
 use orchard::{
     builder::{Builder, BundleType},
     bundle::BundleVersion,
-    circuit::{OrchardCircuitVersion, ProvingKey, VerifyingKey},
+    circuit::{ProvingKey, VerifyingKey},
+    circuit_version::OrchardCircuitVersion,
     keys::{FullViewingKey, Scope, SpendingKey},
     value::NoteValue,
     Anchor, Bundle,

benches/note_decryption.rs

@@ -2,7 +2,8 @@ use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Through
 use orchard::{
     builder::{Builder, BundleType},
     bundle::BundleVersion,
-    circuit::{OrchardCircuitVersion, ProvingKey},
+    circuit::ProvingKey,
+    circuit_version::OrchardCircuitVersion,
     keys::{FullViewingKey, PreparedIncomingViewingKey, Scope, SpendingKey},
     note_encryption::{CompactAction, OrchardDomain},
     value::NoteValue,

src/action.rs

@@ -196,7 +196,7 @@ pub(crate) mod testing {
     use crate::{
         note::{
             commitment::ExtractedNoteCommitment, nullifier::testing::arb_nullifier,
-            testing::arb_note, TransmittedNoteCiphertext,
+            testing::arb_note, AssetBase, TransmittedNoteCiphertext,
         },
         note_encryption::{OrchardDomain, OrchardNoteEncryption},
         primitives::redpallas::{self, testing::arb_valid_spendauth_keypair},
@@ -235,9 +235,11 @@ pub(crate) mod testing {
             rng_seed in prop::array::uniform32(prop::num::u8::ANY),
         ) -> Action<()> {
             let cmx = ExtractedNoteCommitment::from(note.commitment());
-            let cv_net = ValueCommitment::derive(
+            let cv_net = ValueCommitment::derive_with_asset(
                 spend_value - output_value,
-                ValueCommitTrapdoor::zero()
+                ValueCommitTrapdoor::zero(),
+                // TODO ZSA: asset should be a param, not hardcoded here
+                AssetBase::zatoshi()
             );
             let encrypted_note =
                 encrypted_note_for(note, &cv_net, &cmx, StdRng::from_seed(rng_seed));
@@ -263,9 +265,11 @@ pub(crate) mod testing {
             fake_sighash in prop::array::uniform32(prop::num::u8::ANY),
         ) -> Action<redpallas::Signature<SpendAuth>> {
             let cmx = ExtractedNoteCommitment::from(note.commitment());
-            let cv_net = ValueCommitment::derive(
+            let cv_net = ValueCommitment::derive_with_asset(
                 spend_value - output_value,
-                ValueCommitTrapdoor::zero()
+                ValueCommitTrapdoor::zero(),
+                // TODO ZSA: asset should be a param, not hardcoded here
+                AssetBase::zatoshi()
             );
 
             let encrypted_note =

src/builder.rs

@@ -17,7 +17,10 @@ use crate::{
         FullViewingKey, OutgoingViewingKey, Scope, SpendAuthorizingKey, SpendValidatingKey,
         SpendingKey,
     },
-    note::{ExtractedNoteCommitment, Note, NoteVersion, Nullifier, Rho, TransmittedNoteCiphertext},
+    note::{
+        AssetBase, ExtractedNoteCommitment, Note, NoteVersion, Nullifier, Rho,
+        TransmittedNoteCiphertext,
+    },
     note_encryption::OrchardNoteEncryption,
     primitives::redpallas::{self, Binding, SpendAuth},
     tree::{Anchor, MerklePath},
@@ -29,7 +32,8 @@ use crate::{
 use {
     crate::{
         action::Action,
-        circuit::{Circuit, Instance, OrchardCircuitVersion, ProvingKey},
+        circuit::{Circuit, Instance, ProvingKey},
+        circuit_version::OrchardCircuitVersion,
     },
     nonempty::NonEmpty,
 };
@@ -352,6 +356,9 @@ pub struct SpendInfo {
     pub(crate) scope: Scope,
     pub(crate) note: Note,
     pub(crate) merkle_path: Option<MerklePath>,
+    // If `split_flag` is true, the spend note's value is not counted in the action's `ValueSum`.
+    // TODO ZSA: `ActionInfo::value_sum` does not implement this yet.
+    pub(crate) split_flag: bool,
 }
 
 impl SpendInfo {
@@ -372,6 +379,7 @@ impl SpendInfo {
             scope,
             note,
             merkle_path: Some(merkle_path),
+            split_flag: false,
         })
     }
 
@@ -392,6 +400,7 @@ impl SpendInfo {
             scope,
             note,
             merkle_path: None,
+            split_flag: false,
         })
     }
 
@@ -410,6 +419,7 @@ impl SpendInfo {
             scope: Scope::External,
             note,
             merkle_path,
+            split_flag: false,
         }
     }
 
@@ -484,6 +494,7 @@ pub struct OutputInfo {
     ovk: Option<OutgoingViewingKey>,
     recipient: Address,
     value: NoteValue,
+    asset: AssetBase,
     memo: [u8; 512],
     note_version: NoteVersion,
     /// When set, `build` fills `enc_ciphertext` with random bytes instead of encrypting the
@@ -514,6 +525,8 @@ impl OutputInfo {
             ovk,
             recipient,
             value,
+            // TODO ZSA: asset should be a param, not hardcoded here
+            asset: AssetBase::zatoshi(),
             memo,
             note_version,
             randomized_ciphertext: false,
@@ -536,6 +549,8 @@ impl OutputInfo {
             ovk: None,
             recipient,
             value: NoteValue::ZERO,
+            // TODO ZSA: asset should be a param, not hardcoded here
+            asset: AssetBase::zatoshi(),
             memo: [0u8; 512],
             note_version,
             randomized_ciphertext: matches!(spent_scope, Scope::External),
@@ -679,7 +694,18 @@ struct ActionInfo {
 }
 
 impl ActionInfo {
+    /// # Panics
+    ///
+    /// Panics if the spent and output notes do not have the same asset. The circuit
+    /// witnesses a single `asset`, used for both note commitments and for the value
+    /// commitment, so an action cannot mix assets.
     fn new(spend: SpendInfo, output: OutputInfo, rng: impl RngCore) -> Self {
+        assert_eq!(
+            spend.note.asset(),
+            output.asset,
+            "an action's spent and output notes must have the same asset"
+        );
+
         ActionInfo {
             spend,
             output,
@@ -706,7 +732,8 @@ impl ActionInfo {
         circuit_version: OrchardCircuitVersion,
     ) -> (Action<SigningMetadata>, Circuit) {
         let v_net = self.value_sum();
-        let cv_net = ValueCommitment::derive(v_net, self.rcv.clone());
+        let cv_net =
+            ValueCommitment::derive_with_asset(v_net, self.rcv.clone(), self.spend.note.asset());
 
         let (nf_old, ak, alpha, rk) = self.spend.build(&mut rng);
         let (note, cmx, encrypted_note) = self.output.build(&cv_net, nf_old, &mut rng);
@@ -738,8 +765,11 @@ impl ActionInfo {
     }
 
     fn build_for_pczt(self, mut rng: impl RngCore) -> crate::pczt::Action {
+        // ZSA notes are not yet supported by PCZT.
+        assert_eq!(self.spend.note.asset(), AssetBase::zatoshi());
         let v_net = self.value_sum();
-        let cv_net = ValueCommitment::derive(v_net, self.rcv.clone());
+        let cv_net =
+            ValueCommitment::derive_with_asset(v_net, self.rcv.clone(), self.spend.note.asset());
 
         let spend = self.spend.into_pczt(&mut rng);
         let output = self.output.into_pczt(&cv_net, spend.nullifier, &mut rng);
@@ -1427,6 +1457,7 @@ fn build_bundle<B, R: RngCore>(
                 scope,
                 note,
                 merkle_path: Some(MerklePath::dummy(&mut rng)),
+                split_flag: false,
             };
             pairs.push((None, Some(chg_idx), spend, output));
         }
@@ -1880,7 +1911,8 @@ pub mod testing {
     use crate::{
         address::testing::arb_address,
         bundle::{Authorized, Bundle, BundleVersion, TxVersion},
-        circuit::{OrchardCircuitVersion, ProvingKey},
+        circuit::ProvingKey,
+        circuit_version::OrchardCircuitVersion,
         keys::{
             testing::arb_spending_key, FullViewingKey, Scope, SpendAuthorizingKey, SpendingKey,
         },
@@ -2166,7 +2198,8 @@ mod tests {
     use crate::{
         builder::{BundleType, SpendError},
         bundle::{Authorized, Bundle, BundleVersion, Flags, TxVersion},
-        circuit::{OrchardCircuitVersion, ProvingKey},
+        circuit::ProvingKey,
+        circuit_version::OrchardCircuitVersion,
         constants::MERKLE_DEPTH_ORCHARD,
         keys::{
             FullViewingKey, PreparedIncomingViewingKey, Scope, SpendAuthorizingKey, SpendingKey,