Apply suggestions from code review

Co-authored-by: Jan Beneš <[email protected]>

docs/docs/concepts/foundation/state_model/storage_slots.md

@@ -26,9 +26,9 @@ For structs and arrays, we are logically using a similar storage slot computatio
 
 ## Private State Slots - Slots aren't real
 
-Private storage is a different beast. As you might remember from [State Model](./main.md), private state is stored in a append-only tree where each leaf is a note. Being append-only, mean that leafs are never updated or deleted, instead a nullifier is emitted to signify that some note is no longer valid. A major reason we used this tree, is that lookups at a specific storage slot don't really make sense in the context of private state. If you could look up a specific address balance just by looking at the storage slot, even if encrypted you would be able to see to see it changing! That is not good privacy. 
+Private storage is a different beast. As you might remember from [State Model](./main.md), private state is stored in a append-only tree where each leaf is a note. Being append-only, mean that leafs are never updated or deleted, instead a nullifier is emitted to signify that some note is no longer valid. A major reason we used this tree, is that lookups at a specific storage slot don't really make sense in the context of private state. If you could look up a specific address balance just by looking at the storage slot, even if encrypted you would be able to see it changing! That is not good privacy. 
 
-Following this. The storage slot as we know if it don't really exists. The leafs of the private data tree are just commitments to content (think of it as a hash of its content). 
+Following this. The storage slot as we know it doesn't really exists. The leafs of the private data tree are just commitments to content (think of it as a hash of its content). 
 
 Nevertheless, the concept of a storage slot is very useful when writing applications, since it allows us to reason about distinct and disjoint pieces of data. For example we can say that the balance of an account is stored in a specific slot and that the balance of another account is stored in another slot with the total supply stored in some third slot. By making sure that these slots are disjoint, we can be sure that the balances are not mixed up and that someone cannot use the total supply as their balance. 
 
@@ -50,7 +50,7 @@ The private variable wrappers set and singletons in Aztec.nr include this to mak
 
 When reading the values for these notes, the application circuit can then constrain it to only read notes with a specific logical storage slot.
 
-To ensure that one contract's cannot insert storage that other contracts believe is theirs we do a second siloing by hashing the the `commitment` with the contract address. 
+To ensure that one contract's cannot insert storage that other contracts believe is theirs we do a second siloing by hashing the `commitment` with the contract address. 
 
 ```rust
 siloed_commitment = H(contract_address, commitment);

docs/docs/dev_docs/contracts/syntax/storage/storage_slots.md

@@ -2,15 +2,16 @@
 title: Storage slots
 ---
 
-From the description of [storage slot in concepts](./../../../../concepts/foundation/state_model/storage_slots.md) you will get an idea around the logic of storage slots. In this section we will go into more detail to walk through an entire example of how storage slots are computed for private state to improve that intuition. Recall, that storage slots are only a logical construct in private, and are not "actually" used for lookups, but rather as a value to constrain against.
+From the description of [storage slot in concepts](./../../../../concepts/foundation/state_model/storage_slots.md) you will get an idea around the logic of storage slots. In this section we will go into more detail and walk through an entire example of how storage slots are computed for private state to improve our storage slot intuition. Recall, that storage slots are only a logical construct in the private domain, and are not "actually" used for lookups, but rather just as a value to constrain against.
 
 For the case of the example, we will look at what is inserted into the private data tree when adding a note in the Token contract. Specifically, we are looking at the last part of the `transfer` function:
 
 #include_code increase_private_balance yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust
 
-This function is creating a new note and inserting it note into the balance set of the recipient `to`. Recall that to ensure privacy, only the note commitment is really inserted into the private data tree. To share the contents of the note with `to` the contract can emit an encrypted log (which this one does), or it can require an out-of-band data transfer sharing the information. Below, we will walk through the steps of how the note commitment is computed and inserted into the tree. For this, we don't care about the encrypted log, so we are going to ignore that part of the function call for now. 
+This function is creating a new note and inserting it into the balance set of the recipient `to`. Recall that to ensure privacy, only the note commitment is really inserted into the private data tree. To share the contents of the note with `to` the contract can emit an encrypted log (which this one does), or it can require an out-of-band data transfer sharing the information. Below, we will walk through the steps of how the note commitment is computed and inserted into the tree. For this, we don't care about the encrypted log, so we are going to ignore that part of the function call for now. 
 
-Outlining it in more detail below as a sequence diagram, we can see how the calls make their way down the stack, and in the end is computing a siloed note hash in the kernel. 
+Outlining it in more detail below as a sequence diagram, we can see how the calls make their way down the stack.
+In the end a siloed note hash is computed in the kernel. 
 
 :::info
 Some of the syntax below is a little butchered to make it easier to follow variables without the full code.
@@ -52,7 +53,7 @@ Where the `map_slot` is the slot specified in `Storage::init`, recall:
 
 #include_code storage_balances_init yarn-project/noir-contracts/src/contracts/token_contract/src/main.nr rust
 
-And `to` is the actor to receive the note, `amount` of the note and `randomness` is the randomness used to make the note hiding. Without the `randomness` the note could could just as well be plaintext.
+And `to` is the actor who receives the note, `amount` of the note and `randomness` is the randomness used to make the note hiding. Without the `randomness` the note could could just as well be plaintext (computational cost of a preimage attack would be trivial in such a case).
 
 :::info
 Beware that this hash computation is what the aztec.nr libraries is doing, and not strict requirements by the network (only the kernel computation is).

docs/docs/dev_docs/tutorials/writing_dapp/contract_interaction.md

@@ -93,7 +93,7 @@ At the time of this writing, there are no events emitted when new private notes
 
 ## Working with public state
 
-While they are [fundamentally differently](../../../concepts/foundation/state_model/main.md), the API for working with private and public functions and state from `aztec.js` is equivalent. To query the balance in public tokens for our user accounts, we can just call the `publicBalanceOf` view function in the contract:
+While [private and public state](../../../concepts/foundation/state_model/main.md) are fundamentally different, the API for working with private and public functions and state from `aztec.js` is equivalent. To query the balance in public tokens for our user accounts, we can just call the `balance_of_public` view function in the contract:
 
 #include_code showPublicBalances yarn-project/end-to-end/src/sample-dapp/index.mjs javascript