diff --git a/docs/build-decentralized-apps/02-how-to-estimate-gas.mdx b/docs/build-decentralized-apps/02-how-to-estimate-gas.mdx
index 0f7f93b980..e5b580b69d 100644
--- a/docs/build-decentralized-apps/02-how-to-estimate-gas.mdx
+++ b/docs/build-decentralized-apps/02-how-to-estimate-gas.mdx
@@ -12,7 +12,7 @@ Head over to [the Stylus gas docs](/stylus/reference/opcode-hostio-pricing) for
:::
-This how-to is intended for users and developers interested in understanding how gas operates in Arbitrum, how it's calculated, and how to estimate it before submitting transactions. More detailed information about these calculations can be found in this [Medium article](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and the [Gas and Fees](/how-arbitrum-works/09-gas-fees.mdx) page.
+This how-to is intended for users and developers interested in understanding how gas operates in Arbitrum, how it's calculated, and how to estimate it before submitting transactions. More detailed information about these calculations can be found in this [Medium article](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and the [Gas and Fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx) page.
## Skip the formula, focus on practical know-how
@@ -22,7 +22,7 @@ Multiplying the value obtained from `eth_estimateGas` by the child chain gas pri
Alternatively, to obtain the gas limit for your transaction, you can call `NodeInterface.gasEstimateComponents()` and then use the first result, which is `gasEstimate`. Next, to find the total cost, you need to multiply this amount by the child chain gas price, which is available in the third result, `baseFee`.
-Note that when working with parent to child chain messages (also known as [retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx)), you can use the function [`L1ToL2MessageGasEstimator.estimateAll()`](https://github.com/OffchainLabs/arbitrum-sdk/blob/main/src/lib/message/L1ToL2MessageGasEstimator.ts#L215) of the Arbitrum SDK or [`NodeInterface.estimateRetryableTicket()`](https://github.com/OffchainLabs/@@nitroRepositorySlug=nitro@@/blob/@@nitroVersionTag=v3.7.2@@/nodeInterface/NodeInterface.go#L120) to get all the gas information needed to send a successful transaction.
+Note that when working with parent to child chain messages (also known as [retryable tickets](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx)), you can use the function [`L1ToL2MessageGasEstimator.estimateAll()`](https://github.com/OffchainLabs/arbitrum-sdk/blob/main/src/lib/message/L1ToL2MessageGasEstimator.ts#L215) of the Arbitrum SDK or [`NodeInterface.estimateRetryableTicket()`](https://github.com/OffchainLabs/@@nitroRepositorySlug=nitro@@/blob/@@nitroVersionTag=v3.6.8@@/nodeInterface/NodeInterface.go#L120) to get all the gas information needed to send a successful transaction.
## Breaking down the formula
@@ -36,7 +36,7 @@ As explained in the Medium article, the transaction fees to pay at any given mom
Transaction fees (TXFEES) = L2 Gas Price (P) * Gas Limit (G)
```
-This Gas Limit includes the gas of the child chain computation and an additional buffer to cover the parent chain gas to be paid by the Sequencer when [posting the batch including this transaction on the parent chain](/how-arbitrum-works/03-sequencer.mdx).
+This Gas Limit includes the gas of the child chain computation and an additional buffer to cover the parent chain gas to be paid by the Sequencer when [posting the batch including this transaction on the parent chain](/how-arbitrum-works/deep-dives/sequencer.mdx).
```
Gas Limit (G) = Gas used on L2 (L2G) + Extra Buffer for L1 cost (B)
@@ -47,7 +47,7 @@ This buffer takes into account the cost of posting the transaction, batched and
- L1S, which estimates the amount of data the transaction will take up in the batch by compressing the transaction with Brotli.
- L1P, which is the child chain's estimated view of the current parent chain's price of data (per byte), which the child chain dynamically adjusts over time.
-More information is available [in this page](/how-arbitrum-works/09-gas-fees.mdx).
+More information is available [in this page](/how-arbitrum-works/deep-dives/gas-and-fees.mdx).
```
L1 Estimated Cost (L1C) = L1 price per byte of data (L1P) * Size of data to be posted in bytes (L1S)
@@ -76,7 +76,7 @@ We'll use one resource available in Arbitrum: the [`NodeInterface`](/build-decen
- L1P (L1 estimated price per byte of data) ⇒ Estimated cost of posting 1 byte of data on the parent chain:
- Call `NodeInterface.GasEstimateComponents()`, get the fourth element `l1BaseFeeEstimate` and multiply it by 16.
- L1S (Size of data to be posted on L1, in bytes) ⇒ This will depend on the data of the transaction. Keep in mind that Arbitrum adds a fixed amount to this number to make up for the static part of the transaction, which is also posted on the parent chain (140 bytes). We can do a small calculation to obtain this value: call `NodeInterface.GasEstimateComponents()` take the second element, `gasEstimateForL1` (this is equivalent to `B` in our formula), multiply it by P and divide it by L1P.
- - For Arbitrum Nova (AnyTrust), the size of the data is also a fixed value, as only the Data Availability Certificate (DAC) is posted on the parent chain, [as explained here](/how-arbitrum-works/08-anytrust-protocol.mdx#data-availability-certificates).
+ - For Arbitrum Nova (AnyTrust), the size of the data is also a fixed value, as only the Data Availability Certificate (DAC) is posted on the parent chain, [as explained here](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx#data-availability-certificates).
:::note
For L1P and L1S, you can also call `NodeInterface.gasEstimateL1Component()` to get `l1BaseFeeEstimate` and `gasEstimateForL1`
diff --git a/docs/build-decentralized-apps/03-public-chains.mdx b/docs/build-decentralized-apps/03-public-chains.mdx
index 46912181bc..bd0a18a325 100644
--- a/docs/build-decentralized-apps/03-public-chains.mdx
+++ b/docs/build-decentralized-apps/03-public-chains.mdx
@@ -14,11 +14,11 @@ Arbitrum chains are child chain solutions built on top of the Ethereum blockchai
### Arbitrum One
-**Arbitrum One** is a child chain Optimistic Rollup chain that implements the Arbitrum Rollup protocol and settles to Ethereum's parent chain. It lets you build high-performance Ethereum dApps with low transaction costs and Ethereum-grade security guarantees, introducing no additional trust assumptions. This is made possible by the [Nitro](/how-arbitrum-works/04-state-transition-function/04-modified-geth-on-arbitrum.mdx) technology stack, a "Geth-at-the-core" architecture that gives Arbitrum One (and Nova) advanced calldata compression, separate contexts for common execution and fault proving, Ethereum parent chain gas compatibility, and more.
+**Arbitrum One** is a child chain Optimistic Rollup chain that implements the Arbitrum Rollup protocol and settles to Ethereum's parent chain. It lets you build high-performance Ethereum dApps with low transaction costs and Ethereum-grade security guarantees, introducing no additional trust assumptions. This is made possible by the [Nitro](/how-arbitrum-works/deep-dives/geth.mdx) technology stack, a "Geth-at-the-core" architecture that gives Arbitrum One (and Nova) advanced calldata compression, separate contexts for common execution and fault proving, Ethereum parent chain gas compatibility, and more.
### Arbitrum Nova
-**Arbitrum Nova** is a high-performance alternative to Arbitrum One's chain. While Arbitrum One implements the purely trustless Rollup protocol, Arbitrum Nova implements the mostly trustless [AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx) protocol. The key difference between Rollup and AnyTrust is that the AnyTrust protocol introduces an additional trust assumption in the form of a Data Availability Committee (DAC). This committee (detailed below) is responsible for expediting the process of storing, batching, and posting child chain transaction data to Ethereum's parent chain. This lets you use Arbitrum in scenarios that demand performance and affordability, while Arbitrum One is optimal for scenarios that demand Ethereum's pure trustlessness.
+**Arbitrum Nova** is a high-performance alternative to Arbitrum One's chain. While Arbitrum One implements the purely trustless Rollup protocol, Arbitrum Nova implements the mostly trustless [AnyTrust](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) protocol. The key difference between Rollup and AnyTrust is that the AnyTrust protocol introduces an additional trust assumption in the form of a Data Availability Committee (DAC). This committee (detailed below) is responsible for expediting the process of storing, batching, and posting child chain transaction data to Ethereum's parent chain. This lets you use Arbitrum in scenarios that demand performance and affordability, while Arbitrum One is optimal for scenarios that demand Ethereum's pure trustlessness.
## What Arbitrum testnet chains are available?
@@ -58,11 +58,11 @@ Finally, Arbitrum Sepolia is a testnet chain. It's designed for testing purposes
### Nitro
-Nitro is the technology that powers Arbitrum One, Arbitrum Nova (with AnyTrust configuration),and Arbitrum Sepolia. It's designed to offer high throughput and low cost, making it ideal for scaling Ethereum applications. Nitro is a major upgrade to the “Classic” stack, offering several improvements including advanced calldata compression, separate contexts for common execution and fault proving, Ethereum parent chain gas compatibility, and more. You can find more information about Nitro in [How Arbitrum works](/how-arbitrum-works/01-a-gentle-introduction.mdx).
+Nitro is the technology that powers Arbitrum One, Arbitrum Nova (with AnyTrust configuration),and Arbitrum Sepolia. It's designed to offer high throughput and low cost, making it ideal for scaling Ethereum applications. Nitro is a major upgrade to the “Classic” stack, offering several improvements including advanced calldata compression, separate contexts for common execution and fault proving, Ethereum parent chain gas compatibility, and more. You can find more information about Nitro in [How Arbitrum works](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx).
### AnyTrust (variant of Nitro)
-AnyTrust is a variant of the Nitro technology stack that lowers costs by accepting a mild trust assumption. The AnyTrust protocol relies on an external Data Availability Committee (DAC) to store data and provide it on demand. The DAC has `N` members, of which AnyTrust assumes at least two are honest. Keeping the data offchain in the happy/common case means the system can charge the user significantly lower fees. You can find more information about AnyTrust in [Anytrust protocol](/how-arbitrum-works/08-anytrust-protocol.mdx).
+AnyTrust is a variant of the Nitro technology stack that lowers costs by accepting a mild trust assumption. The AnyTrust protocol relies on an external Data Availability Committee (DAC) to store data and provide it on demand. The DAC has `N` members, of which AnyTrust assumes at least two are honest. Keeping the data offchain in the happy/common case means the system can charge the user significantly lower fees. You can find more information about AnyTrust in [Anytrust protocol](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx).
### Classic (deprecated)
diff --git a/docs/build-decentralized-apps/04-cross-chain-messaging.mdx b/docs/build-decentralized-apps/04-cross-chain-messaging.mdx
index a9e53218d8..f73d98e710 100644
--- a/docs/build-decentralized-apps/04-cross-chain-messaging.mdx
+++ b/docs/build-decentralized-apps/04-cross-chain-messaging.mdx
@@ -12,7 +12,7 @@ The Arbitrum protocol and related tooling makes it easy for developers to build
Arbitrary parent to child chain contract calls can be created via the Inbox's `createRetryableTicket` method; upon publishing the parent chain transaction, the child chain side will typically get included within minutes. Commonly, the child chain execution will automatically succeed, but if reverts, and it can be rexecuted via a call to the `redeem` method of the [`ArbRetryableTx`](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile.
-For details and protocol specification, see [Parent to child chain messages](/how-arbitrum-works/10-l1-to-l2-messaging.mdx).
+For details and protocol specification, see [Parent to child chain messages](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx).
For an example of retryable tickets in action, see the [`Greeter`](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/greeter) tutorial, which uses the [Arbitrum SDK](../../sdk).
@@ -20,6 +20,6 @@ For an example of retryable tickets in action, see the [`Greeter`](https://githu
Similarly, child chain contracts can send Arbitrary messages for execution on the parent chain. These are initiated via calls to the [`ArbSys`](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) precompile contract's `sendTxToL1` method. Upon confirmation (about one week later), they can execute by retrieving the relevant data via a call to `NodeInterface` contract's `constructOutboxProof` method, and then executing them via the `Outbox`'s `executeTransaction` method.
-For details and protocol specification, see [Child to parent chain messages](/how-arbitrum-works/11-l2-to-l1-messaging.mdx).
+For details and protocol specification, see [Child to parent chain messages](/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx).
For a demo, see the [Outbox Tutorial](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/outbox-execute).
diff --git a/docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx b/docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx
index 53e9b1357a..316fa8fdbc 100644
--- a/docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx
+++ b/docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx
@@ -13,32 +13,70 @@ Arbitrum's design is to be as compatible and consistent with Ethereum as possibl
This article outlines the key differences, benefits, and potential pitfalls that devs should be aware of when working with Arbitrum. This first page serves as an outline, with links to the relevant pages.
-## Block numbers and time
+## STF in Ethereum
+
+In Ethereum, the STF receives transactions as inputs, processes them via the EVM, and produces the final state as output.
+
+The Ethereum state is a vast data structure represented by a modified Merkle Patricia Trie. This structure holds all accounts, linking them via hashes and reducing the entire state to a single root hash stored on the blockchain.
+
+The Ethereum Virtual Machine (EVM) operates similarly to a mathematical function: given an input, it produces a deterministic output. Ethereum's STF encapsulates this behavior:
+
+$$
+Y(S, T) = S'
+$$
+
+Here, `S` represents the current state, `T` denotes the transaction, and `S'` is the new state resulting from the execution of `T`.
+
+The EVM operates as a stack machine with a maximum depth of 1024 items. Each item is a 256-bit word, chosen for compatibility with 256-bit cryptography (e.g., Keccak-256 hashes and secp256k1 signatures).
+
+During execution, the EVM uses transient _memory_ (a word-addresses byte array) that only persists for the duration of a transaction. In contrast, each contract maintains a persistent Merkle Patricia _storage_ trie–a word-addressable word array–that forms part of the global state.
+
+smart contract bytecode compiles into a series of EVM opcodes
+that perform standard stack operations (such as `XOR`, `AND`, `ADD`, `SUB`) and blockchain-specific operations
+(such as `ADDRESS`, `BALANCE`, `BLOCKHASH`).
+
+Geth (go-Ethereum) is one of the primary
+ client
+ implementations of Ethereum, serving as the practical embodiment of both the STF and the EVM execution
+engine. It processes transactions by executing the smart contract's bytecode and updating the global
+state, ensuring that every state change is deterministic and secure.
+
+In essence, Geth converts transaction inputs into precise computational steps within the EVM, maintaining the intricate data structures that underpin Ethereum's blockchain. Its robust design not only powers the core operations of Ethereum but also provides the foundation for advanced modificaitons in platforms like the Arbitrum Nitro stack.
+
+## STF on Arbitrum
+
+The Arbitrum Nitro stack implements a modified version of Ethereum's STF. While it retains the core principles of Ethereum, several Arbitrum-specific features and processes distinguish it from Ethereum's implementation. Key differences include:
+
+### Block numbers and time
Time in Arbitrum chains is tricky. The timing assumptions one is used to making about Ethereum blocks don't exactly carry over into the timing of Arbitrum blocks. See [Block numbers and time](/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx) for details about how block numbers and time work in Arbitrum.
-## RPC methods
+### RPC methods
Although the majority of RPC methods follow the same behavior as Ethereum, some methods may produce a different result or add additional information when used on an Arbitrum chain. You can find more information about these differences in [RPC methods](/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx).
-## Solidity support
+### Solidity support
You can deploy Solidity contracts onto Arbitrum just like you do on Ethereum. There are only a few minor functional differences. For more information, refer to [Solidity support](/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx).
-## Fees
+### Gas accounting
+
+The fees for executing an Arbitrum transaction function similarly to gas fees on Ethereum. However, Arbitrum transactions must also pay a fee component to cover the cost of posting their calldata to the parent chain (for example, calldata on Arbitrum One, a child chain, is posted to Ethereum, a parent chain). Find more information about the two components of gas fees in [Gas and fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx) and parent chain pricing.
+
+### Base fee mechanism
-The fees for executing an Arbitrum transaction function similarly to gas fees on Ethereum. However, Arbitrum transactions must also pay a fee component to cover the cost of posting their calldata to the parent chain (for example, calldata on Arbitrum One, a child chain, is posted to Ethereum, a parent chain). Find more information about the two components of gas fees in [Gas and fees](/how-arbitrum-works/09-gas-fees.mdx) and parent chain pricing.
+Arbitrum chains support arbitrary message passing from a parent chain (e.g., Ethereum) to a child chain (e.g., Arbitrum One). These messages are commonly referred to as "parent chain to child chain messages." Developers using this functionality should familiarize themselves with how messaging works. For more information, refer to [Parent chain to child chain messaging](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx).
-## Cross-chain messaging
+Similarly, Arbitrum chains can also send messages to the parent chain—more information about this is available in [Child Chain to Parent Chain Messaging and the Outbox](/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx).
-Arbitrum chains support arbitrary message passing from a parent chain (e.g., Ethereum) to a child chain (e.g., Arbitrum One). These messages are commonly referred to as "parent chain to child chain messages." Developers using this functionality should familiarize themselves with how messaging works. For more information, refer to [Parent chain to child chain messaging](/how-arbitrum-works/10-l1-to-l2-messaging.mdx).
+Arbitrum chains support arbitrary message passing from a parent chain (for example, a parent chain like Ethereum) to a child chain (for example, a child chain like Arbitrum One or Arbitrum Nova). These are commonly known as "parent chain to child chain messages". Developers using this functionality should familiarize themselves with how they work. Find more information about it in [Parent chain to child chain messaging](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx).
-Similarly, Arbitrum chains can also send messages to the parent chain—more information about this is available in [Child Chain to Parent Chain Messaging and the Outbox](/how-arbitrum-works/11-l2-to-l1-messaging.mdx).
+Similarly, Arbitrum chains can also send messages to the parent chain. Find more information about them in [Child chain to parent chain messaging and the outbox](/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx).
-## Precompiles
+### Precompiles
Besides supporting all precompiles available in Ethereum, Arbitrum provides child chain-specific precompiles with methods that smart contracts can call in the same way as Solidity functions. You can find a full reference to them on the [Precompiles](/build-decentralized-apps/precompiles/01-overview.mdx) page.
-## NodeInterface
+### NodeInterface
The Arbitrum Nitro software includes a special `NodeInterface` contract, available at address `0xc8`, that is only accessible via RPCs (deployed offchain, making it inaccessible to smart contracts). Find more information about this interface in [NodeInterface](build-decentralized-apps/nodeinterface/01-overview.mdx).
diff --git a/docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx b/docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx
index c2f81883bf..a2b547e314 100644
--- a/docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx
+++ b/docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx
@@ -18,7 +18,7 @@ Throughout this and other pages, we note that the block number of a chain does n
:::
-As with Ethereum, Arbitrum clients submit transactions, and the system executes them later. In Arbitrum, clients submit transactions by posting messages to the Ethereum chain, either [through the Sequencer](/how-arbitrum-works/03-sequencer.mdx) or via the chain's [Delayed Inbox](/how-arbitrum-works/03-sequencer.mdx).
+As with Ethereum, Arbitrum clients submit transactions, and the system executes them later. In Arbitrum, clients submit transactions by posting messages to the Ethereum chain, either [through the Sequencer](/how-arbitrum-works/deep-dives/sequencer.mdx) or via the chain's [Delayed Inbox](/how-arbitrum-works/deep-dives/sequencer.mdx).
Once in the chain's core inbox contract, transaction processing occurs in order. Generally, some time will elapse between when a message is put into the inbox (and timestamped) and when the contract processes the message and carries out the transaction requested by the message.
diff --git a/docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx b/docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx
index 606a93e2ba..3c6314fc56 100644
--- a/docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx
+++ b/docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx
@@ -22,18 +22,18 @@ When calling [`eth_getTransactionByHash`](https://ethereum.org/en/developers/doc
### Transaction types
-In addition to the [three transaction types](https://ethereum.org/en/developers/docs/transactions/#types-of-transactions) currently supported on Ethereum, Arbitrum adds additional types listed below and [documented in full detail here](/how-arbitrum-works/04-state-transition-function/04-modified-geth-on-arbitrum.mdx#transaction-types).
+In addition to the [three transaction types](https://ethereum.org/en/developers/docs/transactions/#types-of-transactions) currently supported on Ethereum, Arbitrum adds additional types listed below and [documented in full detail here](/how-arbitrum-works/deep-dives/geth.mdx#transaction-types).
On RPC calls that return transactions, the `type` field will reflect the custom codes where applicable.
-| Transaction type code | Transaction type name | Description |
-| --------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `100` | `ArbitrumDepositTxType` | Used to deposit `ETH` from a parent chain to a child chain via the Arbitrum bridge |
-| `101` | `ArbitrumUnsignedTxType` | Used to call a child chain contract from a parent chain, originated by a user through the Arbitrum bridge |
-| `102` | `ArbitrumContractTxType` | Used to call a child chain contract from a parent chain, originated by a contract through the Arbitrum bridge |
-| `104` | `ArbitrumRetryTxType` | Used to [manually redeem a retryable ticket](/how-arbitrum-works/10-l1-to-l2-messaging.mdx) on a child chain that failed to execute automatically (usually due to low gas) |
-| `105` | `ArbitrumSubmitRetryableTxType` | Used to [submit a retryable ticket](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#submission) via the Arbitrum bridge on the parent chain |
-| `106` | `ArbitrumInternalTxType` | Internal transactions created by the ArbOS itself for certain state updates, like the parent chain base fee and the block number |
+| Transaction type code | Transaction type name | Description |
+| --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `100` | `ArbitrumDepositTxType` | Used to deposit `ETH` from a parent chain to a child chain via the Arbitrum bridge |
+| `101` | `ArbitrumUnsignedTxType` | Used to call a child chain contract from a parent chain, originated by a user through the Arbitrum bridge |
+| `102` | `ArbitrumContractTxType` | Used to call a child chain contract from a parent chain, originated by a contract through the Arbitrum bridge |
+| `104` | `ArbitrumRetryTxType` | Used to [manually redeem a retryable ticket](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx) on a child chain that failed to execute automatically (usually due to low gas) |
+| `105` | `ArbitrumSubmitRetryableTxType` | Used to [submit a retryable ticket](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#submission) via the Arbitrum bridge on the parent chain |
+| `106` | `ArbitrumInternalTxType` | Internal transactions created by the ArbOS itself for certain state updates, like the parent chain base fee and the block number |
### Additional fields
@@ -47,9 +47,9 @@ On RPC calls that return transactions, the following fields are added to the ret
On RPC calls that return transactions, the following fields will have different content than what's received on Ethereum.
-| Field name | Description |
-| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `from` | On parent to child chain transactions, this field will contain the [_aliased_ version](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#address-aliasing) of the parent chain's `msg.sender` |
+| Field name | Description |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `from` | On parent to child chain transactions, this field will contain the [_aliased_ version](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#address-aliasing) of the parent chain's `msg.sender` |
## Transaction receipts
@@ -62,7 +62,7 @@ On RPC calls that return transaction receipts, the following fields are added to
| Field name | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `l1BlockNumber` | The block number of the first non-Arbitrum ancestor chain that is usable for `block.number` calls. More information in [Block numbers and time](/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx) |
-| `gasUsedForL1` | The amount of gas spent on parent chain calldata in units of child chain gas. More information in [Gas and fees](/how-arbitrum-works/09-gas-fees.mdx) |
+| `gasUsedForL1` | The amount of gas spent on parent chain calldata in units of child chain gas. More information in [Gas and fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx) |
## Blocks
diff --git a/docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx b/docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx
index e74671e3a9..b5842e3010 100644
--- a/docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx
+++ b/docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx
@@ -23,5 +23,5 @@ Although Arbitrum supports Solidity code, there are differences in the effects o
| `block.difficulty` | Returns the constant 1. |
| `block.prevrandao` | Returns the constant 1. |
| `block.number` | Returns an "estimate" of the block number of the first non-Arbitrum ancestor chain at which the sequencer received the transaction. For more information, see [Block numbers and time](/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx). |
-| `msg.sender` | Works the same way it does on Ethereum for regular child chain to child chain transactions. For transactions submitted via the delayed inbox, it will return the child chain address alias of the parent chain contract that triggered the message. For more information, see [address aliasing](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#address-aliasing). |
+| `msg.sender` | Works the same way it does on Ethereum for regular child chain to child chain transactions. For transactions submitted via the delayed inbox, it will return the child chain address alias of the parent chain contract that triggered the message. For more information, see [address aliasing](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#address-aliasing). |
| OPCODE `PUSH0` | This OPCODE was added as part of ArbOS 11 and is now supported. |
diff --git a/docs/build-decentralized-apps/custom-gas-token-sdk.mdx b/docs/build-decentralized-apps/custom-gas-token-sdk.mdx
index 069bae5e05..f100dac3cc 100644
--- a/docs/build-decentralized-apps/custom-gas-token-sdk.mdx
+++ b/docs/build-decentralized-apps/custom-gas-token-sdk.mdx
@@ -27,7 +27,7 @@ You should use `EthBridger` when bridging the native token between the parent ch
2. **`Erc20Bridger` Context:**
- **APIs:** `getApproveGasTokenRequest` and `approveGasToken`.
- - **Purpose:** In the scenario of bridging `ERC-20` assets to an Arbitrum chain, these APIs play a crucial role. Token Bridging on Arbitrum Nitro stack uses retryable tickets and needs a specific fee to be paid for the creation and redemption of the ticket. For more information about retryable tickets, please take a look at [our chapter about retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#retryable-tickets) part of our docs. The Arbitrum chain operates as a custom gas token network, necessitating the payment of fees in native tokens for the creation of retryable tickets and their redemption on the Arbitrum chain. To cover the submission and execution fees associated with retryable tickets on the Arbitrum chain, an adequate number of native tokens must be approved and allocated to the parent chain to cover the fees.
+ - **Purpose:** In the scenario of bridging `ERC-20` assets to an Arbitrum chain, these APIs play a crucial role. Token Bridging on Arbitrum Nitro stack uses retryable tickets and needs a specific fee to be paid for the creation and redemption of the ticket. For more information about retryable tickets, please take a look at [our chapter about retryable tickets](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#retryable-tickets) part of our docs. The Arbitrum chain operates as a custom gas token network, necessitating the payment of fees in native tokens for the creation of retryable tickets and their redemption on the Arbitrum chain. To cover the submission and execution fees associated with retryable tickets on the Arbitrum chain, an adequate number of native tokens must be approved and allocated to the parent chain to cover the fees.
:::note Important Notes
diff --git a/docs/build-decentralized-apps/precompiles/02-reference.mdx b/docs/build-decentralized-apps/precompiles/02-reference.mdx
index b982d0eb3c..f4d0351480 100644
--- a/docs/build-decentralized-apps/precompiles/02-reference.mdx
+++ b/docs/build-decentralized-apps/precompiles/02-reference.mdx
@@ -149,7 +149,7 @@ import ArbOwnerPublicRef from '../../for-devs/dev-tools-and-resources/partials/p
### `ArbRetryableTx`
-ArbRetryableTx ([Interface](https://github.com/OffchainLabs/@@nitroPrecompilesRepositorySlug=nitro-precompile-interfaces@@/blob/@@nitroPrecompilesCommit=f9f65d7c77adf61ad16504a3738a9edcc31e2b2f@@/ArbRetryableTx.sol) | [Implementation](https://github.com/OffchainLabs/@@nitroRepositorySlug=nitro@@/blob/@@nitroVersionTag=v3.7.2@@/@@nitroPathToPrecompiles=precompiles@@/ArbRetryableTx.go)) provides methods for managing retryables. The model has been adjusted for Nitro, most notably in terms of how retry transactions are scheduled. For more information on retryables, please see [the retryable documentation](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#retryable-tickets).
+ArbRetryableTx ([Interface](https://github.com/OffchainLabs/@@nitroPrecompilesRepositorySlug=nitro-precompile-interfaces@@/blob/@@nitroPrecompilesCommit=f9f65d7c77adf61ad16504a3738a9edcc31e2b2f@@/ArbRetryableTx.sol) | [Implementation](https://github.com/OffchainLabs/@@nitroRepositorySlug=nitro@@/blob/@@nitroVersionTag=v3.7.2@@/@@nitroPathToPrecompiles=precompiles@@/ArbRetryableTx.go)) provides methods for managing retryables. The model has been adjusted for Nitro, most notably in terms of how retry transactions are scheduled. For more information on retryables, please see [the retryable documentation](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#retryable-tickets).
Precompile address: `0x000000000000000000000000000000000000006E`
diff --git a/docs/build-decentralized-apps/reference/07-debugging-tools.mdx b/docs/build-decentralized-apps/reference/07-debugging-tools.mdx
index e6c6ce46b3..22fe44b703 100644
--- a/docs/build-decentralized-apps/reference/07-debugging-tools.mdx
+++ b/docs/build-decentralized-apps/reference/07-debugging-tools.mdx
@@ -16,7 +16,7 @@ The following tools will help you debug your decentralized apps (dApps):
[Tenderly](https://tenderly.co/) is an all-in-one Web3 development platform that empowers developers to build, test, monitor, and operate smart contracts from inception to mass adoption. Tenderly's debugging options focus on providing developers with efficient and user-friendly tools to identify and fix smart contract bugs and production issues. The Debugger enables developers to inspect smart contracts by analyzing precise lines of code in a human-readable format. With Tenderly's Simulator, developers can play out specific historical transactions and current transaction outcomes before sending them onchain, allowing them to change relevant parameters and source code to test and debug contracts. The platform streamlines the debugging process, saving time and resources while improving smart contract reliability.
-Although Tenderly provides great debugging options, there are certain limitations when debugging [parent-to-child chain messages](../../how-arbitrum-works/10-l1-to-l2-messaging.mdx) (also known as Retryable Tickets), due to the utilization of custom Geth errors. For further information on this constraint, please refer to the following [resource](/for-devs/troubleshooting-building#i-tried-to-create-a-retryable-ticket-but-the-transaction-reverted-on-l1-how-can-i-debug-the-issue).
+Although Tenderly provides great debugging options, there are certain limitations when debugging [parent-to-child chain messages](../../how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx) (also known as Retryable Tickets), due to the utilization of custom Geth errors. For further information on this constraint, please refer to the following [resource](/for-devs/troubleshooting-building#i-tried-to-create-a-retryable-ticket-but-the-transaction-reverted-on-l1-how-can-i-debug-the-issue).
### Arbiscan
diff --git a/docs/build-decentralized-apps/reference/08-mainnet-risks.mdx b/docs/build-decentralized-apps/reference/08-mainnet-risks.mdx
index 6c0005677a..0431279295 100644
--- a/docs/build-decentralized-apps/reference/08-mainnet-risks.mdx
+++ b/docs/build-decentralized-apps/reference/08-mainnet-risks.mdx
@@ -7,7 +7,7 @@ displayed_sidebar: buildAppsSidebar
# Arbitrum: Understanding the risks
-Arbitrum One is the first permissionless Ethereum parent chain rollup with full Ethereum smart contract functionality, and is [live on mainnet](https://offchain.medium.com/mainnet-for-everyone-27ce0f67c85e) — as is [Nova](https://medium.com/offchainlabs/its-time-for-a-new-dawn-nova-is-open-to-the-public-a081df1e4ad2), our first [AnyTrust chain](/how-arbitrum-works/08-anytrust-protocol.mdx); We're sure you're (almost) as excited as we are!
+Arbitrum One is the first permissionless Ethereum parent chain rollup with full Ethereum smart contract functionality, and is [live on mainnet](https://offchain.medium.com/mainnet-for-everyone-27ce0f67c85e) — as is [Nova](https://medium.com/offchainlabs/its-time-for-a-new-dawn-nova-is-open-to-the-public-a081df1e4ad2), our first [AnyTrust chain](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx); We're sure you're (almost) as excited as we are!
Here are some risks you should know about before using the system:
### State Of progressive decentralization
diff --git a/docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx b/docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx
index 84732de423..d6f4803f34 100644
--- a/docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx
+++ b/docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx
@@ -42,7 +42,7 @@ ArbSys(100).withdrawEth{ value: 2300000 }(destAddress)
Upon withdrawal, the Ether balance is burned on the Arbitrum side and will later be made available on the Ethereum side.
-`ArbSys.withdrawEth` is a convenience function equivalent to calling `ArbSys.sendTxToL1` with empty `calldataForL1`. Like any other `sendTxToL1` call, it will require an additional call to `Outbox.executeTransaction` on the parent chain after the dispute period elapses for the user to finalize claiming their funds on the parent chain (see [Child to parent chain messaging](/how-arbitrum-works/11-l2-to-l1-messaging.mdx)). Once the withdrawal is executed from the Outbox, the user's `ETH` balance will be credited on the parent chain.
+`ArbSys.withdrawEth` is a convenience function equivalent to calling `ArbSys.sendTxToL1` with empty `calldataForL1`. Like any other `sendTxToL1` call, it will require an additional call to `Outbox.executeTransaction` on the parent chain after the dispute period elapses for the user to finalize claiming their funds on the parent chain (see [Child to parent chain messaging](/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx)). Once the withdrawal is executed from the Outbox, the user's `ETH` balance will be credited on the parent chain.
The following diagram depicts the process that funds follow during a withdrawal operation.
diff --git a/docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx b/docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx
index 007f1bfd03..cbaa2cfe8a 100644
--- a/docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx
+++ b/docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx
@@ -47,11 +47,11 @@ Our architecture consists of three types of contracts:
-All Ethereum-to-Arbitrum token transfers are initiated via the router contract on the parent chain, specifically the `L1GatewayRouter` contract. `L1GatewayRouter` forwards the token's deposit call to the appropriate gateway contract on the parent chain, the `L1ArbitrumGateway` contract. `L1GatewayRouter` is responsible for mapping the parent chain token addresses to L1Gateway contracts, thus acting as a parent/child chain address oracle and ensuring each token corresponds to only one gateway. The `L1ArbitrumGateway` then communicates to its counterpart gateway contract on the child chain, the `L2ArbitrumGateway` contract (typically/expectedly via [retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx)).
+All Ethereum-to-Arbitrum token transfers are initiated via the router contract on the parent chain, specifically the `L1GatewayRouter` contract. `L1GatewayRouter` forwards the token's deposit call to the appropriate gateway contract on the parent chain, the `L1ArbitrumGateway` contract. `L1GatewayRouter` is responsible for mapping the parent chain token addresses to L1Gateway contracts, thus acting as a parent/child chain address oracle and ensuring each token corresponds to only one gateway. The `L1ArbitrumGateway` then communicates to its counterpart gateway contract on the child chain, the `L2ArbitrumGateway` contract (typically/expectedly via [retryable tickets](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx)).
-Similarly, Arbitrum-to-Ethereum transfers initiate via the router contract on the child chain, specifically the `L2GatewayRouter` contract, which in turn calls the token's gateway contract on the child chain. This `L2ArbitrumGateway` contract in turn communicates to its corresponding gateway contract on the parent chain, the `L1ArbitrumGateway` contract (typically/expectedly via [sending child-to-parent messages to the outbox](/how-arbitrum-works/11-l2-to-l1-messaging.mdx)).
+Similarly, Arbitrum-to-Ethereum transfers initiate via the router contract on the child chain, specifically the `L2GatewayRouter` contract, which in turn calls the token's gateway contract on the child chain. This `L2ArbitrumGateway` contract in turn communicates to its corresponding gateway contract on the parent chain, the `L1ArbitrumGateway` contract (typically/expectedly via [sending child-to-parent messages to the outbox](/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx)).
diff --git a/docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx b/docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx
index 1059d2b537..3412398745 100644
--- a/docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx
+++ b/docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx
@@ -173,7 +173,7 @@ As mentioned before, you can also call the method `outboundTransferCustomRefund`
## Step 5: Wait for execution on the child chain
-After calling the deposit method (or the `outboundTransferCustomRefund` if you’re choosing the manual way), you’ll have to wait a bit until the message executes on the child chain. We will verify the status of the underlying retryable ticket created to bridge the tokens. Check this page to learn more about [parent-to-child chain messages, also known as retryables](/how-arbitrum-works/10-l1-to-l2-messaging.mdx).
+After calling the deposit method (or the `outboundTransferCustomRefund` if you’re choosing the manual way), you’ll have to wait a bit until the message executes on the child chain. We will verify the status of the underlying retryable ticket created to bridge the tokens. Check this page to learn more about [parent-to-child chain messages, also known as retryables](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx).
You can programmatically wait for the execution of the transaction on the child chain using Arbitrum’s SDK. You should first wait for the execution of the submission transaction (the one sent to the router contract) and then the execution of the child chain transaction.
diff --git a/docs/get-started/overview.mdx b/docs/get-started/overview.mdx
index 2082ae1027..ff4d36f995 100644
--- a/docs/get-started/overview.mdx
+++ b/docs/get-started/overview.mdx
@@ -14,17 +14,17 @@ Arbitrum suite along with onboarding guidance tailored to specific audiences.
The Arbitrum suite includes the protocols, chains, services, and SDKs that power the Arbitrum ecosystem:
-| Component | Description |
-| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| [Arbitrum Rollup](/how-arbitrum-works/05-validation-and-proving/02-rollup-protocol.mdx) | A **protocol** for scaling Ethereum smart contracts. |
-| [Arbitrum AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx) | A **protocol** for scaling Ethereum smart contracts even further, with a mild trust assumption. |
-| [Arbitrum Nitro](/how-arbitrum-works/01-a-gentle-introduction.mdx) | The node **software** that codifies the Rollup and AnyTrust protocols. |
-| [Arbitrum nodes](/run-arbitrum-node/02-run-full-node.mdx) | **Machines** that run Nitro in order to service and/or interact with an Arbitrum chain. |
-| [Arbitrum One](https://portal.arbitrum.io/?chains=arbitrum-one) | A public Rollup **chain**. |
-| [Arbitrum Nova](https://portal.arbitrum.io/?chains=arbitrum-nova) | A public AnyTrust **chain**. |
-| [Arbitrum bridge](https://bridge.arbitrum.io/) | Lets you move `ETH` and `ERC-20` tokens between Ethereum, Arbitrum, and select Arbitrum (Orbit) chains. |
-| [Arbitrum (Orbit) chains](https://orbit.arbitrum.io/) | Lets you run your own Rollup and AnyTrust chains. |
-| [Arbitrum Stylus](/stylus/gentle-introduction.mdx) | Lets you write EVM-compatible smart contracts in Rust and any other language that compiles to Wasm. |
+| Component | Description |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| [Arbitrum Rollup](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx) | A **protocol** for scaling Ethereum smart contracts. |
+| [Arbitrum AnyTrust](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) | A **protocol** for scaling Ethereum smart contracts even further, with a mild trust assumption. |
+| [Arbitrum Nitro](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx) | The node **software** that codifies the Rollup and AnyTrust protocols. |
+| [Arbitrum nodes](/run-arbitrum-node/02-run-full-node.mdx) | **Machines** that run Nitro in order to service and/or interact with an Arbitrum chain. |
+| [Arbitrum One](https://portal.arbitrum.io/?chains=arbitrum-one) | A public Rollup **chain**. |
+| [Arbitrum Nova](https://portal.arbitrum.io/?chains=arbitrum-nova) | A public AnyTrust **chain**. |
+| [Arbitrum bridge](https://bridge.arbitrum.io/) | Lets you move `ETH` and `ERC-20` tokens between Ethereum, Arbitrum, and select Arbitrum (Orbit) chains. |
+| [Arbitrum (Orbit) chains](https://orbit.arbitrum.io/) | Lets you run your own Rollup and AnyTrust chains. |
+| [Arbitrum Stylus](/stylus/gentle-introduction.mdx) | Lets you write EVM-compatible smart contracts in Rust and any other language that compiles to Wasm. |
## Arbitrum for users
@@ -67,7 +67,7 @@ The Arbitrum suite includes the protocols, chains, services, and SDKs that power
| Resource | Description |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| [Inside Nitro](/how-arbitrum-works/01-a-gentle-introduction.mdx) | A technical deep dive into Nitro's architecture. |
-| [Inside AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx) | A technical deep dive into the AnyTrust protocol. |
+| [Inside Nitro](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx) | A technical deep dive into Nitro's architecture. |
+| [Inside AnyTrust](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) | A technical deep dive into the AnyTrust protocol. |
| [Arbitrum whitepaper](https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf) | The original whitepaper that introduced Nitro. |
| [DAO docs](https://docs.arbitrum.foundation/gentle-intro-dao-governance) | Docs that support members of the Arbitrum DAO. |
diff --git a/docs/how-arbitrum-works/01-a-gentle-introduction.mdx b/docs/how-arbitrum-works/01-a-gentle-introduction.mdx
deleted file mode 100644
index 1de8f9e39d..0000000000
--- a/docs/how-arbitrum-works/01-a-gentle-introduction.mdx
+++ /dev/null
@@ -1,87 +0,0 @@
----
-title: 'A gentle introduction'
-description: 'Learn the fundamentals of Nitro, Arbitrum stack.'
-author: dzgoldman
-sme: dzgoldman
-user_story: As a current or prospective Arbitrum user, I need learn more about Nitros design.
-content_type: get-started
----
-
-import ImageWithCaption from '@site/src/components/ImageCaptions/';
-
-:::info
-
-This page gives a high-level overview. It explains Arbitrum, its purpose, and a brief "how it works." As you progress through the articles in this section, the content will get more technical and dive deeper into each component(s) and function(s) of the Arbitrum technology stack.
-
-:::
-
-Arbitrum is a technology suite designed to improve Ethereum. You can use Arbitrum chains for the same things you do on Ethereum, like using Web3 apps and deploying smart contracts. The difference is that your transactions will be cheaper and faster. Our main product, Arbitrum Rollup, is an Optimistic Rollup protocol that offers the same security as Ethereum.
-
-### But why?
-
-Ethereum is awesome, but it has its limitations. The Ethereum Blockchain can handle only about 20 to 40 transactions per second (TPS) for all users. Once it reaches this limit, users must compete for space to have their transactions included, increasing fees.
-
-Arbitrum Rollup solves this issue! Here's how it works: an Arbitrum Rollup Chain acts as a submodule within Ethereum. Unlike regular Ethereum transactions, we don't need Ethereum nodes to handle every Arbitrum transaction. Instead, Ethereum takes an ["innocent until proven guilty"](https://insights.deribit.com/market-research/making-sense-of-rollups-part-2-dispute-resolution-on-arbitrum-and-optimism/) stance with Arbitrum. Initially, the Parent chain assumes that actions on Arbitrum follow the rules. If there is a rule violation (like someone claiming, "Now I have all of your money"), that claim is challengeable on the parent chain. In this case, we can prove fraud, disregard the invalid claim, and penalize the guilty party. This ability to investigate and confirm fraud on the parent chain is Arbitrum's main feature and explains why it benefits from Ethereum's security.
-
-### How do these fraud proofs work?
-
-People who help manage the Arbitrum chain on the parent chain are called validators. They make claims about the chain's state, dispute others' claims, and more. Most Arbitrum users are unlikely to run a validator, just as most Ethereum users do not operate their parent chain staking node. However, anyone can become a validator; you don't need special permission ([once the allowlist gets lifted](https://docs.arbitrum.foundation/state-of-progressive-decentralization)). You only need to run the [open source validator software](https://github.com/OffchainLabs/nitro) and bond `ETH` if required.
-
-The chain stays secure if there is at least one honest validator. It only takes one trustworthy fraud prover to catch many bad actors. These features make the system "Trustless." Users do not depend on any specific group to keep their funds safe.
-
-### Who does this fraud proofing?
-
-This step is where the "Rollup" part comes in. Arbitrum Rollup chains handle user transaction data by posting it directly on Ethereum. This setup means that as long as Ethereum is secure, anyone can see what happens on Arbitrum. They can also spot and prove any fraud that occurs.
-
-Validators are the nodes that help move the Arbitrum Chain state forward on the parent chain. They make claims about the chain's state and can dispute claims made by others. Most Arbitrum users are unlikely to want to run a validator, just as most Ethereum users typically don't run their parent chain staking nodes. However, anyone can become a validator. Once the allowlist gets removed, users only need to run the open-source validator software and bond `ETH` if they need to take action.
-
-The network stays secure if there is at least one honest validator, which means that just one trustworthy fraud prover can catch any number of bad actors. This setup makes the system "trustless"; users do not have to rely on any specific person to keep their funds safe.
-
-### The game
-
-It's not as complicated as it seems. If two validators disagree, only one is telling the truth. In the event of a dispute, the two validators engage in an interactive game, where they respond to each other in a call-and-response format. This process enables them to narrow their disagreement down to a single computational step—something straightforward, such as multiplying two numbers. This step executes on the parent chain, which shows which party is honest. For a more detailed explanation, [read the explainer on interactive fraud proofs and the challenge protocol](/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx#5-interactive-fraud-proofs-and-the-challenge-protocol).
-
-Users only experience delays when they withdraw funds from Arbitrum back to Ethereum. When withdrawing directly from Arbitrum to Ethereum, users usually wait one week to receive their funds on the parent chain. However, users can skip this waiting period if they use a fast bridge application, often for a small fee. Other activities do not have this delay, like depositing funds from Ethereum to Arbitrum or using a decentralized application on the Arbitrum chain.
-
-### How is it cheaper?
-
-Arbitrum helps lower user transaction costs by reducing the strain on the parent chain. The primary way it does this is by processing transactions in batches. A batch can contain several hundred child chain transactions and gets submitted as one parent chain transaction. This batching makes interacting with the parent chain cheaper since you save on overhead costs compared to submitting each transaction individually.
-
-Additionally, Arbitrum posts transaction data on the parent chain in a compressed format. It only decompresses this data within the child chain environment, reducing the amount of information that needs storing on the parent chain.
-
-### How does it all work together?
-
-At the most basic level, an Arbitrum chain works like this:
-
-
-
-Users and contracts put messages into the inbox. The chain reads the messages one at a time and processes each one. This processing updates the state of the chain and produces some outputs.
-
-If you want an Arbitrum chain to process a transaction for you, you need to put that transaction into the chain's inbox. Then, the chain will see your transaction, execute it, and produce some outputs: a transaction receipt and any withdrawals that your transaction initiated.
-
-Execution is deterministic, meaning that the contents of its inbox uniquely determine the chain's behavior. Because of this, the result of your transaction is knowable as soon as it gets put in the inbox. Any Arbitrum node will be able to tell you the result. (And you can run an Arbitrum node yourself if you want.)
-
-All of the technical details in this document connect to this diagram. To get from this diagram to a complete description of Arbitrum, we'll need to answer questions like these:
-
-- Who keeps track of the inbox, Chain state, and outputs?
-- How does Arbitrum make sure that the chain state and outputs are correct?
-- How can Ethereum users and contracts interact with Arbitrum?
-- How does Arbitrum support Ethereum-compatible contracts and transactions?
-- How are ETH and tokens transferred into and out of Arbitrum chains, and how are they managed while on the chain?
-- How can I run my own Arbitrum node or validator?
-
-### Nitro's Design: The Four Big Ideas
-
-The essence of Nitro and its key innovations lie in four big ideas. We'll list them here with a quick summary of each. We will unpack them in more detail in later sections.
-
-**Big Idea: Sequencing, Followed by Deterministic Execution**: Nitro processes transactions with a two-phase strategy. First, the transactions get organized into a single-ordered sequence, and Nitro commits to that sequence. Then, the transactions get processed in that sequence by a deterministic State Transition Function.
-
-**Big Idea: Geth at the Core**: Nitro supports Ethereum's data structures, formats, and virtual machine by compiling in the core code of the popular go-ethereum ("Geth") Ethereum node software. Using Geth as a library in this way ensures a very high degree of compatibility with Ethereum.
-
-**Big Idea: Separate Execution from Proving**: Nitro takes the same source code and compiles it twice, once to native code for execution in a Nitro node, optimized for speed, and again to WASM for use in proving, optimized for portability and security.
-
-**Big Idea: Optimistic Rollup with Interactive Fraud Proofs**: Nitro settles transactions to the parent Ethereum chain using an Optimistic Rollup protocol, including the interactive fraud proofs pioneered by Arbitrum.
-Now that we have covered the foundational concepts, the big picture, and the four big ideas of Arbitrum Nitro, we will begin a journey following a transaction through the Arbitrum protocol. In the next section, the transaction lifecycle begins.
diff --git a/docs/how-arbitrum-works/01-inside-arbitrum-nitro.mdx b/docs/how-arbitrum-works/01-inside-arbitrum-nitro.mdx
new file mode 100644
index 0000000000..106316bf2a
--- /dev/null
+++ b/docs/how-arbitrum-works/01-inside-arbitrum-nitro.mdx
@@ -0,0 +1,116 @@
+---
+title: 'Inside Arbitrum Nitro'
+description: "Follow a transaction's journey through the complete Arbitrum Nitro stack, from submission to finality."
+author: pete-vielhaber
+sme: mehdi salehi
+user_story: "As a developer, I need to understand how transactions flow through Arbitrum's architecture and how the system ensures security and performance."
+content_type: get-started
+---
+
+import ImageWithCaption from '@site/src/components/ImageCaptions/';
+
+### Transaction Processing Journey on Arbitrum
+
+As a developer initiating a transaction on Arbitrum, gaining a clear understanding of the end-to-end flow—from initial submission through to finality—is helpful, but it is not required.
+
+This overview methodically traces the transaction lifecycle, emphasizing how Arbitrum's architecture ensures precise, efficient, and secure handling at every stage. This article encompasses the complete Arbitrum Nitro stack, beginning with the Sequencer responsible for transaction ordering, advancing to the State Transition Function for execution, and culminating in validation mechanisms that uphold integrity.
+
+Along the way, we will highlight Arbitrum's ability to deliver security on par with Ethereum, while achieving fee reductions by a factor of ten and transaction speeds accelerated by a factor of 100 through optimized scaling techniques.
+
+### The Foundation: Arbitrum's Core Architecture Overview
+
+Before delving into the journey of a transaction, it is important to outline the foundational architecture that powers Arbitrum's operations. Central to the architecture is a simple yet powerful principle: deterministic state transitions, which ensure consistent outcomes across the network. The system revolves around three core components.
+
+
+
+Transactions first enter through the Inbox, serving as the primary gateway into the ecosystem.
+From there, the State Transition Function (STF) processes them in a deterministic fashion, applying rules that guarantee reproducibility.
+Finally, the Outputs component generates the resulting data and state updates, completing the cycle.
+This deterministic model means that identical inputs always produce the same outputs among honest nodes, forming the bedrock of Arbitrum's security. It supports efficient fraud proofs and dispute resolution, allowing verification of execution correctness without the need to rerun entire transactions, thereby minimizing computational overhead.
+
+### Nitro's Four Key Innovations
+
+Arbitrum Nitro's design draws from four pivotal innovations that collectively enhance its efficiency, security, and compatibility.
+
+1. The first involves a two-phase approach to transaction handling: sequencing followed by deterministic execution. In this method, the ordering of transactions forms a single, committed sequence, after which the STF executes them in that fixed order, ensuring predictability and order integrity.
+
+2. The second innovation centers on deep integration with Geth, the core codebase of go-ethereum, a prominent Ethereum node software. By embedding Geth as a library, Nitro fully supports Ethereum's data structures, formats, and virtual machine, delivering near-perfect compatibility and allowing seamless migration of Ethereum applications.
+
+3. Third, Nitro separates execution from proving by compiling its source code twice—once to native code for high-speed operation in Nitro nodes, and once to WebAssembly (WASM) for secure, portable proving processes. This dual compilation optimizes for both performance during runtime and reliability in validation scenarios.
+
+4. Finally, Nitro employs an Optimistic Rollup protocol with interactive fraud proofs, settling transactions on Ethereum's Layer 1 while using Arbitrum's pioneering proof system to resolve disputes efficiently. Together, these innovations enable Arbitrum to match Ethereum's security guarantees, boost overall performance, and maintain full interoperability with existing Ethereum tools and dApps.
+
+### Step 1: Submitting a Transaction
+
+The submission process for a transaction on Arbitrum starts with the user sending the request, with options tailored to balance factors like speed, control, and reliability according to specific needs. Most transactions route through the Sequencer, a specialized node that orders them and issues quick confirmations. This path accommodates various submission methods, including public RPC for development and light usage, third-party RPC for improved throughput, direct Sequencer endpoints for minimal latency in critical operations, and self-hosted Arbitrum nodes for ultimate privacy and customization.
+
+
+
+Alternatively, to counter risks of exclusion or delay by the Sequencer, users can submit directly to the Delayed Inbox contract on Ethereum, bolstering system resilience. In this mechanism, non-Sequencer transactions enter a dedicated queue, where a well-functioning Sequencer typically integrates them within about ten minutes. If delayed beyond 24 hours, any network participant can force inclusion into the main inbox, limiting the Sequencer's influence to temporary delays rather than permanent blocks. While the Sequencer route offers faster soft finality and streamlined workflows, the Delayed Inbox path doubles processing time but emphasizes censorship resistance. Overall, the Sequencer's commitment to ordered inclusion provides "soft finality" for a responsive experience, complemented by these alternatives for robust, flexible operations across applications. For more technical detail about the transaction lifecycle, refer to the [Transaction Lifecycle deep dive](/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx).
+
+### Step 2: Ordering and Broadcasting: The Sequencer
+
+Once a transaction reaches the Sequencer, it integrates into a refined system for ordering and broadcasting, designed to maximize performance while upholding security. The Sequencer immediately shares the transaction through its real-time feed, offering instant network-wide visibility. This feed delivers immediate confirmation of acceptance and sequencing, keeps all nodes synchronized with the latest order, and enables soft finality, allowing users to proceed confidently based on the Sequencer's reliable commitment.
+
+To further optimize, the Sequencer groups transactions into batches rather than processing them individually, which cuts costs and boosts efficiency. Batches form when transactions accumulate to a predefined size or after a set time interval to prevent lags. The data then undergoes compression via the Brotli algorithm, with levels dynamically adjusted from 0 to 11 based on congestion. Higher compression reduces Layer 1 posting expenses at the cost of more computation, while the system shifts toward speed during heavy backlogs.
+
+After batching and compression, the data posts to Ethereum through the Sequencer Inbox Contract using one of two methods.
+
+1. The default, blob transactions under [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844), provide cost-effective and scalable data inclusion when supported by Ethereum.
+
+2. As a fallback, calldata transactions embed data directly, ensuring compatibility even if blob fees rise or [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) is unavailable. This process yields 10-100x cost savings over individual postings and adapts to network conditions for consistent efficiency. For deeper insights into the Sequencer's internals, refer to the [Sequencer deep-dive documentation](/how-arbitrum-works/deep-dives/sequencer.mdx).
+
+### Step 3: Execution Phase: State Transition Function
+
+With ordering and batching complete, execution shifts to the State Transition Function (STF), the core of Arbitrum's processing engine. Arbitrum ensures full Ethereum Virtual Machine (EVM) compatibility via a three-layer architecture. At the base, the Geth core handles EVM execution, aligning behaviors with Ethereum and drawing on its extensively tested code for security. For more technical details about Geth, refer to the [Geth deep dive documentation](/how-arbitrum-works/deep-dives/geth.mdx).
+
+Above this, ArbOS—the Arbitrum Operating System—adds Layer 2 features like cross-chain messaging, fee management, gas pricing, handling of deposits and withdrawals, and advanced tools such as Stylus. The top layer, the node interface, manages RPC connections and APIs, providing Ethereum-like functionality for clients.
+
+In the STF, transactions follow a structured workflow: ArbOS first validates format and funds, then charges gas for Layer 2 execution and Layer 1 posting. Geth executes per EVM standards, after which ArbOS updates states and cross-chain elements, generating receipts and logs to conclude the process. For technical details about ArbOS, refer to the [ArbOS deep dive documentation](/how-arbitrum-works/deep-dives/arbos.mdx).
+
+
+
+For Stylus contracts using WebAssembly (WASM), execution diverts to a WASM runtime, where contracts access state via specialized host I/O calls. This diversion yields 10-70x faster performance than EVM equivalents and full interoperability for mixed calls. The Geth base lets Ethereum apps run unchanged, while ArbOS and Stylus enable Layer 2 optimizations and high-performance innovations. Consult the [State Transition Function deep dive](/how-arbitrum-works/deep-dives/stf-inputs.mdx) for further mechanics.
+
+### Step 4: Finality
+
+At this stage, the transaction achieves two complementary levels of finality, each tailored to Arbitrum's security needs.
+
+1. Soft finality emerges immediately upon the inclusion of the Sequencer feed, offering instant acceptance feedback, a commitment to order, and the ability to act without wait times—as noted in the submission phase. This soft finality" relies on the Sequencer's trustworthiness for usability but lacks cryptographic backing.
+
+2. Hard finality, conversely, solidifies when the batch posts and confirms on Ethereum, inheriting its consensus security, ensuring public data availability, and making the transaction irreversible. This process typically spans 10-20 minutes, varying with Ethereum block times and batch frequency.
+
+The dual model combines rapid soft finality for seamless experiences with Ethereum-level safeguards for hard finality, along with censorship-resistant paths for assured inclusion. This balance delivers quick feedback alongside strong protections, ideal for high-stakes transactions.
+
+### Step 5: Ensuring Correctness: Validation and Dispute Resolution
+
+Following execution, Arbitrum verifies correctness through its validation and dispute systems. Central to this is the BoLD (Bounded Liquidity Delay) protocol, an advanced dispute framework enabling permissionless validation. Unlike conventional optimistic rollups, BoLD permits any participant to validate without approval, while ensuring dispute resolution within bounded timeframes to prevent indefinite delays.
+
+BoLD facilitates a challenge-based defense where honest parties can protect the chain's state against malice. Disputants narrow conflicts to a single execution step via supporting claims, culminating in a one-step proof (OSP) that Ethereum verifies as an impartial arbiter to determine the outcome. While BoLD's intricacies—such as its multi-round challenge games and economic incentives—are extensive, they enhance decentralization and resilience. For more, see the [BoLD Gentle Introduction](/how-arbitrum-works/bold/gentle-introduction.mdx) and [Economics of Disputes documentation](/how-arbitrum-works/bold/bold-economics-of-disputes.mdx).
+
+### Step 6: Bridging: Cross-Chain Communication
+
+Many transactions involve asset or data transfers between Ethereum and Arbitrum, managed through secure bridging protocols. For L1-to-L2 messaging from Ethereum to Arbitrum, options include native token bridging for direct `ETH` deposits, `ERC-20` transfers via the canonical bridge, or support for custom gas tokens. Retryable tickets enable atomic operations with guaranteed retries if execution fails, featuring predictable gas costs and a one-week validity period redeemable by anyone. Direct messaging handles signed EOA messages with verification or unsigned contract messages using address aliasing for security. See the [L1-to-L2 messaging deep dive](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx) for details.
+
+L2-to-L1 transfers from Arbitrum to Ethereum begin with message creation via [`ArbSys.sendTxToL1()`](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys), followed by inclusion in a rollup assertion, a 6.4-day challenge period, and manual Layer 1 execution by any party. Messages validate through Merkle proofs, persist indefinitely until executed, and require manual triggering due to Ethereum's constraints. See the [L2-to-L1 messaging deep dive](/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx) documentation for more details.
+
+The canonical bridge architecture comprises asset contracts on both chains, gateway pairs for specific logic, and routers to direct flows. Its security locks tokens on one layer while minting equivalents on the other, with a seven-day challenge period guarding withdrawals. This setup fosters seamless, unified interactions while safeguarding each chain's integrity.
+
+### Step 7: The Economics of Execution: Gas and Fees
+
+Fees accumulate across the transaction lifecycle to fund processing and security. Arbitrum's dual-fee model separates L2 gas fees, which cover EVM computation and storage with [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559)-style dynamic pricing targeting 7,000,000 gas per second on Arbitrum One, adjusting for congestion, from L1 calldata fees. L1 calldata fees account for Ethereum data posting based on compressed batch contributions and apply only to Sequencer submissions.
+
+A gas speed limit protects infrastructure by capping throughput at 7,000,000 gas per second for Arbitrum One and Nova. Exceeding this triggers [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) fee escalations to prevent node overloads and maintain liveness. This limit prioritizes high-value transactions during peaks while deterring spam, ensuring that validators and the Sequencer stay operational for optimal performance, even though parent contracts handle ultimate security.
+
+Fee calculation during execution involves assessing L2 gas via EVM standards, estimating L1 batch impact, applying current pricing, and collecting `ETH` totals. This model covers all costs effectively, with the speed limit reinforcing security by keeping validation in sync. Refer to the [Gas and fees deep dive](/how-arbitrum-works/deep-dives/gas-and-fees.mdx) for more.
+
+### Step 8: Advanced Features
+
+Arbitrum extends beyond standard Layer 2 capabilities with features like Stylus, which supports smart contracts in languages such as Rust, C, and C++ via WASM. It offers 10-70x faster execution and 100-500x better memory efficiency than the EVM, with full interoperability for cross-calls. Stylus runs in a co-located WASM VM using host I/O for state access—details in the [Stylus Gentle Intro](/stylus/gentle-introduction.mdx).
+
+Timeboost refines ordering to capture MEV for chain operators, protect users from attacks like front-running, reduce spam-related congestion, and allow customizable policies. See the [Timeboost Gentle Introduction](/how-arbitrum-works/timeboost/gentle-introduction.mdx) for insights.
+
+AnyTrust provides cost-optimized data availability with a mild trust model, relying on a Data Availability Committee (DAC) of `N` members, where at least two are assumed honest. It uses BLS-signed Data Availability Certificates (DACerts) and falls back to Layer 1 posting if needed. Keysets define member keys and thresholds; DACerts include hashes, expirations, and signatures; and servers support various storage, such as local files or Amazon S3. The Sequencer sends batches to the committee, gathers signatures for DACerts, and posts them to Layer 1, defaulting to full data if the required signatures are not present. Ideal for low-cost apps like gaming, as in Arbitrum Nova—explore the [AnyTrust protocol documentation](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx).
diff --git a/docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/docs/how-arbitrum-works/02-transaction-lifecycle.mdx
deleted file mode 100644
index f7622ecc94..0000000000
--- a/docs/how-arbitrum-works/02-transaction-lifecycle.mdx
+++ /dev/null
@@ -1,76 +0,0 @@
----
-title: Sequencing, Followed by Deterministic Execution
-description: 'Learn the fundamentals of the Arbitrum Transaction Lifecycle, sequencing, and deterministic execution.'
-author: pete-vielhaber
-sme: Mehdi
-user_story: As a current or prospective Arbitrum user, I need to learn more about the transaction lifecycle.
-content_type: get-started
----
-
-import ImageZoom from '@site/src/components/ImageZoom';
-
-This section explores the various methods users can employ to submit transactions for inclusion on the Arbitrum chain. We discuss the different pathways available—sending transactions to the Sequencer or bypassing it by submitting transactions through the Delayed Inbox contract on the parent chain. By outlining these options, we aim to clarify how users can interact with the network, detail the processes involved in each method, and identify the modules responsible for handling these transactions. This overview will enhance your understanding of the initial steps in Arbitrum ecosystem's Transaction lifecycle and prepare you for a detailed exploration of transaction inclusion mechanisms in the subsequent sections.
-
-The first subsection, [Submitting Transactions to the Sequencer](#submitting-transactions-to-the-sequencer), presents four different methods users can utilize to send their transactions to the sequencer: via Public RPC, Third-Party RPC, Arbitrum Nodes, and the Sequencer Endpoint. Transactions sent through the first three pathways will route through our Load Balancer before reaching the sequencer. In contrast, the Sequencer Endpoint allows transactions to bypass the Load Balancer and be sent directly to the sequencer.
-
-The second subsection, [Bypassing the Sequencer](#bypassing-the-sequencer), describes an alternative method where users can include their transactions on the Arbitrum chain without relying on the sequencer. By sending transactions directly to the Delayed Inbox contract on the parent chain, users gain additional flexibility, ensuring that their transactions can be processed even if the sequencer is unavailable or if they prefer not to use it.
-
-This diagram illustrates the various pathways for submitting transactions to the Arbitrum chain. It highlights the options for sending transactions through the sequencer or bypassing it and using the Delayed Inbox contract on the parent chain.
-
-
-
-## Submitting transactions to the Sequencer
-
-This section outlines the different methods for users to submit transactions to the sequencer on the Arbitrum chain. There are four primary ways to do this: Public RPC, Third-Party RPCs, Arbitrum Nodes, and the Sequencer Endpoint. We will explore these methods in detail, explaining when to choose one over the other and how to use each to effectively submit transactions to the Arbitrum sequencer.
-
-### 1. Public RPC
-
-Arbitrum provides public RPCs for its main chains: Arbitrum One, Arbitrum Nova, and Arbitrum Sepolia. Due to their rate-limited nature, these RPC endpoints are suitable for less resource-intensive operations. Public RPCs can be an accessible option for general use cases and light interactions with the network.
-
-For more details on the specific RPC endpoints for each chain, please see [this section](https://docs.arbitrum.io/build-decentralized-apps/reference/node-providers#arbitrum-public-rpc-endpoints) of the documentation.
-
-### 2. Third-Party RPC
-
-Users also have the option to interact with Arbitrum's public chains using third-party node providers. These providers are often the same popular ones used for Ethereum, making them reliable choices for resource-intensive operations. We recommend using these third-party providers when performance and scalability are critical.
-
-You can find a list of supported third-party providers [here](https://docs.arbitrum.io/build-decentralized-apps/reference/node-providers#third-party-rpc-providers).
-
-### 3. Arbitrum Nodes
-
-Another approach for sending transactions to the sequencer is through self-hosted Arbitrum nodes. Running a node gives you direct control over your transactions, which go to the sequencer via the Sequencer Feed.
-
-Please see the [Arbitrum Node](https://docs.arbitrum.io/run-arbitrum-node/overview) documentation to learn more about setting up and running a node.
-
-### 4. Sequencer Endpoint
-
-The Sequencer Endpoint is the most direct method for users looking to minimize delays in their transactions reaching the sequencer. Unlike standard RPC URLs, the Sequencer Endpoint supports only `eth_sendRawTransaction` and `eth_sendRawTransactionConditional` calls, bypassing the load balancer entirely. This endpoint makes it an optimal choice for users who require the quickest transaction processing time.
-
-The diagram below shows different ways to submit transactions to the Sequencer:
-
-
-
-## Bypassing the Sequencer
-
-This section delves into an alternative method for submitting transactions to the Arbitrum chain, bypassing the Sequencer. This page focuses on how users can send their transactions directly to the Delayed Inbox contract on the parent chain rather than through the Sequencer. This method offers two distinct paths a transaction can take, with each route interacting with the network differently to achieve transaction inclusion. This approach provides users with greater flexibility and ensures that transactions can still be processed if the Sequencer is unavailable or if users choose not to depend on it. This section highlights these alternative submission mechanisms and underscores the robustness and decentralization features inherent in the Arbitrum network.
-
-In **Diagram 3**, we demonstrate how users can submit their transactions using the Delayed Inbox contract to bypass the Sequencer. As illustrated in the diagram, there are two possible paths for transaction handling. When a transaction is submitted to the Delayed Inbox, the Sequencer may automatically pick it up, include it as an ordered transaction, and send it to the Sequencer feed. However, if the Sequencer does not process the transaction within 24 hours, users have the reliable option to call the `forceInclude` function on the `SequencerInbox` contract. This action ensures that the Sequencer to picks up the transaction and includes it in the ordered transaction list, providing users with a sense of security about their transactions.
-
-
-
-To send a transaction to the Delayed Inbox instead of submitting it to the sequencer, users can construct their transaction and then call the [`sendL2Message`](https://github.com/OffchainLabs/nitro-contracts/blob/fbbcef09c95f69decabaced3da683f987902f3e2/src/bridge/AbsInbox.sol#L150) function, passing the data of the serialized signed transaction as an argument. This function allows users to send a generic child chain messages to the chain, suitable for any message that does not require parent chain validation.
-
-If the sequencer is not back online within 24 hours or decides to censor the transaction, users can invoke the [`forceInclusion`](https://github.com/OffchainLabs/nitro-contracts/blob/fbbcef09c95f69decabaced3da683f987902f3e2/src/bridge/SequencerInbox.sol#L284) function on the `SequencerInbox` contract. This action ensures their transaction is included on the chain, bypassing the sequencer's role.
-
-Additionally, the Arbitrum SDK provides the [`InboxTools`](https://github.com/OffchainLabs/arbitrum-sdk/blob/792a7ee3ccf09842653bc49b771671706894cbb4/src/lib/inbox/inbox.ts#L64C14-L64C24) class, which simplifies the process of submitting transactions to the Delayed Inbox. Users can utilize the [`sendChildSignedTx`](https://github.com/OffchainLabs/arbitrum-sdk/blob/792a7ee3ccf09842653bc49b771671706894cbb4/src/lib/inbox/inbox.ts#L401C16-L401C33) method to send the transaction and the [`forceInclude`](https://github.com/OffchainLabs/arbitrum-sdk/blob/792a7ee3ccf09842653bc49b771671706894cbb4/src/lib/inbox/inbox.ts#L367) method to ensure its inclusion. The SDK also offers helper methods like [`signChildTx`](https://github.com/OffchainLabs/arbitrum-sdk/blob/792a7ee3ccf09842653bc49b771671706894cbb4/src/lib/inbox/inbox.ts#L429) to assist with signing the transaction during the creation of the serialized signed transaction hex string, streamlining the entire process.
diff --git a/docs/how-arbitrum-works/04-state-transition-function/01-stf-gentle-intro.mdx b/docs/how-arbitrum-works/04-state-transition-function/01-stf-gentle-intro.mdx
deleted file mode 100644
index 1339fcb306..0000000000
--- a/docs/how-arbitrum-works/04-state-transition-function/01-stf-gentle-intro.mdx
+++ /dev/null
@@ -1,36 +0,0 @@
----
-title: 'A gentle introduction'
-description: 'Learn the fundamentals of Nitro, Arbitrum stack.'
-author: petevielhaber
-sme: Mehdi
-user_story: As a current or prospective Arbitrum user, I need learn more about Nitros design.
-content_type: get-started
----
-
-A State Transition Function (STF) is a core mechanism in blockchain systems that defines how the system evolves from one state to another when transactions are processed. At its essence, the STF takes the current state of the blockchain–a comprehensive snapshot of account balances, smart contract data, and other ledger information–and an input (such as a transaction or a block of transactions) and deterministically computes the new state. This deterministic property is crucial because it ensures that all nodes in a decentralized network arrive at the same result when applying transactions, thereby maintaining consensus across the system.
-
-With Arbitrum, the STF plays an even more pivotal role. Offchain transactions are executed in batches according to this function, with the STF periodically submitting a concise summary of changes to the parent chain. This approach leverages offchain computation to boost throughput and reduce gas costs while anchoring the process to Ethereum's robust security model. To safeguard against incorrect or malicious offchain execution, Arbitrum employs a challenge mechanism known as fraud proofs. If a dispute arises, the STF can be recomputed step-by-step onchain, enabling the network to verify the validity of the offchain computations and ensure that the errors or fraudulent behavior are detected and rectified.
-
-Beyond these foundational aspects, the STF on the Arbitrum Nitro Stack closely mirrors Ethereum's STF in its overall structure but incorporates several key modifications to accommodate the unique requirements of the Arbitrum chain. Essentially, the function receives a sequence of ordered transactions as its input, applies a defined set of rules to these inputs, and produces a new final state that reflects all the updates from the batch of transactions.
-
-With the introduction of Stylus, Arbitrum expands its execution model beyond the Ethereum Virtual Machine (EVM) by adding WebAssembly (WASM)–based smart contract execution. This enhancement allows high-performance smart contracts written in Rust, C, and C++ to run alongside traditional EVM contracts. The integration of Stylus introduces several modifications to the STF, including:
-
-### Stylus-specific transaction processing
-
-A modified version of Geth that recognizes and processes Stylus transactions, ensuring proper inclusion in state transitions.
-
-### Execution in a WASM runtime
-
-Stylus transactions execute in ArbOS's WASM runtime instead of the EVM, enabling faster execution and more efficient computation.
-
-### Stylus gas accounting and pricing
-
-Unlike standard EVM transactions, Stylus transactions introduce new gas pricing models that account for factors such as opcode pricing, host I/O operations, and Ink usage costs.
-
-### Interoperability with the EVM
-
-Stylus contracts can interact seamlessly with Solidity contracts, enabling hybrid applications that leverage EVM and WASM execution environments.
-
-These Stylus-related changes aim to maintain compatibility with Ethereum's execution model while introducing a more efficient, flexible, and scalable alternative for smart contract development.
-
-In the following sections, we will explain what these inputs are and how Arbitrum nodes receive them. We will also discuss the rules implemented in the Arbitrum Nitro Stack's STF, highlighting the differences between how state transitions occur in Ethereum, Arbitrum, and Stylus-based execution environments. Stylus-specific execution tasks handled within ArbOS will be covered separately, focusing on host I/O operations, caching, and WASM memory management.
diff --git a/docs/how-arbitrum-works/04-state-transition-function/02-stf-inputs.mdx b/docs/how-arbitrum-works/04-state-transition-function/02-stf-inputs.mdx
deleted file mode 100644
index 02c2696ee7..0000000000
--- a/docs/how-arbitrum-works/04-state-transition-function/02-stf-inputs.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: 'Inputs to the State Transition Function'
-description: 'Learn the fundamentals of Nitro, Arbitrum stack.'
-author: petevielhaber
-sme: Mehdi
-user_story: As a current or prospective Arbitrum user, I need learn more about Nitros design.
-content_type: get-started
----
-
-Arbitrum nodes receive
- transaction
- inputs through a dual-channel approach that enhances reliability and consistency.
-
-First, nodes subscribe
-to the Sequencer feed, receiving the upcoming ordered transactions
-published in real time. To learn more, refer to the [real-time sequencer feed documentation](/how-arbitrum-works/03-sequencer.mdx#real-time-sequencer-feed).
-
-In addition to the Sequencer Feed, Arbitrum nodes subscribe to the `SequencerBatchDelivered` event on the parent chain. This event occurs whenever a batch of transactions gets delivered to the parent chain via the batch poster. Upon receiving this event, nodes verify that the transactions recorded on the parent chain match those previously provided by the Sequencer feed. If discrepancies arise, nodes re-organize to adopt the transactions confirmed on the parent chain, using the parent chain as the definitive source of truth.
-
-As discussed in the [considerations and limitations section](/how-arbitrum-works/03-sequencer.mdx#considerations-and-limitations), these methods may be more appropriate for different applications depending on their specific requirements.
-
-Arbitrum nodes reliably receive an ordered set of transactions through these mechanisms, which serve as inputs for the State Transition Function (STF). The function then processes these transactions and outputs the final state, ensuring consistency and security across the network.
-
-## Message types
-
-Arbitrum supports submitting a variety of message types to its chains. These messages fall into two broad categories:
-
-- Messages submitted directly to the Sequencer as child chain messages
-- Messages submitted to the parent chain
-
-For more details on message types beyond standard child chain transactions, please refer to the [parent-to-child chain messaging documentation](/how-arbitrum-works/10-l1-to-l2-messaging.mdx).
-
-In the system, we refer to these messages as `L1IncomingMessage` [source code reference](https://github.com/OffchainLabs/nitro/blob/4ac7e9268e9885a025e0060c9ec30f9612f9e651/arbos/incomingmessage.go#L54).
-
-When submitted to the Sequencer feed, messages are tagged with a unique identifier, ensuring Arbitrum nodes correctly differentiate and process them. Below is the list of message types, their associated constant values, and descriptions:
-
-```solidity
-uint8 constant L2_MSG = 3;
-uint8 constant L1MessageType_L2FundedByL1 = 7;
-uint8 constant L1MessageType_submitRetryableTx = 9;
-uint8 constant L1MessageType_ethDeposit = 12;
-uint8 constant L1MessageType_batchPostingReport = 13;
-uint8 constant L2MessageType_unsignedEOATx = 0;
-uint8 constant L2MessageType_unsignedContractTx = 1;
-
-uint8 constant ROLLUP_PROTOCOL_EVENT_TYPE = 8;
-uint8 constant INITIALIZATION_MSG_TYPE = 11;
-```
-
-- `L2_MSG` (3): Child chain messages submitted directly to the Sequencer.
-
-- `L1MessageType_L2FundedByL1` (7): Child chain messages that go to the parent chain's Delayed Inbox, with funding provided on the parent chain itself.
-
-- `L1MessageType_submitRetryableTx` (9): Submitting parent chain messages to the child chain via retryable tickets.
-
-- `L1MessageType_ethDeposit` (12): Child chain messages that handle deposits of native tokens (`ETH`) into the child chain.
-
-- `L1MessageType_batchPostingReport` (13): Used by the Sequencer to update the pricing model based on payment(s) by the batch poster.
-
-- `L2MessageType_unsignedEOATx` (0): Child chain messages submitted by externally owned accounts (EOAs) to the parent chain that does not include a signature.
-
-- `L2MessageType_unsignedContractTx` (1): Child chain messages submitted on the parent chain that does not include a signature.
-
-- `ROLLUP_PROTOCOL_EVENT_TYPE` (8): Arbitrum Classic used it for messages sent to bridge, Nitro does not use it.
-
-- `INITIALIZATION_MSG_TYPE` (11): The first message added to a new Rollup inbox. Its presence indicates proper initialization of the Rollup.
-
-These tagged identifiers enable Arbitrum nodes to parse incoming messages and direct their payloads appropriately, ensuring smooth and reliable network operation.
diff --git a/docs/how-arbitrum-works/04-state-transition-function/03-ethereum-vs-arbitrum.mdx b/docs/how-arbitrum-works/04-state-transition-function/03-ethereum-vs-arbitrum.mdx
deleted file mode 100644
index d72d6b7544..0000000000
--- a/docs/how-arbitrum-works/04-state-transition-function/03-ethereum-vs-arbitrum.mdx
+++ /dev/null
@@ -1,154 +0,0 @@
----
-title: 'State Transition Function: Ethereum vs. Arbitrum'
-description: 'Learn the fundamentals of Nitro, Arbitrum stack.'
-author: petevielhaber
-sme: Mehdi
-user_story: As a current or prospective Arbitrum user, I need learn more about Nitros design.
-content_type: get-started
----
-
-import ImageZoom from '@site/src/components/ImageZoom';
-
-This section explains the architecture and implementation of the State Transition Function (STF) in Ethereum and the Arbitrum Nitro stack, highlighting their similarities and key differences.
-
-## STF in Ethereum
-
-In Ethereum, the STF receives transactions as inputs, processes them via the EVM, and produces the final state as output.
-
-The Ethereum state is a vast data structure represented by a modified Merkle Patricia Trie. This structure holds all accounts, linking them via hashes and reducing the entire state to a single root hash stored on the blockchain.
-
-The Ethereum Virtual Machine (EVM) operates similarly to a mathematical function: given an input, it produces a deterministic output. Ethereum's STF encapsulates this behavior:
-
-$$
-Y(S, T) = S'
-$$
-
-Here, `S` represents the current state, `T` denotes the transaction, and `S'` is the new state resulting from the execution of `T`.
-
-The EVM operates as a stack machine with a maximum depth of 1024 items. Each item is a 256-bit word, chosen for compatibility with 256-bit cryptography (e.g., Keccak-256 hashes and secp256k1 signatures).
-
-During execution, the EVM uses transient _memory_ (a word-addresses byte array) that only persists for the duration of a transaction. In contrast, each contract maintains a persistent Merkle Patricia _storage_ trie–a word-addressable word array–that forms part of the global state.
-
-smart contract bytecode compiles into a series of EVM opcodes
-that perform standard stack operations (such as `XOR`, `AND`, `ADD`, `SUB`) and blockchain-specific operations
-(such as `ADDRESS`, `BALANCE`, `BLOCKHASH`).
-
-Geth (go-Ethereum) is one of the primary
- client
- implementations of Ethereum, serving as the practical embodiment of both the STF and the EVM execution
-engine. It processes transactions by executing the smart contract's bytecode and updating the global
-state, ensuring that every state change is deterministic and secure.
-
-In essence, Geth converts transaction inputs into precise computational steps within the EVM, maintaining the intricate data structures that underpin Ethereum's blockchain. Its robust design not only powers the core operations of Ethereum but also provides the foundation for advanced modificaitons in platforms like the Arbitrum Nitro stack.
-
-## STF on Arbitrum
-
-The Arbitrum Nitro stack implements a modified version of Ethereum's STF. While it retains the core principles of Ethereum, several Arbitrum-specific features and processes distinguish it from Ethereum's implementation. Key differences include:
-
-### Gas accounting
-
-In Arbitrum, executing a transaction incurs two costs, one for executing on the child chain and another for submitting transaction batches to the parent chain. This dual fee structure requires a different approach to gas accounting.
-
-### Base fee mechanism
-
-Gas prices and base fees on Arbitrum change differently from Ethereum's. Arbitrum maintains two base fees: one to track the cost of execution on the child chain and another to estimate the cost of posting batches to the parent chain. The mechanism that changes the child chain's base fee differs from what is currently on Ethereum.
-
-### Cross-chain bridge functionalities
-
-Arbitrum supports cross-chain messaging and regular transactions, facilitating seamless interactions between the child and parent chains.
-
-### Block time and block number
-
-The Arbitrum chain uses two block numbers: the child chain's block number, and the block number of the first non-Arbitrum ancestor chain. Additionally, block times are determined by the child chain's sequencer clock, as described in the [Block numbers and time documentation](/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx).
-
-### Precompiles
-
-Specific precompiled contracts on the Arbitrum chain will process Arbitrum-specific features. Moreover, individual Arbitrum chains may implement their own custom precompiles.
-
-### Custom transaction types
-
-Nitro Geth introduces several child chain-specific transaction types that utilize the non-standard [EIP-2718: Typed Transaction Envelope](https://eips.ethereum.org/EIPS/eip-2718). These types represent different transactions on the Arbitrum chain, such as retryable transactions.
-
-### Stylus in the STF
-
-With the introduction of Stylus, Arbitrum Nitro now supports executing smart contracts written in Rust, C, and C++, offering a high-performance alternative to the EVM. Unlike standard Ethereum transactions, Stylus contracts execute in a WASM-based runtime within ArbOS, leveraging efficient host I/O operations and optimized caching mechanisms.
-
-## Implementation overview
-
-The Arbitrum STF is implemented using a modified version of Geth and integrated with ArbOS. This combination allows Arbitrum to support additional functionalities while maintaining compatibility with Ethereum's core execution model. The following diagram provides an abstract overview:
-
-
-
-The organization of the Nitro node software has three main layers:
-
-1. **Base layer (Geth Core)**: This layer comprises the core components of Geth that emulate EVM contract execution and maintain Ethereum's state data structures. Nitro integrates this code as a library with minor modifications to insert additional hooks.
-
-2. **Middle layer (ArbOS)**: ArbOS is custom software that extends child chain functionalities. It decompresses and parses Sequencer data batches, accounts for parent chain gas costs (collecting fees for reimbursement), and supports cross-chain bridge operations (e.g., Ether and token deposits and withdrawals). More details about ArbOS are in the [next section](#arbos-overview).
-
-3. **Top layer (Node software)**: Primarily derived from Geth, this layer handles network connections, incoming RPC requests, and other high-level functionalities required to operate an Ethereum-compatible blockchain node.
-
-Because both the top and bottom layers are Geth-based, this architecture is often referred to as a "geth sandwich"–with Geth as the "bread" and ArbOS as the "filling."
-
-The State Transition Function (STF) itself consists of the modified Geth core (base layer) combined with a portion of ArbOS (middle layer). In practice, the STF is a designated function within the source code (including all the code it calls), which:
-
-- Takes the bytes of a transaction received in the inbox as input.
-
-- Operates on a modifiable copy of the Ethereum state tree.
-
-- May modify the state during execution.
-
-- Emits a new block header (formatted in Ethereum's block header structure) that appends to the Nitro chain.
-
-## Modified Geth on Nitro
-
-[Nitro's](https://github.com/OffchainLabs/nitro) design builds upon the robust foundation of Geth with targeted modifications that enable it to support child chain-specific functionalities. These modifications include:
-
-### Custom hooks and interface adaptions
-
-Nitro integrates a series of custom hooks within Geth's transaction processing flow. These hooks allow Nitro to implement dual gas accounting, manage parent chain calldata fees, and handle custom transaction types–such as retryable transactions–without deviating from Ethereum's core logic.
-
-### Strategic re-appropriations of core types
-
-By adapting key data structures and interfaces within Geth, Nitro ensures that state transitions and transaction executions can seamlessly accommodate child chain optimizations. These adaptations maintain compatibility with Ethereum's existing architecture while enabling enhanced functionality.
-
-### Minimal yet essential adjustments
-
-The modifications made to Geth are deliberately minimal to preserve its stability and security properties. This "modified Geth" layer, in tandem with ArbOS, provides the necessary enhancements for Nitro's STF without compromising the deterministic behavior of the EVM.
-
-### Stylus-specific features
-
-Geth is modified to route Stylus transactions, handle custom gas accounting, and track Stylus-specific state changes, ensuring seamless execution within Arbitrum Nitro.
-
-Detailed technical explanations of these modifications are in the following sections, where we dive deeper into how Nitro's custom hooks, interface implementations, and Geth adaptations come together to support an advanced, high-performance STF.
-
-## ArbOS overview
-
-ArbOS is the child chain EVM hypervisor that provides the execution environment for the Arbitrum chain. Acting as a trusted "system glue" component within the STF, ArbOS is responsible for:
-
-### Managing network resources
-
-It allocates and tracks resources necessary for executing transcations on the child chain.
-
-### Block production
-
-ArbOS processes incoming sequencer data batches to produce child chain blocks, ensuring the state is updated correctly.
-
-### Cross-chain messaging
-
-It facilitates communication between the parent and child chains, supporting functionalities like Ether and token deposits and withdrawals.
-
-### Enhanced EVM execution
-
-ArbOS operates its instrumented instance of Geth to execute smart contracts, incorporating additional logic specific to the child chain environment.
-
-### Stylus-specific tasks in ArbOS
-
-ArbOS manages host I/O calls, memory operations, and execution context for Stylus transactions, ensuring efficient and deterministic processing with the WASM runtime.
-
-By offloading tasks that would execute at a high cost on the parent chain, ArbOS enables these operations to be performed quickly and cost-effectively on the child chain. This design reduces computational and storage costs and offers significant flexibility, allowing the child chain code to evolve or be customized more easily than a parent chain-enforced architecture.
-
-While Ethereum's STF forms the basis for secure and deterministic state updates, Arbitrum's Nitro stack builds on this foundation with key modifications–ranging from dual gas accounting to cross-chain messaging–to optimize performance and flexibility. These innovations are realized through minimal yet strategic modifications to Geth, integrated seamlessly with ArbOS, forming the "geth sandwich."
-
-With the introduction of Stylus, Arbitrum extends its execution model beyond the EVM, enabling high-performance WASM-based smart contracts. This integration introduces additional modifications to Geth, ensuring compatibility with Stylus transactions while preserving Ethereum-like execution guarantees. These changes include handling Stylus-specific transaction types and ensuring smooth interaction between the EVM and WASM environments.
-
-In the following section, we'll dive deep into these modifications, exploring how Nitro leverages 'Geth at the core' and the custom enhancements provided by ArbOS to deliver an advanced, high-performance STF. Stylus-specific tasks within ArbOS are covered separately to highlight its role in managing execution, host I/O, and memory operations.
diff --git a/docs/how-arbitrum-works/04-state-transition-function/06-stylus-execution-path.mdx b/docs/how-arbitrum-works/04-state-transition-function/06-stylus-execution-path.mdx
deleted file mode 100644
index 8f18cdd560..0000000000
--- a/docs/how-arbitrum-works/04-state-transition-function/06-stylus-execution-path.mdx
+++ /dev/null
@@ -1,109 +0,0 @@
----
-title: 'Stylus execution path'
-description: 'Learn the fundamentals of Nitro, Arbitrum stack.'
-author: petevielhaber
-sme: Mehdi
-user_story: As a current or prospective Arbitrum user, I need learn more about Nitros design.
-content_type: get-started
----
-
-This article details how Stylus integrates into the State Transition Function (STF), covering execution flow, messaging handling, caching, and interactions with ArbOS and Geth.
-
-## 1. Execution flow of a Stylus transaction
-
-When a Transaction interacts with a Stylus contract, its execution follows a distinct path compared to EVM transactions:
-
-### Transaction submission and routing
-
-- The transaction is included in a child chain block by the Sequencer.
-
-- Geth processes the transaction and determines its target contract.
-
-- If the target is a Stylus contract, ArbOS routes execution to the WASM runtime instead of the EVM.
-
-### Stylus execution within ArbOS
-
-- ArbOS retrieves the Stylus program from its cache (`stylus/src/cache.rs`) or loads it from storage if not cached.
-
-- The WebAssembly System Interface (Go-WASI) initializes a secure execution environment.
-
-- The WASM module executes within ArbOS, processing instructions efficiently and calling host I/O functions.
-
-### Host I/O operations for blockchain state access
-
-- Stylus contracts do not use EVM opcodes. Instead, they interact with the blockchain through host I/O calls handled by ArbOS.
-
-- These include storage access (`TLOAD` `TSTORE`), arithmetic operations (`MULMOD`, `ADDMOD`), and context retrieval (`GETCALLER`, `GETCALLVALUE`).
-
-- ArbOS ensures these operations are efficient and compatible with Ethereum's state model.
-
-#### State commitment and finalization
-
-- Once execution is complete, ArbOS finalizes storage changes and updates logs and receipts.
-
-- Geth processes the final transaction result and commits it to the state tree.
-
-This process bypasses the EVM interpreter entirely, allowing Stylus contracts to execute significantly faster than their Solidity counterparts.
-
-## 2. Stylus caching and gas pricing
-
-### Stylus gas pricing model
-
-Unlike standard EVM gas pricing, Stylus pricing follows a multi-dimensional cost model, incorporating:
-
-- **Ink cost (memory and execution cost)**
-
- - Measure in `Ink` units (Stylus's equivalent of computational gas).
-
- - `Ink` pricing varies based on execution complexity, memory usage, and computation steps.
-
- - Complex WASM operations consume more `Ink`, directly impacting execution costs.
-
-- **Opcode pricing**
-
- - WASM instructions are assigned individual execution costs similar to EVM opcodes.
-
- - Heavy computation opcodes are priced higher.
-
- - Cheap opcodes (e.g., simple arithmetic, bitwise operations) have minimal costs.
-
-- **Host I/O pricing**
-
- - Stylus introduces fine-grained pricing for different I/O calls:
-
- - **Storage read/writes**: Priced based on access pattern and data size.
-
- - **Precompile calls**: Stylus-specific precompiles have fixed execution costs.
-
- - **External calls to EVM contracts**: Encapsulated within ArbOS transaction handling, with additional gas considerations.
-
-### Stylus caching
-
-Stylus contracts leverage an advanced caching system to minimize execution overhead within ArbOS:
-
-- **LRU (Least Recently Used) caching**: Keeps the most recently accessed Stylus contracts in memory for fast execution.
-
-- **Persistent long-term caching**: Caching for selected contracts may occur across blocks based on an economic auction model.
-
-- **Init costs and execution pricing**: Instead of a flat gas cost, Stylus contracts have dynamic execution costs based on WASM complexity. ArbOS maintains pricing parameters (`initCost`, `cachedCost`) that adjust based on future optimizations in WASM execution.
-
-## 3. Interaction with ArbOS and Geth
-
-| Execution Stage | Handled By |
-| ---------------------- | --------------------------------------------------------- |
-| Transaction submission | **Geth** (identifies target contract) |
-| Stylus execution | **ArbOS** (switches to WASM runtime) |
-| Host I/O calls | **ArbOS** (handles storage, call data, context retrieval) |
-| State commitment | **Geth and ArbOS** (finalizes updates, commits to state) |
-
-## 4. Go-WASI and co-threads in Stylus execution
-
-ArbOS executes Stylus contracts using Go-WASI, a WASM-compatible runtime with custom optimizations for Arbitrum. Key features include:
-
-- **Memory management**: WASM modules execute in a sandboxed environment with strict memory allocation policies.
-
-- **Co-threads for efficient execution**: Instead of traditional synchronous execution, Stylus employs co-threading, enabling lightweight task switching and parallelism where possible.
-
-- **Deterministic execution**: Ensures that Stylus contracts remain fully deterministic and compatible with Ethereum's consensus model.
-
-These optimizations make Stylus an extremely efficient execution environment, capable of outperforming the EVM while maintaining security and compatibility with Ethereum's state model.
diff --git a/docs/how-arbitrum-works/05-validation-and-proving/01-validation-and-proving.mdx b/docs/how-arbitrum-works/05-validation-and-proving/01-validation-and-proving.mdx
deleted file mode 100644
index bc55188bed..0000000000
--- a/docs/how-arbitrum-works/05-validation-and-proving/01-validation-and-proving.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: Validation and Proving Mechanisms
-description: 'Learn the fundamentals of validation and proving mechanisms on Arbitrum.'
-author: pete-vielhaber
-sme: Mehdi
-user_story: As a current or prospective Arbitrum user, I need to learn more about validation and proving mechanisms.
-content_type: get-started
----
-
-The validation and proving mechanism in Arbitrum ensures the integrity of offchain execution while maintaining Ethereum's security guarantees. As an Optimistic Rollup, Arbitrum assumes that transactions execute correctly unless challenged. Arbitrum employs interactive fraud proofs to resolve conflicts efficiently, if a dispute arises.
-
-At the core of Arbitrum's validation model is the separation of execution and proving: transactions execute optimistically, while state transitions can be verified onchain if necessary. Arbitrum achieves this through WAVM (WebAssembly for Arbitrum Virtual Machine), a modified WASM format optimized for proving, and the BoLD dispute protocol, which resolves disagreements using an interactive, multi-round challenge system.
-
-This section will explore two primary topics:
-
-## [Rollup protocol and validation](/how-arbitrum-works/05-validation-and-proving/02-rollup-protocol.mdx)
-
-Reviews how Arbitrum records and validates transactions, the role of validators, and the mechanics of state confirmations.
-
-## [Proving and challenge protocols](/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx)
-
-Discusses how the protocol handles resolving disputes using interactive proofs and narrowing conflicts down to a single execution step.
diff --git a/docs/how-arbitrum-works/05-validation-and-proving/02-rollup-protocol.mdx b/docs/how-arbitrum-works/05-validation-and-proving/02-rollup-protocol.mdx
deleted file mode 100644
index 6190591275..0000000000
--- a/docs/how-arbitrum-works/05-validation-and-proving/02-rollup-protocol.mdx
+++ /dev/null
@@ -1,272 +0,0 @@
----
-title: Rollup Protocol and Validation
-description: 'Learn the fundamentals of the Arbitrum Rollup Protocol and validation.'
-author: pete-vielhaber
-sme: Mehdi
-user_story: As a current or prospective Arbitrum user, I need to learn more about the Rollup protocol and validation.
-content_type: get-started
----
-
-import ImageZoom from '@site/src/components/ImageZoom';
-
-Arbitrum operates as an Optimistic Rollup, which advances the chain's
-state based on transaction assertions unless a dispute arises.
-This approach enables scalability, lower costs, and high throughput while maintaining security through
-Ethereum's trustless validation model.
-
-Optimistic Rollups work by separating execution from proving to ensure efficient transaction processing without immediate validation. The execution process is covered in detail in the [State Transition Function](/how-arbitrum-works/04-state-transition-function/01-stf-gentle-intro.mdx). This section focuses on validation and proving mechanisms. We will cover how child chain validators confirm the chain's state and how assertions are posted to parent chain for finalization, with the potential for future challenges if an assertion is determined to be incorrect.
-
-## Execution vs. proving: Separating responsibilities
-
-A fundamental design choice in Arbitrum is the separation of execution from proving, which allows for:
-
-#### Efficient execution
-
-Transactions are processed optimistically without immediate verification.
-
-#### Deterministic proving
-
-If challenged, state transitions are replayable and verified onchain.
-
-To achieve this, Arbitrum compiles the State Transition Function (STF) into different formats:
-
-#### Execution mode
-
-Uses Go's native compiler for high-performance execution on validator nodes.
-
-#### Proving mode
-
-Compiles to WebAssembly (WASM), which transforms into WebAssembly for Arbitrum Virtual Machine (WAVM) for fraud-proof verification.
-
-This dual compilation approach ensures that Arbitrum nodes execute transactions efficiently while allowing deterministic trustless verification on parent chain.
-
-### Stylus execution and proving
-
-Stylus extends Arbitrum's execution model by enabling WASM-based
-smart contracts. While execution occurs natively in WAVM, the proving process follows the same interactive
-fraud-proof mechanism as the EVM, ensuring Stylus transactions are challengeable and deterministically
-verifiable. Fraud proofs for Stylus transactions involve WAVM opcode evaluation, leveraging Arbitrum's
-existing one-step proof (OSP) system.
-
-## The role of validators and the Rollup chain
-
-Arbitrum's Rollup Protocol relies on validators––network participants responsible for ensuring state correctness. The protocol enforces security through the following principles:
-
-#### Permissionless validation
-
-Anyone can become a validator by running an Arbitrum node.
-
-#### Trustless verification
-
-Validators confirm assertions, ensuring transactions adhere to protocol rules.
-
-#### Fraud-proof system
-
-If an incorrect assertion is detected, validators can challenge it and trigger an interactive fraud-proof.
-
-Validators interact with the Rollup chain, a sequence of assertions representing state updates. Each assertion includes:
-
-#### Predecessor assertion
-
-The last confirmed valid state.
-
-#### State transition output
-
-The result of applying transactions.
-
-#### Inbox message consumption
-
-A record of processed messages from the parent chain.
-
-#### Execution claim
-
-A cryptographic commitment to the computed state.
-
-### Assertions progress through different stages:
-
-#### Proposed
-
-A validator submits a state assertion.
-
-#### Challenged (if necessary)
-
-If another validator disputes the assertion, an interactive fraud-proof initiates.
-
-#### Confirmed
-
-It becomes final if no one challenges the assertion within the dispute window (6.4 days).
-
-This model ensures that as long at least one honest validator participates, the correct execution will always be confirmed.
-
-## Arbitrum Rollup protocol
-
-Before diving into the Rollup protocol, it is important to clarify two key points:
-
-1. End users and developers do not need to interact with the Rollup Protocol.
- - Like a train passenger relying on the engine without needing to understand its mechanics, users, and developers can interact with Arbitrum without engaging with the validation process.
-2. The protocol does not determine transaction results, it only confirms them.
- - The ordered sequence of messages in the chain's inbox dictates the transaction outcomes. The protocol ensures correctness and finality but does not alter execution results.
-
-Since transaction execution is deterministic, the Rollup Protocol exists to confirm results and prevent fraud. This mechanism serves two key purposes:
-
-- **Detecting dishonest behavior**: If a validator submits an incorrect state, others can challenge it.
-- **Anchoring Rollup state to the parent chain**: The parent chain itself does not execute every child chain transaction but serves as the final arbiter of state correctness.
-
-## Validators and assertions in the Rollup protocol
-
-Validators play a central role in maintaining Arbitrum's integrity. Some validators act as proposers, submitting assertions to Ethereum and placing a `WETH` bond as collateral. If their assertion is determined to be incorrect, they lose their bond.
-
-Since at least one honest validator can always confirm the correct state, Arbitrum remains as trustless as Ethereum.
-
-### The Rollup chain assertions vs. child chain blocks
-
-The Rollup chain consists of assertions, which serve as checkpoints summarizing multiple child chain blocks.
-
-- Child chain blocks contain individual transaction data
-- Assertions provide state summaries recorded on Ethereum
-- Each assertion may represent multiple child chain blocks, optimizing gas costs and reducing Ethereum storage usage.
-
-Validators submit assertions by calling `createNewAssertion` in the Rollup contract. Assertions contain structured data known as `AssertionInputs`, which capture the before-state and after-state of execution for future validation.
-
-### Contents of an assertion
-
-Each assertion consists of:
-
-- **Assertion number**: A unique identifier
-- **Predecessor assertion**: The last confirmed assertion
-- **Number of child chain blocks**: The total child chain blocks included
-- **Number of inbox messages**: Messages consumed during execution
-- **Output hash**: A cryptographic commitment to the resulting state
-
-Arbitrum ensures assertions are automatically confirmed or rejected based on protocol rules:
-
-1. An assertion is confirmed if:
- - Its predecessor is the latest confirmed assertion
- - The dispute window has passed without challenges
-2. An assertion is rejected if:
- - Its predecessor assertion is invalid
- - A conflicting assertion has been confirmed
-
-For more details on how the Rollup chain works under BoLD, the [gentle introduction](/how-arbitrum-works/bold/gentle-introduction.mdx) provides an overview that touches on the Rollup chain.
-
-:::note
-
-Validators and proposers serve different roles. Validators validate transactions by computing the next chain state using the chain's STF, whereas proposers can also assert and challenge the chain state on the parent chain.
-
-:::
-
-Except for the assertion number, the contents of the assertion are all just claims by the assertion's proposer. Arbitrum doesn't know at first whether any of these fields are correct. The protocol should eventually confirm the assertion if all of these fields are correct. The protocol should eventually reject the assertion if one or more of these fields are incorrect.
-
-An assertion implicitly claims that its predecessor assertion is correct, which means that it also claims the correctness of a complete history of the chain: a sequence of ancestor assertions that reaches back to the birth of the chain.
-
-An assertion also implicitly claims that its older siblings (older assertions with the same predecessor), if there are any, are incorrect. If two assertions are siblings, and the older sibling is correct––then the younger sibling is considered incorrect, even if everything else in the younger sibling is true.
-
-The assertion is assigned a deadline, which indicates how much time other validators have to respond to it. For an assertion `R` with no older siblings, this will equal the time the assertion was posted, plus an interval of time known as the challenge Period; subsequent younger siblings will have the same deadline as their oldest sibling (`R`). You don't need to do anything if you're a validator and agree that an assertion is correct. If you disagree with an assertion, you can post another assertion with a different result, and you'll probably end up in a challenge against the party who proposed the first assertion (or another party acting in support of that assertion). More on challenges below:
-
-In the normal case, the Rollup chain will look like this:
-
-
-
-On the left, representing an earlier part of the chain's history, we have confirmed assertions. These have been fully accepted and recorded by the parent chain contracts that manage the chain. The newest of the confirmed assertions, assertion 94, is called the "latest confirmed assertion."
-
-On the right, we see a set of newer proposed assertions. The protocol can't yet confirm or reject them because their deadlines haven't run out yet. The oldest assertion whose fate has yet to be determined, assertion 95, is called the "first unresolved assertion."
-
-Notice that a proposed assertion can build on an earlier proposed assertion. This process allows validators to continue proposing assertions without waiting for the protocol to confirm the previous one. Normally, all of the proposed assertions will be valid, so they will all eventually be accepted.
-
-Here's another example of what the chain state might look like if several validators are being malicious. It's a contrived example designed to illustrate a variety of cases that can come up in the protocol, all smashed into a single scenario.
-
-
-
-There's a lot going on here, so let's unpack it:
-
-- Assertion 100 was confirmed.
-- Assertion 101 claimed to be a correct successor to assertion 100, but 101 was rejected.
-- Assertion 102 eventually receives confirmation as the correct successor to 100.
-- Assertion 103 was confirmed and is now the latest confirmed assertion.
-- Assertion 104 was proposed as a successor to assertion 103, and 105 was proposed as a successor to 104. 104 was rejected as incorrect, consequently, 105 was rejected because its predecessor was rejected.
-- Assertion 106 is unresolved. It claims to be a correct successor to assertion 103 but the protocol hasn't yet decided whether to confirm or reject it. It is the first unresolved assertion.
-- Assertions 107 and 108 claim to chain from 106. They are also unresolved. If 106 gets rejected, they will be automatically rejected too.
-- Assertion 109 disagrees with assertion 106 because they both claim the same predecessor. At least one of them will eventually be rejected, but the protocol hasn't yet resolved them.
-- Assertion 110 claims to follow 109. It is unresolved. If 109 gets rejected, 110 will be automatically rejected too.
-- Assertion 111 claims to follow 104. 111 will inevitably get rejected because its predecessor has already been rejected. However, it remains active, because the protocol resolves assertions in assertion number order, so the protocol will have to resolve 106 through 110 in order, before it can resolve 111. After 110 resolves, the protocol will immediately reject 111.
-
-Again this sort of thing is very unlikely in practice. In this diagram, at least four different bonds are on incorrect assertions, and when the dust settles, at least four bonds will be forfeited. The protocol handles these cases correctly, but they're rare corner cases. This diagram illustrates the possible situations that are possible in principle and how the protocol would deal with them.
-
-## Delays
-
-Even if the Assertion Tree has multiple conflicting assertions and multiple disputes are in progress, validators can continue making new assertions. Honest validators will build on one valid assertion (intuitively, an assertion is also an implicit claim of the validity of all of its parent assertions). Likewise, users can continue transacting on the child chain since transactions will continue to post in the chain's inbox.
-
-The only delay users experience during a dispute is their [Child to parent chain messages](/how-arbitrum-works/11-l2-to-l1-messaging.mdx) (i.e., withdrawals). A key property of BoLD is that we can guarantee that, in the common case, their withdrawals/messages will only get delayed for one challenge period. In the case of an actual dispute, the withdrawals/messages will be delayed by no more than two challenge periods, regardless of the adversaries' behavior during the challenge.
-
-## Who will be validators?
-
-Anyone can do it, but most people will choose not to. In practice, we expect people to validate a chain for several reasons.
-
-- It is possible to pay validators for their work by the party that created the chain or someone else. A chain is configurable, so some of the funds from user transaction fees are paid directly to validators.
-- Parties with significant assets at bond on a chain, such as decentralized app developers, exchanges, power users, and liquidity providers, may choose to validate in order to protect their investment.
-- Anyone who wants to validate can do so. Some users may choose to validate to protect their interests or be good citizens. But ordinary users don't need to validate, and we expect most users won't.
-
-### Staking and validator incentives
-
-Arbitrum requires validators to bond `ETH` as a security deposit to ensure honest participation and prevent malicious behavior. This mechanism enforces economic accountability:
-
-- **Proposers** (validators submitting assertions) must bond `ETH` to support their claims.
-- **Challenges** against incorrect assertions result in bond forfeiture for dishonest validators.
-- **Successful challengers** receive a portion of the dishonest validator's bond as a reward.
-
-Validators can adopt different roles:
-
-1. **Active validators**: Regularly propose new assertions.
-2. **Defensive validators**: Monitor the network and challenge incorrect assertions.
-3. **Watchtower validators**: Passively observe and raise alarms when fraud is detected.
-
-The protocol design requires only one honest validator to secure the system, making Arbitrum trustless and resistant to Sybil attacks.
-
-### Staking mechanism
-
-Some validators will act as bonders at any given time, while others remain passive. Bonders deposit `ETH` bonds into Arbitrum's smart contracts, which are forfeited if they lose a challenge.
-
-:::note
-
-Nitro chains exclusively accept `ETH` as collateral for staking.
-
-:::
-
-A single bond can secure a sequence of assertions, meaning a validator's bond applies to multiple checkpoints of the chain's history. This checkpoint allows efficient resource use while maintaining security.
-
-A validator must be bonded to its predecessor to create a new assertion. The bond ensures that validators have economic risk in any assertion they make.
-
-### Staking rules
-
-1. **New validators**: If unbonded, a validator can bond on the latest confirmed assertion by depositing the required `ETH` bond.
-2. **Extending an existing bond**: The validator can extend its bond to one successor assertion if already bonded. - If a validator submits a new assertion, they automatically extend their existing bond to cover it.
-3. **Unbonding**: A validator can only request a refund if they have a bond on the latest confirmed assertion.
-4. **Losing a challenge**: If a validator's assertion is challenged successfully (i.e., they are malicious), they lose **all** their bonded `ETH` across any unresolved assertions.
-
-Since unbonding is not allowed mid-assertion validators must commit until their assertion is confirmed or disproven.
-
-### Handling disputes and delays
-
-Multiple disputes may be active simultaneously if conflicting assertions arise in the Assertion Tree. However, Arbitrum's protocol ensures that:
-
-- **Honest validators can continue asserting**, building on the last correct assertion.
-- **Users can keep transacting** on the child chain without disruption.
-- **Child-to-parent chain withdrawals** may experience delays - Typically, withdrawals experience a single challenge period (6.4 days) delay. - A key property of BoLD is that we can guarantee that in the common case, withdrawals/messages will only experience delay of one challenge period. In the case of an actual dispute, the withdrawals/messages will be delayed by no more than two challenge periods, regardless of the adversaries' behavior during the challenge.
-
-Despite these delays, Arbitrum guarantees that honest assertions always succeed, maintaining Ethereum-level security.
-
-### Who becomes a validator?
-
-Arbitrum's validation process is permissionless, allowing anyone to participate. However, in practice, most users will not act as validators.
-
-Common validator motivations include:
-
-- **Financial incentives**: Some validators receive payment from network fees or the chain's owner.
-- **Asset protection**: app developers, exchanges, and liquidity providers may validate the chain to protect their holdings.
-- **Public interest**: Some participants validate purely for network integrity, ensuring fair execution.
-
-For most users, validation is unnecessary, as the network relies on economic incentives and fraud-proof mechanisms to maintain security.
diff --git a/docs/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx b/docs/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx
deleted file mode 100644
index 64ef819cf3..0000000000
--- a/docs/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx
+++ /dev/null
@@ -1,444 +0,0 @@
----
-title: Proving and Challenge Protocol
-description: 'Learn the fundamentals of the Arbitrum proving and challenge protocols'
-author: pete-vielhaber
-sme: Mehdi
-user_story: As a current or prospective Arbitrum user, I need to learn more about the Arbitrum proving and challenge protocols.
-content_type: get-started
----
-
-import ImageZoom from '@site/src/components/ImageZoom';
-
-This document details the mechanisms for proving correct execution and resolving disputes in the Rollup Protocol. It explains how the system separates ordinary execution from proving, transforms WASM into a specialized proving format (WAVM), and employs interactive fraud proofs to resolve disputes efficiently.
-
-## 1. Separating execution from proving
-
-
-
-One of the key challenges in designing a practical Rollup system is balancing fast, ordinary execution with the need for reliable proofs of that execution. Nitro addresses this challenge by using the same source code for both purposes but compiling it to different targets:
-
-- **Execution compilation**:
- - The [Nitro node software](https://github.com/OffchainLabs/nitro) is compiled with the ordinary Go compiler into native code for the target architecture.
- - This native binary is distributed as source code and as a Docker image, making it deployable on various nodes.
-- **Proving compilation**:
- - For proving, only the portion of the code that is the State Transition Function (STF) gets compiled by the Go compiler into WebAssembly (WASM).
- - The generated WASM code transforms into a specialized format called WAVM.
- - In any dispute regarding the STF, the WAVM code is referenced to resolve the correct result.
-
-## 2. WAVM: A specialized proving format
-
-WAVM is a modified version of WASM designed to meet the needs of fraud proofs. The following features describe it:
-
-- **Portability and Structure**:
- - WASM was selected because it is portable, well-specified, and supported by robust tools.
-- **Modifications made in WAVM**:
- - **Removal of unused features**:
- - WAVM removes some WASM features that the Go compiler never generates. The transformation phase ensures these features are absent.
- - **Restrictions on certain features**:
- - Floating-point instructions: WAVM does not contain floating-point instructions. Instead, any floating-point operations get replaced by calls to the Berkeley SoftFloat library.
- - Rationale: Using software floating-point libraries reduces the risk of incompatibilities between different architecture.
- - **Nested control flow**:
- - WAVM flattens control flow constructs by converting them into jump instructions.
- - **Variable-time instructions**:
- -Some instructions in WASM may take a variable amount of time to execute. WAVM transforms these into constructs with fixed-cost instructions to simplify proving.
- - **Additional opcodes for blockchain interaction**:
- - WAVM adds new opcodes to enable the code to interact with the blockchain environment.
- - For example, new instructions allow the WAVM code to read and write the chain's global state, retrieve the next message from the chain's inbox, or signal a successful end to the STF execution.
-
-## 3. `ReadPreImage` and the hash oracle trick
-
-An interesting instruction in WAVM is `ReadPreImage`, which the "hash oracle trick" uses. This mechanism works as follows:
-
-- **Functionality of `ReadPreImage`**:
- - **Input**: A hash `H` and an offset `I`.
- - **Output**: The word of data at offset `I` in the preimage of `H` along with the number of bytes written (zero if `I` is at or beyond the end).
-- **Constraints for safety**:
- - Generating a preimage for an arbitrary hash is infeasible. Therefore, the instruction is allowed only when:
- - The preimage is publicly known
- - The preimage's size is known to be less than a fixed upper bound (approximately 110 kbytes).
-- **Usage examples in Nitro**:
- - **State tree access**:
- - Nitro's state tree is stored offchain as a Merkle tree, with nodes indexed by their Merkle hashes.
- - The STF only stores the root hash but can retrieve any node's contents using `ReadPreImage`.
- - **Block headers**:
- - The instruction fetches recent publicly known child chain block headers of bounded size.
-
-:::info Historical Note
-
-This "hash oracle trick" originates from the original Arbitrum design, where the Merkle hash of a data structure is stored and full contents are retrievable on demand.
-
-:::
-
-## 4. Resolving disputes using interactive fraud proofs
-
-Disputes resolution in Optimistic Rollups is a critical design decision. The protocol must decide which execution version is correct when two parties disagree.
-
-### 4.1 Overview of dispute resolution
-
-- **Optimistic Rollups**:
- - Assume that assertions about execution are correct unless challenged.
-- **Dispute Resolution Options**:
- - **Interactive proving**:
- - Parties engage in a challenge game to narrow down the dispute executed steps.
- - **Re-executing transactions**:
- - The parent chain re-executes transactions, checking each state transition.
-
-:::note
-
-Zero-knowledge Rollups avoid the dispute situation by directly proving correctness via ZK proofs.
-
-:::
-
-### 4.2 Interactive proving
-
-Arbitrum favors interactive proving due to its efficiency and flexibility.
-
-
-
-#### The interactive proving process
-
-1. **Initial claim and dispute start**:
- - Suppose Alice claims that the chain will produce a specific result. Bob disagrees.
-2. **Bisection of the dispute**:
- - **First round**:
- - Alice posts an assertion covering `N` steps.
- - Bob challenges the assertion.
- - Alice then provides two sub-assertions, each covering `N/2` steps.
- - **Subsequent rounds**:
- - Bob chooses one half to challenge, and the process repeats––halving the disputed steps until only a single instruction remains.
-3. **Final one-step proof**:
- - Once the dispute narrows to a single execution step, the parent chain referee verifies that one-step claim.
-
-#### Simplified bisection protocol
-
-- **Step-by-step breakdown**:
- - Alice provides a commitment to the entire computation history.
- - She bisects her claim into two halves.
- - Bob selects the half he disputes.
- - This iteration of the bisection continues until the dispute reaches a single instruction.
-
-#### Why bisection correctly identifies a cheater
-
-1. **If Alice's claim is correct**:
- - Every bisection provides truthful intermediate states.
- - Bob's challenge eventually leads to a correct one-step proof, allowing Alice to win.
-2. **If Alice's claim is incorrect**:
- - One of Alice's halves will be false at some bisection.
- - Bob can always choose the incorrect half, ultimately forcing an incorrect one-step proof that is not verifiable.
- - Thus, an honest party will always be able to challenge a dishonest claim.
-
-### 4.3 Re-executing transactions (alternative approach)
-
-- **Mechanism**:
- - Each transaction would include a state hash after its execution.
- - In case of a dispute, the parent chain would re-execute every transaction to verify the correctness.
-- **Drawbacks**:
- - Requires a state claim for every transaction, increasing computational load.
- - In a dispute, the entire transaction must be re-executed onchain, leading to high gas costs.
-
-:::info
-
-Interactive proving is more efficient in optimistic and pessimistic cases, as it minimizes onchain computation and adapts to Ethereum's gas limits.
-
-:::
-
-## 5. Interactive fraud proofs and the challenge protocol
-
-Interactive fraud proofs form the basis for resolving proposer disputes when conflicting assertions are made.
-
-### 5.1 Dispute scenario
-
-- **Example setup**:
- - Suppose the Rollup chain includes assertions 93 and 95, which are siblings (both following assertion 92).
- - Alice is bonded on assertion 93, while Bob is bonded on assertion 95.
- - Bob's bonding on 95 implies that assertion 93 must be incorrect.
-- **Initiation of the challenge**:
- - An interactive challenge is initiated automatically when two proposers place bonds on sibling assertions.
- - Multiple assertions may participate in a single challenge.
- - The protocol records and referees the challenge and eventually declares a winner, confiscating the bonds of the losing parties and removing them as proposers.
-
-### 5.2 The two-phase challenge game
-
-1. **Bisection phase**:
- - The goal is to narrow the dispute to a single execution step.
- - At each stage, claims are bisected into smaller segments (first over child chain blocks, then over "big steps" of 2²⁶ instructions, and finally to a single instruction).
- - The parent chain referee only checks that the moves have "the right shape" (e.g., that the bisection was performed correctly) without evaluating the correctness of execution.
-2. **One-step proof phase**:
- - Once the dispute reduces to one instruction, any player can initiate the one-step proof.
- - The parent chain executes the disputed instruction using the proof data provided.
- - If the one-step proof is correct, the disputed edge is confirmed, and the challenges resolves.
-
-### 5.3 Efficiency considerations
-
-- **Optimistic case**:
- - Interactive proving allows a single assertion to cover all transactions in a block.
-- **Pessimistic case**:
- - Only one instruction is re-executed onchain during a dispute.
-- **Gas limits**:
- - The interactive proving model can work with higher per-transaction gas limits since most work is done offchain.
-- **Implementation flexibility**:
- - The system only requires verification a one-step proof onchain, rather than full transaction re-execution.
-
-### 5.4 `ChallengeManager`: The arbiter
-
-
-
-- **Role**:
- - The `ChallengeManager` contract arbitrates the challenge game.
- - It tracks assertion histories, timers, and state commitments.
-- **State machine**:
- - A state machine represents the challenge with several distinct phases:
- - **Block challenge**:
- - The challenge begins by bisecting over global states (including block hashes) to narrow down the dispute to a single block.
- - **Big-step execution challenge**:
- - Upon identifying the block, the execution challenge bisects a "chunk" of 2²⁶ instructions.
- - **Small-step execution challenge**:
- - This phase bisects the chunk until the dispute narrows to a single instruction.
- - **One-step proof**:
- - A final onchain one-step proof confirms the disputed instruction.
-- **Winning the challenge**:
- - Winning is not instantaneous; a built-in time delay safeguards against erroneous challenge resolutions.
- - This delay allows time for diagnosing and correcting errors via contract upgrades if necessary.
-
-## 6. One-step proof assumptions
-
-The one-step proof (OSP) is the final arbiter of a single disputed instruction. Its design accounts for several key assumptions:
-
-### 6.1 Assumptions for correct execution
-
-- **Correct cases**:
- - In a challenge involving at least one honest party, the honest side will always prove a reachable case.
- - An arbitrator generates the WAVM code (from a valid WASM compile) and should not encounter unreachable cases in correct execution.
-
-### 6.2 Handling unreachable cases
-
-- **Definition**:
- - An unreachable case is a situation that is assumed never to arise during correct execution.
-- **Behavior in malicious challenges**:
- - In challenges between malicious assertions, unreachable cases may occur and can be handled arbitrarily by the one-step proof.
-- **Safety in honest challenges**:
- - An honest party never needs to prove an unreachable case.
- - If a dishonest party attempts to force an unreachable case, it will be preceded by an invalid reachable case, ensuring that the dishonest party eventually loses the challenge.
-
-### 6.3 Additional safety assumptions
-
-- **WAVM code validity**:
- - The WAVM code produced by the arbitrator comes from valid WASM compile. It is checked using `wasm-validate` from the WebAssembly Binary Toolkit (WABT).
-- **Inbox message size**:
- - Inbox messages must be small enough (no larger than 117,964 bytes) to be fully available for proving.
-- **Preimage requests**:
- - Preimages requested via `ReadPreImage` must be known and within the size limit (117,964 bytes).
- - Examples include block headers, state trie nodes, and recent child chain block headers.
-
-## 7. WASM to WAVM transformation
-
-Not all WASM instructions are mapped directly 1:1 to WAVM opcodes. The transformation design simplifies execution for proving and enables additional blockchain interactions.
-
-### 7.1 Transformation process overview
-
-- **Source**:
- - The Go compiler produces WASM code.
-- **Transformation**:
- - A simple transformation stage converts the WASM code into WAVM code.
-- **Purpose**:
- - Ensure that the WAVM code is free from unused features, restricted in its functionality where necessary, and augmented with additional opcodes for blockchain interaction.
-
-### 7.2 Key differences between WASM and WAVM
-
-- **Removed features**:
- - Any WASM features not generated by the Go compiler are removed.
-- **Restricted features**:
- - Berkeley SoftFloat library calls replace floating-point instructions.
- - The nested control flow flattens into jumps.
- - Variable-time instructions transform into fixed-cost instructions.
-- **Added opcodes**:
- - New opcodes additions for interacting with the blockchain (e.g., reading global state, fetching inbox messages, signaling completion).
-
-### 7.3 Translation of specific WASM constructs
-
-- **Block and loop**:
- - In WASM, blocks contain instructions and branch instructions for exiting blocks.
- - In WAVM, since instructions are flat, branch instructions are replaced with jumps to predetermined destinations.
-- **If and Else**:
- - Translated into a block with an `ArbitraryJumpIf` instructions.
- - **Structure example**:
- - Begin block with endpoint `end`
- - Conditional jump to `else` block
- - [if-statement instructions]
- - Unconditional branch (to skip else)
- - `Else` block: [else-statement instructions]
- - `End` block
-- **Branch instructions (`br` and `br_if`)**:
- - Translated into `ArbitraryJump` and `ArbitraryJumpIf` with jump destinations known at compile time.
-- **Branch table (`br_table`)**:
- - Translated to a series of conditional checks for each possible branch, with a default branch if no conditions are met.
-- **`Local.tee`**:
- - Implemented by duplicating the local value (using a `Dup` opcode) followed by a `LocalSet`.
-- **Return**:
- - The function signature knows the number of return values:
- - A `MoveFromStackToInternal` opcode is added for each return value.
- - A loop uses `IsStackBoundary` to clean up the stack.
- - Finally, `MoveFromInternalToStack` opcodes are added for each return value, followed by a `Return` opcode.
-- **Floating-point instructions**:
- - `f32` and `f64` values are bitcast to `i32` and `i64`.
- - Cross-module calls go to the floating-point library.
- - Return values are bitcast back to floating-point types.
-
-### 7.4 WAVM custom opcodes not in WASM
-
-WAVM includes several unique opcodes that simplifying proving. They breakdown into several categories:
-
-#### Invariants and Codegen internal opcodes
-
-- **General assumptions**:
- - Many opcodes assume specific items on the stack (e.g., "pops an `i32" means the top stack item must be an `i32`).
- - WASM validation and arbitrator code generation maintain these invariants.
-- **Examples of custom opcodes**:
-
-| Opcode | Name | Description |
-| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 0x8000 | `EndBlock` | Pops an item from the block stack. |
-| 0x8001 | `EndBlockIf` | Peeks the top value (assumed `i32`) and, if non-zero, pops an item from the block stack. |
-| 0x8002 | `InitFrame` | Pops a caller module index (`i32`), a caller module internals offset (`i32`), and a return `InternalRef`; creates a stack frame with these details and the locals Merkle root. |
-| 0x8003 | `ArbitraryJumpIf` | Pops an `i32`; if non-zero, jumps to the program counter provided in the argument data. |
-| 0x8004 | `PushStackBoundary` | Pushes a stack boundary marker onto the stack. |
-| 0x8005 | `MoveFromStackToInternal` | Pops an item from the stack and pushes it to an internal stack. |
-| 0x8006 | `MoveFromInternalToStack` | Pops an item from the internal stack and pushes it back onto the stack. |
-| 0x8007 | `IsStackBoundary` | Pops an item from the stack; if it is a stack boundary, pushes an `i32` with value 1; otherwise, 0. |
-| 0x8008 | `Dup` | Peeks at the top stack item and pushes a duplicate. |
-
-#### Linking opcode
-
-- **Purpose**:
- - Generated for linking modules together:
-- **Opcode**:
-
-| Opcode | Name | Description |
-| ------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 0x8009 | `CrossModuleCall` | Pushes current program counter, module number, and module internals offset; splits the argument data into function index and module index; jumps to the beginning of that function. |
-
-#### Host calls
-
-- **Used in host call implementations**:
- - They enable libraries to perform host calls and access the caller's memory.
-- **Examples of host call opcodes**:
-
-| Opcode | Name | Description |
-| ------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 0x800A | `CallerModuleInternalCall` | Pushes the current program counter, module number, and module internals offset; retrieves caller module internals offset; jumps to caller module function if valid, otherwise errors. |
-| 0x8010 | `GetGlobalStateBytes32` | Pops a pointer and index; writes the global state bytes32 value (if all alignment and bounds checks pass) to the pointer. |
-| 0x8011 | `SetGlobalStateBytes32` | Pops a pointer and index; reads a bytes32 value from memory and writes it into the global state. |
-| 0x8012 | `GetGlobalStateU64` | Pops a pointer and index; writes the global state u64 value to memory (with alignment and bounds checking). |
-| 0x8013 | SetGlobalStateU64 | Pops a pointer and index; reads a u64 from memory and writes it into the global state. |
-| 0x8020 | `ReadPreImage` | Pops an offset and pointer; reads a 32-byte Keccak-256 hash from memory; writes up to 32 bytes of its preimage starting from the offset; pushes the number of bytes written. |
-| 0x8021 | `ReadInboxMessage` | Pops an offset, pointer, and i64 message number; attempts to read an inbox message; if out-of-bounds, enters a “too far” state; writes up to 32 bytes and pushes the number of bytes written. |
-| 0x8022 | `HaltAndSetFinished` | Sets the machine status to finished, halting execution and marking it as successful. |
-
-## 8. WAVM floating-point implementation
-
-Floating-point operations in WAVM are handled differently to ensure determinism and consistency:
-
-- **Implementation using Berkeley SoftFloat**:
- - Instead of implementation IEEE 754-2019 directly in WAVM, floating-point instructions are replaced with calls to the Berkeley SoftFloat-3e library.
- - The soft float library is linked, and floating-point operations are implemented via cross-module calls.
-- **Known divergences**:
- - For example, floating-point to integer truncation will saturate on overflow (instead of erroring), which is safer and more consistent with x86 behavior.
- - These divergences follow proposals (e.g., saturating opcodes) that are not yet widely adopted.
-
-## 9. WAVM modules and linking
-
-WASM's notion of modules is extended in WAVM to support multi-module programs. This extension allows:
-
-### 9.1 Entrypoint module
-
-- **Definition**:
- - The entry point module is the starting point of execution.
-- **Behavior**:
- - It calls any modules' start functions if specified.
- - If then calls the main module's `main` function:
- - **For Go**:
- - Sets `argv` to `["js"]` (to mimic the JS environment) and calls `run`.
- - **For Rust**:
- - Simply calls `main` with no arguments.
-
-### 9.2 Library exports
-
-- **Export naming convention**:
- - Libraries export function using the pattern `module__name`.
- - This convention allows future libraries or the main module to import these functions.
-- **Example**:
- - The `wasi-stub` library provides functions that Rust imports, adhering to the WebAssembly System Interface (WASI).
-
-### 9.3 WAVM guest calls
-
-- **Mechanism**:
- - Libraries can call exports of the main module using the naming scheme `"env"` `"wavm_guest_call__*"`.
-- **Usage example**:
- - `go-stub` calls Go's resume function when queueing asynchronous events via `wavm_guest_call_resume()`, and retrieves the new stack pointer with `wavm_guest_call_getsp()`.
-
-### 9.4 Caller module internals call
-
-- **Purpose**:
- - Each stack frame retains information about the caller module and its internals offset.
-- **Implementation**:
- - WAVM appends four "internal" functions to each module that perform small memory load or store operations.
- - Libraries use opcodes such as `wavm_caller_{load,store}{8,32}` to access their caller's memory.
- - Only libraries can access their caller's memory; restrictions prevent the main module from doing so.
-
-## 10. Stylus proving and fraud detection
-
-Stylus introduces an execution path alongside the EVM, enabling
- smart Contract
- execution in WebAssembly (WASM). Given that Stylus program are fraud-proven directly rather than
-interpreted via Geth's EVM implementation––the proving mechanism required modifications to the standard
-Arbitrum proving architecture.
-
-### 10.1 Proving Stylus programs
-
-Unlike EVM-based contracts, Stylus programs are dynamically linked into the replay machine when proving fraud. This is achieved through two key opcodes:
-
-- **`LinkModule`**: Loads the Stylus contract's WASM module into the replay machine.
-- **`UnlinkModule`**: Removes the module once execution completes.
-
-These opcodes ensure that Stylus contracts are treated as part as part of the replay machine, allowing for precise fraud-proof bisection at the WASM level.
-
-### 10.2 Execution-proving separation
-
-Stylus leverages Arbitrum's execution-proving separation, where the replay machine runs in WAVM, and disputes over Stylus transactions follow the standard interactive fraud-proof protocol (BoLD), which means:
-
-1. A challenge initiates if a validator disputes the execution of a Stylus transaction.
-2. The dispute narrows to a single WAVM opcode via the bisection protocol.
-3. The One-Step Proof (OSP) mechanism extends to handle Stylus-specific operations, proving the correctness of WASM execution at the opcode level.
-
-### 10.3 Internal function calls in proofs
-
-Since Stylus programs interact with the blockchain through host I/O's, fraud proofs must ensure correct execution of cross-module calls. The following additional proving opcodes facilitate Stylus program execution:
-
-- **`CrossModuleInternalCall`**: Allows internal functions within a Stylus module to be proven independently.
-- **`CrossModuleForward`**: Ensures host I/O calls are accurately relayed through `forward.wat`, maintaining consistency in fraud proofs.
-
-### 10.4 Error recovery and chain safety
-
-Stylus introduces a novel Error Guard mechanism to prevent malicious programs from halting the chain. If an error occurs within a Stylus program during proving:
-
-1. Execution reverts to the main replay machine context.
-2. The replay machine resets the program's execution state using an Error Guard stack.
-3. If recovery is not possible, the transaction is flagged as invalid, ensuring Stylus fraud proofs remain deterministic.
-
-### 10.5 One-Step Proofs for Stylus
-
-The One-Step Prover extends to validate Stylus-specific opcodes, which include:
-
-- **Memory operations** (e.g., `MemoryGrow`, `HeapAlloc`)
-- **Host I/O's** (e.g., `storage_load_bytes32`, `return_data`)
-- **Gas metering** within WASM execution
-
-By integrating these functionalities, Stylus ensures WASM contract execution can be fraud-proven like EVM transactions, while leveraging Arbitrum's existing BoLD fraud-proof architecture.
diff --git a/docs/how-arbitrum-works/bold/bold-technical-deep-dive.mdx b/docs/how-arbitrum-works/bold/bold-technical-deep-dive.mdx
index 24bc45ffb4..536fea266f 100644
--- a/docs/how-arbitrum-works/bold/bold-technical-deep-dive.mdx
+++ b/docs/how-arbitrum-works/bold/bold-technical-deep-dive.mdx
@@ -61,7 +61,7 @@ The current implementation of BoLD involves both onchain and offchain components
- **Edge:** Edges are a portion of a claim made by a validator about the history of the chain from some end state all the way back to some initial state. Edges are the fundamental unit in a challenge.
-- **Fraud proofs:** Proofs that prove or disprove that an invalid state transition has taken place. These proofs are generated by challenge participants and are submitted to a chain's parent chain. For example, Arbitrum Rollups that settle onto Ethereum will have their proofs submitted to Ethereum and verified via a smart contract. In this case, these proofs allow Ethereum to be the final arbiter of disagreements over assertions in the Rollup contracts, which cannot be falsified by any parties as there is only a single, correct result of executing a `WASM` instruction on a pre-state. WASM is the assembly language that is used to represent programs whose execution is being disputed. In fact, Arbitrum, before and after BoLD, uses a slightly different language called WAVM when executing challenges. The difference is not important to this discussion, but for details, see the page outlining the differences between [WASM and WAVM](/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx#7-wasm-to-wavm-transformation).
+- **Fraud proofs:** Proofs that prove or disprove that an invalid state transition has taken place. These proofs are generated by challenge participants and are submitted to a chain's parent chain. For example, Arbitrum Rollups that settle onto Ethereum will have their proofs submitted to Ethereum and verified via a smart contract. In this case, these proofs allow Ethereum to be the final arbiter of disagreements over assertions in the Rollup contracts, which cannot be falsified by any parties as there is only a single, correct result of executing a `WASM` instruction on a pre-state. WASM is the assembly language that is used to represent programs whose execution is being disputed. In fact, Arbitrum, before and after BoLD, uses a slightly different language called WAVM when executing challenges. The difference is not important to this discussion, but for details, see the page outlining the differences between WASM and WAVM.
- **Honest validator:** An entity that knows the correct state of the Arbitrum child chain and who may want to participate in creating assertions, confirming assertions, and/or challenging invalid assertions if they exist. More specifically, this entity must run an Arbitrum full node in `MakeNodes`, `Defensive`, `StakeLatest`, or `ResolveNodes` mode as described in the [How to run a validator](/run-arbitrum-node/more-types/02-run-validator-node.mdx). Note that there must always be an active proposer (i.e., a validator who actively submits new assertions) to advance the chain and who will need to run a validator in `MakeNodes` mode.
@@ -156,7 +156,7 @@ At its core, the disagreement between validators looks something like this:
Their disagreement is about an Arbitrum block somewhere between batch 5 and batch 10. Here’s how the actual challenge begins in this example:
-Validators have to fetch all blocks between batch 5 and batch 10 and create a Merkle commitment out of them as a Merkle tree with 2^26+1 leaves. If there are fewer than 2^26 blocks in between the assertions, the last block is repeated to pad the leaves of the tree to that value. Validators then create an “edge” data structure, which contains the following fields:
+Validators have to fetch all blocks between batch 5 and batch 10 and create a Merkle commitment out of them as a Merkle tree with `2^26+1` leaves. If there are fewer than 2^26 blocks in between the assertions, the last block is repeated to pad the leaves of the tree to that value. Validators then create an “edge” data structure, which contains the following fields:
- **start_hash:** the start_hash of the claimed assertion and is also the end_hash of the previous assertion
@@ -198,7 +198,7 @@ A validator can make a bisection move on an edge as long as that edge is “riva
The number of steps of execution at which validators could disagree within a single Arbitrum block has a max of 2^42. To play a game of bisections on this amount of hashes would be unreasonable from a space requirement, as each history commitment would require 4.35Tb worth of hashes. Instead, BoLD plays the bisection game over different levels of granularity of this space of 2^42 hashes that we call sub-challenges that can be viewed as recursive execution of the dispute resolution process.
-As a reminder, the bisection game is an iterative and interactive process. The first sub-challenge is at the block level and is where validators disagree over Arbitrum blocks between two assertions. The disagreeing validators create “edges” containing history commitments to all the blocks in between those two assertions, which is a max of 2^26 child chain blocks, and commence the bisection game. As they progressively narrow down to a single block of disagreement, the validators then begin the next phase of the challenge process by opening a sub-challenge over up to 2^19 **BigSteps**, which are each 2^23 steps of WASM execution. Once they reach a single disagreement at the BigStep level, they open a final sub-challenge over a maximum of 2^23 SmallSteps, which are each a single step of WASM execution. The bisection game is the same at each sub-challenge level, and opening a sub-challenge requires placing another “challenge bond”. The magnitudes of challenge bonds are different at each sub-challenge level.
+As a reminder, the bisection game is an iterative and interactive process. The first sub-challenge is at the block level and is where validators disagree over Arbitrum blocks between two assertions. The disagreeing validators create “edges” containing history commitments to all the blocks in between those two assertions, which is a max of `2^26` child chain blocks, and commence the bisection game. As they progressively narrow down to a single block of disagreement, the validators then begin the next phase of the challenge process by opening a sub-challenge over up to `2^19` **BigSteps**, which are each `2^23` steps of WASM execution. Once they reach a single disagreement at the BigStep level, they open a final sub-challenge over a maximum of `2^23` SmallSteps, which are each a single step of WASM execution. The bisection game is the same at each sub-challenge level, and opening a sub-challenge requires placing another “challenge bond”. The magnitudes of challenge bonds are different at each sub-challenge level.
#### One step proof
diff --git a/docs/how-arbitrum-works/bold/gentle-introduction.mdx b/docs/how-arbitrum-works/bold/gentle-introduction.mdx
index 5d63b4a7fd..93a8d20c81 100644
--- a/docs/how-arbitrum-works/bold/gentle-introduction.mdx
+++ b/docs/how-arbitrum-works/bold/gentle-introduction.mdx
@@ -70,6 +70,12 @@ To summarize with an analogy and the diagram below: Arbitrum’s former dispute
className="img-600px"
/>
+
+
+
+
+
+
:::note
The timer/clocks above are arbitrary and instead represent the duration of challenges and how challenges are sequential today, but can take place in parallel with BoLD. The duration of challenges is independent of one another.
@@ -82,9 +88,9 @@ The BoLD protocol provides the guardrails and rules for how validators challenge
Let’s dive into an overview of how BoLD actually works.
-1. **An assertion is made:** Validators begin by taking the most recent confirmed [assertion](/how-arbitrum-works/05-validation-and-proving/02-rollup-protocol.mdx), called `Block A`, and assert that some number of transactions afterward, using Nitro’s deterministic State Transition Function (STF), will result in an end state, `Block Z`. If a validator claims that the end state represented by `Block Z` is correct, they will bond their funds to `Block Z` and propose that state to its parent chain. (For more details on how bonding works, see [Bold technical deep dive](/how-arbitrum-works/bold/bold-technical-deep-dive.mdx)). If nobody disagrees after a certain amount of time, known as the challenge period, then the state represented by the assertion `Block Z` is confirmed as the correct state of an Arbitrum chain. However, if someone disagrees with the end state `Block Z`, they can submit a challenge.
+1. **An assertion is made:** Validators begin by taking the most recent confirmed [assertion](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx), called `Block A`, and assert that some number of transactions afterward, using Nitro’s deterministic State Transition Function (STF), will result in an end state, `Block Z`. If a validator claims that the end state represented by `Block Z` is correct, they will bond their funds to `Block Z` and propose that state to its parent chain. (For more details on how bonding works, see [Bold technical deep dive](/how-arbitrum-works/bold/bold-technical-deep-dive.mdx)). If nobody disagrees after a certain amount of time, known as the challenge period, then the state represented by the assertion `Block Z` is confirmed as the correct state of an Arbitrum chain. However, if someone disagrees with the end state `Block Z`, they can submit a challenge.
2. **A challenge is opened:** When another validator observes and disagrees with the end state represented by `Block Z`, they can permissionlessly open a challenge by asserting and bonding capital to a claim on a different end state, represented by an assertion `Block Y`. At this point, there are now two asserted states: `Block A → Block Z` and `Block A → Block Y`. Each of these asserted states, at this point, is referred to as an edge, while a Merkle tree of asserted states from some start to endpoint (e.g., `Block A → Block Z`) is more formally known as a _history commitment _.\_ It is important to note that Ethereum at this point has no notion of which edge(s) are correct or incorrect - edges are simply a portion of a claim made by a validator about the history of the chain from some end state all the way back to some initial state. Also note that because a bond put up by a validator is for an assertion rather than the party that put up that bond, there can be any number of honest, anonymous parties that can open challenges against incorrect claims. It is important to note that bonds posted to open challenges get held in the Rollup contract. There is a prescribed procedure outlining the expectation of the Arbitrum Foundation regarding the use of these funds; see Step 5 below for a summary.
-3. **Multi-level, interactive dissection begins:** To resolve the dispute, the disagreeing entities will need to agree on what the _actual, correct_ asserted state should be. [It would be tremendously expensive to re-execute](/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx) and compare everything from `Block A → Block Z` and `Block A → Block Y`, especially since there could be potentially millions of transactions in between `A`, `Z`, and `Y`. Instead, entities take turns bisecting their respective history commitments until they arrive at a single step of instruction, where an arbiter, such as Ethereum, can declare a winner. Note that [this system is very similar to how challenges are resolved on Arbitrum chains today](/how-arbitrum-works/05-validation-and-proving/01-validation-and-proving.mdx) - BoLD only changes some minor, but important, details in the resolution process. Let’s dive into what happens next:
+3. **Multi-level, interactive dissection begins:** To resolve the dispute, the disagreeing entities will need to agree on what the _actual, correct_ asserted state should be. [It would be tremendously expensive to re-execute](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx) and compare everything from `Block A → Block Z` and `Block A → Block Y`, especially since there could be potentially millions of transactions in between `A`, `Z`, and `Y`. Instead, entities take turns bisecting their respective history commitments until they arrive at a single step of instruction, where an arbiter, such as Ethereum, can declare a winner. Note that [this system is very similar to how challenges are resolved on Arbitrum chains today](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx) - BoLD only changes some minor, but important, details in the resolution process. Let’s dive into what happens next:
- **Block challenges**: When a challenge gets opened, edges are referred to as level-zero edges since they are at the granularity of Arbitrum blocks. The disputing parties take turns bisecting their historical commitments until they identify the specific block on which they disagree.
- **Big-step challenge:** Now that the parties have narrowed down their dispute to a single block, the back-and-forth bisection exercise continues within that block. Note that this block is agreed upon by all parties to be a state that follows the initial state but precedes the final state. This time, however, the parties will narrow down on a specific range of instructions for the State Transition Function within the block - essentially working towards identifying a set of instructions within which their disagreement lies. Currently, this range is 2^20 steps of `WASM` instructions, which is the assembly of choice for validating Arbitrum chains.
- **One-step challenge:** Within that range of 2^20 instructions, the back-and-forth bisecting continues until all parties arrive at a single step of instruction that they disagree on. At this point, parties agree on the initial state of Arbitrum before the step, but disagree on the end state one step immediately after. Remember that since Arbitrum’s state is entirely deterministic, there is only one correct end state.
@@ -99,139 +105,143 @@ That’s it! We’ve now walked through each of the steps that validators will t
#### Q: How does bonding work?
-The entities responsible for posting assertions about Arbitrum state to Ethereum are called validators. If posting assertions were free, anyone could create conflicting assertions to always delay withdrawals by 14 days instead of seven. As such, Arbitrum requires validators to put in a “security deposit”, known as a bond, to be allowed to post assertions. Validators can withdraw their bond as soon as their latest posted assertion has been confirmed, and end their responsibilities. These bonds can be any `ERC-20` token and should be set to a large enough value (e.g., 200 `WETH`) to make it economically infeasible for an adversary to attack an Arbitrum chain and to mitigate against spam (that would otherwise delay confirmations). Requiring a high bond to post assertions about Arbitrum seems centralizing, as we are replacing an allowlist of validators with instead a system that requires a lot of money to participate in. To address this, there is a [contract](https://github.com/OffchainLabs/BoLD/blob/main/contracts/src/assertionStakingPool/AssertionStakingPoolCreator.sol) that anyone can use to deploy a bonding pool as a way of crowdsourcing funds from others who wish to help defend Arbitrum but who may not individually be able to put up the large upfront bond itself. The use of bonding pools, coupled with the fact that there can be any number of honest anonymous parties ready to defend Arbitrum, means that these high bond values do not harm decentralization.
+The entities responsible for posting assertions about Arbitrum state to Ethereum are called validators. If posting assertions were free, anyone could create conflicting assertions always to delay withdrawals by 14 days instead of seven. As such, Arbitrum requires validators to put in a “security deposit”, known as a bond, to be allowed to post assertions. Validators can withdraw their bond as soon as their latest posted assertion receives confirmation, and they will then end their responsibilities. These bonds can be any `ERC-20` token. They should be set to a large enough value (e.g., 200 `WETH`) to make it economically infeasible for an adversary to attack an Arbitrum chain and to mitigate against spam (that would otherwise delay confirmations). Requiring a high bond to post assertions about Arbitrum seems centralized, as we are replacing an allowlist of validators with a system that requires a lot of money to participate in. To address this, there is a [contract](https://github.com/OffchainLabs/BoLD/blob/main/contracts/src/assertionStakingPool/AssertionStakingPoolCreator.sol) that anyone can use to deploy a bonding pool as a way of crowdsourcing funds from others who wish to help defend Arbitrum but who may not individually be able to put up the large upfront bond itself. The use of bonding pools, coupled with the fact that there can be any number of honest anonymous parties ready to defend Arbitrum, means that these high bond values do not harm decentralization.
#### Q: Why are the bond sizes so high for Arbitrum One?
-There are two types of “bonds” in BoLD: **assertion and challenge.** The below sizes are carefully calculated and set for Arbitrum One using a variety of factors, including TVL and optimizing for a balance between cost for honest parties and security of the protocol. As always, the exact bond sizes for an Arbitrum chain using BoLD is entirely up to the chain owner to decide, if they choose to adopt BoLD at all.
+There are two types of “bonds” in BoLD: **assertion and challenge**. The sizes below are carefully calculated and set for Arbitrum One, using a variety of factors, including TVL, to optimize a balance between the cost for honest parties and the security of the protocol. As always, the exact bond sizes for an Arbitrum chain using BoLD is entirely up to the chain owner to decide, if they choose to adopt BoLD at all.
**Assertion bond sizes**
-Assertion bond sizes can be thought of as a “security deposit” that an entity puts down to fulfill the role of a proposer (i.e., a validator who proposes state assertions to the parent chain). The bond sizes are high because the role of a proposer assumes a big responsibility - their role is to ensure that the chain progresses. Accordingly, the bond also acts as a deterrence to _delay attacks_, where the attacker would sacrifice the bond in order to cause roughly a week of delay in a group of withdrawals. If the bond is too small or free, there may not be enough deterrence against this type of attack. Validators who choose to be proposers can withdraw their bond as soon as their most recent posted assertion has been confirmed by the protocol. We expect there to be very few proposers for Arbitrum One as only one is sufficient for safety and full functioning of the chain.
+Assertion bond sizes are akin to a “security deposit” that an entity deposits to fulfill the role of a proposer (i.e., a validator who proposes state assertions to the parent chain). The bond sizes are high because the role of a proposer assumes a big responsibility - their role is to ensure that the chain progresses. Accordingly, the bond also acts as a deterrent to _delay attacks_, where the attacker would sacrifice the bond to cause roughly a week of delay in a group of withdrawals. If the bond is too small or free, there may not be sufficient deterrence against this type of attack. Validators who choose to be proposers can withdraw their bond as soon as the protocol has confirmed their most recent posted assertion. We expect there to be very few proposers for Arbitrum One, as only one is sufficient for safety and full functioning of the chain.
**Challenge bond sizes**
-If someone disagrees with a posted assertion from a proposer, they can pool funds together to propose their own assertion that represents the correct history of the chain. Upon doing so, a challenge between the two claims will begin. Anyone can participate in the challenge, as it is not tied up to specific addresses. To resolve a challenge, participants will incur compute and gas costs due to the [interactive fraud proof game](/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx), and certain moves within a challenge have an additional bond required to prevent resource exhaustion and spam from adversaries. These moves within a challenge require smaller, **challenge bonds**. The proposed challenge bonds for Arbitrum One are 1110 `ETH` to fully resolve a dispute, which will also get reimbursed upon the confirmation of assertions by the protocol.
+If someone disagrees with a posted assertion from a proposer, they can pool funds together to propose their assertion that represents the correct history of the chain. Upon doing so, a challenge between the two claims will begin. Anyone can participate in the challenge, as it is permissionless. To resolve a challenge, participants will incur compute and gas costs due to the [interactive fraud proof game](/how-arbitrum-works/bold/gentle-introduction.mdx). Additionally, certain moves within a challenge require an extra bond to prevent resource exhaustion and spam from adversaries. These moves within a challenge require smaller, **challenge bonds**. The proposed challenge bonds for Arbitrum One are 1,110 `ETH` to fully resolve a dispute, which will also be reimbursed upon confirmation of assertions by the protocol.
-The rationale behind the specific challenge bond size was made using something called a “resource ratio” - defined as the cost ratio between an adversary and an honest party when participating in the interactive fraud proof game. The value was chosen to ensure that the malicious party will pay 10x the marginal costs of the honest party. This resource ratio, coupled with the fact that an honest party will always get their bonds refunded while a malicious party loses everything, helps prevent and deter attacks to begin with.
+The rationale behind the specific challenge bond size is based on a concept known as a “resource ratio,” defined as the cost ratio between an adversary and an honest party when participating in the interactive fraud proof game. Selecting this value ensured that the malicious party would pay 10 times the marginal costs of the honest party. This resource ratio, coupled with the fact that an honest party will always have its bonds refunded while a malicious party loses everything, helps prevent and deter attacks from the outset.
-To summarize with a scenario, this effectively means that defending against a \$1B dollar attack would require ~\$100M of bonds. The ~\$100M would be reimbursed upon winning a challenge, where the \$1B put up by an adversary would be lost. The proposal aims to send the confiscated funds to the treasury by setting the “excess state receiver” address to the [DAO’s treasury address](https://arbiscan.io/address/0xF3FC178157fb3c87548bAA86F9d24BA38E649B58). The tradeoff here is that the higher the resource ratio we want, the more expensive it is for both honest and evil parties to make claims in disputes.
+To summarize with a scenario, this effectively means that defending against a \$1B dollar attack would require ~\$100M of bonds. The ~\$100M would get reimbursed upon winning a challenge, where the \$1B bonded by an adversary would get forfeited. The proposal aims to send the confiscated funds to the treasury by setting the “excess state receiver” address to the [DAO’s treasury address](https://arbiscan.io/address/0xF3FC178157fb3c87548bAA86F9d24BA38E649B58). The tradeoff here is that the higher the resource ratio we want, the more expensive it is for both honest and evil parties to make claims in disputes.
**Bonding pools as a way to allow people to participate in assertion posting**
-BoLD ships with trustless bonding pools that allow any group of participants to pool their funds together to challenge a dishonest proposer, and win. That is, any group of entities can pool funds into a simple contract that will post an assertion to Ethereum without needing to trust each other. Upon observation of an invalid assertion, validators have one challenge period (~6.4 days) to pool funds in the contract and respond with a counter assertion. We believe that making it easy to pool the funds to participate in the defense of Arbitrum trustlessly and improves decentralization and the safety of BoLD.
+BoLD ships with trustless bonding pools that allow any group of participants to pool their funds together to challenge a dishonest proposer, and win. That is, any group of entities can pool funds into a simple contract that will post an assertion to Ethereum without needing to trust each other. Upon observation of an invalid assertion, validators have one challenge period (~6.4 days) to pool funds in the contract and respond with a counter assertion. Making it easy to pool the funds to participate in the defense of the Arbitrum trustlessly improves decentralization and the safety of BoLD.
#### Q: Does the bond requirement only mean that whales can validate Arbitrum One?
-Validating Arbitrum One is **free and accessible**. All Arbitrum One nodes, by default, are watchtower validators meaning they can detect and report invalid assertions posted to Ethereum.
+Validating Arbitrum One is **free and accessible**. All Arbitrum One nodes, by default, are watchtower validators, meaning they can detect and report invalid assertions posted to Ethereum.
-However, becoming an assertion proposer requires a bond, as without it, anyone could delay all Arbitrum bridged assets by one week. However, BoLD allows for anyone to propose assertions and also challenge invalid assertions via pool contracts, helping keep proposers accountable for their actions.
+However, becoming an assertion proposer requires a bond, as without it, anyone could delay all Arbitrum bridged assets by one week. However, BoLD allows anyone to propose assertions and also challenge invalid assertions via pool contracts, helping keep proposers accountable for their actions.
#### Q: How does BoLD disincentivize malicious actors from attacking an Arbitrum chain?
-Bonds put up by honest parties will always be refunded while malicious actors always stand to lose 100% of their bond. Malicious actors stand to lose everything at each challenge. BoLD delay is bounded and additional challenges would not increase the delay of a particular assertion.
+Honest, bonded parties will always be refunded, while malicious actors always stand to lose 100% of their bond. Malicious actors stand to lose everything at each challenge. The BoLD delay is bounded, and additional challenges would not increase the delay of a particular assertion.
#### Q: In the event of a challenge, what happens to the confiscated funds from malicious actors for Arbitrum One?
-Recall that BoLD enables any validator to put up a bond to propose assertions about the child chain state. These assertions about the child chain state are deterministic and so an honest party who puts up a bond on the correct assertion will always win in disputes. In these scenarios, the honest party will eventually have their bonds reimbursed while the malicious actor will lose all of their funds.
+Recall that BoLD enables any validator to put up a bond to propose assertions about the child chain state. These assertions about the child chain state are deterministic, and so an honest party who puts up a bond on the correct assertion will always win in disputes. In these scenarios, the honest party will eventually have their bonds reimbursed while the malicious actor will lose all of their funds.
-In BoLD, all costs spent by malicious actors are confiscated and sent to the Arbitrum DAO treasury. A small reward, called the Defender's Bounty, of 1% will be awarded to entities who put down challenge bonds in defense of Arbitrum One. For the remainder of the funds, the Arbitrum DAO will have full discretion over what to do with the funds confiscated from a malicious actor. This includes, but is not limited to:
+In BoLD, all costs spent by malicious actors are confiscated and sent to the Arbitrum DAO treasury. A small reward, called the Defender's Bounty, of 1% will go to entities who put down challenge bonds in defense of Arbitrum One. For the remaining funds, the Arbitrum DAO will have full discretion over how to utilize the funds confiscated from a malicious actor. Applications include, but is not limited to:
- Using the confiscated funds to refund the parent chain gas costs to honest parties,
-- Rewarding or reimbursing the honest parties with some, or all, of the confiscated funds in excess of the 1% Defender's Bounty,
+- Rewarding or reimbursing the honest parties with some, or all, of the confiscated funds over the 1% Defender's Bounty,
- Burning some, or all, of the confiscated funds, or
- Keep some, or all, of the confiscated funds within the Arbitrum DAO Treasury
-As always, an Arbitrum chain can choose how they wish to structure and manage confiscated funds from dishonest parties.
+As always, an Arbitrum chain can choose how it wishes to structure and manage confiscated funds from dishonest parties.
#### Q: Why are honest parties not automatically rewarded with confiscated funds from a malicious actor?
It’s tempting to think that rewarding the honest proposer in a dispute can only make the protocol stronger, but this turns out not to be true, because an adversary can sometimes profit by placing the honest bonds themselves.
-This creates perverse incentives that threaten the security of BoLD. Here’s an example, from Ed Felten:
+This situation creates perverse incentives that threaten the security of BoLD. Here’s an example, from Ed Felten:
That said, there’s no harm in paying the honest proposer a fair interest rate on their bond, so they don’t suffer for having helped the protocol by locking up their capital in a bond.
-Therefore, the BoLD AIP proposes that the honest parties be rewarded 1% of confiscated bonds from a dishonest party, in the event of a challenge. This reward applies only to entities who deposit challenge bonds and participate in defending Arbitrum against a challenge. The exact amount rewarded to honest parties will be proportional to the amount defender’s deposited into the protocol during a challenge, making bonding pool participants eligible. The process by which this reward is calculated will be done offchain and payouts will require a DAO vote because the confiscated funds are always sent to a DAO-controlled address.
+Therefore, the BoLD AIP proposes that honest parties be rewarded with 1% of the confiscated bonds from a dishonest party, in the event of a challenge. This reward applies only to entities that deposit challenge bonds and participate in defending Arbitrum against a challenge. The exact amount rewarded to honest parties will be proportional to the amount the defender deposits into the protocol during a challenge, making bonding pool participants eligible.
-#### Q: Why is `ARB` not the bonding token used in BoLD? on Arbitrum One?
+#### Q: Why is `ARB` not the bonding token used for BoLD on Arbitrum One?
Although BoLD supports using an `ERC-20` token, Ethereum, specifically `WETH`, was chosen over `ARB` for a few reasons:
-1. **Arbitrum One & Arbitrum Nova both inherit their security from Ethereum already,** Arbitrum One and Nova rely on Ethereum for both data availability and as the referee for determining winners during fraud-proof disputes. It follows then that Ethereum continues to be used in BoLD, which is meant to permissionlessly secure Arbitrum even further. Ethereum’s value is also relatively independent of Arbitrum, especially when compared to `ARB`.
-2. Adversaries might be able to exploit the potential instability of `ARB` when trying to win challenges. Suppose an adversary deposits their bond in `ARB`, and can create an impression that they have a nontrivial chance of winning the challenge. This might drive down the value of `ARB`, which would decrease the adversary's cost to create more bonds (i.e., more spam) during the challenge, which in turn could increase the adversary's chances of winning (which would drive `ARB` lower, making the attack cheaper still for the adversary, etc.)
+1. **Arbitrum One and Arbitrum Nova both inherit their security from Ethereum already.** Arbitrum One and Nova rely on Ethereum for both data availability and as the referee for determining winners during fraud-proof disputes. Ethereum’s value is also relatively independent of Arbitrum, especially when compared to `ARB`.
+2. Adversaries might be able to exploit the potential instability of `ARB` when trying to win challenges. Suppose an adversary deposits their bond in `ARB`, and can create an impression that they have a nontrivial chance of winning the challenge. This impression might drive down the value of `ARB`, which would decrease the adversary's cost to create more bonds (i.e., more spam) during the challenge, which in turn could increase the adversary's chances of winning (which would drive `ARB` lower, making the attack cheaper still for the adversary, etc.)
3. **Access to liquidity**: Ethereum has greater liquidity than `ARB`. In the event of an attack on Arbitrum, access and ease of pooling funds may become crucial.
-4. **Fraud proofs are submitted to, and arbitrated on the parent chain (Ethereum).** The bonding of capital to make assertions is done so on the parent chain (Ethereum), since Ethereum is the arbitrator of disputes. If BoLD were to use `ARB` instead of Ethereum, a large amount of `ARB` must be pre-positioned on the parent chain which is more difficult to do when compared to pre-positioning Ethereum on the parent chain (Ethereum).
+4. **Fraud proofs are submitted to, and arbitrated on, the parent chain (Ethereum).** The bonding of capital to make assertions is done so on the parent chain (Ethereum), since Ethereum is the arbitrator of disputes. If BoLD were to use `ARB` instead of Ethereum, a large amount of `ARB` must be pre-positioned on the parent chain, which is more difficult to do when compared to pre-positioning Ethereum on the parent chain (Ethereum).
-An Arbitrum chain owner may choose to use any token they wish for bonding, if they adopt and use BoLD permissionless validation.
+An Arbitrum chain owner may choose to use any token they wish for bonding if they adopt and use BoLD permissionless validation.
-#### Q: Can the required token for the validator be set to `ARB` and can network `ETH` revenues be distributed for validator incentives for Arbitrum One?
+#### Q: Can the required token for the validator be set to `ARB`, and can network `ETH` revenues get distributed for validator incentives for Arbitrum One?
-Yes. The asset that a validator uses to become a proposer in BoLD can be set to any `ERC-20` token, including `ARB`. For Arbitrum One, `ETH` is used for bonds for various reasons mentioned above. The Arbitrum DAO can change this asset type at any time via a governance proposal. Should such an economic incentive model exist, the source and denomination of funds used to incentivize validators will be at the discretion of the Arbitrum DAO. Again, though, we don't see `ARB`-based bonding as a good idea at present; see the last question.
+Yes. The asset that a validator uses to become a proposer in BoLD is configurable to any `ERC-20` token, including `ARB`. For Arbitrum One, `ETH` is used for bonds for various reasons mentioned above. The Arbitrum DAO can change this asset type at any time via a governance proposal. Should such an economic incentive model exist, the source and denomination of funds used to incentivize validators will be at the discretion of the Arbitrum DAO. Again, though, we don't see `ARB`-based bonding as a good idea at present; see the last question.
#### Q: How are honest parties reimbursed for bonding their capital to help secure Arbitrum One?
-The Arbitrum DAO reimburses “active” proposers with a fair interest rate, as a way of removing the disincentive to participate, by reimbursing honest parties who bond their own capital and propose assertions for Arbitrum One. The interest rate should be denominated in `ETH` and should be equal to the annualized yield that Ethereum mainnet validators receive, which at the time of writing, is an APR between 3% to 4% (based on [CoinDesk Indices Composite Ether Staking Rate (CESR)](https://www.coindesk.com/indices/ether/cesr) benchmark and [_Rated.Network_](https://explorer.rated.network/network?network=mainnet&timeWindow=all&rewardsMetric=average&geoDistType=all&hostDistType=all&soloProDist=stake)). This interest is considered a reimbursement because this payment reimburses the honest party for the opportunity cost of locking up their capital and should not be perceived as a “reward” - for the same [reasons why the protocol does not reward honest parties with the funds confiscated from a malicious actor](#q-why-are-honest-parties-not-automatically-rewarded-with-confiscated-funds-from-a-malicious-actor)). These reimbursement payments can be paid out upon an active proposer’s honest assertion being confirmed on Ethereum and will be calculated and handled offchain by the Arbitrum Foundation.
+The Arbitrum DAO reimburses “active” proposers with a fair interest rate, as a way of removing the disincentive to participate, by reimbursing honest parties who bond their capital and propose assertions for Arbitrum One. The interest rate should be denominated in `ETH` and should be equal to the annualized yield that Ethereum mainnet validators receive, which at the time of writing, is an APR between 3% to 4% (based on [CoinDesk Indices Composite Ether Staking Rate (CESR)](https://www.coindesk.com/indices/ether/cesr) benchmark and [_Rated.Network_](https://explorer.rated.network/network?network=mainnet&timeWindow=all&rewardsMetric=average&geoDistType=all&hostDistType=all&soloProDist=stake)). This interest is considered a reimbursement because this payment reimburses the honest party for the opportunity cost of locking up their capital and should not be perceived as a “reward” - for the same [reasons why the protocol does not reward honest parties with the funds confiscated from a malicious actor](#q-why-are-honest-parties-not-automatically-rewarded-with-confiscated-funds-from-a-malicious-actor)). These reimbursement payments can be paid out upon an active proposer’s honest assertion being confirmed on Ethereum and will be calculated and handled offchain by the Arbitrum Foundation.
-BoLD makes it permissionless for any validator to become a proposer and also introduces a way to pay a service fee to honest parties for locking up capital to do so. Validators are not considered active proposers until they successfully propose an assertion _with_ a bond. In order to become an active proposer for Arbitrum One, post-BoLD, a validator has to propose a child chain state assertion to Ethereum. If they do not have an active bond on the parent chain, they then need to attach a bond to their assertion in order to successfully post the assertion. Subsequent assertions posted by the same address will simply move the already-supplied bond to their latest proposed assertion. Meanwhile, if an entity, say Bob, has posted a successor assertion to one previously made by another entity, Alice, then Bob would be considered by the protocol to be the current active proposer. Alice would no longer be considered by the protocol as the active proposer and once Alice’s assertion is confirmed, then Alice gets her assertion bond refunded. There can only be one “active” proposer at any point in time.
+BoLD makes it permissionless for any validator to become a proposer and also introduces a way to pay a service fee to honest parties for locking up capital to do so. Validators are not considered as active proposers until they successfully propose an assertion _with_ a bond. To become an active proposer for Arbitrum One post-BoLD, a validator must propose a child chain state assertion to Ethereum. If they do not have an active bond on the parent chain, they then need to attach a bond to their assertion to post the assertion successfully. Subsequent assertions posted by the same address will move the already-supplied bond to their latest proposed assertion.
+Meanwhile, if an entity, say Bob, has posted a successor assertion to one previously made by another entity, Alice, then Bob would be considered by the protocol to be the current active proposer. Alice would no longer be considered as the active proposer by the protocol, and once Alice’s assertion is confirmed, she will receive a refund of her assertion bond. There can only be one “active” proposer at any point in time.
-The topic of economic and incentive models for BoLD on Arbitrum One is valuable and we believe it deserves the full focus and attention of the community via a separate proposal/discussion - decoupled from this proposal to bring BoLD to mainnet. Details around proposed economic or incentive models for BoLD will need continued research and development work, but the deployment of BoLD as-is represents a substantial improvement to the security of Arbitrum even without economic-related concerns being resolved. The DAO may choose, via governance, to fund other parties or change this reimbursement model at any time.
+The topic of economic and incentive models for BoLD on Arbitrum One is valuable. It deserves the full focus and attention of the community via a separate proposal or discussion, decoupled from this proposal to bring BoLD to mainnet. Details regarding proposed economic or incentive models for BoLD will require continued research and development work. However, deploying BoLD as-is represents a substantial improvement to Arbitrum's security, even without addressing economic-related concerns. The DAO may, through governance, choose to fund other parties or modify this reimbursement model at any time.
-For Arbitrum chains, any economic model can be implemented alongside BoLD, if chain owners decide to adopt BoLD.
+For Arbitrum chains, any economic model can be configured alongside BoLD if chain owners decide to adopt BoLD.
-#### Q: For Arbitrum One proposers, is the service fee applied to the amount bonded? If that’s the case, the `ETH` would be locked and thus unable to be used to generate yield elsewhere. So, which assets are used to generate this yield for the service fee? Would it involve some `ETH` from the Arbitrum bridge?
+#### Q: For Arbitrum One proposers, is the service fee applied to the amount bonded? If that’s the case, the `ETH` would be locked and thus unable to be used to generate yield elsewhere. So, which assets get used to create this yield for the service fee? Would it involve some `ETH` from the Arbitrum bridge?
-The proposed service fee should correlate to the annualized income that Ethereum mainnet validators receive, over the same time period. At the time of writing, the estimated annual income for Ethereum mainnet validators is approximately 3% to 4% of their bond (based on [CoinDesk Indices Composite Ether Staking Rate (CESR)](https://www.coindesk.com/indices/ether/cesr) benchmark and [_Rated.Network_](https://explorer.rated.network/network?network=mainnet&timeWindow=all&rewardsMetric=average&geoDistType=all&hostDistType=all&soloProDist=stake)).
+The proposed service fee should correlate to the annualized income that Ethereum mainnet validators receive over the same period. At the time of writing, the estimated annual income for Ethereum mainnet validators is approximately 3% to 4% of their bond (based on [CoinDesk Indices Composite Ether Staking Rate (CESR)](https://www.coindesk.com/indices/ether/cesr) benchmark and [_Rated.Network_](https://explorer.rated.network/network?network=mainnet&timeWindow=all&rewardsMetric=average&geoDistType=all&hostDistType=all&soloProDist=stake)).
-The fee is applied to the total amount bonded over the duration of time that a proposer is active. A validator will need to deposit `ETH` into the contracts on the parent chain to become a proposer and so those deposited funds will indeed be unable to be used for yield in other scenarios. The decision on the source of funds for the yield is entirely up to the ArbitrumDAO to decide.
+The fee is applied to the total amount bonded over the duration of time that a proposer is active. A validator will need to deposit `ETH` into the contracts on the parent chain to become a proposer. So those deposited funds will indeed be unable to be used for yield in other scenarios. The decision on the source of funds for the yield is entirely up to the ArbitrumDAO to decide.
-#### Q: For Arbitrum One, will the offchain compute costs be reimbursed? (i.e., the costs for a validator computing the hashes for a challenge)
+#### Q: For Arbitrum One, will the offchain computation costs get reimbursed? (i.e., the costs for a validator computing the hashes for a challenge)
-Reimbursement will not be made for offchain compute costs as we view these to be costs borne by all honest operators, alongside the maintenance and infra costs that regularly arise from running a node.
+Reimbursements will not be made for any offchain computation costs, as we view these to be costs borne by all honest operators, alongside the maintenance and infrastructure costs that regularly arise from running a node.
-Our testing has demonstrated that the cost of running a sub-challenge in BoLD, the most computationally-heavy step, on an AWS r5.4xlarge EC2 instance, costs around \$2.50 USD (~\$1 hour for one challenge with 2.5 hour duration) using [on-demand prices for U.S. East (N. Virginia)](https://instances.vantage.sh/aws/ec2/r5.4xlarge). Therefore, the additional costs from offchain compute is assumed to be negligible relative to the regular infra costs of operating a node.
+Our testing has demonstrated that the cost of running a sub-challenge in BoLD, the most computationally-heavy step, on an AWS r5.4xlarge EC2 instance, costs around USD \$2.50 (~\$1 hour for one challenge with 2.5 hour duration) using [on-demand prices for U.S. East (N. Virginia)](https://instances.vantage.sh/aws/ec2/r5.4xlarge). Therefore, the additional costs from offchain compute are assumed to be negligible relative to the regular infra costs of operating a node.
#### Q: How will BoLD impact Arbitrum Nova?
-Although this AIP proposes that both Arbitrum One and Nova upgrade to use BoLD, we recommend for the removal of the [allowlist of validators for Arbitrum One while keeping Nova permissioned with a DAO-controlled allowlist of entities](https://docs.arbitrum.foundation/state-of-progressive-decentralization#allowlisted-validators) - unchanged from today.
+Although this AIP proposes that both Arbitrum One and Nova upgrade to use BoLD, we recommend the removal of the [allowlist of validators for Arbitrum One while keeping Nova permissioned with a DAO-controlled allowlist of entities](https://docs.arbitrum.foundation/state-of-progressive-decentralization#allowlisted-validators) - unchanged from today.
-This decision was made for two reasons. First, Arbitrum Nova’s TVL is much lower than Arbitrum One’s TVL, (~\$17B vs. ~\$46M at the time of writing, from [L2Beat](https://l2beat.com/scaling/summary)). This means that the high bond sizes necessary for preventing spam and delay attacks would make up a significant proportion of Nova’s TVL - which we believe introduces a centralization risk as very few parties would be incentivized to secure Nova. A solution here would be to lower the bond sizes, which brings us to the second reason: lower bond sizes reduce the costs of delay griefing attacks (where malicious actors delay the chain’s progress) and therefore hurt the security of the chain. We believe enabling permissionless validation for Nova is not worth the capital requirement tradeoffs, given the unique security model of AnyTrust chains.
+This decision comes from two reasons:
+First, Arbitrum Nova’s TVL is much lower than Arbitrum One’s TVL (~\$17B vs. ~\$46M at the time of writing, from [L2Beat](https://l2beat.com/scaling/summary)). This lower TVL means that the high bond sizes necessary for preventing spam and delay attacks would comprise a significant proportion of Nova’s TVL, which we believe introduces a centralization risk, as very few parties would have an incentive to secure Nova. A solution here would be to lower the bond sizes,
+Second, the lower bond sizes reduce the costs of delay griefing attacks (where malicious actors delay the chain’s progress) and therefore hurt the security of the chain. We believe enabling permissionless validation for Nova is not worth the capital requirement tradeoffs, given the unique security model of AnyTrust chains.
-Notably, since Arbitrum Nova's security already depends on at least one DAC member providing honest data availability, trusting the same committee to have at least one member provide honest validation does not add a major trust assumption. This requires all DAC members also to run validators. If the DAC is also validating the chain, a feature the Offchain Labs team has been working on, Fast Withdrawals, would allow users to withdraw assets from Nova in ~15 minutes, or the time it takes to reach parent chain finality. This is made possible by the DAC attesting to and instantly confirming an assertion. Fast Withdrawals will be the subject of future forum post and snapshot vote.
+Notably, since Arbitrum Nova's security already depends on at least one DAC member providing honest data availability, trusting the same committee to have at least one member provide honest validation does not add a major trust assumption. This trust assumption requires all DAC members also to run validators. If the DAC is also validating the chain, a feature the Offchain Labs team has been working on, Fast Withdrawals, would allow users to withdraw assets from Nova in ~15 minutes, or the time it takes to reach parent chain finality. This finality is made possible by the DAC attesting to and instantly confirming an assertion. Fast Withdrawals will be the subject of a future forum post and snapshot vote.
-#### Q: When it comes to viewing the upfront assertion bond (to be a proposer) as the security budget for Arbitrum One, is it possible for an attacker to go above the security budget and, if yes, what happens then?
+#### Q: When it comes to viewing the upfront assertion bond (to be a proposer) as the security budget for Arbitrum One, is it possible for an attacker to go above the security budget, and if so, what happens then?
-The upfront capital to post assertions (onchain action) is 3600 `ETH`, with subsequent sub-challenge assertions requiring 555/79 `ETH` (per level) - this applies to honest proposers as well as malicious entities. A malicious entity can post multiple invalid top level assertions and/or open multiple challenges and the honest entity can
+The upfront capital to post assertions (onchain action) is 3,600 `ETH`, with subsequent sub-challenge assertions requiring 555/79 `ETH` (per level) - this applies to both honest proposers and malicious entities. A malicious entity can post multiple invalid top-level assertions and/or open multiple challenges, and the honest entity can
-It is critical to note that Arbitrum state transitions are entirely deterministic. An honest party bonded to the correct state assertion, the honest party will get all their costs refunded while a malicious entity stands to lose everything. Additionally, BoLD’s design ensures that any party bonded to the correct
+It is critical to note that Arbitrum state transitions are entirely deterministic. An honest party bonded to the correct state assertion will receive all their costs refunded, while a malicious entity stands to lose everything. Additionally, BoLD’s design ensures that any party bonded to the correct
If a malicious entity wanted to attack Arbitrum, they would need to deposit 3600 `ETH` to propose an invalid state assertion.
:::info Node Running Info
- Anyone can run an Arbitrum node (today and post-BoLD)
-- The default mode is `watchtower`, which chills out and watches the chain in action. It will alert you if it sees something wrong on chain but no action is taken. It requires **no** funds and **doesn't** take any onchain action.
+- The default mode is `watchtower`, which chills out and watches the chain in action. It will alert you if it detects something wrong on the chain, but it takes no action. It requires **no** funds and **doesn't** take any onchain action.
- Other "modes" that nodes can run are: `stakeLatest`, `resolveNodes`, `makeNodes`, and `defensive`. All of these modes **require** funds and **will** take onchain action.
- Nodes running in this mode are considered validators because they validate what they see and take onchain action.
- Running a `watchtower` node is **not** a validator.
-- Proposers are a special role, they strictly run in `makeNodes` mode. This means a proposer is someone running an Arbitrum node in `makeNodes` mode, also making them a validator.
+- Proposers are in a special role; they strictly run in `makeNodes` mode. This role means a proposer is someone running an Arbitrum node in `makeNodes` mode, also making them a validator.
- For more information about see [Running a Node](/run-arbitrum-node/01-overview.mdx) and [Validation strategies](/run-arbitrum-node/more-types/02-run-validator-node.mdx#validation-strategies).
- :::
+
+:::
#### Q: How do BoLD-based L3s challenge periods operate, considering the worst-case scenario?
-To recap, both Arbitrum’s current dispute protocol and BoLD require assertions to be posted to the parent chain and employ interactive proving, which involves a back-and-forth between two entities until a single step of disagreement is reached. That single step (of disagreement) is then submitted to contracts on the parent chain. Those contracts are used to declare a winner. For L2s, like Arbitrum One, BoLD must be deployed on a credibly-neutral, censorship-resistant backend to ensure disputes are fairly resolved. Ethereum, therefore, is the perfect candidate for deployment of the BoLD protocol for L2s.
+To recap, both Arbitrum’s current dispute protocol and BoLD require assertions to be posted to the parent chain and employ interactive proving, which involves a back-and-forth between two entities until a single step of disagreement is reached. That single disputed step then gets submitted to contracts on the parent chain, which will eventually declare a winner. For L2s, such as Arbitrum One, BoLD must be deployed on a credibly neutral, censorship-resistant backend to ensure a fair resolution of disputes. Ethereum, therefore, is the ideal candidate for deploying the BoLD protocol on L2s.
-But you might now be wondering: what about L3 Arbitrum chains that don’t settle to Ethereum? Unlike L2s that settle to Ethereum, assertions on an L3’s state need to be posted to an L2 either via (A) the L3 Sequencer or (B) the Delayed Inbox queue managed by the L2 sequencer on L2. In the event that the parent chain (in this case, L2) is being repeatedly censored or if the L2 sequencer is offline, every block level assertion and/or sub-challenge assertion would need to wait 24 hours before they can bypass the sequencer (using the the`SequencerInbox`’s `forceInclusion` method described [here](/how-arbitrum-works/03-sequencer.mdx)). If this were to happen, challenge resolution would be delayed by a time _t_ where _t_ = (24 hours) \* number of moves for a challenge. To illustrate with sample numbers, if a challenge takes 50 sequential moves to resolve, then the delay would be 50 days!
+But you might now be wondering: what about L3 Arbitrum chains that don’t settle to Ethereum? Unlike L2s that settle to Ethereum, assertions on an L3’s state need to be posted to an L2 either via (A) the L3 Sequencer or (B) the Delayed Inbox queue managed by the L2 sequencer on L2. In the event that the parent chain (in this case, L2) is getting repeatedly censored or if the L2 sequencer is offline, every block-level assertion and/or sub-challenge assertion would need to wait 24 hours before they can bypass the sequencer (using the the`SequencerInbox`’s `forceInclusion` method described [here](/how-arbitrum-works/deep-dives/sequencer.mdx)). If this were to happen, challenge resolution would get delayed by a time _t_ where _t_ = (24 hours) \* number of moves for a challenge. To illustrate with sample numbers, if a challenge takes 50 sequential moves to resolve, then the delay would be 50 days!
-To mitigate the risk of this issue manifesting for Arbitrum chains, Offchain Labs has included a feature called _Delay Buffer_ as part of BoLD’s 1.0.0 release. The _Delay Buffer_ feature aims to limit the negative effects of: prolonged parent chain censorship, prolonged sequencer censorship, and/or unexpected sequencer outages. This is accomplished by implementing some time threshold that is decremented when unexpected delays occur. Once that time threshold is met, the force inclusion window is lowered - effectively enabling entities to make moves without the 24 hour delay-per-move.
+To mitigate the risk of this issue manifesting for Arbitrum chains, Offchain Labs has included a feature called _Delay Buffer_ as part of BoLD’s 1.0.0 release. The _Delay Buffer_ feature aims to limit the negative effects of: prolonged parent chain censorship, prolonged sequencer censorship, and/or unexpected sequencer outages. This buffer is configurable by setting a time threshold that decrements when unexpected delays occur. Once that time threshold passes, the force inclusion window is lowered, effectively enabling entities to make moves without the 24-hour delay per move.
-Under reasonable parameterization, the sequencer could be offline / censoring for 24 hours twice, before the force inclusion window is effectively dropped from 24 hours to a minimum inclusion time. The force inclusion window gradually (over weeks) replenishes to it's original value over time as long as the sequencer is on "good behavior" - regularly sequencing messages without unexpected delays. We believe that the Delay Buffer feature provides stronger guarantees of censorship resistance for Arbitrum chains.
+Under reasonable parameterization, the sequencer could be offline/censoring for 24 hours twice, before the force inclusion window drops from 24 hours to a minimum inclusion time. The force inclusion window gradually (over weeks) replenishes to its original value over time as long as the sequencer is on "good behavior" - regularly sequencing messages without unexpected delays. We believe that the Delay Buffer feature provides stronger guarantees of censorship resistance for Arbitrum chains.
The methodology for calculating the parameters, specifically for L3 Arbitrum chains, will be made available at a later date for teams who wish to use BoLD.
@@ -243,20 +253,20 @@ The autopooling feature is not available on State Transition Function (STF) determines how blockchain systems change state when processing transactions. The STF takes the current blockchain state (account balances, smart contract data, and ledger information) plus an input (transaction or block) and deterministically computes the new state. This deterministic property ensures all network nodes reach the same result, maintaining consensus.
+
+With Arbitrum, the STF plays an even more pivotal role. Arbitrum executes transactions offchain in batches, periodically submitting summaries to the parent chain. This leverages offchain computation for higher throughput and lower gas costs while maintaining Ethereum's security. To safeguard against incorrect or malicious offchain execution, Arbitrum employs a challenge mechanism known as fraud proofs. If a dispute arises, the STF can be recomputed step-by-step onchain, enabling the network to verify the validity of the offchain computations and ensure that the errors or fraudulent behavior are detected and rectified.
+
+The Arbitrum Nitro Stack STF mirrors Ethereum's STF with key modifications for Arbitrum chain requirements. The function processes ordered transactions and outputs the updated state from the transaction batch.
+
+Stylus expands Arbitrum's execution model beyond the Ethereum Virtual
+Machine (EVM) by adding WebAssembly (WASM)–based execution, allowing
+high-performance contracts in Rust, C, and C++ to run alongside traditional EVM contracts. The integration
+of Stylus introduces several modifications to the STF, including:
+
+### Stylus-specific transaction processing
+
+A modified version of Geth that recognizes and processes Stylus transactions, ensuring proper inclusion in state transitions.
+
+### Execution in a WASM runtime
+
+Stylus transactions execute in ArbOS's WASM runtime instead of the EVM, enabling faster execution and more efficient computation.
+
+### Stylus gas accounting and pricing
+
+Unlike standard EVM transactions, Stylus transactions introduce new gas pricing models that account for factors such as opcode pricing, host I/O operations, and Ink usage costs.
+
+### Interoperability with the EVM
+
+Stylus contracts can interact seamlessly with Solidity contracts, enabling hybrid applications that leverage EVM and WASM execution environments.
+
+These Stylus-related changes aim to maintain compatibility with Ethereum's execution model while introducing a more efficient, flexible, and scalable alternative for smart contract development.
+
+The following sections cover STF inputs, node processing, and implementation rules, highlighting differences between Ethereum, Arbitrum, and Stylus execution environments. Stylus-specific execution tasks handled within ArbOS will be covered separately, focusing on host I/O operations, caching, and WASM memory management.
diff --git a/docs/how-arbitrum-works/08-anytrust-protocol.mdx b/docs/how-arbitrum-works/deep-dives/anytrust-protocol.mdx
similarity index 100%
rename from docs/how-arbitrum-works/08-anytrust-protocol.mdx
rename to docs/how-arbitrum-works/deep-dives/anytrust-protocol.mdx
diff --git a/docs/how-arbitrum-works/04-state-transition-function/05-arbos.mdx b/docs/how-arbitrum-works/deep-dives/arbos.mdx
similarity index 72%
rename from docs/how-arbitrum-works/04-state-transition-function/05-arbos.mdx
rename to docs/how-arbitrum-works/deep-dives/arbos.mdx
index 271f50513d..06cdcca986 100644
--- a/docs/how-arbitrum-works/04-state-transition-function/05-arbos.mdx
+++ b/docs/how-arbitrum-works/deep-dives/arbos.mdx
@@ -7,62 +7,47 @@ user_story: As a current or prospective Arbitrum user, I need learn more about N
content_type: get-started
---
-ArbOS is the child chain hypervisor
-that facilitates the execution environment of the child chain Arbitrum. ArbOS is a trusted "system glue"
-component that runs at the child chain as part of the
- State Transition Function
- (STF). It accounts for and manages network resources, produces blocks from incoming messages and
-cross-chain messaging, and operates its instrumented instance of
- Geth
- for smart contract execution.
+ArbOS is the child chain EVM hypervisor that provides the execution environment for the Arbitrum chain. Acting as a trusted "system glue" component within the STF, ArbOS is responsible for:
-In Arbitrum, much of the work that would otherwise have to be done expensively on the parent chain gets completed by ArbOS, who will trustlessly perform these functions at the speed and low cost of the child chain.
+### Managing network resources
-Supporting these functions in the child chain trusted software, rather than building them into the parent chain-enforced rules of the architecture as Ethereum does, offers significant advantages in cost because these operations can benefit from the lower cost of computation and storage at the child chain, instead of having to manage those resources as part of a parent chain contract. Having a trusted operating system at the child chain also has significant advantages in flexibility because the child chain code is easier to evolve or to customize for a particular chain than a parent chain enforced architecture would be.
+It allocates and tracks resources necessary for executing transcations on the child chain.
-## Precompiles
+### Block production
-ArbOS provides child chain-specific precompiles with methods smart contracts can call the same way they can Solidity functions. Visit the [precompiles conceptual page](/build-decentralized-apps/precompiles/01-overview.mdx) for more information about how these work and the [precompiles reference page](/build-decentralized-apps/precompiles/02-reference.mdx) for a full reference of the precompiles available in Arbitrum chains.
+ArbOS processes incoming sequencer data batches to produce child chain blocks, ensuring the state is updated correctly.
-A precompile consists of a Solidity interface in `contracts/src/precompiles/` and a corresponding Golang implementation in `precompiles/`. Using Geth's ABI generator, `solgen/gen.go` generates `solgen/go/precompilesgen/precompilesgen.go`, which collects the ABI data of the precompiles. The [runtime installer](https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L379) uses this generated file to check the type safety of each precompile's implementer.
-
-[The installer](https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L379) uses runtime reflection to ensure each implementer has all the right methods and signatures. This reflection includes restricting access to stateful objects like the EVM and `statedb` based on the declared purity. Additionally, the installer verifies and populates event function pointers to provide each precompile the ability to emit logs and know their gas costs. Additional configuration, like restricting a precompile's methods to only be callable by chain owners is possible by adding precompile wrappers like `ownerOnly` and `debugOnly` to their [installation entry](https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L403).
-
-Completion of calling, dispatching, and recording of precompile methods occurs via runtime reflection, which avoids any human error manually parsing and writing bytes could introduce, and uses Geth's stable APIs for [packing and unpacking](https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L438) values.
-
-Each time a transaction calls a method of a child chain-specific precompile, a [`call context`](https://github.com/OffchainLabs/nitro/blob/f11ba39cf91ee1fe1b5f6b67e8386e5efd147667/precompiles/context.go#L26) gets created to track and record the gas burnt. For convenience, it also provides access to the public fields of the underlying [`TxProcessor`](https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L38). Because sub-transactions could revert without updates to this struct, the `TxProcessor` only makes public what is safe, such as the amount of parent chain calldata paid by the top-level transaction.
-
-## Precompile descriptions
+### Cross-chain messaging
-- `ArbAggregator`: Provides methods for configuring transaction aggregation. The Arbitrum OneSequencer is the default aggregator unless changed by users. The precompile manages fee collection and batch posters for chain aggregation.
+It facilitates communication between the parent and child chains, supporting functionalities like Ether and token deposits and withdrawals.
-- `ArbGasInfo`: Retrieves various gas-related statistics, including gas prices in both `wei` and `Ink`, parent chain gas price estimates, transaction fees, and congestion metrics. It is crucial in estimating transaction costs and adjusting gas pricing dynamically.
+### Enhanced EVM execution
-- `ArbRetryableTx`: Handles retryable transactions, enabling parent-to-child messaging with delayed execution. The precompile manages retryables, checks expiration times, extends their lifetime, and cancels pending retryables.
+ArbOS operates its instrumented instance of Geth to execute smart contracts, incorporating additional logic specific to the child chain environment.
-- `ArbSys`: Provides system-level utilities for interacting with the Arbitrum chain. It exposes methods to retrieve chain-specific information such as block numbers, chain IDs, and gas availability. It also supports child-to-parent messaging and contract aliasing.
+### Stylus-specific tasks in ArbOS
-- `ArbWasm`: Facilitates the deployment and management of Stylus contracts on Arbitrum Nitro. It provides lifecycle management for WASM-based programs, including activation, expiration handling, memory footprint calculation, and version tracking.
+ArbOS manages host I/O calls, memory operations, and execution context for Stylus transactions, ensuring efficient and deterministic processing with the WASM runtime.
-- `ArbWasmCache`: Manages Stylus caching mechanisms. It allows chain owners or designated managers to cache WASM programs for efficient execution, reduce computation costs, and improve call performance.
+By offloading tasks that would execute at a high cost on the parent chain, ArbOS enables these operations to be performed quickly and cost-effectively on the child chain. This design reduces computational and storage costs and offers significant flexibility, allowing the child chain code to evolve or be customized more easily than a parent chain-enforced architecture.
-- `ArbAddressTable`: Implements a compression scheme for frequently used addresses, allowing smart contracts to reference addresses using shorter representations, thus reducing calldata costs.
+While Ethereum's STF forms the basis for secure and deterministic state updates, Arbitrum's Nitro stack builds on this foundation with key modifications–ranging from dual gas accounting to cross-chain messaging–to optimize performance and flexibility. These innovations are realized through minimal yet strategic modifications to Geth, integrated seamlessly with ArbOS, forming the "geth sandwich."
-- `ArbBLS` (disabled): Previously used for registering BLS public keys but is deprecated in Nitro.
+With the introduction of Stylus, Arbitrum extends its execution model beyond the EVM, enabling high-performance WASM-based smart contracts. This integration introduces additional modifications to Geth, ensuring compatibility with Stylus transactions while preserving Ethereum-like execution guarantees. These changes include handling Stylus-specific transaction types and ensuring smooth interaction between the EVM and WASM environments.
-- `ArbDebug`: A debugging tool enabled by the `AllowDebugPrecompiles` flag. It provides mechanisms to emit test events, trigger reverts, and panic the chain for testing purposes.
+In the following section, we'll dive deep into these modifications, exploring how Nitro leverages 'Geth at the core' and the custom enhancements provided by ArbOS to deliver an advanced, high-performance STF. Stylus-specific tasks within ArbOS are covered separately to highlight its role in managing execution, host I/O, and memory operations.
-- `ArbFunctionTable` (no longer used): Originally designed to assist with function table compression, but is now deprecated in Nitro.
+## How precompiles work
-- `ArbInfo`: Retrieves account information, including balances and deployed contract code, providing a lightweight alternative to calling `eth_getCode` or `eth_getBalance`.
+A precompile consists of a Solidity interface in `contracts/src/precompiles/` and a corresponding Golang implementation in `precompiles/`. Using Geth's ABI generator, `solgen/gen.go` generates `solgen/go/precompilesgen/precompilesgen.go`, which collects the ABI data of the precompiles. The [runtime installer](https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L379) uses this generated file to check the type safety of each precompile's implementer.
-- `ArbOwner`: Allows chain owners to manage key network parameters, including gas pricing, scheduling upgrades, and setting various chain limits. The precompile is only accessible to chain owners.
+[The installer](https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L379) uses runtime reflection to ensure each implementer has all the right methods and signatures. This reflection includes restricting access to stateful objects like the EVM and `statedb` based on the declared purity. Additionally, the installer verifies and populates event function pointers to provide each precompile the ability to emit logs and know their gas costs. Additional configuration, like restricting a precompile's methods to only be callable by chain owners is possible by adding precompile wrappers like `ownerOnly` and `debugOnly` to their [installation entry](https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L403).
-- `ArbOwnerPublic`: A read-only version of `ArbOwner` that allows users to query information about current chain owners and governance settings.
+Completion of calling, dispatching, and recording of precompile methods occurs via runtime reflection, which avoids any human error manually parsing and writing bytes could introduce, and uses Geth's stable APIs for [packing and unpacking](https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L438) values.
-- `ArbosTest` (legacy): A historical precompile used for burning arbitrary amounts of gas. It has limited utility in Nitro.
+Each time a transaction calls a method of a child chain-specific precompile, a [`call context`](https://github.com/OffchainLabs/nitro/blob/f11ba39cf91ee1fe1b5f6b67e8386e5efd147667/precompiles/context.go#L26) gets created to track and record the gas burnt. For convenience, it also provides access to the public fields of the underlying [`TxProcessor`](https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L38). Because sub-transactions could revert without updates to this struct, the `TxProcessor` only makes public what is safe, such as the amount of parent chain calldata paid by the top-level transaction.
-- `ArbStatistics`: Provides historical data about the chain's state before the Nitro upgrade. Most functions that required this precompile in Arbitrum Classic now have better alternatives.
+For a complete list of precompiles refer to the [precompile references](/build-decentralized-apps/precompiles/02-reference.mdx).
## Messages
@@ -70,7 +55,7 @@ An [`L1IncomingMessage`](https://github.com/OffchainLabs/nitro/blob/4ac7e9268e98
## Retryables
-A retryable is a special message type for creating atomic parent chain to child chain messages; for details, see [parent-to-child chain messaging](/how-arbitrum-works/10-l1-to-l2-messaging.mdx).
+A retryable is a special message type for creating atomic parent chain to child chain messages; for details, see [parent-to-child chain messaging](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx).
## ArbOS state
@@ -78,11 +63,11 @@ ArbOS's state is viewed and modified via [`ArbosState`](https://github.com/Offch
Because two [`ArbosState`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L36) objects with the same [`backingStorage`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/storage/storage.go#L51) contain and mutate the same underlying state, different `ArbosState` objects can provide different views of ArbOS's contents. [`Burner`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/burn/burn.go#L11) objects, which track gas usage while working with the `ArbosState`, provide the internal mechanism. Some are read-only, causing transactions to revert with `vm.ErrWriteProtection` upon a mutating request. Others demand the caller have elevated privileges. Meanwhile, others dynamically charge users when doing stateful work. This view is chosen for safety when [`OpenArbosState()`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L57) creates the object and may never change.
-Must of ArbOS's state exists to facilitate its [precompiles](/build-decentralized-apps/precompiles/02-reference.mdx). The parts that aren't are detailed below.
-
[`arbosVersion`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L37), [`updgradeVersion`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L38) and [`upgradeTimestamp`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L39)
ArbOS upgrades are scheduled to happen [when finalizing the first block](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L350) after the `upgradeTimestamp`.
+Most of ArbOS's state exists to facilitate its [precompiles](/build-decentralized-apps/precompiles/02-reference.mdx). The parts that aren't are detailed below.
+
### [`blockhashes`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/blockhash/blockhash.go#L15)
This component maintains the last 256 parent chain block hashes in a circular buffer. This component allows the [`TxProcessor`](https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L38) to implement the `BLOCKHASH` and `NUMBER` opcodes and supports the precompile methods that involve the Outbox. To avoid changing the ArbOS state outside of a transaction, blocks made from messages with a new parent chain–block number update this info during an [`InternalTxUpdateL1BlockNumber`](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/internal_tx.go#L24) [`ArbitrumInternalTx`](https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/internal_tx.go) included as the first transaction of the block.
@@ -371,9 +356,9 @@ Users and developers can access parent chain fee-related data through the follow
The child chain pricing state tracks child chain resource usage to determine a reasonable child chain gas price. This process considers various factors, including user demand, the state of Geth, and the computational speed limit. The primary mechanism for doing so consists of a pair of pools, one larger than the other, that drain as child chain–specific resources are consumed and filled as time passes. Parent chain-specific resources, such as parent chain `calldata`, are not accounted for in the pools since they do not directly impact the computational workload of network actors. Instead, the design of the speed limit mechanism regulates execution resources to ensure consistent system performance and synchronization.
-While much of this state is accessible through the [`ArbGasInfo`](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo) and [`ArbOwner`](/build-decentralized-apps/precompiles/02-reference.mdx#arbowner) precompiles, most changes are automatic and happen during [block production](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L77) and the [transaction hooks](/how-arbitrum-works/04-state-transition-function/04-modified-geth-on-arbitrum.mdx#hooks). Each of an incoming message's transactions removes the parent chain component of the gas it uses from the pool. Afterward, the message's timestamp [informs the pricing mechanism](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L336) of the time passed as ArbOS [finalizes the block](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L350).
+While much of this state is accessible through the [`ArbGasInfo`](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo) and [`ArbOwner`](/build-decentralized-apps/precompiles/02-reference.mdx#arbowner) precompiles, most changes are automatic and happen during [block production](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L77) and the [transaction hooks](/how-arbitrum-works/deep-dives/geth.mdx#hooks). Each of an incoming message's transactions removes the parent chain component of the gas it uses from the pool. Afterward, the message's timestamp [informs the pricing mechanism](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L336) of the time passed as ArbOS [finalizes the block](https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L350).
-ArbOS's larger gas pool [determines](https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/l2pricing/pools.go#L98) the per-block gas limit, setting a dynamic [upper limit](https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/block_processor.go#L146) on the amount of compute gas a child chain block may have. This limit is always enforced, though it's done in the [`GasChargingHook`](/how-arbitrum-works/04-state-transition-function/04-modified-geth-on-arbitrum.mdx#gascharginghook) for the first transaction to avoid sharp decreases in the parent chain gas price from over-inflating the compute component purchased to above the gas limit. Enforicng this improves UX by allowing the first transaction to succeed rather than requiring a resubmission. Because the first transaction lowers the space left in the block, subsequent transactions do not employ this strategy and may fail from such compute-component inflation. This space is acceptable because such transactions are only present in cases where the system is under heavy load. The result is that the user's transaction is dropped without charges since the state transition fails early. Those trusting the Sequencer can rely on the transaction being automatically resubmitted in such a scenario.
+ArbOS's larger gas pool [determines](https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/l2pricing/pools.go#L98) the per-block gas limit, setting a dynamic [upper limit](https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/block_processor.go#L146) on the amount of compute gas a child chain block may have. This limit is always enforced, though it's done in the [`GasChargingHook`](/how-arbitrum-works/deep-dives/geth.mdx#gascharginghook) for the first transaction to avoid sharp decreases in the parent chain gas price from over-inflating the compute component purchased to above the gas limit. Enforicng this improves UX by allowing the first transaction to succeed rather than requiring a resubmission. Because the first transaction lowers the space left in the block, subsequent transactions do not employ this strategy and may fail from such compute-component inflation. This space is acceptable because such transactions are only present in cases where the system is under heavy load. The result is that the user's transaction is dropped without charges since the state transition fails early. Those trusting the Sequencer can rely on the transaction being automatically resubmitted in such a scenario.
We need a per-block gas limit because arbitrator WAVM execution is much slower than native transaction execution. This limit means there can only be so much gas, roughly translating to wall-block time–in a child chain block. It also allows ArbOS to limit the size of blocks should demand continue to surge even as the price rises.
@@ -393,7 +378,7 @@ Child chain gas fees work very similarly to gas on Ethereum. The amount of gas i
The child chain basefee is set by a version of the "exponential mechanism" widely discussed in the Ethereum community and shown to be equivalent to Ethereum's EIP-1559 gas pricing mechanism.
-The algorithm compares gas usage against the [speed limit](/how-arbitrum-works/09-gas-fees.mdx#the-speed-limit) parameter, the target amount of gas per second that the chain can handle sustainably over time. (The speed limit on Arbitrum One is 7,000,000 gas per second.) The algorithm tracks a gas backlog. Whenever a transaction consumes gas, it gets added to the backlog. Whenever the clock ticks one second, the speed limit subtracts from the backlog, but the backlog can never go below zero.
+The algorithm compares gas usage against the [speed limit](/how-arbitrum-works/deep-dives/gas-and-fees.mdx#the-speed-limit) parameter, the target amount of gas per second that the chain can handle sustainably over time. (The speed limit on Arbitrum One is 7,000,000 gas per second.) The algorithm tracks a gas backlog. Whenever a transaction consumes gas, it gets added to the backlog. Whenever the clock ticks one second, the speed limit subtracts from the backlog, but the backlog can never go below zero.
Intuitively, if the backlog grows, the algorithm should increase the gas price to slow gas usage because usage is above the sustainable level. If the backlog shrinks, the price should decrease again because usage has been below the sustainable limit so more gas usage can be welcomed.
@@ -418,3 +403,74 @@ The security of Nitro chains depends on the assumption that when one Stylus integrates into the State Transition Function (STF), covering execution flow, messaging handling, caching, and interactions with ArbOS and Geth.
+
+### 1. Execution flow of a Stylus transaction
+
+When a Transaction interacts with a Stylus contract, its execution follows a distinct path compared to EVM transactions:
+
+- **Transaction submission and routing**
+ - The transaction is included in a child chain block by the Sequencer.
+ - Geth processes the transaction and determines its target contract.
+ - If the target is a Stylus contract, ArbOS routes execution to the WASM runtime instead of the EVM.
+- **Stylus execution within ArbOS**
+ - ArbOS retrieves the Stylus program from its cache (`stylus/src/cache.rs`) or loads it from storage if not cached.
+ - The WebAssembly System Interface (Go-WASI) initializes a secure execution environment.
+ - The WASM module executes within ArbOS, processing instructions efficiently and calling host I/O functions.
+- **Host I/O operations for blockchain state access**
+ - Stylus contracts do not use EVM opcodes. Instead, they interact with the blockchain through host I/O calls handled by ArbOS.
+ - These include storage access (`TLOAD` `TSTORE`), arithmetic operations (`MULMOD`, `ADDMOD`), and context retrieval (`GETCALLER`, `GETCALLVALUE`).
+ - ArbOS ensures these operations are efficient and compatible with Ethereum's state model.
+ - **State commitment and finalization**
+ - Once execution is complete, ArbOS finalizes storage changes and updates logs and receipts.
+ - Geth processes the final transaction result and commits it to the state tree.
+
+This process bypasses the EVM interpreter entirely, allowing Stylus contracts to execute significantly faster than their Solidity counterparts.
+
+### 2. Stylus caching and gas pricing
+
+- **Stylus gas pricing model**
+ Unlike standard EVM gas pricing, Stylus pricing follows a multi-dimensional cost model, incorporating:
+ - **Ink cost (memory and execution cost)**
+ - Measure in `Ink` units (Stylus's equivalent of computational gas).
+ - `Ink` pricing varies based on execution complexity, memory usage, and computation steps.
+ - Complex WASM operations consume more `Ink`, directly impacting execution costs.
+ - **Opcode pricing**
+ - WASM instructions are assigned individual execution costs similar to EVM opcodes.
+ - Heavy computation opcodes are priced higher.
+ - Cheap opcodes (e.g., simple arithmetic, bitwise operations) have minimal costs.
+ - **Host I/O pricing**
+ - Stylus introduces fine-grained pricing for different I/O calls:
+ - **Storage read/writes**: Priced based on access pattern and data size.
+ - **Precompile calls**: Stylus-specific precompiles have fixed execution costs.
+ - **External calls to EVM contracts**: Encapsulated within ArbOS transaction handling, with additional gas considerations.
+
+#### Stylus caching
+
+Stylus contracts leverage an advanced caching system to minimize execution overhead within ArbOS:
+
+- **LRU (Least Recently Used) caching**: Keeps the most recently accessed Stylus contracts in memory for fast execution.
+- **Persistent long-term caching**: Caching for selected contracts may occur across blocks based on an economic auction model.
+- **Init costs and execution pricing**: Instead of a flat gas cost, Stylus contracts have dynamic execution costs based on WASM complexity. ArbOS maintains pricing parameters (`initCost`, `cachedCost`) that adjust based on future optimizations in WASM execution.
+
+### 3. Interaction with ArbOS and Geth
+
+| Execution Stage | Handled By |
+| ---------------------- | --------------------------------------------------------- |
+| Transaction submission | **Geth** (identifies target contract) |
+| Stylus execution | **ArbOS** (switches to WASM runtime) |
+| Host I/O calls | **ArbOS** (handles storage, call data, context retrieval) |
+| State commitment | **Geth and ArbOS** (finalizes updates, commits to state) |
+
+### 4. Go-WASI and co-threads in Stylus execution
+
+ArbOS executes Stylus contracts using Go-WASI, a WASM-compatible runtime with custom optimizations for Arbitrum. Key features include:
+
+- **Memory management**: WASM modules execute in a sandboxed environment with strict memory allocation policies.
+- **Co-threads for efficient execution**: Instead of traditional synchronous execution, Stylus employs co-threading, enabling lightweight task switching and parallelism where possible.
+- **Deterministic execution**: Ensures that Stylus contracts remain fully deterministic and compatible with Ethereum's consensus model.
+
+These optimizations make Stylus an extremely efficient execution environment, capable of outperforming the EVM while maintaining security and compatibility with Ethereum's state model.
diff --git a/docs/how-arbitrum-works/deep-dives/assertions.mdx b/docs/how-arbitrum-works/deep-dives/assertions.mdx
new file mode 100644
index 0000000000..fa25d60ce2
--- /dev/null
+++ b/docs/how-arbitrum-works/deep-dives/assertions.mdx
@@ -0,0 +1,99 @@
+---
+title: Assertions
+description: 'Deep dive information on assertions and creating them.'
+author: pete-vielhaber
+sme: Mehdi
+user_story: As a current or prospective Arbitrum user, I need to learn more about the Rollup protocol and validation.
+content_type: get-started
+---
+
+## The Rollup chain assertions vs. child chain blocks
+
+The Rollup chain consists of assertions, which serve as checkpoints summarizing multiple child chain blocks.
+
+- Child chain blocks contain individual transaction data
+- Assertions provide state summaries recorded on Ethereum
+- Each assertion may represent multiple child chain blocks, optimizing gas costs and reducing Ethereum storage usage.
+
+Validators submit assertions by calling `createNewAssertion` in the Rollup contract. Assertions contain structured data known as `AssertionInputs`, which capture the before-state and after-state of execution for future validation.
+
+## Contents of an assertion
+
+Each assertion consists of:
+
+- **Assertion number**: A unique identifier
+- **Predecessor assertion**: The last confirmed assertion
+- **Number of child chain blocks**: The total child chain blocks included
+- **Number of inbox messages**: Messages consumed during execution
+- **Output hash**: A cryptographic commitment to the resulting state
+
+Arbitrum ensures assertions are automatically confirmed or rejected based on protocol rules:
+
+1. An assertion is confirmed if:
+ - Its predecessor is the latest confirmed assertion
+ - The dispute window has passed without challenges
+2. An assertion is rejected if:
+ - Its predecessor assertion is invalid
+ - A conflicting assertion has been confirmed
+
+For more details on how the Rollup chain works under BoLD, the [gentle introduction](/how-arbitrum-works/bold/gentle-introduction.mdx) provides an overview that touches on the Rollup chain.
+
+:::note
+
+Validators and proposers serve different roles. Validators validate transactions by computing the next chain state using the chain's STF, whereas proposers can also assert and challenge the chain state on the parent chain.
+
+:::
+
+Except for the assertion number, the contents of the assertion are all just claims by the assertion's proposer. Arbitrum doesn't know at first whether any of these fields are correct. The protocol should eventually confirm the assertion if all of these fields are correct. The protocol should eventually reject the assertion if one or more of these fields are incorrect.
+
+An assertion implicitly claims that its predecessor assertion is correct, which means that it also claims the correctness of a complete history of the chain: a sequence of ancestor assertions that reaches back to the birth of the chain.
+
+An assertion also implicitly claims that its older siblings (older assertions with the same predecessor), if there are any, are incorrect. If two assertions are siblings, and the older sibling is correct––then the younger sibling is considered incorrect, even if everything else in the younger sibling is true.
+
+The assertion is assigned a deadline, which indicates how much time other validators have to respond to it. For an assertion `R` with no older siblings, this will equal the time the assertion was posted, plus an interval of time known as the challenge Period; subsequent younger siblings will have the same deadline as their oldest sibling (`R`). You don't need to do anything if you're a validator and agree that an assertion is correct. If you disagree with an assertion, you can post another assertion with a different result, and you'll probably end up in a challenge against the party who proposed the first assertion (or another party acting in support of that assertion). More on challenges below:
+
+## Delays
+
+Even if the Assertion Tree has multiple conflicting assertions and multiple disputes are in progress, validators can continue making new assertions. Honest validators will build on one valid assertion (intuitively, an assertion is also an implicit claim of the validity of all of its parent assertions). Likewise, users can continue transacting on the child chain since transactions will continue to post in the chain's inbox.
+
+The only delay users experience during a dispute is their [Child to parent chain messages](/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx) (i.e., withdrawals). A key property of BoLD is that we can guarantee that, in the common case, their withdrawals/messages will only get delayed for one challenge period. In the case of an actual dispute, the withdrawals/messages will be delayed by no more than two challenge periods, regardless of the adversaries' behavior during the challenge.
+
+## Staking and validator incentives
+
+Arbitrum requires validators to bond `ETH` as a security deposit to ensure honest participation and prevent malicious behavior. This mechanism enforces economic accountability:
+
+- **Proposers** (validators submitting assertions) must bond `ETH` to support their claims.
+- **Challenges** against incorrect assertions result in bond forfeiture for dishonest validators.
+- **Successful challengers** receive a portion of the dishonest validator's bond as a reward.
+
+Validators can adopt different roles:
+
+1. **Active validators**: Regularly propose new assertions.
+2. **Defensive validators**: Monitor the network and challenge incorrect assertions.
+3. **Watchtower validators**: Passively observe and raise alarms when fraud is detected.
+
+The protocol design requires only one honest validator to secure the system, making Arbitrum trustless and resistant to Sybil attacks.
+
+## Staking mechanism
+
+Some validators will act as bonders at any given time, while others remain passive. Bonders deposit `ETH` bonds into Arbitrum's smart contracts, which are forfeited if they lose a challenge.
+
+:::note
+
+Nitro chains exclusively accept `ETH` as collateral for staking.
+
+:::
+
+A single bond can secure a sequence of assertions, meaning a validator's bond applies to multiple checkpoints of the chain's history. This checkpoint allows efficient resource use while maintaining security.
+
+A validator must be bonded to its predecessor to create a new assertion. The bond ensures that validators have economic risk in any assertion they make.
+
+## Handling disputes and delays
+
+Multiple disputes may be active simultaneously if conflicting assertions arise in the Assertion Tree. However, Arbitrum's protocol ensures that:
+
+- **Honest validators can continue asserting**, building on the last correct assertion.
+- **Users can keep transacting** on the child chain without disruption.
+- **Child-to-parent chain withdrawals** may experience delays - Typically, withdrawals experience a single challenge period (6.4 days) delay. - A key property of BoLD is that we can guarantee that in the common case, withdrawals/messages will only experience delay of one challenge period. In the case of an actual dispute, the withdrawals/messages will be delayed by no more than two challenge periods, regardless of the adversaries' behavior during the challenge.
+
+Despite these delays, Arbitrum guarantees that honest assertions always succeed, maintaining Ethereum-level security.
diff --git a/docs/how-arbitrum-works/09-gas-fees.mdx b/docs/how-arbitrum-works/deep-dives/gas-and-fees.mdx
similarity index 99%
rename from docs/how-arbitrum-works/09-gas-fees.mdx
rename to docs/how-arbitrum-works/deep-dives/gas-and-fees.mdx
index 2c6e43f21f..5fa5b6cbde 100644
--- a/docs/how-arbitrum-works/09-gas-fees.mdx
+++ b/docs/how-arbitrum-works/deep-dives/gas-and-fees.mdx
@@ -18,7 +18,7 @@ The parent chain component is the product of the Geth would pay to bonders in a vanilla parent chain, such as the computation and storage charges applying the State Transition Function entails. ArbOS charges additional fees for executing its child chain-specific [precompiles](/build-decentralized-apps/precompiles/01-overview.mdx), whose fees are dynamically priced according to the specific resources used while executing the call.
-The following sections will detail how to calculate parent and child chain fees. If you do not need precise calculations or a technical understanding, skip to the next section, [Parent chain to child chain messaging](/how-arbitrum-works/10-l1-to-l2-messaging.mdx).
+The following sections will detail how to calculate parent and child chain fees. If you do not need precise calculations or a technical understanding, skip to the next section, [Parent chain to child chain messaging](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx).
## Parent chain gas pricing
diff --git a/docs/how-arbitrum-works/04-state-transition-function/04-modified-geth-on-arbitrum.mdx b/docs/how-arbitrum-works/deep-dives/geth.mdx
similarity index 98%
rename from docs/how-arbitrum-works/04-state-transition-function/04-modified-geth-on-arbitrum.mdx
rename to docs/how-arbitrum-works/deep-dives/geth.mdx
index 771ff89f77..3e0258d9ef 100644
--- a/docs/how-arbitrum-works/04-state-transition-function/04-modified-geth-on-arbitrum.mdx
+++ b/docs/how-arbitrum-works/deep-dives/geth.mdx
@@ -135,11 +135,11 @@ It represents a user deposit from a parent chain to a child chain. This represen
### [`ArbitrumSubmitRetryableTx`](https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L232)
-It represents a retryable submission and may schedule an [`ArbitrumRetryTx`](#arbitrumretrytx) if enough gas is available. Fore more info, please see the [retryables documentation](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#retryable-tickets).
+It represents a retryable submission and may schedule an [`ArbitrumRetryTx`](#arbitrumretrytx) if enough gas is available. Fore more info, please see the [retryables documentation](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#retryable-tickets).
### [`ArbitrumRetryTx`](https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L161)
-These calls get scheduled by calls using the `redeem` method of the [`ArbRetryableTx`](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile and via retryable auto-redemption. Fore more info, please see the [retryables documentation](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#retryable-tickets).
+These calls get scheduled by calls using the `redeem` method of the [`ArbRetryableTx`](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile and via retryable auto-redemption. Fore more info, please see the [retryables documentation](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#retryable-tickets).
### [`ArbitrumInternalTx`](https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/internal_tx.go)
@@ -167,7 +167,7 @@ Nitro's Geth is configurable with the following [child chain-specific chain para
### `EnableArbos`
-Introduces [ArbOS](/how-arbitrum-works/04-state-transition-function/05-arbos.mdx), converting what would otherwise be a vanilla parent chain into a child chain Arbitrum rollup.
+Introduces [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx), converting what would otherwise be a vanilla parent chain into a child chain Arbitrum rollup.
### `AllowDebugPrecompiles`
diff --git a/docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx b/docs/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx
similarity index 97%
rename from docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx
rename to docs/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx
index 048cf712fb..6d5fc0f4db 100644
--- a/docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx
+++ b/docs/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx
@@ -9,7 +9,7 @@ content_type: get-started
import ImageZoom from '@site/src/components/ImageZoom';
-In the [Bypassing the Sequencer](/how-arbitrum-works/02-transaction-lifecycle.mdx#bypassing-the-sequencer) section, we introduced an alternative way for users to submit transactions to a child chain by going through the parent chain's Delayed Inbox contract instead of sending them directly to the Sequencer. This approach is one example of a parent-to-child messaging path. More broadly, parent-to-child chain messaging covers all ways to:
+In the [Bypassing the Sequencer](/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx#bypassing-the-sequencer) section, we introduced an alternative way for users to submit transactions to a child chain by going through the parent chain's Delayed Inbox contract instead of sending them directly to the Sequencer. This approach is one example of a parent-to-child messaging path. More broadly, parent-to-child chain messaging covers all ways to:
- Submit child chain bound transaction from a parent chain
- Deposit `ETH` or native tokens from a parent chain to a child chain
@@ -22,7 +22,7 @@ We generally categorize these parent-to-child chain messaging methods as follows
- **`ETH` Bridging**: For Arbitrum chains that use `ETH` as their gas token, users can deposit `ETH` onto a child chain via the Delayed Inbox.
- **Custom gas token bridging**: For Arbitrum chains that use a custom gas token, users can deposit that chain's native token to a child chain using the same mechanism.
-2. **Transaction via the Delayed Inbox**: As described in the [Bypassing the Sequencer](/how-arbitrum-works/02-transaction-lifecycle.mdx#bypassing-the-sequencer) section, this method allows users to send transactions through the parent chain. It includes two sub-types of messages:
+2. **Transaction via the Delayed Inbox**: As described in the [Bypassing the Sequencer](/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx#bypassing-the-sequencer) section, this method allows users to send transactions through the parent chain. It includes two sub-types of messages:
- **Unsigned messages**: General arbitrary data or function calls
- **Signed messages**: Messages that include a signature, enabling certain authenticated actions
@@ -105,7 +105,7 @@ modifier onlyFromMyL1Contract() override {
Arbitrum provides a _Delayed Inbox_ contract on the parent chain that can deliver arbitrary messages to the child chain. This functionality is important for two reasons:
1. **General cross-chain messaging**: Allows parent chain EOAs or parent chain contracts to send messages or transactions to a child chain. This functionality is critical for bridging assets (other than the chain's native token) and performing cross-chain operations.
-2. **Censorship resistance**: It ensures the Arbitrum chain remains censorship-resistant, even if the Sequencer misbehaves or excludes certain transactions; refer to [Bypassing the Sequencer](/how-arbitrum-works/02-transaction-lifecycle.mdx#bypassing-the-sequencer) for more details.
+2. **Censorship resistance**: It ensures the Arbitrum chain remains censorship-resistant, even if the Sequencer misbehaves or excludes certain transactions; refer to [Bypassing the Sequencer](/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx#bypassing-the-sequencer) for more details.
Users can send child chain transactions through the Delayed Inbox in two primary ways:
diff --git a/docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx b/docs/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx
similarity index 92%
rename from docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx
rename to docs/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx
index 0ee37c144f..7c60e1a4a0 100644
--- a/docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx
+++ b/docs/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx
@@ -15,7 +15,7 @@ allows for arbitrary child chain to contract calls, i.e., messages initiated from the child chain, which eventually resolve in
execution on the parent chain. Child-to-parent chain messages (aka "outgoing" messages) bear some
things in common with Arbitrum's [parent chain to child chain
-messages](/how-arbitrum-works/10-l1-to-l2-messaging.mdx), which are "in reverse" though with
+messages](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx), which are "in reverse" though with
differences, which we'll explore in this section.
## Protocol flow
@@ -69,7 +69,7 @@ We refer to `NodeInterface` as a "virtual" contract; its methods are accessible
### Why child to parent chain messages require manual execution
-Unlike [retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx), which can execute automatically with pre-funded gas, child-to-parent chain message must undergo manual execution because Ethereum (parent chain) does not support scheduled execution.
+Unlike [retryable tickets](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx), which can execute automatically with pre-funded gas, child-to-parent chain message must undergo manual execution because Ethereum (parent chain) does not support scheduled execution.
However, applications can implement execution markets that allow third parties to execute messages for a fee.
@@ -108,7 +108,7 @@ The following diagram depicts the process that funds follow during a withdrawal
## `ERC-20` token withdrawal
-Arbitrum has a canonical bridge design and architecture, which we explain in detail in the [Token bridging](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#token-bridging) section of Bridging from a parent chain to a child chain article. This section will explain how the Arbitrum canonical bridge works on the child-to-parent chain token bridging.
+Arbitrum has a canonical bridge design and architecture, which we explain in detail in the [Token bridging](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#token-bridging) section of Bridging from a parent chain to a child chain article. This section will explain how the Arbitrum canonical bridge works on the child-to-parent chain token bridging.
1. Initiation of a child-to-parent chain transfer occurs via the `L2GatewayRouter` contract on the child chain.
2. The token's gateway contract (`L2ArbitrumGateway`) on the child chain gets called.
diff --git a/docs/how-arbitrum-works/03-sequencer.mdx b/docs/how-arbitrum-works/deep-dives/sequencer.mdx
similarity index 98%
rename from docs/how-arbitrum-works/03-sequencer.mdx
rename to docs/how-arbitrum-works/deep-dives/sequencer.mdx
index a705a4db43..b1a53449d2 100644
--- a/docs/how-arbitrum-works/03-sequencer.mdx
+++ b/docs/how-arbitrum-works/deep-dives/sequencer.mdx
@@ -269,7 +269,7 @@ Developers and users should consider the appropriate level of finality based on
## Censorship Timeout
-As mentioned in the original [Arbitrum BoLD Forum Post](https://forum.arbitrum.foundation/t/aip-bold-permissionless-validation-for-arbitrum/23232/70?), the initial release of [Arbitrum BoLD](../how-arbitrum-works/bold/gentle-introduction.mdx) will come with a feature called ”Censorship Timeout” (originally called “Delay Buffer”). For Arbitrum One and Arbitrum Nova, it is proposed that this feature be enabled by default alongside BoLD’s upgrade.
+As mentioned in the original [Arbitrum BoLD Forum Post](https://forum.arbitrum.foundation/t/aip-bold-permissionless-validation-for-arbitrum/23232/70?), the initial release of [Arbitrum BoLD](/how-arbitrum-works/bold/gentle-introduction.mdx) will come with a feature called ”Censorship Timeout” (originally called “Delay Buffer”). For Arbitrum One and Arbitrum Nova, it is proposed that this feature be enabled by default alongside BoLD’s upgrade.
Censorship Timeout aims to limit the negative effects of:
diff --git a/docs/how-arbitrum-works/deep-dives/stf-inputs.mdx b/docs/how-arbitrum-works/deep-dives/stf-inputs.mdx
new file mode 100644
index 0000000000..9815dc4030
--- /dev/null
+++ b/docs/how-arbitrum-works/deep-dives/stf-inputs.mdx
@@ -0,0 +1,60 @@
+---
+title: 'Inputs to the State Transition Function'
+description: 'Learn the fundamentals of Nitro, Arbitrum stack.'
+author: petevielhaber
+sme: Mehdi
+user_story: As a current or prospective Arbitrum user, I need learn more about Nitros design.
+content_type: get-started
+---
+
+Arbitrum nodes receive
+ transaction
+ inputs through two channels:
+
+Nodes subscribe to the Sequencer feed, receiving upcoming ordered transactions published in real time. To learn more, refer to the [real-time sequencer feed documentation](/how-arbitrum-works/deep-dives/sequencer.mdx#real-time-sequencer-feed).
+
+Nodes also subscribe to the `SequencerBatchDelivered` event on the parent chain. This event occurs whenever a batch of transactions gets delivered to the parent chain via the batch poster. Upon receiving this event, nodes verify that the transactions recorded on the parent chain match those from the Sequencer feed. If discrepancies arise, nodes re-organize to adopt the transactions confirmed on the parent chain, using the parent chain as the definitive source of truth.
+
+As discussed in the [considerations and limitations section](/how-arbitrum-works/deep-dives/sequencer.mdx#considerations-and-limitations), these methods suit different applications.
+
+These transactions serve as inputs for the State Transition Function (STF).
+
+## Message types
+
+Arbitrum supports multiple message types: These messages fall into two broad categories:
+
+- Messages submitted directly to the Sequencer as child chain messages
+- Messages submitted to the parent chain
+
+For other message types, see the [parent-to-child chain messaging documentation](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx).
+
+In the system, we refer to these messages as `L1IncomingMessage` (Feel free to inspect the [source code reference](https://github.com/OffchainLabs/nitro/blob/4ac7e9268e9885a025e0060c9ec30f9612f9e651/arbos/incomingmessage.go#L54) ).
+
+When submitted to the Sequencer feed, messages receive unique identifiers for proper routing. Below is the list of message types, their associated constant values, and descriptions:
+
+```solidity
+uint8 constant L2_MSG = 3;
+uint8 constant L1MessageType_L2FundedByL1 = 7;
+uint8 constant L1MessageType_submitRetryableTx = 9;
+uint8 constant L1MessageType_ethDeposit = 12;
+uint8 constant L1MessageType_batchPostingReport = 13;
+uint8 constant L2MessageType_unsignedEOATx = 0;
+uint8 constant L2MessageType_unsignedContractTx = 1;
+
+uint8 constant ROLLUP_PROTOCOL_EVENT_TYPE = 8;
+uint8 constant INITIALIZATION_MSG_TYPE = 11;
+```
+
+| Message Type | Value | Description |
+| ---------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `L2MessageType_unsignedEOATx` | 0 | Unsigned child chain messages from EOAs submitted to the parent chain. |
+| `L2MessageType_unsignedContractTx` | 1 | Unsigned child chain messages submitted to the parent chain. |
+| `L2_MSG` | 3 | Child chain messages submitted directly to the Sequencer. |
+| `L1MessageType_L2FundedByL1` | 7 | Child chain messages that go to the parent chain's Delayed Inbox, with funding provided on the parent chain itself. |
+| `ROLLUP_PROTOCOL_EVENT_TYPE` | 8 | Arbitrum Classic used it for messages sent to bridge, Nitro does not use it. |
+| `L1MessageType_submitRetryableTx` | 9 | Submitting parent chain messages to the child chain via retryable tickets. |
+| `INITIALIZATION_MSG_TYPE` | 11 | The first message added to a new Rollup inbox. Its presence indicates proper initialization of the Rollup. |
+| `L1MessageType_ethDeposit` | 12 | Child chain messages that handle deposits of native tokens (`ETH`) into the child chain. |
+| `L1MessageType_batchPostingReport` | 13 | Used by the Sequencer to update the pricing model based on payment(s) by the batch poster. |
+
+These identifiers enable nodes to route messages correctly.
diff --git a/docs/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx b/docs/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx
new file mode 100644
index 0000000000..ed68bc9a6c
--- /dev/null
+++ b/docs/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx
@@ -0,0 +1,139 @@
+---
+title: Transaction lifecycle on Arbitrum
+description: 'Learn how transactions are submitted and processed on Arbitrum, including sequencer and non-sequencer pathways.'
+author: pete-vielhaber
+sme: Mehdi
+user_story: As a current or prospective Arbitrum user, I need to learn more about the transaction lifecycle.
+content_type: concept
+---
+
+import ImageZoom from '@site/src/components/ImageZoom';
+
+You can submit transactions to the Arbitrum chain through two main pathways:
+
+1. **Through the Sequencer** - The standard method for most transactions
+2. **Bypassing the Sequencer** - Using the Delayed Inbox contract on the Parent chain
+
+This guide explains both methods, when to use each one, and how they work within Arbitrum's transaction lifecycle.
+
+## Transaction submission methods
+
+### Sequencer pathways
+
+You can send transactions to the Sequencer through four methods:
+
+- Public RPC endpoints
+- Third-party RPC providers
+- Self-hosted Arbitrum nodes
+- Direct Sequencer endpoint
+
+The first three options route through a load balancer, while the Sequencer endpoint connects directly.
+
+### Non-sequencer pathway
+
+You can also submit transactions directly to the Delayed Inbox contract on the Parent chain. This method works even when the Sequencer is unavailable and provides additional censorship resistance.
+
+The following diagram shows the different ways you can submit transactions to Arbitrum:
+
+
+
+## Submitting transactions to the Sequencer
+
+The Sequencer processes most transactions on Arbitrum. You have four options for sending transactions to the Sequencer, each with different benefits depending on your needs.
+
+### Public RPC
+
+Arbitrum provides public RPC endpoints for Arbitrum One, Arbitrum Nova, and Arbitrum Sepolia. These endpoints are rate-limited, making them best for:
+
+- Testing and development
+- Light usage and general interactions
+- Applications with low transaction volume
+
+For more details on the specific RPC endpoints for each chain, please see [this section](https://docs.arbitrum.io/build-decentralized-apps/reference/node-providers#arbitrum-public-rpc-endpoints) of the documentation.
+
+### Third-party RPC
+
+Third-party node providers offer enhanced performance and higher rate limits. Many providers that support Ethereum also support Arbitrum chains. Use third-party RPCs when you need:
+
+- Higher throughput
+- Better performance
+- More reliable uptime
+- Advanced features like analytics
+
+You can find a list of supported third-party providers [here](https://docs.arbitrum.io/build-decentralized-apps/reference/node-providers#third-party-rpc-providers).
+
+### Arbitrum nodes
+
+Running your own Arbitrum node provides maximum control and privacy. Your transactions connect to the Sequencer through the Sequencer Feed. Consider this option if you need:
+
+- Complete control over transaction handling
+- Maximum privacy
+- Custom node configurations
+
+Please see the [Arbitrum Node](https://docs.arbitrum.io/run-arbitrum-node/overview) documentation to learn more about setting up and running a node.
+
+### Sequencer endpoint
+
+The Sequencer endpoint provides the fastest path to transaction submission by bypassing the load balancer. This endpoint only supports:
+
+- `eth_sendRawTransaction`
+- `eth_sendRawTransactionConditional`
+
+Use this method when you need the lowest possible latency for time-sensitive transactions.
+
+The following diagram shows the four methods for submitting transactions to the Sequencer:
+
+
+
+## Bypassing the Sequencer
+
+You can submit transactions directly to the Delayed Inbox contract on the Parent chain without using the Sequencer. This method provides:
+
+- **Censorship resistance** - Your transaction will be included even if the Sequencer refuses to process it
+- **Availability guarantee** - Transactions work even when the Sequencer is offline
+- **Decentralization** - Reduces dependency on the Sequencer
+
+There are two paths your transaction can take through the Delayed Inbox.
+
+When you submit a transaction to the Delayed Inbox, two things can happen:
+
+1. **Automatic processing** - The Sequencer picks up your transaction and includes it in the normal transaction flow
+2. **Force inclusion** - If 24 hours pass without processing, you can call the `forceInclude` function on the `SequencerInbox` contract to guarantee inclusion
+
+This two-path system ensures your transaction will always be processed, even if the Sequencer is unresponsive or censoring transactions.
+
+
+
+### Using the Delayed Inbox
+
+To submit a transaction through the Delayed Inbox:
+
+1. **Construct your transaction** and serialize it
+2. **Call [`sendL2Message`](https://github.com/OffchainLabs/nitro-contracts/blob/fbbcef09c95f69decabaced3da683f987902f3e2/src/bridge/AbsInbox.sol#L150)** with your serialized transaction data
+3. **Wait for processing** or force inclusion after 24 hours
+
+### Force inclusion after delays
+
+If your transaction isn't processed within 24 hours, call the [`forceInclusion`](https://github.com/OffchainLabs/nitro-contracts/blob/fbbcef09c95f69decabaced3da683f987902f3e2/src/bridge/SequencerInbox.sol#L284) function on the `SequencerInbox` contract. This guarantees your transaction will be included regardless of Sequencer status.
+
+### Using the Arbitrum SDK
+
+The Arbitrum SDK simplifies Delayed Inbox interactions through the [`InboxTools`](https://github.com/OffchainLabs/arbitrum-sdk/blob/792a7ee3ccf09842653bc49b771671706894cbb4/src/lib/inbox/inbox.ts#L64C14-L64C24) class:
+
+| Method | Purpose |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| [`sendChildSignedTx`](https://github.com/OffchainLabs/arbitrum-sdk/blob/792a7ee3ccf09842653bc49b771671706894cbb4/src/lib/inbox/inbox.ts#L401C16-L401C33) | Submit transaction to Delayed Inbox |
+| [`forceInclude`](https://github.com/OffchainLabs/arbitrum-sdk/blob/792a7ee3ccf09842653bc49b771671706894cbb4/src/lib/inbox/inbox.ts#L367) | Force transaction inclusion after 24 hours |
+| [`signChildTx`](https://github.com/OffchainLabs/arbitrum-sdk/blob/792a7ee3ccf09842653bc49b771671706894cbb4/src/lib/inbox/inbox.ts#L429) | Helper for transaction signing |
diff --git a/docs/how-arbitrum-works/timeboost/gentle-introduction.mdx b/docs/how-arbitrum-works/timeboost/gentle-introduction.mdx
index dacb13639a..12d89acb81 100644
--- a/docs/how-arbitrum-works/timeboost/gentle-introduction.mdx
+++ b/docs/how-arbitrum-works/timeboost/gentle-introduction.mdx
@@ -90,21 +90,11 @@ The chain owner sets the minimum reserve price, which can be updated at any time
Once the autonomous auctioneer determines an auction winner, the `Auction` contract will deduct the second-highest bid amount from the account of the highest bidder and transfer those funds to a `beneficiary` account designated by the chain owner by default. The `expressLaneControllerAddress` specified in the highest bid will become the express lane controller for the round.
-### Default parameters
+ |
-Below are a few of the default Timeboost parameters mentioned earlier. All these parameters and more are configurable by the chain owner.
+## FAQs
-| Parameter name | Description | Recommended default value |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
-| `roundDurationSeconds` | Duration of time that the sequencer will honor the express lane privileges for transactions signed by the current round’s express lane controller. | 60 seconds |
-| `auctionClosingSeconds` | Time before the start of the next round. The autonomous auctioneer will not accept bids during this time interval. | 15 seconds |
-| `beneficiary` | Address where proceeds from the Timeboost auction are sent to when `flushBeneficiaryBalance()` gets called on the auction contract. | An address controlled by the chain's owner |
-| `_biddingToken` | Address of the token used to make bids in the Timeboost auction. It can be any `ERC-20` token (assuming the token chosen does not have fee-on-transfer, rebasing, transfer hooks, or otherwise non-standard `ERC-20` logic). | `WETH` |
-| `nonExpressDelayMsec` | The artificial delay applied to the arrival timestamp of non-express lane transactions _before_ the non-express lane transactions are sequenced. | 0.2 seconds, or 200 milliseconds |
-| `reservePrice` | The minimum bid amount accepted by the auction contract for the current Timeboost auction, denominated in `_biddingToken`. | None |
-| `_minReservePrice` | A value that must be equal to or below the `reservePrice` to act as a "floor minimum" for Timeboost bids. Enforced by the auction contract. | 0.001 `WETH` |
-
-## Who is Timeboost for, and how do I use it?
+#### Who is Timeboost for, and how do I use it?
Timeboost is an optional addition to an Arbitrum chain’s infrastructure, meaning that enabling Timeboost is at the discretion of the chain owner and that an Arbitrum chain can fully function normally without Timeboost.
@@ -127,3 +117,9 @@ Timeboost adds a unique twist to your existing or prospective MEV strategies tha
As with many new features and upgrades to Arbitrum Nitro, Timeboost is an optional feature that chain owners may choose to deploy and customize however they see fit. Deploying and enabling/disabling Timeboost on a live Arbitrum chain will not halt or impact the chain but will instead influence the chain's transaction ordering policy. An Arbitrum chain will, by default, fall back to FCFS in scenarios where Timeboost is deployed but disabled, or if there is no express lane controller for a given round.
We recommend that Arbitrum chains holistically assess the applicability and use cases of Timeboost for their chain before deploying and enabling Timeboost. This assessment is necessary because some Arbitrum chains may not have that much MEV (e.g., arbitrage) to begin with. Furthermore, we recommend that Arbitrum chains start with the default parameters recommended by Offchain Labs and closely monitor the results and impacts on their chain’s ecosystem over time before considering any adjustments to the parameters.
+
+:::info Additional FAQs
+
+For more frequently asked questions refer to the [Timeboost FAQ](/how-arbitrum-works/timeboost/timeboost-faq.mdx).
+
+:::
diff --git a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx
index 22107a8ae8..5646e493f8 100644
--- a/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx
+++ b/docs/how-arbitrum-works/timeboost/how-to-use-timeboost.mdx
@@ -548,6 +548,20 @@ Here is an example query on how to look up and download historical bid data:
download: s3://timeboost-auctioneer-arb1/ue2/validated-timeboost-bids/2025/06/09/0130304-0130343.csv.gzip to ./local.csv.gzip
```
+## Default parameters
+
+Below are a few of the default Timeboost parameters mentioned earlier. All these parameters and more are configurable by the chain owner.
+
+| Parameter name | Description | Recommended default value |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `roundDurationSeconds` | Duration of time that the sequencer will honor the express lane privileges for transactions signed by the current round’s express lane controller. | 60 seconds |
+| `auctionClosingSeconds` | Time before the start of the next round. The autonomous auctioneer will not accept bids during this time interval. | 15 seconds |
+| `beneficiary` | Address where proceeds from the Timeboost auction are sent to when `flushBeneficiaryBalance()` gets called on the auction contract. | An address controlled by the chain's owner |
+| `_biddingToken` | Address of the token used to make bids in the Timeboost auction. It can be any `ERC-20` token (assuming the token chosen does not have fee-on-transfer, rebasing, transfer hooks, or otherwise non-standard `ERC-20` logic). | `WETH` |
+| `nonExpressDelayMsec` | The artificial delay applied to the arrival timestamp of non-express lane transactions _before_ the non-express lane transactions are sequenced. | 0.2 seconds, or 200 milliseconds |
+| `reservePrice` | The minimum bid amount accepted by the auction contract for the current Timeboost auction, denominated in `_biddingToken`. | None |
+| `_minReservePrice` | A value that must be equal to or below the `reservePrice` to act as a "floor minimum" for Timeboost bids. Enforced by the auction contract. | 0.001 `WETH` |
+
## Troubleshooting and best practices
Our guide on [Troubleshooting Timeboost](/how-arbitrum-works/timeboost/troubleshoot-timeboost.mdx) provides more information on how response times work and how express lane transactions are sequenced, along with common errors and best practices for using Timeboost.
diff --git a/docs/how-arbitrum-works/timeboost/troubleshoot-timeboost.mdx b/docs/how-arbitrum-works/timeboost/troubleshoot-timeboost.mdx
index 65ec7985a1..82e65c7b5e 100644
--- a/docs/how-arbitrum-works/timeboost/troubleshoot-timeboost.mdx
+++ b/docs/how-arbitrum-works/timeboost/troubleshoot-timeboost.mdx
@@ -14,7 +14,7 @@ The express lane time advantage is currently set to 200ms, while the current blo
Express lane transactions are processed in the order of their `sequenceNumber`, which is a field in every express lane transaction. The `sequenceNumber` field is important because transactions with `sequenceNumber = n` can only be sequenced after all the transactions from `sequenceNumber = 0` to `sequenceNumber = n-1` have been sequenced. The first expected sequence number for a new round is zero and increments for each accepted transaction.
-There is a special "dontcare" sequence number (2^64 - 1) that can be used to indicate that you don't care about ordering of this express lane submission relative to others. Transactions with the "dontcare" sequence number will be sequenced right away without waiting for any other transactions. Note that normal nonce ordering within transactions for an account is still respected, so transactions from the same account will still be ordered by their nonce regardless of sequence number. The express lane controller can send `ExpressLaneSubmissions` with both "dontcare" and normal sequence numbers within the same round.
+There is a special "dontcare" sequence number (`2^64 - 1`) that can be used to indicate that you don't care about ordering of this express lane submission relative to others. Transactions with the "dontcare" sequence number will be sequenced right away without waiting for any other transactions. Note that normal nonce ordering within transactions for an account is still respected, so transactions from the same account will still be ordered by their nonce regardless of sequence number. The express lane controller can send `ExpressLaneSubmissions` with both "dontcare" and normal sequence numbers within the same round.
## How response times work
@@ -36,7 +36,7 @@ In this scenario, a `null` response is immediately returned after you send an ex
If the express lane controller decides to send a burst of transactions to the express lane with ascending values for the `sequenceNumber`, then the sequencer will attempt to process them in the order defined by the `sequenceNumber` (as explained above). However, if the transactions arrive out-of-order at the sequencer, then the transactions that do not have the expected `sequenceNumber` will be buffered (up to a limit) to be processed until the sequencer receives the transaction with the expected `sequenceNumber`. Once the sequencer receives the transaction with the expected `sequenceNumber`, then the sequencer will begin processing the buffered transaction with the next `sequenceNumber`. In other words, a transaction will only be sequenced into a block once transactions with the other, missing sequence numbers arrive to fill in the “gap” between the expected `sequencerNumber` and a given transaction’s `sequenceNumber`.
-A block-based timeout is applied to all express lane transactions, even those in the buffer, such that any transactions accepted (meaning `sequenceNumber` is consumed) by the sequencer will be dropped if they are not sequenced into a block within 5 blocks. This timeout can occur if the cummulative gas usage of transactions (express lane or otherwise) fill up 5 blocks worth of transactions _before_ all of the buffered express lane transactions are sequenced. No timeout error will be returned in this case and we recommend checking transaction receipts for confirmation on whether your transactions were sequenced into a block or not. Note that each Arbitrum block has a gas limit of 32 million gas and 1 Arbitrum block is produced every 250ms. This block-based timeout is likely to be reached before the limit on buffered transactions is hit in almost all cases.
+A block-based timeout is applied to all express lane transactions, even those in the buffer, such that any transactions accepted (meaning `sequenceNumber` is consumed) by the sequencer will be dropped if they are not sequenced into a block within five blocks. This timeout can occur if the cummulative gas usage of transactions (express lane or otherwise) fill up 5 blocks worth of transactions _before_ all of the buffered express lane transactions are sequenced. No timeout error will be returned in this case and we recommend checking transaction receipts for confirmation on whether your transactions were sequenced into a block or not. Note that each Arbitrum block has a gas limit of 32 million gas and 1 Arbitrum block is produced every 250ms. This block-based timeout is likely to be reached before the limit on buffered transactions is hit in almost all cases.
## Common error responses
diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/01-use-a-custom-gas-token-anytrust.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/01-use-a-custom-gas-token-anytrust.mdx
index 7d6c35c521..00b31b5e39 100644
--- a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/01-use-a-custom-gas-token-anytrust.mdx
+++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/01-use-a-custom-gas-token-anytrust.mdx
@@ -44,4 +44,4 @@ These methods use L1 to refer to the parent chain of the Arbitrum chain.
These parameter changes are strongly recommended to avoid charging users for a non-existent parent chain's base fee. The impact of not doing this is that Nitro will apply a parent chain's fee to all transactions. As Nitro assumes the native asset is `ETH`, all fees are expected to be denominated in `ETH`. This has the consequence of overcharging users for parent chain fees in native tokens that are more expensive than `ETH` (for example, if you use wrapped `BTC` as the custom gas token). In the case for tokens with prices much lower than `ETH`, the impact is far less pronounced.
-In either case we strongly recommend taking these steps to avoid any issues with chain economics. You can read more about how Nitro manages fees in [Gas and fees](/how-arbitrum-works/09-gas-fees.mdx).
+In either case we strongly recommend taking these steps to avoid any issues with chain economics. You can read more about how Nitro manages fees in [Gas and fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx).
diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/02-use-a-custom-gas-token-rollup.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/02-use-a-custom-gas-token-rollup.mdx
index 662c06358c..95429a7fa1 100644
--- a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/02-use-a-custom-gas-token-rollup.mdx
+++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/02-use-a-custom-gas-token-rollup.mdx
@@ -14,7 +14,7 @@ Custom gas token support for Rollups is currently limited to L2s that post data
:::
-When deploying an Arbitrum chain in [Rollup mode](/how-arbitrum-works/12-data-availability.mdx#rollup-mode), you can use a custom `ERC-20` token as the native gas token. This token is usable for Transaction fees on that specific Arbitrum chain and reimbursing the Batch poster for data posted to Ethereum. An example would be an L2 Rollup that uses `USDC` as its custom gas token but pays `ETH` to post data to L1 Ethereum.
+When deploying an Arbitrum chain in [Rollup mode](/run-arbitrum-node/data-availability.mdx#rollup-mode), you can use a custom `ERC-20` token as the native gas token. This token is usable for Transaction fees on that specific Arbitrum chain and reimbursing the Batch poster for data posted to Ethereum. An example would be an L2 Rollup that uses `USDC` as its custom gas token but pays `ETH` to post data to L1 Ethereum.
Enabling a custom fee token for a Rollup chain requires additional configuration compared to an [AnyTrust chain](/launch-arbitrum-chain/02-configure-your-chain/common-configurations/01-use-a-custom-gas-token-anytrust.mdx); it also introduces important exchange-rate considerations. This guide outlines specific implementation steps and operational considerations for chain owners or operators to consider when enabling a custom fee token for Rollups.
@@ -617,5 +617,5 @@ You can refer to the source files for more details on:
- [fee-token-pricers](https://github.com/OffchainLabs/nitro-contracts/tree/main/test/foundry/fee-token-pricers)
- [createERC20Rollup.ts](https://github.com/OffchainLabs/nitro-contracts/blob/main/scripts/createERC20Rollup.ts)
-You can also find more info about how Nitro manages [gas and fees](/how-arbitrum-works/09-gas-fees.mdx) here. If you’re unsure how to configure the Rollup correctly or have questions about fee pricer implementations, please get in touch with Offchain Labs or your chain’s deployment provider.
+You can also find more info about how Nitro manages [gas and fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx) here. If you’re unsure how to configure the Rollup correctly or have questions about fee pricer implementations, please get in touch with Offchain Labs or your chain’s deployment provider.
````
diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/07-fee-management.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/07-fee-management.mdx
index 39e8705492..875b3ec743 100644
--- a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/07-fee-management.mdx
+++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/07-fee-management.mdx
@@ -25,8 +25,8 @@ There are four fee types that are collected on every transaction of an Arbitrum
You can find more detailed information about these fee types in these pages:
-- [L2 fees](/how-arbitrum-works/09-gas-fees.mdx#child-chain-gas-pricing) for the Arbitrum chain base fee and surplus fee
-- [L1 fees](/how-arbitrum-works/09-gas-fees.mdx#parent-chain-gas-pricing) for the Parent chain base fee and surplus fee
+- [L2 fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx#child-chain-gas-pricing) for the Arbitrum chain base fee and surplus fee
+- [L1 fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx#parent-chain-gas-pricing) for the Parent chain base fee and surplus fee
## How to configure the fees collected?
diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/arbitrum-chain-finality.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/arbitrum-chain-finality.mdx
index 137a172032..1d94d7c4e9 100644
--- a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/arbitrum-chain-finality.mdx
+++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/arbitrum-chain-finality.mdx
@@ -9,11 +9,11 @@ content_type: how-to
## Child chain transactions
-Generally, transactions executed through the sequencer on Arbitrum chains [achieve finality](/how-arbitrum-works/02-transaction-lifecycle.mdx) equivalent to their parent chain once the relevant transaction data has been [posted in a batch](/how-arbitrum-works/05-validation-and-proving/02-rollup-protocol.mdx). This means that transactions on Arbitrum chains are considered final in minutes.
+Generally, transactions executed through the sequencer on Arbitrum chains [achieve finality](/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx) equivalent to their parent chain once the relevant transaction data has been [posted in a batch](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx). This means that transactions on Arbitrum chains are considered final in minutes.
## Parent chain → child chain transactions
-Messages being sent through the Delayed Inbox of a parent chain as [retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#retryable-tickets), including deposits through token bridges, are released by the [sequencer](/how-arbitrum-works/03-sequencer.mdx) once it has reasonable confidence of finality on the parent chain. For example, on an L2 chain settling to Ethereum, the sequencer will release delayed messages to the inbox after 40 blocks. Following this, the transaction must complete another finality period for the Ethereum transaction that prompted it to achieve finality.
+Messages being sent through the Delayed Inbox of a parent chain as [retryable tickets](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx#retryable-tickets), including deposits through token bridges, are released by the [sequencer](/how-arbitrum-works/deep-dives/sequencer.mdx) once it has reasonable confidence of finality on the parent chain. For example, on an L2 chain settling to Ethereum, the sequencer will release delayed messages to the inbox after 40 blocks. Following this, the transaction must complete another finality period for the Ethereum transaction that prompted it to achieve finality.
Arbitrum chain L3s may configure the finality of transactions executed through the Delayed Inbox to depend on different layers of finality. By default, Arbitrum chains will rely on the number of L1 block confirmations, effectively finalizing an L3 deposit as soon as L1 finalizes the batch posted by Arbitrum One or when a DACert is posted by Arbitrum Nova. This would be on the order of tens of minutes.
@@ -33,4 +33,4 @@ Note, however, that if you choose to enable fast bridging, a re-org of un-finali
## Child chain → parent chain transactions
-Normally, [outgoing transactions](/how-arbitrum-works/11-l2-to-l1-messaging.mdx) must wait until the assertion that includes their L2 message is confirmed (~one week) before a client can execute the message on L1. However, in the near future [AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx) chains will be able to leverage their DAC to enable fast confirmations of withdrawals through the native token bridge. By immediately confirming assertions that have been signed by the DAC, finality can be reduced to ~15 minutes.
+Normally, [outgoing transactions](/how-arbitrum-works/deep-dives/l2-to-l1-messaging.mdx) must wait until the assertion that includes their L2 message is confirmed (~one week) before a client can execute the message on L1. However, in the near future [AnyTrust](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) chains will be able to leverage their DAC to enable fast confirmations of withdrawals through the native token bridge. By immediately confirming assertions that have been signed by the DAC, finality can be reduced to ~15 minutes.
diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/bold-adoption-for-arbitrum-chains.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/bold-adoption-for-arbitrum-chains.mdx
index 69a13d393a..38e80b0192 100644
--- a/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/bold-adoption-for-arbitrum-chains.mdx
+++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common-configurations/bold-adoption-for-arbitrum-chains.mdx
@@ -70,7 +70,7 @@ Arbitrum BoLD is not an upgrade to a different type of proving architecture and
#### Use of your project's native token as the bonding asset to secure the chain
-Arbitrum BoLD enables the chain owner to use any `ERC-20` token on the parent chain as the bond for validators to participate in securing the network. By default, this token will be `WETH` for Arbitrum One and we do not recommend teams to use alternative tokens as the bonding asset. For more information on the rationale, we recommend teams consult our documentation to understand [why `WETH` was selected for Arbitrum One](/how-arbitrum-works/bold/gentle-introduction.mdx#q-why-is-arb-not-the-bonding-token-used-in-bold-on-arbitrum-one) (and not `ARB`).
+Arbitrum BoLD enables the chain owner to use any `ERC-20` token on the parent chain as the bond for validators to participate in securing the network. By default, this token will be `WETH` for Arbitrum One and we do not recommend teams to use alternative tokens as the bonding asset. For more information on the rationale, we recommend teams consult our documentation to understand [why `WETH` was selected for Arbitrum One](/how-arbitrum-works/bold/gentle-introduction.mdx#q-why-is-arb-not-the-bonding-token-used-for-bold-on-arbitrum-one) (and not `ARB`).
#### Increased censorship resistance for `L3` Arbitrum chains
@@ -115,7 +115,7 @@ As mentioned earlier, the upgrade to the dispute protocol involves both a Nitro
To read more about Arbitrum BoLD, please refer to the [Gentle Introduction for BoLD](../../../how-arbitrum-works/bold/gentle-introduction.mdx).
:::caution
-As mentioned in our guide on [BoLD adoption for Arbitrum chains](/launch-arbitrum-chain/02-configure-your-chain/common-configurations/bold-adoption-for-arbitrum-chains.mdx), the recommendation is to keep Arbitrum chains validation permissioned by having `disableValidatorWhitelist` be `false` (which is the default) and by having a list of validators on the allowlist via the `validators[]` array. Furthermore, we recommend keeping the [Censorship Timeout](../../../how-arbitrum-works/03-sequencer.mdx#censorship-timeout) feature disabled.
+As mentioned in our guide on [BoLD adoption for Arbitrum chains](/launch-arbitrum-chain/02-configure-your-chain/common-configurations/bold-adoption-for-arbitrum-chains.mdx), the recommendation is to keep Arbitrum chains validation permissioned by having `disableValidatorWhitelist` be `false` (which is the default) and by having a list of validators on the allowlist via the `validators[]` array. Furthermore, we recommend keeping the [Censorship Timeout](../../../how-arbitrum-works/deep-dives/sequencer.mdx#censorship-timeout) feature disabled.
:::
:::info This is not an ArbOS upgrade
diff --git a/docs/launch-arbitrum-chain/03-deploy-an-arbitrum-chain/07-canonical-factory-contracts.mdx b/docs/launch-arbitrum-chain/03-deploy-an-arbitrum-chain/07-canonical-factory-contracts.mdx
index 5f786b2390..175da50d9d 100644
--- a/docs/launch-arbitrum-chain/03-deploy-an-arbitrum-chain/07-canonical-factory-contracts.mdx
+++ b/docs/launch-arbitrum-chain/03-deploy-an-arbitrum-chain/07-canonical-factory-contracts.mdx
@@ -8,7 +8,7 @@ content_type: how-to
import { AddressExplorerLink as AEL } from '@site/src/components/AddressExplorerLink';
-Deploying new Arbitrum chains is usually done through a `RollupCreator` contract that processes the creation of the needed contracts and sends the initialization messages from the parent to the child chain. Similarly, creating a token bridge for an Arbitrum chain is usually done using a `TokenBridgeCreator` contract that creates the token bridge contracts in both the parent and child chains (this last one via [Parent-to-child messages](/how-arbitrum-works/10-l1-to-l2-messaging.mdx)).
+Deploying new Arbitrum chains is usually done through a `RollupCreator` contract that processes the creation of the needed contracts and sends the initialization messages from the parent to the child chain. Similarly, creating a token bridge for an Arbitrum chain is usually done using a `TokenBridgeCreator` contract that creates the token bridge contracts in both the parent and child chains (this last one via [Parent-to-child messages](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx)).
This page describes the benefits of using these canonical factory contracts and lists their addresses in all supported chains.
diff --git a/docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/03-state-growth.mdx b/docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/03-state-growth.mdx
index 85d58d9e59..7012fe4492 100644
--- a/docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/03-state-growth.mdx
+++ b/docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/03-state-growth.mdx
@@ -20,7 +20,7 @@ When we say ‘state size’, we mean the total amount of data recorded on the b
The state growth rate is simply the rate at which state size increases. A high state growth rate creates higher requirements for nodes to process state transitions and perform operations needed to keep up with the tip of the chain.
-The critical Nitro stack parameter affecting state growth and state growth rate is the **gas speed limit**. Offchain Labs has set the gas speed limit to a default (7,000,000 gas/s), ensuring a safe, sustained operating limit for Arbitrum chains. You can read more about the nuances of the gas speed limit [here](/how-arbitrum-works/09-gas-fees.mdx#the-speed-limit).
+The critical Nitro stack parameter affecting state growth and state growth rate is the **gas speed limit**. Offchain Labs has set the gas speed limit to a default (7,000,000 gas/s), ensuring a safe, sustained operating limit for Arbitrum chains. You can read more about the nuances of the gas speed limit [here](/how-arbitrum-works/deep-dives/gas-and-fees.mdx#the-speed-limit).
The default gas speed limit is designed to ensure Arbitrum chains operate performantly and sustainably.
diff --git a/docs/launch-arbitrum-chain/04-maintain-your-chain/06-monitoring-tools-and-considerations.mdx b/docs/launch-arbitrum-chain/04-maintain-your-chain/06-monitoring-tools-and-considerations.mdx
index b3382e7298..276b94a6e5 100644
--- a/docs/launch-arbitrum-chain/04-maintain-your-chain/06-monitoring-tools-and-considerations.mdx
+++ b/docs/launch-arbitrum-chain/04-maintain-your-chain/06-monitoring-tools-and-considerations.mdx
@@ -21,7 +21,7 @@ The Arbitrum chain (Orbit) Verification Script is currently under active develop
## Arbitrum chain (Orbit) retryables tracker
-[Retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx) are messages sent from a parent chain and executed on the Arbitrum chain. Due to their asynchronous nature (they are executed several minutes after being created), if insufficient funds are provided at the time of creation, they might not automatically redeem (execute) upon arrival at the Arbitrum chain. When this occurs, a manual redemption of the ticket is required. The [Arbitrum chain (Orbit) retryables tracker](https://github.com/OffchainLabs/Orbit-retryable-tracker) is designed to assist in identifying and displaying the status of retryable tickets sent from a parent chain to the Arbitrum chain, and it reports any tickets that have not been automatically redeemed.
+[Retryable tickets](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx) are messages sent from a parent chain and executed on the Arbitrum chain. Due to their asynchronous nature (they are executed several minutes after being created), if insufficient funds are provided at the time of creation, they might not automatically redeem (execute) upon arrival at the Arbitrum chain. When this occurs, a manual redemption of the ticket is required. The [Arbitrum chain (Orbit) retryables tracker](https://github.com/OffchainLabs/Orbit-retryable-tracker) is designed to assist in identifying and displaying the status of retryable tickets sent from a parent chain to the Arbitrum chain, and it reports any tickets that have not been automatically redeemed.
## Data Availability Server (DAS) health checks
diff --git a/docs/launch-arbitrum-chain/partials/_arbitrum-chain-public-preview-banner-partial.md b/docs/launch-arbitrum-chain/partials/_arbitrum-chain-public-preview-banner-partial.md
index 5eeb710d79..3b33fd052a 100644
--- a/docs/launch-arbitrum-chain/partials/_arbitrum-chain-public-preview-banner-partial.md
+++ b/docs/launch-arbitrum-chain/partials/_arbitrum-chain-public-preview-banner-partial.md
@@ -1,6 +1,6 @@
:::info PUBLIC PREVIEW, MAINNET READY
-Arbitrum chains are now [Mainnet ready](/launch-arbitrum-chain/concepts/public-preview-expectations#arbitrum-chain-is-mainnet-ready-but-deploy-to-testnet-first)! Note that Arbitrum is still a **[public preview](/launch-arbitrum-chain/concepts/public-preview-expectations)** capability - the Arbitrum product and its supporting documentation may change significantly as we capture feedback from readers like you.
+Arbitrum chains are now [Mainnet ready](/launch-arbitrum-chain/concepts/public-preview-expectations.mdx#arbitrum-chains-are-mainnet-ready-but-deploy-to-testnet-first)! Note that Arbitrum is still a **[public preview](/launch-arbitrum-chain/concepts/public-preview-expectations.mdx)** capability - the Arbitrum product and its supporting documentation may change significantly as we capture feedback from readers like you.
To provide feedback, click the _Request an update_ button at the top of this document, [join the Arbitrum Discord](https://discord.gg/arbitrum), or reach out to our team directly by completing [this form](http://bit.ly/3yy6EUK).
diff --git a/docs/partials/_bold-config-params.mdx b/docs/partials/_bold-config-params.mdx
index b9e8b96444..df748f4b76 100644
--- a/docs/partials/_bold-config-params.mdx
+++ b/docs/partials/_bold-config-params.mdx
@@ -26,8 +26,8 @@ last_reviewed: 2025-01-15
| `smallStepLeafSize` | Maximum number of steps in the "small step" level history committment. The product of `bigStepLeafSize`, `smallStepLeafSize`, and `numBigStepLevel` should equal to the maximum number of WAVM opcodes theoretically possible in the execution of an Arbitrum block, with a small buffer. It is not recommended to change this value. | 2^23 |
| `numBigStepLevel` | Number of "big step" levels. It is not recommended to change this value. | 1 |
| `maxDataSize` | Maximum size of data that can be posted onto the parent chain, in KB | `117964` for L2s, and `104857` for L3s |
-| `isDelayBufferable` | A parameter to enable or disable the delay buffer, otherwise known as the [Censorship Timeout](../how-arbitrum-works/03-sequencer.mdx#censorship-timeout) feature. | `false` |
-| `bufferConfig.max` | The maximum amount of time that the delay buffer can be. More information on how the delay buffer value changes over time and how it is used to calculate the force inclusion window can be found [here](../how-arbitrum-works/03-sequencer.mdx#censorship-timeout). | `2^32` - note that this configuration value is measured using Ethereum blocks for an L2 Arbitrum chain (settling to Ethereum) or an L3 Arbitrum chain settling to Arbitrum One or Arbitrum Nova. If the chain settles to a different type of parent chain, you must use its parent chain's `block.number` timing. It is recommended that you set this value to be higher than the batch posting frequency of your chain and ideally higher than the `bufferConfig.threshold` of your chain. |
+| `isDelayBufferable` | A parameter to enable or disable the delay buffer, otherwise known as the [Censorship Timeout](/how-arbitrum-works/deep-dives/sequencer.mdx#censorship-timeout) feature. | `false` |
+| `bufferConfig.max` | The maximum amount of time that the delay buffer can be. More information on how the delay buffer value changes over time and how it is used to calculate the force inclusion window can be found [here](/how-arbitrum-works/deep-dives/sequencer.mdx#censorship-timeout). | `2^32` - note that this configuration value is measured using Ethereum blocks for an L2 Arbitrum chain (settling to Ethereum) or an L3 Arbitrum chain settling to Arbitrum One or Arbitrum Nova. If the chain settles to a different type of parent chain, you must use its parent chain's `block.number` timing. It is recommended that you set this value to be higher than the batch posting frequency of your chain and ideally higher than the `bufferConfig.threshold` of your chain. |
| `bufferConfig.threshold` | The minimum amount of time that the force inclusion window can be reduced to, in the case of prolonged sequencer censorship and/or unexpected sequencer outages. The `delayBuffer`, starting from `bufferConfig.max`, is decremented by the difference between a delayed message's delay beyond `bufferConfig.threshold` so it is important to set the threshold to some value greater than the regular batch posting frequency of your chain and also greater than `delayBlocks` on your chain | `2^32` - note that this configuration value is measured using Ethereum blocks for an L2 Arbitrum chain (settling to Ethereum) or an L3 Arbitrum chain settling to Arbitrum One or Arbitrum Nova. If the chain settles to a different type of parent chain, you must use its parent chain's `block.number` timing. It is recommended that you set this value to be higher than batch posting frequency of your chain, but lower than the `delayBlocks` of your chain. |
| `bufferConfig.replenishRateInBasis` | The rate at which the delay buffer will replenish linearly | 500 (or 5% replenishment rate), meaning that one minute will be replenished for every 20 minutes where there are no messages delayed beyond `bufferConfig.threshold` |
| `validators` | An array of addresses that are allowed to post assertions to the parent chain, when BoLD is in permissioned mode (i.e., when `disableValidatorWhitelist` is `false`) | The list of whitelisted validators allowed to progress the chain (by regularly posting assertions to the parent chain) |
diff --git a/docs/partials/_gentle-intro-partial.mdx b/docs/partials/_gentle-intro-partial.mdx
index 2175a91deb..1b4475a344 100644
--- a/docs/partials/_gentle-intro-partial.mdx
+++ b/docs/partials/_gentle-intro-partial.mdx
@@ -10,7 +10,7 @@ import ImageZoom from '@site/src/components/ImageZoom';
#### Q: Hello! What's Arbitrum?
-Hi! Arbitrum is a technology suite designed to scale Ethereum. You can use Arbitrum chains to do all things you do on Ethereum — use Web3 apps, deploy smart contracts, etc., but your transactions will be cheaper and faster. Our flagship product — Arbitrum Rollup — is an Optimistic rollup protocol that inherits Ethereum-level security.
+Hi! Arbitrum is a technology suite designed to scale Ethereum. You can use Arbitrum chains to do all things you do on Ethereum—use Web3 apps, deploy smart contracts, etc., but your transactions will be cheaper and faster. Our flagship product—Arbitrum Rollup—is an Optimistic rollup protocol that inherits Ethereum-level security.
#### Q: What, what’s “Ethereum”? What's a “smart contract”? Where am I?
@@ -39,7 +39,7 @@ Yes, indeed we can be. This is where the “rollup” part comes in. The data th
#### Q: Who actually does this work (of checking for fraud, proving it, etc?)
-The parties who move the Arbitrum chain state forward on L1 — i.e., making claims about the chain’s state, disputing other’s claims, etc. — are called validators.
+The parties who move the Arbitrum chain state forward on L1 — i.e., making claims about the chain’s state, disputing other’s claims, etc.—are called validators.
In practice, we don’t expect the average Arbitrum user to be interested in running a
validator, just like the average Ethereum user typically doesn’t run their own layer 1 staking node. The crucial property, however, is that anybody can; becoming an Arbitrum validator requires no special permission ([once the allowlist is lifted](https://docs.arbitrum.foundation/state-of-progressive-decentralization)), only that a user runs the [open source validator software](https://github.com/OffchainLabs/nitro) (and bonds `ETH` when/if they need to take action).
@@ -47,7 +47,7 @@ Additionally, as long as there’s even just one honest validator, the chain wil
#### Q: And how exactly is “fraud” “proven”? Sounds complicated.
-Oh, it’s not so bad. In essence, if two validators disagree, only one of them (at most) can be telling the truth. In a dispute, the two validators play an interactive, call-and-response game in which they narrow down their dispute to a single computational step (think of something small and simple, like multiplying two numbers). This one step gets executed on L1 and will necessarily prove that the honest party was telling the truth. For a more detailed rundown, see [here](/how-arbitrum-works/05-validation-and-proving/01-validation-and-proving.mdx).
+Oh, it’s not so bad. In essence, if two validators disagree, only one of them (at most) can be telling the truth. In a dispute, the two validators play an interactive, call-and-response game in which they narrow down their dispute to a single computational step (think of something small and simple, like multiplying two numbers). This one step gets executed on L1 and will necessarily prove that the honest party was telling the truth. For a more detailed rundown, see [here](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx).
#### Q: This dispute game obviously takes some time; does this impose any sort of delay on Arbitrum users' transactions?
@@ -63,7 +63,7 @@ For one, Arbitrum transactions are submitted on the L1 in batches; typically, a
We really meant it, yes.
Different layer 2 protocols emphasize and optimize for different things; Arbitrum was created with Ethereum compatibility as a top priority. This means users can use Arbitrum with all their favorite Ethereum wallets; developers can build and deploy contracts with all their favorite Ethereum libraries and tooling; in fact, most of the time, the experience of using Arbitrum will feel identical to that of using Ethereum (with the important exception of it being much cheaper and faster).
-Much development went into achieving this level of Ethereum compatibility. But at its core: the Arbitrum itself uses a fork of [Geth](/how-arbitrum-works/04-state-transition-function/04-modified-geth-on-arbitrum.mdx) — the most widely used Ethereum implementation — with modifications to transform it into a trustless layer 2. This means most of the code running in Arbitrum is identical to the code running in Ethereum. We call this cutting-edge approach Nitro (developers can see the codebase [here](https://github.com/OffchainLabs/nitro)).
+Much development went into achieving this level of Ethereum compatibility. But at its core: the Arbitrum itself uses a fork of [Geth](/how-arbitrum-works/deep-dives/geth.mdx) — the most widely used Ethereum implementation — with modifications to transform it into a trustless layer 2. This means most of the code running in Arbitrum is identical to the code running in Ethereum. We call this cutting-edge approach Nitro (developers can see the codebase [here](https://github.com/OffchainLabs/nitro)).
#### Q: So builders can do all the stuff they do on Ethereum on Arbitrum, nice! But can they do _more_?
diff --git a/docs/partials/_glossary-partial.mdx b/docs/partials/_glossary-partial.mdx
index 668eb36f26..b7cadaa4b3 100644
--- a/docs/partials/_glossary-partial.mdx
+++ b/docs/partials/_glossary-partial.mdx
@@ -87,6 +87,12 @@ Arbitrum's "operating system" that trustlessly handles system-level operations;
A bonded claim made by an Arbitrum [Validator](/intro/glossary#validator) representing a claim about an Arbitrum chain's state. An [Assertion](/intro/glossary#assertion) may, e.g., propose a new assertion, or may be a step in a [Challenge](/intro/glossary#challenge).
+Assertions can have different states:
+
+- **Proposed**: When a validator submits an assertion
+- **Challenged**: If another validator disputes the assertion, an interactive fraud-proof initiates.
+- **Confirmed**: An assertion becomes final if no one challenges it within the dispute window (6.4 days).
+
### Auction Contract {#auction-contract}
A smart contract that handles the state, accounting of funds for bids, and various operations of the [Timeboost](/intro/glossary#timeboost) auction. The contract is deployed on the target chain for which Timeboost is enabled.
@@ -182,6 +188,16 @@ A [Validator](/intro/glossary#validator) that watches an Arbitrum chain and take
A contract that holds [Parent chain](/intro/glossary#parent-chain) initiated messages to be eventually included in the [Sequencer Inbox](/intro/glossary#sequencer). Inclusion of messages doesn't depend on the [Sequencer](/intro/glossary#sequencer).
+### Deterministic proving {#deterministic-proving}
+
+If challenged, state transitions are replayable and verified onchain.
+
+To achieve this, Arbitrum compiles the State Transition Function (STF) into different formats:
+
+- **Execution mode**: Uses Go's native compiler for high-performance execution on validator nodes.
+
+- **Proving mode**: Compiles to WebAssembly (WASM), which transforms into WebAssembly for Arbitrum Virtual Machine (WAVM) for fraud-proof verification.
+
### Dev-Tools Dashboard {#devtools-dashboard}
Web application built and maintained by [Offchain Labs](/intro/glossary#offchain-labs) for developers and users to debug Arbitrum transactions; i.e., executing or checking the status of [Cross-chain messages](/intro/glossary#crosschain-message); visit it [here](https://retryable-dashboard.arbitrum.io/).
@@ -198,6 +214,10 @@ A software application used for transacting with the Ethereum [Blockchain](/intr
The paradigm introduced by [Stylus](/intro/glossary#stylus) in which Arbitrum's EVM compatibility is preserved while new features and improvements are introduced.
+### Execution claim {#execution-claim}
+
+A cryptographic commitment to the computed state.
+
### Express Lane {#express-lane}
A component of [Timeboost](/intro/glossary#timeboost), the express lane is a special endpoint on the [Sequencer](/intro/glossary#sequencer) that immediately sequences incoming, valid transactions signed by the current express lane controller.
@@ -286,10 +306,18 @@ A parent chain contract responsible for tracking [Child to parent chain Message]
EVM compatible chain that acts as the settlement layer for one or more Arbitrum Chains (aka [Child chain](/intro/glossary#child-chain) ). E.g., Ethereum is the parent chain of both Arbitrum One and Arbitrum Nova. Parent chain is synonymous with "underlying chain."
+### Permissionless validation {#permissionless-validation}
+
+Anyone can become a validator by running an Arbitrum node, without permission.
+
### Portal {#portal}
A web application maintained by [Offchain Labs](/intro/glossary#offchain-labs) showcasing the Arbitrum ecosystem; visit it [here](https://portal.arbitrum.io/).
+### Predecessor Assertion {#predecessor-assertion}
+
+The last confirmed valid state of the chain.
+
### raas {#raas}
RaaS (Rollup as a Service) is a platform that provides the necessary infrastructure and tools to deploy and operate blockchain Rollups, eliminating the need for teams to build the underlying technical infrastructure themselves. It typically includes pre-built Rollup software, node hosting, data availability solutions, and monitoring tools, allowing developers to focus on their application logic rather than the complex technical implementation of Rollup technology.
@@ -356,7 +384,7 @@ An token contract on an Arbitrum chain deployed via the [`StandardERC20` gateway
### State Transition Function {#state-transition-function}
-The STF (State Transition Function) defines how new blocks are produced from input messages (i.e., transactions) in an Arbitrum chain.
+The STF (State Transition Function) defines how new blocks are produced from input messages (i.e., transactions) in an Arbitrum chain. The State Transition Function's output is the result of applying those input messages (transactions).
### Stylus {#stylus}
@@ -384,6 +412,12 @@ In the context of Ethereum, trustless refers to the ability of a system to opera
This is achieved through the use of cryptographic techniques and decentralized consensus mechanisms that let users verify the integrity of network transactions using open-source software. Trustless systems are considered to be more secure and resistant to fraud or tampering because they don't rely on a single point of failure that can be exploited by attackers.
+### Trustless verification {#trustless-verification}
+
+#### Trustless verification
+
+Validators confirm assertions, ensuring transactions adhere to the protocol rules.
+
### Underlying Chain {#underlying-chain}
Synonymous with [Parent chain](/intro/glossary#parent-chain).
diff --git a/docs/partials/glossary/_assertion.mdx b/docs/partials/glossary/_assertion.mdx
index 70de7a5ec9..6eae013d60 100644
--- a/docs/partials/glossary/_assertion.mdx
+++ b/docs/partials/glossary/_assertion.mdx
@@ -5,3 +5,9 @@ titleforSort: Assertion
---
A bonded claim made by an Arbitrum [Validator](/intro/glossary#validator) representing a claim about an Arbitrum chain's state. An [Assertion](/intro/glossary#assertion) may, e.g., propose a new assertion, or may be a step in a [Challenge](/intro/glossary#challenge).
+
+Assertions can have different states:
+
+- **Proposed**: When a validator submits an assertion
+- **Challenged**: If another validator disputes the assertion, an interactive fraud-proof initiates.
+- **Confirmed**: An assertion becomes final if no one challenges it within the dispute window (6.4 days).
diff --git a/docs/partials/glossary/_deterministic-proving.mdx b/docs/partials/glossary/_deterministic-proving.mdx
new file mode 100644
index 0000000000..95b8070318
--- /dev/null
+++ b/docs/partials/glossary/_deterministic-proving.mdx
@@ -0,0 +1,13 @@
+---
+title: Deterministic proving
+key: deterministic-proving
+titleforSort: Deterministic proving
+---
+
+If challenged, state transitions are replayable and verified onchain.
+
+To achieve this, Arbitrum compiles the State Transition Function (STF) into different formats:
+
+- **Execution mode**: Uses Go's native compiler for high-performance execution on validator nodes.
+
+- **Proving mode**: Compiles to WebAssembly (WASM), which transforms into WebAssembly for Arbitrum Virtual Machine (WAVM) for fraud-proof verification.
diff --git a/docs/partials/glossary/_execution-claim.mdx b/docs/partials/glossary/_execution-claim.mdx
new file mode 100644
index 0000000000..7908fdae8c
--- /dev/null
+++ b/docs/partials/glossary/_execution-claim.mdx
@@ -0,0 +1,7 @@
+---
+title: Execution claim
+key: execution-claim
+titleforSort: Execution claim
+---
+
+A cryptographic commitment to the computed state.
diff --git a/docs/partials/glossary/_permissionless_validation.mdx b/docs/partials/glossary/_permissionless_validation.mdx
new file mode 100644
index 0000000000..6ccb5df02e
--- /dev/null
+++ b/docs/partials/glossary/_permissionless_validation.mdx
@@ -0,0 +1,7 @@
+---
+title: Permissionless validation
+key: permissionless-validation
+titleforSort: Permissionless validation
+---
+
+Anyone can become a validator by running an Arbitrum node, without permission.
diff --git a/docs/partials/glossary/_predecessor-assertion.mdx b/docs/partials/glossary/_predecessor-assertion.mdx
new file mode 100644
index 0000000000..abdbca910a
--- /dev/null
+++ b/docs/partials/glossary/_predecessor-assertion.mdx
@@ -0,0 +1,7 @@
+---
+title: Predecessor Assertion
+key: predecessor-assertion
+titleforSort: predecessor-assertion
+---
+
+The last confirmed valid state of the chain.
diff --git a/docs/partials/glossary/_state-transition-function.mdx b/docs/partials/glossary/_state-transition-function.mdx
index 3b1666f921..1be4fb3584 100644
--- a/docs/partials/glossary/_state-transition-function.mdx
+++ b/docs/partials/glossary/_state-transition-function.mdx
@@ -4,4 +4,4 @@ key: state-transition-function
titleforSort: State Transition Function
---
-The STF (State Transition Function) defines how new blocks are produced from input messages (i.e., transactions) in an Arbitrum chain.
+The STF (State Transition Function) defines how new blocks are produced from input messages (i.e., transactions) in an Arbitrum chain. The State Transition Function's output is the result of applying those input messages (transactions).
diff --git a/docs/partials/glossary/_trustless-verification.mdx b/docs/partials/glossary/_trustless-verification.mdx
new file mode 100644
index 0000000000..372e22fe21
--- /dev/null
+++ b/docs/partials/glossary/_trustless-verification.mdx
@@ -0,0 +1,9 @@
+---
+title: Trustless verification
+key: trustless-verification
+titleforSort: Trustless verification
+---
+
+#### Trustless verification
+
+Validators confirm assertions, ensuring transactions adhere to the protocol rules.
diff --git a/docs/run-arbitrum-node/arbos-releases/01-overview.mdx b/docs/run-arbitrum-node/arbos-releases/01-overview.mdx
index e237ad6107..5db55b5bbd 100644
--- a/docs/run-arbitrum-node/arbos-releases/01-overview.mdx
+++ b/docs/run-arbitrum-node/arbos-releases/01-overview.mdx
@@ -27,7 +27,7 @@ import PublicPreviewBannerPartial from '../../node-running/partials/_upgrade-cad
ArbOS upgrades are carried out by the chain's owner; in the case of Arbitrum One and Nova, the owner is the Arbitrum DAO and so an upgrade will require a governance proposal and vote to pass to complete the upgrade. [This is an example of a Nitro release that contains an ArbOS version bump, specifically to ArbOS 11](https://github.com/OffchainLabs/nitro/releases/tag/v2.2.0).
-Visit [How Arbitrum works](/how-arbitrum-works/01-a-gentle-introduction.mdx) to learn more about Nitro's architecture; more information about ArbOS software releases is available on [the Arbitrum DAO forum](https://forum.arbitrum.foundation/t/arbitrum-arbos-upgrades/19695).
+Visit [How Arbitrum works](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx) to learn more about Nitro's architecture; more information about ArbOS software releases is available on [the Arbitrum DAO forum](https://forum.arbitrum.foundation/t/arbitrum-arbos-upgrades/19695).
## List of available ArbOS releases
diff --git a/docs/run-arbitrum-node/arbos-releases/arbos11.mdx b/docs/run-arbitrum-node/arbos-releases/arbos11.mdx
index e15831d778..9a1e158cd5 100644
--- a/docs/run-arbitrum-node/arbos-releases/arbos11.mdx
+++ b/docs/run-arbitrum-node/arbos-releases/arbos11.mdx
@@ -22,7 +22,7 @@ Formal release notes can be found [here](https://github.com/OffchainLabs/nitro/r
- [EIP-3855: PUSH0 instruction](https://eips.ethereum.org/EIPS/eip-3855)
- [EIP-3860: Limit and meter initcode](https://eips.ethereum.org/EIPS/eip-3860)
- [EIP-6049: Deprecate SELFDESTRUCT](https://eips.ethereum.org/EIPS/eip-6049)
-- Improvements and fixes for [retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx) to ensure that the fee calculation to redeem retryable tickets will take into account both the infrastructure fee and the network fee. The infrastructure fee is the minimum child chain base fee only, while the network fee collects child chain congestion charges. This is important for [AnyTrust chains](/how-arbitrum-works/08-anytrust-protocol.mdx) like Arbitrum Nova because members of the Data Availability Committee (DAC) gets paid a percentage of the infrastructure fee but not the network fee. Previously, the calculations to determine the fee for redeeming retryable tickets did not consider the infrastructure fee.
+- Improvements and fixes for [retryable tickets](/how-arbitrum-works/deep-dives/l1-to-l2-messaging.mdx) to ensure that the fee calculation to redeem retryable tickets will take into account both the infrastructure fee and the network fee. The infrastructure fee is the minimum child chain base fee only, while the network fee collects child chain congestion charges. This is important for [AnyTrust chains](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) like Arbitrum Nova because members of the Data Availability Committee (DAC) gets paid a percentage of the infrastructure fee but not the network fee. Previously, the calculations to determine the fee for redeeming retryable tickets did not consider the infrastructure fee.
- Fixes an issue where the [`ArbOwnerPublic` precompile](/build-decentralized-apps/precompiles/02-reference.mdx#arbownerpublic) returned the incorrect list of chain owners. This does not change the parties who are able to perform chain owner actions. As intended, only the Arbitrum DAO is able to take chain owner actions for Arbitrum One and Nova.
- Resolves an issue where the [`arbBlockHash` method](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) would take up all the gas when reverting. The previous incorrect behavior meant that if a transaction calls `arbBlockHash` with an out-of-range block number, then the transaction would consume all the gas when reverting.
- Addition of the [`L1RewardReceipient`](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo) and [`L1RewardRate`](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo) precompile methods to view the parent chain pricing parameters and make it easier to view the current chain configuration.
diff --git a/docs/run-arbitrum-node/data-availability-committees/01-get-started.mdx b/docs/run-arbitrum-node/data-availability-committees/01-get-started.mdx
index 851435f8c5..f1de268bbe 100644
--- a/docs/run-arbitrum-node/data-availability-committees/01-get-started.mdx
+++ b/docs/run-arbitrum-node/data-availability-committees/01-get-started.mdx
@@ -15,7 +15,7 @@ content_type: overview
This section offers information and a series of how-to guides to help you along the process of setting up a Data Availability Committee. These guides target two audiences: Committee members who wish to deploy a Data Availability Server, and chain owners who wish to configure their chain with the information of the Committee.
-Before following the guides in this section, you should be familiar with how the AnyTrust protocol works and the role of the DAC in the protocol. Refer to the [AnyTrust Protocol](/how-arbitrum-works/08-anytrust-protocol.mdx) documentation to learn more.
+Before following the guides in this section, you should be familiar with how the AnyTrust protocol works and the role of the DAC in the protocol. Refer to the [AnyTrust Protocol](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) documentation to learn more.
## If you are a DAC member
diff --git a/docs/run-arbitrum-node/data-availability-committees/02-deploy-das.mdx b/docs/run-arbitrum-node/data-availability-committees/02-deploy-das.mdx
index db853f64e1..1f87154d54 100644
--- a/docs/run-arbitrum-node/data-availability-committees/02-deploy-das.mdx
+++ b/docs/run-arbitrum-node/data-availability-committees/02-deploy-das.mdx
@@ -22,7 +22,7 @@ For more information related to configuring a DAC, refer to the [Introduction](/
This how-to assumes that you're familiar with:
-- The DAC's role in the AnyTrust protocol. Refer to [Inside AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx) for a refresher.
+- The DAC's role in the AnyTrust protocol. Refer to [Inside AnyTrust](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) for a refresher.
- [Kubernetes](https://kubernetes.io/). The examples in this guide use Kubernetes to containerize your DAS.
## How does a DAS work?
@@ -427,7 +427,7 @@ After you decode a batch poster transaction and get its `data` within the functi
The first part (1 byte) is the `header flag`, which is used to specify which type of batch it is. Here we need to check if it has bit `0x80` (For example, `0x88` and `0x80` are both valid, but `0x55` is wrong).
-The second part (32 bytes) is the keyset hash. You can learn more about what keyset is [here](/how-arbitrum-works/08-anytrust-protocol.mdx#keysets).
+The second part (32 bytes) is the keyset hash. You can learn more about what keyset is [here](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx#keysets).
The third part (32 bytes) is the data hash, and this is what we need to retrieve data. When you get this hash, you can retrieve data directly by following what we demonstrate in Step 4.
diff --git a/docs/run-arbitrum-node/data-availability-committees/04-configure-dac.mdx b/docs/run-arbitrum-node/data-availability-committees/04-configure-dac.mdx
index 8711216756..e4dbb926f4 100644
--- a/docs/run-arbitrum-node/data-availability-committees/04-configure-dac.mdx
+++ b/docs/run-arbitrum-node/data-availability-committees/04-configure-dac.mdx
@@ -21,7 +21,7 @@ In this how-to, you'll learn how to configure the DAC in your chain. Refer to th
This how-to assumes that you're familiar with:
-- The DAC's role in the AnyTrust protocol. Refer to [Inside AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx) for a refresher.
+- The DAC's role in the AnyTrust protocol. Refer to [Inside AnyTrust](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) for a refresher.
- [Kubernetes](https://kubernetes.io/). The examples in this guide use Kubernetes to containerize your DAS.
- [How to deploy a Data Availability Server (DAS)](/run-arbitrum-node/data-availability-committees/02-deploy-das.mdx). This is needed to understand where the data we'll be handling in this guide comes from.
- The [Foundry toolkit](https://github.com/foundry-rs/foundry)
@@ -44,7 +44,7 @@ The AnyTrust protocol assumes that for the `n` members of the DAC, a minimum of
To perform this signing operation, each DAC member must generate their own set of BLS public and private keys. They should do this independently and ensure these keys are random and only used by them. You can find more information about how to generate a BLS pair of keys in [Generating BLS Keys](/run-arbitrum-node/data-availability-committees/deploy-das#step-1-generate-the-bls-keypair).
-An AnyTrust chain needs to know all DAC members' public keys to validate the integrity of the data being batched and posted. A _keyset_ is a list of all DAC members' RPC endpoint and BLS public key. Additionally, it also contains information about how many signatures are needed to approve a Data Availability Certificate (DACert), via a special `assumed-honest` parameter (i.e., the `h` parameter we mentioned above). This design lets the chain owner modify the DAC membership over time, and DAC members change their keys if needed. See [Inside AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx) for more information.
+An AnyTrust chain needs to know all DAC members' public keys to validate the integrity of the data being batched and posted. A _keyset_ is a list of all DAC members' RPC endpoint and BLS public key. Additionally, it also contains information about how many signatures are needed to approve a Data Availability Certificate (DACert), via a special `assumed-honest` parameter (i.e., the `h` parameter we mentioned above). This design lets the chain owner modify the DAC membership over time, and DAC members change their keys if needed. See [Inside AnyTrust](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx) for more information.
We use this keyset, and its hash to configure the `SequencerInbox` contract with the valid keyset, and also the batch poster (to request storing information) and full nodes (to request information already stored).
diff --git a/docs/how-arbitrum-works/12-data-availability.mdx b/docs/run-arbitrum-node/data-availability.mdx
similarity index 100%
rename from docs/how-arbitrum-works/12-data-availability.mdx
rename to docs/run-arbitrum-node/data-availability.mdx
diff --git a/docs/run-arbitrum-node/more-types/02-run-validator-node.mdx b/docs/run-arbitrum-node/more-types/02-run-validator-node.mdx
index e2650a53d8..b10c16d15c 100644
--- a/docs/run-arbitrum-node/more-types/02-run-validator-node.mdx
+++ b/docs/run-arbitrum-node/more-types/02-run-validator-node.mdx
@@ -13,7 +13,7 @@ This page describes the different strategies a validator may follow and provides
This how-to assumes that you're familiar with the following:
- How to run a full node (see instructions [here](/run-arbitrum-node/02-run-full-node.mdx))
-- [How the Rollup protocol works](/how-arbitrum-works/05-validation-and-proving/02-rollup-protocol.mdx)
+- [How the Rollup protocol works](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx)
- [How BoLD works](/how-arbitrum-works/bold/bold-technical-deep-dive.mdx#how-bold-uses-ethereum), if you're running a validator for a chain that has BoLD activated
## Validation strategies
diff --git a/docs/stylus/concepts/how-it-works.md b/docs/stylus/concepts/how-it-works.md
index b4136c1c71..540a573998 100644
--- a/docs/stylus/concepts/how-it-works.md
+++ b/docs/stylus/concepts/how-it-works.md
@@ -53,9 +53,9 @@ EVM contracts continue to execute the same way they were before Stylus. When cal
Nitro operates in two modes: a "happy case" where it compiles execution history to native code, and a "sad case" during validator disputes, where it compiles execution history to WASM for interactive fraud proofs on Ethereum. Stylus builds on Nitro's fraud-proving technology, allowing it to verify both execution history and WASM programs deployed by developers.
-Stylus is made possible by Nitro’s ability to replay and verify disputes using WASM. Validators bisect disputes until an invalid step is identified and proven onchain through a [“one-step proof.”](/how-arbitrum-works/05-validation-and-proving/03-proving-and-challenges.mdx#simplified-bisection-protocol). This deterministic fraud-proving capability ensures the correctness of any arbitrary program compiled to WASM. The combination of WASM's and Nitro's properties enables this technological leap we call Stylus.
+Stylus is made possible by Nitro’s ability to replay and verify disputes using WASM. Validators bisect disputes until an invalid step is identified and proven onchain through a [“one-step proof.”](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx#dissection-protocol-simplified-version). This deterministic fraud-proving capability ensures the correctness of any arbitrary program compiled to WASM. The combination of WASM's and Nitro's properties enables this technological leap we call Stylus.
-For more details on Nitro’s architecture, refer to the [documentation](/how-arbitrum-works/01-a-gentle-introduction.mdx) or the [Nitro whitepaper](https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf).
+For more details on Nitro’s architecture, refer to the [documentation](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx) or the [Nitro whitepaper](https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf).
## Why does this matter?
@@ -79,4 +79,4 @@ Stylus doesn't just improve on cost and speed. WASM programs are also safer. Ree
### Fully interoperable
-Solidity programs and WASM programs are completely composable. If working in Solidity, a developer can call a Rust program or rely on another dependency in a different language. If working in Rust, all Solidity functionalities are accessible out of the box.
+Solidity programs and WASM programs are completely composable. If working in Solidity, a developer can call a Rust program or rely on another dependency in a different language. If working in Rust, all Solidity functionalities are accessible out of the box.gas-
diff --git a/docusaurus.config.js b/docusaurus.config.js
index eacc8adac4..cbfda05052 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -136,6 +136,7 @@ const config = {
invalidLink: true,
notDocumented: true,
},
+ skipErrorChecking: true,
logLevel: 'Verbose',
sidebar: {
autoConfiguration: false,
diff --git a/i18n/ja/docusaurus-plugin-content-docs/current.json b/i18n/ja/docusaurus-plugin-content-docs/current.json
index 10191d9853..7c0e646734 100644
--- a/i18n/ja/docusaurus-plugin-content-docs/current.json
+++ b/i18n/ja/docusaurus-plugin-content-docs/current.json
@@ -540,7 +540,7 @@
},
"sidebar.getStartedSidebar.link.How Arbitrum works": {
"message": "How Arbitrum works",
- "description": "The label for link How Arbitrum works in sidebar getStartedSidebar, linking to /how-arbitrum-works/a-gentle-introduction"
+ "description": "The label for link How Arbitrum works in sidebar getStartedSidebar, linking to /how-arbitrum-works/inside-arbitrum-nitro"
},
"sidebar.getStartedSidebar.link.Run an Arbitrum (Orbit) chain": {
"message": "Run an Arbitrum (Orbit) chain",
diff --git a/sidebars.js b/sidebars.js
index 4c33e9e64e..b502e7c9ad 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -72,7 +72,7 @@ const sidebars = {
{
type: 'link',
label: 'How Arbitrum works',
- href: '/how-arbitrum-works/a-gentle-introduction',
+ href: '/how-arbitrum-works/inside-arbitrum-nitro',
},
{
type: 'html',
@@ -516,6 +516,11 @@ const sidebars = {
id: 'run-arbitrum-node/l1-ethereum-beacon-chain-rpc-providers',
label: 'L1 Ethereum RPC providers',
},
+ {
+ type: 'doc',
+ id: 'run-arbitrum-node/data-availability',
+ label: 'Data Availability',
+ },
{
type: 'doc',
id: 'run-arbitrum-node/run-feed-relay',
@@ -728,107 +733,65 @@ const sidebars = {
items: [
{
type: 'doc',
- id: 'how-arbitrum-works/a-gentle-introduction',
- label: 'A gentle introduction',
- },
- {
- type: 'doc',
- id: 'how-arbitrum-works/transaction-lifecycle',
- label: 'Sequencing, Followed by Deterministic Execution',
- },
- {
- type: 'doc',
- id: 'how-arbitrum-works/sequencer',
- label: 'The Sequencer and Censorship Resistance',
+ id: 'how-arbitrum-works/inside-arbitrum-nitro',
+ label: 'Inside Arbitrum Nitro',
},
{
- type: 'doc',
- id: 'how-arbitrum-works/l1-to-l2-messaging',
- label: 'Parent to Child chain messaging',
+ type: 'link',
+ href: 'https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf',
+ label: 'Nitro whitepaper',
},
{
type: 'category',
- label: 'State Transition Function',
+ label: 'Deep dives',
items: [
{
type: 'doc',
- label: 'STF Overview',
- id: 'how-arbitrum-works/state-transition-function/stf-gentle-intro',
+ label: 'AnyTrust',
+ id: 'how-arbitrum-works/deep-dives/anytrust-protocol',
},
{
type: 'doc',
- label: 'STF inputs',
- id: 'how-arbitrum-works/state-transition-function/stf-inputs',
+ label: 'Assertions',
+ id: 'how-arbitrum-works/deep-dives/assertions',
},
{
type: 'doc',
- label: 'Ethereum vs Arbitrum',
- id: 'how-arbitrum-works/state-transition-function/ethereum-vs-arbitrum',
+ label: 'L1 to L2 Messaging',
+ id: 'how-arbitrum-works/deep-dives/l1-to-l2-messaging',
},
{
type: 'doc',
- label: 'Modified Geth on Arbitrum',
- id: 'how-arbitrum-works/state-transition-function/modified-geth-on-arbitrum',
+ label: 'L2 to L1 Messaging',
+ id: 'how-arbitrum-works/deep-dives/l2-to-l1-messaging',
},
{
type: 'doc',
- label: 'ArbOS',
- id: 'how-arbitrum-works/state-transition-function/arbos',
+ label: 'Geth',
+ id: 'how-arbitrum-works/deep-dives/geth',
},
{
type: 'doc',
- label: 'Stylus execution path',
- id: 'how-arbitrum-works/state-transition-function/stylus-execution-path',
+ label: 'Sequencer',
+ id: 'how-arbitrum-works/deep-dives/sequencer',
},
- ],
- },
- {
- type: 'category',
- label: 'Validation and Proving',
- items: [
{
type: 'doc',
- label: 'Validation and proving overview',
- id: 'how-arbitrum-works/validation-and-proving/validation-and-proving',
+ label: 'STF inputs',
+ id: 'how-arbitrum-works/deep-dives/stf-inputs',
},
{
type: 'doc',
- label: 'Rollup protocol',
- id: 'how-arbitrum-works/validation-and-proving/rollup-protocol',
+ label: 'Transaction lifecycle',
+ id: 'how-arbitrum-works/deep-dives/transaction-lifecycle',
},
{
type: 'doc',
- label: 'Proving and challenges',
- id: 'how-arbitrum-works/validation-and-proving/proving-and-challenges',
+ label: 'Gas and fees',
+ id: 'how-arbitrum-works/deep-dives/gas-and-fees',
},
],
},
- {
- type: 'doc',
- id: 'how-arbitrum-works/anytrust-protocol',
- label: 'AnyTrust protocol',
- },
- {
- type: 'doc',
- id: 'how-arbitrum-works/l2-to-l1-messaging',
- label: 'Child to parent chain messaging',
- },
- {
- type: 'doc',
- id: 'how-arbitrum-works/gas-fees',
- label: 'Gas and fees',
- },
- {
- type: 'doc',
- id: 'how-arbitrum-works/data-availability',
- label: 'Data Availability',
- },
- {
- type: 'link',
- href: 'https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf',
- label: 'Nitro whitepaper',
- },
-
{
type: 'category',
label: 'The BoLD dispute protocol',
diff --git a/static/bridging-faqs.json b/static/bridging-faqs.json
index b38ab1c9bc..2f8c42aa0d 100644
--- a/static/bridging-faqs.json
+++ b/static/bridging-faqs.json
@@ -1,8 +1,32 @@
[
-{"question": "How do I move assets between One and Nova?","answer": "Both Arbitrum One and Arbitrum Nova run as layers on top of Ethereum. Thus, you can always move assets between the two chains in two steps by going \"through\" Ethereum. In other words: withdraw your assets from Arbitrum One to Ethereum and then deposit them onto Nova, or conversely, withdraw your assets from Nova to Ethereum and then deposit them to Arbitrum One. You can complete these steps using the [Arbitrum Bridge](https://bridge.arbitrum.io/). \n\n\n\n","key": "how-do-i-move-assets-between-one-and-nova"},
-{"question": "What fees do I have to pay when bridging funds from L1 to L2?","answer": "When bridging over tokens from L1 to L2, you will have to sign one or two transactions with their corresponding fees:\n\n1. If you are bridging a token for the first time, you'll sign one **approval transaction**.\n2. In all cases, you'll sign a **deposit transaction** that will send your tokens to the Bridge.\nPlease note that the approval transaction needs to be executed at least once per token and wallet. This approval means that if you bridge the same token from the same wallet again, you probably won't have to pay for that transaction. However, if you bridge the same token from a different wallet, you will have to pay for that transaction again.\n\nIn any case, the Bridge and your wallet will guide you through the process, showing the transaction(s) that you need to sign to have your tokens bridged to Arbitrum.\n\n","key": "what-fees-do-i-have-to-pay-when-bridging-funds-from-l1-to-l2"},
-{"question": "How long does it take before I receive my funds when I initiate a withdrawal from Arbitrum chains (One and Nova)?","answer": "Using the official Arbitrum Bridge, the process will take *roughly* one week. However, some users opt to use third-party fast bridges, which often bypass this delay (remember that these bridges are created and maintained by third parties, so please DYOR!).\n\nThere's some variability in the exact wall-clock time of the dispute window, plus there's some expected additional \"padding\" time on both ends (no more than about an hour, typically).\n\nThe variability of the dispute window comes from the slight variance of block times. Arbitrum One's dispute window is 45818 blocks; this converts to about 6.5 days, assuming slightly more than 12 seconds per block, the average block time of Ethereum.\n\nThe \"padding on both ends\" involves three events that have to occur between a client receiving their transaction receipt from the Sequencer and their child-to-parent chain message being executable. After getting their receipt,\n\n1. The sequencer posts their transaction in a batch (usually within a few minutes, though the sequencer will wait a bit longer if the parent chain is congested). Then,\n2. A validator includes their transaction in an assertion (usually within the hour). Then, after the ~week long dispute window passes, the assertion is confirmable, and\n3. Somebody (anybody) confirms the assertion on the parent chain (usually within ~15 minutes).\nAdditionally, in the rare and unlikely event of a dispute, this delay period will be extended for the dispute to resolve.\n\n","key": "how-long-does-it-take-before-i-receive-my-funds-when-i-initiate-a-withdrawal-from-arbitrum-chains-one-and-nova"},
-{"question": "Is there a way to cancel a withdrawal from Arbitrum?","answer": "Once initiated, it is not possible to cancel a withdrawal. However, you can claim your funds on L1 and deposit them again on L2 once the [withdrawal period](https://docs.arbitrum.io/learn-more/faq#why-was-one-week-chosen-for-arbitrum-ones-dispute-window) is past.\n\n\n\n","key": "is-there-a-way-to-cancel-a-withdrawal-from-arbitrum"},
-{"question": "Can I use a smart contract wallet in the bridge?","answer": "Support for Smart Contract Wallets is currently limited to token deposits and withdrawals. Keep in mind that when withdrawing funds, you won't be able to claim them on L1 using the [bridge](https://bridge.arbitrum.io/) (unless you also control that address on L1). In that case, you can use the [cross-chain dashboard](https://retryable-dashboard.arbitrum.io/tx) to claim your funds on L1.\n\n`ETH` deposits and withdrawals using a Smart Contract Wallet are currently not supported, but will be available soon.\n\n","key": "can-i-use-a-smart-contract-wallet-in-the-bridge"},
-{"question": "How can I claim withdrawn funds if I don't control on L1 the address that initiated the transaction on L2?","answer": "Once the [withdrawal period](https://docs.arbitrum.io/learn-more/faq#why-was-one-week-chosen-for-arbitrum-ones-dispute-window) is past, you can use the [cross-chain dashboard](https://retryable-dashboard.arbitrum.io/tx) to execute the message on L1. Paste the transaction hash that initiated the withdrawal on L2, and follow the process described in the dashboard.\n\n\n\n","key": "how-can-i-claim-withdrawn-funds-if-i-dont-control-on-l1-the-address-that-initiated-the-transaction-on-l2"}
-]
\ No newline at end of file
+ {
+ "question": "How do I move assets between One and Nova?",
+ "answer": "Both Arbitrum One and Arbitrum Nova run as layers on top of Ethereum. Thus, you can always move assets between the two chains in two steps by going \"through\" Ethereum. In other words: withdraw your assets from Arbitrum One to Ethereum and then deposit them onto Nova, or conversely, withdraw your assets from Nova to Ethereum and then deposit them to Arbitrum One. You can complete these steps using the [Arbitrum Bridge](https://bridge.arbitrum.io/). \n\n\n\n",
+ "key": "how-do-i-move-assets-between-one-and-nova"
+ },
+ {
+ "question": "What fees do I have to pay when bridging funds from L1 to L2?",
+ "answer": "When bridging over tokens from L1 to L2, you will have to sign one or two transactions with their corresponding fees:\n\n1. If you are bridging a token for the first time, you'll sign one **approval transaction**.\n2. In all cases, you'll sign a **deposit transaction** that will send your tokens to the Bridge.\nPlease note that the approval transaction needs to be executed at least once per token and wallet. This approval means that if you bridge the same token from the same wallet again, you probably won't have to pay for that transaction. However, if you bridge the same token from a different wallet, you will have to pay for that transaction again.\n\nIn any case, the Bridge and your wallet will guide you through the process, showing the transaction(s) that you need to sign to have your tokens bridged to Arbitrum.\n\n",
+ "key": "what-fees-do-i-have-to-pay-when-bridging-funds-from-l1-to-l2"
+ },
+ {
+ "question": "How long does it take before I receive my funds when I initiate a withdrawal from Arbitrum chains (One and Nova)?",
+ "answer": "Using the official Arbitrum Bridge, the process will take *roughly* one week. However, some users opt to use third-party fast bridges, which often bypass this delay (remember that these bridges are created and maintained by third parties, so please DYOR!).\n\nThere's some variability in the exact wall-clock time of the dispute window, plus there's some expected additional \"padding\" time on both ends (no more than about an hour, typically).\n\nThe variability of the dispute window comes from the slight variance of block times. Arbitrum One's dispute window is 45818 blocks; this converts to about 6.5 days, assuming slightly more than 12 seconds per block, the average block time of Ethereum.\n\nThe \"padding on both ends\" involves three events that have to occur between a client receiving their transaction receipt from the Sequencer and their child-to-parent chain message being executable. After getting their receipt,\n\n1. The sequencer posts their transaction in a batch (usually within a few minutes, though the sequencer will wait a bit longer if the parent chain is congested). Then,\n2. A validator includes their transaction in an assertion (usually within the hour). Then, after the ~week long dispute window passes, the assertion is confirmable, and\n3. Somebody (anybody) confirms the assertion on the parent chain (usually within ~15 minutes).\nAdditionally, in the rare and unlikely event of a dispute, this delay period will be extended for the dispute to resolve.\n\n",
+ "key": "how-long-does-it-take-before-i-receive-my-funds-when-i-initiate-a-withdrawal-from-arbitrum-chains-one-and-nova"
+ },
+ {
+ "question": "Is there a way to cancel a withdrawal from Arbitrum?",
+ "answer": "Once initiated, it is not possible to cancel a withdrawal. However, you can claim your funds on L1 and deposit them again on L2 once the [withdrawal period](https://docs.arbitrum.io/learn-more/faq#why-was-one-week-chosen-for-arbitrum-ones-dispute-window) is past.\n\n\n\n",
+ "key": "is-there-a-way-to-cancel-a-withdrawal-from-arbitrum"
+ },
+ {
+ "question": "Can I use a smart contract wallet in the bridge?",
+ "answer": "Support for Smart Contract Wallets is currently limited to token deposits and withdrawals. Keep in mind that when withdrawing funds, you won't be able to claim them on L1 using the [bridge](https://bridge.arbitrum.io/) (unless you also control that address on L1). In that case, you can use the [cross-chain dashboard](https://retryable-dashboard.arbitrum.io/tx) to claim your funds on L1.\n\n`ETH` deposits and withdrawals using a Smart Contract Wallet are currently not supported, but will be available soon.\n\n",
+ "key": "can-i-use-a-smart-contract-wallet-in-the-bridge"
+ },
+ {
+ "question": "How can I claim withdrawn funds if I don't control on L1 the address that initiated the transaction on L2?",
+ "answer": "Once the [withdrawal period](https://docs.arbitrum.io/learn-more/faq#why-was-one-week-chosen-for-arbitrum-ones-dispute-window) is past, you can use the [cross-chain dashboard](https://retryable-dashboard.arbitrum.io/tx) to execute the message on L1. Paste the transaction hash that initiated the withdrawal on L2, and follow the process described in the dashboard.\n\n\n\n",
+ "key": "how-can-i-claim-withdrawn-funds-if-i-dont-control-on-l1-the-address-that-initiated-the-transaction-on-l2"
+ }
+]
diff --git a/static/building-faqs.json b/static/building-faqs.json
index 87f43b51cc..9c38dd6373 100644
--- a/static/building-faqs.json
+++ b/static/building-faqs.json
@@ -1,30 +1,142 @@
[
-{"question": "How does gas work on Arbitrum?","answer": "Fees on Arbitrum chains are collected on L2 in the chains' native currency (ETH on both Arbitrum One and Nova).\n\nA transaction fee is comprised of both an L1 and an L2 component:\n\nThe L1 component is meant to compensate the Sequencer for the cost of posting transactions on L1 (but no more). (See [L1 Pricing](https://developer.arbitrum.io/arbos/l1-pricing).)\n\nThe L2 component covers the cost of operating the L2 chain; it uses Geth for gas calculation and thus behaves nearly identically to L1 Ethereum. One difference is that unlike on Ethereum, Arbitrum chains enforce a gas price floor; currently 0.1 gwei on Arbitrum One and 0.01 gwei on Nova (See [Gas](https://docs.arbitrum.io/arbos/gas)).\n\nL2 Gas price adjusts responsively to chain congestion, ala EIP 1559.\n\n\n\n","key": "how-does-gas-work-on-arbitrum"},
-{"question": "I tried to create a retryable ticket but the transaction reverted on L1. How can I debug the issue?","answer": "Creation of retryable tickets can revert with one of these custom errors:\n\n1. **`InsufficientValue`**: not enough gas included in your L1 transaction's callvalue to cover the total cost of your retryable ticket; i.e., `msg.value < (maxSubmissionCost + l2CallValue + gasLimit * maxFeePerGas)`. Note that your L1 transaction's callvalue must cover this full cost. See [Retryable Tickets Lifecycle](https://docs.arbitrum.io/arbos/l1-to-l2-messaging#submission) for more information.\n2. **`InsufficientSubmissionCost`****:** The provided submission cost isn't high enough to create your retryable ticket.\n3. **`GasLimitTooLarge`****:** provided gas limit is greater than 2^64\n4. **`DataTooLarge`**: provided data is greater than 117.964 KB (90% of Geth's 128 KB transaction size limit).\nTo figure out which error caused your transaction to revert, we recommend using Etherscan's Parity VM trace support (Tenderly is generally a useful debugging tool; however, it can be buggy when it comes to custom Geth errors).\n\nUse the following link to view the Parity VM trace of your failed transaction (replacing the tx-hash with your own, and using the appropriate etherscan root url):\n\n[https://etherscan.io/vmtrace?txhash=0x51a8088c9b319bbad649c36d9cf2b4e9b61a6099a158181676c8e79dbce2df58&type=parity#raw](https://etherscan.io/vmtrace?txhash=0x51a8088c9b319bbad649c36d9cf2b4e9b61a6099a158181676c8e79dbce2df58&type=parity#raw)\n\nTo find out the reversion error signature, go to the **Raw Traces** tab, and scroll down to find the last **Subtrace** where your transaction was reverted. Then find **Output** field of that subtrace.\n\n(In the above example, the desirable **Output** is: `0xfadf238a0000000000000000000000000000000000000000000000000000c4df7e2903b00000000000000000000000000000000000000000000000000000a39a1d002808`)\n\nThe first four bytes of the output are the custom error signature; in our example, it is `0xfadf238a`.\n\nTo let's find out which custom error this signature represents, we can use this handy tool by Samzcsun: [https://sig.eth.samczsun.com/](https://sig.eth.samczsun.com/)\n\nChecking 0xfadf238a gives us `InsufficientSubmissionCost(uint256,uint256)`.\n\n","key": "i-tried-to-create-a-retryable-ticket-but-the-transaction-reverted-on-l1--how-can-i-debug-the-issue"},
-{"question": "How is the L1 portion of an Arbitrum transaction's gas fee computed? ","answer": "The L1 fee that a transaction is required to pay is determined by compressing its data with Brotli and multiplying the size of the result (in bytes) by ArbOS's current calldata price. The calldata price value can be queried via the `getPricesInWei` method of the `ArbGasInfo` precompile. You can find more information about gas calculations in [Understanding Arbitrum: 2-Dimensional Fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and [How to Estimate Gas in Arbitrum](https://developer.arbitrum.io/devs-how-tos/how-to-estimate-gas).\n\n\n\n","key": "how-is-the-l1-portion-of-an-arbitrum-transactions-gas-fee-computed-"},
-{"question": "What is a retryable ticket's \"submission fee\"? How can I calculate it? What happens if I the fee I provide is insufficient?","answer": "A [retryable's](https://developer.arbitrum.io/arbos/l1-to-l2-messaging) submission fee is a special fee a user must pay to create a retryable ticket. The fee is directly proportional to the size of the L1 calldata the retryable ticket uses. The fee can be queried using the `Inbox.calculateRetryableSubmissionFee`method. If insufficient fee is provided, the transaction will revert on L1, and the ticket won't get created. \n\n\n\n","key": "what-is-a-retryable-tickets-submission-fee-how-can-i-calculate-it-what-happens-if-i-the-fee-i-provide-is-insufficient"},
-{"question": "Which method in the Inbox contract should I use to submit a retryable ticket (aka L1 to L2 message)?","answer": "The method you should (almost certainly) use is `Inbox.createRetryableTicket`. There is an alternative method, `Inbox.unsafeCreateRetryableTicket`, which, as the name suggests, should only be used by those who fully understand its implications.\n\nThere are two differences between `createRetryableTicket` and `unsafeCreateRetryableTicket`:\n\n1. Method `createRetryableTicket` will check that provided L1 callvalue is sufficient to cover the costs of creating and executing the retryable ticket (at the specified parameters) and otherwise [revert directly at L1](https://docs.arbitrum.io/for-devs/troubleshooting-building#i-tried-to-create-a-retryable-ticket-but-the-transaction-reverted-on-l1--how-can-i-debug-the-issue). `unsafeCreateRetryableTicket`, in contrast, will allow a retryable ticket to be created that is guaranteed to revert on L2.\n2. Method `createRetryableTicket` will check if either the provided `excessFeeRefundAddress` or the `callValueRefundAddress` are contracts on L1; if they are, to prevent the situation where refunds are *guaranteed* to be irrecoverable on L2, it will convert them to their [address alias](https://developer.arbitrum.io/arbos/l1-to-l2-messaging#address-aliasing), providing a *potential* path for fund recovery. `unsafeCreateRetryableTicket` will allow the creation of a retryable ticket with refund addresses that are L1 contracts; since no L1 contract can alias to an address that is also itself an L1 contract, refunds to these addresses on L2 will be irrecoverable.\n(Astute observers may note a third ticket creation method, `createRetryableTicketNoRefundAliasRewrite`; this is included only for backwards compatibility, but should be considered deprecated in favor of `unsafeCreateRetryableTicket`)\n\n","key": "which-method-in-the-inbox-contract-should-i-use-to-submit-a-retryable-ticket-aka-l1-to-l2-message"},
-{"question": "Why do I get \"custom tx type\" errors when I use hardhat?","answer": "In Arbitrum, we use a number of non-standard [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) typed transactions. See [here](https://developer.arbitrum.io/arbos/geth#transaction-types) for the full list and the rationale.\n\nNote that if you're using Hardhat, [v2.12.2](https://github.com/NomicFoundation/hardhat/releases/tag/hardhat%402.12.2) added support for forking networks like Arbitrum with custom transaction types (find more information [here](https://github.com/NomicFoundation/hardhat/issues/2995)).\n\n\n\n","key": "why-do-i-get-custom-tx-type-errors-when-i-use-hardhat"},
-{"question": "Why does it look like two identical transactions consume a different amount of gas?","answer": "\n\nCalling an Arbitrum node's `eth_estimateGas` RPC returns a value sufficient to cover both the L1 and L2 components of the fee for the current gas price; this is the value that, e.g., will appear in users' wallets in the **Gas Limit** field.\n\nThus, if the L1 calldata price changes over time, it will appear (in e.g., a wallet) that a transaction's gas limit is changing. In fact, the L2 gas limit isn't changing, merely the total gas required to cover the transaction's L1 + L2 fees.\n\nSee [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and [How to estimate gas in Arbitrum](https://developer.arbitrum.io/devs-how-tos/how-to-estimate-gas) for more.\n\n\n\n\n\n","key": "why-does-it-look-like-two-identical-transactions-consume-a-different-amount-of-gas"},
-{"question": "Why am I getting error \"429 Too Many Requests\" when using one of Offchain Labs' Public RPCs?","answer": "Offchain Labs offers public RPCs for free, but limits requests to prevent denial of service (DoS) attacks. Hitting the rate limit can result from either the frequency of your requests or the resources required to process them. If you are hitting our rate limit, we recommend [running your own node](https://developer.arbitrum.io/node-running/how-tos/running-a-full-node) or [using a third-party node provider](https://developer.arbitrum.io/node-running/node-providers).\n\n\n\n","key": "why-am-i-getting-error-429-too-many-requests-when-using-one-of-offchain-labs-public-rpcs"},
-{"question": "How do block.number and block.timestamp work on Arbitrum?","answer": "Solidity calls to `block.number` on Arbitrum will return the block number/ timestamp of the underlying L1 with a slight delay; i.e., updated every few minutes. Note that L2 block numbers (i.e., as seen in block explorers / returned by RPCs) are different, and are typically updated roughly every second.\n\nSolidity calls to `block.timestamp` on Arbitrum are not linked to the timestamp of the L1 block. It is updated every L2 block based on the Sequencer's clock. Furthermore, for transactions that are force-included from the L1 (bypassing the Sequencer) `block.timestamp` will be equal to the L1 timestamp when the transaction was put in the delayed inbox on L1 (not force-included), or the L2 timestamp of the previous L2 block (whichever is greater of the two timestamps).\n\nFor more information, see [the block numbers and time](https://docs.arbitrum.io/for-devs/concepts/differences-between-arbitrum-ethereum/block-numbers-and-time).\n\n","key": "how-do-blocknumber-and-blocktimestamp-work-on-arbitrum"},
-{"question": "Do I need to download any special npm libraries in order to use web3.js, ethers.js or viem on Arbitrum? ","answer": "Nope, web3.js, ethers.js and viem will work out of the box just like they do on L1 Ethereum.\n\nOnce upon a time, Arbitrum developers were required to download supplemental packages with names like \"arb-provider-ethers\" and \"arb-ethers-web3-bridge\", but these packages are deprecated and no longer required! Any guide that directs devs to use them should be considered outdated.\n\n\n\n\n\n","key": "do-i-need-to-download-any-special-npm-libraries-in-order-to-use-web3js-ethersjs-or-viem-on-arbitrum-"},
-{"question": "How many block numbers must we wait for in Arbitrum before we can confidently state that the transaction has reached finality?","answer": "Arbitrum's block intervals fluctuate with throughput, so relying on block numbers for finality isn't recommended. However, Arbitrum nodes support Ethereum's JSON RPC, enabling the use of `[eth_getBlockByNumber()](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber)` to determine block finality. Here, we provide additional details on how to achieve this.\n\n\n\nYou can use `[eth_getBlockByNumber()](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber)` with the string `\"latest\"`, `\"safe\"`, or `\"finalized\"`, each offering varying degrees of finality:\n\n\n\n- `latest`: Provides you with the most recent Arbitrum block number, also known as the tip of the chain. This block is typically the last sequenced block and may not yet be posted on L1. As long as you trust the Sequencer to eventually post this information on L1, relying on the `latest` block should be fine. \n- `safe`: Provides you with the most recent Arbitrum block number that has achieved attestations from a two-thirds majority of Ethereum's validator set. This occurs when the Sequencer's batch is posted as an L1 block on Ethereum and then the batch transactions achieve `safe` finality there. While safe blocks are typically resistant to re-orgs, they can still be re-orged in the event of a significant L1 re-org.\n- `finalized`: Provides you with the most recent Arbitrum block number that is finalized on Ethereum. This means that the Sequencer's batch has been published** **as an L1 block on the Ethereum network and has reached a substantial depth, making it eligible for hard finality. Unlike `safe` blocks, `finalized` blocks are highly improbable to undergo re-orgs. \n\n\nTo learn more about the different phases of an Arbitrum transaction, from client initiation to Layer 1 confirmation, check out [The Lifecycle of an Arbitrum Transaction](https://docs.arbitrum.io/tx-lifecycle).\n\n\n\n","key": "how-many-block-numbers-must-we-wait-for-in-arbitrum-before-we-can-confidently-state-that-the-transaction-has-reached-finality"},
-{"question": "How can I list my token on the Arbitrum Bridge?","answer": "The L2 token list used in the Arbitrum bridge is generated from the L1 tokens that are part of the token lists of [Uniswap](https://tokenlists.org/token-list?url=https%3A%2F%2Ftokens.uniswap.org), [Gemini](https://tokenlists.org/token-list?url=https%3A%2F%2Fwww.gemini.com%2Funiswap%2Fmanifest.json), [Coinmarketcap](https://api.coinmarketcap.com/data-api/v3/uniswap/all.json), or [Coingecko](https://tokens.coingecko.com/uniswap/all.json). This generation is valid for L1-native tokens bridged to L2 and for L2-native tokens that have been bridged to L1, as long as they are part of either of those lists.\n\nCurrently, there isn't any L2-only token list.\n\n\n\n","key": "how-can-i-list-my-token-on-the-arbitrum-bridge"},
-{"question": "What is a testnet or a devnet?","answer": "Testnets (or devnets) primarily serve developers who want to test their applications without using real mainnet funds.\n\nArbitrum Sepolia is a testnet that offers the same full feature set as the mainnet network. It is also a \"true\" L2 that runs on top of the Sepolia testnet (L1), using it for security and settlement.\n\nUsers can bridge any asset from the Sepolia testnet (L1) into the Arbitrum Sepolia testnet (and back!), using the official [bridge](https://bridge.arbitrum.io/).\n\n\n\n","key": "what-is-a-testnet-or-a-devnet"},
-{"question": "Is there any testnet available on Arbitrum?","answer": "Yes, there's an Arbitrum Sepolia testnet (421614) that uses the Nitro tech stack and runs on top of Ethereum Sepolia. You can find more information [here](https://developer.arbitrum.io/public-chains).\n\n\n\n","key": "is-there-any-testnet-available-on-arbitrum"},
-{"question": "When was Arbitrum One upgraded from Classic to Nitro?","answer": "Arbitrum One [was upgraded](https://medium.com/offchainlabs/its-nitro-time-86944693bf29) on August 31st, 2022 (block [22207818](https://arbiscan.io/block/22207818)), from the Classic stack to the improved [Nitro](https://developer.arbitrum.io/inside-arbitrum-nitro/) tech stack, maintaining the same state.\n\n\n\n","key": "when-was-arbitrum-one-upgraded-from-classic-to-nitro"},
-{"question": "Do Arbitrum chains support precompiles that are present on Ethereum?","answer": "Yes, all Arbitrum chains support all precompiles that Ethereum supports, as well as others that are not present on Ethereum. Check the [precompiles reference page](https://docs.arbitrum.io/for-devs/dev-tools-and-resources/precompiles) for more information about Arbitrum specific precompiles.\n\n\n\n","key": "do-arbitrum-chains-support-precompiles-that-are-present-on-ethereum"},
-{"question": "What's the contract code size limit in Arbitrum chains?","answer": "As specified in [EIP-170](https://eips.ethereum.org/EIPS/eip-170), contracts of up to 24KB are deployable on Arbitrum chains.\n\n\n\n","key": "whats-the-contract-code-size-limit-in-arbitrum-chains"},
-{"question": "How can I find the L2 block(s) that corresponds to a given L1 block?","answer": "First, you should be familiar with how block numbers behave on Arbitrum. You can find information about it in [Block numbers and time](https://docs.arbitrum.io/for-devs/concepts/differences-between-arbitrum-ethereum/block-numbers-and-time).\n\nWhen you query an RPC node for a transaction receipt or a block information, you obtain as part of the result the property `l1BlockNumber`, which is the L1 block number that the sequencer viewed when it processed the transaction.\n\nWith that, although it might be computationally complex, you can binary search the L1 block number you are looking for, and get all L2 blocks that have that `l1BlockNumber`.\n\nIf you want a more specific result, you can perform the same operation with the timestamp from the L1 block, instead of the actual block number.\n\n","key": "how-can-i-find-the-l2-blocks-that-corresponds-to-a-given-l1-block"},
-{"question": "Why do some old transactions have extremely high gas prices when querying them?","answer": "When Arbitrum One was running under the Arbitrum Classic stack (before Nitro), the gas price was an unbounded bid, so when requesting those transactions via RPC, you may obtain a very high amount in the `gasPrice` property.\n\nInstead of that, it is recommended to look at the `effectiveGasPrice` property from the transaction receipt.\n\n\n\n","key": "why-do-some-old-transactions-have-extremely-high-gas-prices-when-querying-them"},
-{"question": "What is the WASM module root?","answer": "The WASM module root is a 32-byte hash, which is a Merkelization of the Go replay binary and its dependencies.\n\nThe replay binary is much too large to post on-chain, so this hash is set in the L1 rollup contract to determine the correct replay binary during fraud proofs.\n\nYou can find more information in [How to Customize your Orbit chain's behavior](https://docs.arbitrum.io/launch-orbit-chain/how-tos/customize-stf#step-4-enable-fraud-proofs).\n\n\n\n","key": "what-is-the-wasm-module-root"},
-{"question": "Why do I get a \"gas required exceeds allowance\" when trying to estimate the gas costs of a request?","answer": "During an `eth_estimateGas` call, the request will go through a simulation on the node. Therefore, if the transaction reverts or if there aren't enough funds in the wallet that's making the call (usually the `from` parameter), the `eth_estimateGas` request will return an error stating: `gas required exceeds allowance`.\n\nEnsure you have sufficient funds in your wallet, and that the gas fields of the request (if you're using them) are populated correctly.\n\n","key": "why-do-i-get-a-gas-required-exceeds-allowance-when-trying-to-estimate-the-gas-costs-of-a-request"},
-{"question": "How can I verify that a child chain block has been processed as part of a specific assertion?","answer": "If you want to verify that the latest confirmed (or created) assertion has processed a specific child chain block, you can follow these steps:\n\n1. From the rollup contract, obtain the latest confirmed (or created) assertion through the function `latestConfirmed` (or `latestNodeCreated`). In this context, we refer to assertions as \"nodes\".\n2. Obtain the node information through `getNode`\n3. Find the `NodeCreated` event emission that occurred upon that node's creation.\n4. In that `NodeCreated` event, there's an `assertion` property that contains the state of the chain before processing the specified blocks, and after processing them. Get the `afterState.globalState` property\n5. That value contains a `bytes32Vals` array with the latest child chain block hash processed in the first element.\nYou can find an example script in our [arbitrum-tutorials](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/l2-block-verification-in-assertion) repository.\n\n","key": "how-can-i-verify-that-a-child-chain-block-has-been-processed-as-part-of-a-specific-assertion"},
-{"question": "Why is the fee of some Classic transactions slightly different than the multiplication of gasLimit and effectiveGasPrice?","answer": "Gas prices in Classic transactions worked differently from those in Nitro transactions. Classic transactions handled four different prices: L1 fixed, L1 calldata, L2 computation, and L2 storage. You can view all these prices in the **Advanced TxInfo** tab on Arbiscan (see an [example](https://arbiscan.io/tx/0xecfe992adc408d1458d97b6e066ea7f4169bf048e84cb7a4beaea6e9c54f07da#txninfo) here).\n\nWhen querying the receipt of a Classic transaction on a Nitro node, some calculation is needed to obtain an `effectiveGasPrice` that is close to (but not exactly) what those four prices represent. That's why if you multiply the `gasLimit` by the `effectiveGasPrice` you might end up with a transaction fee that is slightly different than the actual fee paid.\n\nTo get the exact fees paid, you can query a Classic node, which will return all the accurate information in an object called `feeStats`. That object will contain all the information, split into four different gas fields: `prices`, `unitsUsed`, and `paid` (`which is price * unitsUsed`).\n\n","key": "why-is-the-fee-of-some-classic-transactions-slightly-different-than-the-multiplication-of-gaslimit-and-effectivegasprice"},
-{"question": "How can I update the information of my bridged token on Arbiscan?","answer": "If you have a native-L1 token that was bridged to L2 via the standard gateway, you might find that you can't claim ownership of the L2 contract of your token as it was generated by another contract.\n\nTo update its information on Arbiscan (logo, socials, etc.), you can open a ticket through [Arbiscan support system](https://arbiscan.io/contactus) and request them to replicate the information of your token on L1 to L2.\n\n\n\n","key": "how-can-i-update-the-information-of-my-bridged-token-on-arbiscan"},
-{"question": "Why does my transaction revert with InvalidFEOpcode when using Foundry?","answer": "Foundry and other similar development tools that enable chain forking, do not support Arbitrum precompiles. If your transaction is calling a precompile, it is likely that it will revert with `InvalidFEOpcode`.\n\nTo rule out that possibility, it is recommended to send the transaction with a different tool.\n\n\n\n","key": "why-does-my-transaction-revert-with-invalidfeopcode-when-using-foundry"},
-{"question": "Why do I receive an \"intrinsic gas too low\" error when sending a transaction even with a high gas price?","answer": "The error: `intrinsic gas too low` usually refers to not providing enough gas to pay for the L1 component of the transaction fees. This error typically occurs when a high enough gas limit is not set (instead of a gas price), due to how Arbitrum handles gas. You can find more information in the article [Understanding Arbitrum: 2-dimensional fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and the page [How to estimate gas](https://docs.arbitrum.io/devs-how-tos/how-to-estimate-gas).\n\n\n\n","key": "why-do-i-receive-an-intrinsic-gas-too-low-error-when-sending-a-transaction-even-with-a-high-gas-price"},
-{"question": "How can I interpret Arbitrum transaction traces?","answer": "In Arbitrum, every block contains a system transaction of type `[ArbitrumInternalTxType](https://docs.arbitrum.io/arbos/geth#ArbitrumInternalTx)`, which the ArbOS itself creates for specific state updates, such as the L1 base fee and the block number. These transactions are distinct from typical Ethereum transactions. They are exclusively generated by the ArbOS state transition function, rather than by external entities such as externally owned accounts (EOAs) or smart contracts. Despite having an `INVALID` opcode, these transactions are represented in the trace API to signify their presence in the block, even though an opcode within EVM execution does not trigger them.\n\nOne of the key functionalities of `ArbitrumInternalTxType` involves managing value transfers related to acknowledging batch postings. When batches of transactions get submitted to Layer 1, a special cross-chain message is produced as a receipt, confirming the successful posting of the batch. The function `ApplyInternalTxUpdate` is responsible for processing and updating the system's state based on these crosschain messages, ensuring consistency and integrity across the Arbitrum network.\n\nAnother functionality of `ArbitrumInternalTxType` transactions is handling the value held in retryables if discarded. Retryable transactions are transactions that can be \"resubmitted\" if they fail to execute on the destination chain. However, in certain scenarios, these retryable transactions might get discarded, for instance, due to expiration or other conditions.\n\nIn such cases, the escrowed call value, which is the value associated with the retryable transaction, will be paid out to a specified `callValueRefundAddress` account. This address designation occurs during the initial submission of the transaction on the parent chain. The purpose of this mechanism is to ensure that funds associated with retryable transactions are not lost if they cannot be successfully executed, thereby maintaining the integrity and reliability of the Arbitrum network.\n\nTo accurately reflect the value transfers associated with these transactions, we employ a unique `callType` parameter: `invalid`. Unlike conventional EVM calls (such as `delegatecall`, `call`, etc.), this designation signifies a different system transaction. It denotes a straightforward value transfer from one account to another, with no inherent invocation of smart contract logic. While technically feasible to conduct this transfer within a conventional call type, our deliberate choice of **invalid** aims to enhance the clarity and distinctiveness of this transaction type within the EVM ecosystem.\n\nNotably, the sender account remains consistent across all instances of this transaction type for the batch posting receipt version. However, it's important to note that for retryable transactions, the sender account differs as each retryable transaction escrows its value in a unique vault specific to that transaction. This unique vault ensures that funds associated with each retryable transaction are stored securely until either the transaction successfully executes or a refund is issued.\n\n**Note that:**\n\n- All pre-Nitro transactions are labeled as `ArbitrumLegacyTxType` by Nitro.\n- Traces are not available for pre-Nitro (Classic) transactions.\n","key": "how-can-i-interpret-arbitrum-transaction-traces"},
-{"question": "Why do some blocks have a total gas limit that's over the standard block gas limit?","answer": "The execution gas block limit of Arbitrum chains is 32 million. However, when querying a block, we may find a gasLimit value that exceeds the specified number.\n\nFinding it exceeds happens because this `gasLimit` field accounts for both execution gas and the corresponding gas limit of the L1 costs (you can find more information about the role of the L1 costs in a transaction's gas limit in [this article](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9)). The gas limit corresponding to L1 costs is practically unlimited, leading to the possibility of finding very high values on the gasLimit field of a block.\n\nThe effective block gas limit (32 million) only accounts for execution gas limit. We can check the actual gas used for execution on a specific block by checking the gasUsed field.\n\n","key": "why-do-some-blocks-have-a-total-gas-limit-thats-over-the-standard-block-gas-limit"}
-]
\ No newline at end of file
+ {
+ "question": "How does gas work on Arbitrum?",
+ "answer": "Fees on Arbitrum chains are collected on L2 in the chains' native currency (ETH on both Arbitrum One and Nova).\n\nA transaction fee is comprised of both an L1 and an L2 component:\n\nThe L1 component is meant to compensate the Sequencer for the cost of posting transactions on L1 (but no more). (See [L1 Pricing](https://developer.arbitrum.io/arbos/l1-pricing).)\n\nThe L2 component covers the cost of operating the L2 chain; it uses Geth for gas calculation and thus behaves nearly identically to L1 Ethereum. One difference is that unlike on Ethereum, Arbitrum chains enforce a gas price floor; currently 0.1 gwei on Arbitrum One and 0.01 gwei on Nova (See [Gas](https://docs.arbitrum.io/arbos/gas)).\n\nL2 Gas price adjusts responsively to chain congestion, ala EIP 1559.\n\n\n\n",
+ "key": "how-does-gas-work-on-arbitrum"
+ },
+ {
+ "question": "I tried to create a retryable ticket but the transaction reverted on L1. How can I debug the issue?",
+ "answer": "Creation of retryable tickets can revert with one of these custom errors:\n\n1. **`InsufficientValue`**: not enough gas included in your L1 transaction's callvalue to cover the total cost of your retryable ticket; i.e., `msg.value < (maxSubmissionCost + l2CallValue + gasLimit * maxFeePerGas)`. Note that your L1 transaction's callvalue must cover this full cost. See [Retryable Tickets Lifecycle](https://docs.arbitrum.io/arbos/l1-to-l2-messaging#submission) for more information.\n2. **`InsufficientSubmissionCost`****:** The provided submission cost isn't high enough to create your retryable ticket.\n3. **`GasLimitTooLarge`****:** provided gas limit is greater than 2^64\n4. **`DataTooLarge`**: provided data is greater than 117.964 KB (90% of Geth's 128 KB transaction size limit).\nTo figure out which error caused your transaction to revert, we recommend using Etherscan's Parity VM trace support (Tenderly is generally a useful debugging tool; however, it can be buggy when it comes to custom Geth errors).\n\nUse the following link to view the Parity VM trace of your failed transaction (replacing the tx-hash with your own, and using the appropriate etherscan root url):\n\n[https://etherscan.io/vmtrace?txhash=0x51a8088c9b319bbad649c36d9cf2b4e9b61a6099a158181676c8e79dbce2df58&type=parity#raw](https://etherscan.io/vmtrace?txhash=0x51a8088c9b319bbad649c36d9cf2b4e9b61a6099a158181676c8e79dbce2df58&type=parity#raw)\n\nTo find out the reversion error signature, go to the **Raw Traces** tab, and scroll down to find the last **Subtrace** where your transaction was reverted. Then find **Output** field of that subtrace.\n\n(In the above example, the desirable **Output** is: `0xfadf238a0000000000000000000000000000000000000000000000000000c4df7e2903b00000000000000000000000000000000000000000000000000000a39a1d002808`)\n\nThe first four bytes of the output are the custom error signature; in our example, it is `0xfadf238a`.\n\nTo let's find out which custom error this signature represents, we can use this handy tool by Samzcsun: [https://sig.eth.samczsun.com/](https://sig.eth.samczsun.com/)\n\nChecking 0xfadf238a gives us `InsufficientSubmissionCost(uint256,uint256)`.\n\n",
+ "key": "i-tried-to-create-a-retryable-ticket-but-the-transaction-reverted-on-l1--how-can-i-debug-the-issue"
+ },
+ {
+ "question": "How is the L1 portion of an Arbitrum transaction's gas fee computed? ",
+ "answer": "The L1 fee that a transaction is required to pay is determined by compressing its data with Brotli and multiplying the size of the result (in bytes) by ArbOS's current calldata price. The calldata price value can be queried via the `getPricesInWei` method of the `ArbGasInfo` precompile. You can find more information about gas calculations in [Understanding Arbitrum: 2-Dimensional Fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and [How to Estimate Gas in Arbitrum](https://developer.arbitrum.io/devs-how-tos/how-to-estimate-gas).\n\n\n\n",
+ "key": "how-is-the-l1-portion-of-an-arbitrum-transactions-gas-fee-computed-"
+ },
+ {
+ "question": "What is a retryable ticket's \"submission fee\"? How can I calculate it? What happens if I the fee I provide is insufficient?",
+ "answer": "A [retryable's](https://developer.arbitrum.io/arbos/l1-to-l2-messaging) submission fee is a special fee a user must pay to create a retryable ticket. The fee is directly proportional to the size of the L1 calldata the retryable ticket uses. The fee can be queried using the `Inbox.calculateRetryableSubmissionFee`method. If insufficient fee is provided, the transaction will revert on L1, and the ticket won't get created. \n\n\n\n",
+ "key": "what-is-a-retryable-tickets-submission-fee-how-can-i-calculate-it-what-happens-if-i-the-fee-i-provide-is-insufficient"
+ },
+ {
+ "question": "Which method in the Inbox contract should I use to submit a retryable ticket (aka L1 to L2 message)?",
+ "answer": "The method you should (almost certainly) use is `Inbox.createRetryableTicket`. There is an alternative method, `Inbox.unsafeCreateRetryableTicket`, which, as the name suggests, should only be used by those who fully understand its implications.\n\nThere are two differences between `createRetryableTicket` and `unsafeCreateRetryableTicket`:\n\n1. Method `createRetryableTicket` will check that provided L1 callvalue is sufficient to cover the costs of creating and executing the retryable ticket (at the specified parameters) and otherwise [revert directly at L1](https://docs.arbitrum.io/for-devs/troubleshooting-building#i-tried-to-create-a-retryable-ticket-but-the-transaction-reverted-on-l1--how-can-i-debug-the-issue). `unsafeCreateRetryableTicket`, in contrast, will allow a retryable ticket to be created that is guaranteed to revert on L2.\n2. Method `createRetryableTicket` will check if either the provided `excessFeeRefundAddress` or the `callValueRefundAddress` are contracts on L1; if they are, to prevent the situation where refunds are *guaranteed* to be irrecoverable on L2, it will convert them to their [address alias](https://developer.arbitrum.io/arbos/l1-to-l2-messaging#address-aliasing), providing a *potential* path for fund recovery. `unsafeCreateRetryableTicket` will allow the creation of a retryable ticket with refund addresses that are L1 contracts; since no L1 contract can alias to an address that is also itself an L1 contract, refunds to these addresses on L2 will be irrecoverable.\n(Astute observers may note a third ticket creation method, `createRetryableTicketNoRefundAliasRewrite`; this is included only for backwards compatibility, but should be considered deprecated in favor of `unsafeCreateRetryableTicket`)\n\n",
+ "key": "which-method-in-the-inbox-contract-should-i-use-to-submit-a-retryable-ticket-aka-l1-to-l2-message"
+ },
+ {
+ "question": "Why do I get \"custom tx type\" errors when I use hardhat?",
+ "answer": "In Arbitrum, we use a number of non-standard [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) typed transactions. See [here](https://developer.arbitrum.io/arbos/geth#transaction-types) for the full list and the rationale.\n\nNote that if you're using Hardhat, [v2.12.2](https://github.com/NomicFoundation/hardhat/releases/tag/hardhat%402.12.2) added support for forking networks like Arbitrum with custom transaction types (find more information [here](https://github.com/NomicFoundation/hardhat/issues/2995)).\n\n\n\n",
+ "key": "why-do-i-get-custom-tx-type-errors-when-i-use-hardhat"
+ },
+ {
+ "question": "Why does it look like two identical transactions consume a different amount of gas?",
+ "answer": "\n\nCalling an Arbitrum node's `eth_estimateGas` RPC returns a value sufficient to cover both the L1 and L2 components of the fee for the current gas price; this is the value that, e.g., will appear in users' wallets in the **Gas Limit** field.\n\nThus, if the L1 calldata price changes over time, it will appear (in e.g., a wallet) that a transaction's gas limit is changing. In fact, the L2 gas limit isn't changing, merely the total gas required to cover the transaction's L1 + L2 fees.\n\nSee [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and [How to estimate gas in Arbitrum](https://developer.arbitrum.io/devs-how-tos/how-to-estimate-gas) for more.\n\n\n\n\n\n",
+ "key": "why-does-it-look-like-two-identical-transactions-consume-a-different-amount-of-gas"
+ },
+ {
+ "question": "Why am I getting error \"429 Too Many Requests\" when using one of Offchain Labs' Public RPCs?",
+ "answer": "Offchain Labs offers public RPCs for free, but limits requests to prevent denial of service (DoS) attacks. Hitting the rate limit can result from either the frequency of your requests or the resources required to process them. If you are hitting our rate limit, we recommend [running your own node](https://developer.arbitrum.io/node-running/how-tos/running-a-full-node) or [using a third-party node provider](https://developer.arbitrum.io/node-running/node-providers).\n\n\n\n",
+ "key": "why-am-i-getting-error-429-too-many-requests-when-using-one-of-offchain-labs-public-rpcs"
+ },
+ {
+ "question": "How do block.number and block.timestamp work on Arbitrum?",
+ "answer": "Solidity calls to `block.number` on Arbitrum will return the block number/ timestamp of the underlying L1 with a slight delay; i.e., updated every few minutes. Note that L2 block numbers (i.e., as seen in block explorers / returned by RPCs) are different, and are typically updated roughly every second.\n\nSolidity calls to `block.timestamp` on Arbitrum are not linked to the timestamp of the L1 block. It is updated every L2 block based on the Sequencer's clock. Furthermore, for transactions that are force-included from the L1 (bypassing the Sequencer) `block.timestamp` will be equal to the L1 timestamp when the transaction was put in the delayed inbox on L1 (not force-included), or the L2 timestamp of the previous L2 block (whichever is greater of the two timestamps).\n\nFor more information, see [the block numbers and time](https://docs.arbitrum.io/for-devs/concepts/differences-between-arbitrum-ethereum/block-numbers-and-time).\n\n",
+ "key": "how-do-blocknumber-and-blocktimestamp-work-on-arbitrum"
+ },
+ {
+ "question": "Do I need to download any special npm libraries in order to use web3.js, ethers.js or viem on Arbitrum? ",
+ "answer": "Nope, web3.js, ethers.js and viem will work out of the box just like they do on L1 Ethereum.\n\nOnce upon a time, Arbitrum developers were required to download supplemental packages with names like \"arb-provider-ethers\" and \"arb-ethers-web3-bridge\", but these packages are deprecated and no longer required! Any guide that directs devs to use them should be considered outdated.\n\n\n\n\n\n",
+ "key": "do-i-need-to-download-any-special-npm-libraries-in-order-to-use-web3js-ethersjs-or-viem-on-arbitrum-"
+ },
+ {
+ "question": "How many block numbers must we wait for in Arbitrum before we can confidently state that the transaction has reached finality?",
+ "answer": "Arbitrum's block intervals fluctuate with throughput, so relying on block numbers for finality isn't recommended. However, Arbitrum nodes support Ethereum's JSON RPC, enabling the use of `[eth_getBlockByNumber()](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber)` to determine block finality. Here, we provide additional details on how to achieve this.\n\n\n\nYou can use `[eth_getBlockByNumber()](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber)` with the string `\"latest\"`, `\"safe\"`, or `\"finalized\"`, each offering varying degrees of finality:\n\n\n\n- `latest`: Provides you with the most recent Arbitrum block number, also known as the tip of the chain. This block is typically the last sequenced block and may not yet be posted on L1. As long as you trust the Sequencer to eventually post this information on L1, relying on the `latest` block should be fine. \n- `safe`: Provides you with the most recent Arbitrum block number that has achieved attestations from a two-thirds majority of Ethereum's validator set. This occurs when the Sequencer's batch is posted as an L1 block on Ethereum and then the batch transactions achieve `safe` finality there. While safe blocks are typically resistant to re-orgs, they can still be re-orged in the event of a significant L1 re-org.\n- `finalized`: Provides you with the most recent Arbitrum block number that is finalized on Ethereum. This means that the Sequencer's batch has been published** **as an L1 block on the Ethereum network and has reached a substantial depth, making it eligible for hard finality. Unlike `safe` blocks, `finalized` blocks are highly improbable to undergo re-orgs. \n\n\nTo learn more about the different phases of an Arbitrum transaction, from client initiation to Layer 1 confirmation, check out [The Lifecycle of an Arbitrum Transaction](https://docs.arbitrum.io/tx-lifecycle).\n\n\n\n",
+ "key": "how-many-block-numbers-must-we-wait-for-in-arbitrum-before-we-can-confidently-state-that-the-transaction-has-reached-finality"
+ },
+ {
+ "question": "How can I list my token on the Arbitrum Bridge?",
+ "answer": "The L2 token list used in the Arbitrum bridge is generated from the L1 tokens that are part of the token lists of [Uniswap](https://tokenlists.org/token-list?url=https%3A%2F%2Ftokens.uniswap.org), [Gemini](https://tokenlists.org/token-list?url=https%3A%2F%2Fwww.gemini.com%2Funiswap%2Fmanifest.json), [Coinmarketcap](https://api.coinmarketcap.com/data-api/v3/uniswap/all.json), or [Coingecko](https://tokens.coingecko.com/uniswap/all.json). This generation is valid for L1-native tokens bridged to L2 and for L2-native tokens that have been bridged to L1, as long as they are part of either of those lists.\n\nCurrently, there isn't any L2-only token list.\n\n\n\n",
+ "key": "how-can-i-list-my-token-on-the-arbitrum-bridge"
+ },
+ {
+ "question": "What is a testnet or a devnet?",
+ "answer": "Testnets (or devnets) primarily serve developers who want to test their applications without using real mainnet funds.\n\nArbitrum Sepolia is a testnet that offers the same full feature set as the mainnet network. It is also a \"true\" L2 that runs on top of the Sepolia testnet (L1), using it for security and settlement.\n\nUsers can bridge any asset from the Sepolia testnet (L1) into the Arbitrum Sepolia testnet (and back!), using the official [bridge](https://bridge.arbitrum.io/).\n\n\n\n",
+ "key": "what-is-a-testnet-or-a-devnet"
+ },
+ {
+ "question": "Is there any testnet available on Arbitrum?",
+ "answer": "Yes, there's an Arbitrum Sepolia testnet (421614) that uses the Nitro tech stack and runs on top of Ethereum Sepolia. You can find more information [here](https://developer.arbitrum.io/public-chains).\n\n\n\n",
+ "key": "is-there-any-testnet-available-on-arbitrum"
+ },
+ {
+ "question": "When was Arbitrum One upgraded from Classic to Nitro?",
+ "answer": "Arbitrum One [was upgraded](https://medium.com/offchainlabs/its-nitro-time-86944693bf29) on August 31st, 2022 (block [22207818](https://arbiscan.io/block/22207818)), from the Classic stack to the improved [Nitro](https://developer.arbitrum.io/inside-arbitrum-nitro/) tech stack, maintaining the same state.\n\n\n\n",
+ "key": "when-was-arbitrum-one-upgraded-from-classic-to-nitro"
+ },
+ {
+ "question": "Do Arbitrum chains support precompiles that are present on Ethereum?",
+ "answer": "Yes, all Arbitrum chains support all precompiles that Ethereum supports, as well as others that are not present on Ethereum. Check the [precompiles reference page](https://docs.arbitrum.io/for-devs/dev-tools-and-resources/precompiles) for more information about Arbitrum specific precompiles.\n\n\n\n",
+ "key": "do-arbitrum-chains-support-precompiles-that-are-present-on-ethereum"
+ },
+ {
+ "question": "What's the contract code size limit in Arbitrum chains?",
+ "answer": "As specified in [EIP-170](https://eips.ethereum.org/EIPS/eip-170), contracts of up to 24KB are deployable on Arbitrum chains.\n\n\n\n",
+ "key": "whats-the-contract-code-size-limit-in-arbitrum-chains"
+ },
+ {
+ "question": "How can I find the L2 block(s) that corresponds to a given L1 block?",
+ "answer": "First, you should be familiar with how block numbers behave on Arbitrum. You can find information about it in [Block numbers and time](https://docs.arbitrum.io/for-devs/concepts/differences-between-arbitrum-ethereum/block-numbers-and-time).\n\nWhen you query an RPC node for a transaction receipt or a block information, you obtain as part of the result the property `l1BlockNumber`, which is the L1 block number that the sequencer viewed when it processed the transaction.\n\nWith that, although it might be computationally complex, you can binary search the L1 block number you are looking for, and get all L2 blocks that have that `l1BlockNumber`.\n\nIf you want a more specific result, you can perform the same operation with the timestamp from the L1 block, instead of the actual block number.\n\n",
+ "key": "how-can-i-find-the-l2-blocks-that-corresponds-to-a-given-l1-block"
+ },
+ {
+ "question": "Why do some old transactions have extremely high gas prices when querying them?",
+ "answer": "When Arbitrum One was running under the Arbitrum Classic stack (before Nitro), the gas price was an unbounded bid, so when requesting those transactions via RPC, you may obtain a very high amount in the `gasPrice` property.\n\nInstead of that, it is recommended to look at the `effectiveGasPrice` property from the transaction receipt.\n\n\n\n",
+ "key": "why-do-some-old-transactions-have-extremely-high-gas-prices-when-querying-them"
+ },
+ {
+ "question": "What is the WASM module root?",
+ "answer": "The WASM module root is a 32-byte hash, which is a Merkelization of the Go replay binary and its dependencies.\n\nThe replay binary is much too large to post on-chain, so this hash is set in the L1 rollup contract to determine the correct replay binary during fraud proofs.\n\nYou can find more information in [How to Customize your Orbit chain's behavior](https://docs.arbitrum.io/launch-orbit-chain/how-tos/customize-stf#step-4-enable-fraud-proofs).\n\n\n\n",
+ "key": "what-is-the-wasm-module-root"
+ },
+ {
+ "question": "Why do I get a \"gas required exceeds allowance\" when trying to estimate the gas costs of a request?",
+ "answer": "During an `eth_estimateGas` call, the request will go through a simulation on the node. Therefore, if the transaction reverts or if there aren't enough funds in the wallet that's making the call (usually the `from` parameter), the `eth_estimateGas` request will return an error stating: `gas required exceeds allowance`.\n\nEnsure you have sufficient funds in your wallet, and that the gas fields of the request (if you're using them) are populated correctly.\n\n",
+ "key": "why-do-i-get-a-gas-required-exceeds-allowance-when-trying-to-estimate-the-gas-costs-of-a-request"
+ },
+ {
+ "question": "How can I verify that a child chain block has been processed as part of a specific assertion?",
+ "answer": "If you want to verify that the latest confirmed (or created) assertion has processed a specific child chain block, you can follow these steps:\n\n1. From the rollup contract, obtain the latest confirmed (or created) assertion through the function `latestConfirmed` (or `latestNodeCreated`). In this context, we refer to assertions as \"nodes\".\n2. Obtain the node information through `getNode`\n3. Find the `NodeCreated` event emission that occurred upon that node's creation.\n4. In that `NodeCreated` event, there's an `assertion` property that contains the state of the chain before processing the specified blocks, and after processing them. Get the `afterState.globalState` property\n5. That value contains a `bytes32Vals` array with the latest child chain block hash processed in the first element.\nYou can find an example script in our [arbitrum-tutorials](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/l2-block-verification-in-assertion) repository.\n\n",
+ "key": "how-can-i-verify-that-a-child-chain-block-has-been-processed-as-part-of-a-specific-assertion"
+ },
+ {
+ "question": "Why is the fee of some Classic transactions slightly different than the multiplication of gasLimit and effectiveGasPrice?",
+ "answer": "Gas prices in Classic transactions worked differently from those in Nitro transactions. Classic transactions handled four different prices: L1 fixed, L1 calldata, L2 computation, and L2 storage. You can view all these prices in the **Advanced TxInfo** tab on Arbiscan (see an [example](https://arbiscan.io/tx/0xecfe992adc408d1458d97b6e066ea7f4169bf048e84cb7a4beaea6e9c54f07da#txninfo) here).\n\nWhen querying the receipt of a Classic transaction on a Nitro node, some calculation is needed to obtain an `effectiveGasPrice` that is close to (but not exactly) what those four prices represent. That's why if you multiply the `gasLimit` by the `effectiveGasPrice` you might end up with a transaction fee that is slightly different than the actual fee paid.\n\nTo get the exact fees paid, you can query a Classic node, which will return all the accurate information in an object called `feeStats`. That object will contain all the information, split into four different gas fields: `prices`, `unitsUsed`, and `paid` (`which is price * unitsUsed`).\n\n",
+ "key": "why-is-the-fee-of-some-classic-transactions-slightly-different-than-the-multiplication-of-gaslimit-and-effectivegasprice"
+ },
+ {
+ "question": "How can I update the information of my bridged token on Arbiscan?",
+ "answer": "If you have a native-L1 token that was bridged to L2 via the standard gateway, you might find that you can't claim ownership of the L2 contract of your token as it was generated by another contract.\n\nTo update its information on Arbiscan (logo, socials, etc.), you can open a ticket through [Arbiscan support system](https://arbiscan.io/contactus) and request them to replicate the information of your token on L1 to L2.\n\n\n\n",
+ "key": "how-can-i-update-the-information-of-my-bridged-token-on-arbiscan"
+ },
+ {
+ "question": "Why does my transaction revert with InvalidFEOpcode when using Foundry?",
+ "answer": "Foundry and other similar development tools that enable chain forking, do not support Arbitrum precompiles. If your transaction is calling a precompile, it is likely that it will revert with `InvalidFEOpcode`.\n\nTo rule out that possibility, it is recommended to send the transaction with a different tool.\n\n\n\n",
+ "key": "why-does-my-transaction-revert-with-invalidfeopcode-when-using-foundry"
+ },
+ {
+ "question": "Why do I receive an \"intrinsic gas too low\" error when sending a transaction even with a high gas price?",
+ "answer": "The error: `intrinsic gas too low` usually refers to not providing enough gas to pay for the L1 component of the transaction fees. This error typically occurs when a high enough gas limit is not set (instead of a gas price), due to how Arbitrum handles gas. You can find more information in the article [Understanding Arbitrum: 2-dimensional fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and the page [How to estimate gas](https://docs.arbitrum.io/devs-how-tos/how-to-estimate-gas).\n\n\n\n",
+ "key": "why-do-i-receive-an-intrinsic-gas-too-low-error-when-sending-a-transaction-even-with-a-high-gas-price"
+ },
+ {
+ "question": "How can I interpret Arbitrum transaction traces?",
+ "answer": "In Arbitrum, every block contains a system transaction of type `[ArbitrumInternalTxType](https://docs.arbitrum.io/arbos/geth#ArbitrumInternalTx)`, which the ArbOS itself creates for specific state updates, such as the L1 base fee and the block number. These transactions are distinct from typical Ethereum transactions. They are exclusively generated by the ArbOS state transition function, rather than by external entities such as externally owned accounts (EOAs) or smart contracts. Despite having an `INVALID` opcode, these transactions are represented in the trace API to signify their presence in the block, even though an opcode within EVM execution does not trigger them.\n\nOne of the key functionalities of `ArbitrumInternalTxType` involves managing value transfers related to acknowledging batch postings. When batches of transactions get submitted to Layer 1, a special cross-chain message is produced as a receipt, confirming the successful posting of the batch. The function `ApplyInternalTxUpdate` is responsible for processing and updating the system's state based on these crosschain messages, ensuring consistency and integrity across the Arbitrum network.\n\nAnother functionality of `ArbitrumInternalTxType` transactions is handling the value held in retryables if discarded. Retryable transactions are transactions that can be \"resubmitted\" if they fail to execute on the destination chain. However, in certain scenarios, these retryable transactions might get discarded, for instance, due to expiration or other conditions.\n\nIn such cases, the escrowed call value, which is the value associated with the retryable transaction, will be paid out to a specified `callValueRefundAddress` account. This address designation occurs during the initial submission of the transaction on the parent chain. The purpose of this mechanism is to ensure that funds associated with retryable transactions are not lost if they cannot be successfully executed, thereby maintaining the integrity and reliability of the Arbitrum network.\n\nTo accurately reflect the value transfers associated with these transactions, we employ a unique `callType` parameter: `invalid`. Unlike conventional EVM calls (such as `delegatecall`, `call`, etc.), this designation signifies a different system transaction. It denotes a straightforward value transfer from one account to another, with no inherent invocation of smart contract logic. While technically feasible to conduct this transfer within a conventional call type, our deliberate choice of **invalid** aims to enhance the clarity and distinctiveness of this transaction type within the EVM ecosystem.\n\nNotably, the sender account remains consistent across all instances of this transaction type for the batch posting receipt version. However, it's important to note that for retryable transactions, the sender account differs as each retryable transaction escrows its value in a unique vault specific to that transaction. This unique vault ensures that funds associated with each retryable transaction are stored securely until either the transaction successfully executes or a refund is issued.\n\n**Note that:**\n\n- All pre-Nitro transactions are labeled as `ArbitrumLegacyTxType` by Nitro.\n- Traces are not available for pre-Nitro (Classic) transactions.\n",
+ "key": "how-can-i-interpret-arbitrum-transaction-traces"
+ },
+ {
+ "question": "Why do some blocks have a total gas limit that's over the standard block gas limit?",
+ "answer": "The execution gas block limit of Arbitrum chains is 32 million. However, when querying a block, we may find a gasLimit value that exceeds the specified number.\n\nFinding it exceeds happens because this `gasLimit` field accounts for both execution gas and the corresponding gas limit of the L1 costs (you can find more information about the role of the L1 costs in a transaction's gas limit in [this article](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9)). The gas limit corresponding to L1 costs is practically unlimited, leading to the possibility of finding very high values on the gasLimit field of a block.\n\nThe effective block gas limit (32 million) only accounts for execution gas limit. We can check the actual gas used for execution on a specific block by checking the gasUsed field.\n\n",
+ "key": "why-do-some-blocks-have-a-total-gas-limit-thats-over-the-standard-block-gas-limit"
+ }
+]
diff --git a/static/building-orbit-faqs.json b/static/building-orbit-faqs.json
index 5427b252d5..e096404e32 100644
--- a/static/building-orbit-faqs.json
+++ b/static/building-orbit-faqs.json
@@ -1,33 +1,157 @@
[
-{"question": "Can I use Orbit to deploy a mainnet chain?","answer": "Yes! Arbitrum Orbit's core technology has undergone a comprehensive audit and is now capable of supporting deployments to mainnet. You can read more about it [here](https://docs.arbitrum.io/launch-orbit-chain/concepts/public-preview-expectations#arbitrum-orbit-is-mainnet-ready-but-deploy-to-testnet-first).\n\n\n\n","key": "can-i-use-orbit-to-deploy-a-mainnet-chain"},
-{"question": "Do I need permission/license to launch an Orbit chain?","answer": "You can launch any Arbitrum Orbit chain permissionlessly.\n\nNitro's license is under a [Business Source license](https://github.com/OffchainLabs/nitro?tab=License-1-ov-file), similar to DeFi protocols like Uniswap and Aave, among others. This license contains an Additional Use Grant that permits the permissionless deployment of Nitro software on blockchains that settle to Arbitrum One or Nova.\n\nHowever, Arbitrum Orbit chains that settle to a parent chain other than Arbitrum One or Nova are subject to additional licensing guidelines under the [AEP](https://docs.arbitrum.foundation/aep/ArbitrumExpansionProgramTerms.pdf).\n\n","key": "do-i-need-permissionlicense-to-launch-an-orbit-chain"},
-{"question": "Does Arbitrum officially deploy and/or maintain L3s for external teams?","answer": "No. Teams are required to deploy and maintain their Arbitrum Orbit chains. There are, however, several RaaS (Rollup as a Service) providers that can deploy and maintain your Arbitrum Orbit chain on your behalf.\n\n\n\n","key": "does-arbitrum-officially-deploy-andor-maintain-l3s-for-external-teams"},
-{"question": "Can I modify Orbit's underlying technology to customize my chain?","answer": "Yes, you can make any changes you require to the underlying Nitro code base.\n\n\n\n","key": "can-i-modify-orbits-underlying-technology-to-customize-my-chain"},
-{"question": "What Data Availability (DA) solutions are currently available for Orbit chains?","answer": "Arbitrum Orbit currently supports three different DA solutions:\n\n- Rollup, posting data to the parent chain, which ultimately posts the data to Ethereum.\n- AnyTrust, posting data to a Data Availability Committee, selected by the chain owner.\n- Celestia, posting data to the [Celestia network](https://blog.celestia.org/celestia-is-first-modular-data-availability-network-to-integrate-with-arbitrum-orbit/).\nNote that using AnyTrust provides the chain owner with the most flexibility and the most cost-effective fees.\n\n","key": "what-data-availability-da-solutions-are-currently-available-for-orbit-chains"},
-{"question": "What token is used to pay gas fees on Orbit chains?","answer": "By default, Arbitrum Orbit chains pay gas in `ETH`. However, Arbitrum Orbit chains that use AnyTrust are configurable to use any `ERC-20` token for the gas fee token of the chain.\n\n\n\n","key": "what-token-is-used-to-pay-gas-fees-on-orbit-chains"},
-{"question": "Can I use Ethereum toolkits to develop on my Orbit chain?","answer": "Arbitrum Orbit chains are fully EVM-compatible. Most tools that support Ethereum should be able to support an Arbitrum Orbit chain. There are, however, specific differences that developers need to consider when building on an Orbit chain. You can find them [here](https://docs.arbitrum.io/for-devs/concepts/differences-between-arbitrum-ethereum/overview).\n\n\n\n","key": "can-i-use-ethereum-toolkits-to-develop-on-my-orbit-chain"},
-{"question": "Do Orbit chains have any built-in AA solution?","answer": "Not by default, but they can be customized to have native AA.\n\n","key": "do-orbit-chains-have-any-builtin-aa-solution"},
-{"question": "Is there any cross-chain bridging solution between two Orbit chains?","answer": "There is currently no native Orbit-to-Orbit chain bridging solution, except for going through the parent chain (even if they share the same parent chain). However, many third-party bridges have expressed interest in supporting Arbitrum Orbit chains.\n\n\n\n","key": "is-there-any-crosschain-bridging-solution-between-two-orbit-chains"},
-{"question": "Is there an official block explorer for Orbit chains?","answer": "Arbitrum Orbit chains deployments usually come with an open-source Blockscout explorer by default, but there are many third-party solutions that have expressed interest in supporting Arbitrum Orbit chains.\n\n\n\n","key": "is-there-an-official-block-explorer-for-orbit-chains"},
-{"question": "Is there any indexing solution that supports Orbit chains?","answer": "Similar to bridges and block explorers, there are many third-party indexing solutions that have expressed interest in supporting Arbitrum Orbit chains.\n\n\n\n","key": "is-there-any-indexing-solution-that-supports-orbit-chains"},
-{"question": "Can I increase the maximum contract size for my Orbit chain?","answer": "Yes, Arbitrum Orbit chains support an increased smart contract size limit of up to 96kB. You can use our [Orbit SDK](https://github.com/OffchainLabs/arbitrum-orbit-sdk) and configure the parameters `[MaxCodeSize](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/src/prepareChainConfig.ts#L29)`[ and ](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/src/prepareChainConfig.ts#L29)`[MaxInitCodeSize](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/src/prepareChainConfig.ts#L29)` when calling `[prepareNodeConfig](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/examples/prepare-node-config/index.ts#L43)`. Once deployed, you cannot change the parameters for the smart contract size limit through an upgrade.\n\n\n\n","key": "can-i-increase-the-maximum-contract-size-for-my-orbit-chain"},
-{"question": "How can I modify Nitro to force posting an invalid assertion and test the fraud proof mechanism?","answer": "Forcing an invalid assertion in the chain is not currently supported. However, if you're building Nitro locally, you can run the following test that goes through the whole rollup/challenge mechanism:\n\n```shell\ngo test ./system_tests/ -tags=challengetest -run=TestChallenge\n\n```\n\n\n","key": "how-can-i-modify-nitro-to-force-posting-an-invalid-assertion-and-test-the-fraud-proof-mechanism"},
-{"question": "What fee collectors can be configured on my chain?","answer": "Four fee types are configurable on an Orbit chain:\n\n- **L2 base fee**: L2 execution fees corresponding to the minimum base price of the chain. This fee is deposited into the infraFeeAccount, which can be set by calling `ArbOwner.setInfraFeeAccount().`\n- **L2 surplus fee**: L2 execution fees above the minimum base price (in the case of congestion). This fee goes to the `networkFeeAccount`, which can be set by calling `ArbOwner.setNetworkFeeAccount().`\n- **L1 base fee**: Relative fees for posting a transaction on the parent chain. This fee is paid ultimately to the fee collector of the active batch poster. A call to `SequencerInbox.setIsBatchPoster()` on the parent chain will set the batch poster. Delegating a different fee collector for that batch poster can be specified by calling `ArbAggregator.setFeeCollector()`.\n- **L1 surplus fee**: Any extra fees rewarded to the batch poster. This is paid to a specific `L1RewardRecipient`, which can be set by calling `ArbOwner.setL1PricingRewardRecipient()`.\nFor more detailed information about fees, please refer to the [L1 Fees](https://docs.arbitrum.io/arbos/l1-pricing) and [L2 Fees](https://docs.arbitrum.io/arbos/gas) pages.\n\nTo learn more about precompiles, refer to the [Precompiles reference page](https://docs.arbitrum.io/build-decentralized-apps/precompiles/reference).\n\n","key": "what-fee-collectors-can-be-configured-on-my-chain"},
-{"question": "What is the lowest you can set the base fee to?","answer": "You can set the base fee to any amount to charge users less. You can even set it to `0` (however, this would open the chain to DOS attacks). If the Orbit base fee is `0`, users are then only paying for the cost of DA.\n\n","key": "what-is-the-lowest-you-can-set-the-base-fee-to"},
-{"question": "How does fee collection work in Nitro?","answer": "Four fee types are configurable on Nitro:\n\n- **L2 base fee**: L2 execution fees corresponding to the minimum base price of the chain. This is paid to the `infraFeeAccount`, and you can set it by calling `ArbOwner.setInfraFeeAccount()`.\n- **L2 surplus fee**: L2 execution fees above the minimum base price (in the case of congestion). This is paid to the `networkFeeAccount`, and you can set it by calling `ArbOwner.setNetworkFeeAccount()`.\n- **L1 base fee**: Relative fees for posting this transaction on the parent chain. This is paid ultimately to the fee collector of the active batch poster. You can set the batch poster by calling `SequencerInbox.setIsBatchPoster()`, on the parent chain, and specify a different fee collector for that batch poster by calling `ArbAggregator.setFeeCollector()`.\n- **L1 surplus fee**: Any extra fees rewarded to the batch poster. This is paid to a specific `L1RewardRecipient`, and you can set it by calling `ArbOwner.setL1PricingRewardRecipient()`\nYou can find more detailed information about fees in these pages:\n\n- [L1 fees](https://docs.arbitrum.io/arbos/l1-pricing)\n\n- [L2 fees](https://docs.arbitrum.io/arbos/gas) \n\nAnd information about the precompiles methods in the [Precompile References](https://docs.arbitrum.io/build-decentralized-apps/precompiles/reference).\n\n\n\n","key": "how-does-fee-collection-work-in-nitro"},
-{"question": "Can you upgrade the smart contract size limit once deployed?","answer": "No. There's no way to version it so that old blocks are executed under the past limit and new blocks are executed for the new limit. \n\n","key": "can-you-upgrade-the-smart-contract-size-limit-once-deployed"},
-{"question": "Can you set the block speed below 100ms?","answer": "The implications of reducing the block speed below 100ms are that an increased block count will put more strain on third-party providers, node runners, indexers, etc.\n\n","key": "can-you-set-the-block-speed-below-100ms"},
-{"question": "Can I set fast deposits for an L3?","answer": "Yes, we have documented fast deposits in [how to configure delayed inbox finality](https://www.notion.so/launch-arbitrum-chain/how-tos/arbitrum-chain-finality.mdx).\n\n\n\nThere is a flag that can be changed, which allows an Arbitrum chain to wait for finality on the parent chain before depositing a transaction.\n\n\nFor an L3 on Arb One, for example, we consider this a feature because they can instantly register a deposit on the child chain, as Arb One has an ultra-low re-org risk (having never re-organized).\n\n\nFor an L2, however, we recommend waiting ~12 minutes for L1 finality, as there is a greater risk of reorganization, for example, the deposit transaction not being included immediately in the fork-choice.\n\n","key": "can-i-set-fast-deposits-for-an-l3"},
-{"question": "How do I increase the max transaction data size?","answer": "**Warning: Always test first!!!**\n\nTest this thoroughly on a testnet first.\n\n1. This is a hard limit in the codebase to prevent DoS attacks. If you want to modify this, you'll need to follow this [procedure](https://www.notion.so/launch-arbitrum-chain/05-customize-your-chain/customize-stf.mdx) to create a new WASM module root with an updated max L2 message size. Other limits might also need to be updated, such as the maximum decompressed batch size. Be sure to modify everything starting with the latest version, which includes a couple of extra safety checks that may help prevent issues.\n2. You could disable this limit if you were confident you would stick to AnyTrust and not need to fall back to posting data onchain.\n3. Defaults are in place for non-AnyTrust batch posting, which would need to fit the L3 user's transaction into a batch posted as an L2 transaction, thus respecting L2 transaction size limits.\n","key": "how-do-i-increase-the-max-transaction-data-size"},
-{"question": "What is the max theoretical TPS for an Arbitrum Chain?","answer": "Max TPS is a challenging metric to measure, as it relies on network activity and the type of submitted transactions. We can, however, calculate the max throughput using default orbit chain parameters.\n\nThe actual maximum throughput depends on the configurable execution parameters:\n\n**Using standard Arbitrum chain defaults**\n\n- Block time: 250ms\n- Block gas limit: 32M L2 gas\n- Max L2 gas per second: 128M gas/sec\n- These parameters are entirely configurable, for example, by dropping the block time to 100ms or by increasing the block gas limit (which comes at the cost of faster state bloat).\n- Dropping to 100ms and doubling the block gas limit to 64m L2 gas would achieve 640m L2 gas per second.\n**The actual TPS varies depending on the gas cost per transaction:**\n\n- A simple transfer (~21,000 gas) could approximately achieve around 6,000 TPS.\n- A more complex transaction (~200,000 gas) would enable approximately 640 TPS.\n","key": "what-is-the-max-theoretical-tps-for-an-arbitrum-chain"},
-{"question": "Why is the WETH Gateway not necessary for custom gas token chains?","answer": "The `WETH` gateway used in the token bridge is a special, custom gateway that unwraps the `WETH` deposits and sends them to the Arbitrum chain, then wraps them again on the Arbitrum chain. Since `ETH` is the gas token in the Arbitrum (Orbit) chain, there's no need to perform this operation, so you can use a standard `ERC-20` for `WETH` (this is the default case of the token bridge so that you wouldn't need a special `WETH` gateway).\n\nIf you want to enable extra custom operations with `WETH`, you can create a custom token and a custom gateway to handle this case.\n\n","key": "why-is-the-weth-gateway-not-necessary-for-custom-gas-token-chains"},
-{"question": "How do we verify if an ERC-20 was bridged using the native bridge?","answer": "The following applies to a parent-side bridge deployed on Arbitrum One:\nIf the token was bridged using the native token bridge, you can go to [parent_side_bridge_contract](https://github.com/OffchainLabs/token-bridge-contracts/blob/5bdf33259d2d9ae52ddc69bc5a9cbc558c4c40c7/contracts/tokenbridge/arbitrum/gateway/L2ERC20Gateway.sol#L47)\n\n\n\nCall the `calculateL2TokenAddress` address with the address of the token on the parent chain.\n\n\nFor example, in the case of plugging in the `USDT` address on Arbitrum One `0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9`, you get `0xB2C565cd7e807e6A1C38bFE32D8FAb9c96ffCeCa`.\n\n","key": "how-do-we-verify-if-an-erc20-was-bridged-using-the-native-bridge"},
-{"question": "What are the estimated infrastructure costs to run the Sequencer?","answer": "The estimated cost is approximately $600 per sequencer replica per month for a low-to-medium activity chain. With networking and storage included, the estimated monthly cost would be $1,500 for the Sequencer.\n\n","key": "what-are-the-estimated-infrastructure-costs-to-run-the-sequencer"},
-{"question": "What are the different validator modes?","answer": "- **Defensive (allowlist required)**:- Post stake and create a challenge if local state disagrees with the onchain assertion (wallet required, will only post stake onchain if a bad assertion is found.\n\n- **StakeLatest (allowlist required)**:- Stay staked on the latest assertion and challenge any bad assertions found (wallet required, always staked, uses some gas every time new assertion created)\n\n- **ResolveNodes (allowlist required)**:- Stay staked on the latest assertion, resolve any unconfirmed assertions, and challenge any bad assertions found (wallet required, always staked, uses some gas every time an unconfirmed assertion is resolved or a new assertion is created)\n\n- **MakeNodes (allowlist required)**:- Continuously create new assertions, challenging any bad assertions found (wallet required, always staked, most expensive node to run)\n- Note that if there is more than one MakeNodes validator running, they might all try to create a new assertion at the same time. In that case, only one will be successful, and the others will have still spent gas on reverted calls that did nothing.\n\n- **Watchtower**:- A node in Watchtower mode will immediately log an error if an onchain assertion deviates from the locally computed chain state. It doesn't require a wallet, as it never takes any action onchain. This mode is the default-enabled strategy for all nodes (full and archive).\n\n","key": "what-are-the-different-validator-modes"},
-{"question": "What are the costs to run a validator?","answer": "The estimated monthly cost for Watchtower validators will be approximately $500. All other validators will cost $800 to $900 per month.\n\n","key": "what-are-the-costs-to-run-a-validator"},
-{"question": "What is the amount of funds that a validator needs in its wallet to participate in fraud proofs?","answer": "To participate in a fraud-proof game, your validator will need funds (can be any `ERC-20`) for two things:\n\n1. Gas costs to post assertions- Depends on your parent chain and is estimated to cost 163109 gas per assertion. If you assume one assertion per hour, then you can multiply your gas cost per hour to calculate the annual cost. This assumption holds under normal operation, but during a challenge, you may post more assertions (these will scale with the number of challenges), so it might be one assertion every 10 minutes, depending on how many challenges are ongoing.\n\n2. Bonds to participate- Depends on your config. You can set the bond amounts to be any amount you want. For Arbitrum One, this is 3600 `ETH` initially and then 555+79 `ETH` per each subsequent challenge. These amounts were carefully selected and designed, with extensive research behind them, specifically for Arbitrum One. There could be one or multiple challenges, and so there will always be a possibility where more funds are needed.\n\n","key": "what-is-the-amount-of-funds-that-a-validator-needs-in-its-wallet-to-participate-in-fraud-proofs"},
-{"question": "How do I export snapshots for nitro-based chains? Is there any tooling for this?","answer": "We currently don't have any toolkits available for this. The best way to make a snapshot is to gracefully stop the node and make a copy of the database.\n\n","key": "how-do-i-export-snapshots-for-nitrobased-chains-is-there-any-tooling-for-this"},
-{"question": "What happens if I don't post an assertion for a long period of time?","answer": "Over time, without creating assertions, the validator whitelist in the Rollup contract can become disabled. If you look at the `[removeWhitelistAfterValidatorAfk](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/rollup/RollupUserLogic.sol#L62)` method, it allows you to disable the whitelist after `confirmPeriodBlocks + VALIDATOR_AFK_BLOCKS` L1 blocks have passed since the last assertion created.\n\nAs a default, that's 7200 + 45818 blocks (a bit less than eight days). Disabling the whitelist is not a significant issue if you continue to monitor the chain and run a validator. It can be enabled using `[setValidatorWhitelistDisabled()](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/rollup/RollupAdminLogic.sol#L378)` by the chain owner. But it's always better to avoid reaching that point.\n\n","key": "what-happens-if-i-dont-post-an-assertion-for-a-long-period-of-time"},
-{"question": "Is there a way to increase idle timeout on RPC nodes for websocket connections?","answer": "There is no way to increase the idle timeout for WebSocket connections via configuration options (geth doesn't provide this, and neither do we). The default value in Geth for the idle timeout is, as noted in [the query](https://github.com/OffchainLabs/go-ethereum/blob/85dc1b7ed058bea72a2707e59f5878815dd00485/rpc/websocket.go#L38), 30 seconds.\n\n","key": "is-there-a-way-to-increase-idle-timeout-on-rpc-nodes-for-websocket-connections"},
-{"question": "How do I run a split validator?","answer": "Using Nitro's split validation, it can be run as a separate container using:\n\n```plain text\nnode.block-validator.validation-server-configs-list\n```\nIt's possible to run it in the same container. That is the default way, and then Nitro uses a loopback connection. You can read more about this in [running a split-validator](https://www.notion.so/run-arbitrum-node/more-types/04-run-split-validator-node.mdx).\n\n","key": "how-do-i-run-a-split-validator"}
-]
\ No newline at end of file
+ {
+ "question": "Can I use Orbit to deploy a mainnet chain?",
+ "answer": "Yes! Arbitrum Orbit's core technology has undergone a comprehensive audit and is now capable of supporting deployments to mainnet. You can read more about it [here](https://docs.arbitrum.io/launch-orbit-chain/concepts/public-preview-expectations#arbitrum-orbit-is-mainnet-ready-but-deploy-to-testnet-first).\n\n\n\n",
+ "key": "can-i-use-orbit-to-deploy-a-mainnet-chain"
+ },
+ {
+ "question": "Do I need permission/license to launch an Orbit chain?",
+ "answer": "You can launch any Arbitrum Orbit chain permissionlessly.\n\nNitro's license is under a [Business Source license](https://github.com/OffchainLabs/nitro?tab=License-1-ov-file), similar to DeFi protocols like Uniswap and Aave, among others. This license contains an Additional Use Grant that permits the permissionless deployment of Nitro software on blockchains that settle to Arbitrum One or Nova.\n\nHowever, Arbitrum Orbit chains that settle to a parent chain other than Arbitrum One or Nova are subject to additional licensing guidelines under the [AEP](https://docs.arbitrum.foundation/aep/ArbitrumExpansionProgramTerms.pdf).\n\n",
+ "key": "do-i-need-permissionlicense-to-launch-an-orbit-chain"
+ },
+ {
+ "question": "Does Arbitrum officially deploy and/or maintain L3s for external teams?",
+ "answer": "No. Teams are required to deploy and maintain their Arbitrum Orbit chains. There are, however, several RaaS (Rollup as a Service) providers that can deploy and maintain your Arbitrum Orbit chain on your behalf.\n\n\n\n",
+ "key": "does-arbitrum-officially-deploy-andor-maintain-l3s-for-external-teams"
+ },
+ {
+ "question": "Can I modify Orbit's underlying technology to customize my chain?",
+ "answer": "Yes, you can make any changes you require to the underlying Nitro code base.\n\n\n\n",
+ "key": "can-i-modify-orbits-underlying-technology-to-customize-my-chain"
+ },
+ {
+ "question": "What Data Availability (DA) solutions are currently available for Orbit chains?",
+ "answer": "Arbitrum Orbit currently supports three different DA solutions:\n\n- Rollup, posting data to the parent chain, which ultimately posts the data to Ethereum.\n- AnyTrust, posting data to a Data Availability Committee, selected by the chain owner.\n- Celestia, posting data to the [Celestia network](https://blog.celestia.org/celestia-is-first-modular-data-availability-network-to-integrate-with-arbitrum-orbit/).\nNote that using AnyTrust provides the chain owner with the most flexibility and the most cost-effective fees.\n\n",
+ "key": "what-data-availability-da-solutions-are-currently-available-for-orbit-chains"
+ },
+ {
+ "question": "What token is used to pay gas fees on Orbit chains?",
+ "answer": "By default, Arbitrum Orbit chains pay gas in `ETH`. However, Arbitrum Orbit chains that use AnyTrust are configurable to use any `ERC-20` token for the gas fee token of the chain.\n\n\n\n",
+ "key": "what-token-is-used-to-pay-gas-fees-on-orbit-chains"
+ },
+ {
+ "question": "Can I use Ethereum toolkits to develop on my Orbit chain?",
+ "answer": "Arbitrum Orbit chains are fully EVM-compatible. Most tools that support Ethereum should be able to support an Arbitrum Orbit chain. There are, however, specific differences that developers need to consider when building on an Orbit chain. You can find them [here](https://docs.arbitrum.io/for-devs/concepts/differences-between-arbitrum-ethereum/overview).\n\n\n\n",
+ "key": "can-i-use-ethereum-toolkits-to-develop-on-my-orbit-chain"
+ },
+ {
+ "question": "Do Orbit chains have any built-in AA solution?",
+ "answer": "Not by default, but they can be customized to have native AA.\n\n",
+ "key": "do-orbit-chains-have-any-builtin-aa-solution"
+ },
+ {
+ "question": "Is there any cross-chain bridging solution between two Orbit chains?",
+ "answer": "There is currently no native Orbit-to-Orbit chain bridging solution, except for going through the parent chain (even if they share the same parent chain). However, many third-party bridges have expressed interest in supporting Arbitrum Orbit chains.\n\n\n\n",
+ "key": "is-there-any-crosschain-bridging-solution-between-two-orbit-chains"
+ },
+ {
+ "question": "Is there an official block explorer for Orbit chains?",
+ "answer": "Arbitrum Orbit chains deployments usually come with an open-source Blockscout explorer by default, but there are many third-party solutions that have expressed interest in supporting Arbitrum Orbit chains.\n\n\n\n",
+ "key": "is-there-an-official-block-explorer-for-orbit-chains"
+ },
+ {
+ "question": "Is there any indexing solution that supports Orbit chains?",
+ "answer": "Similar to bridges and block explorers, there are many third-party indexing solutions that have expressed interest in supporting Arbitrum Orbit chains.\n\n\n\n",
+ "key": "is-there-any-indexing-solution-that-supports-orbit-chains"
+ },
+ {
+ "question": "Can I increase the maximum contract size for my Orbit chain?",
+ "answer": "Yes, Arbitrum Orbit chains support an increased smart contract size limit of up to 96kB. You can use our [Orbit SDK](https://github.com/OffchainLabs/arbitrum-orbit-sdk) and configure the parameters `[MaxCodeSize](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/src/prepareChainConfig.ts#L29)`[ and ](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/src/prepareChainConfig.ts#L29)`[MaxInitCodeSize](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/src/prepareChainConfig.ts#L29)` when calling `[prepareNodeConfig](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/examples/prepare-node-config/index.ts#L43)`. Once deployed, you cannot change the parameters for the smart contract size limit through an upgrade.\n\n\n\n",
+ "key": "can-i-increase-the-maximum-contract-size-for-my-orbit-chain"
+ },
+ {
+ "question": "How can I modify Nitro to force posting an invalid assertion and test the fraud proof mechanism?",
+ "answer": "Forcing an invalid assertion in the chain is not currently supported. However, if you're building Nitro locally, you can run the following test that goes through the whole rollup/challenge mechanism:\n\n```shell\ngo test ./system_tests/ -tags=challengetest -run=TestChallenge\n\n```\n\n\n",
+ "key": "how-can-i-modify-nitro-to-force-posting-an-invalid-assertion-and-test-the-fraud-proof-mechanism"
+ },
+ {
+ "question": "What fee collectors can be configured on my chain?",
+ "answer": "Four fee types are configurable on an Orbit chain:\n\n- **L2 base fee**: L2 execution fees corresponding to the minimum base price of the chain. This fee is deposited into the infraFeeAccount, which can be set by calling `ArbOwner.setInfraFeeAccount().`\n- **L2 surplus fee**: L2 execution fees above the minimum base price (in the case of congestion). This fee goes to the `networkFeeAccount`, which can be set by calling `ArbOwner.setNetworkFeeAccount().`\n- **L1 base fee**: Relative fees for posting a transaction on the parent chain. This fee is paid ultimately to the fee collector of the active batch poster. A call to `SequencerInbox.setIsBatchPoster()` on the parent chain will set the batch poster. Delegating a different fee collector for that batch poster can be specified by calling `ArbAggregator.setFeeCollector()`.\n- **L1 surplus fee**: Any extra fees rewarded to the batch poster. This is paid to a specific `L1RewardRecipient`, which can be set by calling `ArbOwner.setL1PricingRewardRecipient()`.\nFor more detailed information about fees, please refer to the [L1 Fees](https://docs.arbitrum.io/arbos/l1-pricing) and [L2 Fees](https://docs.arbitrum.io/arbos/gas) pages.\n\nTo learn more about precompiles, refer to the [Precompiles reference page](https://docs.arbitrum.io/build-decentralized-apps/precompiles/reference).\n\n",
+ "key": "what-fee-collectors-can-be-configured-on-my-chain"
+ },
+ {
+ "question": "What is the lowest you can set the base fee to?",
+ "answer": "You can set the base fee to any amount to charge users less. You can even set it to `0` (however, this would open the chain to DOS attacks). If the Orbit base fee is `0`, users are then only paying for the cost of DA.\n\n",
+ "key": "what-is-the-lowest-you-can-set-the-base-fee-to"
+ },
+ {
+ "question": "How does fee collection work in Nitro?",
+ "answer": "Four fee types are configurable on Nitro:\n\n- **L2 base fee**: L2 execution fees corresponding to the minimum base price of the chain. This is paid to the `infraFeeAccount`, and you can set it by calling `ArbOwner.setInfraFeeAccount()`.\n- **L2 surplus fee**: L2 execution fees above the minimum base price (in the case of congestion). This is paid to the `networkFeeAccount`, and you can set it by calling `ArbOwner.setNetworkFeeAccount()`.\n- **L1 base fee**: Relative fees for posting this transaction on the parent chain. This is paid ultimately to the fee collector of the active batch poster. You can set the batch poster by calling `SequencerInbox.setIsBatchPoster()`, on the parent chain, and specify a different fee collector for that batch poster by calling `ArbAggregator.setFeeCollector()`.\n- **L1 surplus fee**: Any extra fees rewarded to the batch poster. This is paid to a specific `L1RewardRecipient`, and you can set it by calling `ArbOwner.setL1PricingRewardRecipient()`\nYou can find more detailed information about fees in these pages:\n\n- [L1 fees](https://docs.arbitrum.io/arbos/l1-pricing)\n\n- [L2 fees](https://docs.arbitrum.io/arbos/gas) \n\nAnd information about the precompiles methods in the [Precompile References](https://docs.arbitrum.io/build-decentralized-apps/precompiles/reference).\n\n\n\n",
+ "key": "how-does-fee-collection-work-in-nitro"
+ },
+ {
+ "question": "Can you upgrade the smart contract size limit once deployed?",
+ "answer": "No. There's no way to version it so that old blocks are executed under the past limit and new blocks are executed for the new limit. \n\n",
+ "key": "can-you-upgrade-the-smart-contract-size-limit-once-deployed"
+ },
+ {
+ "question": "Can you set the block speed below 100ms?",
+ "answer": "The implications of reducing the block speed below 100ms are that an increased block count will put more strain on third-party providers, node runners, indexers, etc.\n\n",
+ "key": "can-you-set-the-block-speed-below-100ms"
+ },
+ {
+ "question": "Can I set fast deposits for an L3?",
+ "answer": "Yes, we have documented fast deposits in [how to configure delayed inbox finality](https://www.notion.so/launch-arbitrum-chain/how-tos/arbitrum-chain-finality.mdx).\n\n\n\nThere is a flag that can be changed, which allows an Arbitrum chain to wait for finality on the parent chain before depositing a transaction.\n\n\nFor an L3 on Arb One, for example, we consider this a feature because they can instantly register a deposit on the child chain, as Arb One has an ultra-low re-org risk (having never re-organized).\n\n\nFor an L2, however, we recommend waiting ~12 minutes for L1 finality, as there is a greater risk of reorganization, for example, the deposit transaction not being included immediately in the fork-choice.\n\n",
+ "key": "can-i-set-fast-deposits-for-an-l3"
+ },
+ {
+ "question": "How do I increase the max transaction data size?",
+ "answer": "**Warning: Always test first!!!**\n\nTest this thoroughly on a testnet first.\n\n1. This is a hard limit in the codebase to prevent DoS attacks. If you want to modify this, you'll need to follow this [procedure](https://www.notion.so/launch-arbitrum-chain/05-customize-your-chain/customize-stf.mdx) to create a new WASM module root with an updated max L2 message size. Other limits might also need to be updated, such as the maximum decompressed batch size. Be sure to modify everything starting with the latest version, which includes a couple of extra safety checks that may help prevent issues.\n2. You could disable this limit if you were confident you would stick to AnyTrust and not need to fall back to posting data onchain.\n3. Defaults are in place for non-AnyTrust batch posting, which would need to fit the L3 user's transaction into a batch posted as an L2 transaction, thus respecting L2 transaction size limits.\n",
+ "key": "how-do-i-increase-the-max-transaction-data-size"
+ },
+ {
+ "question": "What is the max theoretical TPS for an Arbitrum Chain?",
+ "answer": "Max TPS is a challenging metric to measure, as it relies on network activity and the type of submitted transactions. We can, however, calculate the max throughput using default orbit chain parameters.\n\nThe actual maximum throughput depends on the configurable execution parameters:\n\n**Using standard Arbitrum chain defaults**\n\n- Block time: 250ms\n- Block gas limit: 32M L2 gas\n- Max L2 gas per second: 128M gas/sec\n- These parameters are entirely configurable, for example, by dropping the block time to 100ms or by increasing the block gas limit (which comes at the cost of faster state bloat).\n- Dropping to 100ms and doubling the block gas limit to 64m L2 gas would achieve 640m L2 gas per second.\n**The actual TPS varies depending on the gas cost per transaction:**\n\n- A simple transfer (~21,000 gas) could approximately achieve around 6,000 TPS.\n- A more complex transaction (~200,000 gas) would enable approximately 640 TPS.\n",
+ "key": "what-is-the-max-theoretical-tps-for-an-arbitrum-chain"
+ },
+ {
+ "question": "Why is the WETH Gateway not necessary for custom gas token chains?",
+ "answer": "The `WETH` gateway used in the token bridge is a special, custom gateway that unwraps the `WETH` deposits and sends them to the Arbitrum chain, then wraps them again on the Arbitrum chain. Since `ETH` is the gas token in the Arbitrum (Orbit) chain, there's no need to perform this operation, so you can use a standard `ERC-20` for `WETH` (this is the default case of the token bridge so that you wouldn't need a special `WETH` gateway).\n\nIf you want to enable extra custom operations with `WETH`, you can create a custom token and a custom gateway to handle this case.\n\n",
+ "key": "why-is-the-weth-gateway-not-necessary-for-custom-gas-token-chains"
+ },
+ {
+ "question": "How do we verify if an ERC-20 was bridged using the native bridge?",
+ "answer": "The following applies to a parent-side bridge deployed on Arbitrum One:\nIf the token was bridged using the native token bridge, you can go to [parent_side_bridge_contract](https://github.com/OffchainLabs/token-bridge-contracts/blob/5bdf33259d2d9ae52ddc69bc5a9cbc558c4c40c7/contracts/tokenbridge/arbitrum/gateway/L2ERC20Gateway.sol#L47)\n\n\n\nCall the `calculateL2TokenAddress` address with the address of the token on the parent chain.\n\n\nFor example, in the case of plugging in the `USDT` address on Arbitrum One `0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9`, you get `0xB2C565cd7e807e6A1C38bFE32D8FAb9c96ffCeCa`.\n\n",
+ "key": "how-do-we-verify-if-an-erc20-was-bridged-using-the-native-bridge"
+ },
+ {
+ "question": "What are the estimated infrastructure costs to run the Sequencer?",
+ "answer": "The estimated cost is approximately $600 per sequencer replica per month for a low-to-medium activity chain. With networking and storage included, the estimated monthly cost would be $1,500 for the Sequencer.\n\n",
+ "key": "what-are-the-estimated-infrastructure-costs-to-run-the-sequencer"
+ },
+ {
+ "question": "What are the different validator modes?",
+ "answer": "- **Defensive (allowlist required)**:- Post stake and create a challenge if local state disagrees with the onchain assertion (wallet required, will only post stake onchain if a bad assertion is found.\n\n- **StakeLatest (allowlist required)**:- Stay staked on the latest assertion and challenge any bad assertions found (wallet required, always staked, uses some gas every time new assertion created)\n\n- **ResolveNodes (allowlist required)**:- Stay staked on the latest assertion, resolve any unconfirmed assertions, and challenge any bad assertions found (wallet required, always staked, uses some gas every time an unconfirmed assertion is resolved or a new assertion is created)\n\n- **MakeNodes (allowlist required)**:- Continuously create new assertions, challenging any bad assertions found (wallet required, always staked, most expensive node to run)\n- Note that if there is more than one MakeNodes validator running, they might all try to create a new assertion at the same time. In that case, only one will be successful, and the others will have still spent gas on reverted calls that did nothing.\n\n- **Watchtower**:- A node in Watchtower mode will immediately log an error if an onchain assertion deviates from the locally computed chain state. It doesn't require a wallet, as it never takes any action onchain. This mode is the default-enabled strategy for all nodes (full and archive).\n\n",
+ "key": "what-are-the-different-validator-modes"
+ },
+ {
+ "question": "What are the costs to run a validator?",
+ "answer": "The estimated monthly cost for Watchtower validators will be approximately $500. All other validators will cost $800 to $900 per month.\n\n",
+ "key": "what-are-the-costs-to-run-a-validator"
+ },
+ {
+ "question": "What is the amount of funds that a validator needs in its wallet to participate in fraud proofs?",
+ "answer": "To participate in a fraud-proof game, your validator will need funds (can be any `ERC-20`) for two things:\n\n1. Gas costs to post assertions- Depends on your parent chain and is estimated to cost 163109 gas per assertion. If you assume one assertion per hour, then you can multiply your gas cost per hour to calculate the annual cost. This assumption holds under normal operation, but during a challenge, you may post more assertions (these will scale with the number of challenges), so it might be one assertion every 10 minutes, depending on how many challenges are ongoing.\n\n2. Bonds to participate- Depends on your config. You can set the bond amounts to be any amount you want. For Arbitrum One, this is 3600 `ETH` initially and then 555+79 `ETH` per each subsequent challenge. These amounts were carefully selected and designed, with extensive research behind them, specifically for Arbitrum One. There could be one or multiple challenges, and so there will always be a possibility where more funds are needed.\n\n",
+ "key": "what-is-the-amount-of-funds-that-a-validator-needs-in-its-wallet-to-participate-in-fraud-proofs"
+ },
+ {
+ "question": "How do I export snapshots for nitro-based chains? Is there any tooling for this?",
+ "answer": "We currently don't have any toolkits available for this. The best way to make a snapshot is to gracefully stop the node and make a copy of the database.\n\n",
+ "key": "how-do-i-export-snapshots-for-nitrobased-chains-is-there-any-tooling-for-this"
+ },
+ {
+ "question": "What happens if I don't post an assertion for a long period of time?",
+ "answer": "Over time, without creating assertions, the validator whitelist in the Rollup contract can become disabled. If you look at the `[removeWhitelistAfterValidatorAfk](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/rollup/RollupUserLogic.sol#L62)` method, it allows you to disable the whitelist after `confirmPeriodBlocks + VALIDATOR_AFK_BLOCKS` L1 blocks have passed since the last assertion created.\n\nAs a default, that's 7200 + 45818 blocks (a bit less than eight days). Disabling the whitelist is not a significant issue if you continue to monitor the chain and run a validator. It can be enabled using `[setValidatorWhitelistDisabled()](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/rollup/RollupAdminLogic.sol#L378)` by the chain owner. But it's always better to avoid reaching that point.\n\n",
+ "key": "what-happens-if-i-dont-post-an-assertion-for-a-long-period-of-time"
+ },
+ {
+ "question": "Is there a way to increase idle timeout on RPC nodes for websocket connections?",
+ "answer": "There is no way to increase the idle timeout for WebSocket connections via configuration options (geth doesn't provide this, and neither do we). The default value in Geth for the idle timeout is, as noted in [the query](https://github.com/OffchainLabs/go-ethereum/blob/85dc1b7ed058bea72a2707e59f5878815dd00485/rpc/websocket.go#L38), 30 seconds.\n\n",
+ "key": "is-there-a-way-to-increase-idle-timeout-on-rpc-nodes-for-websocket-connections"
+ },
+ {
+ "question": "How do I run a split validator?",
+ "answer": "Using Nitro's split validation, it can be run as a separate container using:\n\n```plain text\nnode.block-validator.validation-server-configs-list\n```\nIt's possible to run it in the same container. That is the default way, and then Nitro uses a loopback connection. You can read more about this in [running a split-validator](https://www.notion.so/run-arbitrum-node/more-types/04-run-split-validator-node.mdx).\n\n",
+ "key": "how-do-i-run-a-split-validator"
+ }
+]
diff --git a/static/building-stylus-faqs.json b/static/building-stylus-faqs.json
index 79f36327b6..d8017e2206 100644
--- a/static/building-stylus-faqs.json
+++ b/static/building-stylus-faqs.json
@@ -1,12 +1,52 @@
[
-{"question": "How does Stylus manage security issues in smart contracts when interacting with so many different languages?","answer": "All languages are compiled to WASM for them to be able to work with Stylus. So it just needs to verify that the produced WASM programs behave as they should inside the new virtual machine.\n\n\n\n","key": "how-does-stylus-manage-security-issues-in-smart-contracts-when-interacting-with-so-many-different-languages"},
-{"question": "Is there any analogue of the fallback function from Solidity in the Rust Stylus SDK?","answer": "Currently, there isn't any analogue. However, you can use a minimal entrypoint and perform raw delegate calls, forwarding your calldata. You can find more information in [the Bytes-in, Bytes-out programming](https://docs.arbitrum.io/stylus/reference/rust-sdk-guide#bytes-in-bytes-out-programming) and [call, static_call, and delegate_call](https://docs.arbitrum.io/stylus/reference/rust-sdk-guide#call-static_call-and-delegate_call) sections.\n\n\n\n","key": "is-there-any-analogue-of-the-fallback-function-from-solidity-in-the-rust-stylus-sdk"},
-{"question": "Is it possible to verify Stylus contracts on the block explorer?","answer": "Currently it is not possible to verify contracts compiled to WASM on the block explorer, but we are actively working with providers to have the verification process ready for when Stylus reaches mainnet-ready status.\n\n\n\n","key": "is-it-possible-to-verify-stylus-contracts-on-the-block-explorer"},
-{"question": "Do Stylus contracts compile down to EVM bytecode like prior other attempts?","answer": "No. Stylus contracts are compiled down to WASM. The user writes a program in Rust / C / C++ which is then compiled down to WebAssembly.\n\n\n\n","key": "do-stylus-contracts-compile-down-to-evm-bytecode-like-prior-other-attempts"},
-{"question": "How is a Stylus contract deployed?","answer": "Stylus contracts are deployed onchain as a blob of bytes, just like EVM ones. The only difference is that when the contract executes, instead of invoking the EVM, we invoke a separate WASM runtime. Note that a special EOF-inspired prefix distinguishes Stylus contracts from traditional EVM contracts: when a contract's bytecode starts with the magic `0xEFF00000` prefix, it's a Stylus WASM contract.\n\n\n\n","key": "how-is-a-stylus-contract-deployed"},
-{"question": "Is there a new transaction type to deploy Stylus contracts?","answer": "You deploy a Stylus contract the same way that Solidity contracts are deployed. There are no special transaction types. As a UX note: a WASM will revert until a special instrumentation operation is performed by a call to the new `ArbWasm` precompile, which readies the program for calls on-chain.\n\nYou can find instructions for deploying a Stylus contract in our [Quickstart](https://docs.arbitrum.io/stylus/stylus-quickstart#checking-your-stylus-project-is-valid).\n\n","key": "is-there-a-new-transaction-type-to-deploy-stylus-contracts"},
-{"question": "Do Stylus contracts use a different type of ABI?","answer": "Stylus contracts use solidity ABIs. Methods, signatures, logs, calls, etc. work exactly as in the EVM. From a user's / explorer's perspective, it all just looks and behaves like Solidity.\n\n\n\n","key": "do-stylus-contracts-use-a-different-type-of-abi"},
-{"question": "Does the Stylus SDK for Rust support custom data structures?","answer": "For in-memory usage, you should be able to use any implementation of custom data structures without problems.\n\nFor storage usage, it may be more complicated. Stylus uses the EVM storage system, so you'll need to define the data structure on top of it. However, in the SDK, there's a storage trait that custom types can implement to back their collections with the EVM state trie. The SDK macros are also compatible with them, although it's still fundamentally a global key-value system.\n\nYou can read more about it in the [Stylus Rust SDK page](https://docs.arbitrum.io/stylus/reference/rust-sdk-guide#storage).\n\nAs an alternative solution, you can use [entrypoint-style contracts](https://docs.arbitrum.io/stylus/reference/rust-sdk-guide#bytes-in-bytes-out-programming) for your custom data structures.\n\n","key": "does-the-stylus-sdk-for-rust-support-custom-data-structures"},
-{"question": "Why do I get an error \"no library targets found in package\" when trying to compile and old example?","answer": "Some of the first Stylus examples were built and deployed using a previous version of [cargo-stylus](https://github.com/OffchainLabs/cargo-stylus) (`0.1.x`). In that version, Stylus projects were structured as regular Rust binaries.\n\nSince [cargo-stylus v0.2.1](https://github.com/OffchainLabs/cargo-stylus/releases/tag/v0.2.1), Stylus projects are structured as libraries, so when trying to compile old projects you might get an error `no library targets found in package`.\n\nTo solve this, it's usually enough to rename the `main.rs` file to a `lib.rs` file.\n\n\n\n","key": "why-do-i-get-an-error-no-library-targets-found-in-package-when-trying-to-compile-and-old-example"},
-{"question": "How can I generate the ABI of my Stylus contract?","answer": "The [cargo-stylus tool](https://github.com/OffchainLabs/cargo-stylus/tree/main#exporting-solidity-abis) has a command that allows you to export the ABI of your Stylus contract: `cargo stylus export-abi`.\n\nIf you're using the Stylus Rust SDK, you'll need to enable the `export-abi` feature in your `Cargo.toml` file like so:\n\n```rust\n[features]\nexport-abi = [\"stylus-sdk/export-abi\"]\n```\nYou'll also need to have a `main.rs` file that selects that feature.\n\nThis is an example of a `main.rs` file that allows you to export the ABI of the [stylus-hello-world](https://github.com/OffchainLabs/stylus-hello-world) example project:\n\n```rust\n#![cfg_attr(not(feature = \"export-abi\"), no_main)]\n\n#[cfg(feature = \"export-abi\")]\nfn main() {\n stylus_hello_world::main();\n}\n```\n\n\n","key": "how-can-i-generate-the-abi-of-my-stylus-contract"}
-]
\ No newline at end of file
+ {
+ "question": "How does Stylus manage security issues in smart contracts when interacting with so many different languages?",
+ "answer": "All languages are compiled to WASM for them to be able to work with Stylus. So it just needs to verify that the produced WASM programs behave as they should inside the new virtual machine.\n\n\n\n",
+ "key": "how-does-stylus-manage-security-issues-in-smart-contracts-when-interacting-with-so-many-different-languages"
+ },
+ {
+ "question": "Is there any analogue of the fallback function from Solidity in the Rust Stylus SDK?",
+ "answer": "Currently, there isn't any analogue. However, you can use a minimal entrypoint and perform raw delegate calls, forwarding your calldata. You can find more information in [the Bytes-in, Bytes-out programming](https://docs.arbitrum.io/stylus/reference/rust-sdk-guide#bytes-in-bytes-out-programming) and [call, static_call, and delegate_call](https://docs.arbitrum.io/stylus/reference/rust-sdk-guide#call-static_call-and-delegate_call) sections.\n\n\n\n",
+ "key": "is-there-any-analogue-of-the-fallback-function-from-solidity-in-the-rust-stylus-sdk"
+ },
+ {
+ "question": "Is it possible to verify Stylus contracts on the block explorer?",
+ "answer": "Currently it is not possible to verify contracts compiled to WASM on the block explorer, but we are actively working with providers to have the verification process ready for when Stylus reaches mainnet-ready status.\n\n\n\n",
+ "key": "is-it-possible-to-verify-stylus-contracts-on-the-block-explorer"
+ },
+ {
+ "question": "Do Stylus contracts compile down to EVM bytecode like prior other attempts?",
+ "answer": "No. Stylus contracts are compiled down to WASM. The user writes a program in Rust / C / C++ which is then compiled down to WebAssembly.\n\n\n\n",
+ "key": "do-stylus-contracts-compile-down-to-evm-bytecode-like-prior-other-attempts"
+ },
+ {
+ "question": "How is a Stylus contract deployed?",
+ "answer": "Stylus contracts are deployed onchain as a blob of bytes, just like EVM ones. The only difference is that when the contract executes, instead of invoking the EVM, we invoke a separate WASM runtime. Note that a special EOF-inspired prefix distinguishes Stylus contracts from traditional EVM contracts: when a contract's bytecode starts with the magic `0xEFF00000` prefix, it's a Stylus WASM contract.\n\n\n\n",
+ "key": "how-is-a-stylus-contract-deployed"
+ },
+ {
+ "question": "Is there a new transaction type to deploy Stylus contracts?",
+ "answer": "You deploy a Stylus contract the same way that Solidity contracts are deployed. There are no special transaction types. As a UX note: a WASM will revert until a special instrumentation operation is performed by a call to the new `ArbWasm` precompile, which readies the program for calls on-chain.\n\nYou can find instructions for deploying a Stylus contract in our [Quickstart](https://docs.arbitrum.io/stylus/stylus-quickstart#checking-your-stylus-project-is-valid).\n\n",
+ "key": "is-there-a-new-transaction-type-to-deploy-stylus-contracts"
+ },
+ {
+ "question": "Do Stylus contracts use a different type of ABI?",
+ "answer": "Stylus contracts use solidity ABIs. Methods, signatures, logs, calls, etc. work exactly as in the EVM. From a user's / explorer's perspective, it all just looks and behaves like Solidity.\n\n\n\n",
+ "key": "do-stylus-contracts-use-a-different-type-of-abi"
+ },
+ {
+ "question": "Does the Stylus SDK for Rust support custom data structures?",
+ "answer": "For in-memory usage, you should be able to use any implementation of custom data structures without problems.\n\nFor storage usage, it may be more complicated. Stylus uses the EVM storage system, so you'll need to define the data structure on top of it. However, in the SDK, there's a storage trait that custom types can implement to back their collections with the EVM state trie. The SDK macros are also compatible with them, although it's still fundamentally a global key-value system.\n\nYou can read more about it in the [Stylus Rust SDK page](https://docs.arbitrum.io/stylus/reference/rust-sdk-guide#storage).\n\nAs an alternative solution, you can use [entrypoint-style contracts](https://docs.arbitrum.io/stylus/reference/rust-sdk-guide#bytes-in-bytes-out-programming) for your custom data structures.\n\n",
+ "key": "does-the-stylus-sdk-for-rust-support-custom-data-structures"
+ },
+ {
+ "question": "Why do I get an error \"no library targets found in package\" when trying to compile and old example?",
+ "answer": "Some of the first Stylus examples were built and deployed using a previous version of [cargo-stylus](https://github.com/OffchainLabs/cargo-stylus) (`0.1.x`). In that version, Stylus projects were structured as regular Rust binaries.\n\nSince [cargo-stylus v0.2.1](https://github.com/OffchainLabs/cargo-stylus/releases/tag/v0.2.1), Stylus projects are structured as libraries, so when trying to compile old projects you might get an error `no library targets found in package`.\n\nTo solve this, it's usually enough to rename the `main.rs` file to a `lib.rs` file.\n\n\n\n",
+ "key": "why-do-i-get-an-error-no-library-targets-found-in-package-when-trying-to-compile-and-old-example"
+ },
+ {
+ "question": "How can I generate the ABI of my Stylus contract?",
+ "answer": "The [cargo-stylus tool](https://github.com/OffchainLabs/cargo-stylus/tree/main#exporting-solidity-abis) has a command that allows you to export the ABI of your Stylus contract: `cargo stylus export-abi`.\n\nIf you're using the Stylus Rust SDK, you'll need to enable the `export-abi` feature in your `Cargo.toml` file like so:\n\n```rust\n[features]\nexport-abi = [\"stylus-sdk/export-abi\"]\n```\nYou'll also need to have a `main.rs` file that selects that feature.\n\nThis is an example of a `main.rs` file that allows you to export the ABI of the [stylus-hello-world](https://github.com/OffchainLabs/stylus-hello-world) example project:\n\n```rust\n#![cfg_attr(not(feature = \"export-abi\"), no_main)]\n\n#[cfg(feature = \"export-abi\")]\nfn main() {\n stylus_hello_world::main();\n}\n```\n\n\n",
+ "key": "how-can-i-generate-the-abi-of-my-stylus-contract"
+ }
+]
diff --git a/static/get-started-faqs.json b/static/get-started-faqs.json
index 5b3191668c..b3229e30ec 100644
--- a/static/get-started-faqs.json
+++ b/static/get-started-faqs.json
@@ -1,24 +1,112 @@
[
-{"question": "Why do I need ETH to use the Arbitrum network?","answer": "`ETH` is the currency used to pay gas fees on Arbitrum, and it powers all transactions on Arbitrum. You can bridge `ETH` (and other tokens) from Ethereum to Arbitrum through [Arbitrum's bridge](https://bridge.arbitrum.io/).\n\n\n\n","key": "why-do-i-need-eth-to-use-the-arbitrum-network"},
-{"question": "Do I need to pay a tip or priority fee for my Arbitrum transactions?","answer": "Transaction processing occurs in the order that the Sequencer receives them; no priority fee is necessary for Arbitrum transactions. If a transaction includes a priority fee, the origin address of the transaction will be refunded at the end of execution.\n\n","key": "do-i-need-to-pay-a-tip-or-priority-fee-for-my-arbitrum-transactions"},
-{"question": "How can I see the balance of ETH and other tokens in my wallet on Arbitrum?","answer": "Most wallets are \"connected\" to one given network at a time. To view your ETH or token balances, ensure that you have an established connection to the appropriate Arbitrum chain. In MetaMask and OKX Wallet, you can switch networks via the **Networks** drop-down. In this drop-down, please select the desired network (either Arbitrum One or Arbitrum Nova for our mainnet networks). If your preferred network hasn't been added to your wallet yet, you can add it via the [Arbitrum Bridge](https://bridge.arbitrum.io/).\n\n\n\n","key": "how-can-i-see-the-balance-of-eth-and-other-tokens-in-my-wallet-on-arbitrum"},
-{"question": "What happens if I send my funds to an exchange that doesn't support Arbitrum?","answer": "If you send the funds and the receiving wallet/exchange doesn't support the Arbitrum network you are sending funds through, unfortunately, there is nothing we can do to recover your funds. You would need to contact the wallet/exchange support and see if they can assist you in retrieving the funds.\n\n\n\n","key": "what-happens-if-i-send-my-funds-to-an-exchange-that-doesnt-support-arbitrum"},
-{"question": "Does Arbitrum have a mempool?","answer": "The Arbitrum Sequencer orders transactions on a first-come, first-served basis. The Sequencer inserts transactions into a queue based on the order in which they are received and executes them accordingly, which eliminates the need for a mempool. The Sequencer's queue has no space limit; transactions on the queue will eventually timeout and get discarded if not executed within a reasonable timeframe. Under normal conditions, the queue is empty, as transaction execution occurs nearly instantaneously.\n\n\n\n","key": "does-arbitrum-have-a-mempool"},
-{"question": "What's the difference between Arbitrum Rollup and Arbitrum AnyTrust?","answer": "Arbitrum Rollup is an Optimistic Rollup protocol; it is trustless and permissionless. Part of how these properties are achieved is by requiring all chain data to be posted on layer 1. This means the availability of this data follows directly from the security properties of Ethereum itself, and, in turn, that any party can participate in validating the chain and ensuring its safety. For more information, see [Inside Arbitrum Nitro](https://docs.arbitrum.io/inside-arbitrum-nitro/).\n\nBy contrast, Arbitrum AnyTrust introduces a trust assumption in exchange for lower fees; data availability is managed by a Data Availability Committee (DAC), a fixed, permissioned set of entities. We introduce some threshold, `K`, with the assumption that at least `K` members of the committee are honest. For simplicity, we'll hereby assume a committee of size 20 and a `K` value of 2:\n\nIf 19 out of the 20 committee members *and* the Sequencer are malicious and colluding together, they can break the chain's safety (and, e.g., steal users' funds); this is the new trust assumption.\n\nIf anywhere between 2 and 18 of the committee members are well behaved, the AnyTrust chain operates in \"Rollup mode\"; i.e., data gets posted on L1.\n\nIn what should be the common and happy case, however, in which at least 19 of the 20 committee members are well behaved, the system operates without posting the L2 chain's data on L1, and thus, users pay significantly lower fees. This is the core upside of AnyTrust chains over rollups.\n\nVariants of the AnyTrust model in which the new trust assumption is minimized are under consideration; stay tuned.\n\nFor more, see [Inside AnyTrust](https://developer.arbitrum.io/inside-anytrust).\n\n\n\n","key": "whats-the-difference-between-arbitrum-rollup-and-arbitrum-anytrust"},
-{"question": "How can I check the status of my cross chain message?","answer": "You can check the status of *any *Arbitrum cross chain message at [https://retryable-dashboard.arbitrum.io/](https://retryable-dashboard.arbitrum.io/) (you will also be able to execute the cross chain message there, if applicable).\n\nYou'll need the transaction hash of the \"initiating transaction\": the L1 transaction hash for an L1-to-L2 message (e.g., a deposit), or the L2 transaction hash for an L2-to-L1 message (e.g., a withdrawal).\n\n\n\nIf you cross-chain message was initiated from [https://bridge.arbitrum.io/](https://bridge.arbitrum.io/), you can also check its status / execute it at that site in the transaction history tab. \n\n\n\n","key": "how-can-i-check-the-status-of-my-cross-chain-message"},
-{"question": "If there is a dispute, can my L2 transaction get reorged / thrown out / \"yeeted\"?","answer": "Nope; once an Arbitrum transaction is included on L1, there is no way it can be reorged (unless the L1 itself reorgs, of course). A \"dispute\" involves Validators disagreeing over execution, i.e., the outputted state of a chain. The inputs, however, can't be disputed; they are determined by the Inbox on L1. (See [Transaction Lifecycle](https://developer.arbitrum.io/tx-lifecycle))\n\n\n\n","key": "if-there-is-a-dispute-can-my-l2-transaction-get-reorged--thrown-out--yeeted"},
-{"question": "...okay but if there's a dispute, will my transaction get delayed?","answer": "The only thing that a dispute can add delay to is the confirmation of L2-to-L1 messages. All other transactions continue to be processed, even while a dispute is still ongoing. (Additionally, in practice, most L2-to-L1 messages represent withdrawals of fungible assets; these can be trustlessly completed *even during a dispute* via trustless fast \"liquidity exit\" applications. See [L2-to-L1 Messages](https://developer.arbitrum.io/arbos/l2-to-l1-messaging)).\n\n\n\n","key": "okay-but-if-theres-a-dispute-will-my-transaction-get-delayed"},
-{"question": "Are \"Sequencers\" the same entities as \"Validators\"? Can a centralized Sequencer act maliciously (e.g., steal all my money)?","answer": "No and no!\n\nAn Arbitrum Chain's Sequencer(s) and Validators and completely distinct entities, with their own distinct roles.\n\nThe [Sequencer](https://developer.arbitrum.io/sequencer) is the entity granted specific privileges over ordering transactions; once the Sequencer commits to an ordering (by posting a batch on Ethereum), it has no say over what happens next (i.e., execution). A malicious/faulty Sequencer can do things like reordering transactions or *temporarily* delaying a transaction's inclusion — things which could be, to be sure, annoying and bad — but can do nothing to compromise the chain's safety.\n\nThe *Validators* are the ones responsible for the safety of the chain; i.e., making staked claims about the chain state, disputing each other, etc.\n\nCurrently, on Arbitrum One, the Sequencer is a centralized entity maintained by Offchain Labs. Eventually, we expect the single Sequencer to be replaced by a distributed committee of Sequencers who come to consensus on transaction ordering. This upgrade will be an improvement; we don't want you to have to trust us not to reorder your transactions. However, it also isn't *strictly* necessary for Arbitrum One to achieve its most fundamental properties.\n\nIn other words: ***An Arbitrum Rollup chain with a centralized Sequencer could theoretically still be trustless!***\n\nWhich is to say — the more important thing than decentralizing the Sequencer, i.e., the thing you ought to care more about — is decentralizing the *Validators*.\n\nArbitrum One's validator set is currently allowlisted; over time, we expect [governance](https://docs.arbitrum.foundation/) to expand the allowlist and eventually be removed entirely.\n\nFor more info see [\"State of Progressive Decentralization\"](https://docs.arbitrum.foundation/state-of-progressive-decentralization).\n\n\n\n","key": "are-sequencers-the-same-entities-as-validators-can-a-centralized-sequencer-act-maliciously-eg-steal-all-my-money"},
-{"question": "Why was \"one week\" chosen for Arbitrum One's dispute window?","answer": "The expectation is that one week should be sufficient for validators to conduct an interactive dispute, provided they do not face challenges in getting their transactions included on Layer 1. The one-week decision occurred following a consensus among the Ethereum research community and other Layer 2 projects. The intention is to allow the community sufficient time to coordinate socially in the event of a coordinated Ethereum staker censorship attack.\n\n\n\n","key": "why-was-one-week-chosen-for-arbitrum-ones-dispute-window"},
-{"question": "What's the state of Arbitrum One's decentralization?","answer": "See **[\"State of Progressive Decentralization\"](https://docs.arbitrum.foundation/state-of-progressive-decentralization)**, or check out the work of our friends at **[L2BEAT](https://l2beat.com/scaling/risk/)****.**\n\n\n\n","key": "whats-the-state-of-arbitrum-ones-decentralization"},
-{"question": "Are there any Fiat on-ramps that support Arbitrum?","answer": "Yes, you can find a list of Fiat on-ramps that support Arbitrum [on our portal](https://portal.arbitrum.io/one?categories=fiat-on-ramp).\n\n\n\n","key": "are-there-any-fiat-onramps-that-support-arbitrum"},
-{"question": "How many blocks are needed for a transaction to be confirmed/finalized in Arbitrum?","answer": "There are two levels of finality in a [transaction lifecycle](https://developer.arbitrum.io/tx-lifecycle):\n\n- **Soft finality**: Once the Sequencer receives and processes a transaction, it emits a receipt through the Sequencer's feed. At this point, if the Sequencer is trusted, the transaction will not undergo reordering, and after processing, the chain state can be determined.\n- **Hard finality**: At this stage, assuming there's at least one well-behaved active Arbitrum validator, the client can treat their transaction's finality as equivalent to that of an ordinary Ethereum transaction.\n","key": "how-many-blocks-are-needed-for-a-transaction-to-be-confirmedfinalized-in-arbitrum"},
-{"question": "Where can I find stats for Arbitrum?","answer": "Although we currently don't maintain any stats dashboard for Arbitrum, you can find many [community created dashboards](https://dune.com/browse/dashboards?q=arbitrum) in Dune.\n\n\n\n","key": "where-can-i-find-stats-for-arbitrum"},
-{"question": "Will transactions with a higher \"gas price bid\" be confirmed first?","answer": "There is no notion of a mempool on Arbitrum; transactions are processed on a first-come, first-served basis by the Sequencer. Thus, the gas price bid parameter does not affect the order in which transactions get processed.\n\n\n\n","key": "will-transactions-with-a-higher-gas-price-bid-be-confirmed-first"},
-{"question": "Where can I find a list of the current validators of the Arbitrum chains?","answer": "Validation on both Arbitrum One and Arbitrum Nova is currently allow-listed to a committee of public entities. You can see the list of validators **[here](https://docs.arbitrum.foundation/state-of-progressive-decentralization#allowlisted-validators)**. Governance currently has the power to change this status.\n\n\n\n","key": "where-can-i-find-a-list-of-the-current-validators-of-the-arbitrum-chains"},
-{"question": "Where can I find the current Data Availability Committee members?","answer": "The Arbitrum Nova chain has a 7-party DAC, whose members can be seen **[here](https://docs.arbitrum.foundation/state-of-progressive-decentralization#data-availability-committee-members)**. Governance has the ability to remove or add members to the committee.\n\n\n\n","key": "where-can-i-find-the-current-data-availability-committee-members"},
-{"question": "Can I withdraw my funds from Arbitrum back to Ethereum without going through the Sequencer? What about funds that are in a contract?","answer": "Yes, it is possible to send a message from Ethereum to be executed on Arbitrum permissionlessly, while bypassing the Sequencer. You can achieve this by using the `DelayedInbox` contract and forcing the inclusion of the message after a certain amount of time has passed (currently ~24 hours). For more information about this behavior, refer to [How Arbitrum Works](https://docs.arbitrum.io/sequencer#unhappyuncommon-case-sequencer-isnt-doing-its-job).\n\nKeep in mind that you can execute any message in this way, be it a withdrawal of funds back to Ethereum or a call to a contract.\n\nYou can also find an example of force-inclusion in [this tutorial](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/delayedInbox-l2msg).\n\n","key": "can-i-withdraw-my-funds-from-arbitrum-back-to-ethereum-without-going-through-the-sequencer-what-about-funds-that-are-in-a-contract"},
-{"question": "Are there any plans to reduce the time a transaction needs to wait before being able to be force-included from Ethereum into the Arbitrum chain, bypassing the sequencer? (Currently 24 hours)","answer": "The mechanism that allows force-including transactions from Ethereum (bypassing the sequencer) is intended to be used in very rare cases, especially when it is expected that the sequencer will not be operational again, so that users have a way of interacting with Arbitrum in a trustless way.\n\nWhen using this mechanism, if the sequencer is down for longer than the time window for force-including transactions from Ethereum, the moment it is online again, it can lead to a reorganization of blocks in Arbitrum (it would have received transactions timestamped before the force-included one).\n\n24 hours was chosen because it provides a comfortable period of time for the team running the sequencer infrastructure to fix any bugs that may cause the sequencer to not work. While there aren't any active initiatives to lower that time, the decision ultimately falls in the hands of the Arbitrum DAO, who has discussed the topic in their governance forum ([see here for more information](https://forum.arbitrum.foundation/t/proposal-decrease-censorship-delay-from-24-hours-to-4-hours/13047)).\n\nIn any case, we could also analyze why would someone use this mechanism having an honest and functional sequencer. For instance, if the reason is a distrust of the sequencer, a centralised agent as of now, one potential solution could be to [decentralize the sequencer](https://medium.com/@espressosys/offchain-labs-partnership-improving-transaction-ordering-for-arbitrum-technology-chains-beyond-de2b6018acb2) instead of reducing the force-inclusion delay time.\n\n\n\n","key": "are-there-any-plans-to-reduce-the-time-a-transaction-needs-to-wait-before-being-able-to-be-forceincluded-from-ethereum-into-the-arbitrum-chain-bypassing-the-sequencer-currently-24-hours"},
-{"question": "What is the difference between an child chain block and an assertion?","answer": "A child chain block is very similar to the concept of an parent chain block. These blocks are generated by validator nodes of Arbitrum by executing the state transition function on sequenced transactions. The structure of a child chain block is similar to that of an Ethereum block, with a few differences that you can [see here](https://docs.arbitrum.io/for-devs/concepts/differences-between-arbitrum-ethereum/rpc-methods#blocks).\n\nOn the other hand, an assertion is a distinctive block that is transmitted back to the parent chain to serve as a fingerprint of the most recent state of the Arbitrum chain. It comprises an assertion of the present state root of the Arbitrum chain and other essential information pertaining to withdrawals and challenges. The structure of assertions can be viewed [here](https://github.com/OffchainLabs/nitro/blob/2436da3fbf339ce72b02f761254aff5b86efafac/contracts/src/rollup/Node.sol#L7).\n\nThese assertions are also generated by validators, but they are appended to the parent chain. Other validators can [challenge them](https://docs.arbitrum.io/inside-arbitrum-nitro/#resolving-disputes-using-interactive-fraud-proofs) during a specific time frame of approximately one week if they discover that the current state hash of the chain varies from the one that was initially claimed. Once the challenge period elapses, the assertion is confirmed on the parent chain.\n\n\n\n","key": "what-is-the-difference-between-an-child-chain-block-and-an-assertion"},
-{"question": "Why do Arbitrum chains enforce a speed limit? Isn't it better that the speed grows without limits?","answer": "The transaction lifecycle sets a limit that we have to take into account: validators have to execute each transaction, get the status of the chain, and post an assertion to Ethereum every certain amount of time. If the speed of the chain increases too much, there is a risk that validators won't have enough computation power to process all transactions in a timely manner, and will fall behind on validating them, which would cause the chain to delay confirmations of its state.\n\n\n\n","key": "why-do-arbitrum-chains-enforce-a-speed-limit-isnt-it-better-that-the-speed-grows-without-limits"}
-]
\ No newline at end of file
+ {
+ "question": "Why do I need ETH to use the Arbitrum network?",
+ "answer": "`ETH` is the currency used to pay gas fees on Arbitrum, and it powers all transactions on Arbitrum. You can bridge `ETH` (and other tokens) from Ethereum to Arbitrum through [Arbitrum's bridge](https://bridge.arbitrum.io/).\n\n\n\n",
+ "key": "why-do-i-need-eth-to-use-the-arbitrum-network"
+ },
+ {
+ "question": "Do I need to pay a tip or priority fee for my Arbitrum transactions?",
+ "answer": "Transaction processing occurs in the order that the Sequencer receives them; no priority fee is necessary for Arbitrum transactions. If a transaction includes a priority fee, the origin address of the transaction will be refunded at the end of execution.\n\n",
+ "key": "do-i-need-to-pay-a-tip-or-priority-fee-for-my-arbitrum-transactions"
+ },
+ {
+ "question": "How can I see the balance of ETH and other tokens in my wallet on Arbitrum?",
+ "answer": "Most wallets are \"connected\" to one given network at a time. To view your ETH or token balances, ensure that you have an established connection to the appropriate Arbitrum chain. In MetaMask and OKX Wallet, you can switch networks via the **Networks** drop-down. In this drop-down, please select the desired network (either Arbitrum One or Arbitrum Nova for our mainnet networks). If your preferred network hasn't been added to your wallet yet, you can add it via the [Arbitrum Bridge](https://bridge.arbitrum.io/).\n\n\n\n",
+ "key": "how-can-i-see-the-balance-of-eth-and-other-tokens-in-my-wallet-on-arbitrum"
+ },
+ {
+ "question": "What happens if I send my funds to an exchange that doesn't support Arbitrum?",
+ "answer": "If you send the funds and the receiving wallet/exchange doesn't support the Arbitrum network you are sending funds through, unfortunately, there is nothing we can do to recover your funds. You would need to contact the wallet/exchange support and see if they can assist you in retrieving the funds.\n\n\n\n",
+ "key": "what-happens-if-i-send-my-funds-to-an-exchange-that-doesnt-support-arbitrum"
+ },
+ {
+ "question": "Does Arbitrum have a mempool?",
+ "answer": "The Arbitrum Sequencer orders transactions on a first-come, first-served basis. The Sequencer inserts transactions into a queue based on the order in which they are received and executes them accordingly, which eliminates the need for a mempool. The Sequencer's queue has no space limit; transactions on the queue will eventually timeout and get discarded if not executed within a reasonable timeframe. Under normal conditions, the queue is empty, as transaction execution occurs nearly instantaneously.\n\n\n\n",
+ "key": "does-arbitrum-have-a-mempool"
+ },
+ {
+ "question": "What's the difference between Arbitrum Rollup and Arbitrum AnyTrust?",
+ "answer": "Arbitrum Rollup is an Optimistic Rollup protocol; it is trustless and permissionless. Part of how these properties are achieved is by requiring all chain data to be posted on layer 1. This means the availability of this data follows directly from the security properties of Ethereum itself, and, in turn, that any party can participate in validating the chain and ensuring its safety. For more information, see [Inside Arbitrum Nitro](https://docs.arbitrum.io/inside-arbitrum-nitro/).\n\nBy contrast, Arbitrum AnyTrust introduces a trust assumption in exchange for lower fees; data availability is managed by a Data Availability Committee (DAC), a fixed, permissioned set of entities. We introduce some threshold, `K`, with the assumption that at least `K` members of the committee are honest. For simplicity, we'll hereby assume a committee of size 20 and a `K` value of 2:\n\nIf 19 out of the 20 committee members *and* the Sequencer are malicious and colluding together, they can break the chain's safety (and, e.g., steal users' funds); this is the new trust assumption.\n\nIf anywhere between 2 and 18 of the committee members are well behaved, the AnyTrust chain operates in \"Rollup mode\"; i.e., data gets posted on L1.\n\nIn what should be the common and happy case, however, in which at least 19 of the 20 committee members are well behaved, the system operates without posting the L2 chain's data on L1, and thus, users pay significantly lower fees. This is the core upside of AnyTrust chains over rollups.\n\nVariants of the AnyTrust model in which the new trust assumption is minimized are under consideration; stay tuned.\n\nFor more, see [Inside AnyTrust](https://developer.arbitrum.io/inside-anytrust).\n\n\n\n",
+ "key": "whats-the-difference-between-arbitrum-rollup-and-arbitrum-anytrust"
+ },
+ {
+ "question": "How can I check the status of my cross chain message?",
+ "answer": "You can check the status of *any *Arbitrum cross chain message at [https://retryable-dashboard.arbitrum.io/](https://retryable-dashboard.arbitrum.io/) (you will also be able to execute the cross chain message there, if applicable).\n\nYou'll need the transaction hash of the \"initiating transaction\": the L1 transaction hash for an L1-to-L2 message (e.g., a deposit), or the L2 transaction hash for an L2-to-L1 message (e.g., a withdrawal).\n\n\n\nIf you cross-chain message was initiated from [https://bridge.arbitrum.io/](https://bridge.arbitrum.io/), you can also check its status / execute it at that site in the transaction history tab. \n\n\n\n",
+ "key": "how-can-i-check-the-status-of-my-cross-chain-message"
+ },
+ {
+ "question": "If there is a dispute, can my L2 transaction get reorged / thrown out / \"yeeted\"?",
+ "answer": "Nope; once an Arbitrum transaction is included on L1, there is no way it can be reorged (unless the L1 itself reorgs, of course). A \"dispute\" involves Validators disagreeing over execution, i.e., the outputted state of a chain. The inputs, however, can't be disputed; they are determined by the Inbox on L1. (See [Transaction Lifecycle](https://developer.arbitrum.io/tx-lifecycle))\n\n\n\n",
+ "key": "if-there-is-a-dispute-can-my-l2-transaction-get-reorged--thrown-out--yeeted"
+ },
+ {
+ "question": "...okay but if there's a dispute, will my transaction get delayed?",
+ "answer": "The only thing that a dispute can add delay to is the confirmation of L2-to-L1 messages. All other transactions continue to be processed, even while a dispute is still ongoing. (Additionally, in practice, most L2-to-L1 messages represent withdrawals of fungible assets; these can be trustlessly completed *even during a dispute* via trustless fast \"liquidity exit\" applications. See [L2-to-L1 Messages](https://developer.arbitrum.io/arbos/l2-to-l1-messaging)).\n\n\n\n",
+ "key": "okay-but-if-theres-a-dispute-will-my-transaction-get-delayed"
+ },
+ {
+ "question": "Are \"Sequencers\" the same entities as \"Validators\"? Can a centralized Sequencer act maliciously (e.g., steal all my money)?",
+ "answer": "No and no!\n\nAn Arbitrum Chain's Sequencer(s) and Validators and completely distinct entities, with their own distinct roles.\n\nThe [Sequencer](https://developer.arbitrum.io/sequencer) is the entity granted specific privileges over ordering transactions; once the Sequencer commits to an ordering (by posting a batch on Ethereum), it has no say over what happens next (i.e., execution). A malicious/faulty Sequencer can do things like reordering transactions or *temporarily* delaying a transaction's inclusion — things which could be, to be sure, annoying and bad — but can do nothing to compromise the chain's safety.\n\nThe *Validators* are the ones responsible for the safety of the chain; i.e., making staked claims about the chain state, disputing each other, etc.\n\nCurrently, on Arbitrum One, the Sequencer is a centralized entity maintained by Offchain Labs. Eventually, we expect the single Sequencer to be replaced by a distributed committee of Sequencers who come to consensus on transaction ordering. This upgrade will be an improvement; we don't want you to have to trust us not to reorder your transactions. However, it also isn't *strictly* necessary for Arbitrum One to achieve its most fundamental properties.\n\nIn other words: ***An Arbitrum Rollup chain with a centralized Sequencer could theoretically still be trustless!***\n\nWhich is to say — the more important thing than decentralizing the Sequencer, i.e., the thing you ought to care more about — is decentralizing the *Validators*.\n\nArbitrum One's validator set is currently allowlisted; over time, we expect [governance](https://docs.arbitrum.foundation/) to expand the allowlist and eventually be removed entirely.\n\nFor more info see [\"State of Progressive Decentralization\"](https://docs.arbitrum.foundation/state-of-progressive-decentralization).\n\n\n\n",
+ "key": "are-sequencers-the-same-entities-as-validators-can-a-centralized-sequencer-act-maliciously-eg-steal-all-my-money"
+ },
+ {
+ "question": "Why was \"one week\" chosen for Arbitrum One's dispute window?",
+ "answer": "The expectation is that one week should be sufficient for validators to conduct an interactive dispute, provided they do not face challenges in getting their transactions included on Layer 1. The one-week decision occurred following a consensus among the Ethereum research community and other Layer 2 projects. The intention is to allow the community sufficient time to coordinate socially in the event of a coordinated Ethereum staker censorship attack.\n\n\n\n",
+ "key": "why-was-one-week-chosen-for-arbitrum-ones-dispute-window"
+ },
+ {
+ "question": "What's the state of Arbitrum One's decentralization?",
+ "answer": "See **[\"State of Progressive Decentralization\"](https://docs.arbitrum.foundation/state-of-progressive-decentralization)**, or check out the work of our friends at **[L2BEAT](https://l2beat.com/scaling/risk/)****.**\n\n\n\n",
+ "key": "whats-the-state-of-arbitrum-ones-decentralization"
+ },
+ {
+ "question": "Are there any Fiat on-ramps that support Arbitrum?",
+ "answer": "Yes, you can find a list of Fiat on-ramps that support Arbitrum [on our portal](https://portal.arbitrum.io/one?categories=fiat-on-ramp).\n\n\n\n",
+ "key": "are-there-any-fiat-onramps-that-support-arbitrum"
+ },
+ {
+ "question": "How many blocks are needed for a transaction to be confirmed/finalized in Arbitrum?",
+ "answer": "There are two levels of finality in a [transaction lifecycle](https://developer.arbitrum.io/tx-lifecycle):\n\n- **Soft finality**: Once the Sequencer receives and processes a transaction, it emits a receipt through the Sequencer's feed. At this point, if the Sequencer is trusted, the transaction will not undergo reordering, and after processing, the chain state can be determined.\n- **Hard finality**: At this stage, assuming there's at least one well-behaved active Arbitrum validator, the client can treat their transaction's finality as equivalent to that of an ordinary Ethereum transaction.\n",
+ "key": "how-many-blocks-are-needed-for-a-transaction-to-be-confirmedfinalized-in-arbitrum"
+ },
+ {
+ "question": "Where can I find stats for Arbitrum?",
+ "answer": "Although we currently don't maintain any stats dashboard for Arbitrum, you can find many [community created dashboards](https://dune.com/browse/dashboards?q=arbitrum) in Dune.\n\n\n\n",
+ "key": "where-can-i-find-stats-for-arbitrum"
+ },
+ {
+ "question": "Will transactions with a higher \"gas price bid\" be confirmed first?",
+ "answer": "There is no notion of a mempool on Arbitrum; transactions are processed on a first-come, first-served basis by the Sequencer. Thus, the gas price bid parameter does not affect the order in which transactions get processed.\n\n\n\n",
+ "key": "will-transactions-with-a-higher-gas-price-bid-be-confirmed-first"
+ },
+ {
+ "question": "Where can I find a list of the current validators of the Arbitrum chains?",
+ "answer": "Validation on both Arbitrum One and Arbitrum Nova is currently allow-listed to a committee of public entities. You can see the list of validators **[here](https://docs.arbitrum.foundation/state-of-progressive-decentralization#allowlisted-validators)**. Governance currently has the power to change this status.\n\n\n\n",
+ "key": "where-can-i-find-a-list-of-the-current-validators-of-the-arbitrum-chains"
+ },
+ {
+ "question": "Where can I find the current Data Availability Committee members?",
+ "answer": "The Arbitrum Nova chain has a 7-party DAC, whose members can be seen **[here](https://docs.arbitrum.foundation/state-of-progressive-decentralization#data-availability-committee-members)**. Governance has the ability to remove or add members to the committee.\n\n\n\n",
+ "key": "where-can-i-find-the-current-data-availability-committee-members"
+ },
+ {
+ "question": "Can I withdraw my funds from Arbitrum back to Ethereum without going through the Sequencer? What about funds that are in a contract?",
+ "answer": "Yes, it is possible to send a message from Ethereum to be executed on Arbitrum permissionlessly, while bypassing the Sequencer. You can achieve this by using the `DelayedInbox` contract and forcing the inclusion of the message after a certain amount of time has passed (currently ~24 hours). For more information about this behavior, refer to [How Arbitrum Works](https://docs.arbitrum.io/sequencer#unhappyuncommon-case-sequencer-isnt-doing-its-job).\n\nKeep in mind that you can execute any message in this way, be it a withdrawal of funds back to Ethereum or a call to a contract.\n\nYou can also find an example of force-inclusion in [this tutorial](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/delayedInbox-l2msg).\n\n",
+ "key": "can-i-withdraw-my-funds-from-arbitrum-back-to-ethereum-without-going-through-the-sequencer-what-about-funds-that-are-in-a-contract"
+ },
+ {
+ "question": "Are there any plans to reduce the time a transaction needs to wait before being able to be force-included from Ethereum into the Arbitrum chain, bypassing the sequencer? (Currently 24 hours)",
+ "answer": "The mechanism that allows force-including transactions from Ethereum (bypassing the sequencer) is intended to be used in very rare cases, especially when it is expected that the sequencer will not be operational again, so that users have a way of interacting with Arbitrum in a trustless way.\n\nWhen using this mechanism, if the sequencer is down for longer than the time window for force-including transactions from Ethereum, the moment it is online again, it can lead to a reorganization of blocks in Arbitrum (it would have received transactions timestamped before the force-included one).\n\n24 hours was chosen because it provides a comfortable period of time for the team running the sequencer infrastructure to fix any bugs that may cause the sequencer to not work. While there aren't any active initiatives to lower that time, the decision ultimately falls in the hands of the Arbitrum DAO, who has discussed the topic in their governance forum ([see here for more information](https://forum.arbitrum.foundation/t/proposal-decrease-censorship-delay-from-24-hours-to-4-hours/13047)).\n\nIn any case, we could also analyze why would someone use this mechanism having an honest and functional sequencer. For instance, if the reason is a distrust of the sequencer, a centralised agent as of now, one potential solution could be to [decentralize the sequencer](https://medium.com/@espressosys/offchain-labs-partnership-improving-transaction-ordering-for-arbitrum-technology-chains-beyond-de2b6018acb2) instead of reducing the force-inclusion delay time.\n\n\n\n",
+ "key": "are-there-any-plans-to-reduce-the-time-a-transaction-needs-to-wait-before-being-able-to-be-forceincluded-from-ethereum-into-the-arbitrum-chain-bypassing-the-sequencer-currently-24-hours"
+ },
+ {
+ "question": "What is the difference between an child chain block and an assertion?",
+ "answer": "A child chain block is very similar to the concept of an parent chain block. These blocks are generated by validator nodes of Arbitrum by executing the state transition function on sequenced transactions. The structure of a child chain block is similar to that of an Ethereum block, with a few differences that you can [see here](https://docs.arbitrum.io/for-devs/concepts/differences-between-arbitrum-ethereum/rpc-methods#blocks).\n\nOn the other hand, an assertion is a distinctive block that is transmitted back to the parent chain to serve as a fingerprint of the most recent state of the Arbitrum chain. It comprises an assertion of the present state root of the Arbitrum chain and other essential information pertaining to withdrawals and challenges. The structure of assertions can be viewed [here](https://github.com/OffchainLabs/nitro/blob/2436da3fbf339ce72b02f761254aff5b86efafac/contracts/src/rollup/Node.sol#L7).\n\nThese assertions are also generated by validators, but they are appended to the parent chain. Other validators can [challenge them](https://docs.arbitrum.io/inside-arbitrum-nitro/#resolving-disputes-using-interactive-fraud-proofs) during a specific time frame of approximately one week if they discover that the current state hash of the chain varies from the one that was initially claimed. Once the challenge period elapses, the assertion is confirmed on the parent chain.\n\n\n\n",
+ "key": "what-is-the-difference-between-an-child-chain-block-and-an-assertion"
+ },
+ {
+ "question": "Why do Arbitrum chains enforce a speed limit? Isn't it better that the speed grows without limits?",
+ "answer": "The transaction lifecycle sets a limit that we have to take into account: validators have to execute each transaction, get the status of the chain, and post an assertion to Ethereum every certain amount of time. If the speed of the chain increases too much, there is a risk that validators won't have enough computation power to process all transactions in a timely manner, and will fall behind on validating them, which would cause the chain to delay confirmations of its state.\n\n\n\n",
+ "key": "why-do-arbitrum-chains-enforce-a-speed-limit-isnt-it-better-that-the-speed-grows-without-limits"
+ }
+]
diff --git a/static/glossary.json b/static/glossary.json
index e11f822ecd..ea0486df72 100644
--- a/static/glossary.json
+++ b/static/glossary.json
@@ -7,10 +7,6 @@
"title": "Address Alias",
"text": "
An address deterministically generated from a parent chain contract address used on child chain to safely identify the source of an parent to child chain message.
A decentralized application typically consists of smart contracts as well as a user-interface for interacting with them.\nNote: In our documentation, "apps" and "decentralized applications" are used interchangeably.
A contract that holds Parent chain initiated messages to be eventually included in the Sequencer Inbox. Inclusion of messages doesn't depend on the Sequencer.
Web application built and maintained by Offchain Labs for developers and users to debug Arbitrum transactions; i.e., executing or checking the status of Cross-chain messages; visit it here.
A component of Timeboost, the express lane is a special endpoint on the Sequencer that immediately sequences incoming, valid transactions signed by the current express lane controller.
EVM compatible chain that acts as the settlement layer for one or more Arbitrum Chains (aka Child chain ). E.g., Ethereum is the parent chain of both Arbitrum One and Arbitrum Nova. Parent chain is synonymous with "underlying chain."
RaaS (Rollup as a Service) is a platform that provides the necessary infrastructure and tools to deploy and operate blockchain Rollups, eliminating the need for teams to build the underlying technical infrastructure themselves. It typically includes pre-built Rollup software, node hosting, data availability solutions, and monitoring tools, allowing developers to focus on their application logic rather than the complex technical implementation of Rollup technology.
In the context of Ethereum, trustless refers to the ability of a system to operate without reliance on a central authority or intermediary. Instead, users place their trust in math and protocols.
\n
This is achieved through the use of cryptographic techniques and decentralized consensus mechanisms that let users verify the integrity of network transactions using open-source software. Trustless systems are considered to be more secure and resistant to fraud or tampering because they don't rely on a single point of failure that can be exploited by attackers.