update page name, add info on custom note

Author: critesjosh

docs/docs/aztec/concepts/accounts/keys.md

@@ -106,7 +106,7 @@ When it comes to storing the signing key in a private note, there are several de
 
 #### Using Delayed Public Mutable state
 
-By [Delayed Public Mutable](../../../developers/guides/smart_contracts/data_types.md#delayed-public-mutable) we mean privately readable publicly mutable state.
+By [Delayed Public Mutable](../../../developers/guides/smart_contracts/storage_types.md#delayed-public-mutable) we mean privately readable publicly mutable state.
 
 To make public state accessible privately, there is a delay window in public state updates. One needs this window to be able to generate proofs client-side. This approach would not generate additional nullifiers and commitments for each transaction while allowing the user to rotate their key. However, this causes every transaction to now have a time-to-live determined by the frequency of the delayed mutable state, as well as imposing restrictions on how fast keys can be rotated due to minimum delays.
 

docs/docs/aztec/concepts/call_types.md

@@ -149,7 +149,7 @@ aztec = { git = "https://github.com/AztecProtocol/aztec-packages/", tag = "#incl
 
 Even with the router contract achieving good privacy is hard.
 For example, if the value being checked against is unique and stored in the contract's public storage, it's then simple to find private transactions that are using that value in the enqueued public reads, and therefore link them to this contract.
-For this reason it is encouraged to try to avoid public function calls and instead privately read [Shared State](../../developers/guides/smart_contracts/data_types.md#delayed-public-mutable) when possible.
+For this reason it is encouraged to try to avoid public function calls and instead privately read [Shared State](../../developers/guides/smart_contracts/storage_types.md#delayed-public-mutable) when possible.
 
 ### Public Execution
 

docs/docs/developers/guides/smart_contracts/common_patterns.md

@@ -39,7 +39,7 @@ Note - you could also create a note and send it to the user. The problem is ther
 
 ### Reading public storage in private
 
-You can read public storage in private domain by leveraging the private getters of `PublicImmutable` (for values that never change) and `DelayedPublicMutable` (for values that change infrequently, see [delayed public mutable state](./data_types.md#delayed-public-mutable) for details) state variables.
+You can read public storage in private domain by leveraging the private getters of `PublicImmutable` (for values that never change) and `DelayedPublicMutable` (for values that change infrequently, see [delayed public mutable state](./storage_types.md#delayed-public-mutable) for details) state variables.
 Values that change frequently (`PublicMutable`) cannot be read in private as for those we need access to the tip of the chain and only a sequencer has access to that (and sequencer executes only public functions).
 
 E.g. when using `PublicImmutable`

…s/guides/smart_contracts/custom_types.md …ers/guides/smart_contracts/note_types.mddocs/docs/developers/guides/smart_contracts/custom_types.md renamed to docs/docs/developers/guides/smart_contracts/note_types.md docs/docs/developers/guides/smart_contracts/custom_types.md renamed to docs/docs/developers/guides/smart_contracts/note_types.md

@@ -1,9 +1,9 @@
 ---
-title: Custom Types
+title: Note Types
 tags: [contracts, notes]
 sidebar_position: 3
 keywords: [implementing note, note]
-description: Learn how to implement custom note types in your Aztec smart contracts.
+description: Learn about note types and how to implement custom note types in your Aztec smart contracts.
 ---
 
 Notes are the fundamental data structure in Aztec when working with private state. Using Aztec.nr, developers can define note types which allow flexibility in how notes are stored and nullified.
@@ -14,9 +14,7 @@ For example, if you are developing a card game, you may want to store multiple p
 
 If you want to work with values, addresses or integers, you can check out [ValueNote](#valuenote), or [AddressNote](#addressnote).
 
-## Define a note type
-
-You will likely want to define your note in a new file and import it into your contract.
+## Standard Note Type
 
 A note type can be defined with the macro `#[note]` used on a struct:
 
@@ -38,6 +36,7 @@ This would work since the nullifier would be unique and only the note recipient
 However, if we did this, the sender could also derive the nullifier off-chain and monitor the nullifier tree for its inclusion, allowing them to determine when a note has been spent.
 This would leak privacy.
 
+
 ## Examples
 
 Address notes hold one main property of the type `AztecAddress`. It also holds `owner` and `randomness`, similar to other note types.
@@ -124,6 +123,14 @@ For example:
 
 The `decrement` function works similarly except the `amount` is the number that the value will be decremented by, and it will fail if the sum of the selected notes is less than the amount.
 
+### Custom Note Type
+
+Using the `#[custom_note]` macro allows you to define your own note hash and nullifier schemes for your notes, rather than using the default poseidon2 hash of the note to generate the note hash or using the note owners nullifier key to generate a nullifier.
+
+The TransparentNote in an example token contract demonstrates how you can generate a custom note hash and nullifiers.
+
+#include_code transparent_note_impl noir-projects/noir-contracts/contracts/app/token_blacklist_contract/src/types/transparent_note.nr rust
+
 ## Further reading
 
 - [What is `#[note]` actually doing? + functions such as serialize() and deserialize()](../../../aztec/smart_contracts/functions/attributes.md#implementing-notes)

docs/docs/developers/guides/smart_contracts/storage.md

@@ -25,4 +25,4 @@ The `Context` parameter is injected into storage and contract functions. It prov
 
 :::
 
-Read more about the data types available in the [Data Types](./data_types.md) page.
+Read more about the data types available in the [Data Types](./storage_types.md) page.

…ers/guides/smart_contracts/data_types.md …/guides/smart_contracts/storage_types.mddocs/docs/developers/guides/smart_contracts/data_types.md renamed to docs/docs/developers/guides/smart_contracts/storage_types.md docs/docs/developers/guides/smart_contracts/data_types.md renamed to docs/docs/developers/guides/smart_contracts/storage_types.md

@@ -1,10 +1,12 @@
 ---
-title: Data Types
+title: Storage Types
 sidebar_position: 2
 tags: [data-types, smart-contracts]
-description: Learn about the data types available in Aztec.nr.
+description: Learn about how data is stored in Aztec contracts.
 ---
 
+Interacting with the protocol in a reliable, private manner is simplified by using the storage types described below, provided by the Aztec.nr library for writing contracts.
+
 ## Map
 
 A `map` is a state variable that "maps" a key to a value. It can be used with private or public storage variables.
@@ -57,15 +59,15 @@ To simplify the experience of writing private state, Aztec.nr provides three dif
 
 These three structs abstract-away many of Aztec's protocol complexities, by providing intuitive methods to modify notes in the utxo tree in a privacy-preserving way.
 
-Unlike public state variables, which can be arbitrary types, private state variables operate on `NoteType`. See [custom types](./custom_types.md) for more information about how to define your own note types.
+Unlike public state variables, which can be arbitrary types, private state variables operate on `NoteType`. See [Note Types](./note_types.md) for more information about how to define your own note types.
 
 Notes are the fundamental elements of private state.
 
 ### PrivateMutable
 
 PrivateMutable is a private state variable that is unique in a way. When a PrivateMutable is initialized, a note is created to represent its value. And the way to update the value is to destroy the current note, and create a new one with the updated value.
 
-Like for public state, we define the struct to have context and a storage slot. You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/state_vars/private_mutable.nr).
+Like for public state, we define the struct to have context and a storage slot. You can view the implementation [here](https://github.com/AztecProtocol/aztec-packages/blob/master/noir-projects/aztec-nr/aztec/src/state_vars/private_mutable.nr).
 
 An example of `PrivateMutable` usage in the account contracts is keeping track of public keys. The `PrivateMutable` is added to the `Storage` struct as follows:
 
@@ -103,12 +105,18 @@ An unconstrained method to check whether the PrivateMutable has been initialized
 
 #### `replace`
 
-To update the value of a `PrivateMutable`, we can use the `replace` method. The method takes a new note as input, and replaces the current note with the new one. It emits a nullifier for the old value, and inserts the new note into the data tree.
+To update the value of a `PrivateMutable`, we can use the `replace` method. The method takes a new note as input and replaces the current note with the new one. It emits a nullifier for the old value, and inserts the new note into the data tree.
 
 An example of this is seen in a example card game, where we create a new note (a `CardNote`) containing some new data, and replace the current note with it:
 
 #include_code state_vars-PrivateMutableReplace /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/main.nr rust
 
+:::info
+
+Calling `emit(encode_and_encrypt_note())` on the `replace` method will encrypt the new note and post it to the data availability layer so that the note information is retrievable by the recipient.
+
+:::
+
 If two people are trying to modify the PrivateMutable at the same time, only one will succeed as we don't allow duplicate nullifiers! Developers should put in place appropriate access controls to avoid race conditions (unless a race is intended!).
 
 #### `get_note`
@@ -151,6 +159,12 @@ Set the value of an PrivateImmutable by calling the `initialize` method:
 
 #include_code initialize-private-mutable /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/main.nr rust
 
+:::info
+
+Calling `emit(encode_and_encrypt_note())` on `initialize` will encrypt the new note and post it to the data availability layer so that the note information is retrievable by the recipient.
+
+:::
+
 Once initialized, an PrivateImmutable's value remains unchangeable. This method can only be called once.
 
 #### `is_initialized`
@@ -175,21 +189,11 @@ Functionally similar to `get_note`, but executed unconstrained and can be used b
 
 ### PrivateSet
 
-`PrivateSet` is used for managing a collection of notes. All notes in a `PrivateSet` are of the same `NoteType`. But whether these notes all belong to one entity, or are accessible and editable by different entities, is up to the developer. The set is a collection of notes inserted into the data-tree, but notes are never removed from the tree itself, they are only nullified.
-
-You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/private_set.nr).
-
-And can be added to the `Storage` struct as follows. Here adding a set for a custom note.
+`PrivateSet` is used for managing a collection of notes. All notes in a `PrivateSet` are of the same `NoteType`. But whether these notes all belong to one entity, or are accessible and editable by different entities, is up to the developer.
 
-#include_code storage-set-declaration /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/main.nr rust
+For example, adding a mapping of private NFTs to storage, indexed by `AztecAddress`:
 
-#### `new`
-
-The `new` method tells the contract how to operate on the underlying storage.
-
-We can initialize the set as follows:
-
-#include_code storage-set-init /noir-projects/noir-contracts/contracts/docs/docs_example_contract/src/main.nr rust
+#include_code private_map /noir-projects/noir-contracts/contracts/app/nft_contract/src/main.nr rust
 
 #### `insert`
 
@@ -199,6 +203,12 @@ A hash of the note will be generated, and inserted into the note hash tree, allo
 
 #include_code insert /noir-projects/aztec-nr/easy-private-state/src/easy_private_uint.nr rust
 
+:::info
+
+Calling `emit(encode_and_encrypt_note())` on `insert` will encrypt the new note and post it to the data availability layer so that the note information is retrievable by the recipient.
+
+:::
+
 #### `insert_from_public`
 
 The `insert_from_public` allow public function to insert notes into private storage. This is very useful when we want to support private function calls that have been initiated in public.
@@ -243,20 +253,16 @@ This function requires a `NoteViewerOptions`. The `NoteViewerOptions` is essenti
 
 ### PublicMutable
 
-The `PublicMutable` (formerly known as `PublicState`) struct is generic over the variable type `T`.
+The `PublicMutable` struct is generic over the variable type `T`.
 
 The struct contains a `storage_slot` which, similar to Ethereum, is used to figure out _where_ in storage the variable is located.
 
 For a version of `PublicMutable` that can also be read in private, head to [`DelayedPublicMutable`](#delayed-public-mutable).
 
 :::info
-An example using a larger struct can be found in the [lending example (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts/contracts/app/lending_contract)'s use of an [`Asset` (GitHub link)](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/app/lending_contract/src/asset.nr).
+An example using a larger struct can be found in the [lending example](https://github.com/AztecProtocol/aztec-packages/tree/master/noir-projects/noir-contracts/contracts/app/lending_contract)'s use of an [`Asset`](https://github.com/AztecProtocol/aztec-packages/tree/#include_aztec_version/noir-projects/noir-contracts/contracts/app/lending_contract/src/asset.nr).
 :::
 
-#### `new`
-
-When declaring the storage for `T` as a persistent public storage variable, we use the `PublicMutable::new()` constructor. As seen below, this takes the `storage_slot` and the `serialization_methods` as arguments along with the `Context`, which in this case is used to share interface with other structures. You can view the implementation [here (GitHub link)](https://github.com/AztecProtocol/aztec-packages/blob/#include_aztec_version/noir-projects/aztec-nr/aztec/src/state_vars/public_mutable.nr).
-
 ##### Single value example
 
 To add `admin` public state variable into our storage struct, we can define it as:

docs/docs/developers/reference/environment_reference/cli_wallet_reference.md

@@ -11,7 +11,7 @@ For development, it may be useful to deploy, transact, or create notes in a non-
 - Deploying contracts
 - Sending transactions
 - Bridging L1 "Fee Juice" into Aztec
-- Pushing arbitrary [notes](../../guides/smart_contracts/custom_types.md) to your PXE
+- Pushing arbitrary [notes](../../guides/smart_contracts/note_types.md) to your PXE
 - Creating [authwits](../../guides/smart_contracts/authwit.md)
 - Aliasing info and secrets for further usage
 - Proving your transactions and profile gate counts

docs/docs/developers/tutorials/contract_tutorials/nft_contract.md

@@ -174,7 +174,7 @@ Below the dependencies, paste the following Storage struct:
 
 ## Custom Notes
 
-The contract storage uses a [custom note](../../../guides/smart_contracts/custom_types.md) implementation. Custom notes are useful for defining your own data types. You can think of a custom note as a "chunk" of private data, the entire thing is added, updated or nullified (deleted) together. This NFT note is very simple and stores only the owner and the `token_id` and uses `randomness` to hide its contents.
+The contract storage uses a [custom note](../../../guides/smart_contracts/note_types.md) implementation. Custom notes are useful for defining your own data types. You can think of a custom note as a "chunk" of private data, the entire thing is added, updated or nullified (deleted) together. This NFT note is very simple and stores only the owner and the `token_id` and uses `randomness` to hide its contents.
 
 Randomness is required because notes are stored as commitments (hashes) in the note hash tree. Without randomness, the contents of a note may be derived through brute force (e.g. without randomness, if you know my Aztec address, you may be able to figure out which note hash in the tree is mine by hashing my address with many potential `token_id`s).
 

noir-projects/noir-contracts/contracts/app/token_blacklist_contract/src/types/transparent_note.nr

@@ -21,6 +21,7 @@ pub struct TransparentNote {
     secret_hash: Field,
 }
 
+// docs:start:transparent_note_impl
 impl NoteHash for TransparentNote {
     fn compute_note_hash(self, storage_slot: Field) -> Field {
         let inputs = self.pack().concat([storage_slot]);
@@ -51,6 +52,7 @@ impl NoteHash for TransparentNote {
         self.compute_nullifier(zeroed(), note_hash_for_nullify)
     }
 }
+// docs:end:transparent_note_impl
 
 impl TransparentNote {
     // CONSTRUCTORS