docs: initial cleanup

docs/docs/concepts/foundation/state_model.md

@@ -40,4 +40,4 @@ This is achieved with two main features:
 
 ## Further reading
 
-Read more about how to leverage the Aztec state model in Aztec contracts [here](../../dev_docs/contracts/syntax/state_variables.md).
+Read more about how to leverage the Aztec state model in Aztec contracts [here](../../dev_docs/contracts/syntax/storage.md).

docs/docs/dev_docs/contracts/layout.md

@@ -2,7 +2,7 @@
 title: Structure
 ---
 
-A contract is a collection of persistent [state variables](./syntax/state_variables.md), and [functions](./syntax/functions) which may manipulate these variables. Functions and state variables within a contract's scope are said to belong to that contract. A contract can only access and modify its own state. If a contract wishes to access or modify another contract's state, it must make a call to an external function of the other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called.
+A contract is a collection of persistent [state variables](./syntax/storage.md), and [functions](./syntax/functions) which may manipulate these variables. Functions and state variables within a contract's scope are said to belong to that contract. A contract can only access and modify its own state. If a contract wishes to access or modify another contract's state, it must make a call to an external function of the other contract. For anything to happen on the Aztec network, an external function of a contract needs to be called.
 
 # Contract
 

docs/docs/dev_docs/contracts/syntax/main.md

@@ -9,7 +9,7 @@ On top of [Noir's stdlib](https://noir-lang.org/standard_library/array_methods),
 
 Aztec.nr contains abstractions which remove the need to understand the low-level Aztec protocol. Notably, it provides:
 
-- Public and private [state variable types](./state_variables.md)
+- Public and private [state variable types](./storage.md)
 - Some pre-designed notes
 - Functions for [emitting](./events.md) encrypted and unencrypted logs
 - [Oracle functions](./functions.md#oracle-functions) for accessing:

docs/docs/dev_docs/tutorials/writing_token_contract.md

@@ -242,7 +242,7 @@ We are also importing types from a `types.nr` file. Copy [this file](https://git
 
 ### Note on private state
 
-Private state in Aztec is all [UTXOs](https://en.wikipedia.org/wiki/Unspent_transaction_output) under the hood. Handling UTXOs is largely abstracted away from developers, but there are some unique things for developers to be aware of when creating and managing private state in an Aztec contract. See [State Variables](../contracts/syntax/state_variables) to learn more about public and private state in Aztec.
+Private state in Aztec is all [UTXOs](https://en.wikipedia.org/wiki/Unspent_transaction_output) under the hood. Handling UTXOs is largely abstracted away from developers, but there are some unique things for developers to be aware of when creating and managing private state in an Aztec contract. See [State Variables](../contracts/syntax/storage.md) to learn more about public and private state in Aztec.
 
 Copy [`util.nr`](https://github.com/AztecProtocol/aztec-packages/blob/master/yarn-project/noir-contracts/src/contracts/token_contract/src/util.nr) into `token_contract_tutorial/contracts/src` as well. The function defined in `util.nr` will be helpful for generating message hashes that are used when communicating between contracts.
 

docs/sidebars.js

@@ -248,7 +248,6 @@ const sidebars = {
           },
           items: [
             "dev_docs/contracts/syntax/storage",
-            "dev_docs/contracts/syntax/state_variables",
             "dev_docs/contracts/syntax/events",
             "dev_docs/contracts/syntax/functions",
             "dev_docs/contracts/syntax/context",

yarn-project/aztec-nr/aztec/src/state_vars/immutable_singleton.nr

@@ -10,13 +10,16 @@ use crate::oracle;
 use dep::std::hash::pedersen_with_separator;
 use dep::std::option::Option;
 
+// docs:start:struct
 struct ImmutableSingleton<Note, N> {
     context: Context,
     storage_slot: Field,
     note_interface: NoteInterface<Note, N>,
 }
+// docs:end:struct
 
 impl<Note, N> ImmutableSingleton<Note, N> {
+    // docs:start:new
     fn new(
         context: Context,
         storage_slot: Field,
@@ -29,12 +32,14 @@ impl<Note, N> ImmutableSingleton<Note, N> {
             note_interface,
         }
     }
+    // docs:end:new
 
     unconstrained fn is_initialized(self) -> bool {
         let nullifier = self.compute_initialisation_nullifier();
         oracle::notes::is_nullifier_emitted(nullifier)
     }
 
+    // docs:start:initialize
     fn initialize(self, note: &mut Note) {
         // Nullify the storage slot.
         let nullifier = self.compute_initialisation_nullifier();
@@ -49,6 +54,7 @@ impl<Note, N> ImmutableSingleton<Note, N> {
             self.note_interface,
         );
     }
+    // docs:end:initialize
 
     fn compute_initialisation_nullifier(self) -> Field {
         pedersen_with_separator(
@@ -57,10 +63,12 @@ impl<Note, N> ImmutableSingleton<Note, N> {
         )[0]
     }
 
+    // docs:start:get_note
     fn get_note(self) -> Note {
         let storage_slot = self.storage_slot;
         get_note(self.context.private.unwrap(), storage_slot, self.note_interface)
     }
+    // docs:end:get_note
 
     unconstrained fn view_note(self) -> Note {
         let options = NoteViewerOptions::new().set_limit(1);

yarn-project/aztec-nr/aztec/src/state_vars/map.nr

@@ -1,13 +1,16 @@
 use crate::context::{PrivateContext, PublicContext, Context};
 use dep::std::option::Option;
 
+// docs:start:map
 struct Map<V> {
     context: Context,
     storage_slot: Field,
     state_var_constructor: fn(Context, Field) -> V,
 }
+// docs:end:map
 
 impl<V> Map<V> {
+    // docs:start:new
     fn new(
         context: Context,
         storage_slot: Field,
@@ -20,12 +23,15 @@ impl<V> Map<V> {
             state_var_constructor,
         }
     }
+    // docs:end:new
 
+    // docs:start:at
     fn at(self, key: Field) -> V {
         // TODO(#1204): use a generator index for the storage slot
         let derived_storage_slot = dep::std::hash::pedersen([self.storage_slot, key])[0];
 
         let state_var_constructor = self.state_var_constructor;
         state_var_constructor(self.context, derived_storage_slot)
     }
+    // docs:end:at
 }

yarn-project/aztec-nr/aztec/src/state_vars/public_state.nr

@@ -4,12 +4,15 @@ use crate::oracle::storage::storage_write;
 use crate::types::type_serialization::TypeSerializationInterface;
 use dep::std::option::Option;
 
+// docs:start:public_state_struct
 struct PublicState<T, T_SERIALIZED_LEN> {
     storage_slot: Field,
     serialization_methods: TypeSerializationInterface<T, T_SERIALIZED_LEN>,
 }
+// docs:end:public_state_struct
 
 impl<T, T_SERIALIZED_LEN> PublicState<T, T_SERIALIZED_LEN> {
+    // docs:start:public_state_struct_new
     fn new(
         // Note: Passing the contexts to new(...) just to have an interface compatible with a Map.
         _: Context,
@@ -22,14 +25,19 @@ impl<T, T_SERIALIZED_LEN> PublicState<T, T_SERIALIZED_LEN> {
             serialization_methods,
         }
     }
+    // docs:end:public_state_struct_new
 
+    // docs:start:public_state_struct_read
     fn read(self) -> T {
         storage_read(self.storage_slot, self.serialization_methods.deserialize)
     }
+    // docs:end:public_state_struct_read
 
+    // docs:start:public_state_struct_write
     fn write(self, value: T) {
         let serialize = self.serialization_methods.serialize;
         let fields = serialize(value);
         storage_write(self.storage_slot, fields);
     }
+    // docs:end:public_state_struct_write
 }

yarn-project/aztec-nr/aztec/src/state_vars/set.nr

@@ -12,13 +12,16 @@ use crate::note::{
     utils::compute_note_hash_for_read_or_nullify,
 };
 
+// docs:start:struct
 struct Set<Note, N> {
     context: Context,
     storage_slot: Field,
     note_interface: NoteInterface<Note, N>,
 }
+// docs:end:struct
 
 impl<Note, N> Set<Note, N> {
+    // docs:start:new
     fn new(
         context: Context,
         storage_slot: Field,
@@ -31,7 +34,9 @@ impl<Note, N> Set<Note, N> {
             note_interface,
         }
     }
+    // docs:end:new
 
+    // docs:start:insert
     fn insert(self, note: &mut Note) {
         create_note(
             self.context.private.unwrap(),
@@ -40,7 +45,9 @@ impl<Note, N> Set<Note, N> {
             self.note_interface,
         );
     }
+    // docs:end:insert
 
+    // docs:start:insert_from_public
     fn insert_from_public(self, note: &mut Note) {
         create_note_hash_from_public(
             self.context.public.unwrap(),
@@ -49,7 +56,9 @@ impl<Note, N> Set<Note, N> {
             self.note_interface,
         );
     }
-
+    // docs:end:insert_from_public
+
+    // docs:start:assert_contains_and_remove
     fn assert_contains_and_remove(self, note: &mut Note, nonce: Field) {
         // Initialize header of note. Must be done before computing note hashes as it initializes the:
         // - storage slot (used in inner note hash)
@@ -77,7 +86,9 @@ impl<Note, N> Set<Note, N> {
             self.note_interface,
         );
     }
+    // docs:end:assert_contains_and_remove
 
+    // docs:start:assert_contains_and_remove_publicly_created
     // NOTE: this function should ONLY be used for PUBLICLY-CREATED note hashes!
     // WARNING: function will be deprecated/removed eventually once public kernel applies nonces.
     fn assert_contains_and_remove_publicly_created(self, note: &mut Note) {
@@ -114,7 +125,9 @@ impl<Note, N> Set<Note, N> {
             self.note_interface,
         );
     }
+    // docs:end:assert_contains_and_remove_publicly_created
 
+    // docs:start:remove
     fn remove(self, note: Note) {
         let context = self.context.private.unwrap();
         let note_hash = compute_note_hash_for_read_or_nullify(self.note_interface, note);
@@ -127,7 +140,9 @@ impl<Note, N> Set<Note, N> {
             self.note_interface,
         );
     }
+    // docs:end:remove
 
+    // docs:start:get_notes
     fn get_notes<FILTER_ARGS>(
         self,
         options: NoteGetterOptions<Note, N, FILTER_ARGS>,
@@ -141,11 +156,14 @@ impl<Note, N> Set<Note, N> {
         );
         opt_notes
     }
+    // docs:end:get_notes
 
+    // docs:start:view_notes
     unconstrained fn view_notes(
         self,
         options: NoteViewerOptions<Note, N>,
     ) -> [Option<Note>; MAX_NOTES_PER_PAGE] {
         view_notes(self.storage_slot, self.note_interface, options)
     }
+    // docs:end:view_notes
 }

yarn-project/aztec-nr/aztec/src/state_vars/singleton.nr

@@ -10,13 +10,16 @@ use crate::oracle;
 use dep::std::hash::pedersen_with_separator;
 use dep::std::option::Option;
 
+// docs:start:struct
 struct Singleton<Note, N> {
     context: Option<&mut PrivateContext>,
     storage_slot: Field,
     note_interface: NoteInterface<Note, N>,
 }
+// docs:end:struct
 
 impl<Note, N> Singleton<Note, N> {
+    // docs:start:new
     fn new(
         context: Context,
         storage_slot: Field,
@@ -29,12 +32,14 @@ impl<Note, N> Singleton<Note, N> {
             note_interface,
         }
     }
+    // docs:end:new
 
     unconstrained fn is_initialized(self) -> bool {
         let nullifier = self.compute_initialisation_nullifier();
         oracle::notes::is_nullifier_emitted(nullifier)
     }
 
+    // docs:start:initialize
     fn initialize(self, note: &mut Note) {
         let context = self.context.unwrap();
         // Nullify the storage slot.
@@ -43,6 +48,7 @@ impl<Note, N> Singleton<Note, N> {
 
         create_note(context, self.storage_slot, note, self.note_interface);
     }
+    // docs:end:initialize
 
     fn compute_initialisation_nullifier(self) -> Field {
         pedersen_with_separator(
@@ -51,6 +57,7 @@ impl<Note, N> Singleton<Note, N> {
         )[0]
     }
 
+    // docs:start:replace
     fn replace(self, new_note: &mut Note) {
         let context = self.context.unwrap();
         let prev_note = get_note(context, self.storage_slot, self.note_interface);
@@ -61,7 +68,9 @@ impl<Note, N> Singleton<Note, N> {
         // Add replacement note.
         create_note(context, self.storage_slot, new_note, self.note_interface);
     }
+    // docs:end:replace
 
+    // docs:start:get_note
     fn get_note(self) -> Note {
         let context = self.context.unwrap();
         let mut note = get_note(context, self.storage_slot, self.note_interface);
@@ -75,6 +84,7 @@ impl<Note, N> Singleton<Note, N> {
 
         note
     }
+    // docs:end:get_note
 
     unconstrained fn view_note(self) -> Note {
         let options = NoteViewerOptions::new().set_limit(1);

yarn-project/aztec-nr/aztec/src/types/type_serialization/field_serialization.nr

@@ -1,5 +1,6 @@
 use crate::types::type_serialization::TypeSerializationInterface;
 
+// docs:start:field_serialization
 global FIELD_SERIALIZED_LEN: Field = 1;
 
 fn deserializeField(fields: [Field; FIELD_SERIALIZED_LEN]) -> Field {
@@ -13,4 +14,5 @@ fn serializeField(value: Field) -> [Field; FIELD_SERIALIZED_LEN] {
 global FieldSerializationMethods = TypeSerializationInterface {
     deserialize: deserializeField,
     serialize: serializeField,
-};
+};
+// docs:end:field_serialization

yarn-project/aztec-nr/easy-private-state/src/easy_private_state.nr

@@ -42,7 +42,9 @@ impl EasyPrivateUint {
         let mut addend_note = ValueNote::new(addend as Field, owner);
 
         // Insert the new note to the owner's set of notes.
+        // docs:start:insert
         self.set.insert(&mut addend_note);
+        // docs:end:insert
 
         // Emit the newly created encrypted note preimages via oracle calls.
         let owner_key = get_public_key(owner);
@@ -58,8 +60,10 @@ impl EasyPrivateUint {
 
     // Very similar to `value_note::utils::decrement`.
     fn sub(self, subtrahend: u120, owner: Field) {
+        // docs:start:get_notes
         let options = NoteGetterOptions::with_filter(filter_notes_min_sum, subtrahend as Field);
         let maybe_notes = self.set.get_notes(options);
+        // docs:end:get_notes
 
         let mut minuend: u120 = 0;
         for i in 0..maybe_notes.len() {
@@ -71,7 +75,9 @@ impl EasyPrivateUint {
                 assert(note.owner == owner);
 
                 // Removes the note from the owner's set of notes.
+                // docs:start:remove
                 self.set.remove(note);
+                // docs:end:remove
 
                 minuend += note.value as u120;
             }

yarn-project/noir-contracts/src/contracts/docs_example_contract/src/main.nr

@@ -32,7 +32,9 @@ contract DocsExample {
         locked: PublicState<bool, BOOL_SERIALIZED_LEN>,
         queen: PublicState<Queen, QUEEN_SERIALIZED_LEN>,
         game_rules: ImmutableSingleton<RulesNote, RULES_NOTE_LEN>,
+        // docs:start:storage-singleton-declaration
         legendary_card: Singleton<CardNote, CARD_NOTE_LEN>,
+        // docs:end:storage-singleton-declaration
         cards: Set<CardNote, CARD_NOTE_LEN>,
         profiles: Map<Singleton<ProfileNote, PROFILE_NOTE_LEN>>,
     }
@@ -59,7 +61,9 @@ contract DocsExample {
                 // highlight-next-line:state_vars-ImmutableSingleton
                 game_rules: ImmutableSingleton::new(context, 3, RulesNoteMethods),
                 // highlight-next-line:state_vars-Singleton
+                // docs:start:start_vars_singleton
                 legendary_card: Singleton::new(context, 4, CardNoteMethods),
+                // docs:end:start_vars_singleton
                 // highlight-next-line:state_vars-Set
                 cards: Set::new(context, 5, CardNoteMethods),
                 // highlight-next-line:state_vars-MapSingleton