diff --git a/noir-projects/aztec-nr/aztec/src/capsules/mod.nr b/noir-projects/aztec-nr/aztec/src/capsules/mod.nr index cf09773a3d40..9921304dd71a 100644 --- a/noir-projects/aztec-nr/aztec/src/capsules/mod.nr +++ b/noir-projects/aztec-nr/aztec/src/capsules/mod.nr @@ -76,8 +76,12 @@ impl CapsuleArray { capsules::store(self.contract_address, self.base_slot, current_length - 1); } - /// Iterates over the entire array, calling the callback with all values and their array index. The order in which - /// values are processed is arbitrary. + /// Calls a function on each element of the array. + /// + /// The function `f` is called once with each array value and its corresponding index. The order in which values + /// are processed is arbitrary. + /// + /// ## Array Mutation /// /// It is safe to delete the current element (and only the current element) from inside the callback via `remove`: /// ```noir diff --git a/noir-projects/aztec-nr/aztec/src/messages/discovery/mod.nr b/noir-projects/aztec-nr/aztec/src/messages/discovery/mod.nr index ca0ee22548a5..e903b16b9b2d 100644 --- a/noir-projects/aztec-nr/aztec/src/messages/discovery/mod.nr +++ b/noir-projects/aztec-nr/aztec/src/messages/discovery/mod.nr @@ -1,8 +1,8 @@ use crate::protocol::{address::AztecAddress, logging::{debug_log, debug_log_format}}; -pub mod nonce_discovery; -pub mod partial_notes; -pub mod private_events; +pub(crate) mod nonce_discovery; +pub(crate) mod partial_notes; +pub(crate) mod private_events; pub mod private_notes; pub mod process_message; @@ -20,22 +20,38 @@ use crate::{ }; pub struct NoteHashAndNullifier { - /// The result of NoteHash::compute_note_hash + /// The result of [`crate::note::note_interface::NoteHash::compute_note_hash`]. pub note_hash: Field, - /// The result of NoteHash::compute_nullifier_unconstrained (since all of message discovery is unconstrained). - /// This is `None` if the nullifier cannot be computed (e.g., because the nullifier hiding key is not available). + /// The result of [`crate::note::note_interface::NoteHash::compute_nullifier_unconstrained`]. + /// + /// This value is unconstrained, as all of message discovery is unconstrained. It is `None` if the nullifier + /// cannot be computed (e.g. because the nullifier hiding key is not available). pub inner_nullifier: Option, } -/// A function which takes a note's packed content, address of the emitting contract, note nonce, storage slot and note -/// type ID and attempts to compute its note hash (not hashed by note nonce nor siloed by address) and inner nullifier -/// (not siloed by address). +/// A contract's way of computing note hashes and nullifiers. /// -/// This function must be user-provided as its implementation requires knowledge of how note type IDs are allocated in -/// a contract. The `#[aztec]` macro automatically creates such a contract library method called -/// `_compute_note_hash_and_nullifier`, which looks something like this: +/// Each contract in the network is free to compute their note's hash and nullifiers as they see fit - the hash +/// function itself and the nullifier derivation are not enshrined or standardized. Some aztec-nr functions however do +/// need to know the details of this computation (e.g. when finding new notes), which is what this type represents. /// -/// ``` +/// This function takes a note's packed content, storage slot, note type ID, address of the emitting contract, +/// randomness and note nonce, and attempts to compute its inner note hash (not siloed by address nor uniqued by nonce) +/// and inner nullifier (not siloed by address). +/// +/// ## Transient Notes +/// +/// This function is meant to always be used on **settled** notes, i.e. those that have been inserted into the trees +/// and for which the nonce is known. It is never invoked in the context of a transient note, as those are not involved +/// in message processing. +/// +/// ## Automatic Implementation +/// +/// The [`[#aztec]`](crate::macros::aztec::aztec) macro automatically creates a correct implementation of this function +/// for each contract by inspecting all note types in use and the storage layout. This injected function is a +/// `#[contract_library_function]` called `_compute_note_hash_and_nullifier`, and it looks something like this: +/// +/// ```noir /// |packed_note, owner, storage_slot, note_type_id, contract_address, randomness, note_nonce| { /// if note_type_id == MyNoteType::get_id() { /// assert(packed_note.len() == MY_NOTE_TYPE_SERIALIZATION_LENGTH); @@ -78,15 +94,14 @@ pub type CustomMessageHandler = unconstrained fn[Env]( /* msg_content */ BoundedVec, /* message_context */ MessageContext); -/// Performs the state synchronization process, in which private logs are downloaded and inspected to find new private -/// notes, partial notes and events, etc., and pending partial notes are processed to search for their completion logs. -/// This is the mechanism via which a contract updates its knowledge of its private state. +/// Synchronizes the contract's private state with the network. /// -/// Note that the state is synchronized up to the latest block synchronized by PXE (referred to as "anchor block"). -/// That should be close to the chain tip as block synchronization is performed before contract function simulation is -/// done. +/// As blocks are mined, it is possible for a contract's private state to change (e.g. with new notes being created), +/// but because these changes are private they will be invisible to most actors. This is the function that processes +/// new transactions in order to discover new notes, events, and other kinds of private state changes. /// -/// Receives the address of the contract on which discovery is performed along with the contract's configuration. +/// The private state will be synchronized up to the block that will be used for private transactions (i.e. the anchor +/// block. This will typically be close to the tip of the chain. pub unconstrained fn do_sync_state( contract_address: AztecAddress, compute_note_hash_and_nullifier: ComputeNoteHashAndNullifier, @@ -113,6 +128,11 @@ pub unconstrained fn do_sync_state( +pub(crate) unconstrained fn attempt_note_nonce_discovery( unique_note_hashes_in_tx: BoundedVec, first_nullifier_in_tx: Field, compute_note_hash_and_nullifier: ComputeNoteHashAndNullifier, diff --git a/noir-projects/aztec-nr/aztec/src/messages/discovery/partial_notes.nr b/noir-projects/aztec-nr/aztec/src/messages/discovery/partial_notes.nr index df29197a0020..725fc6772213 100644 --- a/noir-projects/aztec-nr/aztec/src/messages/discovery/partial_notes.nr +++ b/noir-projects/aztec-nr/aztec/src/messages/discovery/partial_notes.nr @@ -20,7 +20,7 @@ use crate::protocol::{ }; /// The slot in the PXE capsules where we store a `CapsuleArray` of `DeliveredPendingPartialNote`. -pub global DELIVERED_PENDING_PARTIAL_NOTE_ARRAY_LENGTH_CAPSULES_SLOT: Field = sha256_to_field( +pub(crate) global DELIVERED_PENDING_PARTIAL_NOTE_ARRAY_LENGTH_CAPSULES_SLOT: Field = sha256_to_field( "AZTEC_NR::DELIVERED_PENDING_PARTIAL_NOTE_ARRAY_LENGTH_CAPSULES_SLOT".as_bytes(), ); @@ -37,7 +37,7 @@ pub(crate) struct DeliveredPendingPartialNote { pub(crate) recipient: AztecAddress, } -pub unconstrained fn process_partial_note_private_msg( +pub(crate) unconstrained fn process_partial_note_private_msg( contract_address: AztecAddress, recipient: AztecAddress, msg_metadata: u64, @@ -67,7 +67,7 @@ pub unconstrained fn process_partial_note_private_msg( /// Searches for logs that would result in the completion of pending partial notes, ultimately resulting in the notes /// being delivered to PXE if completed. -pub unconstrained fn fetch_and_process_partial_note_completion_logs( +pub(crate) unconstrained fn fetch_and_process_partial_note_completion_logs( contract_address: AztecAddress, compute_note_hash_and_nullifier: ComputeNoteHashAndNullifier, ) { diff --git a/noir-projects/aztec-nr/aztec/src/messages/discovery/private_events.nr b/noir-projects/aztec-nr/aztec/src/messages/discovery/private_events.nr index 697761f7c959..22b7df8fd6b2 100644 --- a/noir-projects/aztec-nr/aztec/src/messages/discovery/private_events.nr +++ b/noir-projects/aztec-nr/aztec/src/messages/discovery/private_events.nr @@ -7,7 +7,7 @@ use crate::{ }; use crate::protocol::{address::AztecAddress, traits::ToField}; -pub unconstrained fn process_private_event_msg( +pub(crate) unconstrained fn process_private_event_msg( contract_address: AztecAddress, recipient: AztecAddress, msg_metadata: u64, diff --git a/noir-projects/aztec-nr/aztec/src/messages/discovery/private_notes.nr b/noir-projects/aztec-nr/aztec/src/messages/discovery/private_notes.nr index 6366ec9a5543..b810829113be 100644 --- a/noir-projects/aztec-nr/aztec/src/messages/discovery/private_notes.nr +++ b/noir-projects/aztec-nr/aztec/src/messages/discovery/private_notes.nr @@ -6,7 +6,7 @@ use crate::messages::{ }; use crate::protocol::{address::AztecAddress, constants::MAX_NOTE_HASHES_PER_TX, logging::debug_log_format}; -pub unconstrained fn process_private_note_msg( +pub(crate) unconstrained fn process_private_note_msg( contract_address: AztecAddress, tx_hash: Field, unique_note_hashes_in_tx: BoundedVec, diff --git a/noir-projects/aztec-nr/aztec/src/messages/discovery/process_message.nr b/noir-projects/aztec-nr/aztec/src/messages/discovery/process_message.nr index 1d0a754eba9e..1adc84a96157 100644 --- a/noir-projects/aztec-nr/aztec/src/messages/discovery/process_message.nr +++ b/noir-projects/aztec-nr/aztec/src/messages/discovery/process_message.nr @@ -44,13 +44,13 @@ pub unconstrained fn process_message_ciphertext( +pub(crate) unconstrained fn process_message_plaintext( contract_address: AztecAddress, compute_note_hash_and_nullifier: ComputeNoteHashAndNullifier, process_custom_message: Option>,