docs: Add Notational conventions topic

components/Starknet/modules/ROOT/nav.adoc

@@ -1,3 +1,4 @@
 About Starknet
 
 * xref:index.adoc[]
+* xref:notational-conventions.adoc[]

components/Starknet/modules/ROOT/pages/notational-conventions.adoc

@@ -0,0 +1,43 @@
+[id="notational-conventions"]
+= Notational conventions
+
+[cols="1,2", stripes=even]
+|===
+| Notation | Explanation
+
+| *bold* a| * Indicates GUI elements, such as button text or menu names.
+* Highlights text for added importance or to draw attention to it.
+
+| _italics_
+| Indicates the first occurrence of a new term, titles of documents or topics, and user-supplied or variable values.
+
+| `monospace` | Indicates code, commands, file paths, or other text that should be displayed in a fixed-width font to differentiate it from the surrounding text.
+
+| `<item>`
+| Indicates user-supplied or variable values in code, commands, file paths, or other text that should be displayed in a monospace font.
+
+Can also refer to generic types. For example: `List<felt252>`
+
+| stem:[\text{string_in_math_notation}]
+| Indicates a fixed element or constant specified in mathematical notation.
+
+| ...
+| An ellipsis indicates that the preceding element can repeat multiple times.
+
+| [item, ...]
+a| Square brackets indicate that the enclosed items are optional. Also can indicate a range of numbers, where the enclosed items are included. For example, in [0,100], 0 and 100 are part of the specified range.
+
+a| (item1, item2)
+| Parentheses indicate a range of numbers, where the enclosed items are not included. For example, in (0,100), 0 and 100 are _not_ part of the specified range.
+
+| item1 \| item2
+| A vertical bar (\|) indicates a choice between *item1* and *item2*.
+
+a| +{item1, item2}+
+| Curly brackets indicates a list or set of possible values.
+
+| /
+| A forward slash indicates a division operator or a path separator in URLs and file paths.
+
+
+|===

components/Starknet/modules/architecture_and_concepts/pages/Cryptography/hash-functions.adoc

@@ -1,6 +1,6 @@
 [id="hash_functions"]
 = Hash functions
-:stem: latexmath
+// :stem: latexmath
 
 [id="domain_and_range"]
 == Domain and range
@@ -9,14 +9,14 @@ All hashes outputs are eventually mapped to elements in stem:[$\mathbb{F}_P$], w
 
 There are three hash functions used throughout Starknet's specifications:
 
-* stem:[$sn\_keccak: \{0,1\}^* \rightarrow \mathbb{F}_P$]
-* stem:[$pedersen: \mathbb{F}_P^2\rightarrow\mathbb{F}_P$]
-* stem:[$poseidon: \mathbb{F}_P^*\rightarrow \mathbb{F}_P$]
+* stem:[$\text{sn_keccak}: \{0,1\}^* \rightarrow \mathbb{F}_P$]
+* stem:[$\text{pedersen}: \mathbb{F}_P^2\rightarrow\mathbb{F}_P$]
+* stem:[$\text{poseidon}: \mathbb{F}_P^*\rightarrow \mathbb{F}_P$]
 
 [id="starknet_keccak"]
 == Starknet Keccak
 
-Starknet Keccak, usually denoted by stem:[$sn\_keccak$], is defined as the first 250 bits of the Keccak256 hash. For Starknet Keccak, Keccak256 is augmented
+Starknet Keccak, usually denoted by stem:[$\text{sn_keccak}$], is defined as the first 250 bits of the Keccak256 hash. For Starknet Keccak, Keccak256 is augmented
 in order to fit into a field element.
 
 [id="pedersen_hash"]
@@ -42,7 +42,7 @@ where the low part consists of the low 248 bits of the element and the high part
 
 [stem]
 ++++
-h(a,b) = \left[shift\_point + a_{low} \cdot P_0 + a_{high} \cdot P1 + b_{low} \cdot P2  + b_{high} \cdot P3\right]_x
+h(a,b) = \left[\text{shift_point} + a_{low} \cdot P_0 + a_{high} \cdot P1 + b_{low} \cdot P2  + b_{high} \cdot P3\right]_x
 ++++
 
 where the values of the constants stem:[$shift\_point, P_0, P_1, P_2, P_3$] can be found in link:https://github.com/starkware-libs/cairo-lang/blob/master/src/starkware/crypto/signature/fast_pedersen_hash.py[fast_pedersen_hash.py^], and stem:[$[P\]_x$] denotes the stem:[$x$] coordinate of the point stem:[$P$].
@@ -60,16 +60,16 @@ A Poseidon hash of up to 2 elements is defined as follows.
 
 [stem]
 ++++
-poseidon_1(x) := \left[\text{hades_permutation}(x,0,1)\right]_0
+\text{poseidon_1}(x) := \left[\text{hades_permutation}(x,0,1)\right]_0
 ++++
 
 
 [stem]
 ++++
-poseidon_2(x,y) := \left[\text{hades_permutation}(x,y,2)\right]_0
+\text{poseidon_2}(x,y) := \left[\text{hades_permutation}(x,y,2)\right]_0
 ++++
 
-Where latexmath:[[\cdot\]_j] denotes taking the j'th coordinate of a tuple
+Where latexmath:[[\cdot\]_j] denotes taking the stem:[j]'th coordinate of a tuple.
 
 .Additional resources
 
@@ -96,7 +96,7 @@ h(...h(h(0, a_1),a_2),...,a_n),n)
 === Poseidon
 
 Let stem:[$\text{hades}:\mathbb{F}_P^3\rightarrow\mathbb{F}_P^3$] denote the Hades permutation, with Starknet's parameters, then given an array stem:[$a_1,...,a_n$] of stem:[$n$] field elements
-we define stem:[$poseidon(a_1,...,a_n)$] to be the first coordinate of stem:[$H(a_1,...,a_n;0,0,0)$], where:
+we define stem:[$\text{poseidon}(a_1,...,a_n)$] to be the first coordinate of stem:[$H(a_1,...,a_n;0,0,0)$], where:
 
 [stem]
 ++++

components/Starknet/modules/architecture_and_concepts/pages/Network_Architecture/fee-mechanism.adoc

@@ -19,11 +19,11 @@ The following formula describes the overall fee, stem:[F], for a transaction:
 [stem]
 ++++
 \begin{align}
-F  = \; & \text{gas_price}\cdot\Bigg(\max_k v_k w_k + \\
+F  = \; & gas\_price \cdot \Bigg(\max_k v_k w_k + \\
 & \quad + \; \text{message_calldata_cost}\cdot 3t + (\text{message_calldata_cost} + \text{l1_log_data_cost})\cdot \sum\limits_{i=1}^t q_i \; + \\
 & \quad + \; \left(\text{l1_storage_write_cost}+\text{log_message_to_l1_cost}\right)\cdot t + \; \\
 & \quad + \; \text{l2_payload_costs}\Bigg) + \\
-& \text{data_gas_price}\cdot\text{felt_size_in_bytes}\cdot\bigg(2(n-1)+2(m-1) + \ell +2D \bigg)
+& data\_gas\_price\cdot\text{felt_size_in_bytes}\cdot\bigg(2(n-1)+2(m-1) + \ell +2D \bigg)
 \end{align}
 ++++
 
@@ -61,7 +61,7 @@ The following formula describes the overall fee, stem:[F], for a transaction:
 [stem]
 ++++
 \begin{align}
-F  = \text{gas_price}\cdot&\Bigg(\max_k v_k w_k + \\
+F  = gas\_price\cdot&\Bigg(\max_k v_k w_k + \\
 & + \; \text{da_calldata_cost}\left(2(n-1)+2(m-1) + \ell + 2D + 3t + \sum\limits_{i=1}^t q_i\right)\\ 
 & - \; \text{contract_update_discount}\cdot (n-1) - 240 \\
 & + \;  \text{message_calldata_cost}\cdot 3t + (\text{message_calldata_cost} + \text{l1_log_data_cost})\cdot\sum\limits_{i=1}^t q_i \\

components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/starknet-events.adoc

@@ -1,6 +1,6 @@
 [id="events"]
 = Events
-:stem: latexmath
+:stem: latex
 
 A contract may emit events throughout its execution. Each event contains the following fields:
 
@@ -27,7 +27,7 @@ Transfer(12345, 12345, 1)
 ----
 
 
-The emit function emits an event with a single key, which is an identifier of the event, given by stem:[$\text{sn_keccak(event_name)}$], where stem:[$\text{event_name}$] is the ASCII encoding of the event's name and stem:[$\text{sn_keccak}$] is defined xref:../Cryptography/hash-functions.adoc#starknet_keccak[here].
+The emit function emits an event with a single key, which is an identifier of the event, given by stem:[$\text{sn_keccak}(event\_name)$], where stem:[$event\_name$] is the ASCII encoding of the event's name and stem:[$\text{sn_keccak}$] is defined xref:../Cryptography/hash-functions.adoc#starknet_keccak[here].
 
 To emit custom keys, one should use the low level `emit_event` system call:
 
@@ -69,13 +69,15 @@ message_received.emit(2, data, p)
 
 ====
 
-The emitted events are part of the xref:Network_Architecture/transaction-life-cycle.adoc#transaction-receipt[transaction receipt].
+The emitted events are part of the transaction receipt. For more information, see xref:architecture_and_concepts:Network_Architecture/transaction-life-cycle.adoc#transaction-receipt[Transaction receipt].
 
 [id="event_abi"]
-== Event ABI
+== Event definition in the ABI
 
-The event definition appears in the contract's ABI. It contains the list of data fields (name and type) and the list of the custom keys (that is, all keys except the event identifier discussed above). Below is an example of an event inside the ABI:
+The event definition appears in the contract's ABI. It contains the list of data fields, with the name and type for each, and the list of the custom keys, that is, all keys except the event identifier discussed above. Below is an example of an event inside the ABI:
 
+[#example_of_an_event_in_the_abi]
+.Example of an event in the ABI
 [source,json]
 ----
 {
@@ -107,12 +109,18 @@ The event hash is given by:
 
 [stem]
 ++++
-h(h(h(h(0,\text{from_address}),\text{keys_hash}),\text{data_hash}),3)
+h(h(h(h(0,from\_address),keys\_hash),data\_hash),3)
 ++++
 
 Where:
 
-* stem:[$\text{keys_hash}$], stem:[$\text{data_hash}$] are the hashes of the keys list and data list correspondingly (see xref:../Cryptography/hash-functions.adoc#array_hashing[array hashing]).
-* stem:[$h$] is the xref:../Cryptography/hash-functions.adoc#pedersen_hash[Pedersen] hash function.
+* stem:[$keys\_hash$] and stem:[$data\_hash$] are the hashes of the keys list and data list respectively. For more information, see xref:../Cryptography/hash-functions.adoc#array_hashing[Array hashing].
+* stem:[$h$] is the Pedersen hash function.
 
 The event hashes are included in the xref:Network_Architecture/header.adoc[`event_commitment`] field of a block.
+
+== Additional resources
+
+* xref:architecture_and_concepts:Cryptography/hash-functions.adoc#array_hashing[]
+* xref:architecture_and_concepts:Cryptography/hash-functions.adoc#pedersen_hash[Pedersen hash function]
+* The `event_commitment` field in xref:Network_Architecture/header.adoc[]