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/components/Starknet/modules/architecture_and_concepts/pages/Economics-of-Starknet.adoc b/components/Starknet/modules/architecture_and_concepts/pages/Economics-of-Starknet.adoc index 02ed2c6307..36ea69f83b 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]. 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 1a97e40215..3f0d5a0e93 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 @@ -39,7 +39,7 @@ For more information see xref:#calculation_of_computation_costs[Calculation of c * 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. * 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{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. @@ -71,7 +71,7 @@ where: ** 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: +* 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. @@ -273,7 +273,7 @@ Consequently, the gas cost associated with a single L2→L1 message is: ++++ \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{l1_log_data_cost}\cdot\text{payload_size} \; + \\ & + \text{log_message_to_l1_cost} \; + \\ & + \text{l1_storage_write_cost} \end{align} 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. +==== 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 diff --git a/playbook.yml b/playbook.yml index 3a9dd2b1c2..5a5cc23ce2 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: