From 79115d27e20e076dff54ffe12e3cd5e226a4fb68 Mon Sep 17 00:00:00 2001 From: Steve Goodman <39279277+stoobie@users.noreply.github.com> Date: Mon, 18 Mar 2024 18:17:10 +0200 Subject: [PATCH 1/6] Added sentence clarifying that a portion of fees paid are converted by the sequencer to ETH to pay L1 gas costs. (#1189) --- .../pages/Economics-of-Starknet.adoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Economics-of-Starknet.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Economics-of-Starknet.adoc index 54e634492f..c78a5e9401 100644 --- a/components/Starknet/modules/architecture_and_concepts/pages/Economics-of-Starknet.adoc +++ b/components/Starknet/modules/architecture_and_concepts/pages/Economics-of-Starknet.adoc @@ -16,9 +16,11 @@ Starknet operates as a Layer 2 (L2) network on top of Ethereum. Today, Starknet [#purpose_of_the_token] == The purpose of the STRK token -The Starknet token is the mechanism for paying fees to enable operation of the network, maintaining and securing the network by enabling staking for consensus, and deciding on Starknet’s values and technology goals by voting for governance proposals. +STRK is the mechanism for paying fees to enable operation of the network, maintaining and securing the network by enabling staking for consensus, and deciding on Starknet’s values and technology goals by voting for governance proposals. -* *Transaction fees:* Originally, fees in Starknet were paid only in Ether (ETH). As of v.0.13.0, fees for transactions on the network can be paid for using the Starknet token, as well as Ether. +* *Transaction fees:* Originally, fees in Starknet were paid only in Ether (ETH). As of v.0.13.0, fees for transactions on the network can be paid using STRK, as well as ETH. ++ +A portion of the fees paid in STRK are converted to ETH by the receiving sequencer, in order to cover Ethereum L1 gas costs, which, due to the specifications of the Ethereum protocol, must be paid in ETH. * *Staking:* Certain services that are critical to the liveness and security of Starknet may require the staking of Starknet tokens. These services might be offered by multiple providers, and could include sequencing, reaching temporary L2 consensus before L1 finality is reached, STARK-proving services, and data availability provisioning, to name a few examples. These https://starkware.co/resource/starknet-decentralization-a-roadmap-in-broad-strokes/[protocol changes] are still under discussion within the larger governance community and are targeted for https://starkware.co/resource/starknet-decentralization-a-roadmap-in-broad-strokes/[2024 -2025]. From 2f7801c941ee29e7cb0a8d218092fd254df6e260 Mon Sep 17 00:00:00 2001 From: ArielElp <86294909+ArielElp@users.noreply.github.com> Date: Thu, 21 Mar 2024 15:17:12 +0200 Subject: [PATCH 2/6] docs: fix l2 --> l1 message pricing (#1192) * fix message pricing * fix typos --- .../Network_Architecture/fee-mechanism.adoc | 48 ++++++++++++------- 1 file changed, 31 insertions(+), 17 deletions(-) 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 88ddde2bb6..1b7a49927c 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 @@ -20,9 +20,8 @@ The following formula describes the overall fee, stem:[F], for a transaction: ++++ \begin{align} F = \; & \text{gas_price}\cdot\Bigg(\max_k v_k w_k + \\ -& \quad + \; \text{da_calldata_cost}\left(3t + \sum\limits_{i=1}^t q_i\right) + \\ -& \quad + \; \text{message_calldata_cost}\cdot\left(3t + \sum\limits_{i=1}^t q_i\right) + \\ -& \quad + \; \text{l1_storage_write_cost}\cdot t + \\ +& \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) \end{align} @@ -39,13 +38,11 @@ For more information see xref:#calculation_of_computation_costs[Calculation of c * stem:[$t$] is the number of L2->L1 messages sent, where the corresponding payload sizes are denoted by stem:[$q_1,...,q_t$]. * stem:[$\ell$] is the number of contracts whose class was changed, which happens on contract deployment and when applying the `replace_class` syscall. * stem:[$D$] is 1 if the transaction is of type `DECLARE` and 0 otherwise. Declare transactions need to post on L1 the new class hash and compiled class hash which are added to the state. -* stem:[$\text{da_calldata_cost}$] is 551 gas per 32-byte word. This cost is derived as follows: -+ -** 512 gas per 32-byte word for calldata. -** ~100 gas for onchain hashing that happens for every sent word. -** a 10% discount, because the sequencer does not incur additional costs for repeated updates to the same storage slot within a single block. -* stem:[$\text{message_calldata_cost}$] is 512 gas per 32-byte word. For more details, see xref:#l_2-l_1_messages[]. -* stem:[$\text{l1_storage_write_cost}$] is the cost of writing a to a new storage slot on Ethereum, which is 20,000 gas. The reason it appears here is that the hash of an L2->L1 message needs to be recorded on the Starknet core contract on L1. +* L2->L1 messages related constants (for more details, see xref:#l_2-l_1_messages[]): +** stem:[$\text{message_calldata_cost}$] is 1124 gas per 32-byte word. +** stem:[$\text{l1_log_data_cost}$] is 256 gas. +** stem:[$\text{l1_storage_write_cost}$] is the cost of writing to a new storage slot on Ethereum, which is 20,000 gas. +** stem:[$\text{log_message_to_l1_cost}$] is 1637 gas. * stem:[$\text{l2_payload_costs}$] is the gas cost of data sent over L2. This includes calldata, code, and event emission. For more details see xref:#l2_calldata[]. * stem:[$\text{felt_size_in_bytes}$] is 32, which is the number of bytes required to encode a single STARK field element. @@ -62,15 +59,23 @@ The following formula describes the overall fee, stem:[F], for a transaction: F = \text{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\left(3t + \sum\limits_{i=1}^t q_i\right) \\ -& + \; \text{l1_storage_write_cost}\cdot t \\ +& + \; \text{message_calldata_cost}\cdot 3t + (\text{message_calldata_cost} + \text{l1_log_data_cost})\cdot\sum\limits_{i=1}^t q_i \\ +& + \; \left(\text{l1_storage_write_cost}+\text{log_message_to_l1_cost}\right)\cdot t \\ & + \; \text{l2_payload_costs}\Bigg) \end{align} ++++ where: -* stem:[$v, w, n, m, t, \ell, \text{da_calldata_cost}, \text{message_calldata_cost}, \text{l1_storage_write_cost}, D, \text{l2_payload_costs}$] are defined in the same manner as in the blob-based formula above. +* The following constants are defined in the same manner as in the blob-based formula: +** stem:[$v, w, n, m, t, \ell, D$] +** stem:[$\text{message_calldata_cost}, \; \text{l1_log_data_cost}, \; \text{log_message_to_l1_cost}, \; \text{l1_storage_write_cost}$] +** stem:[$\text{l2_payload_costs}$] +* stem:[$\text{da_calldata_cost}$] is 551 gas per 32-byte word. This cost is derived as follows: ++ +** 512 gas per 32-byte word for calldata. +** ~100 gas for onchain hashing that happens for every sent word. +** a 10% discount, because the sequencer does not incur additional costs for repeated updates to the same storage slot within a single block. * stem:[$240$] is the gas discount for updating the sender's balance, for the derivation of this number see xref:#storage_updates[]. * stem:[$\text{contract_update_discount}$] is 312 gas, for the derivation of this discount see xref:#storage_updates[]. @@ -263,14 +268,23 @@ When a transaction that raises the `send_message_to_l1` syscall is included in a Consequently, the gas cost associated with a single L2→L1 message is: + [stem] ++++ -\text{storage_write_cost} + \left(\text{da_calldata_cost} + \text{message_calldata_cost}\right)\cdot\left(3+\text{payload_size}\right) +\begin{align} +\text{MESSAGE_COST} = & \; \text{message_calldata_cost}\cdot\left(3+\text{payload_size}\right) \; + \\ +& + \text{l1_log_data_cost}\cdot\text{payload_size} \; + \\ +& + \text{log_message_to_l1_cost} \; + \\ +& + \text{l1_storage_write_cost} +\end{align} ++++ -Where stem:[$\text{da_calldata_cost}$] is 551 gas, and stem:[$\text{message_calldata_cost}$] is 512 gas. -Messages appear twice in the fee formula, and pay both in stem:[$\text{da_calldata_cost}$] and stem:[$\text{message_calldata_cost}$], because -they are sent to Ethereum twice: once to the STARK verifier contract, where the additional hashing cost is incurred, and once when it is sent to the Starknet Core Contract as part of the state update transaction. +Where: + +* stem:[$\text{message_calldata_cost}$] is 1124 gas. This is the sum of the 512 gas paid to the core contract on submitting the state update, and 612 gas paid for the submitting of the same word to the verifier contract (which incurs ~100 additional gas for hashing). That is, messages are sent to Ethereum twice. +* stem:[$\text{log_message_to_l1_cost}$] is 1637 gas. This is the fixed cost involved in emitting a `LogMessageToL1` event. This event has two topics and a data array, which adds two data words to the event, resulting in a total of stem:[$375+2\cdot 375+2\cdot 256$] gas (log opcode cost, topic cost, and two data words cost). +* stem:[$\text{l1_log_data_cost}$] is 256 gas, which is paid for every payload element during the emission of the `LogMessageToL1` event. +* stem:[$\text{l1_storage_write_cost}$] is 20,000 gas per message which is paid in order to store the message hash on the Starknet core contract. This recording of the message is what later enables the intended L1 contract to consume the message. [#deployed_contracts] === Onchain data: Deployed contracts From af0743fdf8e0b87ecf9761252cb39ec0488395cb Mon Sep 17 00:00:00 2001 From: Steve Goodman <39279277+stoobie@users.noreply.github.com> Date: Thu, 21 Mar 2024 22:33:27 +0200 Subject: [PATCH 3/6] feat: Add glossary (#1095) * Add glossary. * Update playbook.yml * Minor edit to trigger preview * minor edit * Restored common-docs branch to HEAD --- components/Starknet/antora.yml | 1 + components/Starknet/modules/ROOT/nav_glossary.adoc | 1 + components/Starknet/modules/ROOT/pages/glossary.adoc | 7 +++++++ playbook.yml | 3 ++- 4 files changed, 11 insertions(+), 1 deletion(-) create mode 100644 components/Starknet/modules/ROOT/nav_glossary.adoc create mode 100644 components/Starknet/modules/ROOT/pages/glossary.adoc diff --git a/components/Starknet/antora.yml b/components/Starknet/antora.yml index 1ef5fcedd5..4880454932 100644 --- a/components/Starknet/antora.yml +++ b/components/Starknet/antora.yml @@ -8,3 +8,4 @@ nav: - modules/architecture_and_concepts/nav.adoc # Architecture and concepts - modules/cli/nav.adoc # Starknet CLI - modules/tools/nav.adoc # Developer tools and resources + - modules/ROOT/nav_glossary.adoc # The glossary \ No newline at end of file diff --git a/components/Starknet/modules/ROOT/nav_glossary.adoc b/components/Starknet/modules/ROOT/nav_glossary.adoc new file mode 100644 index 0000000000..7c2eb1c886 --- /dev/null +++ b/components/Starknet/modules/ROOT/nav_glossary.adoc @@ -0,0 +1 @@ +* xref:glossary.adoc[] \ No newline at end of file diff --git a/components/Starknet/modules/ROOT/pages/glossary.adoc b/components/Starknet/modules/ROOT/pages/glossary.adoc new file mode 100644 index 0000000000..66178dac4b --- /dev/null +++ b/components/Starknet/modules/ROOT/pages/glossary.adoc @@ -0,0 +1,7 @@ +include::1.0.0@docs-common-content:ROOT:partial$partial_glossary.adoc[] + +// The source for the included file is in a separate repository. +// +// To edit the source page directly, go to: +// +// `https://github.com/starknet-io/docs-common-content/edit/main/modules/ROOT/partials/partial_glossary.adoc` \ No newline at end of file diff --git a/playbook.yml b/playbook.yml index 88e9c02267..6958058a98 100644 --- a/playbook.yml +++ b/playbook.yml @@ -15,7 +15,8 @@ content: start_paths: - components/Starknet - url: https://github.com/starknet-io/docs-common-content.git - branches: HEAD + branches: + - 'HEAD' edit_url: 'https://github.com/starknet-io/docs-common-content/edit/main/{path}' ui: From 5354976500fbfaf45f8f272935ba827adef21782 Mon Sep 17 00:00:00 2001 From: ArielElp <86294909+ArielElp@users.noreply.github.com> Date: Mon, 25 Mar 2024 15:08:50 +0200 Subject: [PATCH 4/6] docs: update block header w.r.t Starknet 0.13.1 (#1187) * update block header * Edits for clarification and grammar. * Apply suggestions from code review * SME comments --------- Co-authored-by: Steve Goodman Co-authored-by: Steve Goodman <39279277+stoobie@users.noreply.github.com> --- .../pages/Network_Architecture/header.adoc | 55 ++++++++++++------- 1 file changed, 36 insertions(+), 19 deletions(-) diff --git a/components/Starknet/modules/architecture_and_concepts/pages/Network_Architecture/header.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Network_Architecture/header.adoc index 06325cd4d4..3789b4bf67 100644 --- a/components/Starknet/modules/architecture_and_concepts/pages/Network_Architecture/header.adoc +++ b/components/Starknet/modules/architecture_and_concepts/pages/Network_Architecture/header.adoc @@ -3,32 +3,44 @@ [id="block_structure"] = Block structure -In Starknet, a block is a list of transactions, and a block header that contains the following fields: +A Starknet block is a list of transactions and a block header that contains the following fields: [%autowidth] |=== -| Name | Type | Description | Implemented - -| `parent_block_hash` | `FieldElement` | The hash of this block's parent | ✓ -|`block_number` | `Integer` | The number (height) of this block | ✓ -| `global_state_root` | `FieldElement` | The state xref:../Network_Architecture/starknet-state.adoc#state_commitment[commitment] after this block | ✓ -|`sequencer_address` | `FieldElement` | The Starknet address of the sequencer who created this block | ✓ -| `block_timestamp` | `Timestamp` | The time the sequencer created this block before executing transactions | ✓ -|`transaction_count` | `Integer` | The number of transactions in a block | ✓ -| `transaction_commitment` | `FieldElement` | A commitment to the transactions included in the block | ✓ -|`event_count` | `Integer` | The number of events | ✓ -| `event_commitment` | `FieldElement` | A commitment to the events produced in this block | ✓ -| `protocol_version` | `Integer` | The version of the Starknet protocol used when creating this block | -| `extra data` | `FieldElement` | Extraneous data that might be useful for running transactions | -|=== +| Name | Type | Description + +| `parent_block_hash` | `FieldElement` | The hash of the block's parent. +|`block_number` | `Integer` | The number, that is, the height, of this block. +| `global_state_root` | `FieldElement` | The xref:../Network_Architecture/starknet-state.adoc#state_commitment[state commitment] after the block. +|`sequencer_address` | `ContractAddress` | The Starknet address of the sequencer that created the block. +| `block_timestamp` | `Timestamp` | The time at which the sequencer began building the block, in seconds since the Unix epoch. +|`transaction_count` | `Integer` | The number of transactions in the block. +| `transaction_commitment` | `FieldElement` | A commitment to the transactions included in the block. + +The root of a height-64 binary Merkle Patricia trie. The leaf at index stem:[$i$] corresponds to stem:[$${h(\text{transaction_hash}, \text{signature})}$$] if the stem:[$i'th$] transaction is an `invoke` transaction and stem:[$h(0,0)$] otherwise. +|`event_count` | `Integer` | The number of events in the block. +| `event_commitment` | `FieldElement` | A commitment to the events produced in the block. -Where: +The root of a height-64 binary Merkle Patricia trie. The leaf at index stem:[$i$] corresponds to the hash of the stem:[$i'th$] event. +| `l1_gas_price` | `(Integer, Integer)` | The price of L1 gas that was used while constructing the block. L1 gas prices apply to storage updates and L1->L2 messages. As of March 2023, computation is also priced in terms of L1 gas, but this will change in the future. +The first `Integer` value is the price in wei. The second is the price in fri. +| `l1_data_gas_price` | `(Integer, Integer)` | The price of L1 blob gas that was used while constructing the block. If the `l1_DA_MODE` of the block is set to `BLOB`, L1 blob gas prices determines the storage update cost. -[horizontal,labelwidth='30'] -`event_commitment`:: is the root of a 64-bit high binary Merkle Patricia tree. The leaf at index stem:[$i$] corresponds to the hash of the stem:[$i'th$] event. -`transaction_commitment`:: is the root of a 64-bit high binary Merkle Patricia tree. The leaf at index stem:[$i$] corresponds to stem:[$${h(transaction \space hash, signature)}$$] if the stem:[$i'th$] transaction is an `invoke` transaction and stem:[$h(0,0)$] otherwise. +The first `Integer` value is the price in wei. The second is the price in fri. +| `l1_da_mode` | `String` | `CALLDATA` or `BLOB`, depending on how Starknet state diffs are sent to L1. +| `protocol_version` | `String` | The version of the Starknet protocol used when creating the block. + + +|=== + +// Where: +// +// +// [horizontal,labelwidth='30'] +// `event_commitment`:: is the root of a 64-bit high binary Merkle Patricia trie. The leaf at index stem:[$i$] corresponds to the hash of the stem:[$i'th$] event. +// `transaction_commitment`:: is the root of a 64-bit high binary Merkle Patricia trie. The leaf at index stem:[$i$] corresponds to stem:[$${h(transaction \space hash, signature)}$$] if the stem:[$i'th$] transaction is an `invoke` transaction and stem:[$h(0,0)$] otherwise. @@ -61,3 +73,8 @@ Where `_h_` is the xref:../../Cryptography/hash-functions.adoc#pedersen-hash[Ped ==== Zeros inside the hash computation of an object are used as placeholders, to be replaced in the future by meaningful fields. ==== + +[NOTE] +==== +Several properties of the block header, such as `l1_gas_price` and `l1_da_mode`, are not yet included in the block hash. This will change in a future Starknet version. +==== From 8e2dd6fc44bc43b7617c3a0b3164abc8f063782e Mon Sep 17 00:00:00 2001 From: odednaor Date: Mon, 25 Mar 2024 15:40:57 +0200 Subject: [PATCH 5/6] Update set_up_an_account.adoc with Sepolia faucets (#1195) * Update set_up_an_account.adoc with Sepolia faucets * Update components/Starknet/modules/quick_start/pages/set_up_an_account.adoc * Update components/Starknet/modules/quick_start/pages/set_up_an_account.adoc --------- Co-authored-by: Steve Goodman <39279277+stoobie@users.noreply.github.com> --- .../Starknet/modules/quick_start/pages/set_up_an_account.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/Starknet/modules/quick_start/pages/set_up_an_account.adoc b/components/Starknet/modules/quick_start/pages/set_up_an_account.adoc index de9ae92257..30ec5c1705 100644 --- a/components/Starknet/modules/quick_start/pages/set_up_an_account.adoc +++ b/components/Starknet/modules/quick_start/pages/set_up_an_account.adoc @@ -29,7 +29,7 @@ public key. After creating and funding your smart wallet with ETH you can deploy it to Starknet. For demonstration purposes, this page uses Starknet's testnet. -For testnet transactions you can fund your wallet using the https://faucet.goerli.starknet.io/[Starknet Goerli Faucet]. +For testnet transactions you can fund your wallet using one of the https://www.starknet.io/en/ecosystem/bridges-and-onramps[Starknet Sepolia faucets]. === Creating a Signer From eb9a89bf6f6628185b080826901e7e1ed4f0c2f2 Mon Sep 17 00:00:00 2001 From: Steve Goodman <39279277+stoobie@users.noreply.github.com> Date: Mon, 25 Mar 2024 17:31:56 +0200 Subject: [PATCH 6/6] docs: Update limits_and_triggers.adoc (#1194) * Update limits_and_triggers.adoc * Update new limits --- .../Starknet/modules/tools/pages/limits_and_triggers.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/Starknet/modules/tools/pages/limits_and_triggers.adoc b/components/Starknet/modules/tools/pages/limits_and_triggers.adoc index d5fb2c39cd..b8909b9f3e 100644 --- a/components/Starknet/modules/tools/pages/limits_and_triggers.adoc +++ b/components/Starknet/modules/tools/pages/limits_and_triggers.adoc @@ -8,14 +8,14 @@ Starknet currently has a number of limits in place in order to keep the network These are subject to revisions and change on a regular basis ==== -.Starknet current limits and triggers +.Starknet's current limits [%header, stripes=even] [%autowidth.stretch] |=== |Entity | Description | Sepolia | Goerli (deprecated) | Mainnet -|Block time | The maximum amount of time within which a pending block is closed, if no other limit is met. | 4 minutes |4 minutes |4 minutes +|Block time | The maximum amount of time within which a pending block is closed, if no other limit is met. | 6 minutes |4 minutes |6 minutes |Block limit (Cairo steps)| The maximum number of Cairo steps that can be completed -within each block to ensure block production times remain consistent and predictable. | 28,000,000 | 28,000,000 | 28,000,000 +within each block to ensure block production times remain consistent and predictable. | 40,000,000 | 28,000,000 | 40,000,000 |Block limit (gas)| Certain Starknet operations, such as sending messages between L1 and L2, consume Ethereum gas. The current L1 state update mechanism involves an Ethereum transaction for each Starknet block.