diff --git a/arbitrum-docs/assets/batching.png b/arbitrum-docs/assets/batching.png new file mode 100644 index 000000000..6e311e261 Binary files /dev/null and b/arbitrum-docs/assets/batching.png differ diff --git a/arbitrum-docs/assets/bypassing-the-sequencer.png b/arbitrum-docs/assets/bypassing-the-sequencer.png new file mode 100644 index 000000000..289d0d599 Binary files /dev/null and b/arbitrum-docs/assets/bypassing-the-sequencer.png differ diff --git a/arbitrum-docs/assets/compression.png b/arbitrum-docs/assets/compression.png new file mode 100644 index 000000000..2a8ec38f1 Binary files /dev/null and b/arbitrum-docs/assets/compression.png differ diff --git a/arbitrum-docs/assets/sequencer-feed.png b/arbitrum-docs/assets/sequencer-feed.png new file mode 100644 index 000000000..b5b580fb7 Binary files /dev/null and b/arbitrum-docs/assets/sequencer-feed.png differ diff --git a/arbitrum-docs/assets/sequencer-operations.png b/arbitrum-docs/assets/sequencer-operations.png new file mode 100644 index 000000000..50053133f Binary files /dev/null and b/arbitrum-docs/assets/sequencer-operations.png differ diff --git a/arbitrum-docs/assets/submit-to-sequencer-inbox.png b/arbitrum-docs/assets/submit-to-sequencer-inbox.png new file mode 100644 index 000000000..08653bb3d Binary files /dev/null and b/arbitrum-docs/assets/submit-to-sequencer-inbox.png differ diff --git a/arbitrum-docs/assets/submit-tx-to-sequencer.png b/arbitrum-docs/assets/submit-tx-to-sequencer.png new file mode 100644 index 000000000..b67b0df65 Binary files /dev/null and b/arbitrum-docs/assets/submit-tx-to-sequencer.png differ diff --git a/arbitrum-docs/audit-reports.mdx b/arbitrum-docs/audit-reports.mdx index 5d6e3bbb0..a3e954a9d 100644 --- a/arbitrum-docs/audit-reports.mdx +++ b/arbitrum-docs/audit-reports.mdx @@ -2,6 +2,7 @@ | Auditor | Audit date (MM/DD/YYY) | Audited code | View report | | ----------------------- | ---------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| **Trail of Bits** | 12/26/2024 | BoLD Proposal Payload & Upgrade Actions + Misc Changes for Nitro Contracts v3.0.0 | [view](hosted-audit-reports/2024_12_26_trail_of_bits_boldfixes_securityreview.pdf) | | **Trail of Bits** | 10/30/2024 | Changes to BoLD Solidity contracts to support EIP7702 & Fast Withdrawals | [view](hosted-audit-reports/2024_10_30_trail_of_bits_security_audit_Nitro_Contracts_with_BoLD.pdf) | | **Trail of Bits** | 10/23/2024 | ArbOS 32 Bianca: Emergency Stylus Fixes | [view](hosted-audit-reports/2024_10_23_trail_of_bits_security_audit_arbos32_emergency_fixes.pdf) | | **Trail of Bits** | 10/07/2024 | Optimizations to BoLD history commitments | [view](hosted-audit-reports/2024_10_07_trail_of_bits_security_audit_bold_optimized_history_commitments.pdf) | diff --git a/arbitrum-docs/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx b/arbitrum-docs/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx index 44fb3cfc9..d1befd410 100644 --- a/arbitrum-docs/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx +++ b/arbitrum-docs/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx @@ -456,7 +456,7 @@ Select `Arbitrum Sepolia` from Metamask's dropdown, paste your contract address Now that we've verified that our smart contract works on Arbitrum's Sepolia testnet, we're ready to deploy it to Arbitrum One Mainnet. This is the same process as deploying to Arbitrum's Sepolia testnet, except that we'll need to pay a transaction fee in real $ETH instead of $ASPL. -Expect to see inconsistent $ETH gas fees in this step - the [Gas and fees section](/how-arbitrum-works/gas-fees.mdx) contains more information about how gas fees are determined for Arbitrum transactions. +Expect to see inconsistent $ETH gas fees in this step - the [Gas and fees section](/how-arbitrum-works/09-gas-fees.mdx) contains more information about how gas fees are determined for Arbitrum transactions. diff --git a/arbitrum-docs/build-decentralized-apps/02-how-to-estimate-gas.mdx b/arbitrum-docs/build-decentralized-apps/02-how-to-estimate-gas.mdx index 1e449f6e5..aac9eaf00 100644 --- a/arbitrum-docs/build-decentralized-apps/02-how-to-estimate-gas.mdx +++ b/arbitrum-docs/build-decentralized-apps/02-how-to-estimate-gas.mdx @@ -11,7 +11,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/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/09-gas-fees.mdx) page. ## Skip the formula, focus on practical know-how @@ -21,7 +21,7 @@ Multiplying the value obtained from `eth_estimateGas` by the L2 gas price will g 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 L2 gas price, which is available in the third result, `baseFee`. -Note that when working with L1 to L2 messages (also known as [retryable tickets](/how-arbitrum-works/arbos/l1-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@/blob/@nitroVersionTag@/nodeInterface/NodeInterface.go#L120) to get all the gas information needed to send a successful transaction. +Note that when working with L1 to L2 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@/blob/@nitroVersionTag@/nodeInterface/NodeInterface.go#L120) to get all the gas information needed to send a successful transaction. ## Breaking down the formula @@ -35,7 +35,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 L2 computation and an additional buffer to cover the L1 gas to be paid by the Sequencer when [posting the batch including this transaction on L1](/how-arbitrum-works/inside-arbitrum-nitro.mdx#how-the-sequencer-publishes-the-sequence). +This Gas Limit includes the gas of the L2 computation and an additional buffer to cover the L1 gas to be paid by the Sequencer when [posting the batch including this transaction on L1](/how-arbitrum-works/03-sequencer.mdx). ``` Gas Limit (G) = Gas used on L2 (L2G) + Extra Buffer for L1 cost (B) @@ -46,7 +46,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 L2's estimated view of the current L1's price of data (per byte), which the L2 dynamically adjusts over time. -More information is available [in this page](/how-arbitrum-works/l1-gas-pricing.mdx). +More information is available [in this page](/how-arbitrum-works/09-gas-fees.mdx). ``` L1 Estimated Cost (L1C) = L1 price per byte of data (L1P) * Size of data to be posted in bytes (L1S) @@ -75,7 +75,7 @@ We'll use one resource available in Arbitrum: the [NodeInterface](/build-decentr - L1P (L1 estimated price per byte of data) ⇒ Estimated cost of posting 1 byte of data on L1: - 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 L1 (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 is posted on L1, [as explained here](/how-arbitrum-works/inside-anytrust.mdx#data-availability-certificates). + - For Arbitrum Nova (AnyTrust), the size of the data is also a fixed value, as only the Data Availability Certificate is posted on L1, [as explained here](/how-arbitrum-works/08-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/arbitrum-docs/build-decentralized-apps/03-public-chains.mdx b/arbitrum-docs/build-decentralized-apps/03-public-chains.mdx index cc2925b0f..b4ab2b70d 100644 --- a/arbitrum-docs/build-decentralized-apps/03-public-chains.mdx +++ b/arbitrum-docs/build-decentralized-apps/03-public-chains.mdx @@ -13,11 +13,11 @@ Arbitrum chains are Layer 2 solutions built on top of the Ethereum blockchain, d ### Arbitrum One -**Arbitrum One** is a Layer 2 (L2) optimistic rollup chain that implements the Arbitrum Rollup protocol and settles to Ethereum's Layer 1 (L1) 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/inside-arbitrum-nitro.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 L1 gas compatibility, and more. +**Arbitrum One** is a Layer 2 (L2) optimistic Rollup chain that implements the Arbitrum Rollup protocol and settles to Ethereum's Layer 1 (L1) 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-geth-at-the-core.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 L1 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/inside-anytrust.mdx) protocol. They 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 L2 transaction data to Ethereum's L1. 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/08-anytrust-protocol.mdx) protocol. They 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 L2 transaction data to Ethereum's L1. 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? @@ -57,11 +57,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 L1 gas compatibility, and more. You can find more information about Nitro in [Inside Arbitrum Nitro](/how-arbitrum-works/inside-arbitrum-nitro.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 L1 gas compatibility, and more. You can find more information about Nitro in [Inside Arbitrum Nitro](/how-arbitrum-works/01-a-gentle-introduction.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 off-chain in the happy/common case means the system can charge the user significantly lower fees. You can find more information about AnyTrust in [Inside AnyTrust](/how-arbitrum-works/inside-anytrust.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 off-chain in the happy/common case means the system can charge the user significantly lower fees. You can find more information about AnyTrust in [Inside AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx). ### Classic (deprecated) diff --git a/arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx b/arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx index 03e3b72a5..2100226da 100644 --- a/arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx +++ b/arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx @@ -11,7 +11,7 @@ The Arbitrum protocol and related tooling makes it easy for developers to build Arbitrary L1 to L2 contract calls can be created via the `Inbox`'s `createRetryableTicket` method; upon publishing the L1 transaction, the L2 side will typically get included within minutes. Happily / commonly, the L2 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 [L1 to L2 Messages](/how-arbitrum-works/arbos/l1-l2-messaging.mdx). +For details and protocol specification, see [L1 to L2 Messages](/how-arbitrum-works/10-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/1-introduction.mdx). @@ -19,6 +19,6 @@ For an example of retryable tickets in action, see the [Greeter](https://github. Similarly, L2 contracts can send Arbitrary messages for execution on L1. These are initiated via calls to the [ArbSys](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) precompile contract's `sendTxToL1` method. Upon confirmation (about 1 week later), they can executed 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 [L2 to L1 Messages](/how-arbitrum-works/arbos/l2-l1-messaging.mdx). +For details and protocol specification, see [L2 to L1 Messages](/how-arbitrum-works/11-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/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx index 23762f350..396919a80 100644 --- a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx +++ b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx @@ -26,13 +26,13 @@ You can deploy Solidity contracts onto Arbitrum just like you do on Ethereum. Th ## Fees -The fees an Arbitrum transaction pays for execution essentially work identically to gas fees on Ethereum. Arbitrum transactions must also, however, pay a fee component to cover the cost of posting their calldata to the parent chain (for example, calldata on Arbitrum One, an L2, is posted to Ethereum, an L1). Find more information about the two components of gas fees in [Gas and fees](/how-arbitrum-works/gas-fees.mdx) and [L1 pricing](/how-arbitrum-works/l1-gas-pricing.mdx). +The fees for executing an Arbitrum transaction work like 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, an L2, is posted to Ethereum, an L1). Find more information about the two components of gas fees in [Gas and fees](/how-arbitrum-works/09-gas-fees.mdx) and L1 pricing. ## Cross-chain messaging -Arbitrum chains support arbitrary message passing from a parent chain (for example, a Layer 1 (L1) like Ethereum) to a child chain (for example, a Layer 2 (L2) like Arbitrum One or Arbitrum Nova). These are commonly known as "L1 to L2 messages". Developers using this functionality should familiarize themselves with how they work. Find more information about it in [L1 to L2 messaging](/how-arbitrum-works/arbos/l1-l2-messaging.mdx). +Arbitrum chains support arbitrary message passing from a parent chain (for example, a Layer 1 (L1) like Ethereum) to a child chain (for example, a Layer 2 (L2) like Arbitrum One or Arbitrum Nova). These are commonly known as "L1 to L2 messages". Developers using this functionality should familiarize themselves with how they work. Find more information about it in [L1 to L2 messaging](/how-arbitrum-works/10-l1-to-l2-messaging.mdx). -Similarly, Arbitrum chains can also send messages to the parent chain. Find more information about them in [L2 to L1 messaging and the outbox](/how-arbitrum-works/arbos/l2-l1-messaging.mdx). +Similarly, Arbitrum chains can also send messages to the parent chain. Find more information about them in [L2 to L1 messaging and the outbox](/how-arbitrum-works/11-l2-to-l1-messaging.mdx). ## Precompiles diff --git a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx index 00b92cc6d..04b01ba9d 100644 --- a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx +++ b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx @@ -13,7 +13,7 @@ With the release of Arbitrum Orbit, Arbitrum chains can now be L2s that settle t ::: -As in Ethereum, Arbitrum clients submit transactions, and the system executes those transactions at some later time. In Arbitrum, clients submit transactions by posting messages to the Ethereum chain, either [through the sequencer](/how-arbitrum-works/sequencer.mdx#happycommon-case-sequencer-is-live-and-well-behaved) or via the chain's [delayed inbox](/how-arbitrum-works/sequencer.mdx#unhappyuncommon-case-sequencer-isnt-doing-its-job). +As in Ethereum, Arbitrum clients submit transactions, and the system executes those transactions 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). Once in the chain's core inbox contract, transactions are processed 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/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx index b24a68c8c..e566a4ab3 100644 --- a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx +++ b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx @@ -21,7 +21,7 @@ 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/arbos/geth.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/04-geth-at-the-core.mdx#transaction-types). On RPC calls that return transactions, the `type` field will reflect the custom codes where applicable. @@ -30,8 +30,8 @@ On RPC calls that return transactions, the `type` field will reflect the custom | `100` | `ArbitrumDepositTxType` | Used to deposit ETH from L1 to L2 via the Arbitrum bridge | | `101` | `ArbitrumUnsignedTxType` | Used to call an L2 contract from L1, originated by a user through the Arbitrum bridge | | `102` | `ArbitrumContractTxType` | Used to call an L2 contract from L1, originated by a contract through the Arbitrum bridge | -| `104` | `ArbitrumRetryTxType` | Used to [manually redeem a retryable ticket](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) on L2 that failed to execute automatically (usually due to low gas) | -| `105` | `ArbitrumSubmitRetryableTxType` | Used to [submit a retryable ticket](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#submission) via the Arbitrum bridge on L1 | +| `104` | `ArbitrumRetryTxType` | Used to [manually redeem a retryable ticket](/how-arbitrum-works/10-l1-to-l2-messaging.mdx) on L2 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 L1 | | `106` | `ArbitrumInternalTxType` | Internal transactions created by the ArbOS itself for certain state updates, like the L1 base fee and the block number | ### Additional fields @@ -48,7 +48,7 @@ On RPC calls that return transactions, the following fields will have a differen | Field name | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `from` | On L1 to L2 transactions, this field will contain the [_aliased_ version](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#address-aliasing) of the L1's `msg.sender` | +| `from` | On L1 to L2 transactions, this field will contain the [_aliased_ version](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#address-aliasing) of the L1's `msg.sender` | ## Transaction receipts @@ -61,7 +61,7 @@ On RPC calls that return transaction receipts, the following fields are added to | Field name | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `l1BlockNumber` | The L1 block number that would be used for `block.number` calls. More information in [Block numbers and time](/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx) | -| `gasUsedForL1` | Amount of gas spent on L1 calldata in units of L2 gas. More information in [Gas and fees](/how-arbitrum-works/gas-fees.mdx) | +| `gasUsedForL1` | Amount of gas spent on L1 calldata in units of L2 gas. More information in [Gas and fees](/how-arbitrum-works/09-gas-fees.mdx) | ## Blocks diff --git a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx index 8730e9eba..3dc50fd2b 100644 --- a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx +++ b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx @@ -22,5 +22,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 L1 block number 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 L2 to L2 transactions. For transactions submitted via the delayed inbox, it will return the L2 address alias of the L1 contract that triggered the message. For more information, see [address aliasing](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#address-aliasing). | +| `msg.sender` | Works the same way it does on Ethereum for regular L2 to L2 transactions. For transactions submitted via the delayed inbox, it will return the L2 address alias of the L1 contract that triggered the message. For more information, see [address aliasing](/how-arbitrum-works/10-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/arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx b/arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx index 37edc16a3..321ec6202 100644 --- a/arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx +++ b/arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx @@ -179,7 +179,7 @@ import ArbOwnerPublicRef from '../../for-devs/dev-tools-and-resources/partials/p ### ArbRetryableTx -ArbRetryableTx ([Interface][arbretryabletx_link_interface] | [Implementation][arbretryabletx_link_implementation]) 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/arbos/l1-l2-messaging.mdx#retryable-tickets). +ArbRetryableTx ([Interface][arbretryabletx_link_interface] | [Implementation][arbretryabletx_link_implementation]) 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). Precompile address: `0x000000000000000000000000000000000000006E` diff --git a/arbitrum-docs/build-decentralized-apps/reference/08-mainnet-risks.mdx b/arbitrum-docs/build-decentralized-apps/reference/08-mainnet-risks.mdx index abe6452a1..69463cd14 100644 --- a/arbitrum-docs/build-decentralized-apps/reference/08-mainnet-risks.mdx +++ b/arbitrum-docs/build-decentralized-apps/reference/08-mainnet-risks.mdx @@ -6,7 +6,7 @@ author: dzgoldman # Arbitrum: Understanding the risks -Arbitrum One — the first permissionless Ethereum layer 2 rollup with full Ethereum smart contract functionality — 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/inside-anytrust.mdx); We're sure you're (almost) as excited as we are! +Arbitrum One — the first permissionless Ethereum layer 2 rollup with full Ethereum smart contract functionality — 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! Here are some risks you should know about before using the system: ### State Of progressive decentralization diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx b/arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx index a17c9c0d5..c6b97d1c6 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx @@ -36,7 +36,7 @@ ArbSys(100).withdrawEth{ value: 2300000 }(destAddress) Upon withdrawing, the Ether balance is burnt on the Arbitrum side, and will later be made available on the Ethereum side. -`ArbSys.withdrawEth` is actually a convenience function which is equivalent to calling `ArbSys.sendTxToL1` with empty calldataForL1. Like any other `sendTxToL1` call, it will require an additional call to `Outbox.executeTransaction` on L1 after the dispute period elapses for the user to finalize claiming their funds on L1 (see ["L2 to L1 Messages"](/how-arbitrum-works/arbos/l2-l1-messaging.mdx)). Once the withdrawal is executed from the Outbox, the user's Ether balance will be credited on L1. +`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 L1 after the dispute period elapses for the user to finalize claiming their funds on L1 (see ["L2 to L1 Messages"](/how-arbitrum-works/11-l2-to-l1-messaging.mdx)). Once the withdrawal is executed from the Outbox, the user's Ether balance will be credited on L1. The following diagram depicts the process that funds follow during a withdraw operation. diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx b/arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx index 4cd915dc0..78dbccc62 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx @@ -44,11 +44,11 @@ Our architecture consists of three types of contracts: ![img](./assets/gatewayUML.svg) -All Ethereum to Arbitrum token transfers are initiated via the router contract on L1, the `L1GatewayRouter` contract. `L1GatewayRouter` forwards the token's deposit call to the appropriate gateway contract on L1, the `L1ArbitrumGateway` contract. `L1GatewayRouter` is responsible for mapping L1 token addresses to L1Gateway contracts, thus acting as an L1/L2 address oracle, and ensuring that each token corresponds to only one gateway. The `L1ArbitrumGateway` then communicates to its counterpart gateway contract on L2, the `L2ArbitrumGateway` contract (typically/expectedly via [retryable tickets](/how-arbitrum-works/arbos/l1-l2-messaging.mdx)). +All Ethereum to Arbitrum token transfers are initiated via the router contract on L1, the `L1GatewayRouter` contract. `L1GatewayRouter` forwards the token's deposit call to the appropriate gateway contract on L1, the `L1ArbitrumGateway` contract. `L1GatewayRouter` is responsible for mapping L1 token addresses to L1Gateway contracts, thus acting as an L1/L2 address oracle and ensuring each token corresponds to only one gateway. The `L1ArbitrumGateway` then communicates to its counterpart gateway contract on L2, the `L2ArbitrumGateway` contract (typically/expectedly via [retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx)). ![img](./assets/bridge_deposits.png) -Similarly, Arbitrum to Ethereum transfers are initiated via the router contract on L2, the `L2GatewayRouter` contract, which calls the token's gateway contract on L2, the `L2ArbitrumGateway` contract, which in turn communicates to its corresponding gateway contract on L1, the `L1ArbitrumGateway` contract (typically/expectedly via [sending L2-to-L1 messages to the outbox](/how-arbitrum-works/arbos/l2-l1-messaging.mdx)). +Similarly, Arbitrum to Ethereum transfers are initiated via the router contract on L2, the `L2GatewayRouter` contract, which calls the token's gateway contract on L2, the `L2ArbitrumGateway` contract, which in turn communicates to its corresponding gateway contract on L1, the `L1ArbitrumGateway` contract (typically/expectedly via [sending L2-to-L1 messages to the outbox](/how-arbitrum-works/11-l2-to-l1-messaging.mdx)). ![img](./assets/bridge_withdrawals.png) diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx index f54a4a12e..1d584001c 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx @@ -172,7 +172,7 @@ As mentioned before, you can also call the method `outboundTransferCustomRefund` ## Step 5: Wait for execution on L2 -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 is executed on L2. We will verify the status of the underlying retryable ticket created to bridge the tokens. Check this page, to know more about [L1-to-L2 messages, also known as retryables](/how-arbitrum-works/arbos/l1-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 is executed on L2. We will verify the status of the underlying retryable ticket created to bridge the tokens. Check this page to learn more about [L1-to-L2 messages, also known as retryables](/how-arbitrum-works/10-l1-to-l2-messaging.mdx). You can programmatically wait for the execution of the transaction on L2 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 L2 transaction. diff --git a/arbitrum-docs/for-devs/third-party-docs/Venly/venly.md b/arbitrum-docs/for-devs/third-party-docs/Venly/venly.md new file mode 100644 index 000000000..66fc4e811 --- /dev/null +++ b/arbitrum-docs/for-devs/third-party-docs/Venly/venly.md @@ -0,0 +1,224 @@ +--- +title: 'Venly Tools <> Arbitrum' +description: 'Venly Tools stand on three pillars: Digital Wallets, Digital Assets, and Payments' +author: Abdullah Baig +sme: abdullahvenly +sidebar_label: 'Venly' +--- + +## [Venly](https://venly.io/) + +Venly stands out as a cutting-edge developer platform, designed to streamline digital asset management and foster the creation of innovative blockchain solutions. Known for its exceptional performance and strong security features, Venly’s non-custodian model ensures you retain complete ownership and control of your assets, distinguishing it from other platforms. + +At Venly, the core principles guide their commitment to you: + +- **Security First**: Venly prioritizes the highest level of security for your assets and operations. +- **Developer-Centric**: Venly's intuitive tools and resources are designed to empower developers to achieve success. +- **Optimal Performance**: Venly guarantees consistent high performance with a focus on efficiency and reliability. +- **Innovation**: They are dedicated to providing cutting-edge solutions, staying at the forefront of technology. + +The [Venly](https://venly.io/) platform is anchored by three main pillars: **Digital Wallets, Digital Assets, and Payments**, each seamlessly integrated to enhance your blockchain experience. + +``` +Venly Tools +│ +├── Digital Wallets: Secure & scalable SSS-based wallets. +│ +├── Digital Assets: API solutions for digital assets. +│ +├── Payments: Customizable payment forms for fiat. +│ +├── Gaming SDK: +│ │ +│ ├── Unity: C# SDK +│ │ +│ └── Unreal Engine: C++ SDK +│ +└── Integrations: + │ + ├── Zapier: no-code NFT minting with zaps. + │ + ├── Shopify: Selling NFTs made easy. + │ + └── SiteManager: Create mint pages in minutes, all no-code. +``` + +### [Digital Wallets](https://docs.venly.io/docs/wallet-api-overview) + +Secure and scalable SSS-based wallets with robust key management custody digital assets. The Venly security protocol redefines private key security, never gathering a private key as one whole, eliminating risk. Venly customers use their wallets for a range of operations, such as treasury, trading, cold storage, royalties, NFTs, smart contracts, user wallets, and other digital assets. + +### [Digital Assets](https://docs.venly.io/docs/nft-api-overview) + +Robust tokenization is based on industry standards and is secured by several code and security audits. The Venly platform facilitates no-code and API solutions to manage, transfer, and gather information on different token asset classes, such as ERC20, ERC721, and ERC1155, which customers use in industries such as Finance, E-commerce, and Gaming. + +### [Payments](https://docs.venly.io/docs/pay-api-overview) + +With PAY, the Venly platform offers a low-code payment integration that creates a customizable form for collecting payments. You can embed Pay directly on your website or redirect customers to a hosted payment page. It offers a wide range of payment methods, from credit cards to PayPal, Apple Pay, Google Pay, instant bank transfers, and more, enabling customers to choose their preferred option. + +## Product Specific Documentation + +| Category | Product | Documentation | +| :-------------- | :------------------------------ | :----------------------------------------------------------------------------- | +| Digital Wallets | Widget | [API Reference](https://venly.readme.io/docs/product-overview) | +| Digital Wallets | Wallet API | [API Reference](https://venly.readme.io/reference/viewwallet) | +| Digital Assets | NFT API | [API Reference](https://docs.venly.io/reference/getcontracts-1) | +| Digital Assets | Shopify NFT Minting Application | [App Store](https://apps.shopify.com/partners/arkane-network1) | +| Digital Assets | Zapier Integration | [Documentation](https://docs.venly.io/docs/zapier-integration) | +| Digital Assets | SiteManager | [Documentation](https://docs.venly.io/docs/sitemanager) | +| Payments | Venly PAY | [API Reference](https://docs.venly.io/docs/pay-api-overview) | +| Gaming SDK | Unity | [Documentation](https://docs.venly.io/docs/getting-started-with-unity) | +| Gaming SDK | Unreal Engine | [Documentation](https://docs.venly.io/docs/getting-started-with-unreal-engine) | + +# [Venly](https://venly.io/) - Arbitrum + +Venly supports the Arbitrum chain on its Wallet API which allows you to create wallets on the Arbitrum chain. You can send and receive funds to/from Arbitrum wallets directly through the Wallet API, enabling seamless integration with applications using the Arbitrum blockchain. + +# Wallet API + +The Wallet API allows developers to interact with blockchain networks and offer wallet functionality to their users without having to build everything from scratch. This can include features like account creation, transaction management, balance inquiries, and more. + +- Welcome your users with custom wallet branding. You can customize the user interface to your requirements. +- You are completely in charge of the wallet user experience to optimize user conversion. Get total freedom with regard to UX and asset management with the Venly Wallet API. +- You and your users have complete control over digital assets without any third-party interference. Securely manage wallets with complete autonomy and privacy. +- In the event of loss of login credentials, you and your users can recover access to wallets with a security code or biometric verification. + +## Key features + +| Features | Description | +| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Wallet management | Developers can use the API to create, manage, and secure wallets for their users. | +| Transaction services | The API can enable the initiation and monitoring of blockchain transactions. | +| Token support | It may allow the handling of various tokens and assets on supported blockchain networks. | +| Blockchain interactions | Developers can integrate functionalities like reading data from the blockchain or writing data to it, along with creating and interacting with smart contracts. | +| Security features | The API might offer features to enhance the security of user funds and transactions. | +| User experience enhancement | It can contribute to a smoother and more user-friendly interaction with blockchain applications. | +| Multi-blockchain support | Venly supports multiple blockchain networks, allowing developers to offer wallets for different cryptocurrencies. | + +## Creating an Arbitrum wallet + +### Prerequisites + +1. You need a Venly business account. If you don't have one, click to register [Developer Portal](https://portal.venly.io), or follow the [Getting Started with Venly](https://venly.readme.io/docs/getting-started) guide. + +2. You need your client ID and client secret which can be obtained from the [Portal](https://portal.venly.io/). + +3. You need a bearer token to authenticate API calls. Click [here](https://docs.venly.io/docs/authentication) to read how to authenticate. + +### Request Endpoint: [reference](https://docs.venly.io/reference/createwallet) + +```https +POST /api/wallets +``` + +#### Header params + +| Parameter | Param type | Value | Description | +| :--------------- | :--------- | :--------- | :-------------------------------------------------------------------------------------------- | +| `Signing-Method` | Header | `id:value` | `id`: This is the ID of the signing method. `value`: This is the value of the signing method. | + +#### Body params + +| Parameter | Param type | Description | Data type | Mandatory | +| :----------- | :--------- | :----------------------------------------------------- | :-------- | :-------- | +| `secretType` | Body | The blockchain on which to create the wallet | String | ✅ | +| `userId` | Body | The ID of the user who you want to link this wallet to | String | ❌ | + +### Request body + +```json +{ + "secretType": "ARBITRUM", + "userId": "9cf9228e-1f2b-4940-9508-4335064cbc76" +} +``` + +### Response body + +> Wallet created! The wallet has been created and linked to the specified user (`userId`). + +```json +{ + "success": true, + "result": { + "id": "590f7276-2886-475c-a2d6-a28421f8f367", + "address": "0xADc25e8A385213Fd820bc17Aa799076688f9fBd5", + "walletType": "API_WALLET", + "secretType": "ARBITRUM", + "createdAt": "2024-06-05T11:19:12.038340492", + "archived": false, + "description": "Elegant Moose", + "primary": false, + "hasCustomPin": false, + "userId": "9cf9228e-1f2b-4940-9508-4335064cbc76", + "custodial": false, + "balance": { + "available": true, + "secretType": "ARBITRUM", + "balance": 0, + "gasBalance": 0, + "symbol": "ETH", + "gasSymbol": "ETH", + "rawBalance": "0", + "rawGasBalance": "0", + "decimals": 18 + } + } +} +``` + +## Transferring Arbitrum Tokens + +### Request Endpoint: [reference](https://docs.venly.io/reference/executetransaction_1) + +```http +POST /api/transactions/execute +``` + +#### Header params + +| Parameter | Param type | Value | Description | +| :--------------- | :--------- | :--------- | :-------------------------------------------------------------------------------------------- | +| `Signing-Method` | Header | `id:value` | `id`: This is the ID of the signing method. `value`: This is the value of the signing method. | + +#### Body params + +| Parameter | Param Type | Description | Data Type | Mandatory | +| :------------------------------ | :--------- | :----------------------------------------------------------------- | :-------- | :-------- | +| `transactionRequest` | Body | This object includes the transaction information | Object | ✅ | +| transactionRequest.`type` | Body | This will be **TRANSFER** | String | ✅ | +| transactionRequest.`walletId` | Body | The `id` of the wallet that will initiate the tx | String | ✅ | +| transactionRequest.`to` | Body | Destination Address (can be a blockchain address or email address) | String | ✅ | +| transactionRequest.`secretType` | Body | On which blockchain the tx will be executed | String | ✅ | +| transactionRequest.`value` | Body | The amount you want to transfer | Integer | ✅ | + +### Request Body: + +```json +{ + "transactionRequest": { + "type": "TRANSFER", + "walletId": "590f7276-2886-475c-a2d6-a28421f8f367", + "to": "0x1588aCD59c9baF27C1b777eAa71A67d6b6024077", + "value": "0.0005", + "secretType": "ARBITRUM" + } +} +``` + +### Response Body: + +> The coins were successfully transferred! + +```json +{ + "success": true, + "result": { + "id": "34d51bb3-c963-486d-856e-1e3f12638e3d", + "transactionHash": "0x804d14bcda10628e61e7ae9085ecad63eafea09d3fdb3cb4ec8cb8dc312dc5b7" + } +} +``` + +### Next Steps + +> Ready to try it out? Click to read the [getting started guide for Wallet API.](https://docs.venly.io/docs/wallet-api-getting-started) diff --git a/arbitrum-docs/hosted-audit-reports/2024_12_26_trail_of_bits_boldfixes_securityreview.pdf b/arbitrum-docs/hosted-audit-reports/2024_12_26_trail_of_bits_boldfixes_securityreview.pdf new file mode 100644 index 000000000..0f9568c1e Binary files /dev/null and b/arbitrum-docs/hosted-audit-reports/2024_12_26_trail_of_bits_boldfixes_securityreview.pdf differ diff --git a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx new file mode 100644 index 000000000..e8ae0214d --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -0,0 +1,74 @@ +--- +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/'; + +This document is a deep-dive explanation of Arbitrum Nitro’s design and the rationale for it. This isn’t API documentation, nor is it a guided tour of the code--look elsewhere for those. “Inside Arbitrum Nitro” is for people who want to understand Nitro's design. + +The body of this document will describe Arbitrum Rollup, the primary use case of the Nitro technology and the one used on the Arbitrum One chain. There is a variant use case, called [AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx), which is used by the Arbitrum Nova chain. + +## Why use Arbitrum? Why use Nitro? + +Arbitrum is an L2 scaling solution for Ethereum, offering a unique combination of benefits: + +- Trustless security: security rooted in Ethereum, with any one + party able to ensure correct Layer 2 results +- Compatibility with Ethereum: able to run unmodified EVM contracts and unmodified Ethereum transactions +- Scalability: moving contracts’ computation and storage off of the main Ethereum chain, allowing much higher throughput +- Minimum cost: designed and engineered to minimize the L1 gas footprint of the system, minimizing per-Transaction cost. + +Some other Layer 2 systems provide some of these features, but to our knowledge no other system offers the same combination of features at the same cost. + +Nitro is a major upgrade to Arbitrum including: + +- **Advanced Calldata Compression,** which further drives down transaction costs on Arbitrum by reducing the amount of data posted to L1. +- **Separate Contexts For Common Execution and Fault Proving,** increasing the performance of L1 nodes, and thus offering lower fees. +- **Ethereum L1 Gas Compatibility,** bringing pricing and accounting for EVM operations perfectly in line with Ethereum. +- **Additional L1 Interoperability,** including tighter synchronization with L1 Block numbers, and full support for all Ethereum L1 precompiles. +- **Safe Retryables,** eliminating the failure mode where a Retryable Ticket fails to get created. +- **Geth Tracing,** for even broader debugging support. +- And many, many more changes. + +## The Big Picture + +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 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 -- which means that the chain’s behavior is uniquely determined by the contents of its inbox. Because of this, the result of your transaction is knowable as soon as your transaction has been 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 detail in this document is connected to this diagram. To get from this diagram to a full 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 very quick summary of each, then we'll 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 are organized into a single ordered sequence, and Nitro commits to that sequence. Then the transactions are 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 Layer 1 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/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx new file mode 100644 index 000000000..bd2928e9a --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -0,0 +1,62 @@ +--- +title: Sequencing, Followed by Deterministic Execution +description: 'Learn the fundamentals of the Arbitrum Transaction Lifecycle, sequencing, and deterministic execution.' +author: pete-vielhaber +sme: gmehta2 +user_story: As a current or prospective Arbitrum user, I need to learn more about the transaction lifecycle. +content_type: get-started +--- + +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 (Layer 1), 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: + +
+ ![submit-transaction-to-sequencer](../assets/submit-tx-to-sequencer.png) +
+ +## 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 sequencer inbox 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. + +
![bypassing-the-sequencer](../assets/bypassing-the-sequencer.png)
+ +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 L2 message to the chain, suitable for any message that does not require L1 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/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx new file mode 100644 index 000000000..fb0aff31f --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -0,0 +1,263 @@ +--- +title: The Sequencer and Censorship Resistance +description: 'Learn the fundamentals of the Arbitrum Sequencer.' +author: pete-vielhaber +sme: gmehta2 +user_story: As a current or prospective Arbitrum user, I need to learn more about the Sequencer. +content_type: get-started +--- + +The Sequencer is a pivotal component of the Arbitrum network and is responsible for efficiently ordering and processing transactions. It plays a crucial role in providing users with fast Transaction confirmations while maintaining the security and integrity of the Blockchain. In Arbitrum, the Sequencer orders incoming transactions and manages the batching, compression, and posting of transaction data to Parent chain, optimizing costs and performance. + +
![sequencer-operations](../assets/sequencer-operations.png)
+ +In this section, we will explore the operation of the Sequencer in detail. The topics covered include: + +- [Sequencing and Broadcasting (Sequencer Feed)](#sequencing-and-broadcasting): An overview of the real-time transaction feed provided by the Sequencer, which allows nodes to receive instant updates on the transaction sequence. +- [Batch-Posting](#batch-posting): How the Sequencer groups transactions into batches, compresses them to reduce data size and sends them to the Sequencer Inbox Contract on the parent chain. This section also delves into the L1 pricing model and how it affects transaction costs. + - [Batching](#batching-and-compression) + - [Compression](#compression) + - [Submitting to the Sequencer Inbox Contract](#submitting-to-the-sequencer-inbox-contract) +- [Finality](#finality): Understanding how transaction finality is achieved in Arbitrum through both soft and hard finality mechanisms, ensuring that transactions are confirmed securely and reliably. (not as a sequencer task) + +By examining these aspects, you will understand the Sequencer's role within the Arbitrum ecosystem, including how it enhances transaction throughput, reduces latency, and maintains a fair and decentralized network. + +## Sequencing and Broadcasting + +The **Sequencer Feed** is a critical component of the Arbitrum network's Nitro architecture. It enables real-time dissemination of transaction data as they are accepted and ordered by the Sequencer. It allows users and nodes to receive immediate updates on transaction sequencing, facilitating rapid transaction confirmations and enhancing the network's overall responsiveness. + +### How the Sequencer Publishes the Sequence + +The Sequencer communicates the transaction sequence through two primary channels: + +1. **Real-Time Sequencer Feed**: A live broadcast that publishes transactions instantly as they are sequenced. Nodes and clients subscribed to this feed receive immediate notifications, allowing them to process transactions without delay. +2. **Batches Posted on the Parent Chain**: At regular intervals, the Sequencer aggregates transactions and posts them to the parent chain for finality. (Refer to the Batch-Posting section for detailed information on this process.) + +
![sequencer-feed](../assets/sequencer-feed.png)
+ +### Real-Time Sequencer Feed + +The real-time feed represents the Sequencer's commitment to process transactions in a specific order. By subscribing to this feed, nodes and clients can: + +- **Receive Immediate Notifications**: Obtain instant information about newly sequenced transactions and their ordering. +- **Process Transactions Promptly**: Utilize the sequenced transactions to update the state locally, enabling rapid application responses and user interactions. +- **Benefit from Soft Finality**: Gain provisional assurance about transaction acceptance and ordering before the parent chain reaches finality. + +This mechanism is particularly valuable for applications requiring low latency and high throughput, such as decentralized exchanges or real-time gaming platforms. + +### Soft Finality and Trust Model + +"Soft finality" refers to the preliminary Confirmation of transactions based on the Sequencer's real-time feed. Key aspects include: + +- **Dependence on Sequencer Integrity**: The feed's accuracy and reliability depend on the Sequencer operating honestly and without significant downtime. +- **Immediate User Feedback**: Users can act on transaction confirmations swiftly, improving the user experience. +- **Eventual Consistency with the Parent Chain**: While the real-time feed provides quick updates, ultimate security, and finality are established once transactions are posted to and finalized on the parent chain. (See the **Finality** section for an in-depth discussion.) + +Understanding this trust model is essential. While we expect the Sequencer to behave correctly, users and developers should know that soft finality depends on this assumption. In scenarios where absolute certainty is required, parties may wait for transactions to achieve finality on the parent chain. + +### Role of the Sequencer Feed in the Network + +The Sequencer Feed serves several vital functions within the Arbitrum ecosystem: + +- **State Synchronization**: Nodes use the feed to stay synchronized with the latest state of the network, ensuring consistency across the decentralized platform. +- **Application Development**: Developers can build applications that respond instantly to network events, enabling features like live updates, instant notifications, and real-time analytics. +- **Ecosystem Transparency**: The feed promotes transparency and trust within the community by providing visibility into transaction sequencing and network activity. + +### Considerations and Limitations + +While the Sequencer Feed offers significant advantages, consider the following: + +- **Reliance on Sequencer Availability**: The effectiveness of the real-time feed depends on the Sequencer's uptime and responsiveness. Network issues or Sequencer downtime can delay transaction visibility. +- **Provisional Nature of Soft Finality**: Until transactions reach finality on the parent chain, there is a small risk that the provisional ordering provided by the feed could change in exceptional circumstances. +- **Security Implications**: For high-stakes transactions where security is paramount (e.g., centralized exchange deposits and withdrawals), users may prefer to wait for parent chain confirmation despite the longer latency. + +Developers and users should design their applications and interactions with these factors in mind, choosing the appropriate balance between speed and certainty based on their requirements. + +### **Delayed Messages on the Sequencer Feed** + +As illustrated in the diagram, the Sequencer feed not only sends Child chain transactions posted directly to the Sequencer but also incorporates parent chain-submitted child chain transactions. These include L2 messages submitted on L1 and retryable transactions. The Sequencer agent monitors the finalized messages submitted to the parent chain's Delayed Inbox Contract. Once finalized, it processes them as incoming messages to the feed, ensuring they are added as ordered transactions. + +It is important to note that the Nitro node can be configured to add delayed inbox transactions immediately after their submission to the parent chain, even before finalization. However, this approach introduces a risk of child chain reorganization if the transaction fails to finalize on the parent chain. To mitigate this risk, on Arbitrum One and Nova, the Sequencer only includes these transactions in the feed once they are finalized on the Ethereum chain. + +You can also explore how the feed sends incoming messages via WebSocket and learn how to extract message data from the feed on this page: [Read Sequencer Feed](https://docs.arbitrum.io/run-arbitrum-node/sequencer/read-sequencer-feed). + +## Batch-Posting + +Batch-Posting is a fundamental process in the operation of the Sequencer within the Arbitrum network. It involves collecting multiple child chain transactions, organizing them into batches, compressing the data to reduce size, and sending these batches to the Sequencer Inbox Contract on parent chain. This mechanism is crucial for ensuring that transactions are securely recorded on the parent chain blockchain while optimizing for cost and performance. + +In this section, we will explore the Batch-Posting process in detail, covering the following topics: + +- **Batching**: How the Sequencer groups incoming transactions into batches for efficient processing and posting. +- **Compression**: The methods used to compress transaction data, minimizing the amount of data that needs to be posted on parent chain and thereby reducing costs. +- **Sending to Sequencer Inbox Contract**: The procedure for submitting compressed batches to the Sequencer Inbox Contract on parent chain, ensuring secure and reliable recording of transactions. + +Understanding Batch-Posting is essential for grasping how Arbitrum achieves scalability and cost-efficiency without compromising security. By delving into these subtopics, you'll gain insight into the Sequencer's role in optimizing transaction throughput and minimizing fees, as well as the innovative solutions implemented to address the challenges of Layer 1 data pricing. + +## Batching and compression + +The Sequencer in Arbitrum is critical in collecting and organizing child chain transactions before posting them to the parent chain. The batching process is designed to optimize for both cost efficiency and timely transaction inclusion. + +
![batching](../assets/batching.png)
+ +**Transaction Collection and Ordering:** + +- **Continuous Reception:** The Sequencer continuously receives transactions submitted by users. +- **Ordering:** Transactions are ordered based on the sequence in which they are received, maintaining a deterministic transaction order. +- **Buffering:** Received transactions are temporarily stored in a buffer awaiting batch formation. + +**Batch Formation Criteria:** + +- **Size Thresholds:** Batch formation occurs when accumulated transactions reach a predefined size limit. This limit ensures that the fixed costs of posting data to the parent chain are amortized over more transaction, improving cost efficiency. +- **Time Constraints:** The Sequencer also monitors the time elapsed since the last posted batch to prevent undue delays. Upon reaching the maximum time threshold, the Sequencer will create a batch with the transactions collected so far, even if the batch doesn't meet the size threshold. + +**Batch Creation Process:** + +- **Aggregation:** Once the batch formation criteria ( the size or time threshold) are satisfied, the Sequencer aggregates the buffered transactions into a single batch. +- **Metadata Inclusion:** The batch includes the necessary metadata of all transactions. +- **Preparation for Compression:** Batch preparation for the compression stage begins, where techniques will minimize the data size before posting to parent chain. + +This batching mechanism allows the Sequencer to efficiently manage transactions by balancing the need for cost-effective parent chain posting with the requirement for prompt transaction processing. By strategically grouping transactions into batches based on size and time criteria, the Sequencer reduces per-transaction costs and enhances the overall scalability of the Arbitrum network. + +### Compression + +The Sequencer employs compression when forming transaction batches to optimize the data and cost of batches posted to the parent chain. Arbitrum uses the Brotli compression algorithm due to its high compression ratio and efficiency, crucial for reducing parent chain posting costs. + +
![compression](../assets/compression.png)
+ +### Compression level in the Brotli algorithm + +Brotli’s compression algorithm includes a parameter: **compression level**, which ranges from **0 to 11**. This parameter allows you to balance two key factors: + +- **Compression Efficiency**: Higher levels result in greater size reduction. +- **Computational Cost**: Higher levels require more processing power and time. + +As the compression level increases, you achieve better compression ratios at the expense of longer compression times. + +### Dynamic compression level setting + +The compression level on Arbitrum is dynamically adjusted based on the current backlog of batches waiting to be posted to parent chain by Sequencer. In scenarios where multiple batches are queued in the buffer, the **compression level** can be dynamically adjusted to improve throughput. When the buffer becomes overloaded with overdue batches, the compression level decreases. + +This tradeoff prioritizes speed over compression efficiency, enabling faster processing and transmitting pending batches. Doing so, clears the buffer more quickly, ensuring smoother overall system performance. + +Now that transactions are batched and compressed, they can be passed to batch-poster to be sent to the parent chain. + +## Submitting to the Sequencer Inbox Contract + +After batching and compressing transactions, the Sequencer posts these batches to the parent chain to ensure security and finality. This process involves the **Batch Poster**, an Externally Owned Account (EOA) controlled by the Sequencer. The Batch Poster is responsible for submitting the compressed transaction batches to the **Sequencer Inbox Contract** on parent chain. + +There are two primary methods the Sequencer uses to send batches to the parent chain, depending on whether the chain supports EIP-4844 (Proto-Danksharding) and the current network conditions: + +
+ ![submit-to-sequencer-inbox](../assets/submit-to-sequencer-inbox.png) +
+ +### 1. Using Blobs with `addSequencerL2BatchFromBlobs` + +- **Default Approach**: When the parent chain supports EIP-4844, the Sequencer utilizes blob transactions to post batches efficiently. +- **Method**: The Batch Poster calls the `addSequencerL2BatchFromBlobs` function of the Sequencer Inbox Contract. +- **Process**: + - Batch data gets included as blobs—large binary data structures optimized for scalability. + - The transaction includes metadata about the batch but does not include the batch data itself in the calldata. +- **Benefits**: + - **Cost Efficiency**: Blobs allow cheaper data inclusion than calldata, reducing gas costs. + - **Scalability**: Leveraging blobs enhances the network's ability to handle large volumes of transactions. + +### 2. Using Calldata with `addSequencerL2Batch` + +- **Alternative Approach**: If the **Blob Base Fee** is significantly high or the blob space is constrained during batch posting, the Sequencer may opt to use calldata. +- **Method**: The Batch Poster calls the `addSequencerL2Batch` function of the Sequencer Inbox Contract. +- **Process**: + - The compressed batch transactions are included directly in the transaction's calldata. +- **Considerations**: + - **Cost Evaluation**: The Sequencer dynamically assesses whether using calldata is more cost-effective than blobs based on current gas prices and blob fees. + - **Compatibility**: If the parent chain does not support EIP-4844, this method is the default and only option for batch posting. + +:::note +The Sequencer continuously monitors network conditions to choose the most economical method for batch posting, ensuring optimal operation under varying circumstances. +::: + +### Authority and Finality + +- **Exclusive Access**: Only the Sequencer can call these methods on the Sequencer Inbox Contract. This exclusivity ensures that no other party can directly include messages. +- **Soft-Confirmation Receipts**: The Sequencer's unique ability to immediately process and include transactions allows it to provide users with instant, "soft-confirmation" receipts, +- **Parent chain Finality**: Once batches post, the transactions achieve parent-chain-level finality, secured by Parent chain’s consensus mechanism. + +By efficiently sending compressed transaction batches to the Sequencer Inbox Contract using the most cost-effective method available, the Sequencer ensures transactions are securely recorded on parent chain. This process maintains the integrity and reliability of the network, providing users with fast and secure transaction processing. + +## Finality + +Finality in blockchain systems refers to the point at which a transaction becomes irreversible and permanently included in the blockchain's ledger. In the context of Arbitrum's Nitro architecture, understanding finality is crucial for developers and users to make informed decisions about transaction confirmations, security guarantees, and application design. + +Arbitrum offers two levels of finality: + +1. **Soft Finality**: Provided by the Sequencer's real-time feed, offering immediate but provisional transaction confirmations. +2. **Hard Finality**: Occurs when transactions are included in batches posted to and finalized on the parent chain, providing strong security assurances. + +This section explores the concepts of soft and hard finality, their implications, trust considerations, and guidance for utilizing them effectively within the Arbitrum network. + +### Soft Finality + +Soft finality refers to the preliminary confirmation of transactions based on the Sequencer's real-time feed. Key characteristics include: + +- **Immediate Confirmation**: Transactions are confirmed almost instantly as they are accepted and ordered by the Sequencer. +- **Provisional Assurance**: The confirmations are provisional and rely on the Sequencer's integrity and availability. +- **High Performance**: Enables applications to offer rapid responses and real-time interactions, enhancing user experience. + +**Advantages of Soft Finality**: + +- **Low Latency**: Users receive immediate feedback on transaction status. +- **Optimized for Speed**: Ideal for applications where responsiveness is critical. +- **Improved User Experience**: Reduces waiting times and uncertainty. + +**Limitations of Soft Finality**: + +- **Trust Dependency**: Relies on the Sequencer's honesty and ability to maintain uptime.. +- **Potential for Reordering**: In rare cases, if the Sequencer acts maliciously or encounters issues, the provisional ordering could change. +- **Not Suitable for High-Value Transactions**: For transactions requiring strong security guarantees, soft finality may not suffice. + +### Hard Finality + +Hard finality occurs when batched transactions get posted to the parent chain. Key characteristics include: + +- **Strong Security Guarantees**: When included in blocks on the parent chain, transactions inherit the parent chain's security assurances. +- **Irreversibility**: Once finalized, transactions are immutable and cannot be altered or reversed. +- **Data Availability**: All transaction data is recorded on-chain, ensuring transparency and verifiability. + +**Advantages of Hard Finality**: + +- **Maximum Security**: Protected by the robustness of the parent chain's consensus mechanism. +- **Trust Minimization**: This does not require trust in the Sequencer; security comes from the underlying blockchain. +- **Suitable for High-Value Transactions**: Ideal for scenarios where security and immutability are paramount. + +**Limitations of Hard Finality**: + +- **Higher Latency**: Achieving hard finality takes longer due to the time required for the parent chain to process and finalize batches. +- **Cost Considerations**: Posting batches to the parent chain incurs fees, which may affect transaction costs. + +### Trust Considerations + +Understanding the trust assumptions associated with each level of finality is essential: + +- **Soft Finality Trust Model**: + - **Reliance on the Sequencer**: Users must trust that the Sequencer operates honestly, sequences transactions correctly, and remains available. + - **Risk of Misbehavior**: If the Sequencer acts maliciously, it could reorder or censor certain transactions before they achieve hard finality. +- **Hard Finality Trust Model**: + - **Reliance on the Parent Chain**: Security is based on the consensus and integrity of the parent chain. + - **Reduced Trust in Sequencer**: Even if the Sequencer misbehaves, transactions included in posted batches are secured once finalized on the parent chain. + +### Application Implications + +Developers and users should consider the appropriate level of finality based on their specific use cases: + +- **When to Rely on Soft Finality**: + - **Low-Risk Transactions**: For transactions where the potential impact of reordering or delays is minimal. + - **User Experience Priority**: Applications where responsiveness and immediacy enhance user engagement, such as gaming or social platforms. + - **Frequent Transactions**: Scenarios involving a high volume of small transactions where waiting for hard finality is impractical. +- **When to Require Hard Finality**: + - **High-Value Transactions**: Financial transfers, large trades, or any transaction where security is critical. + - **Regulatory Compliance**: Situations requiring strict adherence to security standards and auditable records. + - **Centralized Exchanges (CeXs)**: For deposit and withdrawal operations where certainty of transaction finality is mandatory. + +### Decentralized Fair Sequencing + +Arbitrum’s long-term vision includes transitioning from a centralized Sequencer to a decentralized, fair sequencing model. In this framework, a committee of servers (or validators) collectively determines transaction ordering, ensuring fairness, reducing the influence of any single party, and making it more resistant to manipulation. By requiring a supermajority consensus, this approach distributes sequencing power among multiple honest participants, mitigates the risks of front-running or censorship, and aligns with the broader blockchain principles of enhanced security, transparency, and decentralization. diff --git a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx new file mode 100644 index 000000000..f8e8e539b --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -0,0 +1,423 @@ +--- +title: Geth at the core +description: Learn the fundamentals of Geth and ArbOS. +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Geth and ArbOS. +content_type: get-started +--- + +The second key design idea in Nitro is "Geth at the core." Here "geth" refers to go-ethereum, the most common node software for Ethereum. As its name would suggest, go-ethereum is written in the Go programming language, as is almost all of Nitro. + +![geth-sandwich](../assets/geth-sandwich.png) + +The software that makes up a Nitro node can be thought of as built in three main layers, which are shown above: + +- The base layer is the core of geth--the parts of Geth that emulate the execution of EVM contracts and maintain the data structures that make up the Ethereum state. Nitro compiles in this code as a library, with a few minor modifications to add necessary hooks. +- The middle layer, which we call ArbOS, is custom software that provides additional functions associated with Layer 2 functionality, such as decompressing and parsing the Sequencer's data batches, accounting for Layer 1 gas costs and collecting fees to reimburse for them, and supporting cross-chain Bridge functionalities such as deposits of Ether and tokens from L1 and withdrawals of the same back to L1. We'll dig in to the details of ArbOS below. +- The top layer consists of node software, mostly drawn from geth. This handles connections and incoming RPC requests from clients and provides the other top-level functionality required to operate an Ethereum-compatible Blockchain node. + +Because the top and bottom layers rely heavily on code from geth, this structure has been dubbed a "geth sandwich." Strictly speaking, Geth plays the role of the bread in the sandwich, and ArbOS is the filling, but this sandwich is named for the bread. + +The State Transition Function consists of the bottom Geth layer, and a portion of the middle ArbOS layer. In particular, the STF is a designated function in the source code, and implicitly includes all of the code called by that function. The STF takes as input the bytes of a Transaction received in the inbox, and has access to a modifiable copy of the Ethereum state tree. Executing the STF may modify the state, and at the end will emit the header of a new block (in Ethereum's block header format) which will be appended to the Nitro chain. + +The rest of this section will be a deep dive into Geth and ArbOS. If deep technical knowledge does not suit you, skip to the next section [Separating Execution from Proving](/how-arbitrum-works/05-separating-execution-from-proving.mdx). + +## Geth + +Nitro makes minimal modifications to Geth in hopes of not violating its assumptions. This section will explore the relationship between Geth and ArbOS, which consists of a series of hooks, interface implementations, and strategic re-appropriations of Geth's basic types. + +We store ArbOS's state at an address inside a Geth `statedb`. In doing so, ArbOS inherits the `statedb`'s statefulness and lifetime properties. For example, a transaction's direct state changes to ArbOS are discarded upon a revert. + +**0xA4B05FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF**
+The fictional account representing ArbOS + +:::info + +Please note any links on this page may be referencing old releases of Nitro or our fork of Geth. While we try to keep this up to date and most of this should be stable, please check against latest releases for [Nitro](https://github.com/OffchainLabs/nitro/releases) and [Geth](https://github.com/OffchainLabs/go-ethereum/releases) for most recent changes. + +::: + +### Hooks + +Arbitrum uses various hooks to modify Geth's behavior when processing +transactions. Each provides an opportunity for ArbOS to update its state and make decisions about the +transaction during its lifetime. Transactions are applied using Geth's [`ApplyTransaction`][applytransaction_link] +function. + +Below is [`ApplyTransaction`][applytransaction_link]'s callgraph, with additional info on where the various Arbitrum-specific hooks are inserted. Click on any to go to their section. By default, these hooks do nothing so as to leave Geth's default behavior unchanged, but for chains configured with [`EnableArbOS`](#enablearbos) set to true, [`ReadyEVMForL2`](#ReadyEVMForL2) installs the alternative L2 hooks. + +- `core.ApplyTransaction` ⮕ `core.applyTransaction` ⮕ `core.ApplyMessage` + - `core.NewStateTransition` + - [`ReadyEVMForL2`](#ReadyEVMForL2) + - `core.TransitionDb` + - [`StartTxHook`](#StartTxHook) + - `core.transitionDbImpl` + - if `IsArbitrum()` remove tip + - [`GasChargingHook`](/how-arbitrum-works/geth-at-the-core#gascharginghook) + - `evm.Call` + - `core.vm.EVMInterpreter.Run` + - [`PushCaller`](#PushCaller) + - `PopCaller` + - `core.StateTransition.refundGas` + - [`ForceRefundGas`](#ForceRefundGas) + - [`NonrefundableGas`](#NonrefundableGas) + - [`EndTxHook`](#EndTxHook) + - added return parameter: `transactionResult` + +What follows is an overview of each hook, in chronological order. + +#### [`ReadyEVMForL2`][readyevmforl2_link]{#ReadyEVMForL2} + +A call to [`ReadyEVMForL2`][readyevmforl2_link] installs the other transaction-specific hooks into each Geth [`EVM`][evm_link] right before it performs a state transition. Without this call, the state transition will instead use the default [`DefaultTxProcessor`][defaulttxprocessor_link] and get exactly the same results as vanilla Geth. A [`TxProcessor`][txprocessor_link] object is what carries these hooks and the associated Arbitrum-specific state during the transaction's lifetime. + +#### [`StartTxHook`][starttxhook_link]{#StartTxHook} + +The [`StartTxHook`][starttxhook_link] is called by Geth before a transaction starts executing. This allows ArbOS to handle two Arbitrum-specific transaction types. + +If the transaction is `ArbitrumDepositTx`, ArbOS adds balance to the destination account. This is safe because the L1 bridge submits such a transaction only after collecting the same amount of funds on L1. + +If the transaction is an `ArbitrumSubmitRetryableTx`, ArbOS creates a retryable based on the transaction's fields. If the transaction includes sufficient gas, ArbOS schedules a retry of the new retryable. + +The hook returns `true` for both of these transaction types, signifying that the state transition is complete. + +#### [`GasChargingHook`][gascharginghook_link] + +This fallible hook ensures the user has enough funds to pay their poster's L1 calldata costs. If not, the transaction is reverted and the [`EVM`][evm_link] does not start. In the common case that the user can pay, the amount paid for calldata is set aside for later reimbursement of the poster. All other fees go to the network account, as they represent the transaction's burden on validators and nodes more generally. + +If the user attempts to purchase compute gas in excess of ArbOS's per-block gas limit, the difference is [set aside][difference_set_aside_link] and [refunded later][refunded_later_link] via [`ForceRefundGas`](#ForceRefundGas) so that only the gas limit is used. Note that the limit observed may not be the same as that seen [at the start of the block][that_seen_link] if ArbOS's larger gas pool falls below the [`MaxPerBlockGasLimit`][max_perblock_limit_link] while processing the block's previous transactions. + +[difference_set_aside_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L407 +[refunded_later_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state_transition.go#L419 +[that_seen_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/block_processor.go#L176 +[max_perblock_limit_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/l2pricing/l2pricing.go#L86 + +#### [`PushCaller`][pushcaller_link]{#PushCaller} + +These hooks track the callers within the EVM callstack, pushing and popping as calls are made and complete. This provides [`ArbSys`](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) with info about the callstack, which it uses to implement the methods `WasMyCallersAddressAliased` and `MyCallersAddressWithoutAliasing`. + +#### [`L1BlockHash`][l1blockhash_link] + +In Arbitrum, the BlockHash and Number operations return data that relies on underlying L1 blocks instead of L2 blocks, to accommodate the normal use-case of these opcodes, which often assume Ethereum-like time passes between different blocks. The L1BlockHash and L1BlockNumber hooks have the required data for these operations. + +#### [`ForceRefundGas`][forcerefundgas_link]{#ForceRefundGas} + +This hook allows ArbOS to add additional refunds to the user's tx. This is currently only used to refund any compute gas purchased in excess of ArbOS's per-block gas limit during the [`GasChargingHook`](/how-arbitrum-works/geth-at-the-core#gascharginghook). + +#### [`NonrefundableGas`][nonrefundablegas_link]{#NonrefundableGas} + +Because poster costs come at the expense of L1 aggregators and not the network more broadly, the amounts paid for L1 calldata should not be refunded. This hook provides Geth access to the equivalent amount of L2 gas the poster's cost equals, ensuring this amount is not reimbursed for network-incentivized behaviors like freeing storage slots. + +#### [`EndTxHook`][endtxhook_link]{#EndTxHook} + +The [`EndTxHook`][endtxhook_link] is called after the [`EVM`][evm_link] has returned a transaction's result, allowing one last opportunity for ArbOS to intervene before the state transition is finalized. Final gas amounts are known at this point, enabling ArbOS to credit the network and poster each's share of the user's gas expenditures as well as adjust the pools. The hook returns from the [`TxProcessor`][txprocessor_link] a final time, in effect discarding its state as the system moves on to the next transaction where the hook's contents will be set afresh. + +[applytransaction_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state_processor.go#L152 +[evm_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/vm/evm.go#L101 +[defaulttxprocessor_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/vm/evm_arbitrum.go#L42 +[txprocessor_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L38 +[starttxhook_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L100 +[readyevmforl2_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbstate/geth-hook.go#L47 +[gascharginghook_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L354 +[pushcaller_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L76 +[popcaller_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L80 +[forcerefundgas_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L425 +[nonrefundablegas_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L418 +[endtxhook_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L429 +[l1blockhash_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L617 +[l1blocknumber_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L600 + +### Interfaces and components + +#### [`APIBackend`][apibackend_link] + +APIBackend implements the [`ethapi.Backend`][ethapi.backend_link] interface, which allows simple integration of the Arbitrum chain to existing Geth API. Most calls are answered using the Backend member. + +[apibackend_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/apibackend.go#L34 +[ethapi.backend_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/internal/ethapi/backend.go#L42 + +#### [`Backend`][backend_link] + +This struct was created as an Arbitrum equivalent to the [`Ethereum`][ethereum_link] struct. It is mostly glue logic, including a pointer to the ArbInterface interface. + +[backend_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/backend.go#L15 +[ethereum_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/eth/backend.go#L68 + +#### [`ArbInterface`][arbinterface_link] + +This interface is the main interaction-point between geth-standard APIs and the Arbitrum chain. Geth APIs mostly either check status by working on the Blockchain struct retrieved from the [`Blockchain`][blockchain_link] call, or send transactions to Arbitrum using the [`PublishTransactions`][publishtransactions_link] call. + +[arbinterface_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/arbos_interface.go#L10 +[blockchain_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/arbos_interface.go#L12 +[publishtransactions_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/arbos_interface.go#L11 + +#### [`RecordingKV`][recordingkv_link] + +RecordingKV is a read-only key-value store, which retrieves values from an internal trie database. All values accessed by a RecordingKV are also recorded internally. This is used to record all preimages accessed during block creation, which will be needed to prove execution of this particular block. +A [`RecordingChainContext`][recordingchaincontext_link] should also be used, to record which block headers the block execution reads (another option would be to always assume the last 256 block headers were accessed). +The process is simplified using two functions: [`PrepareRecording`][preparerecording_link] creates a stateDB and chaincontext objects, running block creation process using these objects records the required preimages, and [`PreimagesFromRecording`][preimagesfromrecording_link] function extracts the preimages recorded. + +[recordingkv_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/recordingdb.go#L22 +[recordingchaincontext_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/recordingdb.go#L123 +[preparerecording_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/recordingdb.go#L152 +[preimagesfromrecording_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/recordingdb.go#L174 + +### Transaction Types + +Nitro Geth includes a few L2-specific transaction types. Click on any to jump to their section. + +| Tx Type | Represents | Last Hook Reached   | Source | +| :------------------------------------------------ | :----------------------------------------------------------------------- | :------------------------- | ------ | +| [`ArbitrumUnsignedTx`][arbtxunsigned] | An L1 to L2 message | [`EndTxHook`][he] | Bridge | +| [`ArbitrumContractTx`][arbtxcontract] | A nonce-less L1 to L2 message   | [`EndTxHook`][he] | Bridge | +| [`ArbitrumDepositTx`][arbtxdeposit] | A user deposit | [`StartTxHook`][hs] | Bridge | +| [`ArbitrumSubmitRetryableTx`][arbtxsubmit]   | Creating a retryable | [`StartTxHook`][hs]   | Bridge | +| [`ArbitrumRetryTx`][arbtxretry] | A Retryable Redeem attempt | [`EndTxHook`][he] | L2 | +| [`ArbitrumInternalTx`][arbtxinternal] | ArbOS state update | [`StartTxHook`][hs] | ArbOS | + +[arbtxunsigned]: #ArbitrumUnsignedTx +[arbtxcontract]: #ArbitrumContractTx +[arbtxsubmit]: #ArbitrumSubmitRetryableTx +[arbtxretry]: #ArbitrumRetryTx +[arbtxdeposit]: #ArbitrumDepositTx +[arbtxinternal]: #ArbitrumInternalTx +[hs]: #StartTxHook +[he]: #EndTxHook + +The following reference documents each type. + +#### [`ArbitrumUnsignedTx`][arbitrumunsignedtx_link]{#ArbitrumUnsignedTx} + +Provides a mechanism for a user on L1 to message a contract on L2. This uses the bridge for authentication rather than requiring the user's signature. Note, the user's acting address will be remapped on L2 to distinguish them from a normal L2 caller. + +#### [`ArbitrumContractTx`][arbitrumcontracttx_link]{#ArbitrumContractTx} + +These are like an [`ArbitrumUnsignedTx`][arbitrumunsignedtx_link] but are intended for smart contracts. These use the bridge's unique, sequential nonce rather than requiring the caller specify their own. An L1 contract may still use an [`ArbitrumUnsignedTx`][arbitrumunsignedtx_link], but doing so may necessitate tracking the nonce in L1 state. + +#### [`ArbitrumDepositTx`][arbitrumdeposittx_link]{#ArbitrumDepositTx} + +Represents a user deposit from L1 to L2. This increases the user's balance by the amount deposited on L1. + +#### [`ArbitrumSubmitRetryableTx`][arbitrumsubmitretryabletx_link]{#ArbitrumSubmitRetryableTx} + +Represents a retryable submission and may schedule an [`ArbitrumRetryTx`](#ArbitrumRetryTx) if provided enough gas. Please see the [retryables documentation](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#retryable-tickets) for more info. + +#### [`ArbitrumRetryTx`][arbitrumretrytx_link]{#ArbitrumRetryTx} + +These are scheduled by calls to the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile and via retryable auto-redemption. Please see the [retryables documentation](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#retryable-tickets) for more info. + +#### [`ArbitrumInternalTx`][arbitruminternaltx_link]{#ArbitrumInternalTx} + +Because tracing support requires ArbOS's state-changes happen inside a transaction, ArbOS may create a transaction of this type to update its state in-between user-generated transactions. Such a transaction has a [`Type`][internaltype_link] field signifying the state it will update, though currently this is just future-proofing as there's only one value it may have. Below are the internal transaction types. + +##### [`InternalTxStartBlock`][arbinternaltxstartblock_link] + +Updates the L1 block number and L1 base fee. This transaction [is generated][block_generated_link] whenever a new block is created. They are [guaranteed to be the first][block_first_link] in their L2 Block. + +[arbitrumunsignedtx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L43 +[arbitrumcontracttx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L104 +[arbitrumsubmitretryabletx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L232 +[arbitrumretrytx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L161 +[arbitrumdeposittx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L338 +[arbitruminternaltx_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/internal_tx.go +[internaltype_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L387 +[arbinternaltxstartblock_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/internal_tx.go#L22 +[block_generated_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/block_processor.go#L181 +[block_first_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/block_processor.go#L182 + +### Transaction Run Modes and Underlying Transactions + +A [geth message][geth_message_link] may be processed for various purposes. For example, a message may be used to estimate the gas of a contract call, whereas another may perform the corresponding state transition. Nitro Geth denotes the intent behind a message by means of its [`TxRunMode`][txrunmode_link], [which it sets][set_run_mode_link] before processing it. ArbOS uses this info to make decisions about the transaction the message ultimately constructs. + +A message [derived from a transaction][asmessage_link] will carry that transaction in a field accessible via its [`UnderlyingTransaction`][underlying_link] method. While this is related to the way a given message is used, they are not one-to-one. The table below shows the various run modes and whether each could have an underlying transaction. + +| Run Mode | Scope | Carries an Underlying Tx? | +| :--------------------------------------- | :---------------------- | :----------------------------------------------------------------------------------------------------------- | +| [`MessageCommitMode`][mc0] | state transition   | always | +| [`MessageGasEstimationMode`][mc1]   | gas estimation | when created via [NodeInterface](/build-decentralized-apps/nodeinterface/02-reference.mdx) or when scheduled | +| [`MessageEthcallMode`][mc2] | eth_calls | never | + +[mc0]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L654 +[mc1]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L655 +[mc2]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L656 +[geth_message_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L634 +[txrunmode_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L701 +[set_run_mode_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/internal/ethapi/api.go#L955 +[asmessage_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L676 +[underlying_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L700 + +### Arbitrum Chain Parameters + +Nitro's Geth may be configured with the following [l2-specific chain parameters][chain_params_link]. These allow the rollup creator to customize their rollup at genesis. + +#### `EnableArbos` + +Introduces [ArbOS](/how-arbitrum-works/04-geth-at-the-core.mdx#arbos), converting what would otherwise be a vanilla L1 chain into an L2 Arbitrum rollup. + +#### `AllowDebugPrecompiles` + +Allows access to debug precompiles. Not enabled for Arbitrum One. When false, calls to debug precompiles will always revert. + +#### `DataAvailabilityCommittee` + +Currently does nothing besides indicate that the rollup will access a data availability service for preimage resolution in the future. This is not enabled for Arbitrum One, which is a strict state-function of its L1 inbox messages. + +[chain_params_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/params/config_arbitrum.go#L25 + +### Miscellaneous Geth Changes + +#### ABI Gas Margin + +Vanilla Geth's abi library submits txes with the exact estimate the node returns, employing no padding. This means a transaction may revert should another arriving just before even slightly change the transaction's codepath. To account for this, we've added a `GasMargin` field to `bind.TransactOpts` that [pads estimates][pad_estimates_link] by the number of basis points set. + +#### Conservation of L2 ETH + +The total amount of L2 ether in the system should not change except in controlled cases, such as when bridging. As a safety precaution, ArbOS checks Geth's [balance delta][conservation_link] each time a block is created, [alerting or panicking][alert_link] should conservation be violated. + +#### MixDigest and ExtraData + +To aid with [Outbox proof construction][proof_link], the root hash and leaf count of ArbOS's [send merkle accumulator][merkle_link] are stored in the `MixDigest` and `ExtraData` fields of each L2 block. The yellow paper specifies that the `ExtraData` field may be no larger than 32 bytes, so we use the first 8 bytes of the `MixDigest`, which has no meaning in a system without miners/stakers, to store the send count. + +#### Retryable Support + +Retryables are mostly implemented in [ArbOS](/how-arbitrum-works/10-l1-to-l2-messaging.mdx). Some modifications were required in Geth to support them. + +- Added ScheduledTxes field to ExecutionResult. This lists transactions scheduled during the execution. To enable using this field, we also pass the ExecutionResult to callers of ApplyTransaction. +- Added gasEstimation param to DoCall. When enabled, DoCall will also also executing any retryable activated by the original call. This allows estimating gas to enable retryables. + +#### Added accessors + +Added [`UnderlyingTransaction`][underlyingtransaction_link] to Message interface +Added [`GetCurrentTxLogs`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state/statedb_arbitrum.go) to StateDB +We created the AdvancedPrecompile interface, which executes and charges gas with the same function call. This is used by [Arbitrum's precompiles](/build-decentralized-apps/precompiles/01-overview.mdx), and also wraps Geth's standard precompiles. + +#### WASM build support + +The WASM Arbitrum executable does not support file operations. We created [`fileutil.go`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/rawdb/fileutil.go) to wrap fileutil calls, stubbing them out when building WASM. [`fake_leveldb.go`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/ethdb/leveldb/fake_leveldb.go) is a similar WASM-mock for leveldb. These are not required for the WASM block-replayer. + +#### Types + +Arbitrum introduces a new [`signer`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arbitrum_signer.go), and multiple new [`transaction types`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go). + +#### ReorgToOldBlock + +Geth natively only allows reorgs to a fork of the currently-known network. In nitro, reorgs can sometimes be detected before computing the forked block. We added the [`ReorgToOldBlock`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/blockchain_arbitrum.go#L38) function to support reorging to a block that's an ancestor of current head. + +#### Genesis block creation + +Genesis block in nitro is not necessarily block #0. Nitro supports importing blocks that take place before genesis. We split out [`WriteHeadBlock`][writeheadblock_link] from genesis.Commit and use it to commit non-zero genesis blocks. + +[pad_estimates_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/accounts/abi/bind/base.go#L355 +[conservation_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state/statedb.go#L42 +[alert_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/block_processor.go#L424 +[proof_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/system_tests/outbox_test.go#L26 +[merkle_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/merkleAccumulator/merkleAccumulator.go#L13 +[underlyingtransaction_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state_transition.go#L69 +[writeheadblock_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/genesis.go#L415 + +## ArbOS + +ArbOS is the Layer 2 EVM hypervisor that facilitates the execution environment of L2 Arbitrum. ArbOS is a trusted "system glue" component that runs at Layer 2 as part of the State Transition Function, it accounts for and manages network resources, produces blocks from incoming messages, cross-chain messaging, and operates its instrumented instance of Geth for Smart Contract execution. + +In Arbitrum, much of the work that would otherwise have to be done expensively at Layer 1 is instead done by ArbOS, trustlessly performing these functions at the speed and low cost of Layer 2. + +Supporting these functions in Layer 2 trusted software, rather than building them in to the L1-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 Layer 2, instead of having to manage those resources as part of a Layer 1 contract. Having a trusted operating system at Layer 2 also has significant advantages in flexibility, because Layer 2 code is easier to evolve, or to customize for a particular chain, than a Layer-1 enforced architecture would be. + +### Precompiles + +ArbOS provides L2-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. + +A precompile consists of a solidity interface in [`contracts/src/precompiles/`][nitro_precompiles_dir] and a corresponding Golang implementation in [`precompiles/`][precompiles_dir]. Using Geth's ABI generator, [`solgen/gen.go`][gen_file] generates [`solgen/go/precompilesgen/precompilesgen.go`][precompilesgen_link], which collects the ABI data of the precompiles. The [runtime installer][installer_link] uses this generated file to check the type safety of each precompile's implementer. + +[The installer][installer_link] uses runtime reflection to ensure each implementer has all the right methods and signatures. This 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`][owneronly_link] and [`debugOnly`][debugonly_link] to their [installation entry][installation_link]. + +The calling, dispatching, and recording of precompile methods are done via runtime reflection as well. This avoids any human error manually parsing and writing bytes could introduce, and uses Geth's stable APIs for [packing and unpacking][packing_link] values. + +Each time a transaction calls a method of an L2-specific precompile, a [`call context`][call_context_link] is created to track and record the gas burnt. For convenience, it also provides access to the public fields of the underlying [`TxProcessor`][txprocessor_link]. Because sub-transactions could revert without updates to this struct, the [`TxProcessor`][txprocessor_link] only makes public that which is safe, such as the amount of L1 calldata paid by the top level transaction. + +[nitro_precompiles_dir]: https://github.com/OffchainLabs/nitro-contracts/tree/main/src/precompiles +[precompiles_dir]: https://github.com/OffchainLabs/nitro/tree/master/precompiles +[installer_link]: https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L379 +[installation_link]: https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L403 +[gen_file]: https://github.com/OffchainLabs/nitro/blob/master/solgen/gen.go +[owneronly_link]: https://github.com/OffchainLabs/nitro/blob/f11ba39cf91ee1fe1b5f6b67e8386e5efd147667/precompiles/wrapper.go#L58 +[debugonly_link]: https://github.com/OffchainLabs/nitro/blob/f11ba39cf91ee1fe1b5f6b67e8386e5efd147667/precompiles/wrapper.go#L23 +[precompilesgen_link]: https://github.com/OffchainLabs/nitro/blob/f11ba39cf91ee1fe1b5f6b67e8386e5efd147667/solgen/gen.go#L55 +[packing_link]: https://github.com/OffchainLabs/nitro/blob/bc6b52daf7232af2ca2fec3f54a5b546f1196c45/precompiles/precompile.go#L438 +[call_context_link]: https://github.com/OffchainLabs/nitro/blob/f11ba39cf91ee1fe1b5f6b67e8386e5efd147667/precompiles/context.go#L26 + +### Messages + +An [`L1IncomingMessage`][l1incomingmessage_link] represents an incoming sequencer message. A message includes one or more user transactions depending on load, and is made into a [unique L2 block][produceblockadvanced_link]. The L2 block may include additional system transactions added in while processing the message's user transactions, but ultimately the relationship is still bijective: for every [`L1IncomingMessage`][l1incomingmessage_link] there is an L2 block with a unique L2 block hash, and for every L2 block after chain initialization there was an [`L1IncomingMessage`][l1incomingmessage_link] that made it. A sequencer Batch may contain more than one [`L1IncomingMessage`][l1incomingmessage_link]. + +[l1incomingmessage_link]: https://github.com/OffchainLabs/nitro/blob/4ac7e9268e9885a025e0060c9ec30f9612f9e651/arbos/incomingmessage.go#L54 +[produceblockadvanced_link]: https://github.com/OffchainLabs/nitro/blob/4ac7e9268e9885a025e0060c9ec30f9612f9e651/arbos/block_processor.go#L118 + +### Retryables + +A Retryable is a special message type for creating atomic L1 to L2 messages; for details, see [L1 To L2 Messaging](/how-arbitrum-works/10-l1-to-l2-messaging.mdx). + +### ArbOS State + +ArbOS's state is viewed and modified via [`ArbosState`][arbosstate_link] objects, which provide convenient abstractions for working with the underlying data of its [`backingStorage`][backingstorage_link]. The backing storage's [keyed subspace strategy][subspace_link] makes possible [`ArbosState`][arbosstate_link]'s convenient getters and setters, minimizing the need to directly work with the specific keys and values of the underlying storage's [`stateDB`][statedb_link]. + +Because two [`ArbosState`][arbosstate_link] objects with the same [`backingStorage`][backingstorage_link] contain and mutate the same underlying state, different [`ArbosState`][arbosstate_link] objects can provide different views of ArbOS's contents. [`Burner`][burner_link] objects, which track gas usage while working with the [`ArbosState`][arbosstate_link], provide the internal mechanism for doing so. Some are read-only, causing transactions to revert with `vm.ErrWriteProtection` upon a mutating request. Others demand the caller have elevated privileges. While yet others dynamically charge users when doing stateful work. For safety the kind of view is chosen when [`OpenArbosState()`][openarbosstate_link] creates the object and may never change. + +Much of ArbOS's state exists to facilitate its [precompiles](/build-decentralized-apps/precompiles/02-reference.mdx). The parts that aren't are detailed below. + +[arbosstate_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L36 +[backingstorage_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/storage/storage.go#L51 +[statedb_link]: https://github.com/OffchainLabs/go-ethereum/blob/0ba62aab54fd7d6f1570a235f4e3a877db9b2bd0/core/state/statedb.go#L66 +[subspace_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/storage/storage.go#L21 +[openarbosstate_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L57 +[burner_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/burn/burn.go#L11 + +#### [`arbosVersion`][arbosversion_link], [`upgradeVersion`][upgradeversion_link] and [`upgradeTimestamp`][upgradetimestamp_link] + +ArbOS upgrades are scheduled to happen [when finalizing the first block][finalizeblock_link] after the [`upgradeTimestamp`][upgradetimestamp_link]. + +[arbosversion_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L37 +[upgradeversion_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L38 +[upgradetimestamp_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L39 +[finalizeblock_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L350 + +#### [`blockhashes`][blockhashes_link] + +This component maintains the last 256 L1 block hashes in a circular buffer. This allows the [`TxProcessor`][txprocessor_link] to implement the `BLOCKHASH` and `NUMBER` opcodes as well as support precompile methods that involve the outbox. To avoid changing ArbOS state outside of a transaction, blocks made from messages with a new L1 block number update this info during an [`InternalTxUpdateL1BlockNumber`][internaltxupdatel1blocknumber_link] [`ArbitrumInternalTx`][arbitruminternaltx_link] that is included as the first transaction in the block. + +[blockhashes_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/blockhash/blockhash.go#L15 +[internaltxupdatel1blocknumber_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/internal_tx.go#L24 +[arbitruminternaltx_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L116 +[txprocessor_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/tx_processor.go#L33 + +#### [`l1PricingState`][l1pricingstate_link] + +In addition to supporting the [`ArbAggregator precompile`](/build-decentralized-apps/precompiles/02-reference.mdx#arbaggregator), the L1 pricing state provides tools for determining the L1 component of a transaction's gas costs. This part of the state tracks both the total amount of funds collected from transactions in L1 gas fees, as well as the funds spent by batch posters to post data batches on L1. + +Based on this information, ArbOS maintains an L1 data fee, also tracked as part of this state, which determines how much transactions will be charged for L1 fees. ArbOS dynamically adjusts this value so that fees collected are approximately equal to batch posting costs, over time. + +[l1pricingstate_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/l1pricing/l1pricing.go#L16 + +#### [`l2PricingState`][l2pricingstate_link] + +The L2 pricing state tracks L2 resource usage to determine a reasonable L2 gas price. This process considers a variety of 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 L2-specific resources are consumed and filled as time passes. L1-specific resources like L1 `calldata` are not tracked by the pools, as they have little bearing on the actual work done by the network actors that the speed limit is meant to keep stable and synced. + +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][block_production_link] and [the transaction hooks](#hooks). Each of an incoming message's transactions removes from the pool the L2 component of the gas it uses, and afterward the message's timestamp [informs the pricing mechanism][notify_pricer_link] of the time that's passed as ArbOS [finalizes the block][finalizeblock_link]. + +ArbOS's larger gas pool [determines][maintain_limit_link] the per-block gas limit, setting a dynamic [upper limit][per_block_limit_link] on the amount of compute gas an L2 block may have. This limit is always enforced, though for the [first transaction][first_transaction_link] it's done in the [GasChargingHook](/how-arbitrum-works/geth-at-the-core#gascharginghook) to avoid sharp decreases in the L1 gas price from over-inflating the compute component purchased to above the gas limit. This improves UX by allowing the first transaction to succeed rather than requiring a resubmission. Because the first transaction lowers the amount of space left in the block, subsequent transactions do not employ this strategy and may fail from such compute-component inflation. This is acceptable because such transactions are only present in cases where the system is under heavy load and 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. + +The reason we need a per-block gas limit is that Arbitrator WAVM execution is much slower than native transaction execution. This means that there can only be so much gas -- which roughly translates to wall-clock time -- in an L2 block. It also provides an opportunity for ArbOS to limit the size of blocks should demand continue to surge even as the price rises. + +ArbOS's per-block gas limit is distinct from Geth's block limit, which ArbOS [sets sufficiently high][geth_pool_set_link] so as to never run out. This is safe since Geth's block limit exists to constrain the amount of work done per block, which ArbOS already does via its own per-block gas limit. Though it'll never run out, a block's transactions use the [same Geth gas pool][same_geth_pool_link] to maintain the invariant that the pool decreases monotonically after each tx. Block headers [use the Geth block limit][use_geth_pool_link] for internal consistency and to ensure gas estimation works. These are both distinct from the [`gasLeft`][per_block_limit_link] variable, which ephemerally exists outside of global state to both keep L2 blocks from exceeding ArbOS's per-block gas limit and to [deduct space][deduct_space_link] in situations where the state transition failed or [used negligible amounts][negligible_amounts_link] of compute gas. ArbOS does not need to persist [`gasLeft`][per_block_limit_link] because it is its _pool_ that induces a revert and because transactions use the Geth block limit during EVM execution. + +[l2pricingstate_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/l2pricing/l2pricing.go#L14 +[block_production_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L77 +[notify_pricer_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L336 +[maintain_limit_link]: https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/l2pricing/pools.go#L98 +[per_block_limit_link]: https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/block_processor.go#L146 +[first_transaction_link]: https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/block_processor.go#L237 +[geth_pool_set_link]: https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/block_processor.go#L166 +[same_geth_pool_link]: https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/block_processor.go#L199 +[use_geth_pool_link]: https://github.com/OffchainLabs/nitro/blob/2ba6d1aa45abcc46c28f3d4f560691ce5a396af8/arbos/block_processor.go#L67 +[deduct_space_link]: https://github.com/OffchainLabs/nitro/blob/faf55a1da8afcabb1f3c406b291e721bfde71a05/arbos/block_processor.go#L272 +[negligible_amounts_link]: https://github.com/OffchainLabs/nitro/blob/faf55a1da8afcabb1f3c406b291e721bfde71a05/arbos/block_processor.go#L328 diff --git a/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx new file mode 100644 index 000000000..d77c2726f --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx @@ -0,0 +1,36 @@ +--- +title: Separating Execution from Proving +description: 'Learn the fundamentals of Arbitrum Rollup protocol.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about the Arbitrum Rollup protocol. +content_type: get-started +--- + +One of the challenges in designing a practical Rollup system is the tension between wanting the system to perform well in ordinary execution versus being able to reliably prove the results of execution. Nitro resolves this tension by using the same source code for both execution and proving, but compiling it to different targets for the two cases. + +When compiling the Nitro node software for _execution_, the ordinary Go compiler is used, producing native code for the target architecture, which of course will be different for different node deployments. (The node software is distributed in source code form and as a Docker image containing a compiled binary.) + +Separately, for _proving_, the portion of the code that is the State Transition Function is compiled by the Go compiler to WebAssembly (WASM), which is a typed, portable machine code format. The wasm code then goes through a simple transformation into a format we call WAVM, which is detailed below. If there is a dispute about the correct result of computing the STF, it is resolved with reference to the WAVM code. + +## WAVM + +The Wasm format has many features that make it a good vehicle for fraud proofs—it is portable, structured, well-specified, and has reasonably good tools and support. However, it needs a few modifications to do the job completely. Nitro uses a slightly modified version of Wasm, which we call WAVM. A simple transformation stage turns the Wasm code produced by the Go compiler into WAVM code suitable for proving. + +WAVM differs from wasm in three main ways. First, WAVM removes some wasm features that the Go compiler does not generate; the transformation phase verifies that these features are not present. + +Second, WAVM restricts a few features of wasm. For example, WAVM does not contain floating-point instructions, so the transformer replaces floating-point instructions with calls to the Berkeley SoftFloat library. (We use software floating-point to reduce the risk of floating-point incompatibilities between architectures. The core Nitro functions never use floating-point, but the Go runtime does use some floating-point operations.) WAVM does not contain nested control flow, so the transformer flattens control flow constructs, turning control flow instructions into jumps. Some wasm instructions take a variable amount of time to execute, which we avoid in WAVM by transforming them into constructs using fixed-cost instructions. These transformations simplify proving. + +Third, WAVM adds a few opcodes to enable interaction with the Blockchain environment. For example, new instructions allow the WAVM code to read and write the chain's global state, to get the next message from the chain's inbox, or to signal a successful end to execute the State Transition Function. + +## ReadPreImage and the Hash Oracle Trick + +The most interesting new instruction is `ReadPreImage` which takes as input a hash `H` and an offset `I`, and returns the word of data at offset `I` in the preimage of `H` (and the number of bytes written, which is zero if `I` is at or after the end of the preimage). Of course, it is not feasible in general to produce a preimage from an arbitrary hash. For safety, the `ReadPreImage` instruction can only be used in a context where the preimage is publicly known, and where the size of the preimage is known to be less than a fixed upper bound of about 110 kbytes. + +(In this context, "publicly known" information is information that can be derived or recovered efficiently by any honest party, assuming that the full history of the L1 Ethereum chain is available. For convenience, a hash preimage can also be supplied by a third party such as a public server, and the correctness of the supplied value is easily verified.) + +As an example, the state of a Nitro chain is maintained in Ethereum's state tree format, which is organized as a Merkle tree. Nodes of the tree are stored in a database, indexed by the Merkle hash of the node. In Nitro, the state tree is kept outside of the State Transition Function's storage, with the STF only knowing the root hash of the tree. Given the hash of a tree node, the STF can recover the tree node's contents by using `ReadPreImage`, relying on the fact that the full contents of the tree are publicly known and that nodes in the Ethereum state tree will always be smaller than the upper bound on preimage size. In this manner, the STF is able to arbitrarily read and write to the state tree, despite only storing its root hash. + +The only other use of `ReadPreImage` is to fetch the contents of recent L2 Block headers, given the header hash. This is safe because the block headers are publicly known and have bounded size. + +This "hash oracle trick" of storing the Merkle hash of a data structure, and relying on protocol participants to store the full structure and thereby support fetch-by-hash of the contents, goes back to the original Arbitrum design. diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx new file mode 100644 index 000000000..b240fb7b3 --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -0,0 +1,269 @@ +--- +title: Optimistic Rollup +description: Learn the fundamentals of Arbitrum's optimistic rollup. +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Arbitrum's Optimistic Rollup protocol. +content_type: get-started +--- + +Arbitrum is an optimistic rollup. Let’s unpack that term. + +_Rollup_ + +Arbitrum is a Rollup, which means that the inputs to the chain -- the messages that are put into the inbox -- are all recorded on the Ethereum chain as calldata. Because of this, everyone has the information they would need to determine the current correct state of the chain -- they have the full history of the inbox, and the results are uniquely determined by the inbox history, so they can reconstruct the state of the chain based only on public information, if needed. + +This also allows anyone to be a full participant in the Arbitrum protocol, to run an Arbitrum node or participate as a Validator. Nothing about the history or state of the chain is a secret. + +_Optimistic_ + +Arbitrum is optimistic, which means that Arbitrum advances the state of its chain by letting any party (a “validator”) post on Layer 1 a rollup block that that party claims is correct, and then giving everyone else a chance to Challenge that claim. If the Challenge Period (6.4 days) passes and nobody has challenged the claimed rollup block, Arbitrum confirms the rollup block as correct. If someone challenges the claim during the challenge period, then Arbitrum uses an efficient dispute resolution protocol (detailed below) to identify which party is lying. The liar will forfeit a deposit, and the truth-teller will take part of that deposit as a reward for their efforts (some of the deposit is burned, guaranteeing that the liar is punished even if there's some collusion going on). + +Because a party who tries to cheat will lose a deposit, attempts to cheat should be very rare, and the normal case will be a single party posting a correct rollup block, and nobody challenging it. + +## Resolving disputes using interactive fraud proofs + +Among optimistic rollups, the most important design decision is how to resolve disputes. Suppose Alice claims that the chain will produce a certain result, and Bob disagrees. How will the protocol decide which version to accept? + +There are basically two choices: interactive proving, or re-executing transactions. Arbitrum uses interactive proving, which we believe is more efficient and more flexible. Much of the design of Arbitrum follows from this fact. + +### Interactive proving + +The idea of interactive proving is that Alice and Bob will engage in a back-and-forth protocol, refereed by an L1 contract, to resolve their dispute with minimal work required from any L1 contract. + +Arbitrum's approach is based on Dissection of the dispute. If Alice's claim covers N steps of execution, she posts two claims of size N/2 which combine to yield her initial N-step claim, then Bob picks one of Alice's N/2-step claims to challenge. Now the size of the dispute has been cut in half. This process continues, cutting the dispute in half at each stage, until they are disagreeing about a single step of execution. Note that so far the L1 referee hasn't had to think about execution "on the merits". It is only once the dispute is narrowed down to a single step that the L1 referee needs to resolve the dispute by looking at what the instruction actually does and whether Alice's claim about it is correct. + +The key principle behind interactive proving is that if Alice and Bob are in a dispute, Alice and Bob should do as much off-chain work as possible needed to resolve their dispute, rather than putting that work onto an L1 contract. + +### Re-executing transactions + +The alternative to interactive proving would be to have a rollup block contain a claimed machine state hash after every individual Transaction. Then in case of a dispute, the L1 referee would emulate the execution of an entire transaction, to see whether the outcome matches Alice's claim. + +### Why interactive proving is better + +We believe strongly that interactive proving is the superior approach, for the following reasons. + +**More efficient in the optimistic case**: Because interactive proving can resolve disputes that are larger than one transaction, it can allow a rollup block to contain only a single claim about the end state of the chain after all of the execution covered by the block. By contrast, reexecution requires posting a state claim for each transaction within the rollup block. With hundred or thousands of transactions per rollup block, this is a substantial difference in L1 footprint -- and L1 footprint is the main component of cost. + +**More efficient in the pessimistic case**: In case of a dispute, interactive proving requires the L1 referee contract only to check that Alice and Bob's actions "have the right shape", for example, that Alice has divided her N-step claim into two claims half as large. (The referee doesn't need to evaluate the correctness of Alice's claims--Bob does that, off-chain.) Only one instruction needs to be reexecuted. By contrast, reexecution requires the L1 referee to emulate the execution of an entire transaction. + +**Higher per-tx gas limit:** Interactive proving can escape from Ethereum's tight per-transaction gas limit. The gas limit isn't infinite, for obvious reasons, but it can be larger than on Ethereum. As far as Ethereum is concerned, the only downside of a gas-heavy Arbitrum transaction is that it may require an interactive Fraud proof with slightly more steps (and only if indeed it is fraudulent). By contrast, reexecution must impose a _lower_ gas limit than Ethereum, because it must be possible to emulate execution of the transaction (which is more expensive than executing it directly) within a single Ethereum transaction. + +**More implementation flexibility:** Interactive proving allows more flexibility in implementation. All that is necessary is the ability to verify a one-step proof on Ethereum. By contrast, reexecution approaches are tethered to limitations of the EVM. + +### Interactive proving drives the design of Arbitrum + +Much of the design of Arbitrum is driven by the opportunities opened up by interactive proving. If you're reading about some feature of Arbitrum, and you're wondering why it exists, two good questions to ask are: "How does this support interactive proving?" and "How does this take advantage of interactive proving?" The answers to most "why" questions about Arbitrum relate to interactive proving. + +## Arbitrum Rollup Protocol + +Before diving into the Rollup protocol, there are two things we need to cover. + +First, _if you’re an Arbitrum user or developer, you don’t need to understand the Rollup protocol_. You don’t ever need to think about it unless you want to. Your relationship with it can be like a train passenger’s relationship with the train’s engine: you know it exists, and you rely on it to keep working, but you don’t spend your time monitoring it or studying its internals. + +You’re welcome to study, observe, and even participate in the Rollup protocol, but you don’t need to, and most people won’t. So if you’re a typical train passenger who just wants to read or talk to your neighbor, you can skip right to the [next section](#validators) of this document. If not, read on! + +The second thing to understand about the Rollup protocol is that _the protocol doesn’t decide the results of transactions, it only confirms the results_. The results are uniquely determined by the sequence of messages in the chain’s inbox. So once your transaction message is in the chain’s inbox, its result is knowable, and Arbitrum nodes will report that your transaction has been completed. The role of the Rollup protocol is to confirm transaction results that, as far as Arbitrum users are concerned, have already occurred. (This is why Arbitrum users can effectively ignore the Rollup protocol.) + +You might wonder why we need the Rollup protocol. If everyone knows the results of transactions already, why bother confirming them? The Rollup protocol exists for two reasons. First, somebody might lie about a result, and we need a definitive, Trustless way to tell who is lying. Second, Ethereum doesn’t know the results. The whole point of a Layer 2 scaling system is to run transactions without Ethereum needing to do all of the work--and indeed, Arbitrum can go fast enough that Ethereum couldn’t hope to monitor every Arbitrum transaction. However, once the result is confirmed, Ethereum knows about it and can rely on it, enabling operations on Ethereum, such as processing withdrawals of funds from Nitro back to L1. + +With those preliminaries behind us, let’s jump into the details of the Rollup protocol. + +The parties who participate in the protocol are called _validators_. Some validators will choose to be bonders--they will place an ETH deposit which they’ll be able to recover if they’re not caught cheating. In the common case, it's expected that only one validator will be bonded, since as long as it's bonded on the current outcome, and there are no conflicting claims, there's no need for other parties to bond/take any action. The protocol allows for these roles to be permissionless in principle; currently on Arbitrum One, validators/bonders are allowlisted (see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization)). "Watchtower validators," who monitor the chain but don't take any on-chain actions, can be run permissionlessly (see ["validators"](#validators) below). + +The key security property of the Rollup protocol is that any one honest validator can force the correct execution of the chain to be confirmed. This means that the execution of an Arbitrum chain is as trustless as Ethereum. You, and you alone (or someone you hire), can force your transactions to be processed correctly. And that is true, no matter how many malicious people are trying to stop you. + +### The Rollup Chain + +The Rollup protocol tracks a chain of Rollup blocks---we'll call these "RBlocks" for clarity. They're not the same as Layer 1 Ethereum blocks, and also not the same as Layer 2 Nitro blocks. You can think of the RBlocks as forming a separate chain, which the Arbitrum Rollup Protocol manages and oversees. + +Validators can propose RBlocks. New RBlocks will be _unresolved_ at first. Eventually, every RBlock will be _resolved_, by being either _confirmed_ or _rejected_. The confirmed RBlocks make up the confirmed history of the chain. + +:::note + +Validators and proposers serve different roles. Validators validate transactions to the State Transition Function (STF) and Chain state, whereas proposers can also assert and challenge the chain state. + +::: + +Each RBlock contains: + +- the RBlock number +- the predecessor RBlock number: RBlock number of the last RBlock before this one that is (claimed to be) correct +- the number of L2 blocks that have been created in the chain's history +- the number of inbox messages that have been consumed in the chain’s history +- a hash of the outputs produced over the chain’s history. + +Except for the RBlock number, the contents of the RBlock are all just claims by the RBlock's proposer. Arbitrum doesn’t know at first whether any of these fields are correct. If all of these fields are correct, the protocol should eventually confirm the RBlock. If one or more of these fields are incorrect, the protocol should eventually reject the RBlock. + +An RBlock is implicitly claiming that its predecessor RBlock is correct. This implies, transitively, that an RBlock implicitly claims the correctness of a complete history of the chain: a sequence of ancestor RBlocks that reaches all the way back to the birth of the chain. + +An RBlock is also implicitly claiming that its older siblings (older RBlocks with the same predecessor), if there are any, are incorrect. If two RBlocks 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 RBlock is assigned a deadline, which says how long other validators have to respond to it. If you’re a validator, and you agree that an RBlock is correct, you don’t need to do anything. If you disagree with an RBlock, you can post another RBlock with a different result, and you’ll probably end up in a challenge against the first RBlock's bonder. (More on challenges below.) + +In the normal case, the rollup chain will look like this: + +```mermaid +graph RL + f["First unresolved block"] + l["Latest confirmed block"] + + 98-->97-->96-->95 + f-.-95 + + 95-->94 + l-.-94 + + 94-->93-->92-->91-->90-->x[...] + + subgraph Legend + direction RL + Confirmed + Unconfirmed + end + + classDef confirmed fill:#47b860,stroke:#37914c,stroke-width:2px,color:#fff + class 94,93,92,91,90,x,Confirmed confirmed + + + classDef unconfirmed fill:#2aa1f0,stroke:#1c86ca,stroke-width:2px,color:#fff + class 98,97,96,95,Unconfirmed unconfirmed + + classDef note fill:#F1F5F6,stroke:#dbdede,stroke-width:1px,color:#000 + class l,f note +``` + +On the left, representing an earlier part of the chain’s history, we have confirmed RBlocks. These have been fully accepted and recorded by the Layer 1 contracts that manage the chain. The newest of the confirmed RBlocks, RBlock 94, is called the “latest confirmed RBlock.” On the right, we see a set of newer proposed RBlocks. The protocol can’t yet confirm or reject them, because their deadlines haven’t run out yet. The oldest RBlock whose fate has yet to be determined, RBlock 95, is called the “first unresolved RBlock.” + +Notice that a proposed RBlock can build on an earlier proposed RBlock. This allows validators to continue proposing RBlocks without needing to wait for the protocol to confirm the previous one. Normally, all of the proposed RBlocks 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. + +```mermaid +graph RL + subgraph Legend + direction RL + Confirmed + Rejected + Unconfirmed + end + + f["First unresolved block"] + l["Latest confirmed block"] + + + l-.-103 + f-.-106 + + 108-->107-->106-->103 + 111-->104 + 101-->100 + 105-->104-->103 + 110-->109-->103-->102-->100-->x[...] + + classDef confirmed fill:#47b860,stroke:#37914c,stroke-width:2px,color:#fff + class 100,102,103,x,Confirmed confirmed + + classDef rejected fill:#fdaa07,stroke:#fd8607,stroke-width:2px,color:#fff + class 101,104,105,Rejected rejected + + classDef unconfirmed fill:#2aa1f0,stroke:#1c86ca,stroke-width:2px,color:#fff + class 106,107,108,109,110,111,Unconfirmed unconfirmed + + classDef note fill:#F1F5F6,stroke:#dbdede,stroke-width:1px,color:#000 + class l,f note + +``` + +There’s a lot going on here, so let’s unpack it. + +- RBlock 100 has been confirmed. +- RBlock 101 claimed to be a correct successor to RBlock 100, but 101 was rejected (hence it is orange). +- RBlock 102 was eventually confirmed as the correct successor to 100. +- RBlock 103 was confirmed and is now the latest confirmed RBlock. +- RBlock 104 was proposed as a successor to RBlock 103, and 105 was proposed as a successor to 104. 104 was rejected as incorrect, and as a consequence 105 was rejected because its predecessor was rejected. +- RBlock 106 is unresolved. It claims to be a correct successor to RBlock 103 but the protocol hasn’t yet decided whether to confirm or reject it. It is the first unresolved RBlock. +- RBlocks 107 and 108 claim to chain from 106. They are also unresolved. If 106 is rejected, they will be automatically rejected too. +- RBlock 109 disagrees with RBlock 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. +- RBlock 110 claims to follow 109. It is unresolved. If 109 is rejected, 110 will be automatically rejected too. +- RBlock 111 claims to follow 104. 111 will inevitably be rejected because its predecessor has already been rejected. But it hasn’t been rejected yet, because the protocol resolves RBlocks in RBlock number order, so the protocol will have to resolve 106 through 110, in order, before it can resolve 111. After 110 has been resolved, 111 can be rejected immediately. + +Again: this sort of thing is very unlikely in practice. In this diagram, at least four parties must have bonded on wrong RBlocks, and when the dust settles at least four parties will have lost their bonds. The protocol handles these cases correctly, of course, but they’re rare corner cases. This diagram is designed to illustrate the variety of situations that are possible in principle, and how the protocol would deal with them. + +### Staking + +At any given time, some validators will be bonders, and some will not. Bonders deposit funds that are held by the Arbitrum Layer 1 contracts and will be confiscated if the bonder loses a challenge. Nitro chains accept bonds in ETH. + +A single bond can cover a chain of RBlocks. Every bonder is bonded on the latest confirmed RBlock; and if you’re bonded on an RBlock, you can also bond on one successor of that RBlock. So you might be bonded on a sequence of RBlocks that represent a single coherent claim about the correct history of the chain. A single bond suffices to commit you to that sequence of RBlocks. + +In order to create a new RBlock, you must be a bonder, and you must already be bonded on the predecessor of the new RBlock you’re creating. The bond requirement for RBlock creation ensures that anyone who creates a new RBlock has something to lose if that RBlock is eventually rejected. + +The protocol keeps track of the current required bond amount. Normally this will equal the base bond amount, which is a parameter of the Nitro chain. But if the chain has been slow to make progress lately, the required bond will increase, as described in more detail below. + +The rules for staking are as follows: + +- If you’re not bonded, you can bond on the latest confirmed RBlock. When doing this, you deposit the current minimum bond amount. +- If you’re bonded on an RBlock, you can also add your bond to any one successor of that RBlock. (The protocol tracks the maximum RBlock number you’re bonded on, and lets you add your bond to any successor of that RBlock, updating your maximum to that successor.) This doesn’t require you to place a new bond. + - A special case of adding your bond to a successor RBlock is when you create a new RBlock as a successor to an RBlock you’re already bonded on. +- If you’re bonded only on the latest confirmed RBlock (and possibly earlier RBlocks), you or anyone else can ask to have your bond refunded. Your bonded funds will be returned to you, and you will no longer be a bonder. +- If you lose a challenge, your bond is removed from all RBlocks and you forfeit your bonded funds. + +Notice that once you are bonded on an RBlock, there is no way to unbond. You are committed to that RBlock. Eventually one of two things will happen: that RBlock will be confirmed, or you will lose your bond. The only way to get your bond back is to wait until all of the RBlocks you are bonded on are confirmed. + +#### Setting the current minimum bond amount + +One detail we deferred earlier is how the current minimum bond amount is set. Normally, this is just equal to the base bond amount, which is a parameter of the Nitro chain. However, if the chain has been slow to make progress in confirming RBlocks, the bond requirement will escalate temporarily. Specifically, the base bond amount is multiplied by a factor that is exponential in the time since the deadline of the first unresolved RBlock passed. This ensures that if malicious parties are placing false bonds to try to delay progress (despite the fact that they’re losing those bonds), the bond requirement goes up so that the cost of such a delay attack increases exponentially. As RBlock resolution starts advancing again, the bond requirement will go back down. + +### Rules for Confirming or Rejecting RBlocks + +The rules for resolving RBlocks are fairly simple. + +The first unresolved RBlock can be confirmed if: + +- the RBlock's predecessor is the latest confirmed RBlock, and +- the RBlock's deadline has passed, and +- there is at least one bonder, and +- All bonders are bonded to the RBlock. + +The first unresolved RBlock can be rejected if: + +- the RBlock's predecessor has been rejected, or +- all of the following are true: + - the RBlock's deadline has passed, and + - there is at least one bonder, and + - no bonder is bonded on the RBlock. + +A consequence of these rules is that once the first unresolved RBlock's deadline has passed (and assuming there is at least one bonder bonded on something other than the latest confirmed RBlock), the only way the RBlock can be unresolvable is if at least one bonder is bonded on it and at least one bonder is bonded on a different RBlock with the same predecessor. If this happens, the two bonders are disagreeing about which RBlock is correct. It’s time for a challenge, to resolve the disagreement. + +## Delays + +Even if the Assertion Tree has multiple conflicting RBlocks and, say, multiple disputes are in progress, validators can continue making assertions; honest validators will simply build on the one valid RBlock (intuitively: an assertion is also an implicit claim of the validity of all of its parent-assertions.) Likewise, users can continue transacting on L2, since transactions continue to be posted in the chain's inbox. + +The only delay that users experience during a dispute is of their [L2 to L1 messages](/how-arbitrum-works/11-l2-to-l1-messaging.mdx) (i.e., "their withdrawals"). Note that a "delay attacker" who seeks to grief the system by deliberately causing such delays will find this attack quite costly, since each bit of delay-time gained requires the attacker lose another stake. + +## Validators + +Arbitrum full nodes normally "live at Layer 2" which means that they don’t worry about the rollup protocol but simply treat their Arbitrum chain as a mechanism that feeds inbox messages to the State Transition Function to evolve the Layer 2 chain and produce outputs. + +Some Arbitrum nodes will choose to act as _validators_. This means that they watch the progress of the rollup protocol and participate in that protocol to advance the state of the chain securely. + +Not all nodes will choose to do this. Because the Rollup protocol doesn’t decide what the chain will do but merely confirms the correct behavior that is fully determined by the inbox messages, a node can ignore the rollup protocol and simply compute for itself the correct behavior. + +Offchain Labs provides open source validator software, including +a pre-built Docker image. + +Every validator can choose their own approach, but we expect validators to follow three common strategies: + +- The _active validator_ strategy tries to advance the state of the chain by proposing new RBlocks. An Active Validator is always bonded, because creating an RBlock requires being bonded. A chain really only needs one honest active validator; any more is an inefficient use of resources. For the Arbitrum One chain, Offchain Labs runs an active validator. +- The _defensive validator_ strategy watches the rollup protocol operate. If only correct RBlocks are proposed, this strategy doesn't bond. But if an incorrect RBlock is proposed, this strategy intervenes by posting a correct RBlock or staking on a correct RBlock that another party has posted. This strategy avoids staking when things are going well, but if someone is dishonest it bonds in order to defend the correct outcome. +- The _watchtower validator_ strategy never bonds. It simply watches the Rollup protocol, and if an incorrect RBlock is proposed, it raises the alarm (by whatever means it chooses) so that others can intervene. This strategy assumes that other parties who are willing to bond will be willing to intervene in order to take some of the dishonest proposer’s bond and that that can happen before the dishonest RBlock’s deadline expires. (In practice, this will allow several days for a response.) + +Under normal conditions, validators using the defensive and watchtower strategies won’t do anything except observe. A malicious actor who is considering whether to try cheating won’t be able to tell how many defensive and watchtower validators are operating incognito. Perhaps some defensive validators will announce themselves, but others probably won’t, so a would-be attacker will always have to worry that defenders are waiting to emerge. + +The underlying protocol supports permissionless validation, i.e.,--anyone can do it. Currently on Arbitrum One, validators that require bond (i.e., active and defensive validators) are whitelisted; see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization). + +Who will be validators? Anyone will be able to do it, but most people will choose not to. In practice we expect people to validate a chain for several reasons. + +- Validators could be paid for their work, by the party that created the chain or someone else. A chain could be configured such that a portion of the funds from user transaction fees are paid directly to validators. +- Parties who have significant assets at bond on a chain, such as dApp developers, exchanges, power-users, and liquidity providers, may choose to validate in order to protect their investment. +- Anyone who chooses to validate can do so. Some users will probably choose to validate in order to protect their own interests or just to be good citizens. But ordinary users don’t need to validate, and we expect that the vast majority of users won’t. diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx new file mode 100644 index 000000000..7c1b76980 --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -0,0 +1,435 @@ +--- +title: 'Challenges: Interactive Fraud Proofs' +description: Learn the fundamentals of Arbitrum's Interactive Fraud Proofs and challenges. +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Interactive Fraud Proofs and challenges. +content_type: get-started +--- + +Suppose the rollup chain looks like this: + +![img](https://lh4.googleusercontent.com/kAZY9H73dqcHvboFDby9nrtbYZrbsHCYtE5X9NIZQsvcz58vV0WUWUq1xsYKzYWQSc1nPZ8W86LLX0lD3y-ctEaG2ISa2Wpz2pYxTzW09P1UvqSDuoqkHlGDYLLMTzLqX4rlP8Ca) + +RBlocks 93 and 95 are siblings (they both have 92 as predecessor). Alice is bonded on 93 and Bob is bonded on 95. + +At this point we know that Alice and Bob disagree about the correctness of RBlock 93, with Alice committed to 93 being correct and Bob committed to 93 being incorrect. (Bob is bonded on 95, and 95 implicitly claims that 92 is the last correct RBlock before it, which implies that 93 must be incorrect.) + +Whenever two bonders are bonded on sibling RBlocks, and neither of those bonders is already in a Challenge, anyone can start a challenge between the two. The rollup protocol will record the challenge and referee it, eventually declaring a winner and confiscating the loser’s bond. The loser will be removed as a bonder. + +The challenge is a game in which Alice and Bob alternate moves, with an Ethereum contract as the referee. Alice, the defender, moves first. + +The game will operate in two phases: Dissection, followed by one-step proof. Dissection will narrow down the size of the dispute until it is a dispute about just one instruction of execution. Then the one-step proof will determine who is right about that one instruction. + +We’ll describe the dissection part of the protocol twice. First, we’ll give a simplified version which is easier to understand but less efficient. Then we’ll describe how the real version differs from the simplified one. + +## Dissection Protocol: Simplified Version + +Alice is defending the claim that starting with the state in the predecessor RBlock, the state of the Virtual Machine can advance to the state specified in RBlock A. Essentially she is claiming that the Virtual Machine can execute N instructions, and that that execution will consume M inbox messages and transform the hash of outputs from H’ to H. + +Alice’s first move requires her to dissect her claims about intermediate states between the beginning (0 instructions executed) and the end (N instructions executed). So we require Alice to divide her claim in half, and post the state at the half-way point, after N/2 instructions have been executed. + +Now Alice has effectively bisected her N-step Assertion into two (N/2)-step assertions. Bob has to point to one of those two half-size assertions and claim it is wrong. + +At this point we’re effectively back in the original situation: Alice having made an assertion that Bob disagrees with. But we have cut the size of the assertion in half, from N to N/2. We can apply the same method again, with Alice bisecting and Bob choosing one of the halves, to reduce the size to N/4. And we can continue bisecting, so that after a logarithmic number of rounds Alice and Bob will be disagreeing about a single step of execution. That’s where the dissection phase of the protocol ends, and Alice must make a one-step proof which will be checked by the EthBridge. + +## Why Dissection Correctly Identifies a Cheater + +Before talking about the complexities of the real Challenge protocol, let’s stop to understand why the simplified version of the protocol is correct. Here correctness means two things: (1) if Alice’s initial claim is correct, Alice can always win the challenge, and (2) if Alice’s initial claim is incorrect, Bob can always win the challenge. + +To prove (1), observe that if Alice’s initial claim is correct, she can offer a truthful midpoint claim, and both of the implied half-size claims will be correct. So whichever half Bob objects to, Alice will again be in the position of defending a correct claim. At each stage of the protocol, Alice will be defending a correct claim. At the end, Alice will have a correct one-step claim to prove, so that claim will be provable and Alice can win the challenge. + +To prove (2), observe that if Alice’s initial claim is incorrect, this can only be because her claimed endpoint after N steps is incorrect. Now when Alice offers her midpoint state claim, that midpoint claim is either correct or incorrect. If it’s incorrect, then Bob can challenge Alice’s first-half claim, which will be incorrect. If Alice’s midpoint state claim is correct, then her second-half claim must be incorrect, so Bob can challenge that. So whatever Alice does, Bob will be able to challenge an incorrect half-size claim. At each stage of the protocol, Bob can identify an incorrect claim to challenge. At the end, Alice will have an incorrect one-step claim to prove, which she will be unable to do, so Bob can win the challenge. + +(If you’re a stickler for mathematical precision, it should be clear how these arguments can be turned into proofs by induction on N.) + +## The Real Dissection Protocol + +The real dissection protocol is conceptually similar to the simplified one described above, but with several changes that improve efficiency or deal with necessary corner cases. Here is a list of the differences. + +**Dissection over L2 blocks, then over instructions:** Alice's assertion is over an RBlock, which asserts the result of creating some number of Layer 2 Nitro blocks. Dissection first occurs over these Layer 2 blocks, to narrow the dispute down to a dispute about a single Layer 2 Nitro block. At this point, the dispute transforms into a dispute about a single execution of the State Transition Function or in other words about the execution of a sequence of WAVM instructions. The protocol then executes the recursive dissection sub-protocol again, this time over WAVM instructions, to narrow the dispute to a single instruction. The dispute concludes with a one-step proof of a single instruction (or a party failing to act and losing by timeout). + +**K-way dissection:** Rather than dividing a claim into two segments of size N/2, we divide it into K segments of size N/K. This requires posting K-1 intermediate claims, at points evenly spaced through the claimed execution. This reduces the number of rounds by a factor of log(K)/log(2). + +**Answer a dissection with a dissection:** Rather than having each round of the protocol require two moves, where Alice dissects and Bob chooses a segment to challenge, we instead require Bob, in challenging a segment, to post his own claimed endpoint state for that segment (which must differ from Alice’s) as well as his own dissection of his version of the segment. Alice will then respond by identifying a subsegment, posting an alternative endpoint for that segment, and dissecting it. This reduces the number of moves in the game by an additional factor of 2, because the size is cut by a factor of K for every move, rather than for every two moves. + +**Deal With the Empty-Inbox Case**: The real AVM can’t always execute N units of gas without getting stuck. The machine might halt, or it might have to wait because its inbox is exhausted so it can’t go on until more messages arrive. So Bob must be allowed to respond to Alice’s claim of N units of execution by claiming that N steps are not possible. The real protocol thus allows any response (but not the initial claim) to claim a special end state that means essentially that the specified amount of execution is not possible under the current conditions. + +**Time Limits:** Each player is given a time allowance. The total time a player uses for all of their moves must be less than the time allowance, or they lose the game. Think of the time allowance as being about a week. + +It should be clear that these changes don’t affect the basic correctness of the challenge protocol. They do, however, improve its efficiency and enable it to handle all of the cases that can come up in practice. + +## Efficiency + +The challenge protocol is designed so that the dispute can be resolved with a minimum of work required by the protocol (via its Layer 1 Ethereum contracts) in its role as referee. When it is Alice’s move, the protocol only needs to keep track of the time Alice uses, and ensure that her move does include K-1 intermediate points as required. The protocol doesn’t need to pay attention to whether those claims are correct in any way; it only needs to know whether Alice’s move “has the right shape”. + +The only point where the protocol needs to evaluate a move “on the merits” is at the one-step proof, where it needs to look at Alice’s proof and determine whether the proof that was provided does indeed establish that the virtual machine moves from the before state to the claimed after state after one step of computation. + +import ChallengeManagerDiagram from '../diagrams/_challenge-manager.mdx'; + +## ChallengeManager + +This section is a technical deep dive into the `ChallengeManager` and will walk through the arbitration of a challenge game in great detail. The `ChallengeManager` plays the role of the arbiter of challenge games. Here's a diagram of the challenge state machine: + + + +### Block challenge + +The challenge begins by bisecting over global states (including block hashes). +Before actual machine execution is disputed, the dispute is narrowed down to an individual block. +Once the challenge has been bisected down to an individual block, +`challengeExecution` can be called by the current responder. +This operates similarly to a bisection in that the responder must provide a competing global state and machine state, +but it uses that information to transition to the execution challenge phase. + +### Execution challenge + +Once narrowed down to an individual block, the actual machine execution can be bisected. +Once the execution has been bisected down to an individual step, +`oneStepProveExecution` can be called by the current responder. +The current responder must provide proof data to execute a step of the machine. +If executing that step ends in a different state than was previously asserted, +the current responder wins the challenge. + +### General bisection protocol + +_**Note:** the term bisection in this document is used for clarity but refers to a dissection of any degree._ + +The `ChallengeLib` helper library contains a `hashChallengeState` method which hashes a list of segment hashes, +a start position, and a total segments length, which generates the `ChallengeLib.Challenge`'s `challengeStateHash`. +This is enough information to infer the position of each segment hash. +The challenge "degree" refers to the number of segment hashes minus one. +The distance (in steps) between one segment and the next is `floor(segmentsLength / degree)`, except for the +last pair of segments, where `segmentsLength % degree` is added to the normal distance, so that +the total distance is `segmentsLength`. + +A challenge begins with only two segments (a degree of one), which is the asserter's initial assertion. +Then, the bisection game begins on the challenger's turn. +In each round of the game, the current responder must choose an adjacent pair of segments to challenge. +By doing so, they are disputing their opponent's claim that starting with the first segment and executing +for the specified distance (number of steps) will result in the second segment. At this point the two parties +agree on the correctness of the first segment but disagree about the correctness of the second segment. +The responder must provide a bisection with a start segment equal to the first segment, but an end segment +different from the second segment. +In doing so, they break the challenge down into smaller distances, and it becomes their opponent's turn. +Each bisection must have degree `min(40, numStepsInChallengedSegment)`, ensuring the challenge makes progress. + +In addition, a segment with a length of only one step cannot be bisected. +What happens there is specific to the phase of the challenge, as either a `challengeExecution` or `oneStepProveExecution`. + +Note that unlike in a traditional bisection protocol, where one party proposes segments and the other decides which to challenge, +this protocol is symmetric in that both players take turns deciding where to challenge and proposing bisections +when challenging. + +### Winning the challenge + +Note that for the time being, winning the challenge isn't instant. +Instead, it simply makes the current responder the winner's opponent, +and sets the state hash to 0. In that state the party does not have any +valid moves, so it will eventually lose by timeout. +This is done as a precaution, so that if a challenge is resolved incorrectly, +there is time to diagnose and fix the error with a contract upgrade. + +## One Step Proof Assumptions + +The One Step Proof (OSP) implementation makes certain assumptions about the cases that can arise +in a correct execution. This documents those assumptions about what's being executed. + +If a case is "unreachable", that is, the case is assumed to never arise in correct execution, +then the OSP can implement any instruction semantics in that case. + +- In a challenge between malicious parties, any case can arise. The challenge protocol must do + something safe in every case. But the instruction semantics can be weird in such cases because + if both parties to a challenge are malicious, the protocol doesn't care who wins the challenge. +- In a challenge with one honest party, the honest party will never need to one-step prove an + unreachable case. The honest party will only assert correct executions, so it will only have to + prove reachable cases. +- In a challenge with one honest party, the dishonest party could assert an execution that transitions + into an unreachable case, but such an execution must include an invalid execution of a reachable case + earlier in the assertion. Because a challenge involving an honest party will eventually require an OSP + over the first instruction where the parties disagree, the eventual OSP will be over the earlier point + of divergence, and not over the later execution from an unreachable case. + +In general, some unreachable cases will be detectable by the OSP checker and some will not. For safety, the +detectable unreachable cases should be defined by transition the machine into an error state, allowing +governance to eventually push an upgrade to recover from the error. An undetectable unreachable case, if +such a case were reached in correct execution, could lead to a security failure. + +The following assumptions, together, must prevent an unreachable case from arising in correct execution. + +### The WAVM code is generated by Arbitrator from valid WASM + +WAVM is the name of the custom instruction set similar to WASM used for proving. +Arbitrator transpiles WASM code into WAVM. +It also invokes wasm-validate from [wabt](https://github.com/WebAssembly/wabt) +(the WebAssembly Binary Toolkit) to ensure the input WASM is valid. +WAVM produced otherwise may not be executable, as it may try to close a non-existent block, +mismatch types, or do any other number of invalid things which are prevented by WASM validation. + +WAVM code generated from by Arbitrator from valid WASM is assumed to never encounter an unreachable case. + +### Inbox messages must not be too large + +The current method of inbox hashing requires the full inbox message be available for proving. +That message must not be too large as to prevent it from being supplied for proving, +which is enforced by the inboxes. + +The current length limit is 117,964 bytes, which is 90% of the +[max transaction size Geth will accept](https://github.com/ethereum/go-ethereum/blob/356bbe343a30789e77bb38f25983c8f2f2bfbb47/core/tx_pool.go#L53), +leaving 13,108 bytes for other proving data. + +### Requested preimages must be known and not too large + +WAVM has an opcode which resolves the preimage of a Keccak-256 hash. +This can only be executed if the preimage is already known to all nodes, +and can only be proven if the preimage isn't too long. Violations of this assumption are +undetectable by the OSP checker. + +The current length limit is 117,964 bytes for the reasons mentioned above. +Here's a list of which preimages may be requested by Nitro, and why they're known to all parties, +and not too large: + +#### Block headers + +Nitro may request up to the last 256 L2 Block headers. +The last block header is required to determine the current state, +and blocks before it are required to implement the `BLOCKHASH` evm instruction. + +This is safe as previous block headers are a fixed size, and are known to all nodes. + +#### State trie access + +To resolve state, Nitro traverses the state trie by resolving preimages. + +This is safe as validators retain archive state of unconfirmed blocks, +each trie branch is of a fixed size, +and the only variable sized entry in the trie is contract code, +which is limited by EIP-170 to about 24KB. + +## WASM to WAVM + +Not all WASM instructions are 1:1 with WAVM opcodes. +This document lists those which are not, and explains how they're expressed in WAVM. +Many of the WAVM representations use opcodes not in WASM, +which are documented in [`wavm-custom-opcodes`](#wavm-custom-opcodes-not-in-wasm). + +### `block` and `loop` + +In WASM, a block contains instructions. +Branch instructions exit a fixed number of blocks, jumping to their destination. +A normal `block`'s destination is the end of the block, whereas a `loop`'s destination is the start of the loop. + +In WAVM, instructions are flat. +At transpilation time, any branch instructions are replaced with jumps to the corresponding block's destination. +This means that WAVM interpreters don't need to track blocks, and thus block instructions are unnecessary. + +### `if` and `else` + +These are translated to a block with an `ArbitraryJumpIf` as follows: + +``` +begin block with endpoint end + conditional jump to else + [instructions inside if statement] + branch + else: [instructions inside else statement] +end +``` + +### `br` and `br_if` + +`br` and `br_if` are translated into `ArbitraryJump` and `ArbitraryJumpIf` respectively. +The jump locations can be known at transpilation time, making blocks obsolete. + +### `br_table` + +`br_table` is translated to a check for each possible branch in the table, +and then if none of the checks hit, a branch of the default level. + +Each of the non-default branches has a conditional jump to a section afterwards, +containing a `drop` for the selector, and then a jump to the target branch. + +### `local.tee` + +`local.tee` is translated to a WAVM `Dup` and then a `LocalSet`. + +### `return` + +To translate a return, the number of return values must be known from the function signature. +A WAVM `MoveFromStackToInternal` is added for each return value. +Then, a loop checks `IsStackBoundary` (which implicitly pops a value) until it's true and the stack boundary has been popped. +Next, a `MoveFromInternalToStack` is added for each return value to put the return values back on the stack. +Finally, a WAVM `Return` is added, returning control flow to the caller. + +### Floating point instructions + +A floating point library module must be present to translate floating point instructions. +They are translated by bitcasting `f32` and `f64` arguments to `i32`s and `i64`s, +then a cross module call to the floating point library, +and finally bitcasts of any return values from `i32`s and `i64`s to `f32`s and `f64`s. + +## WAVM Custom opcodes not in WASM + +In addition to the MVP WASM specification, +WAVM implements the multi value and sign extension ops WASM proposals. + +WAVM also implements the following unique opcodes, +which are not part of WASM nor any WASM proposal. + +### Invariants + +Many of these opcodes have implicit invariants about what's on the stack, +e.g. "Pops an i32 from the stack" assumes that the top of the stack has an i32. +If these conditions are not satisfied, execution is generally not possible. +These invariants are maintained by WASM validation and Arbitrator codegen. (See [One Step Proof Assumptions](#one-step-proof-assumptions).) + +### Codegen internal + +These are generated when breaking down a WASM instruction that does many things into many WAVM instructions which each do one thing. +For instance, a WASM `local.tee` is implemented in WAVM with `dup` and then `local.set`, the former of which doesn't exist in WASM. + +Other times, these opcodes help out an existing WASM opcode by splitting out functionality. +For instance, the WAVM `return` opcode by itself does not clean up the stack, +but its WASM->WAVM codegen includes a loop that utilizes `IsStackBoundary` to perform the stack cleanup +specified for WASM's `return`. + +| Opcode | Name | Description | +| ------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x8000 | EndBlock | Pops an item from the block stack. | +| 0x8001 | EndBlockIf | Peeks the top value on the stack, assumed an i32. If non-zero, pops an item from the block stack. | +| 0x8002 | InitFrame | Pops a caller module index i32, then a caller module internals offset i32, and finally a return InternalRef from the stack. Creates a stack frame with the popped info and the locals merkle root in proving argument data. | +| 0x8003 | ArbitraryJumpIf | Pops an i32 from the stack. If non-zero, jumps to the program counter in the argument data. | +| 0x8004 | PushStackBoundary | Pushes a stack boundary to the stack. | +| 0x8005 | MoveFromStackToInternal | Pops an item from the stack and pushes it to the internal stack. | +| 0x8006 | MoveFromInternalToStack | Pops an item from the internal stack and pushes it to the stack. | +| 0x8007 | IsStackBoundary | Pops an item from the stack. If a stack boundary, pushes an i32 with value 1. Otherwise, pushes an i32 with value 0. | +| 0x8008 | Dup | Peeks an item from the stack and pushes another copy of that item to the stack. | + +The above opcodes eliminate the need for the following WASM opcodes (which are transpiled into other WAVM opcodes): + +- loop +- if/else +- br_table +- local.tee + +### Linking + +This is only generated to link modules together. +Each import is replaced with a local function consisting primarily of this opcode, +which handles the actual work needed to change modules. + +| Opcode | Name | Description | +| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x8009 | CrossModuleCall | Pushes the current program counter, module number, and module's internals offset to the stack. Then splits its argument data into the lower 32 bits being a function index, and the upper 32 bits being a module index, and jumps to the beginning of that function. | + +### Host calls + +These are only used in the implementation of "host calls". +Each of these has an equivalent host call method, which can be invoked from libraries. +The exception is `CallerModuleInternalCall`, +which is used for the implementation of all of the `wavm_caller_*` host calls. +Those calls are documented in `wavm-modules.mdx`. + +For these instruction descriptions, all pointers and offsets are represented as WASM i32s. + +| Opcode | Name | Description | +| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0x800A | CallerModuleInternalCall | Pushes the current program counter, module number, and module's internals offset (all i32s) to the stack. Then, it retrieves the caller module internals offset from the current stack frame. If 0, errors, otherwise, jumps to the caller module at function (internals offset + opcode argument data) and instruction 0. | +| 0x8010 | GetGlobalStateBytes32 | Pops a pointer and then an index from the stack. If the index is greater than or equal to the number of global state bytes32s, errors. If the pointer mod 32 is not zero, errors. If the pointer + 32 is outside the programs memory, errors. Otherwise, writes the global state bytes32 value of the specified index to the specified pointer in memory. | +| 0x8011 | SetGlobalStateBytes32 | Pops a pointer and then an index from the stack. If the index is greater than or equal to the number of global state bytes32s, errors. If the pointer mod 32 is not zero, errors. If the pointer + 32 is outside the programs memory, errors. Otherwise, reads a bytes32 from the specified pointer in memory and sets the global state bytes32 value of the specified index to it. | +| 0x8012 | GetGlobalStateU64 | Pops a pointer and then an index from the stack. If the index is greater than or equal to the number of global state u64s, errors. If the pointer mod 32 is not zero, errors. If the pointer + 8 is outside the programs memory, errors. Otherwise, writes the global state u32 value of the specified index to the specified pointer in memory. | +| 0x8013 | SetGlobalStateU64 | Pops a pointer and then an index from the stack. If the index is greater than or equal to the number of global state u64s, errors. If the pointer mod 32 is not zero, errors. If the pointer + 8 is outside the programs memory, errors. Otherwise, reads a u64 from the specified pointer in memory and sets the global state u64 value of the specified index to it. | +| 0x8020 | ReadPreImage | Pops an offset and then a pointer from the stack. If the pointer mod 32 is not zero, errors. If the pointer + 32 is outside the programs memory, errors. Reads a 32 byte Keccak-256 hash from the specified pointer in memory. Writes up to 32 bytes of the preimage to that hash, beginning with the `offset` byte of the preimage. If `offset` is greater than or equal to the number of bytes in the preimage, writes nothing. Pushes the number of bytes written to the stack as an i32. | +| 0x8021 | ReadInboxMessage | Pops an offset, then a pointer, and then an i64 message number from the stack. If the pointer mod 32 is not zero, errors. If the pointer + 32 is outside the programs memory, errors. Attempts to read an inbox message from the inbox identifier contained in the argument data (0 for the Sequencer inbox, 1 for the Delayed Inbox) at the specified message number. If this exceeds the machine's inbox limit, enters the "too far" state. Otherwise, writes up to 32 bytes of the specified inbox message, beginning with the `offset` byte of the message. If `offset` is greater than or equal to the number of bytes in the preimage, writes nothing. Pushes the number of bytes written to the stack as an i32. | +| 0x8022 | HaltAndSetFinished | Sets the machine status to finished, halting execution and marking it as a success. | + +## WAVM Floating point implementation + +Implementing correct, consistent, and deterministic floating point operations directly in WAVM +(meaning both a Rust Arbitrator implementation and Solidity OSP implementation) +would be an extremely tricky endeavor. +WASM specifies floating point operations as being compliant to IEEE 754-2019, +which is not deterministic, and full of edge cases. + +Instead, floating point operations (apart from trivial bit-casts like i32 \<-\> f32) +are implemented using the C Berkeley SoftFloat-3e library running inside WAVM. +Arbitrator links other WAVM guests against this, +by replacing float point operations with cross module calls to the library. + +Berkeley SoftFloat does not implement all necessary floating point operations, however. +Most importantly, it does not provide a min function, despite IEEE 754-2019 specifying one. +The implementation of these operations, +along with the export of convenient APIs for WASM opcode implementations, +are contained in bindings32.c for 32 bit integers and bindings64.c for 64 bit integers. + +This ensures that floating point operations are deterministic and consistent between Arbitrator and the OSP, +as they are implemented exclusively using operations already known to be deterministic and consistent. +However, it does not ensure that the floating point operations are perfectly compliant to the WASM specification. +Go uses floating points in its JS\<-\>Go WASM interface, +and floating points may be used outside core state transition code for imprecise computations, +but the former is well exercised as used in Nitro, +and the latter generally doesn't rely on details like the minimum of NaN and infinity. + +### Known divergences from the WASM specification + +Floating point to integer truncation will saturate on overflow, instead of erroring. +This is generally safer, because on x86, overflowing simply produces an undefined result. +A WASM proposal exists to add new opcodes which are defined to saturate, but it's not widely adopted. + +## WAVM Modules + +WASM natively has a notion of modules. +Normally, in WASM, a module is the entire program. +A `.wasm` file represents one module, and generally they aren't combined. +An exception to this is C compiled via Clang, where wasm files are also used as object files, +but [its linking scheme](https://github.com/WebAssembly/tool-conventions/blob/main/Linking.mdx) is not supported in other languages. + +In WAVM this is extended to make the executing program composed of multiple modules. +These may call each other, and library modules may write to their caller's memory to return results. + +### The entrypoint module + +The entrypoint module is where execution begins. +It calls modules' `start` functions if specified, +and then calls the main module's main function, which is language specific. +For Go it sets argv to `["js"]` to match the JS environment, and calls `run`. +For Rust it calls `main` with no arguments. + +### Library exports + +Libraries may export functions with the name pattern `module__name`, +which future libraries or the main module can import as `"module" "name"`. + +For instance, this is used for wasi-stub to provide functions rust imports according +to the WebAssembly System Interface. + +### Floating point operations + +To provide floating point operations for future libraries, +the soft float library exports functions which perform floating point ops. +These have the same name as the WASM instruction names, except `.` is replaced with `_`. +Their type signature is also the same, except all `f32`s and `f64`s are bitcasted to `i32`s and `i64`s. + +Future modules can implicitly use these by using WASM floating point operations, +which are replaced at the WASM->WAVM level with bitcasts and cross module calls to these functions. + +### WAVM guest calls + +Libraries may call the main module's exports via `"env" "wavm_guest_call__*"`. + +For instance, go-stub calls Go's resume function when queueing async events +via `wavm_guest_call_resume()`, and then retrieves the new stack pointer with +`wavm_guest_call_getsp()`. + +### Caller module internals call + +Every stack frame retains its caller module and its caller module's "internals offset", +which is the first internal function index. +WAVM appends 4 "internal" functions to each module, which perform a memory load or store of 1 or 4 bytes. + +Via `wavm_caller_{load,store}{8,32}`, a library may access its caller's memory, +which is implemented by calling these internal functions of the caller's module. +Only libraries can access their caller's memory; the main module cannot. + +For instance, this is used to read arguments from and write return values to the Go stack, +when Go calls into go-stub. diff --git a/arbitrum-docs/how-arbitrum-works/inside-anytrust.mdx b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx similarity index 62% rename from arbitrum-docs/how-arbitrum-works/inside-anytrust.mdx rename to arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx index c490cdcc2..24799e8f9 100644 --- a/arbitrum-docs/how-arbitrum-works/inside-anytrust.mdx +++ b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx @@ -1,20 +1,23 @@ --- -author: dzgoldman +title: AnyTrust Protocol +description: 'Learn the fundamentals of the Arbitrum AnyTrust protocol.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about AnyTrust. +content_type: get-started --- -# Inside AnyTrust +AnyTrust is a variant of Arbitrum Nitro technology that lowers costs by accepting a mild trust assumption. -AnyTrust is a variant of Arbitrum Nitro technology that lowers costs by accepting a mild trust assumption. +The Arbitrum protocol requires that all Arbitrum nodes, including validators (nodes that verify correctness of the chain and are prepared to stake on correct results), have access to the data of every L2 Transaction in the Arbitrum chain's inbox. An Arbitrum rollup provides data access by posting the data (in batched, compressed form) on L1 Ethereum as calldata. The Ethereum gas to pay for this is the largest component of cost in Arbitrum. -The Arbitrum protocol requires that all Arbitrum nodes, including validators (nodes that verify correctness of the chain and are prepared to stake on correct results), have access to the data of every L2 transaction in the Arbitrum chain's inbox. An Arbitrum rollup provides data access by posting the data (in batched, compressed form) on L1 Ethereum as calldata. The Ethereum gas to pay for this is the largest component of cost in Arbitrum. - -AnyTrust relies instead on an external Data Availability Committee (hereafter, "the Committee") to store data and provide it on demand. The Committee has N members, of which AnyTrust assumes at least two are honest. This means that if N - 1 Committee members promise to provide access to some data, at least one of the promising parties must be honest. Since there are two honest members, and only one failed to make the promise, it follows that at least one of the promisers must be honest — and that honest member will provide data when it is needed to ensure the chain can properly function. +AnyTrust relies instead on an external Data Availability Committee (hereafter, "the Committee") to store data and provide it on demand. The Committee has `N` members, of which AnyTrust assumes at least two are honest. This means that if `N - 1` Committee members promise to provide access to some data, at least one of the promising parties must be honest. Since there are two honest members, and only one failed to make the promise, it follows that at least one of the promisers must be honest — and that honest member will provide data when it is needed to ensure the chain can properly function. ## Keysets -A Keyset specifies the public keys of Committee members and the number of signatures required for a Data Availability Certificate to be valid. Keysets make Committee membership changes possible and provide Committee members the ability to change their keys. +A Keyset specifies the BLS public keys of Committee members and the number of signatures required for a Data Availability Certificate to be valid. Keysets make Committee membership changes possible and provide Committee members the ability to change their keys. -A Keyset contains +A Keyset contains: - the number of Committee members, and - for each Committee member, a BLS public key, and @@ -37,9 +40,9 @@ A central concept in AnyTrust is the Data Availability Certificate (hereafter, a - a bitmap saying which Committee members signed, and - a BLS aggregated signature (over the BLS12-381 curve) proving that those parties signed. -Because of the 2-of-N trust assumption, a DACert constitutes proof that the block's data (i.e., the preimage of the hash in the DACert) will be available from at least one honest Committee member, at least until the expiration time. +Because of the `2-of-N` trust assumption, a DACert constitutes proof that the block's data (i.e., the preimage of the hash in the DACert) will be available from at least one honest Committee member, at least until the expiration time. -In ordinary (non-AnyTrust) Nitro, the Arbitrum sequencer posts data blocks on the L1 chain as calldata. The hashes of the data blocks are committed by the L1 Inbox contract, allowing the data to be reliably read by L2 code. +In ordinary (non-AnyTrust) Nitro, the Arbitrum Sequencer posts data blocks on the L1 chain as calldata. The hashes of the data blocks are committed by the L1 Inbox contract, allowing the data to be reliably read by L2 code. AnyTrust gives the sequencer two ways to post a data block on L1: it can post the full data as above, or it can post a DACert proving availability of the data. The L1 inbox contract will reject any DACert that uses an invalid Keyset; the other aspects of DACert validity are checked by L2 code. @@ -64,7 +67,7 @@ The DAS software, based on configuration options, can store its data in local fi ## Sequencer-Committee Interaction -When the Arbitrum sequencer produces a data batch that it wants to post using the Committee, it sends the batch's data, along with an expiration time (normally three weeks in the future) via RPC to all Committee members in parallel. Each Committee member stores the data in its backing store, indexed by the data's hash. Then the member signs the (hash, expiration time) pair using its BLS key, and returns the signature with a success indicator to the sequencer. +When the Arbitrum sequencer produces a data Batch that it wants to post using the Committee, it sends the batch's data, along with an expiration time (normally three weeks in the future) via RPC to all Committee members in parallel. Each Committee member stores the data in its backing store, indexed by the data's hash. Then the member signs the (hash, expiration time) pair using its BLS key, and returns the signature with a success indicator to the sequencer. Once the Sequencer has collected enough signatures, it can aggregate the signatures and create a valid DACert for the (hash, expiration time) pair. The Sequencer then posts that DACert to the L1 inbox contract, making it available to the AnyTrust chain software at L2. diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx new file mode 100644 index 000000000..a8a0137dc --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -0,0 +1,134 @@ +--- +title: Gas and Fees +description: 'Learn the fundamentals of how to calculate fees on Arbitrum.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about gas/fee calculations on Arbitrum. +content_type: get-started +--- + +Gas is used by Arbitrum to track the cost of execution on a Nitro chain. It works the same as Ethereum gas, in the sense that every EVM instruction costs the same amount of gas that it would on Ethereum. + +There are two parties a user pays when submitting a tx: + +- the poster, if reimbursable, for L1 resources such as the L1 calldata needed to post the tx +- the network fee account for L2 resources, which include the computation, storage, and other burdens L2 nodes must bear to service the tx + +The L1 component is the product of the Transaction's estimated contribution to its Batch's size — computed using Brotli on the transaction by itself — and the L2's view of the L1 data price, a value which dynamically adjusts over time to ensure the batch-poster is ultimately fairly compensated. + +The L2 component consists of the traditional fees Geth would pay to stakers in a vanilla L1 chain, such as the computation and storage charges applying the State Transition Function entails. ArbOS charges additional fees for executing its L2-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 L1 and L2 fees. If you do not need precise calculations or a technical understanding, skip to the next section, [L1 to L2 messaging](/how-arbitrum-works/10-l1-to-l2-messaging.mdx). + +## L1 gas pricing + +ArbOS dynamically prices L1 gas, with the price adjusting to ensure that the amount collected in L1 gas fees is as close as possible to the costs that must be covered, over time. + +### L1 costs + +There are two types of L1 costs: batch posting costs, and rewards. + +Batch posting costs reflect the actual cost a batch poster pays to post batch data on L1. Whenever a batch is posted, the L1 contract that records the batch will send a special "batch posting report" message to L2 ArbOS, reporting who paid for the batch and what the L1 basefee was at the time. This message is placed in the chain's Delayed Inbox, so it will be delivered to L2 ArbOS after some delay. + +When a batch posting report message arrives at L2, ArbOS computes the cost of the referenced batch by multiplying the reported basefee by the batch's data cost. (ArbOS retrieves the batch's data from its inbox state, and computes the L1 gas that the batch would have used by counting the number of zero bytes and non-zero bytes in the batch.) The resulting cost is recorded by the pricer as funds due to the party who is reported to have submitted the batch. + +The second type of L1 cost is an optional (per chain) per-unit reward for handling transaction calldata. In general the reward might be paid to the Sequencer, or to members of the Data Availability Committee in an AnyTrust chain, or to anyone else who incurs per-calldata-byte costs on behalf of the chain. The reward is a fixed number of wei per data unit, and is paid to a single address. + +The L1 pricer keeps track of the funds due to the reward address, based on the number of data units handled so far. This amount is updated whenever a batch posting report arrives at L2. + +### L1 calldata fees + +L1 calldata fees exist because the Sequencer, or the batch poster which posts the Sequencer's transaction batches on Ethereum, incurs costs in L1 gas to post transactions on Ethereum as calldata. Funds collected in L1 calldata fees are credited to the batch poster to cover its costs. + +Every transaction that comes in through the Sequencer will pay an L1 calldata fee. Transactions that come in through the delayed inbox do not pay this fee because they don't add to batch posting costs--but these transactions pay gas fees to Ethereum when they are put into the delayed inbox. + +The L1 pricing algorithm assigns an L1 calldata fee to each Sequencer transaction. First, it computes the transaction's size, which is an estimate of how many bytes the transaction will add to the compressed batch it is in; the formula for this includes an estimate of how compressible the transaction is. Second, it multiplies the computed size estimate by the current price per estimated byte, to determine the transaction's L1 calldata wei, in wei. Finally, it divides this cost by the current L2 basefee to translate the fee into L2 gas units. The result is reported as the "poster fee" for the transaction. + +The price per estimated byte is set by a dynamic algorithm that compares the total L1 calldata fees collected to the total fees actually paid by batch posters, and tries to bring the two as close to equality as possible. If the batch posters' costs have been less than fee receipts, the price will increase, and if batch poster costs have exceeded fee receipts, the price will decrease. + +### L1 fee collection + +A transaction is charged for L1 gas if and only if it arrived as part of a sequencer batch. This means that someone would have paid for L1 gas to post the transaction on the L1 chain. + +The estimated cost of posting a transaction on L1 is the product of the transaction's estimated size, and the current L1 Gas Basefee. This estimated cost is divided by the current L2 gas basefee to obtain the amount of L2 gas that corresponds to the L1 operation (more information about this can be found in [this article][two_dimensional_fees_medium_article_link]). + +The estimated size is measured in L1 gas and is calculated as follows: first, compress the transaction's data using the brotli-zero algorithm, then multiply the size of the result by 16. (16 is because L1 charges 16 gas per byte. L1 charges less for bytes that are zero, but that doesn't make sense here.) Brotli-zero is used in order to reward users for posting transactions that are compressible. Ideally we would like to reward for posting transactions that contribute to the compressibility (using the brotli compressor) of the entire batch, but that is a difficult notion to define and in any case would be too expensive to compute at L2. Brotli-zero is an approximation that is cheap enough to compute. + +L1 gas fee funds that are collected from transactions are transferred to a special [`L1PricerFundsPool`][l1pricerfundspool_link] account, so that account's balance represents the amount of funds that have been collected and are available to pay for costs. + +The L1 pricer also records the total number of "data units" (the sum of the estimated sizes, after multiplying by 16) that have been received. + +[l1pricerfundspool_link]: https://github.com/OffchainLabs/nitro/blob/3f4939df1990320310e7f39e8abb32d5c4d8045f/arbos/l1pricing/l1pricing.go#L46 +[two_dimensional_fees_medium_article_link]: https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9 + +## L2 gas pricing + +The L2 gas price on a given Arbitrum chain has a set floor, which can be queried via [ArbGasInfo](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo)'s `getMinimumGasPrice` method (currently @arbOneGasFloorGwei@ gwei on Arbitrum One and @novaGasFloorGwei@ gwei on Nova). + +### Estimating L2 Gas + +Calling an Arbitrum Node's `eth_estimateGas` RPC gives a value sufficient to cover the full transaction fee at the given L2 gas price; i.e., the value returned from `eth_estimateGas` multiplied by the L2 gas price tells you how much total Ether is required for the transaction to succeed. Note that this means that for a given operation, the value returned by `eth_estimateGas` will change over time (as the L1 calldata price fluctuates.) (See [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and [How to estimate gas in Arbitrum](/build-decentralized-apps/02-how-to-estimate-gas.mdx) for more.) + +### L2 gas fees + +L2 gas fees work very similarly to gas on Ethereum. A transaction uses some amount of gas, and this is multiplied by the current basefee to get the L2 gas fee charged to the transaction. + +The L2 basefee is set by a version of the "exponential mechanism" which has been widely discussed in the Ethereum community, and which has been shown equivalent to Ethereum's EIP-1559 gas pricing mechanism. + +The algorithm compares gas usage against a parameter called the [speed limit](#the-speed-limit) which is the target amount of gas per second that the chain can handle sustainably over time. (Currently the Speed Limit on Arbitrum One is @arbOneGasSpeedLimitGasPerSec@ gas per second.) The algorithm tracks a gas backlog. Whenever a transaction consumes gas, that gas is added to the backlog. Whenever the clock ticks one second, the speed limit is subtracted 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 below the sustainable limit so more gas usage can be welcomed. + +To make this more precise, the basefee is an exponential function of the backlog, _F = exp(-a(B-b))_, where a and b are suitably chosen constants: _a_ controls how rapidly the price escalates with backlog, and _b_ allows a small backlog before the basefee escalation begins. + +### L2 Tips + +The sequencer prioritizes transactions on a first-come first-served basis. Because tips do not make sense in this model, they are ignored. Arbitrum users always just pay the basefee regardless of the tip they choose. + +### Gas Estimating Retryables + +When a transaction schedules another, the subsequent transaction's execution [will be included][estimation_inclusion_link] when estimating gas via the node's RPC. A transaction's gas estimate, then, can only be found if all the transactions succeed at a given gas limit. This is especially important when working with retryables and scheduling redeem attempts. + +Because a call to [`redeem`](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) donates all of the call's gas, doing multiple requires limiting the amount of gas provided to each subcall. Otherwise the first will take all of the gas and force the second to necessarily fail irrespective of the estimation's gas limit. + +Gas estimation for Retryable submissions is possible via the [NodeInterface](/build-decentralized-apps/nodeinterface/02-reference.mdx) and similarly requires the auto-redeem attempt to succeed. + +[estimation_inclusion_link]: https://github.com/OffchainLabs/go-ethereum/blob/d52739e6d54f2ea06146fdc44947af3488b89082/internal/ethapi/api.go#L999 + +### The Speed Limit + +The security of Nitro chains depends on the assumption that when one Validator creates an RBlock, other validators will check it, and respond with a correct RBlock and a Challenge if it is wrong. This requires that the other validators have the time and resources to check each RBlock quickly enough to issue a timely challenge. The Arbitrum protocol takes this into account in setting deadlines for RBlocks. + +This sets an effective speed limit on execution of a Nitro chain: in the long run the chain cannot make progress faster than a validator can emulate its execution. If RBlocks are published at a rate faster than the speed limit, their deadlines will get farther and farther in the future. Due to the limit, enforced by the rollup protocol contracts, on how far in the future a deadline can be, this will eventually cause new RBlocks to be slowed down, thereby enforcing the effective speed limit. + +Being able to set the speed limit accurately depends on being able to estimate the time required to validate an RBlock, with some accuracy. Any uncertainty in estimating validation time will force us to set the speed limit lower, to be safe. And we do not want to set the speed limit lower, so we try to enable accurate estimation. + +## Total fee and gas estimation + +The total fee charged to a transaction is the L2 basefee, multiplied by the sum of the L2 gas used plus the L1 calldata charge. As on Ethereum, a transaction will fail if it fails to supply enough gas, or if it specifies a basefee limit that is below the current basefee. Ethereum also allows a "tip" but Nitro ignores this field and never collects any tips. + +### Allocating funds and paying what is owed + +When a batch posting report is processed at L2, the pricer allocates some of the collected funds to pay for costs incurred. To allocate funds, the pricer considers three timestamps: + +- `currentTime` is the current time, when the batch posting report message arrives at L2 +- `updateTime` is the time at which the reported batch was submitted (which will typically be around 20 minutes before currentTime) +- `lastUpdateTime` is the time at which the previous reported batch was submitted + +The pricer computes an allocation fraction `F = (updateTime-lastUpdateTime) / (currentTime-lastUpdateTime)` and allocates a fraction `F` of funds in the `L1PricerFundsPool` to the current report. The intuition is that the pricer knows how many funds have been collected between `lastUpdateTime` and `currentTime`, and we want to figure out how many of those funds to allocate to the interval between `lastUpdateTime` and `updateTime`. The given formula is the correct allocation, if we assume that funds arrived at a uniform rate during the interval between `lastUpdateTime` and `currentTime`. The pricer similarly allocates a portion of the total data units to the current report. + +Now the pricer pays out the allocated funds to cover the rewards due and the amounts due to batch posters, reducing the balance due to each party as a result. If the allocated funds aren't sufficient to cover everything that is due, some amount due will remain. If all of the amount due can be covered with the allocated funds, any remaining allocated funds are returned to the `L1PricerFundsPool`. + +### Getting L1 fee info + +The L1 gas basefee can be queried via [`ArbGasInfo.getL1BaseFeeEstimate`](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo). To estimate the L1 fee a transaction will use, the [NodeInterface.gasEstimateComponents()](/build-decentralized-apps/nodeinterface/02-reference.mdx) or [NodeInterface.gasEstimateL1Component()](/build-decentralized-apps/nodeinterface/02-reference.mdx) method can be used. + +Arbitrum transaction receipts include a `gasUsedForL1` field, showing the amount of gas used on L1 in units of L2 gas. + +### Adjusting the L1 gas basefee + +After allocating funds and paying what is owed, the L1 Pricer adjusts the L1 Gas Basefee. The goal of this process is to find a value that will cause the amount collected to equal the amount owed over time. + +The algorithm first computes the surplus (funds in the `L1PricerFundsPool`, minus total funds due), which might be negative. If the surplus is positive, the L1 Gas Basefee is reduced, so that the amount collected over a fixed future interval will be reduced by exactly the surplus. If the surplus is negative, the Basefee is increased so that the shortfall will be eliminated over the same fixed future interval. + +A second term is added to the L1 Gas Basefee, based on the derivative of the surplus (surplus at present, minus the surplus after the previous batch posting report was processed). This term, which is multiplied by a smoothing factor to reduce fluctuations, will reduce the Basefee if the surplus is increasing, and increase the Basefee if the surplus is shrinking. diff --git a/arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx similarity index 78% rename from arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx rename to arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index c7cf4e50c..2362176e0 100644 --- a/arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -1,8 +1,10 @@ --- -title: 'L1 to L2 messaging' -description: This concept page provides information about how arbitrary messages are passed from L1 to L2 -target_audience: developers who want to build on Arbitrum -content_type: concept +title: L1 to L2 messaging +description: 'Learn the fundamentals of L1 to L2 messaging on Arbitrum.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about messaging between L1 and L2 within Arbitrum. +content_type: get-started --- import { AddressAliasHelper } from '@site/src/components/AddressAliasHelper'; @@ -15,36 +17,40 @@ import { NodeDescription, } from '/src/components/MermaidWithHtml/MermaidWithHtml'; +In the [Transaction Lifecycle](/how-arbitrum-works/02-transaction-lifecycle.mdx) section, we covered how users interact with L2 contracts. They submit transactions by putting messages into the chain’s inbox or having a full node Sequencer or aggregator do so on their behalf. + +L1 and L2 chains run asynchronously from each other, so it is not possible to make a cross-chain call that produces a result within the same Transaction as the caller. Instead, cross-chain calls must be asynchronous, meaning that the caller submits the call at some point in time, and the call runs later. Consequently, a cross-chain contract-to-contract call can never produce a result available to the calling contract (except for acknowledgment of a successful call submitted for later execution). + +In this section, we will discuss how contracts interact between L1 and L2, how an L1 contract is called an L2 contract, and vice versa. + ## Retryable Tickets -Retryable tickets are Arbitrum's canonical method for creating L1 to L2 messages, i.e., L1 transactions that initiate a message to be executed on L2. A retryable can be submitted for a fixed cost (dependent only on its calldata size) paid at L1; its _submission_ on L1 is separable / asynchronous with its _execution_ on L2. Retryables provide atomicity between the cross chain operations; if the L1 transaction to request submission succeeds (i.e. does not revert) then the execution of the Retryable on L2 has a strong guarantee to ultimately succeed as well. +Retryable tickets are Arbitrum's canonical method for creating L1 to L2 messages, i.e., L1 transactions that initiate a message to be executed on L2. A retryable can be submitted for a fixed cost (dependent only on its calldata size) paid at L1; its _submission_ on L1 is separable / asynchronous with its _execution_ on L2. Retryables provide atomicity between the cross chain operations; if the L1 transaction to request submission succeeds (i.e. does not revert) then the execution of the Retryable on L2 has a strong guarantee to ultimately succeed as well. ## Retryable Tickets Lifecycle -Here we walk through the different stages of the lifecycle of a retryable ticket; (1) submission, (2) auto-redemption, and (3) manual redemption. +Here we walk through the different stages of the lifecycle of a Retryable Ticket; (1) submission, (2) auto-redemption, and (3) manual redemption. ### Submission -1. Creating a retryable ticket is initiated with a call (direct or internal) to the `createRetryableTicket` function of the [`inbox` contract][inbox_link]. A ticket is guaranteed to be created if this call succeeds. Here, we describe parameters that need to be carefully set. Note that, this function forces the sender to provide a _reasonable_ amount of funds (at least enough to submitting, and _attempting_ to executing the ticket), but that doesn't guarantee a successful auto-redemption. +1. Creating a retryable ticket is initiated with a call (direct or internal) to the `createRetryableTicket` function of the [`inbox` contract](https://github.com/OffchainLabs/nitro-contracts/blob/67127e2c2fd0943d9d87a05915d77b1f220906aa/src/bridge/Inbox.sol). A ticket is guaranteed to be created if this call succeeds. Here, we describe parameters that need to be carefully set. Note that, this function forces the sender to provide a _reasonable_ amount of funds (at least enough to submitting, and _attempting_ to executing the ticket), but that doesn't guarantee a successful auto-redemption. -| Parameter | Description | -| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `l1CallValue (also referred to as deposit)` | Not a real function parameter, it is rather the callValue that is sent along with the transaction | -| `address to` | The destination L2 address | -| `uint256 l2CallValue` | The callvalue for retryable L2 message that is supplied within the deposit (l1CallValue) | -| `uint256 maxSubmissionCost` | The maximum amount of ETH to be paid for submitting the ticket. This amount is (1) supplied within the deposit (l1CallValue) to be later deducted from sender's L2 balance and is (2) directly proportional to the size of the retryable’s data and L1 basefee | -| `address excessFeeRefundAddress` | The unused gas cost and submssion cost will deposit to this address, formula is: `(gasLimit x maxFeePerGas - execution cost) + (maxSubmission - (autoredeem ? 0 : submission cost))`. (Note: excess deposit will transfer to the alias address of the parent chain tx's `msg.sender` rather than this address) | -| `address callValueRefundAddress` | The L2 address to which the l2CallValue is credited if the ticket times out or gets cancelled (this is also called the `beneficiary`, who's got a critical permission to cancel the ticket) | -| `uint256 gasLimit` | Maximum amount of gas used to cover L2 execution of the ticket | -| `uint256 maxFeePerGas` | The gas price bid for L2 execution of the ticket that is supplied within the deposit (l1CallValue) | -| `bytes calldata data` | The calldata to the destination L2 address | +| Parameter | Description | +| :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `l1CallValue (also referred to as deposit)` | Not a real function parameter, it is rather the callValue that is sent along with the transaction | +| `address to` | The destination L2 address | +| `uint256 l2CallValue` | The callvalue for retryable L2 message that is supplied within the deposit (l1CallValue) | +| `uint256 maxSubmissionCost` | The maximum amount of ETH to be paid for submitting the ticket. This amount is (1) supplied within the deposit (l1CallValue) to be later deducted from sender's L2 balance and is (2) directly proportional to the size of the retryable’s data and L1 basefee | +| `address excessFeeRefundAddress` | The unused gas cost and submssion cost will deposit to this address, formula is: `(gasLimit x maxFeePerGas - execution cost) + (maxSubmission - (autoredeem ? 0 : submission cost))`. (Note: excess deposit will transfer to the alias address of the Parent chain tx's `msg.sender` rather than this address) | +| `address callValueRefundAddress` | The L2 address to which the l2CallValue is credited if the ticket times out or gets cancelled (this is also called the `beneficiary`, who's got a critical permission to cancel the ticket) | +| `uint256 gasLimit` | Maximum amount of gas used to cover L2 execution of the ticket | +| `uint256 maxFeePerGas` | The gas price bid for L2 execution of the ticket that is supplied within the deposit (l1CallValue) | +| `bytes calldata data` | The calldata to the destination L2 address | 2. Sender's deposit must be enough to make the L1 submission succeed and for the L2 execution to be _attempted_. If provided correctly, a new ticket with a unique `TicketID` is created and added to retryable buffer. Also, funds (`submissionCost` + `l2CallValue`) are deducted from the sender and placed into the escrow for later use in redeeming the ticket. 3. Ticket creation causes the [`ArbRetryableTx`](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile to emit a `TicketCreated` event containing the `TicketID` on L2. -[inbox_link]: https://github.com/OffchainLabs/nitro-contracts/blob/67127e2c2fd0943d9d87a05915d77b1f220906aa/src/bridge/Inbox.sol - 🧍 @@ -125,7 +131,7 @@ Here we walk through the different stages of the lifecycle of a retryable ticket ### Manual Redemption -5. At this point, _anyone_ can attempt to manually redeem the ticket again by calling [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx)'s `redeem` precompile method, which donates the call's gas to the next attempt. Note that the amount of gas is NOT limited by the original gasLimit set during the ticket creation. ArbOS will [enqueue the redeem][enqueue_link], which is its own special `ArbitrumRetryTx` type, to its list of redeems that ArbOS [guarantees to exhaust][exhaust_link] before moving on to the next non-redeem transaction in the block its forming. In this manner redeems are scheduled to happen as soon as possible, and will always be in the same block as the tx that scheduled it. Note that the redeem attempt's gas comes from the call to redeem, so there's no chance the block's gas limit is reached before execution. +5. At this point, _anyone_ can attempt to manually redeem the ticket again by calling [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx)'s `redeem` precompile method, which donates the call's gas to the next attempt. Note that the amount of gas is NOT limited by the original gasLimit set during the ticket creation. ArbOS will [enqueue the redeem][enqueue_link], which is its own special `ArbitrumRetryTx` type, to its list of redeems that ArbOS [guarantees to exhaust][exhaust_link] before moving on to the next non-redeem transaction in the block its forming. In this manner redeems are scheduled to happen as soon as possible, and will always be in the same block as the tx that scheduled it. Note that the redeem attempt's gas comes from the call to redeem, so there's no chance the block's gas limit is reached before execution. 6. If the fixed period (one week) elapses without a successful redeem, the ticket **expires** and will be [automatically **discarded**][discard_link], unless some party has paid a fee to [**keep the ticket alive**][renew_link] for another full period. A ticket can live indefinitely as long as it is renewed each time before it expires. @@ -199,7 +205,7 @@ In the lifecycle of a retryable ticket, two types of L2 transaction receipts wil ### Alternative "unsafe" Retryable Ticket Creation -The `Inbox.createRetryableTicket` convenience method includes sanity checks to help minimize the risk of user error: the method will ensure that enough funds are provided directly from L1 to cover the current cost of ticket creation. It also will convert the provided `callValueRefundAddress` and `excessFeeRefundAddress` to their address alias (see below) if either is a contract (determined by if the address has code during the call), providing a path for the L1 contract to recover funds. A power-user may bypass these sanity-check measures via the `Inbox`'s `unsafeCreateRetryableTicket` method; as the method's name desperately attempts to warn you, it should only be accessed by a user who truly knows what they're doing. +The `Inbox.createRetryableTicket` convenience method includes sanity checks to help minimize the risk of user error: the method will ensure that enough funds are provided directly from L1 to cover the current cost of ticket creation. It also will convert the provided `callValueRefundAddress` and `excessFeeRefundAddress` to their Address Alias (see below) if either is a contract (determined by if the address has code during the call), providing a path for the L1 contract to recover funds. A power-user may bypass these sanity-check measures via the `Inbox`'s `unsafeCreateRetryableTicket` method; as the method's name desperately attempts to warn you, it should only be accessed by a user who truly knows what they're doing. ## Eth deposits @@ -211,7 +217,7 @@ In principle, retryable tickets can alternatively be used to deposit Ether; this ## Transacting via the Delayed Inbox -While retryables and Eth deposits _must_ be submitted through the delayed inbox, in principle, _any_ message can be included this way; this is a necessary recourse to ensure the Arbitrum chain preserves censorship resistance even if the Sequencer misbehaves (see [The Sequencer and Censorship Resistance](/how-arbitrum-works/sequencer.mdx)). However, under ordinary/happy circumstances, the expectation/recommendation is that clients use the delayed inbox only for Retryables and Eth deposits, and transact via the Sequencer for all other messages. +While retryables and Eth deposits _must_ be submitted through the Delayed Inbox, in principle, _any_ message can be included this way; this is a necessary recourse to ensure the Arbitrum chain preserves censorship resistance even if the Sequencer misbehaves (see [The Sequencer and Censorship Resistance](/how-arbitrum-works/03-sequencer.mdx)). However, under ordinary/happy circumstances, the expectation/recommendation is that clients use the delayed inbox only for Retryables and Eth deposits, and transact via the Sequencer for all other messages. ### Address Aliasing @@ -224,6 +230,7 @@ L2_Alias = L1_Contract_Address + 0x1111000000000000000000000000000000001111 :::tip Try it out + ::: The Arbitrum protocol's usage of L2 Aliases for L1-to-L2 messages prevents cross-chain exploits that would otherwise be possible if we simply reused the same L1 addresses as the L2 sender; i.e., tricking an L2 contract that expects a call from a given contract address by sending retryable ticket from the expected contract address on L1. @@ -239,6 +246,6 @@ modifier onlyFromMyL1Contract() override { ### Signed Messages -The delayed inbox can also accept messages that include a signature. In this case, the message will execute with the `msg.sender` address equal to the address that produced the included signature (i.e., _not_ its alias). Intuitively, the signature proves that the sender address is not a contract, and thus is safe from cross-chain exploit concerns described above. Thus, it can safely execute from signer's address, similar to a transaction included in a Sequencer's batch. For these messages, the address of the L1 sender is effectively ignored at L2. +The delayed inbox can also accept messages that include a signature. In this case, the message will execute with the `msg.sender` address equal to the address that produced the included signature (i.e., _not_ its alias). Intuitively, the signature proves that the sender address is not a contract, and thus is safe from cross-chain exploit concerns described above. Thus, it can safely execute from signer's address, similar to a transaction included in a Sequencer's Batch. For these messages, the address of the L1 sender is effectively ignored at L2. These signed messages submitted through the delayed inbox can be used to execute messages that bypass the Sequencer and require EOA authorization at L2, e.g., force-including an Ether withdrawal (see ["withdraw eth tutorial"](https://github.com/OffchainLabs/arbitrum-tutorials/blob/a1c3f64a5abdd0f0e728cb94d4ecc2700eab7579/packages/delayedInbox-l2msg/scripts/withdrawFunds.js#L61-L65)). diff --git a/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx new file mode 100644 index 000000000..91bf84bf6 --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx @@ -0,0 +1,33 @@ +--- +title: L2 to L1 messaging +description: 'Learn the fundamentals of L2 to L1 messaging on Arbitrum.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about messaging between L2 and L1 on Arbitrum. +content_type: get-started +--- + +Arbitrum's Outbox system +allows for arbitrary L2 to L1 contract calls; i.e., messages initiated from L2 which eventually +resolve in execution on L1. L2-to-L1 messages (aka "outgoing" messages) bear many things in common +with Arbitrum's [L1-to-L2 messages](/how-arbitrum-works/10-l1-to-l2-messaging.mdx) (Retryables), "in +reverse" though with a few differences. + +### Protocol Flow + +Part of the L2 state of an Arbitrum chain — and consequently, part of what's asserted in every RBlock — is a Merkle root of all L2-to-L1 messages in the chain's history. Upon an asserted RBlock being confirmed (typically ~1 week after its asserted), this Merkle root is posted on L1 in the `Outbox` contract. The Outbox contract then lets users execute their messages — validating Merkle proofs of inclusion, and tracking which L2 to L1 messages have already been spent. + +### Client Flow + +From a Client perspective, an L2 to L1 message begins with a call to the L2 [`ArbSys`](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) precompile contract's `sendTxToL1` method. Once the message is included in an Assertion (typically within ~1 hour) and the assertion is confirmed (typically about ~ 1 week), any client can execute the message. To do this, the client first retrieves the proof data via a call to the Arbitrum chain's "virtual"/precompile-esque\*\* `NodeInterface` contract's `constructOutboxProof` method. The data returned can then be used in the `Outbox`'s `executeTransaction` method to perform the L1 execution. + +### Protocol Design Details + +An important feature in the design of the Outbox system is that calls to `confirmNode` have constant overhead. Requiring that `confirmNode` only update the constant-sized outgoing message root hash, and that users themselves carry out the final step of execution, achieves this goal; i.e., no matter the number of outgoing messages in the root, or the gas cost of executing them on L1, the cost of confirming nodes remains constant; this ensures that the RBlock Confirmation processed can't be griefed. + +Unlike Retryables, which have an option to provide Ether for automatic L2 execution, outgoing messages can't provide in-protocol automatic L1 execution, for the simple reason that Ethereum itself doesn't offer scheduled execution affordances. However, application-layer contracts that interact with the Outbox could in principle be built to provide somewhat-analogous "execution market" functionality for outsourcing the final L1 execution step. + +Another difference between outgoing messages and Retryables is that Retryables have a limited lifetime before which they must be redeemed (or have their lifetime explicitly extended), whereas L2 to L1 messages are stored in L1 state, and thus persist permanently / have no deadline before which they must be executed. +The week long delay period before outgoing messages can be executed is inherent and fundamental to the nature of Arbitrum Rollup, or any Optimistic Rollup style L2; the moment a Transaction is published on-chain, any observer can anticipate its result; however, for Ethereum itself to accept its result, the protocol must give time for Arbitrum validators to detect and prove fault if need-be. For a protocol overview, see [Inside Arbitrum](/how-arbitrum-works/01-a-gentle-introduction.mdx) + +\*\* We refer to `NodeInterface` as a "virtual" contract; its methods are accessible via calls `0x00000000000000000000000000000000000000C8`, but it doesn't really live on chain. It isn't really a precompile, but behaves a lot like a precompile that can't receive calls from other contracts. This is a cute trick that let's us provide Arbitrum-specific data without having to implement a custom RPC. diff --git a/arbitrum-docs/how-arbitrum-works/arbos/geth.mdx b/arbitrum-docs/how-arbitrum-works/arbos/geth.mdx deleted file mode 100644 index 6057b6073..000000000 --- a/arbitrum-docs/how-arbitrum-works/arbos/geth.mdx +++ /dev/null @@ -1,292 +0,0 @@ ---- -author: dzgoldman ---- - -# Geth - -Nitro makes minimal modifications to Geth in hopes of not violating its assumptions. This document will explore the relationship between Geth and ArbOS, which consists of a series of hooks, interface implementations, and strategic re-appropriations of Geth's basic types. - -We store ArbOS's state at an address inside a Geth `statedb`. In doing so, ArbOS inherits the `statedb`'s statefulness and lifetime properties. For example, a transaction's direct state changes to ArbOS are discarded upon a revert. - -**0xA4B05FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF**
-The fictional account representing ArbOS - -:::info - -Please note any links on this page may be referencing old releases of Nitro or our fork of Geth. While we try to keep this up to date and most of this should be stable, please check against latest releases for [Nitro](https://github.com/OffchainLabs/nitro/releases) and [Geth](https://github.com/OffchainLabs/go-ethereum/releases) for most recent changes. - -::: - -## Hooks - -Arbitrum uses various hooks to modify Geth's behavior when processing transactions. Each provides an opportunity for ArbOS to update its state and make decisions about the transaction during its lifetime. Transactions are applied using Geth's [`ApplyTransaction`][applytransaction_link] function. - -Below is [`ApplyTransaction`][applytransaction_link]'s callgraph, with additional info on where the various Arbitrum-specific hooks are inserted. Click on any to go to their section. By default, these hooks do nothing so as to leave Geth's default behavior unchanged, but for chains configured with [`EnableArbOS`](#enablearbos) set to true, [`ReadyEVMForL2`](#ReadyEVMForL2) installs the alternative L2 hooks. - -- `core.ApplyTransaction` ⮕ `core.applyTransaction` ⮕ `core.ApplyMessage` - - `core.NewStateTransition` - - [`ReadyEVMForL2`](#ReadyEVMForL2) - - `core.TransitionDb` - - [`StartTxHook`](#StartTxHook) - - `core.transitionDbImpl` - - if `IsArbitrum()` remove tip - - [`GasChargingHook`](#GasChargingHook) - - `evm.Call` - - `core.vm.EVMInterpreter.Run` - - [`PushCaller`](#PushCaller) - - `PopCaller` - - `core.StateTransition.refundGas` - - [`ForceRefundGas`](#ForceRefundGas) - - [`NonrefundableGas`](#NonrefundableGas) - - [`EndTxHook`](#EndTxHook) - - added return parameter: `transactionResult` - -What follows is an overview of each hook, in chronological order. - -### [`ReadyEVMForL2`][readyevmforl2_link]{#ReadyEVMForL2} - -A call to [`ReadyEVMForL2`][readyevmforl2_link] installs the other transaction-specific hooks into each Geth [`EVM`][evm_link] right before it performs a state transition. Without this call, the state transition will instead use the default [`DefaultTxProcessor`][defaulttxprocessor_link] and get exactly the same results as vanilla Geth. A [`TxProcessor`][txprocessor_link] object is what carries these hooks and the associated Arbitrum-specific state during the transaction's lifetime. - -### [`StartTxHook`][starttxhook_link]{#StartTxHook} - -The [`StartTxHook`][starttxhook_link] is called by Geth before a transaction starts executing. This allows ArbOS to handle two Arbitrum-specific transaction types. - -If the transaction is `ArbitrumDepositTx`, ArbOS adds balance to the destination account. This is safe because the L1 bridge submits such a transaction only after collecting the same amount of funds on L1. - -If the transaction is an `ArbitrumSubmitRetryableTx`, ArbOS creates a retryable based on the transaction's fields. If the transaction includes sufficient gas, ArbOS schedules a retry of the new retryable. - -The hook returns `true` for both of these transaction types, signifying that the state transition is complete. - -### [`GasChargingHook`][gascharginghook_link]{#GasChargingHook} - -This fallible hook ensures the user has enough funds to pay their poster's L1 calldata costs. If not, the transaction is reverted and the [`EVM`][evm_link] does not start. In the common case that the user can pay, the amount paid for calldata is set aside for later reimbursement of the poster. All other fees go to the network account, as they represent the transaction's burden on validators and nodes more generally. - -If the user attempts to purchase compute gas in excess of ArbOS's per-block gas limit, the difference is [set aside][difference_set_aside_link] and [refunded later][refunded_later_link] via [`ForceRefundGas`](#ForceRefundGas) so that only the gas limit is used. Note that the limit observed may not be the same as that seen [at the start of the block][that_seen_link] if ArbOS's larger gas pool falls below the [`MaxPerBlockGasLimit`][max_perblock_limit_link] while processing the block's previous transactions. - -[difference_set_aside_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L407 -[refunded_later_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state_transition.go#L419 -[that_seen_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/block_processor.go#L176 -[max_perblock_limit_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/l2pricing/l2pricing.go#L86 - -### [`PushCaller`][pushcaller_link]{#PushCaller} - -These hooks track the callers within the EVM callstack, pushing and popping as calls are made and complete. This provides [`ArbSys`](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) with info about the callstack, which it uses to implement the methods `WasMyCallersAddressAliased` and `MyCallersAddressWithoutAliasing`. - -### [`L1BlockHash`][l1blockhash_link] - -In Arbitrum, the BlockHash and Number operations return data that relies on underlying L1 blocks instead of L2 blocks, to accommodate the normal use-case of these opcodes, which often assume Ethereum-like time passes between different blocks. The L1BlockHash and L1BlockNumber hooks have the required data for these operations. - -### [`ForceRefundGas`][forcerefundgas_link]{#ForceRefundGas} - -This hook allows ArbOS to add additional refunds to the user's tx. This is currently only used to refund any compute gas purchased in excess of ArbOS's per-block gas limit during the [`GasChargingHook`](#GasChargingHook). - -### [`NonrefundableGas`][nonrefundablegas_link]{#NonrefundableGas} - -Because poster costs come at the expense of L1 aggregators and not the network more broadly, the amounts paid for L1 calldata should not be refunded. This hook provides Geth access to the equivalent amount of L2 gas the poster's cost equals, ensuring this amount is not reimbursed for network-incentivized behaviors like freeing storage slots. - -### [`EndTxHook`][endtxhook_link]{#EndTxHook} - -The [`EndTxHook`][endtxhook_link] is called after the [`EVM`][evm_link] has returned a transaction's result, allowing one last opportunity for ArbOS to intervene before the state transition is finalized. Final gas amounts are known at this point, enabling ArbOS to credit the network and poster each's share of the user's gas expenditures as well as adjust the pools. The hook returns from the [`TxProcessor`][txprocessor_link] a final time, in effect discarding its state as the system moves on to the next transaction where the hook's contents will be set afresh. - -[applytransaction_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state_processor.go#L152 -[evm_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/vm/evm.go#L101 -[defaulttxprocessor_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/vm/evm_arbitrum.go#L42 -[txprocessor_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L38 -[starttxhook_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L100 -[readyevmforl2_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbstate/geth-hook.go#L47 -[gascharginghook_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L354 -[pushcaller_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L76 -[popcaller_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L80 -[forcerefundgas_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L425 -[nonrefundablegas_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L418 -[endtxhook_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L429 -[l1blockhash_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L617 -[l1blocknumber_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/tx_processor.go#L600 - -## Interfaces and components - -### [`APIBackend`][apibackend_link] - -APIBackend implements the [`ethapi.Backend`][ethapi.backend_link] interface, which allows simple integration of the Arbitrum chain to existing Geth API. Most calls are answered using the Backend member. - -[apibackend_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/apibackend.go#L34 -[ethapi.backend_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/internal/ethapi/backend.go#L42 - -### [`Backend`][backend_link] - -This struct was created as an Arbitrum equivalent to the [`Ethereum`][ethereum_link] struct. It is mostly glue logic, including a pointer to the ArbInterface interface. - -[backend_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/backend.go#L15 -[ethereum_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/eth/backend.go#L68 - -### [`ArbInterface`][arbinterface_link] - -This interface is the main interaction-point between geth-standard APIs and the Arbitrum chain. Geth APIs mostly either check status by working on the Blockchain struct retrieved from the [`Blockchain`][blockchain_link] call, or send transactions to Arbitrum using the [`PublishTransactions`][publishtransactions_link] call. - -[arbinterface_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/arbos_interface.go#L10 -[blockchain_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/arbos_interface.go#L12 -[publishtransactions_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/arbos_interface.go#L11 - -### [`RecordingKV`][recordingkv_link] - -RecordingKV is a read-only key-value store, which retrieves values from an internal trie database. All values accessed by a RecordingKV are also recorded internally. This is used to record all preimages accessed during block creation, which will be needed to prove execution of this particular block. -A [`RecordingChainContext`][recordingchaincontext_link] should also be used, to record which block headers the block execution reads (another option would be to always assume the last 256 block headers were accessed). -The process is simplified using two functions: [`PrepareRecording`][preparerecording_link] creates a stateDB and chaincontext objects, running block creation process using these objects records the required preimages, and [`PreimagesFromRecording`][preimagesfromrecording_link] function extracts the preimages recorded. - -[recordingkv_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/recordingdb.go#L22 -[recordingchaincontext_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/recordingdb.go#L123 -[preparerecording_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/recordingdb.go#L152 -[preimagesfromrecording_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/arbitrum/recordingdb.go#L174 - -## Transaction Types - -Nitro Geth includes a few L2-specific transaction types. Click on any to jump to their section. - -| Tx Type | Represents | Last Hook Reached   | Source | -| :------------------------------------------------ | :----------------------------------- | :------------------------- | ------ | -| [`ArbitrumUnsignedTx`][arbtxunsigned] | An L1 to L2 message | [`EndTxHook`][he] | Bridge | -| [`ArbitrumContractTx`][arbtxcontract] | A nonce-less L1 to L2 message   | [`EndTxHook`][he] | Bridge | -| [`ArbitrumDepositTx`][arbtxdeposit] | A user deposit | [`StartTxHook`][hs] | Bridge | -| [`ArbitrumSubmitRetryableTx`][arbtxsubmit]   | Creating a retryable | [`StartTxHook`][hs]   | Bridge | -| [`ArbitrumRetryTx`][arbtxretry] | A retryable redeem attempt | [`EndTxHook`][he] | L2 | -| [`ArbitrumInternalTx`][arbtxinternal] | ArbOS state update | [`StartTxHook`][hs] | ArbOS | - -[arbtxunsigned]: #ArbitrumUnsignedTx -[arbtxcontract]: #ArbitrumContractTx -[arbtxsubmit]: #ArbitrumSubmitRetryableTx -[arbtxretry]: #ArbitrumRetryTx -[arbtxdeposit]: #ArbitrumDepositTx -[arbtxinternal]: #ArbitrumInternalTx -[hs]: #StartTxHook -[he]: #EndTxHook - -The following reference documents each type. - -### [`ArbitrumUnsignedTx`][arbitrumunsignedtx_link]{#ArbitrumUnsignedTx} - -Provides a mechanism for a user on L1 to message a contract on L2. This uses the bridge for authentication rather than requiring the user's signature. Note, the user's acting address will be remapped on L2 to distinguish them from a normal L2 caller. - -### [`ArbitrumContractTx`][arbitrumcontracttx_link]{#ArbitrumContractTx} - -These are like an [`ArbitrumUnsignedTx`][arbitrumunsignedtx_link] but are intended for smart contracts. These use the bridge's unique, sequential nonce rather than requiring the caller specify their own. An L1 contract may still use an [`ArbitrumUnsignedTx`][arbitrumunsignedtx_link], but doing so may necessitate tracking the nonce in L1 state. - -### [`ArbitrumDepositTx`][arbitrumdeposittx_link]{#ArbitrumDepositTx} - -Represents a user deposit from L1 to L2. This increases the user's balance by the amount deposited on L1. - -### [`ArbitrumSubmitRetryableTx`][arbitrumsubmitretryabletx_link]{#ArbitrumSubmitRetryableTx} - -Represents a retryable submission and may schedule an [`ArbitrumRetryTx`](#ArbitrumRetryTx) if provided enough gas. Please see the [retryables documentation](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets) for more info. - -### [`ArbitrumRetryTx`][arbitrumretrytx_link]{#ArbitrumRetryTx} - -These are scheduled by calls to the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile and via retryable auto-redemption. Please see the [retryables documentation](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets) for more info. - -### [`ArbitrumInternalTx`][arbitruminternaltx_link]{#ArbitrumInternalTx} - -Because tracing support requires ArbOS's state-changes happen inside a transaction, ArbOS may create a transaction of this type to update its state in-between user-generated transactions. Such a transaction has a [`Type`][internaltype_link] field signifying the state it will update, though currently this is just future-proofing as there's only one value it may have. Below are the internal transaction types. - -#### [`InternalTxStartBlock`][arbinternaltxstartblock_link] - -Updates the L1 block number and L1 base fee. This transaction [is generated][block_generated_link] whenever a new block is created. They are [guaranteed to be the first][block_first_link] in their L2 block. - -[arbitrumunsignedtx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L43 -[arbitrumcontracttx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L104 -[arbitrumsubmitretryabletx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L232 -[arbitrumretrytx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L161 -[arbitrumdeposittx_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L338 -[arbitruminternaltx_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/internal_tx.go -[internaltype_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arb_types.go#L387 -[arbinternaltxstartblock_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/internal_tx.go#L22 -[block_generated_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/block_processor.go#L181 -[block_first_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/block_processor.go#L182 - -## Transaction Run Modes and Underlying Transactions - -A [geth message][geth_message_link] may be processed for various purposes. For example, a message may be used to estimate the gas of a contract call, whereas another may perform the corresponding state transition. Nitro Geth denotes the intent behind a message by means of its [`TxRunMode`][txrunmode_link], [which it sets][set_run_mode_link] before processing it. ArbOS uses this info to make decisions about the transaction the message ultimately constructs. - -A message [derived from a transaction][asmessage_link] will carry that transaction in a field accessible via its [`UnderlyingTransaction`][underlying_link] method. While this is related to the way a given message is used, they are not one-to-one. The table below shows the various run modes and whether each could have an underlying transaction. - -| Run Mode | Scope | Carries an Underlying Tx? | -| :--------------------------------------- | :---------------------- | :----------------------------------------------------------------------------------------------------------- | -| [`MessageCommitMode`][mc0] | state transition   | always | -| [`MessageGasEstimationMode`][mc1]   | gas estimation | when created via [NodeInterface](/build-decentralized-apps/nodeinterface/02-reference.mdx) or when scheduled | -| [`MessageEthcallMode`][mc2] | eth_calls | never | - -[mc0]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L654 -[mc1]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L655 -[mc2]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L656 -[geth_message_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L634 -[txrunmode_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L701 -[set_run_mode_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/internal/ethapi/api.go#L955 -[asmessage_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L676 -[underlying_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go#L700 - -## Arbitrum Chain Parameters - -Nitro's Geth may be configured with the following [l2-specific chain parameters][chain_params_link]. These allow the rollup creator to customize their rollup at genesis. - -### `EnableArbos` - -Introduces [ArbOS](/how-arbitrum-works/arbos/introduction.mdx), converting what would otherwise be a vanilla L1 chain into an L2 Arbitrum rollup. - -### `AllowDebugPrecompiles` - -Allows access to debug precompiles. Not enabled for Arbitrum One. When false, calls to debug precompiles will always revert. - -### `DataAvailabilityCommittee` - -Currently does nothing besides indicate that the rollup will access a data availability service for preimage resolution in the future. This is not enabled for Arbitrum One, which is a strict state-function of its L1 inbox messages. - -[chain_params_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/params/config_arbitrum.go#L25 - -## Miscellaneous Geth Changes - -### ABI Gas Margin - -Vanilla Geth's abi library submits txes with the exact estimate the node returns, employing no padding. This means a transaction may revert should another arriving just before even slightly change the transaction's codepath. To account for this, we've added a `GasMargin` field to `bind.TransactOpts` that [pads estimates][pad_estimates_link] by the number of basis points set. - -### Conservation of L2 ETH - -The total amount of L2 ether in the system should not change except in controlled cases, such as when bridging. As a safety precaution, ArbOS checks Geth's [balance delta][conservation_link] each time a block is created, [alerting or panicking][alert_link] should conservation be violated. - -### MixDigest and ExtraData - -To aid with [outbox proof construction][proof_link], the root hash and leaf count of ArbOS's [send merkle accumulator][merkle_link] are stored in the `MixDigest` and `ExtraData` fields of each L2 block. The yellow paper specifies that the `ExtraData` field may be no larger than 32 bytes, so we use the first 8 bytes of the `MixDigest`, which has no meaning in a system without miners/stakers, to store the send count. - -### Retryable Support - -Retryables are mostly implemented in [ArbOS](/how-arbitrum-works/arbos/introduction.mdx#retryables). Some modifications were required in Geth to support them. - -- Added ScheduledTxes field to ExecutionResult. This lists transactions scheduled during the execution. To enable using this field, we also pass the ExecutionResult to callers of ApplyTransaction. -- Added gasEstimation param to DoCall. When enabled, DoCall will also also executing any retryable activated by the original call. This allows estimating gas to enable retryables. - -### Added accessors - -Added [`UnderlyingTransaction`][underlyingtransaction_link] to Message interface -Added [`GetCurrentTxLogs`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state/statedb_arbitrum.go) to StateDB -We created the AdvancedPrecompile interface, which executes and charges gas with the same function call. This is used by [Arbitrum's precompiles](/build-decentralized-apps/precompiles/01-overview.mdx), and also wraps Geth's standard precompiles. - -### WASM build support - -The WASM Arbitrum executable does not support file operations. We created [`fileutil.go`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/rawdb/fileutil.go) to wrap fileutil calls, stubbing them out when building WASM. [`fake_leveldb.go`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/ethdb/leveldb/fake_leveldb.go) is a similar WASM-mock for leveldb. These are not required for the WASM block-replayer. - -### Types - -Arbitrum introduces a new [`signer`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/arbitrum_signer.go), and multiple new [`transaction types`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/types/transaction.go). - -### ReorgToOldBlock - -Geth natively only allows reorgs to a fork of the currently-known network. In nitro, reorgs can sometimes be detected before computing the forked block. We added the [`ReorgToOldBlock`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/blockchain_arbitrum.go#L38) function to support reorging to a block that's an ancestor of current head. - -### Genesis block creation - -Genesis block in nitro is not necessarily block #0. Nitro supports importing blocks that take place before genesis. We split out [`WriteHeadBlock`][writeheadblock_link] from genesis.Commit and use it to commit non-zero genesis blocks. - -[pad_estimates_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/accounts/abi/bind/base.go#L355 -[conservation_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state/statedb.go#L42 -[alert_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/block_processor.go#L424 -[proof_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/system_tests/outbox_test.go#L26 -[merkle_link]: https://github.com/OffchainLabs/nitro/blob/8e786ec6d1ac3862be85e0c9b5ac79cbd883791c/arbos/merkleAccumulator/merkleAccumulator.go#L13 -[underlyingtransaction_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state_transition.go#L69 -[writeheadblock_link]: https://github.com/OffchainLabs/go-ethereum/blob/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/genesis.go#L415 diff --git a/arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.mdx b/arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.mdx deleted file mode 100644 index a7aae98db..000000000 --- a/arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 'L2 to L1 messaging and the outbox' -description: This concept page provides information about how arbitrary messages are passed from L2 to L1 -target_audience: developers who want to build on Arbitrum -content_type: concept ---- - -Arbitrum's Outbox system allows for arbitrary L2 to L1 contract calls; i.e., messages initiated from L2 which eventually resolve in execution on L1. L2-to-L1 messages (aka "outgoing" messages) bear many things in common with Arbitrum's [L1-to-L2 messages](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) (Retryables), "in reverse" though with a few differences. - -### Protocol Flow - -Part of the L2 state of an Arbitrum chain — and consequently, part of what's asserted in every RBlock — is a Merkle root of all L2-to-L1 messages in the chain's history. Upon an asserted RBlock being confirmed (typically ~1 week after its asserted), this Merkle root is posted on L1 in the `Outbox` contract. The Outbox contract then lets users execute their messages — validating Merkle proofs of inclusion, and tracking which L2 to L1 messages have already been spent. - -### Client Flow - -From a client perspective, an L2 to L1 message begins with a call to the L2 [`ArbSys`](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) precompile contract's `sendTxToL1` method. Once the message is included in an assertion (typically within ~1 hour) and the assertion is confirmed (typically about ~ 1 week), any client can execute the message. To do this, the client first retrieves the proof data via a call to the Arbitrum chain's "virtual"/precompile-esque\*\* `NodeInterface` contract's `constructOutboxProof` method. The data returned can then be used in the `Outbox`'s `executeTransaction` method to perform the L1 execution. - -### Protocol Design Details - -An important feature in the design of the Outbox system is that calls to `confirmNode` have constant overhead. Requiring that `confirmNode` only update the constant-sized outgoing message root hash, and that users themselves carry out the final step of execution, achieves this goal; i.e., no matter the number of outgoing messages in the root, or the gas cost of executing them on L1, the cost of confirming nodes remains constant; this ensures that the RBlock confirmation processed can't be griefed. - -Unlike Retryables, which have an option to provide Ether for automatic L2 execution, outgoing messages can't provide in-protocol automatic L1 execution, for the simple reason that Ethereum itself doesn't offer scheduled execution affordances. However, application-layer contracts that interact with the Outbox could in principle be built to provide somewhat-analogous "execution market" functionality for outsourcing the final L1 execution step. - -Another difference between outgoing messages and Retryables is that Retryables have a limited lifetime before which they must be redeemed (or have their lifetime explicitly extended), whereas L2 to L1 messages are stored in L1 state, and thus persist permanently / have no deadline before which they must be executed. -The week long delay period before outgoing messages can be executed is inherent and fundamental to the nature of Arbitrum Rollup, or any Optimistic Rollup style L2; the moment a transaction is published on-chain, any observer can anticipate its result; however, for Ethereum itself to accept its result, the protocol must give time for Arbitrum validators to detect and prove fault if need-be. For a protocol overview, see [Inside Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.mdx) - -\*\* We refer to `NodeInterface` as a "virtual" contract; its methods are accessible via calls `0x00000000000000000000000000000000000000C8`, but it doesn't really live on chain. It isn't really a precompile, but behaves a lot like a precompile that can't receive calls from other contracts. This is a cute trick that let's us provide Arbitrum-specific data without having to implement a custom RPC. diff --git a/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.mdx index e4c912339..5488e22ef 100644 --- a/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.mdx +++ b/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.mdx @@ -17,7 +17,7 @@ BoLD will eventually replace the current, permissioned fraud proof mechanism tha ## In a nutshell: - Validation for Arbitrum One and Arbitrum Nova is a privileged action currently limited to an [allow-listed set of parties, maintained by the Arbitrum DAO](https://docs.arbitrum.foundation/state-of-progressive-decentralization#allowlisted-validators) to reduce the risks of _[delay attacks](https://medium.com/offchainlabs/solutions-to-delay-attacks-on-rollups-434f9d05a07a)_. _Delay attacks_ are a class of attacks where malicious entities can open as many disputes as they are willing to forfeit bonds during the challenge period to delay confirmations of assertions (equal to the time needed to resolve those disputes one by one). -- BoLD, an acronym for Bounded Liquidity Delay, is a new challenge resolution protocol for Arbitrum chains that enables permissionless validation by mitigating the risks of delay attacks against [optimistic rollups like Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.mdx#arbitrum-rollup-protocol). This is possible because BoLD's design ensures disputes will be resolved within a fixed time window, currently set to equal 1 challenge period (~6.4 days) for Arbitrum One and Arbitrum Nova. If there is a dispute, BoLD guarantees the maximum total time to be equal to 2 challenge periods (1 for raising disputes, 1 for resolving disputes), a 2 day grace period for the Security Council to intervene if necessary, and a small delta for computing challenges. +- BoLD, an acronym for Bounded Liquidity Delay, is a new challenge resolution protocol for Arbitrum chains that enables permissionless validation by mitigating the risks of delay attacks against [optimistic rollups like Arbitrum](/how-arbitrum-works/06-optimistic-rollup.mdx). This is possible because BoLD's design ensures disputes will be resolved within a fixed time window, currently set to equal 1 challenge period (~6.4 days) for Arbitrum One and Arbitrum Nova. If there is a dispute, BoLD guarantees the maximum total time to be equal to 2 challenge periods (1 for raising disputes, 1 for resolving disputes), a 2 day grace period for the Security Council to intervene if necessary, and a small delta for computing challenges. - Enabling permissionless validation is key milestone on [Arbitrum’s journey to becoming a Stage 2 Rollup](https://docs.arbitrum.foundation/state-of-progressive-decentralization) - the most advanced and mature rollup technology categorization, according to [L2Beat](https://medium.com/l2beat/introducing-stages-a-framework-to-evaluate-rollups-maturity-d290bb22befe). With BoLD, **any honest party can validate and bond their funds to post a correct L2 state assertions to win disputes against malicious entities.** - BoLD is currently considered to be in `alpha` release and is deployed on a public testnet. [Follow this guide](https://github.com/OffchainLabs/BoLD-validator-starter-kit) to deploy a BoLD validator to test and explore, first hand, how BoLD works to secure Arbitrum chains. To learn more about BoLD, please check out the [BoLD whitepaper](https://arxiv.org/abs/2404.10491) and [BoLD's code and specifications on Github](https://github.com/OffchainLabs/BoLD). @@ -70,9 +70,9 @@ The BoLD protocol provides the guardrails and rules for how validators challenge Let’s dive in to an overview of how BoLD actually works. -1. **An assertion is made:** Validators begin by taking the most recent confirmed [RBlock](/how-arbitrum-works/inside-arbitrum-nitro.mdx#the-rollup-chain), called `Block A`, and assert that some number of transactions afterwards, 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 be posted to Ethereum. If nobody disagrees after a certain amount of time, known as the challenge period, then the state represented by the RBlock `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. This is where BoLD comes into play. +1. **An assertion is made:** Validators begin by taking the most recent confirmed [RBlock](/how-arbitrum-works/06-optimistic-rollup.mdx#the-rollup-chain), called `Block A`, and assert that some number of transactions afterwards, 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 be posted to Ethereum. If nobody disagrees after a certain amount of time, known as the challenge period, then the state represented by the RBlock `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. This is where BoLD comes into play. 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 RBlock `Block Y`. At this point in time, there are now 2 asserted states: `Block A → Block Z` and `Block A → Block Y`. Each of these asserted states, at this point in time now that there's a challenge, are referred to _edges_ while a Merkle tree of asserted states from some start to end point (e.g. `Block A → Block Z`) is more formally known as a _history commitment._ It is important to note that Ethereum at this point in time has no notion of which edge(s) is 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 tied to an assertion rather than the party who 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 the bonds put up to open challenges are held in a Gnosis Safe multi-sig wallet controlled by the Arbitrum Foundation. -3. **Multi-level, interactive dissection begins:** To resolve the dispute, the disagreeing entities will need to come to an agreement on what the _actual, correct_ asserted state should be. [It would be tremendously expensive to re-execute](/how-arbitrum-works/inside-arbitrum-nitro.mdx#why-interactive-proving-is-better) 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, like Ethereum, can declare a winner. Note that [this system is very similar to how challenges are resolved on Arbitrum chains today](/how-arbitrum-works/inside-arbitrum-nitro.mdx#challenges) - 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 come to an agreement on what the _actual, correct_ asserted state should be. [It would be tremendously expensive to re-execute](/how-arbitrum-works/06-optimistic-rollup.mdx#why-interactive-proving-is-better) 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, like Ethereum, can declare a winner. Note that [this system is very similar to how challenges are resolved on Arbitrum chains today](/how-arbitrum-works/07-interactive-fraud-proofs.mdx) - BoLD only changes some minor, but important, details in the resolution process. Let’s dive into what happens next: 1. **Block challenges**: when a challenge is opened, the edges are called _level-zero edges_ since they are at the granularity of Arbitrum blocks. The disputing parties take turns bisecting their history commitments until they identify the specific block that they disagree on. 2. **Big-step challenge:** now that the parties have narrowed down their dispute to a single block, that we call `Block B`, the back-and-forth bisection exercise continues within that block. Note that `Block B` is claimed by all parties to be some state after the initial state `Block A` but before the final states `Block Z` and `Block Y`. 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. This range is currently defined as 2^20 steps of WASM instructions, which is the assembly of choice for validating Arbitrum chains. 3. **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 in time, parties agree on the initial state of Arbitrum before the step but disagree on the end state 1 step immediately after. Remember that since Arbitrum’s state is entirely deterministic, there is only 1 correct end state. diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/challenge-manager.mdx b/arbitrum-docs/how-arbitrum-works/fraud-proofs/challenge-manager.mdx deleted file mode 100644 index 407347853..000000000 --- a/arbitrum-docs/how-arbitrum-works/fraud-proofs/challenge-manager.mdx +++ /dev/null @@ -1,64 +0,0 @@ -import ChallengeManagerDiagram from '../../diagrams/_challenge-manager.mdx'; - -# ChallengeManager - -The `ChallengeManager` arbitrates challenge games. Here's a diagram of the challenge state machine: - - - -## Block challenge - -The challenge begins by bisecting over global states (including block hashes). -Before actual machine execution is disputed, the dispute is narrowed down to an individual block. -Once the challenge has been bisected down to an individual block, -`challengeExecution` can be called by the current responder. -This operates similarly to a bisection in that the responder must provide a competing global state and machine state, -but it uses that information to transition to the execution challenge phase. - -## Execution challenge - -Once narrowed down to an individual block, the actual machine execution can be bisected. -Once the execution has been bisected down to an individual step, -`oneStepProveExecution` can be called by the current responder. -The current responder must provide proof data to execute a step of the machine. -If executing that step ends in a different state than was previously asserted, -the current responder wins the challenge. - -## General bisection protocol - -_**Note:** the term bisection in this document is used for clarity but refers to a dissection of any degree._ - -The `ChallengeLib` helper library contains a `hashChallengeState` method which hashes a list of segment hashes, -a start position, and a total segments length, which generates the `ChallengeLib.Challenge`'s `challengeStateHash`. -This is enough information to infer the position of each segment hash. -The challenge "degree" refers to the number of segment hashes minus one. -The distance (in steps) between one segment and the next is `floor(segmentsLength / degree)`, except for the -last pair of segments, where `segmentsLength % degree` is added to the normal distance, so that -the total distance is `segmentsLength`. - -A challenge begins with only two segments (a degree of one), which is the asserter's initial assertion. -Then, the bisection game begins on the challenger's turn. -In each round of the game, the current responder must choose an adjacent pair of segments to challenge. -By doing so, they are disputing their opponent's claim that starting with the first segment and executing -for the specified distance (number of steps) will result in the second segment. At this point the two parties -agree on the correctness of the first segment but disagree about the correctness of the second segment. -The responder must provide a bisection with a start segment equal to the first segment, but an end segment -different from the second segment. -In doing so, they break the challenge down into smaller distances, and it becomes their opponent's turn. -Each bisection must have degree `min(40, numStepsInChallengedSegment)`, ensuring the challenge makes progress. - -In addition, a segment with a length of only one step cannot be bisected. -What happens there is specific to the phase of the challenge, as either a `challengeExecution` or `oneStepProveExecution`. - -Note that unlike in a traditional bisection protocol, where one party proposes segments and the other decides which to challenge, -this protocol is symmetric in that both players take turns deciding where to challenge and proposing bisections -when challenging. - -## Winning the challenge - -Note that for the time being, winning the challenge isn't instant. -Instead, it simply makes the current responder the winner's opponent, -and sets the state hash to 0. In that state the party does not have any -valid moves, so it will eventually lose by timeout. -This is done as a precaution, so that if a challenge is resolved incorrectly, -there is time to diagnose and fix the error with a contract upgrade. diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/osp-assumptions.mdx b/arbitrum-docs/how-arbitrum-works/fraud-proofs/osp-assumptions.mdx deleted file mode 100644 index 93e04a2d1..000000000 --- a/arbitrum-docs/how-arbitrum-works/fraud-proofs/osp-assumptions.mdx +++ /dev/null @@ -1,75 +0,0 @@ -# One Step Proof Assumptions - -The One Step Proof (OSP) implementation makes certain assumptions about the cases that can arise -in a correct execution. This documents those assumptions about what's being executed. - -If a case is "unreachable", that is, the case is assumed to never arise in correct execution, -then the OSP can implement any instruction semantics in that case. - -- In a challenge between malicious parties, any case can arise. The challenge protocol must do - something safe in every case. But the instruction semantics can be weird in such cases because - if both parties to a challenge are malicious, the protocol doesn't care who wins the challenge. -- In a challenge with one honest party, the honest party will never need to one-step prove an - unreachable case. The honest party will only assert correct executions, so it will only have to - prove reachable cases. -- In a challenge with one honest party, the dishonest party could assert an execution that transitions - into an unreachable case, but such an execution must include an invalid execution of a reachable case - earlier in the assertion. Because a challenge involving an honest party will eventually require an OSP - over the first instruction where the parties disagree, the eventual OSP will be over the earlier point - of divergence, and not over the later execution from an unreachable case. - -In general, some unreachable cases will be detectable by the OSP checker and some will not. For safety, the -detectable unreachable cases should be defined by transition the machine into an error state, allowing -governance to eventually push an upgrade to recover from the error. An undetectable unreachable case, if -such a case were reached in correct execution, could lead to a security failure. - -The following assumptions, together, must prevent an unreachable case from arising in correct execution. - -## The WAVM code is generated by Arbitrator from valid WASM - -WAVM is the name of the custom instruction set similar to WASM used for proving. -Arbitrator transpiles WASM code into WAVM. -It also invokes wasm-validate from [wabt](https://github.com/WebAssembly/wabt) -(the WebAssembly Binary Toolkit) to ensure the input WASM is valid. -WAVM produced otherwise may not be executable, as it may try to close a non-existent block, -mismatch types, or do any other number of invalid things which are prevented by WASM validation. - -WAVM code generated from by Arbitrator from valid WASM is assumed to never encounter an unreachable case. - -## Inbox messages must not be too large - -The current method of inbox hashing requires the full inbox message be available for proving. -That message must not be too large as to prevent it from being supplied for proving, -which is enforced by the inboxes. - -The current length limit is 117,964 bytes, which is 90% of the -[max transaction size Geth will accept](https://github.com/ethereum/go-ethereum/blob/356bbe343a30789e77bb38f25983c8f2f2bfbb47/core/tx_pool.go#L53), -leaving 13,108 bytes for other proving data. - -## Requested preimages must be known and not too large - -WAVM has an opcode which resolves the preimage of a Keccak-256 hash. -This can only be executed if the preimage is already known to all nodes, -and can only be proven if the preimage isn't too long. Violations of this assumption are -undetectable by the OSP checker. - -The current length limit is 117,964 bytes for the reasons mentioned above. -Here's a list of which preimages may be requested by Nitro, and why they're known to all parties, -and not too large: - -### Block headers - -Nitro may request up to the last 256 L2 block headers. -The last block header is required to determine the current state, -and blocks before it are required to implement the `BLOCKHASH` evm instruction. - -This is safe as previous block headers are a fixed size, and are known to all nodes. - -### State trie access - -To resolve state, Nitro traverses the state trie by resolving preimages. - -This is safe as validators retain archive state of unconfirmed blocks, -each trie branch is of a fixed size, -and the only variable sized entry in the trie is contract code, -which is limited by EIP-170 to about 24KB. diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx deleted file mode 100644 index 941fefb5a..000000000 --- a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx +++ /dev/null @@ -1,61 +0,0 @@ -# WASM to WAVM - -Not all WASM instructions are 1:1 with WAVM opcodes. -This document lists those which are not, and explains how they're expressed in WAVM. -Many of the WAVM representations use opcodes not in WASM, -which are documented in [`wavm-custom-opcodes.mdx`](/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx). - -## `block` and `loop` - -In WASM, a block contains instructions. -Branch instructions exit a fixed number of blocks, jumping to their destination. -A normal `block`'s destination is the end of the block, whereas a `loop`'s destination is the start of the loop. - -In WAVM, instructions are flat. -At transpilation time, any branch instructions are replaced with jumps to the corresponding block's destination. -This means that WAVM interpreters don't need to track blocks, and thus block instructions are unnecessary. - -## `if` and `else` - -These are translated to a block with an `ArbitraryJumpIf` as follows: - -``` -begin block with endpoint end - conditional jump to else - [instructions inside if statement] - branch - else: [instructions inside else statement] -end -``` - -## `br` and `br_if` - -`br` and `br_if` are translated into `ArbitraryJump` and `ArbitraryJumpIf` respectively. -The jump locations can be known at transpilation time, making blocks obsolete. - -## `br_table` - -`br_table` is translated to a check for each possible branch in the table, -and then if none of the checks hit, a branch of the default level. - -Each of the non-default branches has a conditional jump to a section afterwards, -containing a `drop` for the selector, and then a jump to the target branch. - -## `local.tee` - -`local.tee` is translated to a WAVM `Dup` and then a `LocalSet`. - -## `return` - -To translate a return, the number of return values must be known from the function signature. -A WAVM `MoveFromStackToInternal` is added for each return value. -Then, a loop checks `IsStackBoundary` (which implicitly pops a value) until it's true and the stack boundary has been popped. -Next, a `MoveFromInternalToStack` is added for each return value to put the return values back on the stack. -Finally, a WAVM `Return` is added, returning control flow to the caller. - -## Floating point instructions - -A floating point library module must be present to translate floating point instructions. -They are translated by bitcasting `f32` and `f64` arguments to `i32`s and `i64`s, -then a cross module call to the floating point library, -and finally bitcasts of any return values from `i32`s and `i64`s to `f32`s and `f64`s. diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx deleted file mode 100644 index bbf75c3b6..000000000 --- a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx +++ /dev/null @@ -1,74 +0,0 @@ -# WAVM Custom opcodes not in WASM - -In addition to the MVP WASM specification, -WAVM implements the multi value and sign extension ops WASM proposals. - -WAVM also implements the following unique opcodes, -which are not part of WASM nor any WASM proposal. - -## Invariants - -Many of these opcodes have implicit invariants about what's on the stack, -e.g. "Pops an i32 from the stack" assumes that the top of the stack has an i32. -If these conditions are not satisfied, execution is generally not possible. -These invariants are maintained by WASM validation and Arbitrator codegen. (See [One Step Proof Assumptions](/how-arbitrum-works/fraud-proofs/osp-assumptions.mdx).) - -## Codegen internal - -These are generated when breaking down a WASM instruction that does many things into many WAVM instructions which each do one thing. -For instance, a WASM `local.tee` is implemented in WAVM with `dup` and then `local.set`, the former of which doesn't exist in WASM. - -Other times, these opcodes help out an existing WASM opcode by splitting out functionality. -For instance, the WAVM `return` opcode by itself does not clean up the stack, -but its WASM->WAVM codegen includes a loop that utilizes `IsStackBoundary` to perform the stack cleanup -specified for WASM's `return`. - -| Opcode | Name | Description | -| ------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 0x8000 | EndBlock | Pops an item from the block stack. | -| 0x8001 | EndBlockIf | Peeks the top value on the stack, assumed an i32. If non-zero, pops an item from the block stack. | -| 0x8002 | InitFrame | Pops a caller module index i32, then a caller module internals offset i32, and finally a return InternalRef from the stack. Creates a stack frame with the popped info and the locals merkle root in proving argument data. | -| 0x8003 | ArbitraryJumpIf | Pops an i32 from the stack. If non-zero, jumps to the program counter in the argument data. | -| 0x8004 | PushStackBoundary | Pushes a stack boundary to the stack. | -| 0x8005 | MoveFromStackToInternal | Pops an item from the stack and pushes it to the internal stack. | -| 0x8006 | MoveFromInternalToStack | Pops an item from the internal stack and pushes it to the stack. | -| 0x8007 | IsStackBoundary | Pops an item from the stack. If a stack boundary, pushes an i32 with value 1. Otherwise, pushes an i32 with value 0. | -| 0x8008 | Dup | Peeks an item from the stack and pushes another copy of that item to the stack. | - -The above opcodes eliminate the need for the following WASM opcodes (which are transpiled into other WAVM opcodes): - -- loop -- if/else -- br_table -- local.tee - -## Linking - -This is only generated to link modules together. -Each import is replaced with a local function consisting primarily of this opcode, -which handles the actual work needed to change modules. - -| Opcode | Name | Description | -| ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 0x8009 | CrossModuleCall | Pushes the current program counter, module number, and module's internals offset to the stack. Then splits its argument data into the lower 32 bits being a function index, and the upper 32 bits being a module index, and jumps to the beginning of that function. | - -## Host calls - -These are only used in the implementation of "host calls". -Each of these has an equivalent host call method, which can be invoked from libraries. -The exception is `CallerModuleInternalCall`, -which is used for the implementation of all of the `wavm_caller_*` host calls. -Those calls are documented in `wavm-modules.mdx`. - -For these instruction descriptions, all pointers and offsets are represented as WASM i32s. - -| Opcode | Name | Description | -| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 0x800A | CallerModuleInternalCall | Pushes the current program counter, module number, and module's internals offset (all i32s) to the stack. Then, it retrieves the caller module internals offset from the current stack frame. If 0, errors, otherwise, jumps to the caller module at function (internals offset + opcode argument data) and instruction 0. | -| 0x8010 | GetGlobalStateBytes32 | Pops a pointer and then an index from the stack. If the index is greater than or equal to the number of global state bytes32s, errors. If the pointer mod 32 is not zero, errors. If the pointer + 32 is outside the programs memory, errors. Otherwise, writes the global state bytes32 value of the specified index to the specified pointer in memory. | -| 0x8011 | SetGlobalStateBytes32 | Pops a pointer and then an index from the stack. If the index is greater than or equal to the number of global state bytes32s, errors. If the pointer mod 32 is not zero, errors. If the pointer + 32 is outside the programs memory, errors. Otherwise, reads a bytes32 from the specified pointer in memory and sets the global state bytes32 value of the specified index to it. | -| 0x8012 | GetGlobalStateU64 | Pops a pointer and then an index from the stack. If the index is greater than or equal to the number of global state u64s, errors. If the pointer mod 32 is not zero, errors. If the pointer + 8 is outside the programs memory, errors. Otherwise, writes the global state u32 value of the specified index to the specified pointer in memory. | -| 0x8013 | SetGlobalStateU64 | Pops a pointer and then an index from the stack. If the index is greater than or equal to the number of global state u64s, errors. If the pointer mod 32 is not zero, errors. If the pointer + 8 is outside the programs memory, errors. Otherwise, reads a u64 from the specified pointer in memory and sets the global state u64 value of the specified index to it. | -| 0x8020 | ReadPreImage | Pops an offset and then a pointer from the stack. If the pointer mod 32 is not zero, errors. If the pointer + 32 is outside the programs memory, errors. Reads a 32 byte Keccak-256 hash from the specified pointer in memory. Writes up to 32 bytes of the preimage to that hash, beginning with the `offset` byte of the preimage. If `offset` is greater than or equal to the number of bytes in the preimage, writes nothing. Pushes the number of bytes written to the stack as an i32. | -| 0x8021 | ReadInboxMessage | Pops an offset, then a pointer, and then an i64 message number from the stack. If the pointer mod 32 is not zero, errors. If the pointer + 32 is outside the programs memory, errors. Attempts to read an inbox message from the inbox identifier contained in the argument data (0 for the sequencer inbox, 1 for the delayed inbox) at the specified message number. If this exceeds the machine's inbox limit, enters the "too far" state. Otherwise, writes up to 32 bytes of the specified inbox message, beginning with the `offset` byte of the message. If `offset` is greater than or equal to the number of bytes in the preimage, writes nothing. Pushes the number of bytes written to the stack as an i32. | -| 0x8022 | HaltAndSetFinished | Sets the machine status to finished, halting execution and marking it as a success. | diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-floats.mdx b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-floats.mdx deleted file mode 100644 index 1431c5b06..000000000 --- a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-floats.mdx +++ /dev/null @@ -1,32 +0,0 @@ -# WAVM Floating point implementation - -Implementing correct, consistent, and deterministic floating point operations directly in WAVM -(meaning both a Rust Arbitrator implementation and Solidity OSP implementation) -would be an extremely tricky endeavor. -WASM specifies floating point operations as being compliant to IEEE 754-2019, -which is not deterministic, and full of edge cases. - -Instead, floating point operations (apart from trivial bit-casts like i32 \<-\> f32) -are implemented using the C Berkeley SoftFloat-3e library running inside WAVM. -Arbitrator links other WAVM guests against this, -by replacing float point operations with cross module calls to the library. - -Berkeley SoftFloat does not implement all necessary floating point operations, however. -Most importantly, it does not provide a min function, despite IEEE 754-2019 specifying one. -The implementation of these operations, -along with the export of convenient APIs for WASM opcode implementations, -are contained in bindings32.c for 32 bit integers and bindings64.c for 64 bit integers. - -This ensures that floating point operations are deterministic and consistent between Arbitrator and the OSP, -as they are implemented exclusively using operations already known to be deterministic and consistent. -However, it does not ensure that the floating point operations are perfectly compliant to the WASM specification. -Go uses floating points in its JS\<-\>Go WASM interface, -and floating points may be used outside core state transition code for imprecise computations, -but the former is well exercised as used in Nitro, -and the latter generally doesn't rely on details like the minimum of NaN and infinity. - -## Known divergences from the WASM specification - -Floating point to integer truncation will saturate on overflow, instead of erroring. -This is generally safer, because on x86, overflowing simply produces an undefined result. -A WASM proposal exists to add new opcodes which are defined to saturate, but it's not widely adopted. diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-modules.mdx b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-modules.mdx deleted file mode 100644 index 1bace30e4..000000000 --- a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-modules.mdx +++ /dev/null @@ -1,57 +0,0 @@ -# WAVM Modules - -WASM natively has a notion of modules. -Normally, in WASM, a module is the entire program. -A `.wasm` file represents one module, and generally they aren't combined. -An exception to this is C compiled via Clang, where wasm files are also used as object files, -but [its linking scheme](https://github.com/WebAssembly/tool-conventions/blob/main/Linking.mdx) is not supported in other languages. - -In WAVM this is extended to make the executing program composed of multiple modules. -These may call each other, and library modules may write to their caller's memory to return results. - -## The entrypoint module - -The entrypoint module is where execution begins. -It calls modules' `start` functions if specified, -and then calls the main module's main function, which is language specific. -For Go it sets argv to `["js"]` to match the JS environment, and calls `run`. -For Rust it calls `main` with no arguments. - -## Library exports - -Libraries may export functions with the name pattern `module__name`, -which future libraries or the main module can import as `"module" "name"`. - -For instance, this is used for wasi-stub to provide functions rust imports according -to the WebAssembly System Interface. - -## Floating point operations - -To provide floating point operations for future libraries, -the soft float library exports functions which perform floating point ops. -These have the same name as the WASM instruction names, except `.` is replaced with `_`. -Their type signature is also the same, except all `f32`s and `f64`s are bitcasted to `i32`s and `i64`s. - -Future modules can implicitly use these by using WASM floating point operations, -which are replaced at the WASM->WAVM level with bitcasts and cross module calls to these functions. - -## WAVM guest calls - -Libraries may call the main module's exports via `"env" "wavm_guest_call__*"`. - -For instance, go-stub calls Go's resume function when queueing async events -via `wavm_guest_call_resume()`, and then retrieves the new stack pointer with -`wavm_guest_call_getsp()`. - -## Caller module internals call - -Every stack frame retains its caller module and its caller module's "internals offset", -which is the first internal function index. -WAVM appends 4 "internal" functions to each module, which perform a memory load or store of 1 or 4 bytes. - -Via `wavm_caller_{load,store}{8,32}`, a library may access its caller's memory, -which is implemented by calling these internal functions of the caller's module. -Only libraries can access their caller's memory; the main module cannot. - -For instance, this is used to read arguments from and write return values to the Go stack, -when Go calls into go-stub. diff --git a/arbitrum-docs/how-arbitrum-works/gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/gas-fees.mdx deleted file mode 100644 index 1d8e8df99..000000000 --- a/arbitrum-docs/how-arbitrum-works/gas-fees.mdx +++ /dev/null @@ -1,36 +0,0 @@ ---- -author: dzgoldman ---- - -# Gas and Fees - -There are two parties a user pays when submitting a tx: - -- the poster, if reimbursable, for L1 resources such as the L1 calldata needed to post the tx -- the network fee account for L2 resources, which include the computation, storage, and other burdens L2 nodes must bear to service the tx - -The L1 component is the product of the transaction's estimated contribution to its batch's size — computed using Brotli on the transaction by itself — and the L2's view of the L1 data price, a value which dynamically adjusts over time to ensure the batch-poster is ultimately fairly compensated. For details, see [L1 Pricing](/how-arbitrum-works/l1-gas-pricing.mdx). - -The L2 component consists of the traditional fees Geth would pay to stakers in a vanilla L1 chain, such as the computation and storage charges applying the state transition function entails. ArbOS charges additional fees for executing its L2-specific [precompiles](/build-decentralized-apps/precompiles/01-overview.mdx), whose fees are dynamically priced according to the specific resources used while executing the call. - -## Gas Price Floor - -The L2 gas price on a given Arbitrum chain has a set floor, which can be queried via [ArbGasInfo](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo)'s `getMinimumGasPrice` method (currently @arbOneGasFloorGwei@ gwei on Arbitrum One and @novaGasFloorGwei@ gwei on Nova). - -## Estimating Gas - -Calling an Arbitrum Node's `eth_estimateGas` RPC gives a value sufficient to cover the full transaction fee at the given L2 gas price; i.e., the value returned from `eth_estimateGas` multiplied by the L2 gas price tells you how much total Ether is required for the transaction to succeed. Note that this means that for a given operation, the value returned by `eth_estimateGas` will change over time (as the L1 calldata price fluctuates.) (See [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and [How to estimate gas in Arbitrum](/build-decentralized-apps/02-how-to-estimate-gas.mdx) for more.) - -## Tips in L2 - -The sequencer prioritizes transactions on a first-come first-served basis. Because tips do not make sense in this model, they are ignored. Arbitrum users always just pay the basefee regardless of the tip they choose. - -## Gas Estimating Retryables - -When a transaction schedules another, the subsequent transaction's execution [will be included][estimation_inclusion_link] when estimating gas via the node's RPC. A transaction's gas estimate, then, can only be found if all the transactions succeed at a given gas limit. This is especially important when working with retryables and scheduling redeem attempts. - -Because a call to [`redeem`](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) donates all of the call's gas, doing multiple requires limiting the amount of gas provided to each subcall. Otherwise the first will take all of the gas and force the second to necessarily fail irrespective of the estimation's gas limit. - -Gas estimation for Retryable submissions is possible via the [NodeInterface](/build-decentralized-apps/nodeinterface/02-reference.mdx) and similarly requires the auto-redeem attempt to succeed. - -[estimation_inclusion_link]: https://github.com/OffchainLabs/go-ethereum/blob/d52739e6d54f2ea06146fdc44947af3488b89082/internal/ethapi/api.go#L999 diff --git a/arbitrum-docs/how-arbitrum-works/l1-gas-pricing.mdx b/arbitrum-docs/how-arbitrum-works/l1-gas-pricing.mdx deleted file mode 100644 index 042490f99..000000000 --- a/arbitrum-docs/how-arbitrum-works/l1-gas-pricing.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -author: dzgoldman ---- - -# L1 gas pricing - -ArbOS dynamically prices L1 gas, with the price adjusting to ensure that the amount collected in L1 gas fees is as close as possible to the costs that must be covered, over time. - -## L1 fee collection - -A transaction is charged for L1 gas if and only if it arrived as part of a sequencer batch. This means that someone would have paid for L1 gas to post the transaction on the L1 chain. - -The estimated cost of posting a transaction on L1 is the product of the transaction's estimated size, and the current L1 Gas Basefee. This estimated cost is divided by the current L2 gas basefee to obtain the amount of L2 gas that corresponds to the L1 operation (more information about this can be found in [this article][two_dimensional_fees_medium_article_link]). - -The estimated size is measured in L1 gas and is calculated as follows: first, compress the transaction's data using the brotli-zero algorithm, then multiply the size of the result by 16. (16 is because L1 charges 16 gas per byte. L1 charges less for bytes that are zero, but that doesn't make sense here.) Brotli-zero is used in order to reward users for posting transactions that are compressible. Ideally we would like to reward for posting transactions that contribute to the compressibility (using the brotli compressor) of the entire batch, but that is a difficult notion to define and in any case would be too expensive to compute at L2. Brotli-zero is an approximation that is cheap enough to compute. - -L1 gas fee funds that are collected from transactions are transferred to a special [`L1PricerFundsPool`][l1pricerfundspool_link] account, so that account's balance represents the amount of funds that have been collected and are available to pay for costs. - -The L1 pricer also records the total number of "data units" (the sum of the estimated sizes, after multiplying by 16) that have been received. - -[l1pricerfundspool_link]: https://github.com/OffchainLabs/nitro/blob/3f4939df1990320310e7f39e8abb32d5c4d8045f/arbos/l1pricing/l1pricing.go#L46 -[two_dimensional_fees_medium_article_link]: https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9 - -## L1 costs - -There are two types of L1 costs: batch posting costs, and rewards. - -Batch posting costs reflect the actual cost a batch poster pays to post batch data on L1. Whenever a batch is posted, the L1 contract that records the batch will send a special "batch posting report" message to L2 ArbOS, reporting who paid for the batch and what the L1 basefee was at the time. This message is placed in the chain's delayed inbox, so it will be delivered to L2 ArbOS after some delay. - -When a batch posting report message arrives at L2, ArbOS computes the cost of the referenced batch by multiplying the reported basefee by the batch's data cost. (ArbOS retrieves the batch's data from its inbox state, and computes the L1 gas that the batch would have used by counting the number of zero bytes and non-zero bytes in the batch.) The resulting cost is recorded by the pricer as funds due to the party who is reported to have submitted the batch. - -The second type of L1 cost is an optional (per chain) per-unit reward for handling transaction calldata. In general the reward might be paid to the sequencer, or to members of the Data Availability Committee in an AnyTrust chain, or to anyone else who incurs per-calldata-byte costs on behalf of the chain. The reward is a fixed number of wei per data unit, and is paid to a single address. - -The L1 pricer keeps track of the funds due to the reward address, based on the number of data units handled so far. This amount is updated whenever a batch posting report arrives at L2. - -## Allocating funds and paying what is owed - -When a batch posting report is processed at L2, the pricer allocates some of the collected funds to pay for costs incurred. To allocate funds, the pricer considers three timestamps: - -- `currentTime` is the current time, when the batch posting report message arrives at L2 -- `updateTime` is the time at which the reported batch was submitted (which will typically be around 20 minutes before currentTime) -- `lastUpdateTime` is the time at which the previous reported batch was submitted - -The pricer computes an allocation fraction `F = (updateTime-lastUpdateTime) / (currentTime-lastUpdateTime)` and allocates a fraction `F` of funds in the `L1PricerFundsPool` to the current report. The intuition is that the pricer knows how many funds have been collected between `lastUpdateTime` and `currentTime`, and we want to figure out how many of those funds to allocate to the interval between `lastUpdateTime` and `updateTime`. The given formula is the correct allocation, if we assume that funds arrived at a uniform rate during the interval between `lastUpdateTime` and `currentTime`. The pricer similarly allocates a portion of the total data units to the current report. - -Now the pricer pays out the allocated funds to cover the rewards due and the amounts due to batch posters, reducing the balance due to each party as a result. If the allocated funds aren't sufficient to cover everything that is due, some amount due will remain. If all of the amount due can be covered with the allocated funds, any remaining allocated funds are returned to the `L1PricerFundsPool`. - -## Adjusting the L1 gas basefee - -After allocating funds and paying what is owed, the L1 Pricer adjusts the L1 Gas Basefee. The goal of this process is to find a value that will cause the amount collected to equal the amount owed over time. - -The algorithm first computes the surplus (funds in the `L1PricerFundsPool`, minus total funds due), which might be negative. If the surplus is positive, the L1 Gas Basefee is reduced, so that the amount collected over a fixed future interval will be reduced by exactly the surplus. If the surplus is negative, the Basefee is increased so that the shortfall will be eliminated over the same fixed future interval. - -A second term is added to the L1 Gas Basefee, based on the derivative of the surplus (surplus at present, minus the surplus after the previous batch posting report was processed). This term, which is multiplied by a smoothing factor to reduce fluctuations, will reduce the Basefee if the surplus is increasing, and increase the Basefee if the surplus is shrinking. - -## Getting L1 fee info - -The L1 gas basefee can be queried via [`ArbGasInfo.getL1BaseFeeEstimate`](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo). To estimate the L1 fee a transaction will use, the [NodeInterface.gasEstimateComponents()](/build-decentralized-apps/nodeinterface/02-reference.mdx) or [NodeInterface.gasEstimateL1Component()](/build-decentralized-apps/nodeinterface/02-reference.mdx) method can be used. - -Arbitrum transaction receipts include a `gasUsedForL1` field, showing the amount of gas used on L1 in units of L2 gas. diff --git a/arbitrum-docs/how-arbitrum-works/sequencer.mdx b/arbitrum-docs/how-arbitrum-works/sequencer.mdx deleted file mode 100644 index 80a3d66ca..000000000 --- a/arbitrum-docs/how-arbitrum-works/sequencer.mdx +++ /dev/null @@ -1,34 +0,0 @@ -# The Sequencer and Censorship Resistance - -The Sequencer is a specially designated Arbitrum full node which, under normal conditions, is responsible for submitting users’ transactions onto L1. In principle, a chain’s Sequencer can take different forms; as [Arbitrum One currently stands](https://docs.arbitrum.foundation/state-of-progressive-decentralization), the Sequencer is a single, centralized entity; eventually, sequencing affordances could be given to a distributed committee of sequencers which come to consensus on ordering. However, regardless of its form, the Sequencer has a fundamental limitation that doesn’t apply to any other part of the system: it must operate under its own security assumptions; i.e., it can’t, in principle, derive security directly from layer 1. This brings up the question of how Arbitrum Rollup maintains its claim to censorship resistance when-and-if the Sequencer misbehaves. - -Here we will describe the mechanics of how the Sequencer typically operates, and how any user can bypass the Sequencer entirely to submit any Arbitrum transaction (including one that, say, initiates an L2 to L1 message to withdraw funds) directly from layer 1. Thus mechanism thereby preserves censorship resistance even if the Sequencer is being completely unresponsive or even malicious. - -## The Core Inbox - -When we talk about “submitting a transaction into an Arbitrum chain,” we’re talking about getting it included into the chain’s core Inbox, represented by the `sequencerInboxAccs` byte array in `Bridge`. Once transactions are included in the core Inbox, their ordering is fixed, execution is fully deterministic, and we can trustlessly treat the resultant state as having L1-level finality (see “Transaction Lifecycle”). The Sequencer’s role (or lack thereof) concerns strictly what happens prior; i.e., how a transaction makes its way into the core Inbox. We’ll break down the possible routes a transaction can take into two scenarios: a well-behaved Sequencer, and a faulty Sequencer. - -## Happy/Common Case: Sequencer Is Live and Well-behaved - -Here, we start by assuming that the Sequencer is fully operational, and is running with the intent of processing users’ transactions in as safe and timely a manner as possible. The Sequencer can receive a user’s transaction two ways — either directly via an RPC request, or via the underlying L1. - -If a user is posting a “standard” Arbitrum transaction (i.e., interacting with an L2 native dapp), the user will submit the signed transaction directly to the Sequencer, much like how a user submits a transaction to an Ethereum node when interacting with L1. Upon receiving it, the Sequencer will execute it and nearly instantaneously deliver the user a receipt. Some short time later — [usually no more than a few minutes](https://arbiscan.io/batches) — the Sequencer will include the user’s transaction in a batch and post it on L1 by calling one of the `SequencerInbox`’s `addSequencerL2Batch` methods. Note that only the Sequencer has the authority to call these methods; this assurance that no other party can include a message directly is, in fact, the very thing that gives the Sequencer the unique ability to provide instant, "soft-confirmation" receipts. -Once posted in a batch, the transactions have L1-level finality. - -Alternatively, a user can submit their L2 message to the Sequencer by posting it on the underlying L1. This path is necessary if the user wishes to perform some [L1 operation along with the L2](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) message and to preserve atomicity between the two — the textbook example here being a token deposit via a [bridge](/build-decentralized-apps/token-bridging/01-overview.mdx) (escrow on L1, mint on L2). The user does this by publishing an L1 transaction (i.e., sending a normal transaction to an L1 node) that calls one of the relevant methods on the `Inbox` contract; i.e., `sendUnsignedTransaction`. This adds a message onto what we’ll call “the delayed Inbox”, (represented by the `delayedInboxAccs` in the `Bridge` contract), which is effectively a queue that messages wait in before being moved over to the core `Inbox`. The Sequencer will emit an L2 receipt about ~10 minutes after the transaction has been included in the delayed Inbox (the reason for this delay is to minimize the risk of short term L1 reorgs which could in turn cause an L2 reorg and invalidate the Sequencer’s L2 receipts.) Again, the last step is for the Sequencer to include the L2 message in a batch — when calling the batch submission methods, the Sequencer specifies how many messages in the delayed inbox to include — finalizing the transaction. - -In sum — in either happy case, the user first delivers their message to the Sequencer, who in turn ensures that it arrives in the core Inbox. - -## Unhappy/Uncommon Case: Sequencer Isn’t Doing Its Job - -Now let’s suppose the Sequencer, for whatever reason, is entirely failing to carry out its task of submitting messages. A user can still get their transaction included in two steps: - -First, they submit their L2 message via L1 into the delayed Inbox as described above: note that although atomic cross-chain messages are the common case for using the delayed Inbox, it can in principle be used to submit _any_ L2 message. - -Once in the delayed Inbox, we obviously can’t rely on the Sequencer to include the transaction in a batch. Instead, we can use `SequencerInbox`’s `forceInclusion` method. Once a message has been in the delayed Inbox for a sufficient amount of time, `forceInclusion` can be called to move it from the delayed Inbox into the core Inbox, at which point it’s finalized. Crucially, any account can call `forceInclusion`. - -Currently, on Arbitrum One, this delay time between submission and force inclusion is roughly @arbOneForceIncludePeriodHours@ hours, as specified by `maxTimeVariation.delayBlocks` / `maxTimeVariation.delaySeconds`. A force inclusion from L1 would directly affect the state for any unconfirmed L2 transactions; keeping conservatively high delay value ensures it should only be used under extraordinary circumstances. - -On top of the delay itself, the `forceInclusion` path has the downside of uncertainty around transaction ordering; i.e., while waiting for a message's max delay to pass, a malicious Sequencer could, in principle, directly post messages in front of it. However, there’s ultimately nothing the Sequencer can do to stop it from being included in the core Inbox, at which point its ordering is finalized. - -While the slow, “unhappy” path isn’t optimal, and should rarely, if ever, be necessary, its availability as an option ensures Arbitrum Rollup always preserves its trustless security model, even if the permissioned parts of the system act faulty. diff --git a/arbitrum-docs/how-arbitrum-works/tx-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/tx-lifecycle.mdx deleted file mode 100644 index 4f8c6b4a1..000000000 --- a/arbitrum-docs/how-arbitrum-works/tx-lifecycle.mdx +++ /dev/null @@ -1,139 +0,0 @@ -# Overview: The Lifecycle of an Arbitrum Transaction - -As an introduction to the various components that compose the Arbitrum protocol, we'll go step-by-step over the phases an Arbitrum transaction goes through, starting with a client creating a signed transaction, to it ultimately being confirmed back on layer 1. - -We'll also intersperse it with "finality checks," explaining what guarantees the client has over their transaction's finality (i.e., assurances that their transaction's result is guaranteed and won't later be altered) over the course of a transaction's various stages. - -This overview will be focused on the Arbitrum Rollup protocol; see [Inside AnyTrust](/how-arbitrum-works/inside-anytrust.mdx) for differences in the Arbitrum AnyTrust protocol. Also, for convenience/simplicity, we'll be describing the security properties of the core system itself; see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization) for current decentralization status. - -For clarity on any terminology that may be unfamiliar, see our [glossary](/intro/glossary.mdx). - -### 1. Sequencer receives transaction - -Typically, a transaction's lifecycle starts with the Sequencer, the entity designated with transaction ordering, receiving a transaction from a client. The Sequencer can receive a transaction one of two ways: - -##### 1a. Directly / Offchain - -For typical transacting within the L2 environment (i.e., using an L2 native dapp), a client will connect their wallet to an L2 node and directly deliver a signed transaction. - -##### 1b. ... or from L1 (via the Delayed Inbox). - -Alternatively, a client can send a message to the Sequencer by signing and publishing an L1 transaction in the Arbitrum chain's Delayed Inbox. This functionality is most commonly used for depositing ETH or tokens via a bridge. - -**See**: - -- [Retryables](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) -- [The Sequencer](/how-arbitrum-works/sequencer.mdx) -- [Token Bridge](/build-decentralized-apps/token-bridging/01-overview.mdx) - -### 2. Sequencer orders transaction (off-chain) - -Upon receiving a transaction, the Sequencer will: - -- Order it in its off-chain Inbox -- Locally execute it using the Arbitrum Nitro VM (including collecting/allocating L1 and L2 fees, etc.) -- "Instantly" give a transaction receipt to the client ("instant" in that it doesn't require any additional on-chain confirmations, and typically takes less than a second - with the average user experiencing ~260ms). - -**See**: - -- [ArbOS](/how-arbitrum-works/arbos/introduction.mdx) -- [Geth](/how-arbitrum-works/arbos/geth.mdx) -- [L1 pricing](/how-arbitrum-works/l1-gas-pricing.mdx) / [L2 Gas](/how-arbitrum-works/gas-fees.mdx) - -#### ~ ~ ~ FINALITY CHECK: Trusted / Soft Confirmation ~ ~ ~ - -At this phase, the client's acceptance of finality relies on trusting the Sequencer. I.e., a malicious/faulty Sequencer could deviate between what it promised in the transaction receipt and what is ultimately published in a batch (see phase 3). - -:::note - -Even a malicious/faulty Sequencer can only, at worst, reorder or temporarily delay transactions; it cannot, e.g., forge a client's transaction or propose an invalid state update. Given the degree of trust in the Sequencer at phase 2, we sometimes refer to the "instant" receipt that the Sequencer provides as a "soft confirmation." - -::: - -### 3. Sequencer posts transaction in a batch (on-chain) - -The Sequencer will eventually post a batch of L2 transactions which includes our client's transaction onto the underlying L1 (as calldata); under normal conditions, the Sequencer will post batches [every few minutes](https://arbiscan.io/batches). - -##### 3a. What if the Sequencer never includes our transaction? - -Even if the Sequencer never includes our transaction in a batch, the client can include it in the L2 by posting in the delayed inbox and then "force including" it after some delay period (currently ~ @arbOneForceIncludePeriodHours@ hours on Arbitrum One). - -:::note - -The Sequencer is forced to include messages from the delayed Inbox in the queued order that they appear on chain, i.e. it processes messages using the "first in, first out" method. Thus, it can't selectively delay particular messages while including others; i.e., delaying the message at the front of the queue means delaying all messages behind it as well. - -::: - -**See:** - -- ["The Sequencer / Censorship Resistance."](/how-arbitrum-works/sequencer.mdx) - -#### ~ ~ ~ FINALITY CHECK: Ethereum-Equivalent Finality! ~ ~ ~ - -At this stage, assuming that a client believes there to be at least one well behaved active Arbitrum validator. Currently, the process of validation on the Arbitrum protocol is permissioned, but it's important to be aware that our latest dispute protocol, [BoLD (Bounded Liquidity Delay)](https://medium.com/offchainlabs/bold-permissionless-validation-for-arbitrum-chains-9934eb5328cc), has the potential to allow validation on Arbitrum chains without requiring permission, thereby potentially eliminating the necessity for restricted validation. The client can treat their transaction's finality as equivalent to an ordinary Ethereum transaction. In other words, their L2 transaction has the same finality as the L1 transaction that recorded it in a batch. This means the client should use whatever finality heuristic they use for regular Ethereum transactions (i.e., waiting on L1 block confirmations, etc.), applied to the L1 batch-posting transaction. This also means that a client uncomfortable with the trust model of the Sequencer's soft confirmations (phase 2) can simply wait for the Sequencer to post their transaction in a batch (phase 3). - -How are we able to make such bold a claim? A few (related) things: - -- Once the Sequencer posts a batch, its transactions' ordering is entirely determined by the L1; the Sequencer effectively has no more say in our transaction's lifecycle at all. -- The Inbox contract on L1 ensures that when the Sequencer posts a batch, it posts data sufficient for any Arbitrum Node to reconstruct and validate the state of the L2 chain; i.e., the availability of this "input" data is guaranteed by Ethereum itself. -- Execution on Arbitrum is fully deterministic; i.e., a current chain state along with new input data is sufficient to compute the new chain state; thus, the moment this input data is available (i.e., when the Sequencer posts a batch), the L2 chain's state can be computed. -- Arbitrum's fault-proof system is sound; i.e., if any validator (later) tries to deviate from the valid L2 state, an honest validator will ultimately be able to challenge this and win. Since we already know that valid state will ultimately win out, we can treat our transaction as L1-finalized now. - -### 4. Validator asserts RBlock that includes transaction - -A staked, active validator will then run the Arbitrum VM over the inputs in the Inbox (just like the Sequencer did earlier, except now only over transactions posted on L1) and make an on-chain assertion about the chain's latest state, i.e., a rollup block or "RBlock." RBlocks typically get asserted every 30-60 minutes. - -**See**: - -- [ArbOS](/how-arbitrum-works/arbos/introduction.mdx) -- [Geth](/how-arbitrum-works/arbos/geth.mdx) -- [L1 pricing](/how-arbitrum-works/l1-gas-pricing.mdx) / [L2 Gas](/how-arbitrum-works/gas-fees.mdx) - -:::note - -RBlock assertions include claims about the state of the Outbox; if our transaction triggered any L2 to L1 messages, a RBlock will include an update to the Outbox to reflect its inclusion. - -::: - -**See**: - -- [The Outbox](/how-arbitrum-works/arbos/l2-l1-messaging.mdx) - -#### 4a. RBlock is valid / goes unchallenged - -In the happy / common case, the validator asserted a valid RBlock, and over the course of the dispute window — 1 week on Arbitrum One — no other validators challenge it. - -#### 4b. Assertion is challenged! - -If two validators assert different RBlocks, only (at most) one of them can be valid, so they are put into a dispute. - -A dispute consists of two staked validators dissecting their disagreement down to a single L2 block, and then dissecting the sequence of VM instructions within this block down to a single OPCODE, then finally, executing this single operation. The underlying VM the Arbitrum uses is [WebAssembly (Wasm)](https://webassembly.org), or, more precisely, "WAVM." This is all refereed by contracts on L1. - -**See:** - -- [Challenges](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx) -- [Wasm/WAVM](/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx) - -L1 contracts also keep track of the tree of all assertions; i.e., how many stakers are in disagreement, who is currently disputing with whom, etc. We refer to this level of Arbitrum's design architecture as its "assertion tree protocol." - -**See:** - -- [Assertion Tree Protocol](/how-arbitrum-works/assertion-tree.mdx) - -#### ~ ~ ~ FINALITY CHECK: STILL THE SAME Ethereum-Equivalent Finality! ~ ~ ~ - -Remember in phase 3 when said that once the L1 has committed to inputs, we can guarantee the L2 output? We meant it! Even during a dispute, Arbitrum nodes continue to execute and active validators continue to make assertions on the valid leaf in the state-tree; nothing that can happen in phase 4 has any effect on the L1-level finality we've already locked in at phase 3. - -### 5. RBlock is confirmed on L1 - -Once any and all disputes have been resolved and sufficient time has passed, our RBlock can be confirmed on L1 (any Ethereum account on L1 can confirm it). Upon confirmation, the Outbox root on L1 gets updated. - -#### ~ ~ ~ FINALITY CHECK: L2-to-L1 Messages Executable on L1 ~ ~ ~ - -If our client's transaction didn't include any L2-to-L1 messages (e.g., withdrawals), phase 5 has no material effect on their transaction. If it did include an L2-to-L1 transaction, it is only after confirmation that the message can be executed in the Outbox on L1. - -:::note - -Even before phase 5, the client has L1 finality on the _result_ of their L2-to-L1 message, they just can't execute it yet; i.e., they have a guarantee that they'll eventually be able to, e.g., finalize their withdrawal, they just can't claim their funds on L1 until the RBlock is confirmed. - -::: diff --git a/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md b/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md index 2f6cb58de..3783368bd 100644 --- a/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md +++ b/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md @@ -21,7 +21,7 @@ Custom gas token support in the Arbitrum SDK introduces a suite of APIs designed 2. **Erc20Bridger Context:** - **APIs:** `getApproveGasTokenRequest` and `approveGasToken`. - - **Purpose:** In the scenario of bridging ERC20 assets to an Orbit chain, these APIs play a crucial role. Token Bridging on Arbitrum Nitro stack uses Retryable tickets and needs specific amount of fees to be paid for creation and redemption of the ticket. For more information about retryable tickets please take a look at [this](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets) part of our docs. The Orbit 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 Orbit chain. To cover the submission and execution fees associated with retryable tickets on the Orbit chain, an adequate amount of native tokens must be approved and allocated on the parent chain to cover the fees. + - **Purpose:** In the scenario of bridging ERC20 assets to an Orbit 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 Orbit 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 Orbit chain. To cover the submission and execution fees associated with retryable tickets on the Orbit chain, an adequate number of native tokens must be approved and allocated to the parent chain to cover the fees. - **Note** that you should use `Erc20Bridger` when bridging an ERC-20 token between the parent chain and the orbit chain. **Note** that these APIs are just needed for `custom gas token` orbit chains and for ETH-powered rollup and anytrust orbit chains, you don't need to use them. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx index 66fd35000..027853d87 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx @@ -25,7 +25,7 @@ Based on the above, we interpret that an Orbit chain’s revenue sources include ### Assertion costs -The above fee system applies to an Orbit chain’s Sequencer and Batch Poster, but there is another important actor that is considered essential to the chain. These are the [validators](/how-arbitrum-works/inside-arbitrum-nitro.mdx#validators). +The above fee system applies to an Orbit chain’s Sequencer and Batch Poster, but there is another important actor that is considered essential to the chain. These are the [validators](/how-arbitrum-works/06-optimistic-rollup.mdx#validators). Validators are responsible for posting assertions on the parent chain, which are disputable claims about the new state of the Rollup. Posting an assertion is what progressed chain state on the parent chain. Validators are also responsible for securing the chain by creating disputes on false assertions. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx index ee642dc66..46daafcb4 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx @@ -217,8 +217,8 @@ To do that, you'll need to first extract the replay binary from the `nitro-node- docker run --rm --name replay-binary-extractor --entrypoint sleep custom-nitro-node-dev infinity docker cp replay-binary-extractor:/home/user/target/machines/latest extracted-replay-binary docker stop replay-binary-extractor -cat extracted-replay-binary/module.root -mv extracted-replay-binary "target/machines/$(cat extracted-replay-binary/module.root)" +cat extracted-replay-binary/module-root.txt +mv extracted-replay-binary "target/machines/$(cat extracted-replay-binary/module-root.txt)" ``` These commands will output the new WASM module root, and create the directory `target/machines/`. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx index 90cbb2c0b..3e0414932 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx @@ -197,6 +197,6 @@ The following parameters need to be configured in those nodes. :::note -Immediately after configuring fast withdrawals, your chain may not operate at full speed yet. This ramp-up is because the validators must work through the backlog of assertions that have yet to be confirmed. You will see a series of 'NodeCreated' and 'NodeConfirmed' events. Once the backlog is processed, your chain should operate fully at speed. +Immediately after configuring fast withdrawals - your chain may not be operating fully at speed yet. This is because the validators have to work through the backlog of assertions which were not yet confirmed. You will see a series of NodeCreated and NodeConfirmed events. Once the backlog has been processed, your chain should operate fully at speed. ::: diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/manage-fee-collectors.md b/arbitrum-docs/launch-orbit-chain/how-tos/manage-fee-collectors.md index 04501b651..184f26f5b 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/manage-fee-collectors.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/manage-fee-collectors.md @@ -25,8 +25,8 @@ There are four fee types that are collected on every transaction of an Orbit cha You can find more detailed information about these fee types in these pages: -- [L2 fees](/how-arbitrum-works/gas-fees.mdx) for the Orbit base fee and surplus fee -- [L1 fees](/how-arbitrum-works/l1-gas-pricing.mdx) for the Parent chain base fee and surplus fee +- [L2 fees](/how-arbitrum-works/09-gas-fees.mdx#l2-gas-pricing) for the Orbit base fee and surplus fee +- [L1 fees](/how-arbitrum-works/09-gas-fees.mdx#l1-gas-pricing) for the Parent chain base fee and surplus fee ## How to configure the fee collector addresses? diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-chain-finality.md b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-chain-finality.md index 9a5b1d8cc..068d6e54a 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-chain-finality.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-chain-finality.md @@ -9,11 +9,11 @@ content_type: how-to ## Child chain transactions -Generally, transactions executed through the sequencer on Orbit chains [achieve finality](/how-arbitrum-works/tx-lifecycle.mdx) equivalent to their parent chain once the relevant transaction data has been [posted in a batch](/how-arbitrum-works/sequencer.mdx). This means that transactions on Orbit chains are considered final in minutes. +Generally, transactions executed through the sequencer on Orbit 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/06-optimistic-rollup.mdx). This means that transactions on Orbit 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/arbos/l1-l2-messaging.mdx#retryable-tickets), including deposits through token bridges, are released by the [sequencer](/how-arbitrum-works/inside-arbitrum-nitro.mdx#if-the-sequencer-is-well-behaved) 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 promoted it to achieve finality. +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. Orbit L3s may configure the finality of transactions executed through the delayed inbox to depend on different layers of finality. By default, Orbit 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/arbos/l2-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/inside-anytrust.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 ~fifteen minutes. +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 ~fifteen minutes. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-token-bridge.md b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-token-bridge.md index 4ff984ea8..4254434d5 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-token-bridge.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-token-bridge.md @@ -93,7 +93,7 @@ Please note that after generating the raw transaction, the deployer must still s Deploying token bridge contracts is the first step in creating a bridge between the parent and the Orbit chain. -The deployment process is the same as Orbit chain contracts', where a primary contract facilitates the deployment of core contracts. The token bridge contracts are deployed on the parent and child chains by `TokenBridgeCreator`. `TokenBridgeCreator` does it in a single transaction using the [ Retryable Tickets protocol ](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets). +The deployment process is the same as Orbit chain contracts', where a primary contract facilitates the deployment of core contracts. The token bridge contracts are deployed on the parent and child chains by `TokenBridgeCreator`. `TokenBridgeCreator` does it in a single transaction using the [ Retryable Tickets protocol ](/how-arbitrum-works/10-l1-to-l2-messaging.mdx#retryable-tickets). Orbit SDK provides an API that automates the deployment by interacting with the `TokenBridgeCreator` contract. The API is `createTokenBridgePrepareTransactionRequest`, which processes the necessary inputs and generates a transaction request tailored for token bridge deployment. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/use-a-custom-gas-token.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/use-a-custom-gas-token.mdx index aa0e28190..4b247685c 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/use-a-custom-gas-token.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/use-a-custom-gas-token.mdx @@ -40,4 +40,4 @@ _Note: these methods use L1 to refer to the parent chain of the Orbit 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/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/09-gas-fees.mdx). diff --git a/arbitrum-docs/launch-orbit-chain/infra-options-orbit-chains.md b/arbitrum-docs/launch-orbit-chain/infra-options-orbit-chains.md index 85e8ff89c..07dff9889 100644 --- a/arbitrum-docs/launch-orbit-chain/infra-options-orbit-chains.md +++ b/arbitrum-docs/launch-orbit-chain/infra-options-orbit-chains.md @@ -46,19 +46,18 @@ For applications that require the ability to transfer assets to chains outside o - [Across](https://across.to/) - [Decent](https://www.decent.xyz/) -## Data availability Committee Operators +## Data availability providers for AnyTrust Chains -To reduce transaction fees for Orbit chains, you can configure a Data Availability (DA) solution that stores chain data off-chain with Anytrust Chains. -If you are enabling Fast Withdrawals, you will set up a Data Availability Committee (DAC). We currently recommend (for security and decentralization purposes) to configure a DAC with at least 3 nodes. Here are a few providers: +AnyTrust protocol offers native support data availability. If you are turning on Fast Withdrawals, we recommend having at least 3 members as part of your Data Availability Committee. Here are some providers we recommend: -- Chainbase (https://chainbase.com/) -- Ankr (https://www.ankr.com/) -- Kiln (https://www.kiln.fi/) -- Chainstack (https://chainstack.com/) -- Nansen (https://www.nansen.ai/) -- Unifra (https://unifra.io/) -- BCW Group (https://bcw.group/) -- Caldera (https://www.caldera.xyz/) +- [Chainbase](https://chainbase.com/) +- [Ankr](https://www.ankr.com/) +- [Kiln](https://www.kiln.fi/) +- [Chainstack](https://chainstack.com/) +- [Nansen](https://www.nansen.ai/) +- [Unifra](https://unifra.io/) +- [BCW Group](https://bcw.group/) +- [Caldera](https://www.caldera.xyz/) ## Indexers @@ -95,11 +94,12 @@ RPC endpoints are the primary interface through which users and developers inter - [QuickNode](https://www.quicknode.com?utm_source=arb-docs) - [Sequence](https://sequence.xyz/node-gateway) -## Alternative Data availability +## Alternative data availability One way to reduce transaction fees for Orbit chains is to configure a Data Availability (DA) solution that stores chain data off-chain. Although the AnyTrust protocol offers native support for this functionality (and is configurable by default on Orbit AnyTrust chains), the following third-party providers give you another way to store data off-chain. Note that using these services will limit your chain's ability to leverage AnyTrust protocol improvements as they relate to transaction fee and DA configurability: - [Celestia](https://celestia.org/) - [EigenDA](https://www.eigenlayer.xyz/) - [AvailDA](https://www.availproject.org/) +- [EspressoDA](https://docs.espressosys.com/network) - [Near](https://near.org/data-availability) (coming soon) diff --git a/arbitrum-docs/launch-orbit-chain/orbit-gentle-introduction.md b/arbitrum-docs/launch-orbit-chain/orbit-gentle-introduction.md index 9fc3af719..6ececf3a3 100644 --- a/arbitrum-docs/launch-orbit-chain/orbit-gentle-introduction.md +++ b/arbitrum-docs/launch-orbit-chain/orbit-gentle-introduction.md @@ -164,6 +164,6 @@ Visit the [Orbit Quickstart](./orbit-quickstart.md), start tinkering, and let us ### How can I launch an Orbit chain on mainnet? -While launching a chain on your own is possible, there are multiple infrastructure providers such as [Caldera](https://caldera.xyz/), [Conduit](https://conduit.xyz/), [AltLayer](https://altlayer.io/), and [Gelato](https://www.gelato.network/raas) that are enabling developers to quickly launch their own rollups. +While launching a chain on your own is possible, there are multiple infrastructure providers such as [Caldera](https://caldera.xyz/), [Conduit](https://conduit.xyz/), [AltLayer](https://altlayer.io/), [Zeeve](https://www.zeeve.io/), and [Gelato](https://www.gelato.network/raas) that are enabling developers to quickly launch their own rollups. [^1]: Although your Orbit chain will be able to exchange information with other Orbit chains (and the L2 chain that it settles to) by default, you're free to modify your Orbit chain's code as much as you'd like. You can even intentionally make your Orbit chain _incompatible_ with other Orbit chains and L2s. diff --git a/arbitrum-docs/launch-orbit-chain/orbit-sdk-introduction.md b/arbitrum-docs/launch-orbit-chain/orbit-sdk-introduction.md index 4950b956b..780f9e26f 100644 --- a/arbitrum-docs/launch-orbit-chain/orbit-sdk-introduction.md +++ b/arbitrum-docs/launch-orbit-chain/orbit-sdk-introduction.md @@ -17,11 +17,11 @@ The Arbitrum Orbit SDK lets you programmatically create and manage your own Orbi There are three types of Orbit chains. Review the following table to determine which type best fits your needs: -| Chain Type | Description | Use Case | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | -| **Rollup** | Offers Ethereum-grade security by batching, compressing, and posting data to the parent chain, similarly to [Arbitrum One](https://arbitrum.io/). | Ideal for applications that require high security guarantees. | -| **AnyTrust** | Implements the [AnyTrust protocol](/how-arbitrum-works/inside-arbitrum-nitro.mdx#inside-anytrust), relying on an external [Data Availability Committee (DAC)](/intro/glossary#data-availability-committee-dac) to store data and provide it on-demand instead of using their [parent chain](/intro/glossary/#parent-chain) as the Data Availability (DA) layer. | Suitable for applications that require lower transaction fees. | -| **Custom gas token** | An AnyTrust Orbit chain with the ability to specify a custom `ERC-20` gas token. | Ideal for applications that require custom gas fee tokens and lower transaction fees. | +| Chain Type | Description | Use Case | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | +| **Rollup** | Offers Ethereum-grade security by batching, compressing, and posting data to the parent chain, similarly to [Arbitrum One](https://arbitrum.io/). | Ideal for applications that require high security guarantees. | +| **AnyTrust** | Implements the [AnyTrust protocol](/how-arbitrum-works/08-anytrust-protocol.mdx), relying on an external [Data Availability Committee (DAC)](/intro/glossary#data-availability-committee-dac) to store data and provide it on-demand instead of using their [parent chain](https://docs.arbitrum.io/intro/glossary#parent-chain) as the Data Availability (DA) layer. | Suitable for applications that require lower transaction fees. | +| **Custom gas token** | An AnyTrust Orbit chain with the ability to specify a custom `ERC-20` gas token. | Ideal for applications that require custom gas fee tokens and lower transaction fees. | ## 2. Deploy your chain @@ -45,5 +45,5 @@ With your node configuration specified and token bridge deployed, you'll be read ## See also -- Learn more about the [AnyTrust consensus mechanism](/how-arbitrum-works/inside-arbitrum-nitro.mdx#inside-anytrust) +- Learn more about the [AnyTrust consensus mechanism](/how-arbitrum-works/08-anytrust-protocol.mdx) - Learn more about the [`ERC-20` token bridge architecture](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx) diff --git a/arbitrum-docs/launch-orbit-chain/reference/monitoring-tools-and-considerations.mdx b/arbitrum-docs/launch-orbit-chain/reference/monitoring-tools-and-considerations.mdx index 138955487..49a28024b 100644 --- a/arbitrum-docs/launch-orbit-chain/reference/monitoring-tools-and-considerations.mdx +++ b/arbitrum-docs/launch-orbit-chain/reference/monitoring-tools-and-considerations.mdx @@ -21,7 +21,7 @@ The Orbit Verification Script is currently under active development and is consi ## Orbit retryables tracker -[Retryable tickets](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) are messages sent from a parent chain and executed on the Orbit 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 Orbit chain. When this occurs, a manual redemption of the ticket is required. The [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 Orbit chain, and it reports any tickets that have not been automatically redeemed. +[Retryable tickets](/how-arbitrum-works/10-l1-to-l2-messaging.mdx) are messages sent from a parent chain and executed on the Orbit 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 Orbit chain. When this occurs, a manual redemption of the ticket is required. The [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 Orbit chain, and it reports any tickets that have not been automatically redeemed. ## Data Availability Server (DAS) health checks diff --git a/arbitrum-docs/partials/_gentle-intro-partial.mdx b/arbitrum-docs/partials/_gentle-intro-partial.mdx index e74cdc53a..0c661945d 100644 --- a/arbitrum-docs/partials/_gentle-intro-partial.mdx +++ b/arbitrum-docs/partials/_gentle-intro-partial.mdx @@ -37,7 +37,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, by necessity, prove that the honest party was telling the truth. For a more detailed rundown, see [here](/how-arbitrum-works/fraud-proofs/challenge-manager.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/07-interactive-fraud-proofs.mdx). #### Q: This dispute game obviously takes some time; does this impose any sort of delay on Arbitrum users' transactions? @@ -53,7 +53,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/arbos/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)). +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-geth-at-the-core.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/arbitrum-docs/run-arbitrum-node/arbos-releases/01-overview.mdx b/arbitrum-docs/run-arbitrum-node/arbos-releases/01-overview.mdx index 9cc6dda08..6b503cfe9 100644 --- a/arbitrum-docs/run-arbitrum-node/arbos-releases/01-overview.mdx +++ b/arbitrum-docs/run-arbitrum-node/arbos-releases/01-overview.mdx @@ -23,7 +23,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 [Inside Arbitrum Nitro](/how-arbitrum-works/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). +Visit [Inside Arbitrum Nitro](/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). ## List of available ArbOS releases diff --git a/arbitrum-docs/run-arbitrum-node/arbos-releases/arbos11.mdx b/arbitrum-docs/run-arbitrum-node/arbos-releases/arbos11.mdx index daafe8ab9..eb89fa653 100644 --- a/arbitrum-docs/run-arbitrum-node/arbos-releases/arbos11.mdx +++ b/arbitrum-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/arbos/l1-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 L2 base fee only, while the network fee collects L2 congestion charges. This is important for [AnyTrust chains](/how-arbitrum-works/inside-anytrust.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/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 L2 base fee only, while the network fee collects L2 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. - 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 L1 pricing parameters and make it easier to view the current chain configuration. diff --git a/arbitrum-docs/run-arbitrum-node/arbos-releases/arbos32.mdx b/arbitrum-docs/run-arbitrum-node/arbos-releases/arbos32.mdx index 270a159de..7b6dd6832 100644 --- a/arbitrum-docs/run-arbitrum-node/arbos-releases/arbos32.mdx +++ b/arbitrum-docs/run-arbitrum-node/arbos-releases/arbos32.mdx @@ -13,15 +13,15 @@ Future versions of Nitro may remove support for Orbit chains which have historic ::: -ArbOS 32 "Bianca" is shipped via [Nitro v3.2.1](https://github.com/OffchainLabs/nitro/releases/tag/v3.2.1), which is available on Docker hub with the image tag: `offchainlabs/nitro-node:v3.2.1-d81324d`. This release of Nitro is a mandatory upgrade for Arbitrum One and Nova validators. For Arbitrum One and Nova, the ArbOS 32 "Bianca" upgrade required a governance vote to activate. +The minimum Nitro version that supports ArbOS 32 "Bianca" is [Nitro v3.3.1](https://github.com/OffchainLabs/nitro/releases/tag/v3.3.1), which is available on Docker hub with the image tag: `offchainlabs/nitro-node:v3.3.1-e326369`. This release of Nitro is a mandatory upgrade for Arbitrum One and Nova validators. For Arbitrum One and Nova, the ArbOS 32 "Bianca" upgrade required a governance vote to activate. -Please note that it is important that you only run the Nitro v3.2.1 against trusted databases. If you want to use an untrusted database, you can first remove the `wasm` directory if it exists (it might be inside the `nitro` folder). Otherwise, the database may have malicious, unvalidated code that can result in remote code execution. This is also mitigated by ensuring you run the Arbitrum Nitro node inside Docker. +Please note that it is important that you only run the Nitro v3.3.1 against trusted databases. If you want to use an untrusted database, you can first remove the `wasm` directory if it exists (it might be inside the `nitro` folder). Otherwise, the database may have malicious, unvalidated code that can result in remote code execution. This is also mitigated by ensuring you run the Arbitrum Nitro node inside Docker. The Arbitrum docs will remain the canonical home for information regarding ArbOS releases, with more details found on the [ArbOS Software Releases Overview page](./01-overview.mdx). ### Requirements: -- [Nitro 3.2.1](https://github.com/OffchainLabs/nitro/releases/tag/v3.2.1) or higher +- [Nitro v3.3.1](https://github.com/OffchainLabs/nitro/releases/tag/v3.3.1) or higher - [nitro-contracts v2.1.0](https://github.com/OffchainLabs/nitro-contracts/releases/tag/v2.1.0) or higher - WASM module root: `0x184884e1eb9fefdc158f6c8ac912bb183bf3cf83f0090317e0bc4ac5860baa39` @@ -29,7 +29,7 @@ The Arbitrum docs will remain the canonical home for information regarding ArbOS ArbOS 32 Bianca is a major upgrade for Arbitrum chains. As a refresher, ArbOS upgrades can be treated as Arbitrum’s equivalent of a hard fork - more can be read about this subject over in [Arbitrum ArbOS upgrades](https://forum.arbitrum.foundation/t/arbitrum-arbos-upgrades/19695). Please note that ArbOS 21 Bianca is an upgrade that builds upon [ArbOS 20 Atlas](./arbos20.mdx). -ArbOS 32 Bianca brings many features, improvements, and bug fixes to Arbitrum chains. A full list of changes can be found in the Nitro release notes for [Nitro 3.2.1](https://github.com/OffchainLabs/nitro/releases/tag/v3.2.1) or higher (as Nitro 3.2.1 is the endorsed Nitro node version for ArbOS 32 Bianca). Highlighted below are a few of the most impactful and critical features that are introduced with ArbOS 32 Bianca: +ArbOS 32 Bianca brings many features, improvements, and bug fixes to Arbitrum chains. A full list of changes can be found in the Nitro release notes for [Nitro v3.3.1](https://github.com/OffchainLabs/nitro/releases/tag/v3.3.1) or higher (as Nitro 3.3.1 is the endorsed Nitro node version for ArbOS 32 Bianca). Highlighted below are a few of the most impactful and critical features that are introduced with ArbOS 32 Bianca: - Addition and subsequent activation of [Stylus](../../stylus/gentle-introduction.mdx) on Arbitrum chains through the addition of a new WebAssembly-based (WASM) virtual machine that runs alongside the EVM. Stylus enables developers to write smart contracts in new programming languages that compile to WASM, like Rust, that are more efficient and safer than Solidity smart contracts while retaining complete interoperability. - Adding support for [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md) decreases the costs of verifying the secp256r1 curve on-chain [by 99% when compared to current implementations](https://www.alchemy.com/blog/what-is-rip-7212), making secp256r1 verification more feasible for everyday use and enabling dApp developers and protocols to offer their users improved UX on Arbitrum One and Arbitrum Nova. Without this precompile, verifying this signature on-chain is extremely expensive. Passkey-based wallets offer better security than a typical EOA and seamless cross-device support. Many wallets, notably apps using embedded wallets, have been requesting this feature for over a year. @@ -54,7 +54,7 @@ After you have upgraded your Orbit chain to ArbOS 32 "Bianca" (i.e. you have ful ### Reference links for ArbOS 32 Bianca -- [Nitro v3.2.1 release notes](https://github.com/OffchainLabs/nitro/releases/tag/v3.2.1) +- [Nitro v3.3.1](https://github.com/OffchainLabs/nitro/releases/tag/v3.3.1) - [ArbOS 32 "Bianca" on-chain Tally vote](https://www.tally.xyz/gov/arbitrum/proposal/108288822474129076868455956066667369439381709547570289793612729242368710728616) - [AIP: Activate Stylus and Enable Next-Gen WebAssembly Smart Contracts (ArbOS 32)](https://forum.arbitrum.foundation/t/aip-activate-stylus-and-enable-next-gen-webassembly-smart-contracts-arbos-30/22970) - [AIP: Support RIP-7212 for Account Abstraction Wallets (ArbOS 32)](https://forum.arbitrum.foundation/t/aip-support-rip-7212-for-account-abstraction-wallets-arbos-30/23298) diff --git a/arbitrum-docs/run-arbitrum-node/data-availability-committees/01-get-started.mdx b/arbitrum-docs/run-arbitrum-node/data-availability-committees/01-get-started.mdx index ae6fa069e..18d9eb122 100644 --- a/arbitrum-docs/run-arbitrum-node/data-availability-committees/01-get-started.mdx +++ b/arbitrum-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 familiarized with how the AnyTrust protocol works, and the role of the DAC in the protocol. Refer to _[Inside AnyTrust](/how-arbitrum-works/inside-anytrust.mdx)_ 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 _[Inside AnyTrust](/how-arbitrum-works/08-anytrust-protocol.mdx)_ to learn more. ## If you are a DAC member diff --git a/arbitrum-docs/run-arbitrum-node/data-availability-committees/02-deploy-das.mdx b/arbitrum-docs/run-arbitrum-node/data-availability-committees/02-deploy-das.mdx index ad7c127f3..c4cf02902 100644 --- a/arbitrum-docs/run-arbitrum-node/data-availability-committees/02-deploy-das.mdx +++ b/arbitrum-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/inside-anytrust.mdx)_ for a refresher. +- The DAC's role in the AnyTrust protocol. Refer to _[Inside AnyTrust](/how-arbitrum-works/08-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? @@ -392,7 +392,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/inside-anytrust#keysets). +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 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/arbitrum-docs/run-arbitrum-node/data-availability-committees/04-configure-dac.mdx b/arbitrum-docs/run-arbitrum-node/data-availability-committees/04-configure-dac.mdx index 3d244fde0..59a0629af 100644 --- a/arbitrum-docs/run-arbitrum-node/data-availability-committees/04-configure-dac.mdx +++ b/arbitrum-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/inside-anytrust.mdx)_ for a refresher. +- The DAC's role in the AnyTrust protocol. Refer to _[Inside AnyTrust](/how-arbitrum-works/08-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/inside-arbitrum-nitro#inside-anytrust)_ 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/08-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/arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx b/arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx index 7baadc812..d8459494d 100644 --- a/arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx +++ b/arbitrum-docs/run-arbitrum-node/more-types/02-run-validator-node.mdx @@ -14,7 +14,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/03-run-full-node.mdx) for DAO-governed chains, and [here](/node-running/how-tos/running-an-orbit-node.mdx) for Orbit chains) -- [How the Rollup protocol works](/how-arbitrum-works/inside-arbitrum-nitro.mdx#arbitrum-rollup-protocol) +- [How the Rollup protocol works](/how-arbitrum-works/06-optimistic-rollup.mdx) - [How BoLD works](/bold/concepts/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/arbitrum-docs/stylus/concepts/how-it-works.md b/arbitrum-docs/stylus/concepts/how-it-works.md index bcb004976..890f697a6 100644 --- a/arbitrum-docs/stylus/concepts/how-it-works.md +++ b/arbitrum-docs/stylus/concepts/how-it-works.md @@ -41,9 +41,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 on-chain through a [“one-step proof.”](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx#general-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 on-chain through a [“one-step proof.”](/how-arbitrum-works/07-interactive-fraud-proofs.mdx#general-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. -For more details on Nitro’s architecture, refer to the [documentation](/how-arbitrum-works/inside-arbitrum-nitro.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-a-gentle-introduction.mdx) or the [Nitro whitepaper](https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf). ## Why does this matter? diff --git a/arbitrum-docs/stylus/quickstart.mdx b/arbitrum-docs/stylus/quickstart.mdx index a1f24a999..1338f4b38 100644 --- a/arbitrum-docs/stylus/quickstart.mdx +++ b/arbitrum-docs/stylus/quickstart.mdx @@ -25,7 +25,7 @@ This guide will get you started with Stylus'
Rust toolchain -Follow the instructions on [Rust Lang's installation page](https://www.rust-lang.org/tools/install) to install a complete Rust toolchain (v1.81 or older, v1.82 is currently not supported) on your system. After installation, ensure you can access the programs `rustup`, `rustc`, and `cargo` from your preferred terminal application. +Follow the instructions on [Rust Lang's installation page](https://www.rust-lang.org/tools/install) to install a complete Rust toolchain (v1.81 or newer) on your system. After installation, ensure you can access the programs `rustup`, `rustc`, and `cargo` from your preferred terminal application.
@@ -55,7 +55,7 @@ You can download Docker from [Docker's website](https://www.docker.com/products/
Foundry's Cast -[Foundry's Cast](https://book.getfoundry.sh/cast/) is a command-line tool that allows you to interact with your EVM contracts. +Foundry's Cast is a command-line tool that allows you to interact with your EVM contracts. You need to [install the Foundry CLI](https://getfoundry.sh) to use Cast.
diff --git a/arbitrum-docs/stylus/reference/rust-sdk-guide.md b/arbitrum-docs/stylus/reference/rust-sdk-guide.md index 6c6e0dd37..70db5437b 100644 --- a/arbitrum-docs/stylus/reference/rust-sdk-guide.md +++ b/arbitrum-docs/stylus/reference/rust-sdk-guide.md @@ -113,6 +113,16 @@ impl Contract { self.owner.set(new_owner); } } + + /// Unlike other storage type, stringStorage needs to + /// use `.set_str()` and `.get_string()` to set and get. + pub fn set_base_uri(&mut self, base_uri: String) { + self.base_uri.set_str(base_uri); + } + + pub fn get_base_uri(&self) -> String { + self.base_uri.get_string() + } } ``` diff --git a/arbitrum-docs/stylus/using-cli.mdx b/arbitrum-docs/stylus/using-cli.mdx index c339c98bd..a69bef5f9 100644 --- a/arbitrum-docs/stylus/using-cli.mdx +++ b/arbitrum-docs/stylus/using-cli.mdx @@ -21,7 +21,7 @@ Cargo stylus is a plugin to the standard cargo tool for developing Rust programs
Rust toolchain -Follow the instructions on [Rust Lang's installation page](https://www.rust-lang.org/tools/install) to install a complete Rust toolchain (v1.81 or older; v1.82 is currently not supported) on your system. After installation, ensure you can access the programs `rustup`, `rustc`, and `cargo` from your preferred terminal application. +Follow the instructions on [Rust Lang's installation page](https://www.rust-lang.org/tools/install) to install a complete Rust toolchain (v1.81 or newer) on your system. After installation, ensure you can access the programs `rustup`, `rustc`, and `cargo` from your preferred terminal application.
diff --git a/arbitrum-docs/welcome/get-started.mdx b/arbitrum-docs/welcome/get-started.mdx index 14e15233c..25fd1709b 100644 --- a/arbitrum-docs/welcome/get-started.mdx +++ b/arbitrum-docs/welcome/get-started.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/inside-arbitrum-nitro.mdx) | A **protocol** for scaling Ethereum smart contracts. | -| [Arbitrum AnyTrust](/how-arbitrum-works/inside-anytrust.mdx) | A **protocol** for scaling Ethereum smart contracts even further, with a mild trust assumption. | -| [Arbitrum Nitro](/how-arbitrum-works/inside-arbitrum-nitro.mdx) | The node **software** that codifies the Rollup and AnyTrust protocols. | -| [Arbitrum nodes](/run-arbitrum-node/03-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 Orbit chains. | -| [Arbitrum Orbit](https://orbit.arbitrum.io/) | Lets you run your own Rollup and AnyTrust chains. | -| [Arbitrum Stylus](/stylus/gentle-introduction) | Lets you write EVM-compatible smart contracts in Rust and any other language that compiles to Wasm. | +| Component | Description | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | +| [Arbitrum Rollup](/how-arbitrum-works/06-optimistic-rollup.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/03-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 Orbit chains. | +| [Arbitrum Orbit](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 @@ -68,7 +68,7 @@ The Arbitrum suite includes the protocols, chains, services, and SDKs that power | Resource | Description | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------- | -| [Inside Nitro](/how-arbitrum-works/inside-arbitrum-nitro.mdx) | A technical deep dive into Nitro's architecture. | -| [Inside AnyTrust](/how-arbitrum-works/inside-anytrust.mdx) | A technical deep dive into the AnyTrust protocol. | +| [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. | | [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/vercel.json b/vercel.json index b13e7e1f6..7606d6868 100644 --- a/vercel.json +++ b/vercel.json @@ -12,67 +12,107 @@ }, { "source": "/(proving/challenge-manager/?)", - "destination": "/how-arbitrum-works/fraud-proofs/challenge-manager", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", + "permanent": false + }, + { + "source": "/(fraud-proofs/challenge-manager/?)", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", "permanent": false }, { "source": "/(proving/osp-assumptions/?)", - "destination": "/how-arbitrum-works/fraud-proofs/osp-assumptions", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", + "permanent": false + }, + { + "source": "/(fraud-proofs/osp-assumptions/?)", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", "permanent": false }, { "source": "/(proving/wasm-to-wavm/?)", - "destination": "/how-arbitrum-works/fraud-proofs/wasm-wavm", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", + "permanent": false + }, + { + "source": "/(fraud-proofs/wasm-wavm/?)", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", "permanent": false }, { "source": "/(proving/wavm-custom-opcodes/?)", - "destination": "/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", + "permanent": false + }, + { + "source": "/(fraud-proofs/wavm-custom-opcodes/?)", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", "permanent": false }, { "source": "/(proving/wavm-floats/?)", - "destination": "/how-arbitrum-works/fraud-proofs/wavm-floats", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", + "permanent": false + }, + { + "source": "/(fraud-proofs/wavm-floats/?)", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", "permanent": false }, { "source": "/(proving/wavm-modules/?)", - "destination": "/how-arbitrum-works/fraud-proofs/wavm-modules", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", + "permanent": false + }, + { + "source": "/(fraud-proofs/wavm-modules/?)", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", "permanent": false }, { "source": "/(arbos/geth/?)", - "destination": "/how-arbitrum-works/arbos/geth", + "destination": "/how-arbitrum-works/geth-at-the-core", "permanent": false }, { "source": "/(arbos/?)", - "destination": "/how-arbitrum-works/arbos/introduction", + "destination": "/how-arbitrum-works/geth-at-the-core", "permanent": false }, { "source": "/(arbos/l2-to-l1-messaging/?)", - "destination": "/how-arbitrum-works/arbos/l2-l1-messaging", + "destination": "/how-arbitrum-works/l2-to-l1-messaging", "permanent": false }, { "source": "/(arbos/l1-to-l2-messaging/?)", - "destination": "/how-arbitrum-works/arbos/l1-l2-messaging", + "destination": "/how-arbitrum-works/l1-to-l2-messaging", "permanent": false }, { "source": "/(assertion-tree/?)", - "destination": "/how-arbitrum-works/assertion-tree", + "destination": "/how-arbitrum-works/optimistic-rollup", "permanent": false }, { "source": "/(inside-arbitrum-nitro/?)", - "destination": "/how-arbitrum-works/inside-arbitrum-nitro", + "destination": "/how-arbitrum-works/a-gentle-introduction", + "permanent": false + }, + { + "source": "/(how-arbitrum-works/inside-arbitrum-nitro/?)", + "destination": "/how-arbitrum-works/a-gentle-introduction", "permanent": false }, { "source": "/(arbos/l1-pricing/?)", - "destination": "/how-arbitrum-works/l1-gas-pricing", + "destination": "/how-arbitrum-works/gas-fees", + "permanent": false + }, + { + "source": "/(arbos/l1-gas-pricing/?)", + "destination": "/how-arbitrum-works/gas-fees", "permanent": false }, { @@ -82,17 +122,27 @@ }, { "source": "/(inside-anytrust/?)", - "destination": "/how-arbitrum-works/inside-anytrust", + "destination": "/how-arbitrum-works/anytrust-protocol", + "permanent": false + }, + { + "source": "/(arbos/l1-l2-messaging/?)", + "destination": "/how-arbitrum-works/l1-to-l2-messaging", + "permanent": false + }, + { + "source": "/(arbos/l2-l1-messaging/?)", + "destination": "/how-arbitrum-works/l2-to-l1-messaging", "permanent": false }, { "source": "/(why-nitro/?)", - "destination": "/how-arbitrum-works/why-nitro", + "destination": "/how-arbitrum-works/a-gentle-introduction", "permanent": false }, { "source": "/(tx-lifecycle/?)", - "destination": "/how-arbitrum-works/tx-lifecycle", + "destination": "/how-arbitrum-works/transaction-lifecycle", "permanent": false }, { @@ -461,13 +511,13 @@ "permanent": false }, { - "source": "/docs/inside_arbitrum", - "destination": "/how-arbitrum-works/inside-arbitrum-nitro", + "source": "/(docs/inside_arbitrum/?)", + "destination": "/how-arbitrum-works/a-gentle-introduction", "permanent": false }, { - "source": "/docs/l1_l2_messages", - "destination": "/how-arbitrum-works/arbos/l1-l2-messaging", + "source": "/(docs/l1_l2_messages/?)", + "destination": "/how-arbitrum-works/l1-to-l2-messaging", "permanent": false }, { @@ -491,8 +541,8 @@ "permanent": false }, { - "source": "/docs/anytrust", - "destination": "/how-arbitrum-works/inside-anytrust", + "source": "/(docs/anytrust/?)", + "destination": "/how-arbitrum-works/08-anytrust-protocol", "permanent": false }, { @@ -596,13 +646,18 @@ "permanent": false }, { - "source": "/docs/finality", - "destination": "/how-arbitrum-works/tx-lifecycle", + "source": "/(docs/finality/?)", + "destination": "/how-arbitrum-works/transaction-lifecycle", + "permanent": false + }, + { + "source": "/arbos/introduction", + "destination": "/how-arbitrum-works/geth-at-the-core", "permanent": false }, { - "source": "/docs/withdrawals", - "destination": "/how-arbitrum-works/tx-lifecycle", + "source": "/(docs/withdrawals/?)", + "destination": "/how-arbitrum-works/transaction-lifecycle", "permanent": false }, { @@ -641,48 +696,48 @@ "permanent": false }, { - "source": "/docs/censorship_resistance", + "source": "/(docs/censorship_resistance/?)", "destination": "/how-arbitrum-works/sequencer", "permanent": false }, { - "source": "/docs/arbgas", + "source": "/(docs/arbgas/?)", "destination": "/how-arbitrum-works/gas-fees", "permanent": false }, { - "source": "/docs/arbos", - "destination": "/how-arbitrum-works/arbos/introduction", + "source": "/(docs/arbos/?)", + "destination": "/how-arbitrum-works/geth-at-the-core", "permanent": false }, { - "source": "/docs/tx_lifecycle", - "destination": "/how-arbitrum-works/tx-lifecycle", + "source": "/(docs/tx_lifecycle/?)", + "destination": "/how-arbitrum-works/transaction-lifecycle", "permanent": false }, { - "source": "/docs/rollup_protocol", - "destination": "/how-arbitrum-works/assertion-tree", + "source": "/(docs/rollup_protocol/?)", + "destination": "/how-arbitrum-works/optimistic-rollup", "permanent": false }, { - "source": "/docs/avm_design", - "destination": "/how-arbitrum-works/inside-arbitrum-nitro", + "source": "/(docs/avm_design/?)", + "destination": "/how-arbitrum-works/a-gentle-introduction", "permanent": false }, { - "source": "/docs/dispute_resolution", - "destination": "/how-arbitrum-works/fraud-proofs/challenge-manager", + "source": "/(docs/dispute_resolution/?)", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", "permanent": false }, { - "source": "/docs/arbos_formats", - "destination": "/how-arbitrum-works/arbos/introduction", + "source": "/(docs/arbos_formats/?)", + "destination": "/how-arbitrum-works/geth-at-the-core", "permanent": false }, { - "source": "/docs/avm_specification", - "destination": "/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes", + "source": "/(docs/avm_specification/?)", + "destination": "/how-arbitrum-works/interactive-fraud-proofs", "permanent": false }, { diff --git a/arbitrum-docs/how-arbitrum-works/arbos/introduction.mdx b/website/archive/arbos/introduction.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/arbos/introduction.mdx rename to website/archive/arbos/introduction.mdx diff --git a/arbitrum-docs/how-arbitrum-works/why-nitro.mdx b/website/archive/how-arbitrum-works/12-nitro-vs-classic.mdx similarity index 92% rename from arbitrum-docs/how-arbitrum-works/why-nitro.mdx rename to website/archive/how-arbitrum-works/12-nitro-vs-classic.mdx index a0d6afe7d..5f2076ac1 100644 --- a/arbitrum-docs/how-arbitrum-works/why-nitro.mdx +++ b/website/archive/how-arbitrum-works/12-nitro-vs-classic.mdx @@ -1,8 +1,3 @@ ---- -title: Nitro vs. Classic -author: dzgoldman ---- - Why Nitro? Nitro represents the latest step in the evolution of Arbitrum technology; it is an upgrade from the tech stack first released on the mainnet Arbitrum One chain, which we now refer to as “Arbitrum Classic” (and several steps beyond what was described in the [initial Arbitrum whitepaper back in 2018](https://www.usenix.org/system/files/conference/usenixsecurity18/sec18-kalodner.pdf)). Here, we’ll explain the rationale behind the Nitro upgrade, and outline Nitro’s core benefits over the classic system. @@ -49,4 +44,4 @@ In short, there’s no better way to achieve Ethereum compatibility than to reus Having code that is as simple and easy to reason about as possible is important for L2 systems, which are inevitably complex. The classic stack represents a large codebase built in-house, which requires a fair amount of time and overhead to understand. The AVM together with ArbOS effectively constitute a full blockchain protocol built from the ground up. Since the AVM was custom-built, with no high-level languages yet created for it, the ArbOS logic had to be implemented in what was essentially a custom language — called “mini” — along with a mini-to-AVM compiler. -Nitro’s direct usage of Geth means most of the work of creating an L2 VM is inherited right out of the box. The ArbOS custom logic (which, happily, can now be written in Go instead of mini), is much slimmer than in the classic stack; since the work of emulating the EVM is now handled by the Geth software, ArbOS needs only to implement the things specific and necessary for layer 2 (i.e., L1/L2 gas accounting, special message types for cross-chain transactions, etc.) Leaner, simpler code — much of which directly inherits engineering hours that have been put into an Ethereum-Geth itself — makes it a system that’s far more accessible for auditors and contributors, giving us strong confidence in its implementation security that will only harden as the ecosystem grows. +Nitro’s direct usage of Geth means most of the work of creating an L2 VM is inherited right out of the box. The ArbOS custom logic (which, happily, can now be written in Go instead of mini) is much slimmer than in the classic stack; since the Geth software now handles the work of emulating the EVM, ArbOS needs only to implement the things specific and necessary for layer 2 (i.e., L1/L2 gas accounting, special message types for cross-chain transactions, etc.) Leaner, simpler code — much of which directly inherits engineering hours that have been put into an Ethereum-Geth itself — makes it a system that’s far more accessible for auditors and contributors, giving us strong confidence in its implementation security that will only harden as the ecosystem grows. \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx b/website/archive/how-arbitrum-works/assertion-tree.mdx similarity index 74% rename from arbitrum-docs/how-arbitrum-works/assertion-tree.mdx rename to website/archive/how-arbitrum-works/assertion-tree.mdx index 1669c1944..eb4dd0cc5 100644 --- a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx +++ b/website/archive/how-arbitrum-works/assertion-tree.mdx @@ -1,5 +1,10 @@ --- +title: Assertion Tree +description: 'Learn the fundamentals of assertions/disputable assertions on Arbitrum.' author: dzgoldman +sme: dzgoldman +user_story: As a current or prospective Arbitrum user, I need to learn more about how assertions and disputable assertions work on Arbitrum. +content_type: get-started --- # The Assertion Tree @@ -16,7 +21,7 @@ If, however, two or more conflicting assertions exist, the Assertion Tree bifurc Crucially, the rules of advancing an Arbitrum chain are deterministic; this means that given a chain state and some new inputs, there is only one valid output. Thus, if the Assertion Tree contains more than one leaf, then at most only one leaf can represent the valid chain-state; if we assume there is at least one honest active validator, _exactly_ one leaf will be valid. -Two conflicting assertions can be put into a dispute; see [Interactive Challenges](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx) for details on the dispute process. For the sake of understanding the Assertion Tree protocol, suffice it to say that 2-party disputes last at most a fixed amount of time (1 week), at the end of which one of the two conflicting assertions will be rejected, and the validator who posted it will lose their stake. +Two conflicting assertions can be put into a dispute; see [Interactive Challenges](/how-arbitrum-works/07-interactive-fraud-proofs.mdx) for details on the dispute process. For the sake of understanding the Assertion Tree protocol, suffice it to say that 2-party disputes last at most a fixed amount of time (1 week), at the end of which one of the two conflicting assertions will be rejected, and the validator who posted it will lose their stake. In order for an assertion to be confirmed and for its stake to be recovered, two conditions must be met: sufficient time for disputes must have passed, and no other conflicting branches in the Assertion Tree can exist (i.e., they've all been disputed / "pruned" off.) @@ -26,8 +31,8 @@ These properties together ensure that as long as at least one honest, active val Even if the Assertion Tree has multiple conflicting leaves and, say, multiple disputes are in progress, validators can continue making assertions; honest validators will simply build on the one valid leaf (intuitively: an assertion is also an implicit claim of the validity of all of its parent-assertions.) Likewise, users can continue transacting on L2, since transactions continue to be posted in the chain's inbox. -The only delay that users experience during a dispute is of their [L2 to L1 messages](/how-arbitrum-works/arbos/l2-l1-messaging.mdx) (i.e., "their withdrawals"). Note that a "delay attacker" who seeks to grief the system by deliberately causing such delays will find this attack quite costly, since each bit of delay-time gained requires the attacker lose another stake. +The only delay that users experience during a dispute is of their [L2 to L1 messages](/how-arbitrum-works/11-l2-to-l1-messaging.mdx) (i.e., "their withdrawals"). Note that a "delay attacker" who seeks to grief the system by deliberately causing such delays will find this attack quite costly, since each bit of delay-time gained requires the attacker lose another stake. ### Detailed Spec -For a more detailed breakdown / specification of the assertion tree protocol, see [Inside Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.mdx#arbitrum-rollup-protocol). +For a more detailed breakdown / specification of the assertion tree protocol, see [Inside Arbitrum](/how-arbitrum-works/06-optimistic-rollup.mdx). diff --git a/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx b/website/archive/how-arbitrum-works/inside-arbitrum-nitro.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx rename to website/archive/how-arbitrum-works/inside-arbitrum-nitro.mdx diff --git a/website/sidebars.js b/website/sidebars.js index b77f15bcc..0f82fad14 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -817,146 +817,120 @@ const sidebars = { collapsed: true, items: [ { - type: 'category', - label: 'Introductory concepts', - collapsed: true, - items: [ - { - type: 'doc', - id: 'how-arbitrum-works/tx-lifecycle', - label: 'Transaction lifecycle', - }, - { - type: 'doc', - id: 'how-arbitrum-works/sequencer', - label: 'Sequencer', - }, - { - type: 'doc', - id: 'how-arbitrum-works/inside-anytrust', - label: 'AnyTrust protocol', - }, - { - type: 'category', - label: 'Gas / fees', - items: [ - { - type: 'doc', - id: 'how-arbitrum-works/gas-fees', - label: 'L2 gas and fees', - }, - { - type: 'doc', - id: 'how-arbitrum-works/l1-gas-pricing', - label: 'L1 pricing', - }, - ], - }, - ], + 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', + }, + { + type: 'doc', + id: 'how-arbitrum-works/geth-at-the-core', + label: 'Geth at the Core', + }, + { + type: 'doc', + id: 'how-arbitrum-works/separating-execution-from-proving', + label: 'Separating Execution from Proving', + }, + { + type: 'doc', + id: 'how-arbitrum-works/optimistic-rollup', + label: 'Optimistic Rollup', + }, + { + type: 'doc', + id: 'how-arbitrum-works/interactive-fraud-proofs', + label: 'Challenges: Interactive Fraud Proofs', + }, + { + type: 'doc', + id: 'how-arbitrum-works/anytrust-protocol', + label: 'AnyTrust protocol', + }, + { + type: 'doc', + id: 'how-arbitrum-works/gas-fees', + label: 'Gas and fees', + }, + { + type: 'doc', + id: 'how-arbitrum-works/l1-to-l2-messaging', + label: 'L1 to L2 messaging', + }, + { + type: 'doc', + id: 'how-arbitrum-works/l2-to-l1-messaging', + label: 'L2 to L1 messaging', + }, + { + type: 'link', + href: 'https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf', + label: 'Nitro whitepaper', }, + { type: 'category', - label: 'Advanced concepts', - collapsed: true, + label: 'The BoLD dispute protocol', items: [ { type: 'doc', - id: 'how-arbitrum-works/inside-arbitrum-nitro', - label: 'Deep dive: Inside Arbitrum', + id: 'how-arbitrum-works/bold/gentle-introduction', + label: 'A gentle introduction', + }, + { + type: 'link', + href: 'https://github.com/offchainlabs/bold-validator-starter-kit', + label: 'Deploy a validator on testnet', }, { type: 'link', - href: 'https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf', - label: 'Deeper dive: Whitepaper', + href: 'https://arxiv.org/abs/2404.10491', + label: 'BoLD Whitepaper', }, { type: 'doc', - id: 'how-arbitrum-works/assertion-tree', - label: 'Assertion tree', + id: 'bold/concepts/bold-technical-deep-dive', + label: 'Technical deep dive', }, { type: 'doc', - id: 'how-arbitrum-works/why-nitro', - label: 'Nitro vs. Classic', + id: 'how-arbitrum-works/bold/bold-economics-of-disputes', + label: 'Economics of disputes', }, { - type: 'category', - label: 'Cross-chain messaging', - items: [ - { - type: 'doc', - id: 'how-arbitrum-works/arbos/l1-l2-messaging', - label: 'L1-to-L2 messaging', - }, - { - type: 'doc', - id: 'how-arbitrum-works/arbos/l2-l1-messaging', - label: 'L2-to-L1 messaging', - }, - ], + type: 'link', + href: 'https://github.com/OffchainLabs/bold', + label: 'Specification on Github', }, { - type: 'category', - label: 'ArbOS', - items: [ - { - type: 'doc', - id: 'how-arbitrum-works/arbos/introduction', - label: 'ArbOS', - }, - { - type: 'doc', - id: 'how-arbitrum-works/arbos/geth', - label: 'Geth', - }, - ], + type: 'link', + href: 'https://github.com/trailofbits/publications/blob/master/reviews/2024-04-offchainbold-securityreview.pdf', + label: 'Audit Report by Trail of Bits', }, { - type: 'category', - label: 'Fraud proofs', - items: [ - { - type: 'doc', - id: 'how-arbitrum-works/fraud-proofs/challenge-manager', - label: 'Interactive challenges', - }, - { - type: 'doc', - id: 'how-arbitrum-works/fraud-proofs/osp-assumptions', - label: 'One step proof assumptions', - }, - { - type: 'doc', - id: 'how-arbitrum-works/fraud-proofs/wasm-wavm', - label: 'Wasm To WAVM', - }, - { - type: 'doc', - id: 'how-arbitrum-works/fraud-proofs/wavm-custom-opcodes', - label: 'Custom WAVM opcodes', - }, - { - type: 'doc', - id: 'how-arbitrum-works/fraud-proofs/wavm-floats', - label: 'WAVM floats', - }, - { - type: 'doc', - id: 'how-arbitrum-works/fraud-proofs/wavm-modules', - label: 'WAVM modules', - }, - ], + type: 'link', + href: 'https://code4rena.com/reports/2024-05-arbitrum-foundation', + label: 'Audit Report by Code4rena', }, + ], + }, + { + type: 'category', + label: 'Timeboost', + items: [ { - type: 'category', - label: 'Timeboost', - items: [ - { - type: 'doc', - id: 'how-arbitrum-works/timeboost/gentle-introduction', - label: 'Public preview', - }, - ], + type: 'doc', + id: 'how-arbitrum-works/timeboost/gentle-introduction', + label: 'Public preview', }, ], }, diff --git a/website/src/css/partials/_darkmode.scss b/website/src/css/partials/_darkmode.scss index 5fb98ccb0..d95642293 100644 --- a/website/src/css/partials/_darkmode.scss +++ b/website/src/css/partials/_darkmode.scss @@ -64,6 +64,11 @@ color: white; } } + + // Invert images wrapped in divs with invert-on-dark class when in dark mode + .invert-on-dark img { + filter: invert(1); + } } [data-theme='light'] { diff --git a/website/src/css/partials/_sidebar.scss b/website/src/css/partials/_sidebar.scss index aa339b3a2..57ea5e35e 100644 --- a/website/src/css/partials/_sidebar.scss +++ b/website/src/css/partials/_sidebar.scss @@ -14,14 +14,6 @@ $child-sidebar-item-font-size: 14px; padding-top: 20px; font-weight: 400; - // make the carets less obtrusive - .menu__link--sublist-caret:after { - height: 1rem !important; - width: 1rem !important; - background: var(--ifm-menu-link-sublist-icon) 50% / 1.2rem 1.2rem; - opacity: 0.5; - } - // style the root level items > li.theme-doc-sidebar-item-link-level-1, > li.theme-doc-sidebar-item-category-level-1 {