diff --git a/components/Starknet/modules/ROOT/nav.adoc b/components/Starknet/modules/ROOT/nav.adoc index 53c5931177..f995d72bcf 100644 --- a/components/Starknet/modules/ROOT/nav.adoc +++ b/components/Starknet/modules/ROOT/nav.adoc @@ -1,3 +1,4 @@ About Starknet * xref:index.adoc[] +* xref:notational-conventions.adoc[] diff --git a/components/Starknet/modules/ROOT/pages/notational-conventions.adoc b/components/Starknet/modules/ROOT/pages/notational-conventions.adoc new file mode 100644 index 0000000000..f4c0000b95 --- /dev/null +++ b/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. + +| `` +| 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` + +| stem:[\text{string_in_math_notation}] +| A normal (non-italics) serif typeface 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. + + +|=== diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Cryptography/hash-functions.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Cryptography/hash-functions.adoc index e0aa79dbce..6ca2feb01c 100644 --- a/components/Starknet/modules/architecture_and_concepts/pages/Cryptography/hash-functions.adoc +++ b/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] ++++ diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Network_Architecture/fee-mechanism.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Network_Architecture/fee-mechanism.adoc index c155eb25c9..a230c1fe97 100644 --- a/components/Starknet/modules/architecture_and_concepts/pages/Network_Architecture/fee-mechanism.adoc +++ b/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 \\ diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/starknet-events.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/starknet-events.adoc index 466a0ed2fb..7314ede4bc 100644 --- a/components/Starknet/modules/architecture_and_concepts/pages/Smart_Contracts/starknet-events.adoc +++ b/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[] \ No newline at end of file