core: Introduce API changes

These include:
- Add function `value_commitment`
- Add function `transparent_value_commitment`
- Turn the value-commitment an `JubJubAffine` point
- Expose `NOTE_ENCRYPTION_SIZE`

core/CHANGELOG.md

@@ -10,10 +10,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Add a light sync method in the `ViewKey` [#199]
+- Add function `value_commitment` [#201]
+- Add function `transparent_value_commitment` [#201]
 
 ### Changed
 
 - Rename `crossover` to `deposit` [#190]
+- Turn the value-commitment an `JubJubAffine` point [#201]
+- Expose `NOTE_ENCRYPTION_SIZE` [#201]
 
 ### Removed
 
@@ -329,6 +333,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Canonical implementation shielded by feature.
 
 <!-- ISSUES -->
+[#201]: https://github.com/dusk-network/phoenix/issues/201
 [#199]: https://github.com/dusk-network/phoenix/issues/199
 [#195]: https://github.com/dusk-network/phoenix/issues/195
 [#190]: https://github.com/dusk-network/phoenix/issues/190

core/Cargo.toml

@@ -28,7 +28,7 @@ rand = "0.8"
 rkyv = { version = "0.7", default-features = false, features = ["size_32"] }
 
 [features]
-default = []    # "alloc" is suggested as default feature but would be breaking change
+default = ["alloc"]
 alloc = []
 rkyv-impl = [
     "dusk-jubjub/rkyv-impl",

core/src/addresses.rs

@@ -0,0 +1,23 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+//
+// Copyright (c) DUSK NETWORK. All rights reserved.
+
+pub mod stealth;
+pub mod sync;
+
+// /// Hashes a JubJub's ExtendedPoint into a JubJub's Scalar using the JubJub's
+// /// hash to scalar function
+// pub fn hash(p: &JubJubExtended) -> JubJubScalar {
+//     JubJubScalar::hash_to_scalar(&JubJubAffine::from(p).to_bytes())
+// }
+
+/// The trait `Ownable` is required by any type that wants to prove its
+/// ownership.
+pub trait Ownable {
+    /// Returns the associated `SyncAddress`
+    fn sync_address(&self) -> sync::SyncAddress;
+    /// Returns the associated `StealthAddress`
+    fn stealth_address(&self) -> stealth::StealthAddress;
+}

core/src/keys/stealth.rs → core/src/addresses/stealth.rs

@@ -4,7 +4,7 @@
 //
 // Copyright (c) DUSK NETWORK. All rights reserved.
 
-use crate::keys::{sync::SyncAddress, Ownable};
+use crate::{Ownable, SyncAddress};
 use dusk_jubjub::{JubJubAffine, JubJubExtended};
 use jubjub_schnorr::PublicKey as NotePublicKey;
 

core/src/keys/sync.rs → core/src/addresses/sync.rs

@@ -4,7 +4,7 @@
 //
 // Copyright (c) DUSK NETWORK. All rights reserved.
 
-use crate::keys::{stealth::StealthAddress, Ownable};
+use crate::{Ownable, StealthAddress};
 use dusk_jubjub::{JubJubAffine, JubJubExtended};
 use jubjub_schnorr::PublicKey as NotePublicKey;
 

core/src/keys.rs

@@ -8,21 +8,10 @@ use dusk_jubjub::{JubJubAffine, JubJubExtended, JubJubScalar};
 
 pub mod public;
 pub mod secret;
-pub mod stealth;
-pub mod sync;
 pub mod view;
 
 /// Hashes a JubJub's ExtendedPoint into a JubJub's Scalar using the JubJub's
 /// hash to scalar function
 pub fn hash(p: &JubJubExtended) -> JubJubScalar {
     JubJubScalar::hash_to_scalar(&JubJubAffine::from(p).to_bytes())
 }
-
-/// The trait `Ownable` is required by any type that wants to prove its
-/// ownership.
-pub trait Ownable {
-    /// Returns the associated `SyncAddress`
-    fn sync_address(&self) -> sync::SyncAddress;
-    /// Returns the associated `StealthAddress`
-    fn stealth_address(&self) -> stealth::StealthAddress;
-}

core/src/lib.rs

@@ -10,6 +10,7 @@
 #![deny(missing_docs)]
 #![no_std]
 
+mod addresses;
 mod encryption;
 mod error;
 mod keys;
@@ -18,17 +19,39 @@ mod note;
 #[cfg(feature = "alloc")]
 mod transaction;
 
+pub use addresses::stealth::StealthAddress;
+pub use addresses::sync::SyncAddress;
+pub use addresses::Ownable;
 pub use encryption::aes;
 pub use error::Error;
 pub use keys::hash;
 pub use keys::public::PublicKey;
 pub use keys::secret::SecretKey;
-pub use keys::stealth::StealthAddress;
-pub use keys::sync::SyncAddress;
 pub use keys::view::ViewKey;
-pub use keys::Ownable;
-pub use note::{Note, NoteType};
+pub use note::{Note, NoteType, ENCRYPTION_SIZE as NOTE_ENCRYPTION_SIZE};
 
 #[cfg(feature = "alloc")]
 /// Transaction Skeleton used by the phoenix transaction model
 pub use transaction::TxSkeleton;
+
+use dusk_jubjub::{
+    JubJubAffine, JubJubScalar, GENERATOR_EXTENDED, GENERATOR_NUMS_EXTENDED,
+};
+
+/// Use the pederson commitment scheme to compute a transparent value
+/// commitment.
+pub fn transparent_value_commitment(value: u64) -> JubJubAffine {
+    JubJubAffine::from(GENERATOR_EXTENDED * JubJubScalar::from(value))
+}
+
+/// Use the pederson commitment scheme to compute a value commitment using a
+/// blinding-factor.
+pub fn value_commitment(
+    value: u64,
+    blinding_factor: JubJubScalar,
+) -> JubJubAffine {
+    JubJubAffine::from(
+        (GENERATOR_EXTENDED * JubJubScalar::from(value))
+            + (GENERATOR_NUMS_EXTENDED * blinding_factor),
+    )
+}

core/src/note.rs

@@ -7,14 +7,12 @@
 use core::convert::{TryFrom, TryInto};
 
 use crate::{
-    Error, Ownable, PublicKey, SecretKey, StealthAddress, SyncAddress, ViewKey,
+    transparent_value_commitment, value_commitment, Error, Ownable, PublicKey,
+    SecretKey, StealthAddress, SyncAddress, ViewKey,
 };
 use dusk_bls12_381::BlsScalar;
 use dusk_bytes::{DeserializableSlice, Error as BytesError, Serializable};
-use dusk_jubjub::{
-    dhke, JubJubAffine, JubJubExtended, JubJubScalar, GENERATOR_EXTENDED,
-    GENERATOR_NUMS_EXTENDED,
-};
+use dusk_jubjub::{dhke, JubJubAffine, JubJubScalar, GENERATOR_NUMS_EXTENDED};
 
 use crate::aes;
 
@@ -25,15 +23,14 @@ use rand::{CryptoRng, RngCore};
 #[cfg(feature = "rkyv-impl")]
 use rkyv::{Archive, Deserialize, Serialize};
 
-/// Blinder used for transparent
+/// Blinder used for transparent notes.
 pub(crate) const TRANSPARENT_BLINDER: JubJubScalar = JubJubScalar::zero();
 
 /// Size of the Phoenix notes plaintext: value (8 bytes) + blinder (32 bytes)
 pub(crate) const PLAINTEXT_SIZE: usize = 40;
 
 /// Size of the Phoenix notes encryption
-pub(crate) const ENCRYPTION_SIZE: usize =
-    PLAINTEXT_SIZE + aes::ENCRYPTION_EXTRA_SIZE;
+pub const ENCRYPTION_SIZE: usize = PLAINTEXT_SIZE + aes::ENCRYPTION_EXTRA_SIZE;
 
 /// The types of a Note
 #[derive(Debug, Clone, Copy, Eq, PartialEq)]
@@ -78,7 +75,7 @@ impl TryFrom<i32> for NoteType {
 )]
 pub struct Note {
     pub(crate) note_type: NoteType,
-    pub(crate) value_commitment: JubJubExtended,
+    pub(crate) value_commitment: JubJubAffine,
     pub(crate) stealth_address: StealthAddress,
     pub(crate) sync_address: SyncAddress,
     pub(crate) pos: u64,
@@ -108,9 +105,7 @@ impl Note {
         let r_sync = JubJubScalar::random(&mut *rng);
         let sync_address = pk.gen_sync_address(&r_sync);
 
-        let value_commitment = JubJubScalar::from(value);
-        let value_commitment = (GENERATOR_EXTENDED * value_commitment)
-            + (GENERATOR_NUMS_EXTENDED * blinding_factor);
+        let value_commitment = value_commitment(value, blinding_factor);
 
         // Output notes have undefined position, equals to u64's MAX value
         let pos = u64::MAX;
@@ -167,9 +162,7 @@ impl Note {
         sync_address: SyncAddress,
         value: u64,
     ) -> Self {
-        let value_commitment = JubJubScalar::from(value);
-        let value_commitment = (GENERATOR_EXTENDED * value_commitment)
-            + (GENERATOR_NUMS_EXTENDED * TRANSPARENT_BLINDER);
+        let value_commitment = transparent_value_commitment(value);
 
         let pos = u64::MAX;
 
@@ -205,7 +198,7 @@ impl Note {
     pub fn empty() -> Self {
         Self {
             note_type: NoteType::Transparent,
-            value_commitment: JubJubExtended::default(),
+            value_commitment: JubJubAffine::default(),
             stealth_address: StealthAddress::default(),
             sync_address: SyncAddress::default(),
             pos: 0,
@@ -253,14 +246,13 @@ impl Note {
 
     /// Return the internal representation of scalars to be hashed
     pub fn hash_inputs(&self) -> [BlsScalar; 6] {
-        let value_commitment = self.value_commitment().to_hash_inputs();
         let note_pk =
             self.stealth_address().note_pk().as_ref().to_hash_inputs();
 
         [
             BlsScalar::from(self.note_type as u64),
-            value_commitment[0],
-            value_commitment[1],
+            self.value_commitment.get_u(),
+            self.value_commitment.get_v(),
             note_pk[0],
             note_pk[1],
             BlsScalar::from(self.pos),
@@ -290,7 +282,7 @@ impl Note {
     }
 
     /// Return the value commitment `H(value, blinding_factor)`
-    pub const fn value_commitment(&self) -> &JubJubExtended {
+    pub const fn value_commitment(&self) -> &JubJubAffine {
         &self.value_commitment
     }
 
@@ -367,9 +359,7 @@ impl Serializable<{ 169 + ENCRYPTION_SIZE }> for Note {
 
         buf[0] = self.note_type as u8;
 
-        buf[1..33].copy_from_slice(
-            &JubJubAffine::from(&self.value_commitment).to_bytes(),
-        );
+        buf[1..33].copy_from_slice(&self.value_commitment.to_bytes());
         buf[33..97].copy_from_slice(&self.stealth_address.to_bytes());
         buf[97..161].copy_from_slice(&self.sync_address.to_bytes());
         buf[161..169].copy_from_slice(&self.pos.to_le_bytes());
@@ -384,8 +374,7 @@ impl Serializable<{ 169 + ENCRYPTION_SIZE }> for Note {
 
         let note_type =
             bytes[0].try_into().map_err(|_| BytesError::InvalidData)?;
-        let value_commitment =
-            JubJubExtended::from(JubJubAffine::from_slice(&bytes[1..33])?);
+        let value_commitment = JubJubAffine::from_slice(&bytes[1..33])?;
         let stealth_address = StealthAddress::from_slice(&bytes[33..97])?;
 
         let sync_address = SyncAddress::from_slice(&bytes[97..161])?;

core/tests/note_test.rs

@@ -7,7 +7,8 @@
 use dusk_jubjub::{JubJubScalar, GENERATOR_EXTENDED, GENERATOR_NUMS_EXTENDED};
 use ff::Field;
 use phoenix_core::{
-    Error, Note, NoteType, Ownable, PublicKey, SecretKey, ViewKey,
+    value_commitment, Error, Note, NoteType, Ownable, PublicKey, SecretKey,
+    ViewKey,
 };
 use rand::rngs::StdRng;
 use rand::SeedableRng;
@@ -103,18 +104,16 @@ fn value_commitment_transparent() {
 
     let value = note
         .value(Some(&vk))
-        .expect("Value not returned with the correct view key");
-    let value = JubJubScalar::from(value);
+        .expect("The note should be owned by the provided vk");
 
     let blinding_factor = note
         .blinding_factor(Some(&vk))
-        .expect("Blinding factor not returned with the correct view key");
+        .expect("The note should be owned by the provided vk");
 
     let commitment = note.value_commitment();
-    let commitment_p = (GENERATOR_EXTENDED * value)
-        + (GENERATOR_NUMS_EXTENDED * blinding_factor);
+    let commitment_p = value_commitment(value, blinding_factor);
 
-    assert_eq!(commitment, &commitment_p);
+    assert_eq!(commitment, &commitment_p.into());
 }
 
 #[test]
@@ -131,18 +130,16 @@ fn value_commitment_obfuscated() {
 
     let value = note
         .value(Some(&vk))
-        .expect("Value not returned with the correct view key");
-    let value = JubJubScalar::from(value);
+        .expect("The note should be owned by the provided vk");
 
     let blinding_factor = note
         .blinding_factor(Some(&vk))
-        .expect("Blinding factor not returned with the correct view key");
+        .expect("The note should be owned by the provided vk");
 
     let commitment = note.value_commitment();
-    let commitment_p = (GENERATOR_EXTENDED * value)
-        + (GENERATOR_NUMS_EXTENDED * blinding_factor);
+    let commitment_p = value_commitment(value, blinding_factor);
 
-    assert_eq!(commitment, &commitment_p);
+    assert_eq!(commitment, &commitment_p.into());
 }
 
 #[test]