Skip to content

Commit 9a0361f

Browse files
LandauRazLandauRaz
authored
Block structure refactor (#1391)
* refactored block struct * fixed typo * minor fix * rebase * fixed typo
1 parent 5a87d75 commit 9a0361f

File tree

1 file changed

+80
-105
lines changed
  • components/Starknet/modules/architecture-and-concepts/pages/network-architecture

1 file changed

+80
-105
lines changed

‎components/Starknet/modules/architecture-and-concepts/pages/network-architecture/block-structure.adoc‎

Lines changed: 80 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -7,55 +7,48 @@ A Starknet block is a list of transactions and a block header that contains the
77
|===
88
| Name | Type | Description
99

10-
|`block_number` | `u64` | The number, that is, the height, of this block.
10+
|`block_number` | `u64` | The number of this block (i.e., its height)
1111

12-
| `parent_block_hash` | `felt252` | The hash of the block's parent.
12+
| `parent_block_hash` | `felt252` | The xref:#block_hash[hash of the block's parent]
1313

14-
| `global_state_root` | `felt252` | The xref:../network-architecture/starknet-state.adoc#state_commitment[state commitment] after the block.
14+
| `global_state_root` | `felt252` | A xref:../network-architecture/starknet-state.adoc#state_commitment[commitment to the new state]
1515

16-
|`sequencer_address` | `ContractAddress` | The Starknet address of the sequencer that created the block.
16+
|`sequencer_address` | `ContractAddress` | The Starknet address of the sequencer that created the block
1717

18-
| `block_timestamp` | `Timestamp` | The time at which the sequencer began building the block, in seconds since the Unix epoch.
18+
| `block_timestamp` | `Timestamp` | The time at which the sequencer began building the block, in seconds since the Unix epoch
1919

20-
|`transaction_count` | `u32` | The number of transactions in the block.
20+
|`transaction_count` | `u32` | The number of transactions in the block
2121

2222
|`events_count` | `u32` | The number of events in the block.
2323

24-
|`state_diff_length`| `u32` | The sum of number of storage diffs, nonce updates, deployed contracts and declared classes.
24+
|`state_diff_length`| `u32` | The total amount of storage diffs, nonce updates, deployed contracts, and declared classes
2525

26-
|`state_diff_commitment`| `felt252` | The poseidon hash of the state diff of the block, see below for more details.
26+
|`state_diff_commitment`| `felt252` | A xref:#state_diff_hash[commitment to the state diff of the block]
2727

28-
| `transactions_commitment` | `felt252` | A commitment to the transactions included in the block.
29-
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})}$$].
28+
| `transactions_commitment` | `felt252` | A xref:#transactions_events_receipts_commitments[commitment to the transactions included in the block]
3029

31-
| `events_commitment` | `felt252` | The root of a height-64 binary Merkle Patricia trie.
32-
The leaf at index stem:[$i$] corresponds to the hash of the stem:[$i'th$] event emitted in the block.
33-
See below for a description on how event hashes are computed.
30+
| `events_commitment` | `felt252` | A xref:#transactions_events_receipts_commitments[commitment to the events included in the block]
3431

35-
| `receipts_commitment`| `felt252` | The root of a height-64 Merkle-Patricia trie.
36-
The leaf at index stem:[$i$] corresponds to the hash of the stem:[$i'th$] transaction receipt.
37-
See below for a description on how receipt hashes are computed.
32+
| `receipts_commitment`| `felt252` | A xref:#transactions_events_receipts_commitments[commitment to the receipts of the transactions included in the block]
3833

39-
| `l1_gas_price` | `(u128, u128)` | 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.
40-
The first `u128` value is the price in wei. The second is the price in fri.
34+
| `l1_gas_price` | `(u128, u128)` | The price of L1 gas that was used while constructing the block, where the first value is the price in wei and the second is the price in fri (see xref:./fee-mechanism.adoc[] for more details)
4135

42-
| `l1_data_gas_price` | `(u128, u128)` | 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.
43-
The first `u128` value is the price in wei. The second is the price in fri.
36+
| `l1_data_gas_price` | `(u128, u128)` | The price of L1 blob gas that was used while constructing the block, where the first value is the price in wei and the second is the price in fri (see xref:./fee-mechanism.adoc[] for more details)
4437

45-
| `l1_da_mode` | `String` | `CALLDATA` or `BLOB`, depending on how Starknet state diffs are sent to L1.
38+
| `l1_da_mode` | `String` | `CALLDATA` or `BLOB`, depending on how Starknet state diffs are sent to L1
4639

47-
| `protocol_version` | `String` | The version of the Starknet protocol used when creating the block.
40+
| `protocol_version` | `String` | The version of the Starknet protocol used when creating the block
4841

4942
|===
5043

5144
[#block_hash]
5245
== Block hash
5346

54-
A block hash is defined as the Poseidon hash of the header's fields, as follows:
47+
A block hash is defined by:
5548

5649
[,,subs="quotes"]
5750
----
58-
_h_(𝐵) = _h_(
51+
h(
5952
"STARKNET_BLOCK_HASH0",
6053
block_number,
6154
global_state_root,
@@ -77,76 +70,76 @@ _h_(𝐵) = _h_(
7770

7871
Where:
7972

80-
- `_h_` is the xref:../../cryptography/hash-functions.adoc#poseidon-hash[Poseidon hash].
81-
- `||` denotes concatenation, `transaction_count`, `event_count` and `state_diff_length` are given 64 bits each, and `l1_da_mode` is one bit where 0 denotes `CALLDATA` and 1 denotes `BLOB`.
73+
- `h` is the xref:../../cryptography/hash-functions.adoc#poseidon-hash[Poseidon hash function]
74+
- `transaction_count || event_count || state_diff_length || l1_da_mode` is the concatenation of the 64-bit representations of `transaction_count`, `event_count`, and `state_diff_length` with 0 if `l1_da_mode` is `CALLDATA` and 1 if `l1_da_mode` is `BLOB`
8275

83-
For a reference implementation, see the link:https://github.com/starkware-libs/sequencer/blob/bb361ec67396660d5468fd088171913e11482708/crates/starknet_api/src/block_hash/block_hash_calculator.rs#L68[sequencer repository].
76+
[TIP]
77+
====
78+
For a reference implementation, see link:https://github.com/starkware-libs/sequencer/blob/bb361ec67396660d5468fd088171913e11482708/crates/starknet_api/src/block_hash/block_hash_calculator.rs#L68[ `block_hash_calculator.rs`] in the Starknet sequencer's GitHub repository
79+
====
8480

8581
[#state_diff_hash]
8682
== State diff commitment
8783

88-
The state diff commitment is obtained by the chain-hash of the following:
89-
90-
- updates to contract addresses stem:[$c_1,...,c_n$], with diffs stem:[$(k^1_1, v^1_1),...,(k^1_{m_1}, v^1_{m_1}),...,(k^n_1, v^n_1),...,(k^n_{m_n},v^n_{m_n})$]
91-
- deployed contracts stem:[$(\text{deployed_address}_1, \text{deployed_class_hash}_1),...,(\text{deployed_address}_\ell,\text{deployed_class_hash}_\ell)$]
92-
- declared classes stem:[$(\text{declared_class_hash}_1, \text{declared_compiled_class_hash}_1), ..., (\text{declared_class_hash}_d, \text{declared_compiled_class_hash}_d)$]
93-
- replaced classes stem:[$(\text{replaced_contract_address}_1, \text{new_class_hash}_1),...,(\text{replaced_contract_address}_r, \text{new_class_hash}_r)$]
94-
- updated nonces stem:[$(\text{account}_1, \text{new_nonce}_1),...,(\text{account}_k, \text{new_nonce}_k)$]
95-
96-
More formally, the state-diff hash is given by:
97-
98-
[stem]
99-
++++
100-
\begin{align}
101-
h\big( & \text{"STARKNET_STATE_DIFF0"}, \\
102-
& \quad \ell + r, \\
103-
& \quad \text{deployed_address}_1, \text{deployed_class_hash}_1,...,\text{deployed_address}_\ell,\text{deployed_class_hash}_\ell, \\
104-
& \quad \text{replaced_contract_address}_1, \text{new_class_hash}_1,...,\text{replaced_contract_address}_r, \text{new_class_hash}_r \\
105-
& \quad d, \\
106-
& \quad \text{declared_class_hash}_1, \text{declared_compiled_class_hash}_1, ..., \text{declared_class_hash}_d, \text{declared_compiled_class_hash}_d, \\
107-
& \quad 1, \\
108-
& \quad 0, \\
109-
& \quad n, \\
110-
& \quad c_1 \\
111-
& \quad k^1_1, v^1_1,...,k^1_{m_1}, v^1_{m_1} \\
112-
& \quad \vdots \\
113-
& \quad c_n \\
114-
& \quad k^n_1, v^n_1,...,k^n_{m_n},v^n_{m_n} \\
115-
& \quad k \\
116-
& \quad \text{account}_1, \text{new_nonce}_1,...,\text{account}_k, \text{new_nonce}_k\big)
117-
\end{align}
118-
++++
84+
The state diff commitment is defined by:
85+
86+
[,,subs="quotes"]
87+
----
88+
h(
89+
"STARKNET_STATE_DIFF0",
90+
s + r,
91+
deployed_address~1~, deployed_class_hash~1~, ... , deployed_address~s~, deployed_class_hash~s~,
92+
replaced_contract_address~1~, new_class_hash~1~, ... , replaced_contract_address~r~, new_class_hash~r~,
93+
d,
94+
declared_class_hash~1~, declared_compiled_class_hash~1~, ... , declared_class_hash~d~, declared_compiled_class_hash~d~,
95+
1,
96+
0,
97+
n,
98+
c~1~, k~1,1~, v~1,1~, ... ,k~1,m^1^~, v~1,m^1^~, ... ,c~n~, k~n,1~, v~n,1~, ... ,k~n,m^n^~, v~n,m^n^~,
99+
k,
100+
account~1~, new_nonce~1~, ... ,account~k~, new_nonce~k~
101+
)
102+
----
119103

120104
Where:
121105

122-
- stem:[$h$] is the Poseidon hash function
123-
- stem:[$1, 0$] in the hash computation are placeholders that may be used in the future
106+
- `h` is the Poseidon hash function
107+
- `1` and `0` are placeholders that may be used in the future
108+
- `c~i~,k~i,1~, v~i,1~, ... , k~i,m^i^~,v~i,m^i^~` are `m^i^` updates `(k~i,1~, v~i,1~), ... ,(k~i,m^i^~, v~i,m^i^~)` to contract addresses `c~i~`
124109

125-
[#receipt_hash]
126-
== Receipt hash
110+
[#transactions_events_receipts_commitments]
111+
== Transactions, events, and receipts commitments
112+
The commitment to transactions, the commitment to events and the commitment to receipts are all roots of height-64 binary Merkle Patricia tries where the leaf at index `i` corresponds to:
127113

128-
A transaction receipt consists of the following fields:
114+
* For transactions: `h(transaction_hash, signature)` for the ``i``'th transaction included in the block, where `h` is the xref:../../cryptography/hash-functions.adoc#poseidon-hash[Poseidon hash function]
115+
* For events: The xref:#event_hash[event hash] of the ``i``'th emitted evet included in the block
116+
* For receipts: The xref:#receipt_hash[receipt hash] of the ``i``'th transaction receipt included in the block
129117

130-
[%autowidth]
131-
|===
132-
| Name | Type | Description
118+
[#event_hash]
119+
=== Event hash
133120

134-
| `transaction_hash` | `felt252` | the hash of the transaction
135-
| `actual_fee` | `u128` | the fee paid on-chain
136-
| `events` | `List<Event>` | ordered list of the events emitted by the transaction
137-
| `messages` | `List<L2toL1Message>` | ordered list of the l2->l1 messages sent by the transaction
138-
| `revert_reason`| `String`| The revert reason, in case the transaction was reverted
139-
| `l1_gas_consumed`| `u128` | The amount of l1 gas that was consumed
140-
| `l1_data_gas_consumed`| `u128` | The amount of l1 data (blob) gas that was consumed
141-
| `l2_gas_consumed`| `u128` | The amount of l2 gas that was consumed
121+
The hash of an xref:../smart-contracts/starknet-events.adoc[event] emitted by a contract whose address is `emitter_address` and a transaction whose hash is `tx_hash` is defined by:
142122

143-
|===
123+
[,,subs="quotes"]
124+
----
125+
h(
126+
emitter_address,
127+
tx_hash,
128+
h(keys),
129+
h(data)
130+
)
131+
----
144132

145-
The hash of the transaction receipt is given by:
133+
Where `h` is the xref:../../cryptography/hash-functions.adoc#poseidon-hash[Poseidon hash function].
134+
135+
[#receipt_hash]
136+
=== Receipt hash
137+
138+
The hash of a xref:./transaction-life-cycle.adoc#transaction-receipt[transaction receipt] is defined by:
146139

147140
[,,subs="quotes"]
148141
----
149-
_h_(receipt) = _h_(
142+
h(
150143
transaction_hash,
151144
actual_fee,
152145
h(messages),
@@ -157,31 +150,13 @@ _h_(receipt) = _h_(
157150

158151
Where:
159152

160-
- h is the Poseidon hash function
161-
- given messages stem:[$m_1=(\text{from}_1, \text{to}_1, \text{payload}_1)...m_n=(\text{from}_n, \text{to}_n, \text{payload}_n)$], their hash is given by:
162-
163-
[stem]
164-
++++
165-
h(n, \text{from}_1, \text{to}_1, h(\text{payload}_1), ..., \text{from}_n, \text{to}_n, h(\text{payload}_n))
166-
++++
167-
168-
where each message's payload is length-prefixed.
169-
170-
- events are omitted from the receipt's hash since they are committed separately in the block.
171-
172-
[#event_hash]
173-
== Event hash
174-
175-
The hash of an event stem:[$(\text{keys}, \text{data})$] emitted by a contract whose address is `emitter_address` and a transaction whose hash is `tx_hash` is given by:
176-
177-
[stem]
178-
++++
179-
h\big(\text{emitter_address}, \text{tx_hash}, h(\text{keys}), h(\text{data}) \big)
180-
++++
181-
182-
Where stem:[$h$] is the Poseidon hash function.
183-
184-
[NOTE]
185-
====
186-
Zeros inside the hash computation of an object are used as placeholders, to be replaced in the future by meaningful fields.
187-
====
153+
- `h` is the xref:../../cryptography/hash-functions.adoc#poseidon-hash[Poseidon hash function]
154+
- `h(messages)` for `messages = (from~1~, to~1~, payload~1~), ... , (from~n~, to~n~, payload~n~)` is defined by:
155+
+
156+
[,,subs="quotes"]
157+
----
158+
h(
159+
n,
160+
from~1~, to~1~, h(len(payload~1~) || payload~1~), ... , from~n~, to~n~, h(len(payload~n~) || payload~n~)
161+
)
162+
----

0 commit comments

Comments
 (0)