1use core::fmt;
3use memuse::DynamicUsage;
4
5use blake2b_simd::Params as Blake2bParams;
6use ff::PrimeField;
7use group::GroupEncoding;
8use pasta_curves::pallas;
9use rand::Rng;
10use subtle::CtOption;
11
12use crate::note_encryption::NoteCiphertextBytes;
13use crate::{
14 keys::{EphemeralSecretKey, FullViewingKey, Scope, SpendingKey},
15 spec::{to_base, to_scalar, NonIdentityPallasPoint, NonZeroPallasScalar, PrfExpand},
16 value::NoteValue,
17 Address,
18};
19
20const PRF_EXPAND_PERSONALIZATION: &[u8; 16] = b"Zcash_ExpandSeed";
21const ZIP2005_ORCHARD_QR_RCM_DOMAIN_SEPARATOR: u8 = 0x0B;
22
23#[cfg(not(feature = "unstable-voting-circuits"))]
24pub(crate) mod commitment;
25#[cfg(feature = "unstable-voting-circuits")]
26pub mod commitment;
27#[cfg(any(feature = "unstable-voting-circuits", feature = "unsafe-zns"))]
28pub use self::commitment::NoteCommitTrapdoor;
29#[cfg(feature = "unsafe-zns")]
30pub use self::commitment::Psi;
31pub use self::commitment::{ExtractedNoteCommitment, NoteCommitment};
32
33#[derive(Clone, Copy, Debug, PartialEq, Eq)]
35pub enum NoteVersion {
36 V2,
41 V3,
46}
47
48impl NoteVersion {
49 pub(crate) const fn lead_byte(self) -> u8 {
51 match self {
52 Self::V2 => 0x02,
53 Self::V3 => 0x03,
54 }
55 }
56
57 pub(crate) fn from_lead_byte(b: u8) -> Option<Self> {
60 match b {
61 0x02 => Some(Self::V2),
62 0x03 => Some(Self::V3),
63 _ => None,
64 }
65 }
66}
67
68#[cfg(not(feature = "unstable-voting-circuits"))]
69pub(crate) mod nullifier;
70#[cfg(feature = "unstable-voting-circuits")]
71pub mod nullifier;
72pub use self::nullifier::Nullifier;
73
74#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
76pub struct Rho(pallas::Base);
77
78memuse::impl_no_dynamic_usage!(Rho);
80
81impl Rho {
82 pub fn from_bytes(bytes: &[u8; 32]) -> CtOption<Self> {
91 pallas::Base::from_repr(*bytes).map(Rho)
92 }
93
94 pub fn to_bytes(self) -> [u8; 32] {
96 self.0.to_repr()
97 }
98
99 #[cfg_attr(feature = "unstable-voting-circuits", visibility::make(pub))]
104 pub(crate) fn from_nf_old(nf: Nullifier) -> Self {
105 Rho(nf.inner())
106 }
107
108 #[cfg_attr(feature = "unstable-voting-circuits", visibility::make(pub))]
110 pub(crate) fn into_inner(self) -> pallas::Base {
111 self.0
112 }
113}
114
115#[derive(Copy, Clone, Debug)]
117pub struct RandomSeed([u8; 32]);
118
119impl RandomSeed {
120 pub(crate) fn random(rng: &mut impl Rng, rho: &Rho) -> Self {
121 loop {
122 let mut bytes = [0; 32];
123 rng.fill_bytes(&mut bytes);
124 let rseed = RandomSeed::from_bytes(bytes, rho);
125 if rseed.is_some().into() {
126 break rseed.unwrap();
127 }
128 }
129 }
130
131 pub fn from_bytes(rseed: [u8; 32], rho: &Rho) -> CtOption<Self> {
135 let rseed = RandomSeed(rseed);
136 let esk = rseed.esk_inner(rho);
137 CtOption::new(rseed, esk.is_some())
138 }
139
140 pub fn as_bytes(&self) -> &[u8; 32] {
142 &self.0
143 }
144
145 #[cfg_attr(feature = "unstable-voting-circuits", visibility::make(pub))]
149 pub(crate) fn psi(&self, rho: &Rho) -> pallas::Base {
150 to_base(&PrfExpand::PSI.with(&self.0, &rho.to_bytes()))
151 }
152
153 fn esk_inner(&self, rho: &Rho) -> CtOption<NonZeroPallasScalar> {
157 NonZeroPallasScalar::from_scalar(to_scalar(
158 &PrfExpand::ORCHARD_ESK.with(&self.0, &rho.to_bytes()),
159 ))
160 }
161
162 fn esk(&self, rho: &Rho) -> NonZeroPallasScalar {
166 self.esk_inner(rho).unwrap()
168 }
169
170 #[cfg_attr(feature = "unstable-voting-circuits", visibility::make(pub))]
176 pub(crate) fn rcm_v2(&self, rho: &Rho) -> commitment::NoteCommitTrapdoor {
177 commitment::NoteCommitTrapdoor(to_scalar(
178 &PrfExpand::ORCHARD_RCM.with(&self.0, &rho.to_bytes()),
179 ))
180 }
181
182 #[cfg_attr(feature = "unstable-voting-circuits", visibility::make(pub))]
206 pub(crate) fn rcm_v3(
207 &self,
208 rho: &Rho,
209 g_d: &NonIdentityPallasPoint,
210 pk_d: &NonIdentityPallasPoint,
211 value: u64,
212 psi: &pallas::Base,
213 ) -> commitment::NoteCommitTrapdoor {
214 let mut h = Blake2bParams::new()
215 .hash_length(64)
216 .personal(PRF_EXPAND_PERSONALIZATION)
217 .to_state();
218 h.update(&self.0);
220 h.update(&[ZIP2005_ORCHARD_QR_RCM_DOMAIN_SEPARATOR]);
222 h.update(&g_d.to_bytes());
224 h.update(&pk_d.to_bytes());
226 h.update(&value.to_le_bytes());
228 h.update(&rho.0.to_repr());
230 h.update(&psi.to_repr());
232
233 commitment::NoteCommitTrapdoor(to_scalar(h.finalize().as_array()))
234 }
235}
236
237#[derive(Debug, Copy, Clone)]
239pub struct Note {
240 recipient: Address,
242 value: NoteValue,
244 rho: Rho,
251 rseed: RandomSeed,
253 version: NoteVersion,
255}
256
257impl PartialEq for Note {
258 fn eq(&self, other: &Self) -> bool {
259 ExtractedNoteCommitment::from(self.commitment())
261 .eq(&ExtractedNoteCommitment::from(other.commitment()))
262 }
263}
264
265impl Eq for Note {}
266
267impl Note {
268 pub fn from_parts(
283 recipient: Address,
284 value: NoteValue,
285 rho: Rho,
286 rseed: RandomSeed,
287 version: NoteVersion,
288 ) -> CtOption<Self> {
289 let note = Note {
290 recipient,
291 value,
292 rho,
293 rseed,
294 version,
295 };
296 CtOption::new(note, note.commitment_inner().is_some())
297 }
298
299 #[cfg_attr(feature = "unstable-voting-circuits", visibility::make(pub))]
305 pub(crate) fn new(
306 recipient: Address,
307 value: NoteValue,
308 rho: Rho,
309 version: NoteVersion,
310 mut rng: impl Rng,
311 ) -> Self {
312 loop {
313 let note = Note::from_parts(
314 recipient,
315 value,
316 rho,
317 RandomSeed::random(&mut rng, &rho),
318 version,
319 );
320 if note.is_some().into() {
321 break note.unwrap();
322 }
323 }
324 }
325
326 #[cfg_attr(feature = "unstable-voting-circuits", visibility::make(pub))]
332 pub(crate) fn dummy(
333 rng: &mut impl Rng,
334 rho: Option<Rho>,
335 note_version: NoteVersion,
336 ) -> (SpendingKey, FullViewingKey, Self) {
337 let sk = SpendingKey::random(rng);
338 let fvk: FullViewingKey = (&sk).into();
339 let recipient = fvk.address_at(0u32, Scope::External);
340
341 let note = Note::new(
342 recipient,
343 NoteValue::ZERO,
344 rho.unwrap_or_else(|| Rho::from_nf_old(Nullifier::dummy(rng))),
345 note_version,
346 rng,
347 );
348
349 (sk, fvk, note)
350 }
351
352 pub fn recipient(&self) -> Address {
354 self.recipient
355 }
356
357 pub fn value(&self) -> NoteValue {
359 self.value
360 }
361
362 pub fn rseed(&self) -> &RandomSeed {
364 &self.rseed
365 }
366
367 pub(crate) fn esk(&self) -> EphemeralSecretKey {
369 EphemeralSecretKey(self.rseed.esk(&self.rho))
370 }
371
372 pub fn rho(&self) -> Rho {
374 self.rho
375 }
376
377 pub fn version(&self) -> NoteVersion {
379 self.version
380 }
381
382 pub(crate) fn psi(&self) -> pallas::Base {
384 self.rseed.psi(&self.rho())
385 }
386
387 pub(crate) fn rcm(&self) -> commitment::NoteCommitTrapdoor {
389 let rho = self.rho();
390
391 match self.version {
392 NoteVersion::V2 => self.rseed.rcm_v2(&rho),
393 NoteVersion::V3 => {
394 let g_d = self.recipient.g_d();
395 let pk_d = self.recipient.pk_d().inner();
396 let psi = self.rseed.psi(&rho);
397
398 self.rseed
399 .rcm_v3(&rho, &g_d, &pk_d, self.value.inner(), &psi)
400 }
401 }
402 }
403
404 pub fn commitment(&self) -> NoteCommitment {
410 self.commitment_inner().unwrap()
412 }
413
414 fn commitment_inner(&self) -> CtOption<NoteCommitment> {
424 let g_d = self.recipient.g_d();
425 let g_d_bytes = g_d.to_bytes();
426 let pk_d = self.recipient.pk_d().inner();
427 let pk_d_bytes = pk_d.to_bytes();
428 let psi = self.psi();
429
430 NoteCommitment::derive(
431 g_d_bytes,
432 pk_d_bytes,
433 self.value,
434 self.rho.0,
435 psi,
436 self.rcm(),
437 )
438 }
439
440 pub fn nullifier(&self, fvk: &FullViewingKey) -> Nullifier {
442 Nullifier::derive(fvk.nk(), self.rho.0, self.psi(), self.commitment())
443 }
444
445 pub(crate) fn zns_commitment(
451 &self,
452 rcm: commitment::NoteCommitTrapdoor,
453 psi: commitment::Psi,
454 ) -> CtOption<commitment::NoteCommitment> {
455 let g_d = self.recipient.g_d();
456 let g_d_bytes = g_d.to_bytes();
457 let pk_d = self.recipient.pk_d().inner();
458 let pk_d_bytes = pk_d.to_bytes();
459
460 commitment::NoteCommitment::derive(
461 g_d_bytes,
462 pk_d_bytes,
463 self.value,
464 self.rho.0,
465 psi.inner(),
466 rcm,
467 )
468 }
469
470 #[cfg(feature = "unsafe-zns")]
486 pub fn zns_cmx(
487 &self,
488 rcm: commitment::NoteCommitTrapdoor,
489 psi: commitment::Psi,
490 ) -> Option<ExtractedNoteCommitment> {
491 let cm = Option::<commitment::NoteCommitment>::from(self.zns_commitment(rcm, psi))?;
492 Some(ExtractedNoteCommitment::from(cm))
493 }
494
495 #[cfg(feature = "unsafe-zns")]
507 pub fn zns_nullifier(
508 &self,
509 fvk: &FullViewingKey,
510 rcm: commitment::NoteCommitTrapdoor,
511 psi: commitment::Psi,
512 ) -> Option<Nullifier> {
513 let cm = Option::<commitment::NoteCommitment>::from(self.zns_commitment(rcm, psi))?;
514 Some(Nullifier::derive(fvk.nk(), self.rho.0, psi.inner(), cm))
515 }
516}
517
518#[derive(Clone)]
520pub struct TransmittedNoteCiphertext {
521 pub epk_bytes: [u8; 32],
523 pub enc_ciphertext: NoteCiphertextBytes,
525 pub out_ciphertext: [u8; 80],
528}
529
530impl fmt::Debug for TransmittedNoteCiphertext {
531 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
532 f.debug_struct("TransmittedNoteCiphertext")
533 .field("epk_bytes", &self.epk_bytes)
534 .field("enc_ciphertext", &hex::encode(self.enc_ciphertext.0))
535 .field("out_ciphertext", &hex::encode(self.out_ciphertext))
536 .finish()
537 }
538}
539
540#[cfg(any(test, feature = "test-dependencies"))]
542#[cfg_attr(docsrs, doc(cfg(feature = "test-dependencies")))]
543pub mod testing {
544 use proptest::prelude::*;
545
546 use crate::{
547 address::testing::arb_address, note::nullifier::testing::arb_nullifier, value::NoteValue,
548 };
549
550 #[cfg(feature = "unsafe-zns")]
551 pub use super::commitment::testing::{arb_note_commit_trapdoor, arb_psi};
552
553 use super::{Note, NoteVersion, RandomSeed, Rho};
554
555 prop_compose! {
556 pub(crate) fn arb_rseed()(elems in prop::array::uniform32(prop::num::u8::ANY)) -> RandomSeed {
558 RandomSeed(elems)
559 }
560 }
561
562 prop_compose! {
563 pub fn arb_note(value: NoteValue, version: NoteVersion)(
565 recipient in arb_address(),
566 rho in arb_nullifier().prop_map(Rho::from_nf_old),
567 rseed in arb_rseed(),
568 ) -> Note {
569 Note {
570 recipient,
571 value,
572 rho,
573 rseed,
574 version,
575 }
576 }
577 }
578}
579
580#[cfg(test)]
581mod tests {
582 use super::*;
583 use crate::{
584 keys::{FullViewingKey, Scope, SpendingKey},
585 test_vectors::keys::TestVector,
586 };
587 use ff::PrimeField;
588 use group::GroupEncoding;
589
590 struct QrRcmDerivation {
591 rcm_old_repr: [u8; 32],
592 rcm_new_repr: [u8; 32],
593 cmx_old_bytes: [u8; 32],
594 cmx_qr_bytes: [u8; 32],
595 }
596
597 fn qr_rcm_from_key_test_vector(tv: &TestVector) -> QrRcmDerivation {
598 let sk = SpendingKey::from_bytes(tv.sk).unwrap();
599 let fvk = FullViewingKey::from(&sk);
600 let addr = fvk.address_at(0u32, Scope::External);
601 let rho = Rho::from_bytes(&tv.note_rho).unwrap();
602 let rseed = RandomSeed::from_bytes(tv.note_rseed, &rho).unwrap();
603
604 let g_d = addr.g_d();
605 let pk_d = addr.pk_d().inner();
606 let g_d_bytes = g_d.to_bytes();
607 let pk_d_bytes = pk_d.to_bytes();
608
609 let rcm_old = rseed.rcm_v2(&rho);
610 let psi = rseed.psi(&rho);
611 let rcm_new = rseed.rcm_v3(&rho, &g_d, &pk_d, tv.note_v, &psi);
612
613 let rcm_old_repr = rcm_old.0.to_repr();
614 let rcm_new_repr = rcm_new.0.to_repr();
615 let rho_inner = rho.into_inner();
616 let value = NoteValue::from_raw(tv.note_v);
617
618 let cmx_old =
619 NoteCommitment::derive(g_d_bytes, pk_d_bytes, value, rho_inner, psi, rcm_old).unwrap();
620 let cmx_old_bytes = ExtractedNoteCommitment::from(cmx_old).to_bytes();
621
622 let cmx_qr =
623 NoteCommitment::derive(g_d_bytes, pk_d_bytes, value, rho_inner, psi, rcm_new).unwrap();
624 let cmx_qr_bytes = ExtractedNoteCommitment::from(cmx_qr).to_bytes();
625
626 QrRcmDerivation {
627 rcm_old_repr,
628 rcm_new_repr,
629 cmx_old_bytes,
630 cmx_qr_bytes,
631 }
632 }
633
634 #[test]
635 fn qr_rcm_differs_from_old_rcm() {
636 let tv = &crate::test_vectors::keys::test_vectors()[0];
637 let derived = qr_rcm_from_key_test_vector(tv);
638
639 assert_ne!(derived.rcm_old_repr, derived.rcm_new_repr);
640 assert_eq!(
641 derived.cmx_old_bytes, tv.note_cmx,
642 "old cmx must match known test vector"
643 );
644 assert_ne!(derived.cmx_old_bytes, derived.cmx_qr_bytes);
645 }
646
647 #[test]
648 fn qr_rcm_verify_stored_vectors() {
649 for (i, key_tv) in crate::test_vectors::keys::test_vectors().iter().enumerate() {
650 let derived = qr_rcm_from_key_test_vector(key_tv);
651
652 assert_eq!(
653 derived.rcm_new_repr, key_tv.note_qr_rcm,
654 "vector {i}: rcm_qr mismatch"
655 );
656 assert_eq!(
657 derived.cmx_old_bytes, key_tv.note_cmx,
658 "vector {i}: cmx_old mismatch"
659 );
660 assert_eq!(
661 derived.cmx_qr_bytes, key_tv.note_qr_cmx,
662 "vector {i}: cmx_qr mismatch"
663 );
664 }
665 }
666}