Merge branch 'main' into steve/0.13.1/release_notes/additions

.github/workflows/pull_request.yml

@@ -1,18 +1,9 @@
 name: Pull request workflow
 
 on:
-  pull_request_target:
-    types:
-      - opened
-      - reopened
-      - synchronize
+  pull_request:
     branches:
-      - 'main'
-      - 'dev'
-
-permissions:
-  contents: write
-  pull-requests: write
+      - '*'
 
 jobs:
 
@@ -29,7 +20,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v2
         with:
-          ref: refs/pull/${{ github.event.pull_request.number }}/merge
+          node-version: 16
 
       - name: Install Node.js
         uses: actions/setup-node@v2
@@ -58,8 +49,9 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v2
         with:
+          node-version: 16
           ref: gh-pages
-          token: ${{ secrets.GITHUB_TOKEN }}
+          USER_TOKEN: ${{ secrets.USER_TOKEN }}
 
       - name: Extract PR details
         id: pr
@@ -94,7 +86,6 @@ jobs:
           git status
           git config user.name "GitHub Actions"
           git config user.email [email protected]
-          
           git add .
           
           

.github/workflows/push.yml

@@ -3,7 +3,6 @@ name: Push workflow
 on:
   push:
     branches:
-#      - dev
       - main
 
 jobs:
@@ -29,14 +28,11 @@ jobs:
           git config --global user.name "${{ secrets.USER_NAME }}"
           git config --global user.email "${{ secrets.USER_EMAIL }}"
 
-      - name: Run release script
-        if: ${{ github.ref_name == 'main' }}
-        run: yarn run release
+      - name: Generate Site
+        run: yarn generate
 
-      - name: Push to remote branch
-        uses: ad-m/github-push-action@master
-        with:
-          USER_TOKEN: ${{ secrets.USER_TOKEN }}
-          branch: ${{ github.ref }}
-          tags: true
-          force: true
+      - name: Zip artifacts
+        run: zip -r ${{ steps.get-release-data.outputs.file }}.zip package.json CHANGELOG.md
+
+      - name: scp upload to production site
+        run: sshpass -p ${{ secrets.PROD_PASS }} scp -o 'StrictHostKeyChecking no' -r public_html/ ${{ secrets.PROD_USER }}@${{ secrets.PROD_IP }}:~/

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.1.514](https://github.com/starknet-io/starknet-docs/compare/v0.1.513...v0.1.514) (2024-03-14)
+
 ### [0.1.513](https://github.com/starknet-io/starknet-docs/compare/v0.1.512...v0.1.513) (2024-03-14)
 
 ### [0.1.512](https://github.com/starknet-io/starknet-docs/compare/v0.1.511...v0.1.512) (2024-03-14)

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

components/Starknet/modules/ROOT/nav_glossary.adoc

@@ -0,0 +1 @@
+* xref:glossary.adoc[]

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`

components/Starknet/modules/architecture_and_concepts/pages/Accounts/deploying_new_accounts.adoc

@@ -16,7 +16,7 @@ Upon receiving one of these transactions, the sequencer performs the following s
 +
 [NOTE]
 ====
-If you use a `DEPLOY_ACCOUNT` transaction, the fees are paid from the address of the deployed account. If you use the UDC, which requires an `INVOKE` transaction, the fees are paid from the sender's account. For information on the differences between V1 and V3 `INVOKE` transactions, see xref:architecture_and_concepts/Network_Architecture/transactions.adoc#invoke_transaction[`INVOKE` transaction] in _Transaction types_.
+If you use a `DEPLOY_ACCOUNT` transaction, the fees are paid from the address of the deployed account. If you use the UDC, which requires an `INVOKE` transaction, the fees are paid from the sender's account. For information on the differences between V1 and V3 `INVOKE` transactions, see xref:Network_Architecture/transactions.adoc#invoke_transaction[`INVOKE` transaction] in _Transaction types_.
 ====
 . Sets the account's nonce as follows:
 ** `1`, when deployed with a `DEPLOY_ACCOUNT` transaction

components/Starknet/modules/architecture_and_concepts/pages/Accounts/validate_and_execute.adoc

@@ -40,7 +40,10 @@ As a concrete example, think of many `__validate__`
 
 Currently, Starknet enforces that `__validate__` does not call external contracts.
 
-NOTE: The property that we achieve with the above restrictions is that a single storage update may only invalidate transactions from a single account (this is the best we can do, an account can always invalidate its own past transactions by changing its keys). Thus, the price (in fees) required to invalidate transactions in the mempool is linear in the number of unique accounts that we want to invalidate.
+[NOTE]
+====
+The property that we achieve with the above restrictions is that a single storage update may only invalidate transactions from a single account (this is the best we can do, an account can always invalidate its own past transactions by changing its keys). Thus, the price (in fees) required to invalidate transactions in the mempool is linear in the number of unique accounts that we want to invalidate.
+====
 
 [id="the_execute_function"]
 == The execute function
@@ -53,3 +56,4 @@ In Ethereum, a transaction is necessarily a call to a specific function in a sma
 == Reverted transactions
 
 A transaction is considered reverted when the `__execute__` function failed. A reverted transaction is included in a block and the sequencer is eligible to charge a fee for the work done up to the point of failure, similar to Ethereum.
+

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].
 

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

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.
+====

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
 

components/Starknet/modules/tools/nav.adoc

@@ -23,6 +23,7 @@
 **** xref:starkgate-adding_a_token.adoc[Adding a token]
 **** xref:starkgate-cancelling a deposit.adoc[Cancelling a deposit]
 **** xref:starkgate-estimating_fees.adoc[Estimating StarkGate fees]
+**** xref:dai_token_migration.adoc[Migrating DAI v0 to DAI]
 *** xref:starkgate_function_reference.adoc[StarkGate function and event reference]
 
 * Important addresses