feat: add note metadata

noir-projects/aztec-nr/address-note/src/address_note.nr

@@ -3,8 +3,8 @@ use dep::aztec::{
     keys::getters::{get_nsk_app, get_public_keys},
     macros::notes::note,
     note::{
-        note_interface::NullifiableNote, retrieved_note::RetrievedNote,
-        utils::compute_note_hash_for_nullify,
+        note_interface::NullifiableNote, note_metadata::SettledNoteMetadata,
+        retrieved_note::RetrievedNote, utils::compute_note_hash_for_nullify,
     },
     oracle::random::random,
     protocol_types::{
@@ -48,9 +48,11 @@ impl NullifiableNote for AddressNote {
         contract_address: AztecAddress,
         note_nonce: Field,
     ) -> Field {
-        // We set the note_hash_counter to 0 as the note is assumed to be committed (and hence not transient).
-        let retrieved_note =
-            RetrievedNote { note: self, contract_address, nonce: note_nonce, note_hash_counter: 0 };
+        let retrieved_note = RetrievedNote {
+            note: self,
+            contract_address,
+            metadata: SettledNoteMetadata::new(note_nonce).into(),
+        };
         let note_hash_for_nullify = compute_note_hash_for_nullify(retrieved_note, storage_slot);
         let owner_npk_m_hash = get_public_keys(self.owner).npk_m.hash();
         let secret = get_nsk_app(owner_npk_m_hash);

noir-projects/aztec-nr/aztec/src/note/lifecycle.nr

@@ -3,7 +3,7 @@ use crate::note::{
     note_emission::NoteEmission,
     note_interface::{NoteInterface, NullifiableNote},
     retrieved_note::RetrievedNote,
-    utils::{compute_note_hash_for_nullify_internal, compute_note_hash_for_read_request},
+    utils::{compute_note_hash_for_nullify_from_read_request, compute_note_hash_for_read_request},
 };
 use crate::oracle::notes::notify_created_note;
 use protocol_types::traits::Packable;
@@ -58,11 +58,10 @@ where
     Note: NoteInterface + NullifiableNote,
 {
     let note_hash_for_nullify =
-        compute_note_hash_for_nullify_internal(retrieved_note, note_hash_for_read_request);
+        compute_note_hash_for_nullify_from_read_request(retrieved_note, note_hash_for_read_request);
     let nullifier = retrieved_note.note.compute_nullifier(context, note_hash_for_nullify);
 
-    let note_hash_counter = retrieved_note.note_hash_counter;
-    let notification_note_hash = if (note_hash_counter == 0) {
+    let note_hash = if retrieved_note.metadata.is_settled() {
         // Counter is zero, so we're nullifying a settled note and we don't populate the note_hash with real value.
         0
     } else {
@@ -74,5 +73,5 @@ where
         note_hash_for_nullify
     };
 
-    context.push_nullifier_for_note_hash(nullifier, notification_note_hash)
+    context.push_nullifier_for_note_hash(nullifier, note_hash)
 }

noir-projects/aztec-nr/aztec/src/note/mod.nr

@@ -1,5 +1,6 @@
 pub mod constants;
 pub mod lifecycle;
+pub mod note_metadata;
 pub mod note_getter;
 pub mod note_getter_options;
 pub mod note_interface;

noir-projects/aztec-nr/aztec/src/note/note_metadata.nr

@@ -0,0 +1,187 @@
+use protocol_types::traits::Serialize;
+
+// There's temporarily quite a bit of boilerplate here since Noir does not yet support enums. This file will eventually
+// be simplified into something closer to:
+//
+// pub enum NoteMetadata {
+//   Transient{ note_hash_counter: u32 },
+//   TransientNonRevertible{ note_hash_counter: u32, nonce: Field },
+//   Settled{ nonce: Field },
+// }
+//
+// For now, we have `NoteMetadata` acting as a sort of tagged union.
+
+/// The different stages in which a note can be.
+///  - TRANSIENT_REVERTIBLE: a note that was created in the transaction that is currently being executed during the
+///    revertible phase
+///  - TRANSIENT_NON_REVERTIBLE: same as transient, except the note was created during the non-revertible phase
+///  - SETTLED: a note that was created in a prior transaction and is therefore in the note hash tree
+struct NoteStageEnum {
+    TRANSIENT_REVERTIBLE: u8,
+    TRANSIENT_NON_REVERTIBLE: u8,
+    SETTLED: u8,
+}
+
+global NoteStage: NoteStageEnum =
+    NoteStageEnum { TRANSIENT_REVERTIBLE: 1, TRANSIENT_NON_REVERTIBLE: 2, SETTLED: 3 };
+
+/// The metadata required to both prove a note's existence and destroy it, by computing the correct note hash for kernel
+/// read requests, as well as the correct nullifier to avoid double-spends.
+///
+/// This represents a note in any of the tree valid stages (transient revertible, transient non-revertible or settled),
+/// in order to access the underlying fields callers must first find the appropriate stage (e.g. via `is_settled()`) and
+/// then convert this into the appropriate type (e.g. via `to_settled()`).
+#[derive(Eq, Serialize)]
+pub struct NoteMetadata {
+    stage: u8,
+    // todo: replace with a boolean
+    maybe_note_hash_counter: u32,
+    maybe_nonce: Field,
+}
+
+impl NoteMetadata {
+    /// Constructs a `NoteMetadata` object from optional note hash and nullifiers. Both a zero note hash counter and a
+    /// zero nonce are invalid, so those are used to signal non-existent values.
+    pub fn from_raw_data(maybe_note_hash_counter: u32, maybe_nonce: Field) -> Self {
+        if maybe_note_hash_counter != 0 {
+            if maybe_nonce == 0 {
+                Self { stage: NoteStage.TRANSIENT_REVERTIBLE, maybe_note_hash_counter, maybe_nonce }
+            } else {
+                Self {
+                    stage: NoteStage.TRANSIENT_NON_REVERTIBLE,
+                    maybe_note_hash_counter,
+                    maybe_nonce,
+                }
+            }
+        } else if maybe_nonce != 0 {
+            Self { stage: NoteStage.SETTLED, maybe_note_hash_counter, maybe_nonce }
+        } else {
+            panic(
+                f"Note has no note hash counter nor nonce - existence cannot be proven",
+            )
+        }
+    }
+
+    /// Returns true if the note is transient and revertible, i.e. if it's been created in the current transaction
+    /// during the revertible phase.
+    ///
+    /// To test if the note is transient consider doing `!metadata.is_settled()`.
+    pub fn is_transient_revertible(self) -> bool {
+        self.stage == NoteStage.TRANSIENT_REVERTIBLE
+    }
+
+    /// Returns true if the note is transient and non-revertible, i.e. if it's been created in the current transaction
+    /// during the non-revertible phase.
+    ///
+    /// To test if the note is transient consider doing `!metadata.is_settled()`.
+    pub fn is_transient_non_revertible(self) -> bool {
+        self.stage == NoteStage.TRANSIENT_NON_REVERTIBLE
+    }
+
+    /// Returns true if the note is settled, i.e. if it's been created in a prior transaction and is therefore in the
+    /// note hash tree.
+    pub fn is_settled(self) -> bool {
+        self.stage == NoteStage.SETTLED
+    }
+
+    /// Asserts that the metadata is that of a transient revertible note and converts it accordingly.
+    pub fn to_transient_revertible(self) -> TransientRevertibleNoteMetadata {
+        assert_eq(self.stage, NoteStage.TRANSIENT_REVERTIBLE);
+        TransientRevertibleNoteMetadata { note_hash_counter: self.maybe_note_hash_counter }
+    }
+
+    /// Asserts that the metadata is that of a transient non-revertible note and converts it accordingly.
+    pub fn to_transient_non_revertible(self) -> TransientNonRevertibleNoteMetadata {
+        assert_eq(self.stage, NoteStage.TRANSIENT_NON_REVERTIBLE);
+        TransientNonRevertibleNoteMetadata {
+            note_hash_counter: self.maybe_note_hash_counter,
+            nonce: self.maybe_nonce,
+        }
+    }
+
+    /// Asserts that the metadata is that of a settled note and converts it accordingly.
+    pub fn to_settled(self) -> SettledNoteMetadata {
+        assert_eq(self.stage, NoteStage.SETTLED);
+        SettledNoteMetadata { nonce: self.maybe_nonce }
+    }
+}
+
+impl From<TransientRevertibleNoteMetadata> for NoteMetadata {
+    fn from(value: TransientRevertibleNoteMetadata) -> Self {
+        NoteMetadata::from_raw_data(value.note_hash_counter(), std::mem::zeroed())
+    }
+}
+
+impl From<TransientNonRevertibleNoteMetadata> for NoteMetadata {
+    fn from(value: TransientNonRevertibleNoteMetadata) -> Self {
+        NoteMetadata::from_raw_data(value.note_hash_counter(), value.nonce())
+    }
+}
+
+impl From<SettledNoteMetadata> for NoteMetadata {
+    fn from(value: SettledNoteMetadata) -> Self {
+        NoteMetadata::from_raw_data(std::mem::zeroed(), value.nonce())
+    }
+}
+
+/// The metadata required to both prove a note's existence and destroy it, by computing the correct note hash for kernel
+/// read requests, as well as the correct nullifier to avoid double-spends.
+///
+/// This represents a transient revertible note, i.e. a note that was created in the transaction that is currently being
+/// executed during the revertible phase.
+pub struct TransientRevertibleNoteMetadata {
+    note_hash_counter: u32,
+}
+
+/// The metadata required to both prove a note's existence and destroy it, by computing the correct note hash for kernel
+/// read requests, as well as the correct nullifier to avoid double-spends.
+///
+/// This represents a transient non-revertible note, i.e. a note that was created in a prior transaction and is
+/// therefore in the note hash tree.
+impl TransientRevertibleNoteMetadata {
+    pub fn new(note_hash_counter: u32) -> Self {
+        Self { note_hash_counter }
+    }
+
+    pub fn note_hash_counter(self) -> u32 {
+        self.note_hash_counter
+    }
+}
+
+pub struct TransientNonRevertibleNoteMetadata {
+    note_hash_counter: u32,
+    nonce: Field,
+}
+
+impl TransientNonRevertibleNoteMetadata {
+    pub fn new(note_hash_counter: u32, nonce: Field) -> Self {
+        Self { note_hash_counter, nonce }
+    }
+
+    pub fn note_hash_counter(self) -> u32 {
+        self.note_hash_counter
+    }
+
+    pub fn nonce(self) -> Field {
+        self.nonce
+    }
+}
+
+/// The metadata required to both prove a note's existence and destroy it, by computing the correct note hash for kernel
+/// read requests, as well as the correct nullifier to avoid double-spends.
+///
+/// This represents a settled note, i.e. a note that was created in the transaction that is currently
+/// being executed during the non-revertible phase.
+pub struct SettledNoteMetadata {
+    nonce: Field,
+}
+
+impl SettledNoteMetadata {
+    pub fn new(nonce: Field) -> Self {
+        Self { nonce }
+    }
+
+    pub fn nonce(self) -> Field {
+        self.nonce
+    }
+}

noir-projects/aztec-nr/aztec/src/note/retrieved_note.nr

@@ -1,34 +1,27 @@
-use protocol_types::{address::AztecAddress, traits::Serialize, utils::arrays::array_concat};
+use crate::note::note_metadata::NoteMetadata;
+use protocol_types::{
+    address::AztecAddress,
+    traits::{Serialize, ToField},
+    utils::arrays::array_concat,
+};
 
 /// A container of a note and the metadata required to constrain its existence, regardless of whether the note is
 /// historical (created in a previous transaction) or transient (created in the current transaction).
+#[derive(Eq)]
 pub struct RetrievedNote<NOTE> {
     pub note: NOTE,
     pub contract_address: AztecAddress,
-    pub nonce: Field,
-    pub note_hash_counter: u32, // a note_hash_counter of 0 means non-transient
+    pub metadata: NoteMetadata,
 }
 
-impl<NOTE> Eq for RetrievedNote<NOTE>
-where
-    NOTE: Eq,
-{
-    fn eq(self, other: Self) -> bool {
-        (self.note == other.note)
-            & (self.contract_address == other.contract_address)
-            & (self.nonce == other.nonce)
-            & (self.note_hash_counter == other.note_hash_counter)
-    }
-}
-
-impl<NOTE, let N: u32> Serialize<N + 3> for RetrievedNote<NOTE>
+impl<NOTE, let N: u32> Serialize<N + 1 + 3> for RetrievedNote<NOTE>
 where
     NOTE: Serialize<N>,
 {
-    fn serialize(self) -> [Field; N + 3] {
+    fn serialize(self) -> [Field; N + 1 + 3] {
         array_concat(
-            self.note.serialize(),
-            [self.contract_address.to_field(), self.nonce, self.note_hash_counter as Field],
+            array_concat(self.note.serialize(), [self.contract_address.to_field()]),
+            self.metadata.serialize(),
         )
     }
 }