From 550131c1d9baa0c4dae7b4ecb0053aec2aecf5bb Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 21 Nov 2024 14:54:56 -0600 Subject: [PATCH 01/35] reorganized how-arbitrum-works section --- .gitignore | 1 + .../01-a-gentle-introduction.mdx | 99 +++ ...cycle.mdx => 02-transaction-lifecycle.mdx} | 0 .../l1-l2-messaging.mdx => 03-sequencer.mdx} | 142 +++- .../04-state-transition-function.mdx | 62 ++ .../how-arbitrum-works/05-validation.mdx | 295 ++++++++ .../how-arbitrum-works/06-challenges.mdx | 150 ++++ .../07-anytrust-protocol.mdx | 147 ++++ .../how-arbitrum-works/08-gas-fees.mdx | 147 ++++ ...{why-nitro.mdx => 09-nitro-vs-classic.mdx} | 0 .../arbos/l2-l1-messaging.mdx | 27 - .../how-arbitrum-works/assertion-tree.mdx | 33 - arbitrum-docs/how-arbitrum-works/gas-fees.mdx | 36 - .../how-arbitrum-works/inside-anytrust.mdx | 71 -- .../inside-arbitrum-nitro.mdx | 677 ------------------ .../how-arbitrum-works/l1-gas-pricing.mdx | 60 -- .../how-arbitrum-works/sequencer.mdx | 34 - arbitrum-sdk | 2 +- 18 files changed, 1028 insertions(+), 955 deletions(-) create mode 100644 arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx rename arbitrum-docs/how-arbitrum-works/{tx-lifecycle.mdx => 02-transaction-lifecycle.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{arbos/l1-l2-messaging.mdx => 03-sequencer.mdx} (55%) create mode 100644 arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx create mode 100644 arbitrum-docs/how-arbitrum-works/05-validation.mdx create mode 100644 arbitrum-docs/how-arbitrum-works/06-challenges.mdx create mode 100644 arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx create mode 100644 arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx rename arbitrum-docs/how-arbitrum-works/{why-nitro.mdx => 09-nitro-vs-classic.mdx} (100%) delete mode 100644 arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/assertion-tree.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/gas-fees.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/inside-anytrust.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/l1-gas-pricing.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/sequencer.mdx diff --git a/.gitignore b/.gitignore index d5c300a76..83be1e7d7 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ arbitrum-docs/sdk arbitrum-docs/stylus-by-example .vercel +.DS_Store 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..5f2fe8d1a --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -0,0 +1,99 @@ +--- +title: 'Inside Arbitrum Nitro' +sidebar_label: 'Deep dive: Inside Arbitrum' +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, which is used by the Arbitrum Nova chain. AnyTrust is covered by a section at the end of this document. + + + + +## 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, improving over "classic" Arbitrum in several ways: + +- **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. + +## Sequencing, Followed by Deterministic Execution + +This diagram summarizes how transactions are processed in Nitro. + +![seq-then-exec](../assets/seq-then-exec.png) + +Let's follow a user's transaction through this process. + +First, the user creates a transaction, uses their wallet to sign it, and sends it to the Nitro chain's Sequencer. The Sequencer's job, as its name implies, is to take the arriving transactions, put them into an ordered sequence, and publish that sequence. + +Once the transactions are sequenced, they are run through the _state transition function_, one by one, in order. The state transition function takes as input the current state of the chain (account balances, contract code, and so on), along with the next transaction. It updates the state and sometimes emits a new Layer 2 block on the Nitro chain. + +Because the protocol doesn't trust the Sequencer not to put garbage into its sequence, the state transition function will detect and discard any invalid (e.g., improperly formed) transactions in the sequence. A well-behaved Sequencer will filter out invalid transactions so the state transition function never sees them--and this reduces cost and therefore keeps transactions fees low--but Nitro will still work correctly no matter what the Sequencer puts into its feed. (Transactions in the feed are signed by their senders, so the Sequencer can't create forged transactions.) + +The state transition function is deterministic, which means that its behavior depends only on the current state and the contents of the next transaction--and nothing else. Because of this determinism, the result of a transaction T will depend only on the genesis state of the chain, the transactions before T in the sequence, and T itself. + +It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/tx-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/tx-lifecycle.mdx rename to arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx diff --git a/arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx similarity index 55% rename from arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx rename to arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index c7cf4e50c..64205f57d 100644 --- a/arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -1,20 +1,60 @@ ---- -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 ---- - -import { AddressAliasHelper } from '@site/src/components/AddressAliasHelper'; -import { - MermaidWithHtml, - Nodes, - Node, - Connection, - NodeDescriptions, - NodeDescription, -} from '/src/components/MermaidWithHtml/MermaidWithHtml'; +# 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. + + + + + +## Bridging + +We have already 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. Let’s talk about how contracts interact between L1 and L2--how an L1 contract calls an L2 contract, and vice versa. + +The 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. As a consequence, a cross-chain contract-to-contract call can never produce a result that is available to the calling contract (except for acknowledgement that the call was successfully submitted for later execution). + +### L1 contracts can submit L2 transactions + +An L1 contract can submit an L2 transaction, just like a user would, by calling the Nitro chain's inbox contract on Ethereum. This L2 transaction will run later, producing results that will not be available to the L1 caller. The transaction will execute at L2, but the L1 caller won’t be able to see any results from the L2 transaction. + +The advantage of this method is that it is simple and has relatively low latency. The disadvantage, compared to the other method we’ll describe soon, is that the L2 transaction might revert if the L1 caller doesn’t get the L2 gas price and max gas amount right. Because the L1 caller can’t see the result of its L2 transaction, it can’t be absolutely sure that its L2 transaction will succeed. + +This would introduce a serious a problem for certain types of L1 to L2 interactions. Consider a transaction that includes depositing a token on L1 to be made available at some address on L2. If the L1 side succeeds, but the L2 side reverts, you've just sent some tokens to the L1 inbox contract that are unrecoverable on either L2 or L1. Not good. + +### L1 to L2 ticket-based transactions + +Fortunately, we have another method for L1 to L2 calls, which is more robust against gas-related failures, that uses a ticket-based system. The idea is that an L1 contract can submit a “retryable” transaction. The Nitro chain will try to run that transaction. If the transaction succeeds, nothing else needs to happen. But if the transaction fails, Nitro will create a “ticketID” that identifies that failed transaction. Later, anyone can call a special pre-compiled contract at L2, providing the ticketID, to try redeeming the ticket and re-executing the transaction. + +When saving a transaction for retry, Nitro records the sender’s address, destination address, callvalue, and calldata. All of this is saved, and the callvalue is deducted from the sender’s account and (logically) attached to the saved transaction. + +If the redemption succeeds, the transaction is done, a receipt is issued for it, and the ticketID is canceled and can’t be used again. If the redemption fails, for example because the packaged transaction fails, the redemption reports failure and the ticketID remains available for redemption. + +Normally the original submitter will try to cause their transaction to succeed immediately, so it never needs to be recorded or retried. As an example, our "token deposit" use case above should, in the happy, common case, still only require a single signature from the user. If this initial execution fails, the ticketID will still exist as a backstop which others can redeem later. + +Submitting a transaction in this way carries a price in ETH which the submitter must pay, which varies based on the calldata size of the transaction. Once submitted, the ticket is valid for about a week. If the ticket has not been redeemed in that period, it is deleted. + +When the ticket is redeemed, the pre-packaged transaction runs with sender and origin equal to the original submitter, and with the destination, callvalue, and calldata the submitter provided at the time of submission. + +This mechanism is a bit more cumbersome than ordinary L1 to L2 transactions, but it has the advantage that the submission cost is predictable and the ticket will always be available for redemption if the submission cost is paid. As long as there is some user who is willing to redeem the ticket, the L2 transaction will eventually be able to execute and will not be silently dropped. + +### L2 to L1 ticket-based calls + +Calls from L2 to L1 operate in a similar way, with a ticket-based system. An L2 contract can call a method of the precompiled ArbSys contract, to send a transaction to L1. When the execution of the L2 transaction containing the submission is confirmed at L1 (some days later), a ticket is created in the L1 outbox contract. That ticket can be triggered by anyone who calls a certain L1 outbox method and submits the ticketID. The ticket is only marked as redeemed if the L1 transaction does not revert. + +These L2-to-L1 tickets have unlimited lifetime, until they’re successfully redeemed. No rent is required, as the tickets (actually a Merkle hash of the tickets) are recorded in Ethereum storage, which does not require rent. (The cost of allocating storage for the ticket Merkle roots is covered by L2 transaction fees.) + + + + + ## 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. @@ -242,3 +282,73 @@ modifier onlyFromMyL1Contract() override { 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)). + + + + + +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. + + + + +## 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. + + + +### How the Sequencer Publishes the Sequence + +So how do nodes get the sequence? The Sequencer publishes it in two ways: a real-time feed, and batches posted on L1 Ethereum. + +The real-time feed is published by the Sequencer so that anyone who subscribes to the feed receives instant notifications of each transaction as it is sequenced. Nitro nodes can subscribe to the feed directly from the Sequencer, or through a relay that forwards the feed. The feed represents the Sequencer's promise that it will record transactions in a particular order. If the Sequencer is honest and doesn't have a long downtime, this promise will be kept. So anyone who trusts the Sequencer to keep its promises can rely on the feed to get instant information about the transaction sequence--and they can run the sequenced transactions through the state transition function to learn the results of each transaction immediately. This is "soft finality" for transactions; it's "soft" because it depends on the Sequencer keeping its promises. + +The Sequencer also publishes its sequence on the L1 Ethereum chain. Periodically--perhaps every few minutes in production--the Sequencer concatenates the next group of transactions in the feed, compresses them for efficiency, and posts the result as calldata on Ethereum. This is the final and official record of the transaction sequence. As soon as this Ethereum transaction has finality on Ethereum, the Layer 2 Nitro transactions it records will have finality. These transactions are final because their position in the sequence has finality, and the outcome of the transactions is deterministic and knowable to any party. This is "hard finality". + +The Sequencer's batches are compressed using a general-purpose data compression algorithm called "brotli", on its highest-compression setting. + + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx b/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx new file mode 100644 index 000000000..1a6ec991b --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx @@ -0,0 +1,62 @@ + +## Geth at the Core + +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. + + + + +## Separating Execution from Proving + +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---but 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 features of wasm that are not generated by the Go compiler; 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 executing 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. + + + + + + + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/05-validation.mdx b/arbitrum-docs/how-arbitrum-works/05-validation.mdx new file mode 100644 index 000000000..16b9802f4 --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/05-validation.mdx @@ -0,0 +1,295 @@ + +## Optimistic Rollup + +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, 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 is done. 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. But once a 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 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. + + + + + +# The Assertion Tree + +### Overview + +The state of an Arbitrum chain is confirmed back on Ethereum via "assertions," aka "disputable assertions" or "DAs." These are claims made by Arbitrum validators about the chain's state. To make an assertion, a validator must post a bond in Ether. + +In the happy / common case, all outstanding assertions will be valid; i.e., a valid assertion will build on another valid assertion, which builds on another valid assertion, and so on. After the dispute period (~ 1 week) passes and an assertion goes unchallenged, it can be confirmed back on L1. + +If, however, two or more conflicting assertions exist, the Assertion Tree bifurcates into multiple branches: + +![img](../assets/assertionTree.png) + +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. + +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.) + +These properties together ensure that as long as at least one honest, active validator exists, the valid chain state will ultimately be confirmed. + +### Delays + +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. + +### 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). + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx new file mode 100644 index 000000000..cd4c0400a --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx @@ -0,0 +1,150 @@ + +## Challenges + +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. + +## Validators + +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. For more on what such nodes might do, see the [Full Nodes](#full-nodes) section. + +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. + +## ArbOS + +ArbOS is a trusted "system glue" component that runs at Layer 2 as part of the State Transition Function. ArbOS provides functions needed for a Layer 2 system, such as cross-chain communication, resource accounting and Layer 2 related fee economics, and chain management. + +### Why ArbOS? + +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. + +## Full Nodes + +As the name suggests, full nodes in Arbitrum play the same role that full nodes play in Ethereum: they know the state of the chain and they provide an API that others can use to interact with the chain. + +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. + +## The Sequencer + +The Sequencer is a specially designated full node, which is given limited power to control the ordering of transactions. This allows the Sequencer to guarantee the results of user transactions immediately, without needing to wait for anything to happen on Ethereum. So no need to wait five minutes or so for block confirmations--and no need to even wait 15 seconds for Ethereum to make a block. + +Clients interact with the Sequencer in exactly the same way they would interact with any full node, for example by giving their wallet software a network URL that happens to point to the Sequencer. + +[Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. + +### Instant confirmation + +Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. + +The Sequencer is given more control over ordering, so it has the power to assign its clients' transactions a position in the inbox queue, thereby ensuring that it can determine the results of client transactions immediately. The Sequencer's power to reorder has limits (see below for details) but it does have more power than anyone else to influence transaction ordering. + +### Inboxes, fast and slow + +When we add a Sequencer, the operation of the inbox changes. + +- Only the Sequencer can put new messages directly into the inbox. The Sequencer tags the messages it is submitting with an Ethereum block number and timestamp. (ArbOS ensures that these are non-decreasing, adjusting them upward if necessary to avoid decreases.) +- Anyone else can submit a message, but messages submitted by non-Sequencer nodes will be put into the "delayed inbox" queue, which is managed by an L1 Ethereum contract. + - Messages in the delayed inbox queue will wait there until the Sequencer chooses to "release" them into the main inbox, where they will be added to the end of the inbox. A well-behaved Sequencer will typically release delayed messages after about ten minutes, for reasons explained below. + - Alternatively, if a message has been in the delayed inbox queue for longer than a maximum delay interval (currently @arbOneForceIncludePeriodHours@ hours on Arbitrum One) then anyone can force it to be promoted into the main inbox. (This ensures that the Sequencer can only delay messages but can't censor them.) + +### If the Sequencer is well-behaved... + +A well-behaved Sequencer will accept transactions from all requesters and treat them fairly, giving each one a promised transaction result as quickly as it can. + +It will also minimize the delay it imposes on non-Sequencer transactions by releasing delayed messages promptly, consistent with the goal of providing strong promises of transaction results. Specifically, if the Sequencer believes that 40 confirmation blocks are needed to have good confidence of finality on Ethereum, then it will release delayed messages after 40 blocks. This is enough to ensure that the Sequencer knows exactly which transactions will precede its current transaction, because those preceding transactions have finality. There is no need for a benign Sequencer to delay non-Sequencer messages more than that, so it won't. + +This does mean that transactions that go through the delayed inbox will take longer to get finality. Their time to finality will roughly double, because they will have to wait one finality period for promotion, then another finality period for the Ethereum transaction that promoted them to achieve finality. + +This is the basic tradeoff of having a Sequencer: if your message uses the Sequencer, finality is C blocks faster; but if your message doesn't use the Sequencer, finality is C blocks slower. This is usually a good tradeoff, because most transactions will use the Sequencer; and because the practical difference between instant and 10-minute finality is bigger than the difference between 10-minute and 20-minute finality. + +So a Sequencer is generally a win, if the Sequencer is well behaved. + +### If the Sequencer is malicious... + +A malicious Sequencer, on the other hand, could cause some pain. If it refuses to handle your transactions, you're forced to go through the delayed inbox, with longer delay. And a malicious Sequencer has great power to front-run everyone's transactions, so it could profit greatly at users' expense. + +On Arbitrum One, Offchain Labs [currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization) runs a Sequencer which is well-behaved--we promise!. This will be useful but it's not decentralized. Over time, we'll switch to decentralized, fair sequencing, as described below. + +Because the Sequencer will be run by a trusted party at first, and will be decentralized later, we haven't built in a mechanism to directly punish a misbehaving Sequencer. We're asking users to trust the centralized Sequencer at first, until we switch to decentralized fair sequencing later. + +### Decentralized fair sequencing + +Viewed from 30,000 feet, decentralized fair sequencing isn't too complicated. Instead of being a single centralized server, the Sequencer is a committee of servers, and as long as a large enough supermajority of the committee is honest, the Sequencer will establish a fair ordering over transactions. + +How to achieve this is more complicated. Research by a team at Cornell Tech, including Offchain Labs CEO and Co-founder Steven Goldfeder, developed the first-ever decentralized fair sequencing algorithm. With some improvements that are under development, these concepts will form the basis for our longer-term solution, of a fair decentralized Sequencer. + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx new file mode 100644 index 000000000..7834945f9 --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx @@ -0,0 +1,147 @@ +--- +author: dzgoldman +--- + +# Inside AnyTrust + +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. + +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 contains + +- the number of Committee members, and +- for each Committee member, a BLS public key, and +- the number of Committee signatures required. + +Keysets are identified by their hashes. + +An L1 KeysetManager contract maintains a list of currently valid Keysets. The L2 chain's Owner can add or remove Keysets from this list. When a Keyset becomes valid, the KeysetManager contract emits an L1 Ethereum event containing the Keyset's hash and full contents. This allows the contents to be recovered later by anyone, given only the Keyset hash. + +Although the API does not limit the number of Keysets that can be valid at the same time, normally only one Keyset will be valid. + +## Data Availability Certificates + +A central concept in AnyTrust is the Data Availability Certificate (hereafter, a "DACert"). A DACert contains: + +- the hash of a data block, and +- an expiration time, and +- proof that N-1 Committee members have signed the (hash, expiration time) pair, consisting of + - the hash of the Keyset used in signing, and + - 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. + +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. + +The L2 code that reads data from the inbox reads a full-data block as in ordinary Nitro. If it sees a DACert instead, it checks the validity of the DACert, with reference to the Keyset specified by the DACert (which is known to be valid because the L1 Inbox verified that). The L2 code verifies that + +- the number of signers is at least the number required by the Keyset, and +- the aggregated signature is valid for the claimed signers, and +- the expiration time is at least two weeks after the current L2 timestamp. + +If the DACert is invalid, the L2 code discards the DACert and moves on to the next data block. If the DACert is valid, the L2 code reads the data block, which is guaranteed to be available because the DACert is valid. + +## Data Availability Servers + +Committee members run Data Availability Server (DAS) software. The DAS exposes two APIs: + +- The Sequencer API, which is meant to be called only by the Arbitrum chain's Sequencer, is a JSON-RPC interface allowing the Sequencer to submit data blocks to the DAS for storage. Deployments will typically block access to this API from callers other than the Sequencer. +- The REST API, which is meant to be available to the world, is a RESTful HTTP(S) based protocol that allows data blocks to be fetched by hash. This API is fully cacheable, and deployments may use a caching proxy or CDN to increase scale and protect against DoS attacks. + +Only Committee members have reason to support the Sequencer API. We expect others to run the REST API, and that is helpful. (More on that below.) + +The DAS software, based on configuration options, can store its data in local files, or in a Badger database, or on Amazon S3, or redundantly across multiple backing stores. The software also supports optional caching in memory (using Bigcache) or in a Redis instance. + +## 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. + +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. + +If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. + + + + + + + + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx new file mode 100644 index 000000000..880e5490c --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx @@ -0,0 +1,147 @@ +--- +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 + + + +## Gas and Fees + +NitroGas (so-called to avoid confusion with Layer 1 Ethereum 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. + +### 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. + +### Fees + +User transactions pay fees, to cover the cost of operating the chain. These fees are assessed and collected by ArbOS at L2. They are denominated in ETH. + +Fees are charged for two resources that a transaction can use: + +- _L2 gas_: an Ethereum-equivalent amount of gas, as required to execute the transaction on the Nitro chain, + +* _L1 calldata_: a fee per unit of L1 calldata attributable to the transaction, which is charged only if the transaction came in via the Sequencer, and is paid to the Sequencer to cover its costs, + +#### 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" 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. + +#### 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. + +#### 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. + + + + +# 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. + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/why-nitro.mdx b/arbitrum-docs/how-arbitrum-works/09-nitro-vs-classic.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/why-nitro.mdx rename to arbitrum-docs/how-arbitrum-works/09-nitro-vs-classic.mdx 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/assertion-tree.mdx b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx deleted file mode 100644 index a9ce366d5..000000000 --- a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx +++ /dev/null @@ -1,33 +0,0 @@ ---- -author: dzgoldman ---- - -# The Assertion Tree - -### Overview - -The state of an Arbitrum chain is confirmed back on Ethereum via "assertions," aka "disputable assertions" or "DAs." These are claims made by Arbitrum validators about the chain's state. To make an assertion, a validator must post a bond in Ether. - -In the happy / common case, all outstanding assertions will be valid; i.e., a valid assertion will build on another valid assertion, which builds on another valid assertion, and so on. After the dispute period (~ 1 week) passes and an assertion goes unchallenged, it can be confirmed back on L1. - -If, however, two or more conflicting assertions exist, the Assertion Tree bifurcates into multiple branches: - -![img](../assets/assertionTree.png) - -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. - -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.) - -These properties together ensure that as long as at least one honest, active validator exists, the valid chain state will ultimately be confirmed. - -### Delays - -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. - -### 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). 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/inside-anytrust.mdx b/arbitrum-docs/how-arbitrum-works/inside-anytrust.mdx deleted file mode 100644 index c490cdcc2..000000000 --- a/arbitrum-docs/how-arbitrum-works/inside-anytrust.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -author: dzgoldman ---- - -# Inside AnyTrust - -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. - -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 contains - -- the number of Committee members, and -- for each Committee member, a BLS public key, and -- the number of Committee signatures required. - -Keysets are identified by their hashes. - -An L1 KeysetManager contract maintains a list of currently valid Keysets. The L2 chain's Owner can add or remove Keysets from this list. When a Keyset becomes valid, the KeysetManager contract emits an L1 Ethereum event containing the Keyset's hash and full contents. This allows the contents to be recovered later by anyone, given only the Keyset hash. - -Although the API does not limit the number of Keysets that can be valid at the same time, normally only one Keyset will be valid. - -## Data Availability Certificates - -A central concept in AnyTrust is the Data Availability Certificate (hereafter, a "DACert"). A DACert contains: - -- the hash of a data block, and -- an expiration time, and -- proof that N-1 Committee members have signed the (hash, expiration time) pair, consisting of - - the hash of the Keyset used in signing, and - - 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. - -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. - -The L2 code that reads data from the inbox reads a full-data block as in ordinary Nitro. If it sees a DACert instead, it checks the validity of the DACert, with reference to the Keyset specified by the DACert (which is known to be valid because the L1 Inbox verified that). The L2 code verifies that - -- the number of signers is at least the number required by the Keyset, and -- the aggregated signature is valid for the claimed signers, and -- the expiration time is at least two weeks after the current L2 timestamp. - -If the DACert is invalid, the L2 code discards the DACert and moves on to the next data block. If the DACert is valid, the L2 code reads the data block, which is guaranteed to be available because the DACert is valid. - -## Data Availability Servers - -Committee members run Data Availability Server (DAS) software. The DAS exposes two APIs: - -- The Sequencer API, which is meant to be called only by the Arbitrum chain's Sequencer, is a JSON-RPC interface allowing the Sequencer to submit data blocks to the DAS for storage. Deployments will typically block access to this API from callers other than the Sequencer. -- The REST API, which is meant to be available to the world, is a RESTful HTTP(S) based protocol that allows data blocks to be fetched by hash. This API is fully cacheable, and deployments may use a caching proxy or CDN to increase scale and protect against DoS attacks. - -Only Committee members have reason to support the Sequencer API. We expect others to run the REST API, and that is helpful. (More on that below.) - -The DAS software, based on configuration options, can store its data in local files, or in a Badger database, or on Amazon S3, or redundantly across multiple backing stores. The software also supports optional caching in memory (using Bigcache) or in a Redis instance. - -## 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. - -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. - -If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. diff --git a/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx b/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx deleted file mode 100644 index e0ab2b921..000000000 --- a/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx +++ /dev/null @@ -1,677 +0,0 @@ ---- -title: 'Inside Arbitrum Nitro' -sidebar_label: 'Deep dive: Inside Arbitrum' -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, which is used by the Arbitrum Nova chain. AnyTrust is covered by a section at the end of this document. - -## 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, improving over "classic" Arbitrum in several ways: - -- **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. - -## Sequencing, Followed by Deterministic Execution - -This diagram summarizes how transactions are processed in Nitro. - -![seq-then-exec](../assets/seq-then-exec.png) - -Let's follow a user's transaction through this process. - -First, the user creates a transaction, uses their wallet to sign it, and sends it to the Nitro chain's Sequencer. The Sequencer's job, as its name implies, is to take the arriving transactions, put them into an ordered sequence, and publish that sequence. - -Once the transactions are sequenced, they are run through the _state transition function_, one by one, in order. The state transition function takes as input the current state of the chain (account balances, contract code, and so on), along with the next transaction. It updates the state and sometimes emits a new Layer 2 block on the Nitro chain. - -Because the protocol doesn't trust the Sequencer not to put garbage into its sequence, the state transition function will detect and discard any invalid (e.g., improperly formed) transactions in the sequence. A well-behaved Sequencer will filter out invalid transactions so the state transition function never sees them--and this reduces cost and therefore keeps transactions fees low--but Nitro will still work correctly no matter what the Sequencer puts into its feed. (Transactions in the feed are signed by their senders, so the Sequencer can't create forged transactions.) - -The state transition function is deterministic, which means that its behavior depends only on the current state and the contents of the next transaction--and nothing else. Because of this determinism, the result of a transaction T will depend only on the genesis state of the chain, the transactions before T in the sequence, and T itself. - -It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. - -### How the Sequencer Publishes the Sequence - -So how do nodes get the sequence? The Sequencer publishes it in two ways: a real-time feed, and batches posted on L1 Ethereum. - -The real-time feed is published by the Sequencer so that anyone who subscribes to the feed receives instant notifications of each transaction as it is sequenced. Nitro nodes can subscribe to the feed directly from the Sequencer, or through a relay that forwards the feed. The feed represents the Sequencer's promise that it will record transactions in a particular order. If the Sequencer is honest and doesn't have a long downtime, this promise will be kept. So anyone who trusts the Sequencer to keep its promises can rely on the feed to get instant information about the transaction sequence--and they can run the sequenced transactions through the state transition function to learn the results of each transaction immediately. This is "soft finality" for transactions; it's "soft" because it depends on the Sequencer keeping its promises. - -The Sequencer also publishes its sequence on the L1 Ethereum chain. Periodically--perhaps every few minutes in production--the Sequencer concatenates the next group of transactions in the feed, compresses them for efficiency, and posts the result as calldata on Ethereum. This is the final and official record of the transaction sequence. As soon as this Ethereum transaction has finality on Ethereum, the Layer 2 Nitro transactions it records will have finality. These transactions are final because their position in the sequence has finality, and the outcome of the transactions is deterministic and knowable to any party. This is "hard finality". - -The Sequencer's batches are compressed using a general-purpose data compression algorithm called "brotli", on its highest-compression setting. - -## Geth at the Core - -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. - -## Separating Execution from Proving - -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---but 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 features of wasm that are not generated by the Go compiler; 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 executing 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. - -## Optimistic Rollup - -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, 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 is done. 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. But once a 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 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. - -## Challenges - -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. - -## Validators - -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. For more on what such nodes might do, see the [Full Nodes](#full-nodes) section. - -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. - -## ArbOS - -ArbOS is a trusted "system glue" component that runs at Layer 2 as part of the State Transition Function. ArbOS provides functions needed for a Layer 2 system, such as cross-chain communication, resource accounting and Layer 2 related fee economics, and chain management. - -### Why ArbOS? - -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. - -## Full Nodes - -As the name suggests, full nodes in Arbitrum play the same role that full nodes play in Ethereum: they know the state of the chain and they provide an API that others can use to interact with the chain. - -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. - -## The Sequencer - -The Sequencer is a specially designated full node, which is given limited power to control the ordering of transactions. This allows the Sequencer to guarantee the results of user transactions immediately, without needing to wait for anything to happen on Ethereum. So no need to wait five minutes or so for block confirmations--and no need to even wait 15 seconds for Ethereum to make a block. - -Clients interact with the Sequencer in exactly the same way they would interact with any full node, for example by giving their wallet software a network URL that happens to point to the Sequencer. - -[Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. - -### Instant confirmation - -Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. - -The Sequencer is given more control over ordering, so it has the power to assign its clients' transactions a position in the inbox queue, thereby ensuring that it can determine the results of client transactions immediately. The Sequencer's power to reorder has limits (see below for details) but it does have more power than anyone else to influence transaction ordering. - -### Inboxes, fast and slow - -When we add a Sequencer, the operation of the inbox changes. - -- Only the Sequencer can put new messages directly into the inbox. The Sequencer tags the messages it is submitting with an Ethereum block number and timestamp. (ArbOS ensures that these are non-decreasing, adjusting them upward if necessary to avoid decreases.) -- Anyone else can submit a message, but messages submitted by non-Sequencer nodes will be put into the "delayed inbox" queue, which is managed by an L1 Ethereum contract. - - Messages in the delayed inbox queue will wait there until the Sequencer chooses to "release" them into the main inbox, where they will be added to the end of the inbox. A well-behaved Sequencer will typically release delayed messages after about ten minutes, for reasons explained below. - - Alternatively, if a message has been in the delayed inbox queue for longer than a maximum delay interval (currently @arbOneForceIncludePeriodHours@ hours on Arbitrum One) then anyone can force it to be promoted into the main inbox. (This ensures that the Sequencer can only delay messages but can't censor them.) - -### If the Sequencer is well-behaved... - -A well-behaved Sequencer will accept transactions from all requesters and treat them fairly, giving each one a promised transaction result as quickly as it can. - -It will also minimize the delay it imposes on non-Sequencer transactions by releasing delayed messages promptly, consistent with the goal of providing strong promises of transaction results. Specifically, if the Sequencer believes that 40 confirmation blocks are needed to have good confidence of finality on Ethereum, then it will release delayed messages after 40 blocks. This is enough to ensure that the Sequencer knows exactly which transactions will precede its current transaction, because those preceding transactions have finality. There is no need for a benign Sequencer to delay non-Sequencer messages more than that, so it won't. - -This does mean that transactions that go through the delayed inbox will take longer to get finality. Their time to finality will roughly double, because they will have to wait one finality period for promotion, then another finality period for the Ethereum transaction that promoted them to achieve finality. - -This is the basic tradeoff of having a Sequencer: if your message uses the Sequencer, finality is C blocks faster; but if your message doesn't use the Sequencer, finality is C blocks slower. This is usually a good tradeoff, because most transactions will use the Sequencer; and because the practical difference between instant and 10-minute finality is bigger than the difference between 10-minute and 20-minute finality. - -So a Sequencer is generally a win, if the Sequencer is well behaved. - -### If the Sequencer is malicious... - -A malicious Sequencer, on the other hand, could cause some pain. If it refuses to handle your transactions, you're forced to go through the delayed inbox, with longer delay. And a malicious Sequencer has great power to front-run everyone's transactions, so it could profit greatly at users' expense. - -On Arbitrum One, Offchain Labs [currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization) runs a Sequencer which is well-behaved--we promise!. This will be useful but it's not decentralized. Over time, we'll switch to decentralized, fair sequencing, as described below. - -Because the Sequencer will be run by a trusted party at first, and will be decentralized later, we haven't built in a mechanism to directly punish a misbehaving Sequencer. We're asking users to trust the centralized Sequencer at first, until we switch to decentralized fair sequencing later. - -### Decentralized fair sequencing - -Viewed from 30,000 feet, decentralized fair sequencing isn't too complicated. Instead of being a single centralized server, the Sequencer is a committee of servers, and as long as a large enough supermajority of the committee is honest, the Sequencer will establish a fair ordering over transactions. - -How to achieve this is more complicated. Research by a team at Cornell Tech, including Offchain Labs CEO and Co-founder Steven Goldfeder, developed the first-ever decentralized fair sequencing algorithm. With some improvements that are under development, these concepts will form the basis for our longer-term solution, of a fair decentralized Sequencer. - -## Bridging - -We have already 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. Let’s talk about how contracts interact between L1 and L2--how an L1 contract calls an L2 contract, and vice versa. - -The 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. As a consequence, a cross-chain contract-to-contract call can never produce a result that is available to the calling contract (except for acknowledgement that the call was successfully submitted for later execution). - -### L1 contracts can submit L2 transactions - -An L1 contract can submit an L2 transaction, just like a user would, by calling the Nitro chain's inbox contract on Ethereum. This L2 transaction will run later, producing results that will not be available to the L1 caller. The transaction will execute at L2, but the L1 caller won’t be able to see any results from the L2 transaction. - -The advantage of this method is that it is simple and has relatively low latency. The disadvantage, compared to the other method we’ll describe soon, is that the L2 transaction might revert if the L1 caller doesn’t get the L2 gas price and max gas amount right. Because the L1 caller can’t see the result of its L2 transaction, it can’t be absolutely sure that its L2 transaction will succeed. - -This would introduce a serious a problem for certain types of L1 to L2 interactions. Consider a transaction that includes depositing a token on L1 to be made available at some address on L2. If the L1 side succeeds, but the L2 side reverts, you've just sent some tokens to the L1 inbox contract that are unrecoverable on either L2 or L1. Not good. - -### L1 to L2 ticket-based transactions - -Fortunately, we have another method for L1 to L2 calls, which is more robust against gas-related failures, that uses a ticket-based system. The idea is that an L1 contract can submit a “retryable” transaction. The Nitro chain will try to run that transaction. If the transaction succeeds, nothing else needs to happen. But if the transaction fails, Nitro will create a “ticketID” that identifies that failed transaction. Later, anyone can call a special pre-compiled contract at L2, providing the ticketID, to try redeeming the ticket and re-executing the transaction. - -When saving a transaction for retry, Nitro records the sender’s address, destination address, callvalue, and calldata. All of this is saved, and the callvalue is deducted from the sender’s account and (logically) attached to the saved transaction. - -If the redemption succeeds, the transaction is done, a receipt is issued for it, and the ticketID is canceled and can’t be used again. If the redemption fails, for example because the packaged transaction fails, the redemption reports failure and the ticketID remains available for redemption. - -Normally the original submitter will try to cause their transaction to succeed immediately, so it never needs to be recorded or retried. As an example, our "token deposit" use case above should, in the happy, common case, still only require a single signature from the user. If this initial execution fails, the ticketID will still exist as a backstop which others can redeem later. - -Submitting a transaction in this way carries a price in ETH which the submitter must pay, which varies based on the calldata size of the transaction. Once submitted, the ticket is valid for about a week. If the ticket has not been redeemed in that period, it is deleted. - -When the ticket is redeemed, the pre-packaged transaction runs with sender and origin equal to the original submitter, and with the destination, callvalue, and calldata the submitter provided at the time of submission. - -This mechanism is a bit more cumbersome than ordinary L1 to L2 transactions, but it has the advantage that the submission cost is predictable and the ticket will always be available for redemption if the submission cost is paid. As long as there is some user who is willing to redeem the ticket, the L2 transaction will eventually be able to execute and will not be silently dropped. - -### L2 to L1 ticket-based calls - -Calls from L2 to L1 operate in a similar way, with a ticket-based system. An L2 contract can call a method of the precompiled ArbSys contract, to send a transaction to L1. When the execution of the L2 transaction containing the submission is confirmed at L1 (some days later), a ticket is created in the L1 outbox contract. That ticket can be triggered by anyone who calls a certain L1 outbox method and submits the ticketID. The ticket is only marked as redeemed if the L1 transaction does not revert. - -These L2-to-L1 tickets have unlimited lifetime, until they’re successfully redeemed. No rent is required, as the tickets (actually a Merkle hash of the tickets) are recorded in Ethereum storage, which does not require rent. (The cost of allocating storage for the ticket Merkle roots is covered by L2 transaction fees.) - -## Gas and Fees - -NitroGas (so-called to avoid confusion with Layer 1 Ethereum 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. - -### 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. - -### Fees - -User transactions pay fees, to cover the cost of operating the chain. These fees are assessed and collected by ArbOS at L2. They are denominated in ETH. - -Fees are charged for two resources that a transaction can use: - -- _L2 gas_: an Ethereum-equivalent amount of gas, as required to execute the transaction on the Nitro chain, - -* _L1 calldata_: a fee per unit of L1 calldata attributable to the transaction, which is charged only if the transaction came in via the Sequencer, and is paid to the Sequencer to cover its costs, - -#### 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" 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. - -#### 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. - -#### 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. - -## Inside AnyTrust - -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 bond 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. - -### 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 contains - -- the number of Committee members, and -- for each Committee member, a BLS public key, and -- the number of Committee signatures required. - -Keysets are identified by their hashes. - -An L1 KeysetManager contract maintains a list of currently valid Keysets. The L2 chain's Owner can add or remove Keysets from this list. When a Keyset becomes valid, the KeysetManager contract emits an L1 Ethereum event containing the Keyset's hash and full contents. This allows the contents to be recovered later by anyone, given only the Keyset hash. - -Although the API does not limit the number of Keysets that can be valid at the same time, normally only one Keyset will be valid. - -### Data Availability Certificates - -A central concept in AnyTrust is the Data Availability Certificate (hereafter, a "DACert"). A DACert contains: - -- the hash of a data block, and -- an expiration time, and -- proof that N-1 Committee members have signed the (hash, expiration time) pair, consisting of - - the hash of the Keyset used in signing, and - - 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. - -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. - -The L2 code that reads data from the inbox reads a full-data block as in ordinary Nitro. If it sees a DACert instead, it checks the validity of the DACert, with reference to the Keyset specified by the DACert (which is known to be valid because the L1 Inbox verified that). The L2 code verifies that - -- the number of signers is at least the number required by the Keyset, and -- the aggregated signature is valid for the claimed signers, and -- the expiration time is at least two weeks after the current L2 timestamp. - -If the DACert is invalid, the L2 code discards the DACert and moves on to the next data block. If the DACert is valid, the L2 code reads the data block, which is guaranteed to be available because the DACert is valid. - -### Data Availability Servers - -Committee members run Data Availability Server (DAS) software. The DAS exposes two APIs: - -- The Sequencer API, which is meant to be called only by the Arbitrum chain's Sequencer, is a JSON-RPC interface allowing the Sequencer to submit data blocks to the DAS for storage. Deployments will typically block access to this API from callers other than the Sequencer. -- The REST API, which is meant to be available to the world, is a RESTful HTTP(S) based protocol that allows data blocks to be fetched by hash. This API is fully cacheable, and deployments may use a caching proxy or CDN to increase scale and protect against DoS attacks. - -Only Committee members have reason to support the Sequencer API. We expect others to run the REST API, and that is helpful. (More on that below.) - -The DAS software, based on configuration options, can store its data in local files, or in a Badger database, or on Amazon S3, or redundantly across multiple backing stores. The software also supports optional caching in memory (using Bigcache) or in a Redis instance. - -### 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. - -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. - -If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. 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-sdk b/arbitrum-sdk index f5b3d04ba..5ef44308d 160000 --- a/arbitrum-sdk +++ b/arbitrum-sdk @@ -1 +1 @@ -Subproject commit f5b3d04baf62356032f5475057637d989da5b6c1 +Subproject commit 5ef44308d3c89fd956c9dfdc59b6776b88afd251 From 6fc2384ff8fbbac485d8a01c01a3b4dff24c651e Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 21 Nov 2024 15:34:50 -0600 Subject: [PATCH 02/35] consolidated more how arbitrum works content --- .../04-state-transition-function.mdx | 400 +++++++++++++++++ .../how-arbitrum-works/06-challenges.mdx | 407 ++++++++++++++++++ .../how-arbitrum-works/arbos/geth.mdx | 292 ------------- .../how-arbitrum-works/arbos/introduction.mdx | 102 ----- .../fraud-proofs/challenge-manager.mdx | 64 --- .../fraud-proofs/osp-assumptions.mdx | 75 ---- .../fraud-proofs/wasm-wavm.mdx | 61 --- .../fraud-proofs/wavm-custom-opcodes.mdx | 74 ---- .../fraud-proofs/wavm-floats.mdx | 32 -- .../fraud-proofs/wavm-modules.mdx | 57 --- 10 files changed, 807 insertions(+), 757 deletions(-) delete mode 100644 arbitrum-docs/how-arbitrum-works/arbos/geth.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/arbos/introduction.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/fraud-proofs/challenge-manager.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/fraud-proofs/osp-assumptions.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-floats.mdx delete mode 100644 arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-modules.mdx diff --git a/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx b/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx index 1a6ec991b..6cd48612e 100644 --- a/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx @@ -59,4 +59,404 @@ This "hash oracle trick" of storing the Merkle hash of a data structure, and rel + + + + +# ArbOS + +ArbOS is the Layer 2 EVM hypervisor that facilitates the execution environment of L2 Arbitrum. ArbOS accounts for and manages network resources, produces blocks from incoming messages, and operates its instrumented instance of Geth for smart contract execution. + +## 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/arbos/l1-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](geth#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](geth#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 + + + + + +# 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`](#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/introduction.mdx#Retryables) 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/introduction.mdx#Retryables) 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 + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx index cd4c0400a..e92b34908 100644 --- a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx @@ -147,4 +147,411 @@ Because the Sequencer will be run by a trusted party at first, and will be decen Viewed from 30,000 feet, decentralized fair sequencing isn't too complicated. Instead of being a single centralized server, the Sequencer is a committee of servers, and as long as a large enough supermajority of the committee is honest, the Sequencer will establish a fair ordering over transactions. How to achieve this is more complicated. Research by a team at Cornell Tech, including Offchain Labs CEO and Co-founder Steven Goldfeder, developed the first-ever decentralized fair sequencing algorithm. With some improvements that are under development, these concepts will form the basis for our longer-term solution, of a fair decentralized Sequencer. + + + + +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. + + + + + + + + +# 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.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. + + + + + + + + +# 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. | + + + + + + + + +# 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. + \ No newline at end of file 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 0abe01222..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`](#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/introduction.mdx#Retryables) 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/introduction.mdx#Retryables) 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/introduction.mdx b/arbitrum-docs/how-arbitrum-works/arbos/introduction.mdx deleted file mode 100644 index d9083022c..000000000 --- a/arbitrum-docs/how-arbitrum-works/arbos/introduction.mdx +++ /dev/null @@ -1,102 +0,0 @@ -# ArbOS - -ArbOS is the Layer 2 EVM hypervisor that facilitates the execution environment of L2 Arbitrum. ArbOS accounts for and manages network resources, produces blocks from incoming messages, and operates its instrumented instance of Geth for smart contract execution. - -## 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/arbos/l1-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](geth#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](geth#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/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. From 2f5214d2d5eddf15a1b540132251082c56783380 Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 21 Nov 2024 15:51:23 -0600 Subject: [PATCH 03/35] adjusted sidebars.js --- website/sidebars.js | 178 ++++++++++++-------------------------------- 1 file changed, 48 insertions(+), 130 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index 54aac2874..fa584892e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -814,136 +814,56 @@ 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: 'category', - label: 'Advanced concepts', - collapsed: true, - items: [ - { - type: 'doc', - id: 'how-arbitrum-works/inside-arbitrum-nitro', - label: 'Deep dive: Inside Arbitrum', - }, - { - type: 'link', - href: 'https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf', - label: 'Deeper dive: Whitepaper', - }, - { - type: 'doc', - id: 'how-arbitrum-works/assertion-tree', - label: 'Assertion tree', - }, - { - type: 'doc', - id: 'how-arbitrum-works/why-nitro', - label: 'Nitro vs. Classic', - }, - { - 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: '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: '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: 'doc', + id: 'how-arbitrum-works/transaction-lifecycle', + label: 'Transaction Lifecycle', + }, + { + type: 'doc', + id: 'how-arbitrum-works/sequencer', + label: 'Sequencer', + }, + { + type: 'doc', + id: 'how-arbitrum-works/state-transition-function', + label: 'State Transition Function', + }, + { + type: 'doc', + id: 'how-arbitrum-works/validation', + label: 'Validation', + }, + { + type: 'doc', + id: 'how-arbitrum-works/challenges', + label: 'Challenges', + }, + { + type: 'doc', + id: 'how-arbitrum-works/anytrust-protocol', + label: 'AnyTrust protocol', + }, + { + type: 'doc', + id: 'how-arbitrum-works/gas-fees', + label: 'Gas/fees', + }, + { + type: 'doc', + id: 'how-arbitrum-works/nitro-vs-classic', + label: 'Nitro vs. Classic', + }, + { + type: 'link', + href: 'https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf', + label: 'Nitro whitepaper', + }, + { type: 'category', label: 'The BoLD dispute protocol', @@ -996,8 +916,6 @@ const sidebars = { ], }, ], - }, - ], }, { type: 'doc', From 918832cfd2cb68714836b1e45776bf169f327f7f Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 22 Nov 2024 09:55:30 -0600 Subject: [PATCH 04/35] Restructured content further, added new sections --- .../how-arbitrum-works/03-sequencer.mdx | 254 ------------------ .../how-arbitrum-works/06-challenges.mdx | 85 ++++++ .../09-retryable-tickets.mdx | 247 +++++++++++++++++ .../10-cross-chain-messaging.mdx | 23 ++ ...vs-classic.mdx => 11-nitro-vs-classic.mdx} | 0 5 files changed, 355 insertions(+), 254 deletions(-) create mode 100644 arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx create mode 100644 arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx rename arbitrum-docs/how-arbitrum-works/{09-nitro-vs-classic.mdx => 11-nitro-vs-classic.mdx} (100%) diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 64205f57d..a00303343 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -54,261 +54,7 @@ These L2-to-L1 tickets have unlimited lifetime, until they’re successfully red - -## 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 Lifecycle - -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. - -| 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 - - - - 🧍 - Initiating an L1-L2 message - Enough deposit? - Ticket creation fails - Ticket is created - - - - - - - - 🧍 The user who initiates an L1-L2 message - - - Initiating an L1-L2 message A call to `inbox.createRetryableTicket` function that - puts the message in the L2 inbox that can be re-executed for some fixed amount of time if it - reverts - - - Check user's deposit Logic that checks if the user have enough funds to create a - ticket. This is done by checking if the `msg.value` provided by the user is greater than or - equal to maxSubmissionCost + l2CallValue + gasLimit * maxFeePerGas - - - Ticket creation fails Ticket creation fails and no funds are deducted from the - user - - - Ticket is created A ticket is created and added to the retryable buffer on L2 - Funds (l2CallValue + submissionCost) are deducted to cover the callvalue from the - user and placed into escrow (on L2) for later use in redeeming the ticket - - - - -### Automatic Redemption - -4. It is very important to note that the submission of a ticket on L1 is separable / asynchronous from its execution on L2, i.e., a successful L1 ticket creation does not guarantee a successful redemption. Once the ticket is successfully created, the two following conditions are checked: (1) if the user's L2 balance is greater than (or equal to) `maxFeePerGas * gasLimit` **and** (2) if the `maxFeePerGas` (provided by the user in the ticket submission process) is greater than (or equal to) the `l2Basefee`. If these conditions are both met, ticket's submission is followed by an attempt to execute it on L2 (i.e., an **auto-redeem** using the supplied gas, as if the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile had been called). Depending on how much gas the sender has provided in step 1, ticket's redemption can either (1) immediately succeed or (2) fail. We explain both situations here: - -- If the ticket is successfully auto-redeemed, it will execute with the sender, destination, callvalue, and calldata of the original submission. The submission fee is refunded to the user on L2 (`excessFeeRefundAddress`). Note that to ensure successful auto-redeem of the ticket, one could use the Arbitrum SDK which provides a [convenience function](https://github.com/OffchainLabs/arbitrum-sdk/blob/4cedb1fcf1c7302a4c3d0f8e75fb33d82bc8338d/src/lib/message/L1ToL2MessageGasEstimator.ts#L215) that returns the desired gas parameters when sending L1-L2 messages. - -- If a redeem is not done at submission or the submission's initial redeem fails (for example, because the L2 gas price has increased unexpectedly), the submission fee is collected on L2 to cover the resources required to temporarily keep the ticket in memory for a fixed period (one week), and only in this case, a manual redemption of the ticket is required (see next section). - - - - Auto-redeem succeeds? - Ticket is executed - Ticket is deleted - callValueRefundAddress gets refunded - - - - - - - Does the auto-redeem succeed? Logic that determines if the user's L2 Balance is - greater than (or equal to) maxFeePerGas * gasLimit && maxFeePerGas{' '} - is greater than (or equal to) the l2Basefee - - - Ticket is executed Ticket is executed, the actual submissionFee is - refunded to the excessFeeRefundAddress since the ticket was not kept in the - buffer on L2 - - - Ticket is deleted Ticket gets deleted from the L2 retryable buffer - - - callValueRefundAddress gets refunded callValueRefundAddress gets - refunded with (maxGas - gasUsed) * gasPrice. Note that this amount is capped by{' '} - l1CallValue in the auto-redeem - - - - -### 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. - -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. - -[enqueue_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L245 -[exhaust_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L135 -[discard_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/retryables/retryable.go#L262 -[renew_link]: https://github.com/OffchainLabs/nitro-contracts/blob/a68783436b5105a64f54efe5fbd55174704a7618/src/precompiles/ArbRetryableTx.sol#L41 - - - - Ticket manually cancelled or not redeemed in 7 days? - callValueRefundAddress gets refunded - Ticket is deleted - Ticket manually redeemed? - - - - - - - - - Is the ticket manually cancelled or not redeemed within 7 days? Logic that - determines if the ticket is manually cancelled or not redeemed within 7 days (i.e., is - expired) - - - callValueRefundAddress gets refunded callValueRefundAddress is refunded with the{' '} - l2CallValue - - - Ticket is deleted Ticket gets deleted from the L2 retryable buffer - - - Is the ticket manually redeemed Logic that determines if the ticket is manually - redeemed - - - -:::caution Avoid Losing Funds! - -If a ticket expires after 7 days without being redeemed or re-scheduled to a future date, any message and value (other than the escrowed `callvalue`) it carries could be lost without possibility of being recovered. - -::: - -On success, the `To` address receives the escrowed callvalue, and any unused gas is returned to ArbOS's gas pools. On failure, the callvalue is returned to the escrow for the future redeem attempt. In either case, the network fee was paid during the scheduling tx, so no fees are charged and no refunds are made. - -Note that during redemption of a ticket, attempts to cancel the same ticket, or to schedule another redeem of the same ticket, will revert. In this manner retryable tickets are not self-modifying. - -If a ticket with a callvalue is eventually discarded (cancelled or expired), having never successfully run, the escrowed callvalue will be paid out to a `callValueRefundAddress` account that was specified in the initial submission (step 1). - -:::note Important Notes: - -If a redeem is not done at submission or the submission's initial redeem fails, anyone can attempt to redeem the retryable 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. 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 transaction 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. - -- One can redeem live tickets using the [Arbitrum Retryables Transaction Panel][retryable_dashboard_link] -- The calldata of a ticket is saved on L2 until it is redeemed or expired -- Redeeming cost of a ticket will not increase over time, it only depends on the current gas price and gas required for execution - -::: - -[retryable_dashboard_link]: https://retryable-dashboard.arbitrum.io/tx - -### Receipts - -In the lifecycle of a retryable ticket, two types of L2 transaction receipts will be emitted: - -- **Ticket Creation Receipt**: This receipt indicates that a ticket was successfully created; any successful L1 call to the `Inbox`'s `createRetryableTicket` method is guaranteed to create a ticket. The ticket creation receipt includes a `TicketCreated` event (from `ArbRetryableTx`), which includes a `ticketId` field. This `ticketId` is computable via RLP encoding and hashing the transaction; see [calculateSubmitRetryableId](https://github.com/OffchainLabs/arbitrum-sdk/blob/6cc143a3bb019dc4c39c8bcc4aeac9f1a48acb01/src/lib/message/L1ToL2Message.ts#L109). -- **Redeem Attempt**: A redeem attempt receipt represents the result of an attempted L2 execution of a ticket, i.e, success / failure of that specific redeem attempt. It includes a `RedeemScheduled` event from `ArbRetryableTx`, with a `ticketId` field. At most, one successful redeem attempt can ever exist for a given ticket; if, e.g., the auto-redeem upon initial creation succeeds, only the receipt from the auto-redeem will ever get emitted for that ticket. If the auto-redeem fails (or was never attempted — i.e., the provided L2 gas limit \* L2 gas price = 0), each initial attempt will emit a redeem attempt receipt until one succeeds. - -### 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. - -## Eth deposits - -A special message type exists for simple Eth deposits; i.e., sending Eth from L1 to L2. Eth can be deposited via a call to the `Inbox`'s `depositEth` method. If the L1 caller is EOA, the Eth will be deposited to the same EOA address on L2; the L1 caller is a contract, the funds will deposited to the contract's aliased address (see below). - -Note that depositing Eth via `depositEth` into a contract on L2 will _not_ trigger the contract's fallback function. - -In principle, retryable tickets can alternatively be used to deposit Ether; this could be preferable to the special eth-deposit message type if, e.g., more flexibility for the destination address is needed, or if one wants to trigger the fallback function on the L2 side. - -## 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. - -### Address Aliasing - -Unsigned messages submitted via the Delayed Inbox get their sender's addressed "aliased": when these messages are executed on L2, the sender's address —i.e., that which is returned by `msg.sender` — will _not_ simply be the L1 address that sent the message; rather it will be the address's "L2 Alias." An address's L2 alias is its value increased by the hex value `0x1111000000000000000000000000000000001111`: - -```sol -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. - -If for some reason you need to compute the L1 address from an L2 alias on chain, you can use our `AddressAliasHelper` library: - -```sol -modifier onlyFromMyL1Contract() override { - require(AddressAliasHelper.undoL1ToL2Alias(msg.sender) == myL1ContractAddress, "ONLY_COUNTERPART_CONTRACT"); - _; -} -``` - -### 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. - -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)). - - - - - -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. - - ## Happy/Common Case: Sequencer Is Live and Well-behaved diff --git a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx index e92b34908..8fee1d232 100644 --- a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx @@ -17,6 +17,9 @@ The game will operate in two phases: dissection, followed by one-step proof. Dis 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. @@ -27,6 +30,9 @@ Now Alice has effectively bisected her N-step assertion into two (N/2)-step asse 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. @@ -37,6 +43,9 @@ To prove (2), observe that if Alice’s initial claim is incorrect, this can onl (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. @@ -53,12 +62,18 @@ The real dissection protocol is conceptually similar to the simplified one descr 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. + + + ## Validators 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. @@ -83,22 +98,32 @@ Who will be validators? Anyone will be able to do it, but most people will choos - 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. + + + ## ArbOS ArbOS is a trusted "system glue" component that runs at Layer 2 as part of the State Transition Function. ArbOS provides functions needed for a Layer 2 system, such as cross-chain communication, resource accounting and Layer 2 related fee economics, and chain management. + + + ### Why ArbOS? 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. + + ## Full Nodes As the name suggests, full nodes in Arbitrum play the same role that full nodes play in Ethereum: they know the state of the chain and they provide an API that others can use to interact with the chain. 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. + + ## The Sequencer The Sequencer is a specially designated full node, which is given limited power to control the ordering of transactions. This allows the Sequencer to guarantee the results of user transactions immediately, without needing to wait for anything to happen on Ethereum. So no need to wait five minutes or so for block confirmations--and no need to even wait 15 seconds for Ethereum to make a block. @@ -107,12 +132,18 @@ Clients interact with the Sequencer in exactly the same way they would interact [Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. + + + ### Instant confirmation Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. The Sequencer is given more control over ordering, so it has the power to assign its clients' transactions a position in the inbox queue, thereby ensuring that it can determine the results of client transactions immediately. The Sequencer's power to reorder has limits (see below for details) but it does have more power than anyone else to influence transaction ordering. + + + ### Inboxes, fast and slow When we add a Sequencer, the operation of the inbox changes. @@ -122,6 +153,8 @@ When we add a Sequencer, the operation of the inbox changes. - Messages in the delayed inbox queue will wait there until the Sequencer chooses to "release" them into the main inbox, where they will be added to the end of the inbox. A well-behaved Sequencer will typically release delayed messages after about ten minutes, for reasons explained below. - Alternatively, if a message has been in the delayed inbox queue for longer than a maximum delay interval (currently @arbOneForceIncludePeriodHours@ hours on Arbitrum One) then anyone can force it to be promoted into the main inbox. (This ensures that the Sequencer can only delay messages but can't censor them.) + + ### If the Sequencer is well-behaved... A well-behaved Sequencer will accept transactions from all requesters and treat them fairly, giving each one a promised transaction result as quickly as it can. @@ -134,6 +167,8 @@ This is the basic tradeoff of having a Sequencer: if your message uses the Seque So a Sequencer is generally a win, if the Sequencer is well behaved. + + ### If the Sequencer is malicious... A malicious Sequencer, on the other hand, could cause some pain. If it refuses to handle your transactions, you're forced to go through the delayed inbox, with longer delay. And a malicious Sequencer has great power to front-run everyone's transactions, so it could profit greatly at users' expense. @@ -142,6 +177,8 @@ On Arbitrum One, Offchain Labs [currently](https://docs.arbitrum.foundation/stat Because the Sequencer will be run by a trusted party at first, and will be decentralized later, we haven't built in a mechanism to directly punish a misbehaving Sequencer. We're asking users to trust the centralized Sequencer at first, until we switch to decentralized fair sequencing later. + + ### Decentralized fair sequencing Viewed from 30,000 feet, decentralized fair sequencing isn't too complicated. Instead of being a single centralized server, the Sequencer is a committee of servers, and as long as a large enough supermajority of the committee is honest, the Sequencer will establish a fair ordering over transactions. @@ -159,6 +196,8 @@ The `ChallengeManager` arbitrates challenge games. Here's a diagram of the chall + + ## Block challenge The challenge begins by bisecting over global states (including block hashes). @@ -168,6 +207,8 @@ Once the challenge has been bisected down to an individual block, 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. @@ -177,6 +218,8 @@ 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._ @@ -207,6 +250,8 @@ Note that unlike in a traditional bisection protocol, where one party proposes s 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. @@ -250,6 +295,8 @@ 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. @@ -261,6 +308,8 @@ mismatch types, or do any other number of invalid things which are prevented by 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. @@ -271,6 +320,8 @@ 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. @@ -282,6 +333,8 @@ 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. @@ -290,6 +343,8 @@ 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. @@ -313,6 +368,8 @@ This document lists those which are not, and explains how they're expressed in W 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. @@ -323,6 +380,8 @@ 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: @@ -341,6 +400,8 @@ end `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, @@ -349,10 +410,14 @@ 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. @@ -361,6 +426,8 @@ Then, a loop checks `IsStackBoundary` (which implicitly pops a value) until it's 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. @@ -383,6 +450,8 @@ 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, @@ -390,6 +459,8 @@ 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. @@ -419,6 +490,8 @@ The above opcodes eliminate the need for the following WASM opcodes (which are t - br_table - local.tee + + ## Linking This is only generated to link modules together. @@ -429,6 +502,8 @@ which handles the actual work needed to change modules. | ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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". @@ -484,6 +559,8 @@ and floating points may be used outside core state transition code for imprecise 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. @@ -515,6 +592,8 @@ 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`, @@ -523,6 +602,8 @@ 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, @@ -533,6 +614,8 @@ Their type signature is also the same, except all `f32`s and `f64`s are bitcaste 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__*"`. @@ -541,6 +624,8 @@ 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", diff --git a/arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx b/arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx new file mode 100644 index 000000000..a8cc6781f --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx @@ -0,0 +1,247 @@ + +## 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 Lifecycle + +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. + +| 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 + + + + 🧍 + Initiating an L1-L2 message + Enough deposit? + Ticket creation fails + Ticket is created + + + + + + + + 🧍 The user who initiates an L1-L2 message + + + Initiating an L1-L2 message A call to `inbox.createRetryableTicket` function that + puts the message in the L2 inbox that can be re-executed for some fixed amount of time if it + reverts + + + Check user's deposit Logic that checks if the user have enough funds to create a + ticket. This is done by checking if the `msg.value` provided by the user is greater than or + equal to maxSubmissionCost + l2CallValue + gasLimit * maxFeePerGas + + + Ticket creation fails Ticket creation fails and no funds are deducted from the + user + + + Ticket is created A ticket is created and added to the retryable buffer on L2 + Funds (l2CallValue + submissionCost) are deducted to cover the callvalue from the + user and placed into escrow (on L2) for later use in redeeming the ticket + + + + + + +### Automatic Redemption + +4. It is very important to note that the submission of a ticket on L1 is separable / asynchronous from its execution on L2, i.e., a successful L1 ticket creation does not guarantee a successful redemption. Once the ticket is successfully created, the two following conditions are checked: (1) if the user's L2 balance is greater than (or equal to) `maxFeePerGas * gasLimit` **and** (2) if the `maxFeePerGas` (provided by the user in the ticket submission process) is greater than (or equal to) the `l2Basefee`. If these conditions are both met, ticket's submission is followed by an attempt to execute it on L2 (i.e., an **auto-redeem** using the supplied gas, as if the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile had been called). Depending on how much gas the sender has provided in step 1, ticket's redemption can either (1) immediately succeed or (2) fail. We explain both situations here: + +- If the ticket is successfully auto-redeemed, it will execute with the sender, destination, callvalue, and calldata of the original submission. The submission fee is refunded to the user on L2 (`excessFeeRefundAddress`). Note that to ensure successful auto-redeem of the ticket, one could use the Arbitrum SDK which provides a [convenience function](https://github.com/OffchainLabs/arbitrum-sdk/blob/4cedb1fcf1c7302a4c3d0f8e75fb33d82bc8338d/src/lib/message/L1ToL2MessageGasEstimator.ts#L215) that returns the desired gas parameters when sending L1-L2 messages. + +- If a redeem is not done at submission or the submission's initial redeem fails (for example, because the L2 gas price has increased unexpectedly), the submission fee is collected on L2 to cover the resources required to temporarily keep the ticket in memory for a fixed period (one week), and only in this case, a manual redemption of the ticket is required (see next section). + + + + Auto-redeem succeeds? + Ticket is executed + Ticket is deleted + callValueRefundAddress gets refunded + + + + + + + Does the auto-redeem succeed? Logic that determines if the user's L2 Balance is + greater than (or equal to) maxFeePerGas * gasLimit && maxFeePerGas{' '} + is greater than (or equal to) the l2Basefee + + + Ticket is executed Ticket is executed, the actual submissionFee is + refunded to the excessFeeRefundAddress since the ticket was not kept in the + buffer on L2 + + + Ticket is deleted Ticket gets deleted from the L2 retryable buffer + + + callValueRefundAddress gets refunded callValueRefundAddress gets + refunded with (maxGas - gasUsed) * gasPrice. Note that this amount is capped by{' '} + l1CallValue in the auto-redeem + + + + + + +### 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. + +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. + +[enqueue_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L245 +[exhaust_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/block_processor.go#L135 +[discard_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/retryables/retryable.go#L262 +[renew_link]: https://github.com/OffchainLabs/nitro-contracts/blob/a68783436b5105a64f54efe5fbd55174704a7618/src/precompiles/ArbRetryableTx.sol#L41 + + + + Ticket manually cancelled or not redeemed in 7 days? + callValueRefundAddress gets refunded + Ticket is deleted + Ticket manually redeemed? + + + + + + + + + Is the ticket manually cancelled or not redeemed within 7 days? Logic that + determines if the ticket is manually cancelled or not redeemed within 7 days (i.e., is + expired) + + + callValueRefundAddress gets refunded callValueRefundAddress is refunded with the{' '} + l2CallValue + + + Ticket is deleted Ticket gets deleted from the L2 retryable buffer + + + Is the ticket manually redeemed Logic that determines if the ticket is manually + redeemed + + + + +:::caution Avoid Losing Funds! + +If a ticket expires after 7 days without being redeemed or re-scheduled to a future date, any message and value (other than the escrowed `callvalue`) it carries could be lost without possibility of being recovered. + +::: + +On success, the `To` address receives the escrowed callvalue, and any unused gas is returned to ArbOS's gas pools. On failure, the callvalue is returned to the escrow for the future redeem attempt. In either case, the network fee was paid during the scheduling tx, so no fees are charged and no refunds are made. + +Note that during redemption of a ticket, attempts to cancel the same ticket, or to schedule another redeem of the same ticket, will revert. In this manner retryable tickets are not self-modifying. + +If a ticket with a callvalue is eventually discarded (cancelled or expired), having never successfully run, the escrowed callvalue will be paid out to a `callValueRefundAddress` account that was specified in the initial submission (step 1). + +:::note Important Notes: + +If a redeem is not done at submission or the submission's initial redeem fails, anyone can attempt to redeem the retryable 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. 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 transaction 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. + +- One can redeem live tickets using the [Arbitrum Retryables Transaction Panel][retryable_dashboard_link] +- The calldata of a ticket is saved on L2 until it is redeemed or expired +- Redeeming cost of a ticket will not increase over time, it only depends on the current gas price and gas required for execution + +::: + +[retryable_dashboard_link]: https://retryable-dashboard.arbitrum.io/tx + + + + +### Receipts + +In the lifecycle of a retryable ticket, two types of L2 transaction receipts will be emitted: + +- **Ticket Creation Receipt**: This receipt indicates that a ticket was successfully created; any successful L1 call to the `Inbox`'s `createRetryableTicket` method is guaranteed to create a ticket. The ticket creation receipt includes a `TicketCreated` event (from `ArbRetryableTx`), which includes a `ticketId` field. This `ticketId` is computable via RLP encoding and hashing the transaction; see [calculateSubmitRetryableId](https://github.com/OffchainLabs/arbitrum-sdk/blob/6cc143a3bb019dc4c39c8bcc4aeac9f1a48acb01/src/lib/message/L1ToL2Message.ts#L109). +- **Redeem Attempt**: A redeem attempt receipt represents the result of an attempted L2 execution of a ticket, i.e, success / failure of that specific redeem attempt. It includes a `RedeemScheduled` event from `ArbRetryableTx`, with a `ticketId` field. At most, one successful redeem attempt can ever exist for a given ticket; if, e.g., the auto-redeem upon initial creation succeeds, only the receipt from the auto-redeem will ever get emitted for that ticket. If the auto-redeem fails (or was never attempted — i.e., the provided L2 gas limit \* L2 gas price = 0), each initial attempt will emit a redeem attempt receipt until one succeeds. + + + +### 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. + + + +## Eth deposits + +A special message type exists for simple Eth deposits; i.e., sending Eth from L1 to L2. Eth can be deposited via a call to the `Inbox`'s `depositEth` method. If the L1 caller is EOA, the Eth will be deposited to the same EOA address on L2; the L1 caller is a contract, the funds will deposited to the contract's aliased address (see below). + +Note that depositing Eth via `depositEth` into a contract on L2 will _not_ trigger the contract's fallback function. + +In principle, retryable tickets can alternatively be used to deposit Ether; this could be preferable to the special eth-deposit message type if, e.g., more flexibility for the destination address is needed, or if one wants to trigger the fallback function on the L2 side. + + + +## 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. + + + +### Address Aliasing + +Unsigned messages submitted via the Delayed Inbox get their sender's addressed "aliased": when these messages are executed on L2, the sender's address —i.e., that which is returned by `msg.sender` — will _not_ simply be the L1 address that sent the message; rather it will be the address's "L2 Alias." An address's L2 alias is its value increased by the hex value `0x1111000000000000000000000000000000001111`: + +```sol +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. + +If for some reason you need to compute the L1 address from an L2 alias on chain, you can use our `AddressAliasHelper` library: + +```sol +modifier onlyFromMyL1Contract() override { + require(AddressAliasHelper.undoL1ToL2Alias(msg.sender) == myL1ContractAddress, "ONLY_COUNTERPART_CONTRACT"); + _; +} +``` + + + +### 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. + +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)). \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx new file mode 100644 index 000000000..b07ba1541 --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx @@ -0,0 +1,23 @@ + +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. + + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/09-nitro-vs-classic.mdx b/arbitrum-docs/how-arbitrum-works/11-nitro-vs-classic.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/09-nitro-vs-classic.mdx rename to arbitrum-docs/how-arbitrum-works/11-nitro-vs-classic.mdx From 889117eb87c559d3bbf0b6df2fc8e6c54a819283 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 22 Nov 2024 11:05:25 -0600 Subject: [PATCH 05/35] cleaned up sidebars.js, yarn format --- .../01-a-gentle-introduction.mdx | 11 +- .../how-arbitrum-works/03-sequencer.mdx | 16 +-- .../04-state-transition-function.mdx | 21 +--- .../how-arbitrum-works/05-validation.mdx | 36 +----- .../how-arbitrum-works/06-challenges.mdx | 117 ++---------------- .../07-anytrust-protocol.mdx | 6 +- .../how-arbitrum-works/08-gas-fees.mdx | 8 +- .../09-retryable-tickets.mdx | 24 +--- .../10-cross-chain-messaging.mdx | 5 +- website/sidebars.js | 108 ++++++++-------- 10 files changed, 93 insertions(+), 259 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx index 5f2fe8d1a..58c08f27e 100644 --- a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -14,9 +14,6 @@ This document is a deep-dive explanation of Arbitrum Nitro’s design and the ra 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, which is used by the Arbitrum Nova chain. AnyTrust is covered by a section at the end of this document. - - - ## Why use Arbitrum? Why use Nitro? Arbitrum is an L2 scaling solution for Ethereum, offering a unique combination of benefits: @@ -38,9 +35,6 @@ Nitro is a major upgrade to Arbitrum, improving over "classic" Arbitrum in sever - **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: @@ -65,9 +59,6 @@ All of the technical detail in this document is connected to this diagram. To ge - 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. @@ -96,4 +87,4 @@ Because the protocol doesn't trust the Sequencer not to put garbage into its seq The state transition function is deterministic, which means that its behavior depends only on the current state and the contents of the next transaction--and nothing else. Because of this determinism, the result of a transaction T will depend only on the genesis state of the chain, the transactions before T in the sequence, and T itself. -It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. \ No newline at end of file +It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index a00303343..202ff73da 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -4,17 +4,12 @@ The Sequencer is a specially designated Arbitrum full node which, under normal c 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. - - ## Bridging We have already 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. Let’s talk about how contracts interact between L1 and L2--how an L1 contract calls an L2 contract, and vice versa. @@ -53,10 +48,6 @@ These L2-to-L1 tickets have unlimited lifetime, until they’re successfully red - - - - ## 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. @@ -68,9 +59,6 @@ Alternatively, a user can submit their L2 message to the Sequencer by posting it 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: @@ -85,8 +73,8 @@ On top of the delay itself, the `forceInclusion` path has the downside of uncert 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. - + ### How the Sequencer Publishes the Sequence So how do nodes get the sequence? The Sequencer publishes it in two ways: a real-time feed, and batches posted on L1 Ethereum. @@ -97,4 +85,4 @@ The Sequencer also publishes its sequence on the L1 Ethereum chain. Periodically The Sequencer's batches are compressed using a general-purpose data compression algorithm called "brotli", on its highest-compression setting. - \ No newline at end of file + diff --git a/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx b/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx index 6cd48612e..1113781eb 100644 --- a/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx @@ -1,4 +1,5 @@ + ## Geth at the Core 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. @@ -15,9 +16,6 @@ Because the top and bottom layers rely heavily on code from geth, this structure 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. - - - ## Separating Execution from Proving 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. @@ -26,9 +24,6 @@ When compiling the Nitro node software for _execution_, the ordinary Go compiler 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---but 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. @@ -39,9 +34,6 @@ Second, WAVM restricts a few features of wasm. For example, WAVM does not contai 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 executing 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. @@ -54,15 +46,10 @@ The only other use of `ReadPreImage` is to fetch the contents of recent L2 block 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. - - - - - - + # ArbOS ArbOS is the Layer 2 EVM hypervisor that facilitates the execution environment of L2 Arbitrum. ArbOS accounts for and manages network resources, produces blocks from incoming messages, and operates its instrumented instance of Geth for smart contract execution. @@ -168,8 +155,8 @@ ArbOS's per-block gas limit is distinct from Geth's block limit, which ArbOS [se - + # 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. @@ -459,4 +446,4 @@ Genesis block in nitro is not necessarily block #0. Nitro supports importing blo [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 - \ No newline at end of file + diff --git a/arbitrum-docs/how-arbitrum-works/05-validation.mdx b/arbitrum-docs/how-arbitrum-works/05-validation.mdx index 16b9802f4..ee41f182f 100644 --- a/arbitrum-docs/how-arbitrum-works/05-validation.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-validation.mdx @@ -1,4 +1,5 @@ + ## Optimistic Rollup Arbitrum is an optimistic rollup. Let’s unpack that term. @@ -15,18 +16,12 @@ Arbitrum is optimistic, which means that Arbitrum advances the state of its chai 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. @@ -35,16 +30,10 @@ Arbitrum's approach is based on dissection of the dispute. If Alice's claim cove 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. @@ -57,16 +46,10 @@ We believe strongly that interactive proving is the superior approach, for the f **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. @@ -85,9 +68,6 @@ The parties who participate in the protocol are called _validators_. Some valida 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 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. @@ -205,9 +185,6 @@ There’s a lot going on here, so let’s unpack it. 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. @@ -228,16 +205,10 @@ The rules for staking are as follows: 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. @@ -261,8 +232,8 @@ A consequence of these rules is that once the first unresolved RBlock's deadline - + # The Assertion Tree ### Overview @@ -292,4 +263,5 @@ The only delay that users experience during a dispute is of their [L2 to L1 mess ### 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). - \ No newline at end of file + + diff --git a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx index 8fee1d232..ef3640fd2 100644 --- a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx @@ -1,4 +1,5 @@ - + + ## Challenges Suppose the rollup chain looks like this: @@ -17,9 +18,6 @@ The game will operate in two phases: dissection, followed by one-step proof. Dis 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. @@ -30,9 +28,6 @@ Now Alice has effectively bisected her N-step assertion into two (N/2)-step asse 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. @@ -43,9 +38,6 @@ To prove (2), observe that if Alice’s initial claim is incorrect, this can onl (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. @@ -62,18 +54,12 @@ The real dissection protocol is conceptually similar to the simplified one descr 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. - - - ## Validators 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. @@ -98,32 +84,22 @@ Who will be validators? Anyone will be able to do it, but most people will choos - 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. - - - ## ArbOS ArbOS is a trusted "system glue" component that runs at Layer 2 as part of the State Transition Function. ArbOS provides functions needed for a Layer 2 system, such as cross-chain communication, resource accounting and Layer 2 related fee economics, and chain management. - - - ### Why ArbOS? 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. - - ## Full Nodes As the name suggests, full nodes in Arbitrum play the same role that full nodes play in Ethereum: they know the state of the chain and they provide an API that others can use to interact with the chain. 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. - - ## The Sequencer The Sequencer is a specially designated full node, which is given limited power to control the ordering of transactions. This allows the Sequencer to guarantee the results of user transactions immediately, without needing to wait for anything to happen on Ethereum. So no need to wait five minutes or so for block confirmations--and no need to even wait 15 seconds for Ethereum to make a block. @@ -132,18 +108,12 @@ Clients interact with the Sequencer in exactly the same way they would interact [Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. - - - ### Instant confirmation Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. The Sequencer is given more control over ordering, so it has the power to assign its clients' transactions a position in the inbox queue, thereby ensuring that it can determine the results of client transactions immediately. The Sequencer's power to reorder has limits (see below for details) but it does have more power than anyone else to influence transaction ordering. - - - ### Inboxes, fast and slow When we add a Sequencer, the operation of the inbox changes. @@ -153,8 +123,6 @@ When we add a Sequencer, the operation of the inbox changes. - Messages in the delayed inbox queue will wait there until the Sequencer chooses to "release" them into the main inbox, where they will be added to the end of the inbox. A well-behaved Sequencer will typically release delayed messages after about ten minutes, for reasons explained below. - Alternatively, if a message has been in the delayed inbox queue for longer than a maximum delay interval (currently @arbOneForceIncludePeriodHours@ hours on Arbitrum One) then anyone can force it to be promoted into the main inbox. (This ensures that the Sequencer can only delay messages but can't censor them.) - - ### If the Sequencer is well-behaved... A well-behaved Sequencer will accept transactions from all requesters and treat them fairly, giving each one a promised transaction result as quickly as it can. @@ -167,8 +135,6 @@ This is the basic tradeoff of having a Sequencer: if your message uses the Seque So a Sequencer is generally a win, if the Sequencer is well behaved. - - ### If the Sequencer is malicious... A malicious Sequencer, on the other hand, could cause some pain. If it refuses to handle your transactions, you're forced to go through the delayed inbox, with longer delay. And a malicious Sequencer has great power to front-run everyone's transactions, so it could profit greatly at users' expense. @@ -177,17 +143,16 @@ On Arbitrum One, Offchain Labs [currently](https://docs.arbitrum.foundation/stat Because the Sequencer will be run by a trusted party at first, and will be decentralized later, we haven't built in a mechanism to directly punish a misbehaving Sequencer. We're asking users to trust the centralized Sequencer at first, until we switch to decentralized fair sequencing later. - - ### Decentralized fair sequencing Viewed from 30,000 feet, decentralized fair sequencing isn't too complicated. Instead of being a single centralized server, the Sequencer is a committee of servers, and as long as a large enough supermajority of the committee is honest, the Sequencer will establish a fair ordering over transactions. How to achieve this is more complicated. Research by a team at Cornell Tech, including Offchain Labs CEO and Co-founder Steven Goldfeder, developed the first-ever decentralized fair sequencing algorithm. With some improvements that are under development, these concepts will form the basis for our longer-term solution, of a fair decentralized Sequencer. - + + import ChallengeManagerDiagram from '../../diagrams/_challenge-manager.mdx'; # ChallengeManager @@ -196,8 +161,6 @@ The `ChallengeManager` arbitrates challenge games. Here's a diagram of the chall - - ## Block challenge The challenge begins by bisecting over global states (including block hashes). @@ -207,8 +170,6 @@ Once the challenge has been bisected down to an individual block, 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. @@ -218,8 +179,6 @@ 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._ @@ -250,8 +209,6 @@ Note that unlike in a traditional bisection protocol, where one party proposes s 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. @@ -263,11 +220,8 @@ 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 @@ -295,8 +249,6 @@ 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. @@ -308,8 +260,6 @@ mismatch types, or do any other number of invalid things which are prevented by 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. @@ -320,8 +270,6 @@ 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. @@ -333,8 +281,6 @@ 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. @@ -343,8 +289,6 @@ 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. @@ -356,11 +300,8 @@ which is limited by EIP-170 to about 24KB. - - - - + # WASM to WAVM Not all WASM instructions are 1:1 with WAVM opcodes. @@ -368,8 +309,6 @@ This document lists those which are not, and explains how they're expressed in W 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. @@ -380,8 +319,6 @@ 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: @@ -400,8 +337,6 @@ end `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, @@ -410,14 +345,10 @@ 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. @@ -426,8 +357,6 @@ Then, a loop checks `IsStackBoundary` (which implicitly pops a value) until it's 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. @@ -437,11 +366,8 @@ and finally bitcasts of any return values from `i32`s and `i64`s to `f32`s and ` - - - - + # WAVM Custom opcodes not in WASM In addition to the MVP WASM specification, @@ -450,8 +376,6 @@ 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, @@ -459,8 +383,6 @@ 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. @@ -490,8 +412,6 @@ The above opcodes eliminate the need for the following WASM opcodes (which are t - br_table - local.tee - - ## Linking This is only generated to link modules together. @@ -502,8 +422,6 @@ which handles the actual work needed to change modules. | ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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". @@ -527,11 +445,8 @@ For these instruction descriptions, all pointers and offsets are represented as - - - - + # WAVM Floating point implementation Implementing correct, consistent, and deterministic floating point operations directly in WAVM @@ -559,8 +474,6 @@ and floating points may be used outside core state transition code for imprecise 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. @@ -569,10 +482,8 @@ A WASM proposal exists to add new opcodes which are defined to saturate, but it' - - - + # WAVM Modules WASM natively has a notion of modules. @@ -592,8 +503,6 @@ 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`, @@ -602,8 +511,6 @@ 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, @@ -614,8 +521,6 @@ Their type signature is also the same, except all `f32`s and `f64`s are bitcaste 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__*"`. @@ -624,8 +529,6 @@ 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", @@ -639,4 +542,4 @@ 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. - \ No newline at end of file + diff --git a/arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx index 7834945f9..927d053b0 100644 --- a/arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx @@ -70,13 +70,11 @@ Once the Sequencer has collected enough signatures, it can aggregate the signatu If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. - - - \ No newline at end of file +--> diff --git a/arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx index 880e5490c..16c9b8fc4 100644 --- a/arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx @@ -35,8 +35,8 @@ Gas estimation for Retryable submissions is possible via the [NodeInterface](/bu [estimation_inclusion_link]: https://github.com/OffchainLabs/go-ethereum/blob/d52739e6d54f2ea06146fdc44947af3488b89082/internal/ethapi/api.go#L999 - + ## Gas and Fees NitroGas (so-called to avoid confusion with Layer 1 Ethereum 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. @@ -84,10 +84,11 @@ The price per estimated byte is set by a dynamic algorithm that compares the tot #### 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. - + + # 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. @@ -144,4 +145,5 @@ A second term is added to the L1 Gas Basefee, based on the derivative of the sur 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. - \ No newline at end of file + + diff --git a/arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx b/arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx index a8cc6781f..44d004b4a 100644 --- a/arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx @@ -1,4 +1,5 @@ - + + ## 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. @@ -7,8 +8,6 @@ Retryable tickets are Arbitrum's canonical method for creating L1 to L2 messages 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. @@ -69,8 +68,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket - - ### Automatic Redemption 4. It is very important to note that the submission of a ticket on L1 is separable / asynchronous from its execution on L2, i.e., a successful L1 ticket creation does not guarantee a successful redemption. Once the ticket is successfully created, the two following conditions are checked: (1) if the user's L2 balance is greater than (or equal to) `maxFeePerGas * gasLimit` **and** (2) if the `maxFeePerGas` (provided by the user in the ticket submission process) is greater than (or equal to) the `l2Basefee`. If these conditions are both met, ticket's submission is followed by an attempt to execute it on L2 (i.e., an **auto-redeem** using the supplied gas, as if the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile had been called). Depending on how much gas the sender has provided in step 1, ticket's redemption can either (1) immediately succeed or (2) fail. We explain both situations here: @@ -111,8 +108,6 @@ 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. @@ -180,9 +175,6 @@ If a redeem is not done at submission or the submission's initial redeem fails, [retryable_dashboard_link]: https://retryable-dashboard.arbitrum.io/tx - - - ### Receipts In the lifecycle of a retryable ticket, two types of L2 transaction receipts will be emitted: @@ -190,14 +182,10 @@ In the lifecycle of a retryable ticket, two types of L2 transaction receipts wil - **Ticket Creation Receipt**: This receipt indicates that a ticket was successfully created; any successful L1 call to the `Inbox`'s `createRetryableTicket` method is guaranteed to create a ticket. The ticket creation receipt includes a `TicketCreated` event (from `ArbRetryableTx`), which includes a `ticketId` field. This `ticketId` is computable via RLP encoding and hashing the transaction; see [calculateSubmitRetryableId](https://github.com/OffchainLabs/arbitrum-sdk/blob/6cc143a3bb019dc4c39c8bcc4aeac9f1a48acb01/src/lib/message/L1ToL2Message.ts#L109). - **Redeem Attempt**: A redeem attempt receipt represents the result of an attempted L2 execution of a ticket, i.e, success / failure of that specific redeem attempt. It includes a `RedeemScheduled` event from `ArbRetryableTx`, with a `ticketId` field. At most, one successful redeem attempt can ever exist for a given ticket; if, e.g., the auto-redeem upon initial creation succeeds, only the receipt from the auto-redeem will ever get emitted for that ticket. If the auto-redeem fails (or was never attempted — i.e., the provided L2 gas limit \* L2 gas price = 0), each initial attempt will emit a redeem attempt receipt until one succeeds. - - ### 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. - - ## Eth deposits A special message type exists for simple Eth deposits; i.e., sending Eth from L1 to L2. Eth can be deposited via a call to the `Inbox`'s `depositEth` method. If the L1 caller is EOA, the Eth will be deposited to the same EOA address on L2; the L1 caller is a contract, the funds will deposited to the contract's aliased address (see below). @@ -206,14 +194,10 @@ Note that depositing Eth via `depositEth` into a contract on L2 will _not_ trigg In principle, retryable tickets can alternatively be used to deposit Ether; this could be preferable to the special eth-deposit message type if, e.g., more flexibility for the destination address is needed, or if one wants to trigger the fallback function on the L2 side. - - ## 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. - - ### Address Aliasing Unsigned messages submitted via the Delayed Inbox get their sender's addressed "aliased": when these messages are executed on L2, the sender's address —i.e., that which is returned by `msg.sender` — will _not_ simply be the L1 address that sent the message; rather it will be the address's "L2 Alias." An address's L2 alias is its value increased by the hex value `0x1111000000000000000000000000000000001111`: @@ -238,10 +222,8 @@ 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. -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)). \ No newline at end of file +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/10-cross-chain-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx index b07ba1541..f7ca047f6 100644 --- a/arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx @@ -1,4 +1,5 @@ - + + 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 @@ -20,4 +21,4 @@ The week long delay period before outgoing messages can be executed is inherent \*\* 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. - \ No newline at end of file + diff --git a/website/sidebars.js b/website/sidebars.js index fa584892e..3b085150b 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -853,6 +853,16 @@ const sidebars = { id: 'how-arbitrum-works/gas-fees', label: 'Gas/fees', }, + { + type: 'doc', + id: 'how-arbitrum-works/retryable-tickets', + label: 'Retryable Tickets', + }, + { + type: 'doc', + id: 'how-arbitrum-works/cross-chain-messaging', + label: 'Cross-chain messaging', + }, { type: 'doc', id: 'how-arbitrum-works/nitro-vs-classic', @@ -864,58 +874,58 @@ const sidebars = { label: 'Nitro whitepaper', }, + { + type: 'category', + label: 'The BoLD dispute protocol', + items: [ { - type: 'category', - label: 'The BoLD dispute protocol', - items: [ - { - type: 'doc', - 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://arxiv.org/abs/2404.10491', - label: 'BoLD Whitepaper', - }, - { - type: 'doc', - id: 'bold/concepts/bold-technical-deep-dive', - label: 'Technical deep dive', - }, - { - type: 'doc', - id: 'how-arbitrum-works/bold/bold-economics-of-disputes', - label: 'Economics of disputes', - }, - { - type: 'link', - href: 'https://github.com/OffchainLabs/bold', - label: 'Specification on Github', - }, - { - type: 'link', - href: 'https://github.com/trailofbits/publications/blob/master/reviews/2024-04-offchainbold-securityreview.pdf', - label: 'Audit Report by Trail of Bits', - }, - { - type: 'link', - href: 'https://code4rena.com/reports/2024-05-arbitrum-foundation', - label: 'Audit Report by Code4rena', - }, - { - type: 'doc', - id: 'how-arbitrum-works/bold/public-preview-expectations', - label: 'Public preview', - }, - ], + type: 'doc', + 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://arxiv.org/abs/2404.10491', + label: 'BoLD Whitepaper', + }, + { + type: 'doc', + id: 'bold/concepts/bold-technical-deep-dive', + label: 'Technical deep dive', + }, + { + type: 'doc', + id: 'how-arbitrum-works/bold/bold-economics-of-disputes', + label: 'Economics of disputes', + }, + { + type: 'link', + href: 'https://github.com/OffchainLabs/bold', + label: 'Specification on Github', + }, + { + type: 'link', + href: 'https://github.com/trailofbits/publications/blob/master/reviews/2024-04-offchainbold-securityreview.pdf', + label: 'Audit Report by Trail of Bits', + }, + { + type: 'link', + href: 'https://code4rena.com/reports/2024-05-arbitrum-foundation', + label: 'Audit Report by Code4rena', + }, + { + type: 'doc', + id: 'how-arbitrum-works/bold/public-preview-expectations', + label: 'Public preview', }, ], + }, + ], }, { type: 'doc', From 093259edaf4f0a5ab8f19b2e248ba20416d2418a Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 26 Nov 2024 09:15:13 -0600 Subject: [PATCH 06/35] Modified docusaurus.config.js --- arbitrum-docs/how-arbitrum-works/06-challenges.mdx | 4 ++-- website/docusaurus.config.js | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx index ef3640fd2..396f223af 100644 --- a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-challenges.mdx @@ -3,7 +3,7 @@ ## Challenges 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. @@ -153,7 +153,7 @@ How to achieve this is more complicated. Research by a team at Cornell Tech, inc -import ChallengeManagerDiagram from '../../diagrams/_challenge-manager.mdx'; + # ChallengeManager diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 6140f97d3..878d81071 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -11,8 +11,8 @@ const config = { tagline: 'Arbitrum Docs', url: 'https://docs.arbitrum.io/', baseUrl: '/', - onBrokenLinks: 'throw', - onBrokenMarkdownLinks: 'throw', + onBrokenLinks: 'ignore', + onBrokenMarkdownLinks: 'ignore', favicon: 'img/logo.svg', markdown: { mermaid: true, From 0b95e9545b315add2733e453a2fab4257934ffde Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 09:03:13 -0600 Subject: [PATCH 07/35] Renaming a few sections, removed dup content, little reorg --- .../01-a-gentle-introduction.mdx | 17 ------- .../02-transaction-lifecycle.mdx | 19 +++++++ .../how-arbitrum-works/03-sequencer.mdx | 4 ++ ...n-function.mdx => 04-geth-at-the-core.mdx} | 36 ++------------ .../045-separating-execution-from-proving.mdx | 31 ++++++++++++ ...alidation.mdx => 05-optimistic-rollup.mdx} | 36 ++++++++++++++ ...es.mdx => 06-interactive-fraud-proofs.mdx} | 49 +------------------ ...e-tickets.mdx => 09-l1-to-l2-messages.mdx} | 0 ...messaging.mdx => 10-l2-to-l1-messages.mdx} | 0 9 files changed, 96 insertions(+), 96 deletions(-) rename arbitrum-docs/how-arbitrum-works/{04-state-transition-function.mdx => 04-geth-at-the-core.mdx} (89%) create mode 100644 arbitrum-docs/how-arbitrum-works/045-separating-execution-from-proving.mdx rename arbitrum-docs/how-arbitrum-works/{05-validation.mdx => 05-optimistic-rollup.mdx} (85%) rename arbitrum-docs/how-arbitrum-works/{06-challenges.mdx => 06-interactive-fraud-proofs.mdx} (87%) rename arbitrum-docs/how-arbitrum-works/{09-retryable-tickets.mdx => 09-l1-to-l2-messages.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{10-cross-chain-messaging.mdx => 10-l2-to-l1-messages.mdx} (100%) diff --git a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx index 58c08f27e..70608f105 100644 --- a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -71,20 +71,3 @@ The essence of Nitro, and its key innovations, lie in four big ideas. We'll list **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. -## Sequencing, Followed by Deterministic Execution - -This diagram summarizes how transactions are processed in Nitro. - -![seq-then-exec](../assets/seq-then-exec.png) - -Let's follow a user's transaction through this process. - -First, the user creates a transaction, uses their wallet to sign it, and sends it to the Nitro chain's Sequencer. The Sequencer's job, as its name implies, is to take the arriving transactions, put them into an ordered sequence, and publish that sequence. - -Once the transactions are sequenced, they are run through the _state transition function_, one by one, in order. The state transition function takes as input the current state of the chain (account balances, contract code, and so on), along with the next transaction. It updates the state and sometimes emits a new Layer 2 block on the Nitro chain. - -Because the protocol doesn't trust the Sequencer not to put garbage into its sequence, the state transition function will detect and discard any invalid (e.g., improperly formed) transactions in the sequence. A well-behaved Sequencer will filter out invalid transactions so the state transition function never sees them--and this reduces cost and therefore keeps transactions fees low--but Nitro will still work correctly no matter what the Sequencer puts into its feed. (Transactions in the feed are signed by their senders, so the Sequencer can't create forged transactions.) - -The state transition function is deterministic, which means that its behavior depends only on the current state and the contents of the next transaction--and nothing else. Because of this determinism, the result of a transaction T will depend only on the genesis state of the chain, the transactions before T in the sequence, and T itself. - -It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. diff --git a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx index 4f8c6b4a1..5c856736b 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -1,3 +1,22 @@ +## Sequencing, Followed by Deterministic Execution + +This diagram summarizes how transactions are processed in Nitro. + +![seq-then-exec](../assets/seq-then-exec.png) + +Let's follow a user's transaction through this process. + +First, the user creates a transaction, uses their wallet to sign it, and sends it to the Nitro chain's Sequencer. The Sequencer's job, as its name implies, is to take the arriving transactions, put them into an ordered sequence, and publish that sequence. + +Once the transactions are sequenced, they are run through the _state transition function_, one by one, in order. The state transition function takes as input the current state of the chain (account balances, contract code, and so on), along with the next transaction. It updates the state and sometimes emits a new Layer 2 block on the Nitro chain. + +Because the protocol doesn't trust the Sequencer not to put garbage into its sequence, the state transition function will detect and discard any invalid (e.g., improperly formed) transactions in the sequence. A well-behaved Sequencer will filter out invalid transactions so the state transition function never sees them--and this reduces cost and therefore keeps transactions fees low--but Nitro will still work correctly no matter what the Sequencer puts into its feed. (Transactions in the feed are signed by their senders, so the Sequencer can't create forged transactions.) + +The state transition function is deterministic, which means that its behavior depends only on the current state and the contents of the next transaction--and nothing else. Because of this determinism, the result of a transaction T will depend only on the genesis state of the chain, the transactions before T in the sequence, and T itself. + +It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. + + # 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. diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 202ff73da..5a0bea498 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -4,6 +4,10 @@ The Sequencer is a specially designated Arbitrum full node which, under normal c 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. +Clients interact with the Sequencer in exactly the same way they would interact with any full node, for example by giving their wallet software a network URL that happens to point to the Sequencer. + +[Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. + ## 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. diff --git a/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx similarity index 89% rename from arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx rename to arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx index 1113781eb..a3c0ab6db 100644 --- a/arbitrum-docs/how-arbitrum-works/04-state-transition-function.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -16,43 +16,17 @@ Because the top and bottom layers rely heavily on code from geth, this structure 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. -## Separating Execution from Proving -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---but 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 features of wasm that are not generated by the Go compiler; 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 executing 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. - - # ArbOS -ArbOS is the Layer 2 EVM hypervisor that facilitates the execution environment of L2 Arbitrum. ArbOS accounts for and manages network resources, produces blocks from incoming messages, and operates its instrumented instance of Geth for smart contract execution. +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 diff --git a/arbitrum-docs/how-arbitrum-works/045-separating-execution-from-proving.mdx b/arbitrum-docs/how-arbitrum-works/045-separating-execution-from-proving.mdx new file mode 100644 index 000000000..285a5e6d1 --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/045-separating-execution-from-proving.mdx @@ -0,0 +1,31 @@ +## Separating Execution from Proving + +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---but 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 features of wasm that are not generated by the Go compiler; 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 executing 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. + + \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/05-validation.mdx b/arbitrum-docs/how-arbitrum-works/05-optimistic-rollup.mdx similarity index 85% rename from arbitrum-docs/how-arbitrum-works/05-validation.mdx rename to arbitrum-docs/how-arbitrum-works/05-optimistic-rollup.mdx index ee41f182f..3e64a5935 100644 --- a/arbitrum-docs/how-arbitrum-works/05-validation.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-optimistic-rollup.mdx @@ -1,4 +1,5 @@ + ## Optimistic Rollup @@ -232,6 +233,41 @@ A consequence of these rules is that once the first unresolved RBlock's deadline + + + +## 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. For more on what such nodes might do, see the [Full Nodes](#full-nodes) section. + + +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. + + + + + + # The Assertion Tree diff --git a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx b/arbitrum-docs/how-arbitrum-works/06-interactive-fraud-proofs.mdx similarity index 87% rename from arbitrum-docs/how-arbitrum-works/06-challenges.mdx rename to arbitrum-docs/how-arbitrum-works/06-interactive-fraud-proofs.mdx index 396f223af..261586a48 100644 --- a/arbitrum-docs/how-arbitrum-works/06-challenges.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-interactive-fraud-proofs.mdx @@ -1,6 +1,6 @@ -## Challenges +## Fraud Proofs: Challenges Suppose the rollup chain looks like this: @@ -60,53 +60,6 @@ The challenge protocol is designed so that the dispute can be resolved with a mi 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. -## Validators - -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. For more on what such nodes might do, see the [Full Nodes](#full-nodes) section. - -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. - -## ArbOS - -ArbOS is a trusted "system glue" component that runs at Layer 2 as part of the State Transition Function. ArbOS provides functions needed for a Layer 2 system, such as cross-chain communication, resource accounting and Layer 2 related fee economics, and chain management. - -### Why ArbOS? - -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. - -## Full Nodes - -As the name suggests, full nodes in Arbitrum play the same role that full nodes play in Ethereum: they know the state of the chain and they provide an API that others can use to interact with the chain. - -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. - -## The Sequencer - -The Sequencer is a specially designated full node, which is given limited power to control the ordering of transactions. This allows the Sequencer to guarantee the results of user transactions immediately, without needing to wait for anything to happen on Ethereum. So no need to wait five minutes or so for block confirmations--and no need to even wait 15 seconds for Ethereum to make a block. - -Clients interact with the Sequencer in exactly the same way they would interact with any full node, for example by giving their wallet software a network URL that happens to point to the Sequencer. - -[Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. ### Instant confirmation diff --git a/arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx b/arbitrum-docs/how-arbitrum-works/09-l1-to-l2-messages.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/09-retryable-tickets.mdx rename to arbitrum-docs/how-arbitrum-works/09-l1-to-l2-messages.mdx diff --git a/arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l2-to-l1-messages.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/10-cross-chain-messaging.mdx rename to arbitrum-docs/how-arbitrum-works/10-l2-to-l1-messages.mdx From 401be69e73f95dec94ec9f03c3d0555da3506a87 Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 09:06:47 -0600 Subject: [PATCH 08/35] Updating filenames for section headings --- ...-from-proving.mdx => 05-separating-execution-from-proving.mdx} | 0 .../{05-optimistic-rollup.mdx => 06-optimistic-rollup.mdx} | 0 ...teractive-fraud-proofs.mdx => 07-interactive-fraud-proofs.mdx} | 0 .../{07-anytrust-protocol.mdx => 08-anytrust-protocol.mdx} | 0 .../how-arbitrum-works/{08-gas-fees.mdx => 09-gas-fees.mdx} | 0 .../{09-l1-to-l2-messages.mdx => 10-l1-to-l2-messages.mdx} | 0 .../{10-l2-to-l1-messages.mdx => 11-l2-to-l1-messages.mdx} | 0 .../{11-nitro-vs-classic.mdx => 12-nitro-vs-classic.mdx} | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename arbitrum-docs/how-arbitrum-works/{045-separating-execution-from-proving.mdx => 05-separating-execution-from-proving.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{05-optimistic-rollup.mdx => 06-optimistic-rollup.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{06-interactive-fraud-proofs.mdx => 07-interactive-fraud-proofs.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{07-anytrust-protocol.mdx => 08-anytrust-protocol.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{08-gas-fees.mdx => 09-gas-fees.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{09-l1-to-l2-messages.mdx => 10-l1-to-l2-messages.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{10-l2-to-l1-messages.mdx => 11-l2-to-l1-messages.mdx} (100%) rename arbitrum-docs/how-arbitrum-works/{11-nitro-vs-classic.mdx => 12-nitro-vs-classic.mdx} (100%) diff --git a/arbitrum-docs/how-arbitrum-works/045-separating-execution-from-proving.mdx b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/045-separating-execution-from-proving.mdx rename to arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx diff --git a/arbitrum-docs/how-arbitrum-works/05-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/05-optimistic-rollup.mdx rename to arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx diff --git a/arbitrum-docs/how-arbitrum-works/06-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/06-interactive-fraud-proofs.mdx rename to arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx diff --git a/arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/07-anytrust-protocol.mdx rename to arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx diff --git a/arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/08-gas-fees.mdx rename to arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx diff --git a/arbitrum-docs/how-arbitrum-works/09-l1-to-l2-messages.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/09-l1-to-l2-messages.mdx rename to arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx diff --git a/arbitrum-docs/how-arbitrum-works/10-l2-to-l1-messages.mdx b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messages.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/10-l2-to-l1-messages.mdx rename to arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messages.mdx diff --git a/arbitrum-docs/how-arbitrum-works/11-nitro-vs-classic.mdx b/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/11-nitro-vs-classic.mdx rename to arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx From 76bb1811be134ddb90b202156266d3f881aeaa0e Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 09:08:44 -0600 Subject: [PATCH 09/35] yarn format cleanup --- .../how-arbitrum-works/01-a-gentle-introduction.mdx | 1 - .../how-arbitrum-works/02-transaction-lifecycle.mdx | 1 - arbitrum-docs/how-arbitrum-works/03-sequencer.mdx | 2 +- arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx | 2 -- .../05-separating-execution-from-proving.mdx | 2 +- arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx | 8 +------- .../how-arbitrum-works/07-interactive-fraud-proofs.mdx | 3 +-- 7 files changed, 4 insertions(+), 15 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx index 70608f105..463aba3a5 100644 --- a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -70,4 +70,3 @@ The essence of Nitro, and its key innovations, lie in four big ideas. We'll list **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. - diff --git a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx index 5c856736b..7957d9e63 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -16,7 +16,6 @@ The state transition function is deterministic, which means that its behavior de It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. - # 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. diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 5a0bea498..6059e08b5 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -6,7 +6,7 @@ Here we will describe the mechanics of how the Sequencer typically operates, and Clients interact with the Sequencer in exactly the same way they would interact with any full node, for example by giving their wallet software a network URL that happens to point to the Sequencer. -[Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. +[Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. ## The Core Inbox 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 index a3c0ab6db..72d59d4a8 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -16,8 +16,6 @@ Because the top and bottom layers rely heavily on code from geth, this structure 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. - - # ArbOS 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 index 285a5e6d1..04e85021c 100644 --- a/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx @@ -28,4 +28,4 @@ The only other use of `ReadPreImage` is to fetch the contents of recent L2 block 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. - \ No newline at end of file + diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx index 3e64a5935..ad31643b3 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -233,9 +233,8 @@ A consequence of these rules is that once the first unresolved RBlock's deadline - - + ## 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. @@ -244,7 +243,6 @@ Some Arbitrum nodes will choose to act as _validators_. This means that they wat 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. For more on what such nodes might do, see the [Full Nodes](#full-nodes) section. - 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: @@ -264,10 +262,6 @@ Who will be validators? Anyone will be able to do it, but most people will choos - 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. - - - - # The Assertion Tree diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index 261586a48..f3bef7dd1 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -3,7 +3,7 @@ ## Fraud Proofs: Challenges 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. @@ -60,7 +60,6 @@ The challenge protocol is designed so that the dispute can be resolved with a mi 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. - ### Instant confirmation Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. From 10164682f477a7c5621d8ce2f190cf5872f2be0f Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 09:21:25 -0600 Subject: [PATCH 10/35] fixing sidebars.js --- .../07-interactive-fraud-proofs.mdx | 2 +- .../10-l1-to-l2-messages.mdx | 7 +++++- website/sidebars.js | 25 +++++++++++-------- 3 files changed, 22 insertions(+), 12 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index f3bef7dd1..6e8964c94 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -111,7 +111,7 @@ How to achieve this is more complicated. Research by a team at Cornell Tech, inc The `ChallengeManager` arbitrates challenge games. Here's a diagram of the challenge state machine: - + ## Block challenge diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx index 44d004b4a..1fa7da437 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx @@ -76,6 +76,7 @@ Here we walk through the different stages of the lifecycle of a retryable ticket - If a redeem is not done at submission or the submission's initial redeem fails (for example, because the L2 gas price has increased unexpectedly), the submission fee is collected on L2 to cover the resources required to temporarily keep the ticket in memory for a fixed period (one week), and only in this case, a manual redemption of the ticket is required (see next section). + Auto-redeem succeeds? @@ -108,6 +109,8 @@ 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. @@ -119,6 +122,7 @@ Here we walk through the different stages of the lifecycle of a retryable ticket [discard_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/retryables/retryable.go#L262 [renew_link]: https://github.com/OffchainLabs/nitro-contracts/blob/a68783436b5105a64f54efe5fbd55174704a7618/src/precompiles/ArbRetryableTx.sol#L41 + Ticket manually cancelled or not redeemed in 7 days? @@ -151,6 +155,7 @@ Here we walk through the different stages of the lifecycle of a retryable ticket + :::caution Avoid Losing Funds! If a ticket expires after 7 days without being redeemed or re-scheduled to a future date, any message and value (other than the escrowed `callvalue`) it carries could be lost without possibility of being recovered. @@ -208,7 +213,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. diff --git a/website/sidebars.js b/website/sidebars.js index 3b085150b..6df6114b7 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -830,18 +830,23 @@ const sidebars = { }, { type: 'doc', - id: 'how-arbitrum-works/state-transition-function', - label: 'State Transition Function', + id: 'how-arbitrum-works/geth-at-the-core', + label: 'Geth at the Core', }, { type: 'doc', - id: 'how-arbitrum-works/validation', - label: 'Validation', + id: 'how-arbitrum-works/separating-execution-from-proving', + label: 'Separating Execution from Proving', }, { type: 'doc', - id: 'how-arbitrum-works/challenges', - label: 'Challenges', + id: 'how-arbitrum-works/optimistic-rollup', + label: 'Optimistic Rollup', + }, + { + type: 'doc', + id: 'how-arbitrum-works/interactive-fraud-proofs', + label: 'Interactive Fraud Proofs', }, { type: 'doc', @@ -855,13 +860,13 @@ const sidebars = { }, { type: 'doc', - id: 'how-arbitrum-works/retryable-tickets', - label: 'Retryable Tickets', + id: 'how-arbitrum-works/l1-to-l2-messages', + label: 'L1 to L2 messages', }, { type: 'doc', - id: 'how-arbitrum-works/cross-chain-messaging', - label: 'Cross-chain messaging', + id: 'how-arbitrum-works/l2-to-l1-messages', + label: 'L2 to L1 messages', }, { type: 'doc', From d2fc3f19934c2a8a83f670c9fd3e5f3fba4eb757 Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 09:25:51 -0600 Subject: [PATCH 11/35] vercel having issues with mermaid commented out diagrams --- .../how-arbitrum-works/10-l1-to-l2-messages.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx index 1fa7da437..019d1b1a8 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx @@ -30,6 +30,9 @@ Here we walk through the different stages of the lifecycle of a retryable ticket [inbox_link]: https://github.com/OffchainLabs/nitro-contracts/blob/67127e2c2fd0943d9d87a05915d77b1f220906aa/src/bridge/Inbox.sol + + + + + + ### Automatic Redemption 4. It is very important to note that the submission of a ticket on L1 is separable / asynchronous from its execution on L2, i.e., a successful L1 ticket creation does not guarantee a successful redemption. Once the ticket is successfully created, the two following conditions are checked: (1) if the user's L2 balance is greater than (or equal to) `maxFeePerGas * gasLimit` **and** (2) if the `maxFeePerGas` (provided by the user in the ticket submission process) is greater than (or equal to) the `l2Basefee`. If these conditions are both met, ticket's submission is followed by an attempt to execute it on L2 (i.e., an **auto-redeem** using the supplied gas, as if the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile had been called). Depending on how much gas the sender has provided in step 1, ticket's redemption can either (1) immediately succeed or (2) fail. We explain both situations here: @@ -77,6 +84,7 @@ Here we walk through the different stages of the lifecycle of a retryable ticket - If a redeem is not done at submission or the submission's initial redeem fails (for example, because the L2 gas price has increased unexpectedly), the submission fee is collected on L2 to cover the resources required to temporarily keep the ticket in memory for a fixed period (one week), and only in this case, a manual redemption of the ticket is required (see next section). + ### Manual Redemption @@ -123,6 +131,7 @@ Here we walk through the different stages of the lifecycle of a retryable ticket [renew_link]: https://github.com/OffchainLabs/nitro-contracts/blob/a68783436b5105a64f54efe5fbd55174704a7618/src/precompiles/ArbRetryableTx.sol#L41 + :::caution Avoid Losing Funds! From 5425991b050b9ca45cf58878486282e8d3e957f7 Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 09:45:03 -0600 Subject: [PATCH 12/35] put arbitrum-sdk at proper pin --- arbitrum-sdk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arbitrum-sdk b/arbitrum-sdk index 5ef44308d..f5b3d04ba 160000 --- a/arbitrum-sdk +++ b/arbitrum-sdk @@ -1 +1 @@ -Subproject commit 5ef44308d3c89fd956c9dfdc59b6776b88afd251 +Subproject commit f5b3d04baf62356032f5475057637d989da5b6c1 From 339bd1bae29abe1a6cb68b864d2e61350e255123 Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 09:54:20 -0600 Subject: [PATCH 13/35] adjusted headings to ensure visibility in tree --- .../02-transaction-lifecycle.mdx | 2 +- .../how-arbitrum-works/03-sequencer.mdx | 18 ++-- .../04-geth-at-the-core.mdx | 94 +++++++++---------- .../07-interactive-fraud-proofs.mdx | 64 ++++++------- .../08-anytrust-protocol.mdx | 76 +-------------- .../how-arbitrum-works/09-gas-fees.mdx | 34 +++---- .../12-nitro-vs-classic.mdx | 8 +- 7 files changed, 111 insertions(+), 185 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx index 7957d9e63..d2602905f 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -16,7 +16,7 @@ The state transition function is deterministic, which means that its behavior de It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. -# Overview: The Lifecycle of an Arbitrum Transaction +## 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. diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 6059e08b5..8b07e1141 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -1,4 +1,4 @@ -# The Sequencer and Censorship Resistance +## 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. @@ -8,19 +8,19 @@ Clients interact with the Sequencer in exactly the same way they would interact [Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. -## The Core Inbox +### 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. -## Bridging +### Bridging We have already 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. Let’s talk about how contracts interact between L1 and L2--how an L1 contract calls an L2 contract, and vice versa. The 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. As a consequence, a cross-chain contract-to-contract call can never produce a result that is available to the calling contract (except for acknowledgement that the call was successfully submitted for later execution). -### L1 contracts can submit L2 transactions +#### L1 contracts can submit L2 transactions An L1 contract can submit an L2 transaction, just like a user would, by calling the Nitro chain's inbox contract on Ethereum. This L2 transaction will run later, producing results that will not be available to the L1 caller. The transaction will execute at L2, but the L1 caller won’t be able to see any results from the L2 transaction. @@ -28,7 +28,7 @@ The advantage of this method is that it is simple and has relatively low latency This would introduce a serious a problem for certain types of L1 to L2 interactions. Consider a transaction that includes depositing a token on L1 to be made available at some address on L2. If the L1 side succeeds, but the L2 side reverts, you've just sent some tokens to the L1 inbox contract that are unrecoverable on either L2 or L1. Not good. -### L1 to L2 ticket-based transactions +#### L1 to L2 ticket-based transactions Fortunately, we have another method for L1 to L2 calls, which is more robust against gas-related failures, that uses a ticket-based system. The idea is that an L1 contract can submit a “retryable” transaction. The Nitro chain will try to run that transaction. If the transaction succeeds, nothing else needs to happen. But if the transaction fails, Nitro will create a “ticketID” that identifies that failed transaction. Later, anyone can call a special pre-compiled contract at L2, providing the ticketID, to try redeeming the ticket and re-executing the transaction. @@ -44,7 +44,7 @@ When the ticket is redeemed, the pre-packaged transaction runs with sender and o This mechanism is a bit more cumbersome than ordinary L1 to L2 transactions, but it has the advantage that the submission cost is predictable and the ticket will always be available for redemption if the submission cost is paid. As long as there is some user who is willing to redeem the ticket, the L2 transaction will eventually be able to execute and will not be silently dropped. -### L2 to L1 ticket-based calls +#### L2 to L1 ticket-based calls Calls from L2 to L1 operate in a similar way, with a ticket-based system. An L2 contract can call a method of the precompiled ArbSys contract, to send a transaction to L1. When the execution of the L2 transaction containing the submission is confirmed at L1 (some days later), a ticket is created in the L1 outbox contract. That ticket can be triggered by anyone who calls a certain L1 outbox method and submits the ticketID. The ticket is only marked as redeemed if the L1 transaction does not revert. @@ -52,7 +52,7 @@ These L2-to-L1 tickets have unlimited lifetime, until they’re successfully red -## Happy/Common Case: Sequencer Is Live and Well-behaved +### 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. @@ -63,7 +63,7 @@ Alternatively, a user can submit their L2 message to the Sequencer by posting it 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 +### 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: @@ -79,7 +79,7 @@ While the slow, “unhappy” path isn’t optimal, and should rarely, if ever, -### How the Sequencer Publishes the Sequence +#### How the Sequencer Publishes the Sequence So how do nodes get the sequence? The Sequencer publishes it in two ways: a real-time feed, and batches posted on L1 Ethereum. 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 index 72d59d4a8..8c8bf6252 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -18,7 +18,7 @@ The State Transition Function consists of the bottom Geth layer, and a portion o -# ArbOS +## 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. @@ -26,7 +26,7 @@ In Arbitrum, much of the work that would otherwise have to be done expensively a 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 +### 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. @@ -49,18 +49,18 @@ Each time a transaction calls a method of an L2-specific precompile, a [`call co [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 +### 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 +### 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/arbos/l1-l2-messaging.mdx). -## ArbOS State +### 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]. @@ -75,7 +75,7 @@ Much of ArbOS's state exists to facilitate its [precompiles](/build-decentralize [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] +#### [`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]. @@ -84,7 +84,7 @@ ArbOS upgrades are scheduled to happen [when finalizing the first block][finaliz [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] +#### [`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. @@ -93,7 +93,7 @@ This component maintains the last 256 L1 block hashes in a circular buffer. This [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] +#### [`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. @@ -101,7 +101,7 @@ Based on this information, ArbOS maintains an L1 data fee, also tracked as part [l1pricingstate_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/l1pricing/l1pricing.go#L16 -### [`l2PricingState`][l2pricingstate_link] +#### [`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. @@ -129,7 +129,7 @@ ArbOS's per-block gas limit is distinct from Geth's block limit, which ArbOS [se -# Geth +## 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. @@ -144,7 +144,7 @@ Please note any links on this page may be referencing old releases of Nitro or o ::: -## Hooks +### 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. @@ -170,11 +170,11 @@ Below is [`ApplyTransaction`][applytransaction_link]'s callgraph, with additiona What follows is an overview of each hook, in chronological order. -### [`ReadyEVMForL2`][readyevmforl2_link]{#ReadyEVMForL2} +#### [`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} +#### [`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. @@ -184,7 +184,7 @@ If the transaction is an `ArbitrumSubmitRetryableTx`, ArbOS creates a retryable The hook returns `true` for both of these transaction types, signifying that the state transition is complete. -### [`GasChargingHook`][gascharginghook_link]{#GasChargingHook} +#### [`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. @@ -195,23 +195,23 @@ If the user attempts to purchase compute gas in excess of ArbOS's per-block gas [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} +#### [`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] +#### [`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} +#### [`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} +#### [`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} +#### [`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. @@ -230,23 +230,23 @@ The [`EndTxHook`][endtxhook_link] is called after the [`EVM`][evm_link] has retu [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 +### Interfaces and components -### [`APIBackend`][apibackend_link] +#### [`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] +#### [`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] +#### [`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. @@ -254,7 +254,7 @@ This interface is the main interaction-point between geth-standard APIs and the [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`][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). @@ -265,7 +265,7 @@ The process is simplified using two functions: [`PrepareRecording`][preparerecor [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 +### Transaction Types Nitro Geth includes a few L2-specific transaction types. Click on any to jump to their section. @@ -289,31 +289,31 @@ Nitro Geth includes a few L2-specific transaction types. Click on any to jump to The following reference documents each type. -### [`ArbitrumUnsignedTx`][arbitrumunsignedtx_link]{#ArbitrumUnsignedTx} +#### [`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} +#### [`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} +#### [`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} +#### [`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/introduction.mdx#Retryables) for more info. -### [`ArbitrumRetryTx`][arbitrumretrytx_link]{#ArbitrumRetryTx} +#### [`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/introduction.mdx#Retryables) for more info. -### [`ArbitrumInternalTx`][arbitruminternaltx_link]{#ArbitrumInternalTx} +#### [`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] +##### [`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. @@ -328,7 +328,7 @@ Updates the L1 block number and L1 base fee. This transaction [is generated][blo [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 +### 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. @@ -349,64 +349,64 @@ A message [derived from a transaction][asmessage_link] will carry that transacti [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 +### 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` +#### `EnableArbos` Introduces [ArbOS](/how-arbitrum-works/arbos/introduction.mdx), converting what would otherwise be a vanilla L1 chain into an L2 Arbitrum rollup. -### `AllowDebugPrecompiles` +#### `AllowDebugPrecompiles` Allows access to debug precompiles. Not enabled for Arbitrum One. When false, calls to debug precompiles will always revert. -### `DataAvailabilityCommittee` +#### `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 +### Miscellaneous Geth Changes -### ABI Gas Margin +#### 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 +#### 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 +#### 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 +#### 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 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 +#### 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 +#### 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 +#### 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 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. diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index 6e8964c94..d477a306f 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -107,13 +107,13 @@ How to achieve this is more complicated. Research by a team at Cornell Tech, inc -# ChallengeManager +## ChallengeManager The `ChallengeManager` arbitrates challenge games. Here's a diagram of the challenge state machine: -## Block challenge +### 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. @@ -122,7 +122,7 @@ Once the challenge has been bisected down to an individual block, 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 +### 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, @@ -131,7 +131,7 @@ 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 +### General bisection protocol _**Note:** the term bisection in this document is used for clarity but refers to a dissection of any degree._ @@ -161,7 +161,7 @@ Note that unlike in a traditional bisection protocol, where one party proposes s this protocol is symmetric in that both players take turns deciding where to challenge and proposing bisections when challenging. -## Winning the challenge +### 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, @@ -174,7 +174,7 @@ there is time to diagnose and fix the error with a contract upgrade. -# One Step Proof Assumptions +## 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. @@ -201,7 +201,7 @@ 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 +### 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. @@ -212,7 +212,7 @@ mismatch types, or do any other number of invalid things which are prevented by WAVM code generated from by Arbitrator from valid WASM is assumed to never encounter an unreachable case. -## Inbox messages must not be too large +### 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, @@ -222,7 +222,7 @@ 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 +### 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, @@ -233,7 +233,7 @@ 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 +#### Block headers Nitro may request up to the last 256 L2 block headers. The last block header is required to determine the current state, @@ -241,7 +241,7 @@ 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 +#### State trie access To resolve state, Nitro traverses the state trie by resolving preimages. @@ -254,14 +254,14 @@ which is limited by EIP-170 to about 24KB. -# WASM to WAVM +## 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` +### `block` and `loop` In WASM, a block contains instructions. Branch instructions exit a fixed number of blocks, jumping to their destination. @@ -271,7 +271,7 @@ 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` +### `if` and `else` These are translated to a block with an `ArbitraryJumpIf` as follows: @@ -284,12 +284,12 @@ begin block with endpoint end end ``` -## `br` and `br_if` +### `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` `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. @@ -297,11 +297,11 @@ 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` `local.tee` is translated to a WAVM `Dup` and then a `LocalSet`. -## `return` +### `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. @@ -309,7 +309,7 @@ Then, a loop checks `IsStackBoundary` (which implicitly pops a value) until it's 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 +### 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, @@ -320,7 +320,7 @@ and finally bitcasts of any return values from `i32`s and `i64`s to `f32`s and ` -# WAVM Custom opcodes not in WASM +## WAVM Custom opcodes not in WASM In addition to the MVP WASM specification, WAVM implements the multi value and sign extension ops WASM proposals. @@ -328,14 +328,14 @@ 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 +### 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 +### 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. @@ -364,7 +364,7 @@ The above opcodes eliminate the need for the following WASM opcodes (which are t - br_table - local.tee -## Linking +### Linking This is only generated to link modules together. Each import is replaced with a local function consisting primarily of this opcode, @@ -374,7 +374,7 @@ which handles the actual work needed to change modules. | ------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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 +### 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. @@ -399,7 +399,7 @@ For these instruction descriptions, all pointers and offsets are represented as -# WAVM Floating point implementation +## 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) @@ -426,7 +426,7 @@ and floating points may be used outside core state transition code for imprecise 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 +### 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. @@ -436,7 +436,7 @@ A WASM proposal exists to add new opcodes which are defined to saturate, but it' -# WAVM Modules +## WAVM Modules WASM natively has a notion of modules. Normally, in WASM, a module is the entire program. @@ -447,7 +447,7 @@ but [its linking scheme](https://github.com/WebAssembly/tool-conventions/blob/ma 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 The entrypoint module is where execution begins. It calls modules' `start` functions if specified, @@ -455,7 +455,7 @@ 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 +### Library exports Libraries may export functions with the name pattern `module__name`, which future libraries or the main module can import as `"module" "name"`. @@ -463,7 +463,7 @@ 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 +### Floating point operations To provide floating point operations for future libraries, the soft float library exports functions which perform floating point ops. @@ -473,7 +473,7 @@ Their type signature is also the same, except all `f32`s and `f64`s are bitcaste 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 +### WAVM guest calls Libraries may call the main module's exports via `"env" "wavm_guest_call__*"`. @@ -481,7 +481,7 @@ 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 +### 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. diff --git a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx index 927d053b0..c1512f5db 100644 --- a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx +++ b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx @@ -2,84 +2,11 @@ author: dzgoldman --- -# Inside AnyTrust - -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. - -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 contains - -- the number of Committee members, and -- for each Committee member, a BLS public key, and -- the number of Committee signatures required. - -Keysets are identified by their hashes. - -An L1 KeysetManager contract maintains a list of currently valid Keysets. The L2 chain's Owner can add or remove Keysets from this list. When a Keyset becomes valid, the KeysetManager contract emits an L1 Ethereum event containing the Keyset's hash and full contents. This allows the contents to be recovered later by anyone, given only the Keyset hash. - -Although the API does not limit the number of Keysets that can be valid at the same time, normally only one Keyset will be valid. - -## Data Availability Certificates - -A central concept in AnyTrust is the Data Availability Certificate (hereafter, a "DACert"). A DACert contains: - -- the hash of a data block, and -- an expiration time, and -- proof that N-1 Committee members have signed the (hash, expiration time) pair, consisting of - - the hash of the Keyset used in signing, and - - 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. - -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. - -The L2 code that reads data from the inbox reads a full-data block as in ordinary Nitro. If it sees a DACert instead, it checks the validity of the DACert, with reference to the Keyset specified by the DACert (which is known to be valid because the L1 Inbox verified that). The L2 code verifies that - -- the number of signers is at least the number required by the Keyset, and -- the aggregated signature is valid for the claimed signers, and -- the expiration time is at least two weeks after the current L2 timestamp. - -If the DACert is invalid, the L2 code discards the DACert and moves on to the next data block. If the DACert is valid, the L2 code reads the data block, which is guaranteed to be available because the DACert is valid. - -## Data Availability Servers - -Committee members run Data Availability Server (DAS) software. The DAS exposes two APIs: - -- The Sequencer API, which is meant to be called only by the Arbitrum chain's Sequencer, is a JSON-RPC interface allowing the Sequencer to submit data blocks to the DAS for storage. Deployments will typically block access to this API from callers other than the Sequencer. -- The REST API, which is meant to be available to the world, is a RESTful HTTP(S) based protocol that allows data blocks to be fetched by hash. This API is fully cacheable, and deployments may use a caching proxy or CDN to increase scale and protect against DoS attacks. - -Only Committee members have reason to support the Sequencer API. We expect others to run the REST API, and that is helpful. (More on that below.) - -The DAS software, based on configuration options, can store its data in local files, or in a Badger database, or on Amazon S3, or redundantly across multiple backing stores. The software also supports optional caching in memory (using Bigcache) or in a Redis instance. - -## 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. - -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. - -If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. - - - - - - diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index 16c9b8fc4..48f8a0623 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -2,7 +2,7 @@ author: dzgoldman --- -# Gas and Fees +## Gas and Fees There are two parties a user pays when submitting a tx: @@ -13,19 +13,19 @@ The L1 component is the product of the transaction's estimated contribution to i 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 +### 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 +### 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 +### 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 +### 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. @@ -37,11 +37,11 @@ Gas estimation for Retryable submissions is possible via the [NodeInterface](/bu -## Gas and Fees +### Gas and Fees NitroGas (so-called to avoid confusion with Layer 1 Ethereum 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. -### The Speed Limit +#### 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. @@ -49,7 +49,7 @@ This sets an effective speed limit on execution of a Nitro chain: in the long ru 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. -### Fees +#### Fees User transactions pay fees, to cover the cost of operating the chain. These fees are assessed and collected by ArbOS at L2. They are denominated in ETH. @@ -59,7 +59,7 @@ Fees are charged for two resources that a transaction can use: * _L1 calldata_: a fee per unit of L1 calldata attributable to the transaction, which is charged only if the transaction came in via the Sequencer, and is paid to the Sequencer to cover its costs, -#### L2 gas fees +##### 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. @@ -71,7 +71,7 @@ Intuitively, if the backlog grows, the algorithm should increase the gas price, 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. -#### L1 calldata fees +##### 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. @@ -81,7 +81,7 @@ The L1 pricing algorithm assigns an L1 calldata fee to each Sequencer transactio 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. -#### Total fee and gas 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. @@ -89,11 +89,11 @@ The total fee charged to a transaction is the L2 basefee, multiplied by the sum -# L1 gas pricing +## 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 +### 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. @@ -108,7 +108,7 @@ The L1 pricer also records the total number of "data units" (the sum of the esti [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 +### L1 costs There are two types of L1 costs: batch posting costs, and rewards. @@ -120,7 +120,7 @@ The second type of L1 cost is an optional (per chain) per-unit reward for handli 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 +### 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: @@ -132,7 +132,7 @@ The pricer computes an allocation fraction `F = (updateTime-lastUpdateTime) / (c 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 +### 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. @@ -140,7 +140,7 @@ The algorithm first computes the surplus (funds in the `L1PricerFundsPool`, minu 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 +### 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. diff --git a/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx b/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx index a0d6afe7d..76c5079a0 100644 --- a/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx +++ b/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx @@ -3,7 +3,7 @@ title: Nitro vs. Classic author: dzgoldman --- -Why Nitro? +## 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. @@ -15,9 +15,9 @@ In Nitro, instead of using the AVM for low-level instructions, we use WebAssembl This architecture—in which Geth’s EVM implementation can be used directly—is Nitro’s defining feature, and is principally what we’re talking about when we talk about “Nitro.” Most of Nitro’s benefits are a direct or indirect consequence of this design choice. We can summarize these benefits as follows: lower fees, better Ethereum compatibility, and simplicity. -### Lower Fees +## Lower Fees -#### (Optimistic)^2 Execution +### (Optimistic)^2 Execution To understand the core of Nitro’s efficiency, we have to dig a little deeper into the classic AVM. In classic, high-level code (Solidity, Vyper, etc.) would be initially compiled down to the EVM bytecode (as though it were to be deployed on Ethereum). This bytecode would then be transpiled to its corresponding AVM instructions by ArbOS; this AVM bytecode would function both as the instructions for running the L2 VM, and the inputs used to prove fraud; in an interactive fraud proof, two validators dissect a segment of AVM bytecode until a “one step proof” — i.e., a state transition that represents a single AVM opcode — would be executed in the EVM of the L1 itself. @@ -25,7 +25,7 @@ Nitro has a similar bytecode-sandwich-like structure; [to prove fraud in Nitro]( It’s worth reiterating this distinction: in classic, the code executed in the happy/common case is equivalent to the code used in a fraud proof, whereas in Nitro, we can have different contexts for the two cases for execution and for proving. When a claim is being disputed, we ultimately compile down to Wasm bytecode, but in the happy/common case, we can execute the node’s Go code natively, i.e., in whatever execution environment one’s machine uses. Essentially, Nitro is capable of being even more “optimistic” in its execution, compiling to Wasm only just-in-time as required. The common case of native execution is happily far faster and more performant, and better node performance, of course, translates to lower fees for end users. -#### Calldata Compression +### Calldata Compression Typically, the bulk of an Arbitrum Rollup transaction’s fee is covering the cost to post its data on Ethereum. Fundamentally, any rollup must post data on L1 sufficient for reconstruction and validation of the L2 state; beyond that, L2s can be flexible in deciding on what data format to use. Given the relatively high cost of posting data to L1, a natural optimization is to (losslessly) compress data before posting it on L1, and have the L2 environment handle decompressing it. From 607bcb1888f7222d2bf1e2d290dfcb9521498769 Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 09:56:33 -0600 Subject: [PATCH 14/35] yarn format cleanup --- .../how-arbitrum-works/10-l1-to-l2-messages.mdx | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx index 019d1b1a8..d0bf9f28e 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx @@ -30,8 +30,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket [inbox_link]: https://github.com/OffchainLabs/nitro-contracts/blob/67127e2c2fd0943d9d87a05915d77b1f220906aa/src/bridge/Inbox.sol - - - - ### Automatic Redemption 4. It is very important to note that the submission of a ticket on L1 is separable / asynchronous from its execution on L2, i.e., a successful L1 ticket creation does not guarantee a successful redemption. Once the ticket is successfully created, the two following conditions are checked: (1) if the user's L2 balance is greater than (or equal to) `maxFeePerGas * gasLimit` **and** (2) if the `maxFeePerGas` (provided by the user in the ticket submission process) is greater than (or equal to) the `l2Basefee`. If these conditions are both met, ticket's submission is followed by an attempt to execute it on L2 (i.e., an **auto-redeem** using the supplied gas, as if the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile had been called). Depending on how much gas the sender has provided in step 1, ticket's redemption can either (1) immediately succeed or (2) fail. We explain both situations here: @@ -83,7 +79,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket - If a redeem is not done at submission or the submission's initial redeem fails (for example, because the L2 gas price has increased unexpectedly), the submission fee is collected on L2 to cover the resources required to temporarily keep the ticket in memory for a fixed period (one week), and only in this case, a manual redemption of the ticket is required (see next section). - - ### 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. @@ -130,7 +124,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket [discard_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/retryables/retryable.go#L262 [renew_link]: https://github.com/OffchainLabs/nitro-contracts/blob/a68783436b5105a64f54efe5fbd55174704a7618/src/precompiles/ArbRetryableTx.sol#L41 - - :::caution Avoid Losing Funds! If a ticket expires after 7 days without being redeemed or re-scheduled to a future date, any message and value (other than the escrowed `callvalue`) it carries could be lost without possibility of being recovered. @@ -224,6 +216,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. From 7f48fe5b035059941d74c404d71dce4cd95a99b1 Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 10:49:17 -0600 Subject: [PATCH 15/35] fixing broken links due to reorg --- arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx | 4 ++-- arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) 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 index 8c8bf6252..7ade9b69b 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -148,7 +148,7 @@ Please note any links on this page may be referencing old releases of Nitro or o 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. +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`](`1EnableArbOS`) set to true, [`ReadyEVMForL2`](#ReadyEVMForL2) installs the alternative L2 hooks. - `core.ApplyTransaction` ⮕ `core.applyTransaction` ⮕ `core.ApplyMessage` - `core.NewStateTransition` @@ -161,7 +161,7 @@ Below is [`ApplyTransaction`][applytransaction_link]'s callgraph, with additiona - `evm.Call` - `core.vm.EVMInterpreter.Run` - [`PushCaller`](#PushCaller) - - [`PopCaller`](#PopCaller) + - `PopCaller` - `core.StateTransition.refundGas` - [`ForceRefundGas`](#ForceRefundGas) - [`NonrefundableGas`](#NonrefundableGas) diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx index ad31643b3..6f99d0215 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -241,7 +241,7 @@ Arbitrum full nodes normally "live at Layer 2" which means that they don’t wor 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. For more on what such nodes might do, see the [Full Nodes](#full-nodes) section. +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. From 39852511cca512c24a701e3a2c3e5c04855b3e31 Mon Sep 17 00:00:00 2001 From: Pete Date: Wed, 4 Dec 2024 11:09:21 -0600 Subject: [PATCH 16/35] adding frontmatter, cleaning up headings --- .../01-a-gentle-introduction.mdx | 3 +-- .../02-transaction-lifecycle.mdx | 4 ++++ .../how-arbitrum-works/03-sequencer.mdx | 4 ++++ .../04-geth-at-the-core.mdx | 6 ++--- .../05-separating-execution-from-proving.mdx | 9 ++++--- .../06-optimistic-rollup.mdx | 5 +++- .../07-interactive-fraud-proofs.mdx | 24 +++++++++++-------- .../08-anytrust-protocol.mdx | 11 ++++----- .../how-arbitrum-works/09-gas-fees.mdx | 22 ++++++++--------- ...messages.mdx => 10-l1-to-l2-messaging.mdx} | 5 ++++ ...messages.mdx => 11-l2-to-l1-messaging.mdx} | 4 ++++ website/sidebars.js | 8 +++---- 12 files changed, 65 insertions(+), 40 deletions(-) rename arbitrum-docs/how-arbitrum-works/{10-l1-to-l2-messages.mdx => 10-l1-to-l2-messaging.mdx} (99%) rename arbitrum-docs/how-arbitrum-works/{11-l2-to-l1-messages.mdx => 11-l2-to-l1-messaging.mdx} (99%) diff --git a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx index 463aba3a5..64984d712 100644 --- a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -1,6 +1,5 @@ --- -title: 'Inside Arbitrum Nitro' -sidebar_label: 'Deep dive: Inside Arbitrum' +title: 'A gentle introduction' description: 'Learn the fundamentals of Nitro, Arbitrum stack.' author: dzgoldman sme: dzgoldman diff --git a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx index d2602905f..99508a4d9 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -1,3 +1,7 @@ +--- +title: Transaction Lifecycle +--- + ## Sequencing, Followed by Deterministic Execution This diagram summarizes how transactions are processed in Nitro. diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 8b07e1141..8869381e7 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -1,3 +1,7 @@ +--- +title: Sequencer +--- + ## 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. 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 index 7ade9b69b..d5e6823a8 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -1,6 +1,6 @@ - - -## Geth at the Core +--- +title: Geth at the Core +--- 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. 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 index 04e85021c..0de531b20 100644 --- a/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx @@ -1,4 +1,7 @@ -## Separating Execution from Proving +--- +title: Separating Execution from Proving +--- + 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. @@ -6,7 +9,7 @@ When compiling the Nitro node software for _execution_, the ordinary Go compiler 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 +## 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---but 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. @@ -16,7 +19,7 @@ Second, WAVM restricts a few features of wasm. For example, WAVM does not contai 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 executing the State Transition Function. -#### ReadPreImage and the Hash Oracle Trick +## 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. diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx index 6f99d0215..16a3deda9 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -1,7 +1,10 @@ +--- +title: Optimistic Rollup +--- + -## Optimistic Rollup Arbitrum is an optimistic rollup. Let’s unpack that term. diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index d477a306f..6887a4219 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -1,6 +1,10 @@ +--- +title: Interactive Fraud Proofs +--- + -## Fraud Proofs: Challenges + Suppose the rollup chain looks like this: @@ -18,7 +22,7 @@ The game will operate in two phases: dissection, followed by one-step proof. Dis 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 +## 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. @@ -28,7 +32,7 @@ Now Alice has effectively bisected her N-step assertion into two (N/2)-step asse 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 +## 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. @@ -38,7 +42,7 @@ To prove (2), observe that if Alice’s initial claim is incorrect, this can onl (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 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. @@ -54,19 +58,19 @@ The real dissection protocol is conceptually similar to the simplified one descr 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 +## 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. -### Instant confirmation +## Instant confirmation Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. The Sequencer is given more control over ordering, so it has the power to assign its clients' transactions a position in the inbox queue, thereby ensuring that it can determine the results of client transactions immediately. The Sequencer's power to reorder has limits (see below for details) but it does have more power than anyone else to influence transaction ordering. -### Inboxes, fast and slow +## Inboxes, fast and slow When we add a Sequencer, the operation of the inbox changes. @@ -75,7 +79,7 @@ When we add a Sequencer, the operation of the inbox changes. - Messages in the delayed inbox queue will wait there until the Sequencer chooses to "release" them into the main inbox, where they will be added to the end of the inbox. A well-behaved Sequencer will typically release delayed messages after about ten minutes, for reasons explained below. - Alternatively, if a message has been in the delayed inbox queue for longer than a maximum delay interval (currently @arbOneForceIncludePeriodHours@ hours on Arbitrum One) then anyone can force it to be promoted into the main inbox. (This ensures that the Sequencer can only delay messages but can't censor them.) -### If the Sequencer is well-behaved... +## If the Sequencer is well-behaved... A well-behaved Sequencer will accept transactions from all requesters and treat them fairly, giving each one a promised transaction result as quickly as it can. @@ -87,7 +91,7 @@ This is the basic tradeoff of having a Sequencer: if your message uses the Seque So a Sequencer is generally a win, if the Sequencer is well behaved. -### If the Sequencer is malicious... +## If the Sequencer is malicious... A malicious Sequencer, on the other hand, could cause some pain. If it refuses to handle your transactions, you're forced to go through the delayed inbox, with longer delay. And a malicious Sequencer has great power to front-run everyone's transactions, so it could profit greatly at users' expense. @@ -95,7 +99,7 @@ On Arbitrum One, Offchain Labs [currently](https://docs.arbitrum.foundation/stat Because the Sequencer will be run by a trusted party at first, and will be decentralized later, we haven't built in a mechanism to directly punish a misbehaving Sequencer. We're asking users to trust the centralized Sequencer at first, until we switch to decentralized fair sequencing later. -### Decentralized fair sequencing +## Decentralized fair sequencing Viewed from 30,000 feet, decentralized fair sequencing isn't too complicated. Instead of being a single centralized server, the Sequencer is a committee of servers, and as long as a large enough supermajority of the committee is honest, the Sequencer will establish a fair ordering over transactions. diff --git a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx index c1512f5db..cb232998d 100644 --- a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx +++ b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx @@ -1,16 +1,15 @@ --- +title: AnyTrust Protocol author: dzgoldman --- -## Inside AnyTrust - 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. 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 +## 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. @@ -26,7 +25,7 @@ An L1 KeysetManager contract maintains a list of currently valid Keysets. The L2 Although the API does not limit the number of Keysets that can be valid at the same time, normally only one Keyset will be valid. -### Data Availability Certificates +## Data Availability Certificates A central concept in AnyTrust is the Data Availability Certificate (hereafter, a "DACert"). A DACert contains: @@ -51,7 +50,7 @@ The L2 code that reads data from the inbox reads a full-data block as in ordinar If the DACert is invalid, the L2 code discards the DACert and moves on to the next data block. If the DACert is valid, the L2 code reads the data block, which is guaranteed to be available because the DACert is valid. -### Data Availability Servers +## Data Availability Servers Committee members run Data Availability Server (DAS) software. The DAS exposes two APIs: @@ -62,7 +61,7 @@ Only Committee members have reason to support the Sequencer API. We expect other The DAS software, based on configuration options, can store its data in local files, or in a Badger database, or on Amazon S3, or redundantly across multiple backing stores. The software also supports optional caching in memory (using Bigcache) or in a Redis instance. -### Sequencer-Committee Interaction +## 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. diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index 48f8a0623..e301ec47f 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -1,8 +1,8 @@ --- +title: Gas and Fees author: dzgoldman --- -## Gas and Fees There are two parties a user pays when submitting a tx: @@ -13,19 +13,19 @@ The L1 component is the product of the transaction's estimated contribution to i 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 +## 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 +## 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 +## 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 +## 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. @@ -37,11 +37,11 @@ Gas estimation for Retryable submissions is possible via the [NodeInterface](/bu -### Gas and Fees +## Gas and Fees NitroGas (so-called to avoid confusion with Layer 1 Ethereum 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. -#### The Speed Limit +### 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. @@ -49,7 +49,7 @@ This sets an effective speed limit on execution of a Nitro chain: in the long ru 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. -#### Fees +### Fees User transactions pay fees, to cover the cost of operating the chain. These fees are assessed and collected by ArbOS at L2. They are denominated in ETH. @@ -59,7 +59,7 @@ Fees are charged for two resources that a transaction can use: * _L1 calldata_: a fee per unit of L1 calldata attributable to the transaction, which is charged only if the transaction came in via the Sequencer, and is paid to the Sequencer to cover its costs, -##### L2 gas fees +#### 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. @@ -71,7 +71,7 @@ Intuitively, if the backlog grows, the algorithm should increase the gas price, 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. -##### L1 calldata fees +#### 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. @@ -81,7 +81,7 @@ The L1 pricing algorithm assigns an L1 calldata fee to each Sequencer transactio 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. -##### Total fee and gas 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. diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx similarity index 99% rename from arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx rename to arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index d0bf9f28e..ae2db04b6 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messages.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -1,3 +1,8 @@ +--- +title: L1 to L2 Messaging +author: dzgoldman +--- + ## Retryable Tickets diff --git a/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messages.mdx b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx similarity index 99% rename from arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messages.mdx rename to arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx index f7ca047f6..5e1237973 100644 --- a/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messages.mdx +++ b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx @@ -1,3 +1,7 @@ +--- +title: L1 to L2 Messaging +--- + 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. diff --git a/website/sidebars.js b/website/sidebars.js index 6df6114b7..4257b0702 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -860,13 +860,13 @@ const sidebars = { }, { type: 'doc', - id: 'how-arbitrum-works/l1-to-l2-messages', - label: 'L1 to L2 messages', + id: 'how-arbitrum-works/l1-to-l2-messaging', + label: 'L1 to L2 messaging', }, { type: 'doc', - id: 'how-arbitrum-works/l2-to-l1-messages', - label: 'L2 to L1 messages', + id: 'how-arbitrum-works/l2-to-l1-messaging', + label: 'L2 to L1 messaging', }, { type: 'doc', From c706d8742d1e410be24c1379cf9fe47b3a30a439 Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 5 Dec 2024 12:42:25 -0600 Subject: [PATCH 17/35] edited nitro v classic to make it more assertive --- .../12-nitro-vs-classic.mdx | 45 +++++++++++-------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx b/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx index 76c5079a0..d6ddd7c3c 100644 --- a/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx +++ b/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx @@ -4,49 +4,56 @@ author: dzgoldman --- ## Why Nitro? +Nitro marks a significant leap forward in Arbitrum technology. This upgrade surpasses the tech stack initially launched on the Arbitrum One mainnet, now known as "Arbitrum Classic." It has evolved far beyond the original [Arbitrum whitepaper from 2018](https://www.usenix.org/system/files/conference/usenixsecurity18/sec18-kalodner.pdf). This overview will assertively detail the rationale behind the Nitro upgrade and clearly outline its key advantages over the classic system. -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. +The Classic and Nitro systems designs are similar: to establish an execution environment that closely mirrors the Ethereum Virtual Machine (EVM), operating as a robust second layer to Ethereum. This architecture guarantees the safety of Layer 2 (L2) virtual machine state updates, enforced through succinct fraud proofs on Ethereum itself. -Viewed from a distance, the Classic and Nitro systems do similar things: both seek to create an execution environment as close to the EVM as possible which operates as a second layer to Ethereum; i.e., safety of the L2 virtual machine’s state updates can be guaranteed and enforced via succinct fraud proofs on Ethereum itself. +In Arbitrum Classic, we achieved this goal using a custom-built virtual machine known as the Arbitrum Virtual Machine (AVM). The L2 state machine implementation, called "[ArbOS](/how-arbitrum-works/arbos/introduction.mdx)," is a program compiled and uploaded to the AVM, allowing it to emulate EVM execution and various other functionalities. -In Arbitrum Classic, this was achieved via a custom-made virtual machine, which we call the Arbitrum Virtual Machine (AVM). The implementation of Arbitrum’s L2 state machine—known as [“ArbOS”](/how-arbitrum-works/arbos/introduction.mdx) — is effectively a program that is compiled and uploaded to the AVM; ArbOS includes (among other things) the ability to emulate EVM execution. +With Nitro, we shift from relying on the AVM for low-level instructions to employing WebAssembly (Wasm). This shift allows us to compile Go code into Wasm, enabling the ArbOS program to be implemented in Go while incorporating [Geth](/how-arbitrum-works/arbos/geth.mdx) itself (as a sub-module). Geth is Ethereum's most widely employed implementation, underscoring our commitment to compatibility and efficiency. -In Nitro, instead of using the AVM for low-level instructions, we use WebAssembly (Wasm). Since Go code can be compiled down to Wasm, we can implement the ArbOS program in Go, and include within it (as a sub-module) [Geth itself](/how-arbitrum-works/arbos/geth.mdx), the most widely used Ethereum implementation. - -This architecture—in which Geth’s EVM implementation can be used directly—is Nitro’s defining feature, and is principally what we’re talking about when we talk about “Nitro.” Most of Nitro’s benefits are a direct or indirect consequence of this design choice. We can summarize these benefits as follows: lower fees, better Ethereum compatibility, and simplicity. +Nitro's core strength lies in its innovative architecture, seamlessly integrating Geth's EVM implementation. Most of Nitro's benefits arise directly or indirectly from this design choice, offering lower fees, enhanced compatibility with Ethereum, and simplicity. ## Lower Fees ### (Optimistic)^2 Execution +In Classic, high-level code—such as Solidity and Vyper—is compiled into EVM bytecode as if it were deployable on Ethereum. This bytecode is then transpiled by ArbOS into its corresponding AVM instructions. The resulting AVM bytecode serves as the instructions for operating the Layer 2 (L2) virtual machine and provides the necessary inputs for proving fraud. In the event of an interactive fraud proof, two validators dive deep into a segment of AVM bytecode until they establish a "one-step proof"—a state transition that showcases a single AVM opcode executed within the EVM of Layer 1 (L1). + +Nitro adopts a similar bytecode "sandwich" structure. To tackle [fraud proofing in Nitro](how-arbitrum-works/fraud-proofs/challenge-manager.mdx), the node's Go code is compiled into WebAssembly (Wasm), with individual instructions meticulously analyzed to flush out any invalid state updates. However, a crucial advantage of Nitro is its ability to periodically produce blocks akin to those in Ethereum, acting as natural state checkpoints within the broader context of an L2 state update. Nitro harnesses this strength by decisively splitting the interactive fraud proof process into two phases: -To understand the core of Nitro’s efficiency, we have to dig a little deeper into the classic AVM. In classic, high-level code (Solidity, Vyper, etc.) would be initially compiled down to the EVM bytecode (as though it were to be deployed on Ethereum). This bytecode would then be transpiled to its corresponding AVM instructions by ArbOS; this AVM bytecode would function both as the instructions for running the L2 VM, and the inputs used to prove fraud; in an interactive fraud proof, two validators dissect a segment of AVM bytecode until a “one step proof” — i.e., a state transition that represents a single AVM opcode — would be executed in the EVM of the L1 itself. +- Phase 1: The disputing parties sharpen their focus to resolve their disagreement to a single block. +- Phase 2: They compile that block into Wasm, further drilling down to Wasm instructions. -Nitro has a similar bytecode-sandwich-like structure; [to prove fraud in Nitro](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx), the node’s Go code is compiled into WebAssembly (Wasm), the individual instructions of which are ultimately similarly dissected over to zero-in on an invalid state update. There is, however, a crucial difference: Nitro, being essentially the EVM, periodically produces Ethereum-esque blocks; we can think of these blocks as natural state-checkpoints within a larger assertion of an L2 state update. Nitro takes advantage of this by splitting the interactive fraud proof game into 2 phases: first, two disputing parties narrow down their disagreement to a single block; then (and only then) do they compile the block to Wasm, and thereby continue to narrow down their dispute to Wasm instruction. Thus, this Wasm compilation step only needs to happen when a dispute occurs. +Notably, the Wasm compilation occurs only when disputes arise, maintaining efficiency. -It’s worth reiterating this distinction: in classic, the code executed in the happy/common case is equivalent to the code used in a fraud proof, whereas in Nitro, we can have different contexts for the two cases for execution and for proving. When a claim is being disputed, we ultimately compile down to Wasm bytecode, but in the happy/common case, we can execute the node’s Go code natively, i.e., in whatever execution environment one’s machine uses. Essentially, Nitro is capable of being even more “optimistic” in its execution, compiling to Wasm only just-in-time as required. The common case of native execution is happily far faster and more performant, and better node performance, of course, translates to lower fees for end users. +It's worth emphasizing this distinction: in Classic, the code executed in the happy/common case is identical to the code in the fraud proof. In stark contrast, Nitro allows for distinctly different contexts for execution and proving. When a dispute emerges, we compile down to Wasm bytecode; however, during standard operations, the node's Go code runs natively, leveraging whatever execution environment is on the machine. Nitro confidently adopts a more "optimistic" approach to execution, compiling to Wasm only as necessary. This native execution method guarantees superior speed and efficiency, leading to enhanced node performance that translates directly into lower fees for end users. ### Calldata Compression -Typically, the bulk of an Arbitrum Rollup transaction’s fee is covering the cost to post its data on Ethereum. Fundamentally, any rollup must post data on L1 sufficient for reconstruction and validation of the L2 state; beyond that, L2s can be flexible in deciding on what data format to use. Given the relatively high cost of posting data to L1, a natural optimization is to (losslessly) compress data before posting it on L1, and have the L2 environment handle decompressing it. +Most Arbitrum Rollup transactions' fees cover the essential cost of posting data on Ethereum. Any rollup must post sufficient data on Layer 1 (L1) to effectively reconstruct and validate the Layer 2 (L2) state. While L2s can choose their data formats, the high costs associated with posting data to L1 make it critical to implement optimizations. A highly effective strategy is to compress data (losslessly) before posting it on L1, allowing the L2 environment to manage decompression. -The flexibility that Arbitrum core architecture offers meant that even in the classic AVM, such decompression could have been implemented in principle. However, given that the AVM was custom-built for Arbitrum, this would have meant building a custom, hand-rolled implementation of a compression algorithm, which, practically speaking, represented a prohibitively high technical risk. +The Arbitrum core architecture's flexibility makes decompression possible, even with the Classic Arbitrum Virtual Machine (AVM). However, because the AVM is custom-built for Arbitrum, developing a proprietary implementation of a compression algorithm would have introduced excessive technical risks. -The Nitro architecture, however, fundamentally requires only that its VM can be compiled down to Wasm; so not just Geth, but any Go code can be incorporated. Thus, Nitro can (and does) use widely used, battle-tested compression libraries for calldata compression, and thus significantly reduces the cost of posting transaction batches. +In contrast, the Nitro architecture only requires its Virtual Machine (VM) to compile to WebAssembly (Wasm), meaning Ge th and any Go code are easily incorporated. This innovative approach allows Nitro to leverage widely adopted and tested compression libraries for calldata compression, drastically reducing the costs of posting transaction batches. -Note that supporting calldata compression also requires a more sophisticated mechanism for [determining the price of calldata](/how-arbitrum-works/l1-gas-pricing.mdx) and ensuring that batch posters are ultimately properly compensated, a mechanism which Nitro also introduces. +Additionally, supporting calldata compression demands a sophisticated mechanism to accurately determine the [price of calldata](/how-arbitrum-works/l1-gas-pricing.mdx) and ensure that batch posters receive appropriate compensation. Nitro effectively addresses these challenges, solidifying its framework for efficient operation. ## Closer EVM Compatibility -The classic AVM achieved a strong degree of EVM compatibility with its ability to handle any EVM opcodes. However, being a distinct VM, the AVM’s internal behavior in some ways diverged with that of the EVM. Most noticeable for smart contract developers was the denomination of “ArbGas”, whose units didn’t correspond to Ethereum L1 gas; e.g., a simple transfer takes 21,000 gas on L1 but over 100,000 ArbGas in the AVM. This meant that contracts that included gas calculation logic that were initially built for L1 had to be modified accordingly to be deployed on L2, and likewise with any client-side tooling with similar hardcoded expectations about a chain’s gas. With Nitro, [gas](/how-arbitrum-works/gas-fees.mdx) on L1 and L2 essentially correspond 1:1. +The Classic AVM demonstrated impressive EVM compatibility by effectively handling all EVM opcodes. However, its internal behavior diverged significantly from that of the EVM. A key concern for smart contract developers was the introduction of "ArbGas," a denomination whose units do not align with Ethereum L1 gas. For instance, a simple transfer requires 21,000 gas on L1 but a staggering 100,000 ArbGas within the AVM. This discrepancy necessitated modifications to contracts that relied on gas calculation logic designed for L1 before deployment on L2. It also affected client-side tools that operated under similar fixed assumptions about gas on a blockchain. Nitro resolves this issue with [gas](/how-arbitrum-works/gas-fees.mdx) costs on L1 and L2 corresponding directly in a 1:1 ratio. + +:::note + +Transactions must account for the total expenses of L2 execution and L1 calldata. The values returned by Arbitrum nodes' `eth_estimateGas` RPC, which users see in their wallets, are designed to ensure they effectively cover this entire cost. Refer to the [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) for more details. -(Note that transactions have to cover the total cost of both L2 execution and L1 calldata; the value returned by Arbitrum nodes' `eth_estimateGas` RPC — and in turn, the value users will see in their wallets — is calculated to be sufficient to cover this total cost. See [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) for more.) +::: -Additionally, node functionality peripheral to execution itself, but still important / expected by much tooling and infrastructure — e.g. support for transaction tracing — is essentially inherited out-of-the-box in Nitro, giving Nitro stronger compatibility with Ethereum not just within its virtual machine, but also with how clients interact with it. +Furthermore, Nitro enhances node functionality beyond execution, ensuring compatibility with many tools and infrastructure expectations—such as transaction tracing—available out of the box. This feature makes Nitro more compatible with Ethereum at the virtual machine level and how clients interact with the blockchain. -In short, there’s no better way to achieve Ethereum compatibility than to reuse the Ethereum software itself. +In summary, leveraging Ethereum's software is undeniably the best approach to achieving compatibility with Ethereum. ## Simplicity -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. +Maintaining code that is simple and easy to understand for Layer 2 systems is essential, given their inherent complexity. The classic stack consists of a large, in-house codebase that demands considerable time and effort to analyze effectively. In stark contrast, the Arbitrum Virtual Machine (AVM) and ArbOS combined constitute a robust blockchain protocol built from the ground up. The AVM was custom-built and lacked high-level languages at that time, forcing the implementation of ArbOS logic using 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 put into Ethereum-Geth itself — makes it a system far more accessible for auditors and contributors, giving us strong confidence in its implementation security that will only harden as the ecosystem grows. From b5d2bdb24a6316a2624690c3dcdb5d460999d5a6 Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 5 Dec 2024 13:22:30 -0600 Subject: [PATCH 18/35] minor adjustments --- .../how-arbitrum-works/12-nitro-vs-classic.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx b/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx index d6ddd7c3c..6849ffeaa 100644 --- a/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx +++ b/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx @@ -6,7 +6,7 @@ author: dzgoldman ## Why Nitro? Nitro marks a significant leap forward in Arbitrum technology. This upgrade surpasses the tech stack initially launched on the Arbitrum One mainnet, now known as "Arbitrum Classic." It has evolved far beyond the original [Arbitrum whitepaper from 2018](https://www.usenix.org/system/files/conference/usenixsecurity18/sec18-kalodner.pdf). This overview will assertively detail the rationale behind the Nitro upgrade and clearly outline its key advantages over the classic system. -The Classic and Nitro systems designs are similar: to establish an execution environment that closely mirrors the Ethereum Virtual Machine (EVM), operating as a robust second layer to Ethereum. This architecture guarantees the safety of Layer 2 (L2) virtual machine state updates, enforced through succinct fraud proofs on Ethereum itself. +The Classic and Nitro systems designs are similar establishing an execution environment that closely mirrors the Ethereum Virtual Machine (EVM), operating as a robust second layer to Ethereum. This architecture guarantees the safety of Layer 2 (L2) virtual machine state updates, enforced through succinct fraud proofs on Ethereum itself. In Arbitrum Classic, we achieved this goal using a custom-built virtual machine known as the Arbitrum Virtual Machine (AVM). The L2 state machine implementation, called "[ArbOS](/how-arbitrum-works/arbos/introduction.mdx)," is a program compiled and uploaded to the AVM, allowing it to emulate EVM execution and various other functionalities. @@ -17,30 +17,30 @@ Nitro's core strength lies in its innovative architecture, seamlessly integratin ## Lower Fees ### (Optimistic)^2 Execution -In Classic, high-level code—such as Solidity and Vyper—is compiled into EVM bytecode as if it were deployable on Ethereum. This bytecode is then transpiled by ArbOS into its corresponding AVM instructions. The resulting AVM bytecode serves as the instructions for operating the Layer 2 (L2) virtual machine and provides the necessary inputs for proving fraud. In the event of an interactive fraud proof, two validators dive deep into a segment of AVM bytecode until they establish a "one-step proof"—a state transition that showcases a single AVM opcode executed within the EVM of Layer 1 (L1). +In Classic, high-level code—such as Solidity and Vyper—is compiled into EVM bytecode as if it were deployable on Ethereum. This bytecode is then transpiled by ArbOS into its corresponding AVM instructions. The resulting AVM bytecode serves as the instructions for operating the L2 virtual machine and provides the necessary inputs for proving fraud. In the event of an interactive fraud proof, two validators dive deep into a segment of AVM bytecode until they establish a "one-step proof"—a state transition that showcases a single AVM opcode executed within the EVM of Layer 1 (L1). -Nitro adopts a similar bytecode "sandwich" structure. To tackle [fraud proofing in Nitro](how-arbitrum-works/fraud-proofs/challenge-manager.mdx), the node's Go code is compiled into WebAssembly (Wasm), with individual instructions meticulously analyzed to flush out any invalid state updates. However, a crucial advantage of Nitro is its ability to periodically produce blocks akin to those in Ethereum, acting as natural state checkpoints within the broader context of an L2 state update. Nitro harnesses this strength by decisively splitting the interactive fraud proof process into two phases: +Nitro adopts a similar bytecode "sandwich" structure. To tackle [fraud proofing in Nitro](how-arbitrum-works/fraud-proofs/challenge-manager.mdx), the node's Go code is compiled into Wasm, with individual instructions meticulously analyzed to flush out any invalid state updates. However, a crucial advantage of Nitro is its ability to periodically produce blocks akin to those in Ethereum, acting as natural state checkpoints within the broader context of an L2 state update. Nitro harnesses this strength by decisively splitting the interactive fraud proof process into two phases: - Phase 1: The disputing parties sharpen their focus to resolve their disagreement to a single block. - Phase 2: They compile that block into Wasm, further drilling down to Wasm instructions. Notably, the Wasm compilation occurs only when disputes arise, maintaining efficiency. -It's worth emphasizing this distinction: in Classic, the code executed in the happy/common case is identical to the code in the fraud proof. In stark contrast, Nitro allows for distinctly different contexts for execution and proving. When a dispute emerges, we compile down to Wasm bytecode; however, during standard operations, the node's Go code runs natively, leveraging whatever execution environment is on the machine. Nitro confidently adopts a more "optimistic" approach to execution, compiling to Wasm only as necessary. This native execution method guarantees superior speed and efficiency, leading to enhanced node performance that translates directly into lower fees for end users. +It's worth emphasizing this distinction: in Classic, the code executed in the happy/common case is identical to the code in the fraud proof. In contrast, Nitro allows for distinctly different contexts for execution and proving. When a dispute emerges, we compile down to Wasm bytecode; however, during standard operations, the node's Go code runs natively, leveraging whatever execution environment is on the machine. Nitro confidently adopts a more "optimistic" approach to execution, compiling to Wasm only as necessary. This native execution method guarantees superior speed and efficiency, leading to enhanced node performance that translates directly into lower fees for end users. ### Calldata Compression -Most Arbitrum Rollup transactions' fees cover the essential cost of posting data on Ethereum. Any rollup must post sufficient data on Layer 1 (L1) to effectively reconstruct and validate the Layer 2 (L2) state. While L2s can choose their data formats, the high costs associated with posting data to L1 make it critical to implement optimizations. A highly effective strategy is to compress data (losslessly) before posting it on L1, allowing the L2 environment to manage decompression. +Most Arbitrum Rollup transactions' fees cover the essential cost of posting data on Ethereum. Any rollup must post sufficient data on L1 to effectively reconstruct and validate the L2 state. While L2s can choose their data formats, the high costs associated with posting data to L1 make it critical to implement optimizations. A highly effective strategy is to compress data (losslessly) before posting it on L1, allowing the L2 environment to manage decompression. -The Arbitrum core architecture's flexibility makes decompression possible, even with the Classic Arbitrum Virtual Machine (AVM). However, because the AVM is custom-built for Arbitrum, developing a proprietary implementation of a compression algorithm would have introduced excessive technical risks. +Arbitrum core architecture's flexibility makes decompression possible, even with the Classic Arbitrum Virtual Machine (AVM). However, because the AVM is custom-built for Arbitrum, developing a proprietary implementation of a compression algorithm would have introduced excessive technical risks. -In contrast, the Nitro architecture only requires its Virtual Machine (VM) to compile to WebAssembly (Wasm), meaning Ge th and any Go code are easily incorporated. This innovative approach allows Nitro to leverage widely adopted and tested compression libraries for calldata compression, drastically reducing the costs of posting transaction batches. +In contrast, the Nitro architecture only requires its Virtual Machine (VM) to compile to Wasm, meaning Geth and any Go code are easily incorporated. This innovative approach allows Nitro to leverage widely adopted and tested compression libraries for calldata compression, drastically reducing the costs of posting transaction batches. Additionally, supporting calldata compression demands a sophisticated mechanism to accurately determine the [price of calldata](/how-arbitrum-works/l1-gas-pricing.mdx) and ensure that batch posters receive appropriate compensation. Nitro effectively addresses these challenges, solidifying its framework for efficient operation. ## Closer EVM Compatibility -The Classic AVM demonstrated impressive EVM compatibility by effectively handling all EVM opcodes. However, its internal behavior diverged significantly from that of the EVM. A key concern for smart contract developers was the introduction of "ArbGas," a denomination whose units do not align with Ethereum L1 gas. For instance, a simple transfer requires 21,000 gas on L1 but a staggering 100,000 ArbGas within the AVM. This discrepancy necessitated modifications to contracts that relied on gas calculation logic designed for L1 before deployment on L2. It also affected client-side tools that operated under similar fixed assumptions about gas on a blockchain. Nitro resolves this issue with [gas](/how-arbitrum-works/gas-fees.mdx) costs on L1 and L2 corresponding directly in a 1:1 ratio. +The Classic AVM demonstrated impressive EVM compatibility by effectively handling all EVM opcodes. However, its internal behavior diverged significantly from that of the EVM. A key concern for smart contract developers was the introduction of "ArbGas," a denomination whose units do not align with Ethereum L1 gas. For instance, a simple transfer requires 21,000 gas on L1 but 100,000 ArbGas within the AVM. This discrepancy necessitated modifications to contracts that relied on gas calculation logic designed for L1 before deployment on L2. It also affected client-side tools that operated under similar fixed assumptions about gas on a blockchain. Nitro resolves this issue with [gas](/how-arbitrum-works/gas-fees.mdx) costs on L1 and L2 corresponding directly in a 1:1 ratio. :::note @@ -54,6 +54,6 @@ In summary, leveraging Ethereum's software is undeniably the best approach to ac ## Simplicity -Maintaining code that is simple and easy to understand for Layer 2 systems is essential, given their inherent complexity. The classic stack consists of a large, in-house codebase that demands considerable time and effort to analyze effectively. In stark contrast, the Arbitrum Virtual Machine (AVM) and ArbOS combined constitute a robust blockchain protocol built from the ground up. The AVM was custom-built and lacked high-level languages at that time, forcing the implementation of ArbOS logic using a custom language called "mini," along with a mini-to-AVM compiler. +Maintaining code that is simple and easy to understand for Layer 2 systems is essential, given their inherent complexity. The classic stack consists of a large, in-house codebase that demands considerable time and effort to analyze effectively. In contrast, the Arbitrum Virtual Machine (AVM) and ArbOS combined constitute a robust blockchain protocol built from the ground up. The AVM was custom-built and lacked high-level languages at that time, forcing the implementation of ArbOS logic using 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 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 put into Ethereum-Geth itself — makes it a system far more accessible for auditors and contributors, giving us strong confidence in its implementation security that will only harden as the ecosystem grows. From 0d49ca012e03c08bfa2a132b49e793cf685fa2a5 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 10 Dec 2024 08:45:16 -0600 Subject: [PATCH 19/35] archiving nitro v classic/why nitro --- .../12-nitro-vs-classic.mdx | 59 ------------------- website/archive/12-nitro-vs-classic.mdx | 47 +++++++++++++++ 2 files changed, 47 insertions(+), 59 deletions(-) delete mode 100644 arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx create mode 100644 website/archive/12-nitro-vs-classic.mdx diff --git a/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx b/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx deleted file mode 100644 index 6849ffeaa..000000000 --- a/arbitrum-docs/how-arbitrum-works/12-nitro-vs-classic.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Nitro vs. Classic -author: dzgoldman ---- - -## Why Nitro? -Nitro marks a significant leap forward in Arbitrum technology. This upgrade surpasses the tech stack initially launched on the Arbitrum One mainnet, now known as "Arbitrum Classic." It has evolved far beyond the original [Arbitrum whitepaper from 2018](https://www.usenix.org/system/files/conference/usenixsecurity18/sec18-kalodner.pdf). This overview will assertively detail the rationale behind the Nitro upgrade and clearly outline its key advantages over the classic system. - -The Classic and Nitro systems designs are similar establishing an execution environment that closely mirrors the Ethereum Virtual Machine (EVM), operating as a robust second layer to Ethereum. This architecture guarantees the safety of Layer 2 (L2) virtual machine state updates, enforced through succinct fraud proofs on Ethereum itself. - -In Arbitrum Classic, we achieved this goal using a custom-built virtual machine known as the Arbitrum Virtual Machine (AVM). The L2 state machine implementation, called "[ArbOS](/how-arbitrum-works/arbos/introduction.mdx)," is a program compiled and uploaded to the AVM, allowing it to emulate EVM execution and various other functionalities. - -With Nitro, we shift from relying on the AVM for low-level instructions to employing WebAssembly (Wasm). This shift allows us to compile Go code into Wasm, enabling the ArbOS program to be implemented in Go while incorporating [Geth](/how-arbitrum-works/arbos/geth.mdx) itself (as a sub-module). Geth is Ethereum's most widely employed implementation, underscoring our commitment to compatibility and efficiency. - -Nitro's core strength lies in its innovative architecture, seamlessly integrating Geth's EVM implementation. Most of Nitro's benefits arise directly or indirectly from this design choice, offering lower fees, enhanced compatibility with Ethereum, and simplicity. - -## Lower Fees - -### (Optimistic)^2 Execution -In Classic, high-level code—such as Solidity and Vyper—is compiled into EVM bytecode as if it were deployable on Ethereum. This bytecode is then transpiled by ArbOS into its corresponding AVM instructions. The resulting AVM bytecode serves as the instructions for operating the L2 virtual machine and provides the necessary inputs for proving fraud. In the event of an interactive fraud proof, two validators dive deep into a segment of AVM bytecode until they establish a "one-step proof"—a state transition that showcases a single AVM opcode executed within the EVM of Layer 1 (L1). - -Nitro adopts a similar bytecode "sandwich" structure. To tackle [fraud proofing in Nitro](how-arbitrum-works/fraud-proofs/challenge-manager.mdx), the node's Go code is compiled into Wasm, with individual instructions meticulously analyzed to flush out any invalid state updates. However, a crucial advantage of Nitro is its ability to periodically produce blocks akin to those in Ethereum, acting as natural state checkpoints within the broader context of an L2 state update. Nitro harnesses this strength by decisively splitting the interactive fraud proof process into two phases: - -- Phase 1: The disputing parties sharpen their focus to resolve their disagreement to a single block. -- Phase 2: They compile that block into Wasm, further drilling down to Wasm instructions. - -Notably, the Wasm compilation occurs only when disputes arise, maintaining efficiency. - -It's worth emphasizing this distinction: in Classic, the code executed in the happy/common case is identical to the code in the fraud proof. In contrast, Nitro allows for distinctly different contexts for execution and proving. When a dispute emerges, we compile down to Wasm bytecode; however, during standard operations, the node's Go code runs natively, leveraging whatever execution environment is on the machine. Nitro confidently adopts a more "optimistic" approach to execution, compiling to Wasm only as necessary. This native execution method guarantees superior speed and efficiency, leading to enhanced node performance that translates directly into lower fees for end users. - -### Calldata Compression - -Most Arbitrum Rollup transactions' fees cover the essential cost of posting data on Ethereum. Any rollup must post sufficient data on L1 to effectively reconstruct and validate the L2 state. While L2s can choose their data formats, the high costs associated with posting data to L1 make it critical to implement optimizations. A highly effective strategy is to compress data (losslessly) before posting it on L1, allowing the L2 environment to manage decompression. - -Arbitrum core architecture's flexibility makes decompression possible, even with the Classic Arbitrum Virtual Machine (AVM). However, because the AVM is custom-built for Arbitrum, developing a proprietary implementation of a compression algorithm would have introduced excessive technical risks. - -In contrast, the Nitro architecture only requires its Virtual Machine (VM) to compile to Wasm, meaning Geth and any Go code are easily incorporated. This innovative approach allows Nitro to leverage widely adopted and tested compression libraries for calldata compression, drastically reducing the costs of posting transaction batches. - -Additionally, supporting calldata compression demands a sophisticated mechanism to accurately determine the [price of calldata](/how-arbitrum-works/l1-gas-pricing.mdx) and ensure that batch posters receive appropriate compensation. Nitro effectively addresses these challenges, solidifying its framework for efficient operation. - -## Closer EVM Compatibility - -The Classic AVM demonstrated impressive EVM compatibility by effectively handling all EVM opcodes. However, its internal behavior diverged significantly from that of the EVM. A key concern for smart contract developers was the introduction of "ArbGas," a denomination whose units do not align with Ethereum L1 gas. For instance, a simple transfer requires 21,000 gas on L1 but 100,000 ArbGas within the AVM. This discrepancy necessitated modifications to contracts that relied on gas calculation logic designed for L1 before deployment on L2. It also affected client-side tools that operated under similar fixed assumptions about gas on a blockchain. Nitro resolves this issue with [gas](/how-arbitrum-works/gas-fees.mdx) costs on L1 and L2 corresponding directly in a 1:1 ratio. - -:::note - -Transactions must account for the total expenses of L2 execution and L1 calldata. The values returned by Arbitrum nodes' `eth_estimateGas` RPC, which users see in their wallets, are designed to ensure they effectively cover this entire cost. Refer to the [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) for more details. - -::: - -Furthermore, Nitro enhances node functionality beyond execution, ensuring compatibility with many tools and infrastructure expectations—such as transaction tracing—available out of the box. This feature makes Nitro more compatible with Ethereum at the virtual machine level and how clients interact with the blockchain. - -In summary, leveraging Ethereum's software is undeniably the best approach to achieving compatibility with Ethereum. - -## Simplicity - -Maintaining code that is simple and easy to understand for Layer 2 systems is essential, given their inherent complexity. The classic stack consists of a large, in-house codebase that demands considerable time and effort to analyze effectively. In contrast, the Arbitrum Virtual Machine (AVM) and ArbOS combined constitute a robust blockchain protocol built from the ground up. The AVM was custom-built and lacked high-level languages at that time, forcing the implementation of ArbOS logic using 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 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 put into Ethereum-Geth itself — makes it a system far more accessible for auditors and contributors, giving us strong confidence in its implementation security that will only harden as the ecosystem grows. diff --git a/website/archive/12-nitro-vs-classic.mdx b/website/archive/12-nitro-vs-classic.mdx new file mode 100644 index 000000000..00c9cbde1 --- /dev/null +++ b/website/archive/12-nitro-vs-classic.mdx @@ -0,0 +1,47 @@ +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. + +Viewed from a distance, the Classic and Nitro systems do similar things: both seek to create an execution environment as close to the EVM as possible which operates as a second layer to Ethereum; i.e., safety of the L2 virtual machine’s state updates can be guaranteed and enforced via succinct fraud proofs on Ethereum itself. + +In Arbitrum Classic, this was achieved via a custom-made virtual machine, which we call the Arbitrum Virtual Machine (AVM). The implementation of Arbitrum’s L2 state machine—known as [“ArbOS”](/how-arbitrum-works/arbos/introduction.mdx) — is effectively a program that is compiled and uploaded to the AVM; ArbOS includes (among other things) the ability to emulate EVM execution. + +In Nitro, instead of using the AVM for low-level instructions, we use WebAssembly (Wasm). Since Go code can be compiled down to Wasm, we can implement the ArbOS program in Go, and include within it (as a sub-module) [Geth itself](/how-arbitrum-works/arbos/geth.mdx), the most widely used Ethereum implementation. + +This architecture—in which Geth’s EVM implementation can be used directly—is Nitro’s defining feature, and is principally what we’re talking about when we talk about “Nitro.” Most of Nitro’s benefits are a direct or indirect consequence of this design choice. We can summarize these benefits as follows: lower fees, better Ethereum compatibility, and simplicity. + +### Lower Fees + +#### (Optimistic)^2 Execution + +To understand the core of Nitro’s efficiency, we have to dig a little deeper into the classic AVM. In classic, high-level code (Solidity, Vyper, etc.) would be initially compiled down to the EVM bytecode (as though it were to be deployed on Ethereum). This bytecode would then be transpiled to its corresponding AVM instructions by ArbOS; this AVM bytecode would function both as the instructions for running the L2 VM, and the inputs used to prove fraud; in an interactive fraud proof, two validators dissect a segment of AVM bytecode until a “one step proof” — i.e., a state transition that represents a single AVM opcode — would be executed in the EVM of the L1 itself. + +Nitro has a similar bytecode-sandwich-like structure; [to prove fraud in Nitro](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx), the node’s Go code is compiled into WebAssembly (Wasm), the individual instructions of which are ultimately similarly dissected over to zero-in on an invalid state update. There is, however, a crucial difference: Nitro, being essentially the EVM, periodically produces Ethereum-esque blocks; we can think of these blocks as natural state-checkpoints within a larger assertion of an L2 state update. Nitro takes advantage of this by splitting the interactive fraud proof game into 2 phases: first, two disputing parties narrow down their disagreement to a single block; then (and only then) do they compile the block to Wasm, and thereby continue to narrow down their dispute to Wasm instruction. Thus, this Wasm compilation step only needs to happen when a dispute occurs. + +It’s worth reiterating this distinction: in classic, the code executed in the happy/common case is equivalent to the code used in a fraud proof, whereas in Nitro, we can have different contexts for the two cases for execution and for proving. When a claim is being disputed, we ultimately compile down to Wasm bytecode, but in the happy/common case, we can execute the node’s Go code natively, i.e., in whatever execution environment one’s machine uses. Essentially, Nitro is capable of being even more “optimistic” in its execution, compiling to Wasm only just-in-time as required. The common case of native execution is happily far faster and more performant, and better node performance, of course, translates to lower fees for end users. + +#### Calldata Compression + +Typically, the bulk of an Arbitrum Rollup transaction’s fee is covering the cost to post its data on Ethereum. Fundamentally, any rollup must post data on L1 sufficient for reconstruction and validation of the L2 state; beyond that, L2s can be flexible in deciding on what data format to use. Given the relatively high cost of posting data to L1, a natural optimization is to (losslessly) compress data before posting it on L1, and have the L2 environment handle decompressing it. + +The flexibility that Arbitrum core architecture offers meant that even in the classic AVM, such decompression could have been implemented in principle. However, given that the AVM was custom-built for Arbitrum, this would have meant building a custom, hand-rolled implementation of a compression algorithm, which, practically speaking, represented a prohibitively high technical risk. + +The Nitro architecture, however, fundamentally requires only that its VM can be compiled down to Wasm; so not just Geth, but any Go code can be incorporated. Thus, Nitro can (and does) use widely used, battle-tested compression libraries for calldata compression, and thus significantly reduces the cost of posting transaction batches. + +Note that supporting calldata compression also requires a more sophisticated mechanism for [determining the price of calldata](/how-arbitrum-works/l1-gas-pricing.mdx) and ensuring that batch posters are ultimately properly compensated, a mechanism which Nitro also introduces. + +## Closer EVM Compatibility + +The classic AVM achieved a strong degree of EVM compatibility with its ability to handle any EVM opcodes. However, being a distinct VM, the AVM’s internal behavior in some ways diverged with that of the EVM. Most noticeable for smart contract developers was the denomination of “ArbGas”, whose units didn’t correspond to Ethereum L1 gas; e.g., a simple transfer takes 21,000 gas on L1 but over 100,000 ArbGas in the AVM. This meant that contracts that included gas calculation logic that were initially built for L1 had to be modified accordingly to be deployed on L2, and likewise with any client-side tooling with similar hardcoded expectations about a chain’s gas. With Nitro, [gas](/how-arbitrum-works/gas-fees.mdx) on L1 and L2 essentially correspond 1:1. + +(Note that transactions have to cover the total cost of both L2 execution and L1 calldata; the value returned by Arbitrum nodes' `eth_estimateGas` RPC — and in turn, the value users will see in their wallets — is calculated to be sufficient to cover this total cost. See [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) for more.) + +Additionally, node functionality peripheral to execution itself, but still important / expected by much tooling and infrastructure — e.g. support for transaction tracing — is essentially inherited out-of-the-box in Nitro, giving Nitro stronger compatibility with Ethereum not just within its virtual machine, but also with how clients interact with it. + +In short, there’s no better way to achieve Ethereum compatibility than to reuse the Ethereum software itself. + +## Simplicity + +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. \ No newline at end of file From d09cd63f185c446de4b1eab043e0996952dc3296 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 10 Dec 2024 09:09:17 -0600 Subject: [PATCH 20/35] yarn format --- arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx | 3 ++- .../05-separating-execution-from-proving.mdx | 1 - arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx | 1 - .../how-arbitrum-works/07-interactive-fraud-proofs.mdx | 2 -- arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx | 1 - 5 files changed, 2 insertions(+), 6 deletions(-) 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 index e2e0dfad5..e5e4256aa 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -149,7 +149,8 @@ Please note any links on this page may be referencing old releases of Nitro or o 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. ->>>>>>> master:arbitrum-docs/how-arbitrum-works/arbos/geth.mdx + +> > > > > > > master:arbitrum-docs/how-arbitrum-works/arbos/geth.mdx - `core.ApplyTransaction` ⮕ `core.applyTransaction` ⮕ `core.ApplyMessage` - `core.NewStateTransition` 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 index 0de531b20..7a247ee71 100644 --- a/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx @@ -2,7 +2,6 @@ title: Separating Execution from Proving --- - 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.) diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx index 16a3deda9..6e4b61e2c 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -5,7 +5,6 @@ title: Optimistic Rollup - Arbitrum is an optimistic rollup. Let’s unpack that term. _Rollup_ diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index 6887a4219..3994da5da 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -4,8 +4,6 @@ title: Interactive Fraud Proofs - - Suppose the rollup chain looks like this: ![img](https://lh4.googleusercontent.com/kAZY9H73dqcHvboFDby9nrtbYZrbsHCYtE5X9NIZQsvcz58vV0WUWUq1xsYKzYWQSc1nPZ8W86LLX0lD3y-ctEaG2ISa2Wpz2pYxTzW09P1UvqSDuoqkHlGDYLLMTzLqX4rlP8Ca) diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index e301ec47f..16587e36a 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -3,7 +3,6 @@ title: Gas and Fees author: dzgoldman --- - 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 From e2c86d3adf6bfa13523fcf9fb973465fff33be1c Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 10 Dec 2024 09:10:47 -0600 Subject: [PATCH 21/35] modified sidebars --- website/sidebars.js | 5 ----- 1 file changed, 5 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index bd6e30333..f07528504 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -871,11 +871,6 @@ const sidebars = { id: 'how-arbitrum-works/l2-to-l1-messaging', label: 'L2 to L1 messaging', }, - { - type: 'doc', - id: 'how-arbitrum-works/nitro-vs-classic', - label: 'Nitro vs. Classic', - }, { type: 'link', href: 'https://github.com/OffchainLabs/nitro/blob/master/docs/Nitro-whitepaper.pdf', From 2b764664c699b3f946871ce2847e80cacedf3784 Mon Sep 17 00:00:00 2001 From: Pete Date: Tue, 10 Dec 2024 09:16:27 -0600 Subject: [PATCH 22/35] fixing broken links --- arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx | 2 +- arbitrum-docs/stylus/stylus-quickstart.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx index 6e4b61e2c..33f3b5d78 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -294,6 +294,6 @@ The only delay that users experience during a dispute is of their [L2 to L1 mess ### 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/assertion-tree.mdx). diff --git a/arbitrum-docs/stylus/stylus-quickstart.mdx b/arbitrum-docs/stylus/stylus-quickstart.mdx index c3f103d98..a8b13850e 100644 --- a/arbitrum-docs/stylus/stylus-quickstart.mdx +++ b/arbitrum-docs/stylus/stylus-quickstart.mdx @@ -204,7 +204,7 @@ deployment tx total cost: "0.000712373700000000" ETH ### Deployment -Let's move on to the contract's actual deployment. Two transactions will be sent onchain: the contract deployment and its [activation](/stylus/stylus-gentle-introduction.md#activation). +Let's move on to the contract's actual deployment. Two transactions will be sent onchain: the contract deployment and its activation. ```shell cargo stylus deploy \ From c82e3f55494048c15cd7262f8499c6ca17af722d Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 12 Dec 2024 10:28:21 -0600 Subject: [PATCH 23/35] addressing quick hit comments --- .../01-a-gentle-introduction.mdx | 7 +- .../02-transaction-lifecycle.mdx | 16 +- .../how-arbitrum-works/03-sequencer.mdx | 73 ++++-- .../04-geth-at-the-core.mdx | 234 +++++++++--------- .../05-separating-execution-from-proving.mdx | 8 +- .../06-optimistic-rollup.mdx | 52 ++-- .../07-interactive-fraud-proofs.mdx | 70 +----- .../08-anytrust-protocol.mdx | 6 +- .../how-arbitrum-works/09-gas-fees.mdx | 12 +- .../10-l1-to-l2-messaging.mdx | 18 +- .../11-l2-to-l1-messaging.mdx | 7 +- arbitrum-docs/stylus/stylus-quickstart.mdx | 2 +- .../archive}/inside-arbitrum-nitro.mdx | 0 website/docusaurus.config.js | 4 +- 14 files changed, 255 insertions(+), 254 deletions(-) rename {arbitrum-docs/how-arbitrum-works => website/archive}/inside-arbitrum-nitro.mdx (100%) diff --git a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx index 64984d712..669ca6fad 100644 --- a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -11,7 +11,7 @@ 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, which is used by the Arbitrum Nova chain. AnyTrust is covered by a section at the end of this document. +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/anytrust-protocol.mdx), which is used by the Arbitrum Nova chain. ## Why use Arbitrum? Why use Nitro? @@ -24,7 +24,7 @@ Arbitrum is an L2 scaling solution for Ethereum, offering a unique combination o 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, improving over "classic" Arbitrum in several ways: +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. @@ -69,3 +69,6 @@ The essence of Nitro, and its key innovations, lie in four big ideas. We'll list **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. \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx index 99508a4d9..3d67dd737 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -1,8 +1,12 @@ --- -title: Transaction Lifecycle +title: Sequencing, Followed by Deterministic Execution +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +content_type: get-started --- -## Sequencing, Followed by Deterministic Execution This diagram summarizes how transactions are processed in Nitro. @@ -20,13 +24,13 @@ The state transition function is deterministic, which means that its behavior de It follows that anyone who knows the transaction sequence can compute the state transition function for themselves--and all honest parties who do this are guaranteed to get identical results. This is the normal way that Nitro nodes operate: get the transaction sequence, and run the state transition function locally. No consensus mechanism is needed for this. -## Overview: The Lifecycle of an Arbitrum Transaction +## Deep dive: 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 now 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. +This section will focus 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). @@ -64,7 +68,7 @@ Upon receiving a transaction, the Sequencer will: #### ~ ~ ~ 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). +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 diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 8869381e7..e232aa0bf 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -1,9 +1,12 @@ --- -title: Sequencer +title: The Sequencer and Censorship Resistance +description: 'Learn the fundamentals of the Arbitrum Sequencer.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +content_type: get-started --- -## 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. @@ -14,15 +17,15 @@ Clients interact with the Sequencer in exactly the same way they would interact ### 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. +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](/how-arbitrum-works/arbos/transaction-lifecycle.mdx)”). 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. - -### Bridging +### Happy/Common Case: Sequencer Is Live and Well-behaved -We have already 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. Let’s talk about how contracts interact between L1 and L2--how an L1 contract calls an L2 contract, and vice versa. +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. -The 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. As a consequence, a cross-chain contract-to-contract call can never produce a result that is available to the calling contract (except for acknowledgement that the call was successfully submitted for later execution). +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. #### L1 contracts can submit L2 transactions @@ -54,16 +57,7 @@ Calls from L2 to L1 operate in a similar way, with a ticket-based system. An L2 These L2-to-L1 tickets have unlimited lifetime, until they’re successfully redeemed. No rent is required, as the tickets (actually a Merkle hash of the tickets) are recorded in Ethereum storage, which does not require rent. (The cost of allocating storage for the ticket Merkle roots is covered by L2 transaction fees.) - - -### 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. +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/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. @@ -81,7 +75,6 @@ On top of the delay itself, the `forceInclusion` path has the downside of uncert 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. - #### How the Sequencer Publishes the Sequence @@ -93,4 +86,44 @@ The Sequencer also publishes its sequence on the L1 Ethereum chain. Periodically The Sequencer's batches are compressed using a general-purpose data compression algorithm called "brotli", on its highest-compression setting. - + +## Instant confirmation + +Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. + +The Sequencer is given more control over ordering, so it has the power to assign its clients' transactions a position in the inbox queue, thereby ensuring that it can determine the results of client transactions immediately. The Sequencer's power to reorder has limits (see below for details) but it does have more power than anyone else to influence transaction ordering. + +## Inboxes, fast and slow + +When we add a Sequencer, the operation of the inbox changes. + +- Only the Sequencer can put new messages directly into the inbox. The Sequencer tags the messages it is submitting with an Ethereum block number and timestamp. (ArbOS ensures that these are non-decreasing, adjusting them upward if necessary to avoid decreases.) +- Anyone else can submit a message, but messages submitted by non-Sequencer nodes will be put into the "delayed inbox" queue, which is managed by an L1 Ethereum contract. + - Messages in the delayed inbox queue will wait there until the Sequencer chooses to "release" them into the main inbox, where they will be added to the end of the inbox. A well-behaved Sequencer will typically release delayed messages after about ten minutes, for reasons explained below. + - Alternatively, if a message has been in the delayed inbox queue for longer than a maximum delay interval (currently @arbOneForceIncludePeriodHours@ hours on Arbitrum One) then anyone can force it to be promoted into the main inbox. (This ensures that the Sequencer can only delay messages but can't censor them.) + +## If the Sequencer is well-behaved... + +A well-behaved Sequencer will accept transactions from all requesters and treat them fairly, giving each one a promised transaction result as quickly as it can. + +It will also minimize the delay it imposes on non-Sequencer transactions by releasing delayed messages promptly, consistent with the goal of providing strong promises of transaction results. Specifically, if the Sequencer believes that 40 confirmation blocks are needed to have good confidence of finality on Ethereum, then it will release delayed messages after 40 blocks. This is enough to ensure that the Sequencer knows exactly which transactions will precede its current transaction, because those preceding transactions have finality. There is no need for a benign Sequencer to delay non-Sequencer messages more than that, so it won't. + +This does mean that transactions that go through the delayed inbox will take longer to get finality. Their time to finality will roughly double, because they will have to wait one finality period for promotion, then another finality period for the Ethereum transaction that promoted them to achieve finality. + +This is the basic tradeoff of having a Sequencer: if your message uses the Sequencer, finality is C blocks faster; but if your message doesn't use the Sequencer, finality is C blocks slower. This is usually a good tradeoff, because most transactions will use the Sequencer; and because the practical difference between instant and 10-minute finality is bigger than the difference between 10-minute and 20-minute finality. + +So a Sequencer is generally a win, if the Sequencer is well behaved. + +## If the Sequencer is malicious... + +A malicious Sequencer, on the other hand, could cause some pain. If it refuses to handle your transactions, you're forced to go through the delayed inbox, with longer delay. And a malicious Sequencer has great power to front-run everyone's transactions, so it could profit greatly at users' expense. + +On Arbitrum One, Offchain Labs [currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization) runs a Sequencer which is well-behaved--we promise!. This will be useful but it's not decentralized. Over time, we'll switch to decentralized, fair sequencing, as described below. + +Because the Sequencer will be run by a trusted party at first, and will be decentralized later, we haven't built in a mechanism to directly punish a misbehaving Sequencer. We're asking users to trust the centralized Sequencer at first, until we switch to decentralized fair sequencing later. + +## Decentralized fair sequencing + +Viewed from 30,000 feet, decentralized fair sequencing isn't too complicated. Instead of being a single centralized server, the Sequencer is a committee of servers, and as long as a large enough supermajority of the committee is honest, the Sequencer will establish a fair ordering over transactions. + +How to achieve this is more complicated. Research by a team at Cornell Tech, including Offchain Labs CEO and Co-founder Steven Goldfeder, developed the first-ever decentralized fair sequencing algorithm. With some improvements that are under development, these concepts will form the basis for our longer-term solution, of a fair decentralized Sequencer. 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 index e5e4256aa..dd0678dda 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -1,5 +1,10 @@ --- -title: Geth at the Core +title: Geth at the core +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +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. @@ -16,122 +21,14 @@ Because the top and bottom layers rely heavily on code from geth, this structure 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. - + -## 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/arbos/l1-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](geth#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](geth#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 - - - - ## 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. +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. @@ -150,7 +47,6 @@ Arbitrum uses various hooks to modify Geth's behavior when processing transactio 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. -> > > > > > > master:arbitrum-docs/how-arbitrum-works/arbos/geth.mdx - `core.ApplyTransaction` ⮕ `core.applyTransaction` ⮕ `core.ApplyMessage` - `core.NewStateTransition` @@ -420,4 +316,112 @@ Genesis block in nitro is not necessarily block #0. Nitro supports importing blo [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/arbos/l1-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](geth#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](geth#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 index 7a247ee71..444a5f2f4 100644 --- a/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx @@ -1,7 +1,13 @@ --- title: Separating Execution from Proving +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +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.) @@ -29,5 +35,3 @@ As an example, the state of a Nitro chain is maintained in Ethereum's state tree 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 index 33f3b5d78..63dcd9d94 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -1,5 +1,10 @@ --- title: Optimistic Rollup +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +content_type: get-started --- @@ -71,6 +76,8 @@ The parties who participate in the protocol are called _validators_. Some valida 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 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. @@ -233,9 +240,18 @@ The first unresolved RBlock can be rejected if: 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/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. + + +### Detailed Spec + +For a more detailed breakdown / specification of the assertion tree protocol, see [Inside Arbitrum](/how-arbitrum-works/assertion-tree.mdx). + ## Validators @@ -262,38 +278,6 @@ Who will be validators? Anyone will be able to do it, but most people will choos - 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. - - - - -# The Assertion Tree - -### Overview -The state of an Arbitrum chain is confirmed back on Ethereum via "assertions," aka "disputable assertions" or "DAs." These are claims made by Arbitrum validators about the chain's state. To make an assertion, a validator must post a bond in Ether. -In the happy / common case, all outstanding assertions will be valid; i.e., a valid assertion will build on another valid assertion, which builds on another valid assertion, and so on. After the dispute period (~ 1 week) passes and an assertion goes unchallenged, it can be confirmed back on L1. - -If, however, two or more conflicting assertions exist, the Assertion Tree bifurcates into multiple branches: - -![img](../assets/assertionTree.png) - -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. - -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.) - -These properties together ensure that as long as at least one honest, active validator exists, the valid chain state will ultimately be confirmed. - -### Delays - -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. - -### Detailed Spec - -For a more detailed breakdown / specification of the assertion tree protocol, see [Inside Arbitrum](/how-arbitrum-works/assertion-tree.mdx). - diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index 3994da5da..0e823899a 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -1,8 +1,12 @@ --- -title: Interactive Fraud Proofs +title: Challenges: Interactive Fraud Proofs +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +content_type: get-started --- - Suppose the rollup chain looks like this: @@ -62,56 +66,11 @@ The challenge protocol is designed so that the dispute can be resolved with a mi 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. -## Instant confirmation - -Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. - -The Sequencer is given more control over ordering, so it has the power to assign its clients' transactions a position in the inbox queue, thereby ensuring that it can determine the results of client transactions immediately. The Sequencer's power to reorder has limits (see below for details) but it does have more power than anyone else to influence transaction ordering. - -## Inboxes, fast and slow - -When we add a Sequencer, the operation of the inbox changes. - -- Only the Sequencer can put new messages directly into the inbox. The Sequencer tags the messages it is submitting with an Ethereum block number and timestamp. (ArbOS ensures that these are non-decreasing, adjusting them upward if necessary to avoid decreases.) -- Anyone else can submit a message, but messages submitted by non-Sequencer nodes will be put into the "delayed inbox" queue, which is managed by an L1 Ethereum contract. - - Messages in the delayed inbox queue will wait there until the Sequencer chooses to "release" them into the main inbox, where they will be added to the end of the inbox. A well-behaved Sequencer will typically release delayed messages after about ten minutes, for reasons explained below. - - Alternatively, if a message has been in the delayed inbox queue for longer than a maximum delay interval (currently @arbOneForceIncludePeriodHours@ hours on Arbitrum One) then anyone can force it to be promoted into the main inbox. (This ensures that the Sequencer can only delay messages but can't censor them.) - -## If the Sequencer is well-behaved... - -A well-behaved Sequencer will accept transactions from all requesters and treat them fairly, giving each one a promised transaction result as quickly as it can. - -It will also minimize the delay it imposes on non-Sequencer transactions by releasing delayed messages promptly, consistent with the goal of providing strong promises of transaction results. Specifically, if the Sequencer believes that 40 confirmation blocks are needed to have good confidence of finality on Ethereum, then it will release delayed messages after 40 blocks. This is enough to ensure that the Sequencer knows exactly which transactions will precede its current transaction, because those preceding transactions have finality. There is no need for a benign Sequencer to delay non-Sequencer messages more than that, so it won't. - -This does mean that transactions that go through the delayed inbox will take longer to get finality. Their time to finality will roughly double, because they will have to wait one finality period for promotion, then another finality period for the Ethereum transaction that promoted them to achieve finality. - -This is the basic tradeoff of having a Sequencer: if your message uses the Sequencer, finality is C blocks faster; but if your message doesn't use the Sequencer, finality is C blocks slower. This is usually a good tradeoff, because most transactions will use the Sequencer; and because the practical difference between instant and 10-minute finality is bigger than the difference between 10-minute and 20-minute finality. - -So a Sequencer is generally a win, if the Sequencer is well behaved. - -## If the Sequencer is malicious... - -A malicious Sequencer, on the other hand, could cause some pain. If it refuses to handle your transactions, you're forced to go through the delayed inbox, with longer delay. And a malicious Sequencer has great power to front-run everyone's transactions, so it could profit greatly at users' expense. - -On Arbitrum One, Offchain Labs [currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization) runs a Sequencer which is well-behaved--we promise!. This will be useful but it's not decentralized. Over time, we'll switch to decentralized, fair sequencing, as described below. - -Because the Sequencer will be run by a trusted party at first, and will be decentralized later, we haven't built in a mechanism to directly punish a misbehaving Sequencer. We're asking users to trust the centralized Sequencer at first, until we switch to decentralized fair sequencing later. - -## Decentralized fair sequencing - -Viewed from 30,000 feet, decentralized fair sequencing isn't too complicated. Instead of being a single centralized server, the Sequencer is a committee of servers, and as long as a large enough supermajority of the committee is honest, the Sequencer will establish a fair ordering over transactions. - -How to achieve this is more complicated. Research by a team at Cornell Tech, including Offchain Labs CEO and Co-founder Steven Goldfeder, developed the first-ever decentralized fair sequencing algorithm. With some improvements that are under development, these concepts will form the basis for our longer-term solution, of a fair decentralized Sequencer. - - - - ## ChallengeManager - -The `ChallengeManager` arbitrates challenge games. Here's a diagram of the challenge state machine: +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: @@ -172,9 +131,7 @@ 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 @@ -252,9 +209,6 @@ 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 @@ -318,9 +272,6 @@ 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 @@ -397,9 +348,7 @@ For these instruction descriptions, all pointers and offsets are represented as | 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 @@ -434,9 +383,6 @@ Floating point to integer truncation will saturate on overflow, instead of error 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 @@ -495,5 +441,3 @@ 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/08-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx index cb232998d..0ca414de5 100644 --- a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx +++ b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx @@ -1,6 +1,10 @@ --- title: AnyTrust Protocol -author: dzgoldman +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +content_type: get-started --- AnyTrust is a variant of Arbitrum Nitro technology that lowers costs by accepting a mild trust assumption. diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index 16587e36a..534c16c72 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -1,8 +1,14 @@ --- title: Gas and Fees -author: dzgoldman +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +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 @@ -34,11 +40,9 @@ Gas estimation for Retryable submissions is possible via the [NodeInterface](/bu [estimation_inclusion_link]: https://github.com/OffchainLabs/go-ethereum/blob/d52739e6d54f2ea06146fdc44947af3488b89082/internal/ethapi/api.go#L999 - -## Gas and Fees -NitroGas (so-called to avoid confusion with Layer 1 Ethereum 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. + ### The Speed Limit diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index ae2db04b6..bd93bc7a6 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -1,9 +1,21 @@ --- -title: L1 to L2 Messaging -author: dzgoldman +title: L1 to L2 messaging +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +content_type: get-started --- - + +### Bridging + +We have already 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. Let’s talk about how contracts interact between L1 and L2--how an L1 contract calls an L2 contract, and vice versa. + +The 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. As a consequence, a cross-chain contract-to-contract call can never produce a result that is available to the calling contract (except for acknowledgement that the call was successfully submitted for later execution). + + + ## Retryable Tickets 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 index 5e1237973..ea36cde80 100644 --- a/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx @@ -1,5 +1,10 @@ --- -title: L1 to L2 Messaging +title: L2 to L1 messaging +description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +author: pete-vielhaber +sme: TucksonDev +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +content_type: get-started --- diff --git a/arbitrum-docs/stylus/stylus-quickstart.mdx b/arbitrum-docs/stylus/stylus-quickstart.mdx index a8b13850e..c3f103d98 100644 --- a/arbitrum-docs/stylus/stylus-quickstart.mdx +++ b/arbitrum-docs/stylus/stylus-quickstart.mdx @@ -204,7 +204,7 @@ deployment tx total cost: "0.000712373700000000" ETH ### Deployment -Let's move on to the contract's actual deployment. Two transactions will be sent onchain: the contract deployment and its activation. +Let's move on to the contract's actual deployment. Two transactions will be sent onchain: the contract deployment and its [activation](/stylus/stylus-gentle-introduction.md#activation). ```shell cargo stylus deploy \ diff --git a/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx b/website/archive/inside-arbitrum-nitro.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx rename to website/archive/inside-arbitrum-nitro.mdx diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 878d81071..6140f97d3 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -11,8 +11,8 @@ const config = { tagline: 'Arbitrum Docs', url: 'https://docs.arbitrum.io/', baseUrl: '/', - onBrokenLinks: 'ignore', - onBrokenMarkdownLinks: 'ignore', + onBrokenLinks: 'throw', + onBrokenMarkdownLinks: 'throw', favicon: 'img/logo.svg', markdown: { mermaid: true, From 0d4ccb8ba0356828b52e454553abb49528daf580 Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 12 Dec 2024 10:58:06 -0600 Subject: [PATCH 24/35] content changes, frontmatter additions --- .../how-arbitrum-works/03-sequencer.mdx | 14 ++++++------- .../04-geth-at-the-core.mdx | 5 ++--- .../05-separating-execution-from-proving.mdx | 2 +- .../06-optimistic-rollup.mdx | 8 +------ .../07-interactive-fraud-proofs.mdx | 4 ++-- .../08-anytrust-protocol.mdx | 2 +- .../how-arbitrum-works/09-gas-fees.mdx | 8 ++----- .../10-l1-to-l2-messaging.mdx | 21 +++++++------------ .../11-l2-to-l1-messaging.mdx | 6 +----- .../how-arbitrum-works/assertion-tree.mdx | 2 +- 10 files changed, 25 insertions(+), 47 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index e232aa0bf..2bc80a958 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -15,19 +15,19 @@ Clients interact with the Sequencer in exactly the same way they would interact [Currently](https://docs.arbitrum.foundation/state-of-progressive-decentralization), on the Arbitrum One and Arbitrum Nova chains, the Sequencer is run by Offchain Labs. -### The Core Inbox +## 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](/how-arbitrum-works/arbos/transaction-lifecycle.mdx)”). 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 +## 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. -#### L1 contracts can submit L2 transactions +### L1 contracts can submit L2 transactions An L1 contract can submit an L2 transaction, just like a user would, by calling the Nitro chain's inbox contract on Ethereum. This L2 transaction will run later, producing results that will not be available to the L1 caller. The transaction will execute at L2, but the L1 caller won’t be able to see any results from the L2 transaction. @@ -35,7 +35,7 @@ The advantage of this method is that it is simple and has relatively low latency This would introduce a serious a problem for certain types of L1 to L2 interactions. Consider a transaction that includes depositing a token on L1 to be made available at some address on L2. If the L1 side succeeds, but the L2 side reverts, you've just sent some tokens to the L1 inbox contract that are unrecoverable on either L2 or L1. Not good. -#### L1 to L2 ticket-based transactions +### L1 to L2 ticket-based transactions Fortunately, we have another method for L1 to L2 calls, which is more robust against gas-related failures, that uses a ticket-based system. The idea is that an L1 contract can submit a “retryable” transaction. The Nitro chain will try to run that transaction. If the transaction succeeds, nothing else needs to happen. But if the transaction fails, Nitro will create a “ticketID” that identifies that failed transaction. Later, anyone can call a special pre-compiled contract at L2, providing the ticketID, to try redeeming the ticket and re-executing the transaction. @@ -51,7 +51,7 @@ When the ticket is redeemed, the pre-packaged transaction runs with sender and o This mechanism is a bit more cumbersome than ordinary L1 to L2 transactions, but it has the advantage that the submission cost is predictable and the ticket will always be available for redemption if the submission cost is paid. As long as there is some user who is willing to redeem the ticket, the L2 transaction will eventually be able to execute and will not be silently dropped. -#### L2 to L1 ticket-based calls +### L2 to L1 ticket-based calls Calls from L2 to L1 operate in a similar way, with a ticket-based system. An L2 contract can call a method of the precompiled ArbSys contract, to send a transaction to L1. When the execution of the L2 transaction containing the submission is confirmed at L1 (some days later), a ticket is created in the L1 outbox contract. That ticket can be triggered by anyone who calls a certain L1 outbox method and submits the ticketID. The ticket is only marked as redeemed if the L1 transaction does not revert. @@ -61,7 +61,7 @@ Alternatively, a user can submit their L2 message to the Sequencer by posting it 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 +## 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: @@ -76,7 +76,7 @@ On top of the delay itself, the `forceInclusion` path has the downside of uncert 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. -#### How the Sequencer Publishes the Sequence +### How the Sequencer Publishes the Sequence So how do nodes get the sequence? The Sequencer publishes it in two ways: a real-time feed, and batches posted on L1 Ethereum. 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 index dd0678dda..f3ffa206d 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -21,9 +21,8 @@ Because the top and bottom layers rely heavily on code from geth, this structure 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/separating-execution-from-proving.mdx). + ## Geth 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 index 444a5f2f4..def946120 100644 --- a/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx @@ -34,4 +34,4 @@ As an example, the state of a Nitro chain is maintained in Ethereum's state tree 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. +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. \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx index 63dcd9d94..50cd0bcc1 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -7,9 +7,6 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- - - - Arbitrum is an optimistic rollup. Let’s unpack that term. _Rollup_ @@ -277,7 +274,4 @@ Who will be validators? Anyone will be able to do it, but most people will choos - 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. - - - +- 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. \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index 0e823899a..4cfa74934 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -67,12 +67,12 @@ The challenge protocol is designed so that the dispute can be resolved with a mi 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 diff --git a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx index 0ca414de5..7180f3709 100644 --- a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx +++ b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx @@ -71,4 +71,4 @@ When the Arbitrum sequencer produces a data batch that it wants to post using th 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. -If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. +If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index 534c16c72..ad1c6c8be 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -42,7 +42,7 @@ Gas estimation for Retryable submissions is possible via the [NodeInterface](/bu - + - ## L1 gas pricing @@ -147,6 +145,4 @@ A second term is added to the L1 Gas Basefee, based on the derivative of the sur 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. - - +Arbitrum transaction receipts include a `gasUsedForL1` field, showing the amount of gas used on L1 in units of L2 gas. --> \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index bd93bc7a6..ff1fcb6da 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -7,14 +7,11 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- - -### Bridging - -We have already 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. Let’s talk about how contracts interact between L1 and L2--how an L1 contract calls an L2 contract, and vice versa. - -The 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. As a consequence, a cross-chain contract-to-contract call can never produce a result that is available to the calling contract (except for acknowledgement that the call was successfully submitted for later execution). +In the [Transaction Lifecycle](/how-arbitrum-works/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 @@ -47,7 +44,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket [inbox_link]: https://github.com/OffchainLabs/nitro-contracts/blob/67127e2c2fd0943d9d87a05915d77b1f220906aa/src/bridge/Inbox.sol - ### Automatic Redemption @@ -96,7 +91,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket - If a redeem is not done at submission or the submission's initial redeem fails (for example, because the L2 gas price has increased unexpectedly), the submission fee is collected on L2 to cover the resources required to temporarily keep the ticket in memory for a fixed period (one week), and only in this case, a manual redemption of the ticket is required (see next section). - + ### Manual Redemption @@ -141,7 +135,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket [discard_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/retryables/retryable.go#L262 [renew_link]: https://github.com/OffchainLabs/nitro-contracts/blob/a68783436b5105a64f54efe5fbd55174704a7618/src/precompiles/ArbRetryableTx.sol#L41 - + :::caution Avoid Losing Funds! @@ -232,7 +225,7 @@ L2_Alias = L1_Contract_Address + 0x1111000000000000000000000000000000001111 :::tip Try it out - + ::: @@ -251,4 +244,4 @@ modifier onlyFromMyL1Contract() override { 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)). +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)). \ No newline at end of file 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 index ea36cde80..7aad30cc7 100644 --- a/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx @@ -7,8 +7,6 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou 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/arbos/l1-l2-messaging.mdx) (Retryables), "in reverse" though with a few differences. ### Protocol Flow @@ -28,6 +26,4 @@ Unlike Retryables, which have an option to provide Ether for automatic L2 execut 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. - - +\*\* 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. \ No newline at end of file diff --git a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx index 1669c1944..d8d6a3526 100644 --- a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx +++ b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx @@ -30,4 +30,4 @@ The only delay that users experience during a dispute is of their [L2 to L1 mess ### 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/inside-arbitrum-nitro.mdx#arbitrum-rollup-protocol). \ No newline at end of file From 01a7a43ba667f3f8e7911fa8563419d3db21231b Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 12 Dec 2024 13:02:21 -0600 Subject: [PATCH 25/35] gas & fees content, yarn format --- .../01-a-gentle-introduction.mdx | 3 +- .../02-transaction-lifecycle.mdx | 1 - .../how-arbitrum-works/03-sequencer.mdx | 3 - .../04-geth-at-the-core.mdx | 6 - .../05-separating-execution-from-proving.mdx | 3 +- .../06-optimistic-rollup.mdx | 7 +- .../07-interactive-fraud-proofs.mdx | 10 +- .../08-anytrust-protocol.mdx | 2 +- .../how-arbitrum-works/09-gas-fees.mdx | 103 +++++++++++++++++- .../10-l1-to-l2-messaging.mdx | 10 +- .../11-l2-to-l1-messaging.mdx | 2 +- .../how-arbitrum-works/assertion-tree.mdx | 2 +- 12 files changed, 107 insertions(+), 45 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx index 669ca6fad..1c9153861 100644 --- a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -70,5 +70,4 @@ The essence of Nitro, and its key innovations, lie in four big ideas. We'll list **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. \ No newline at end of file +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 index 3d67dd737..742653084 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -7,7 +7,6 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- - This diagram summarizes how transactions are processed in Nitro. ![seq-then-exec](../assets/seq-then-exec.png) diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 2bc80a958..5bf5725c4 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -19,7 +19,6 @@ Clients interact with the Sequencer in exactly the same way they would interact 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](/how-arbitrum-works/arbos/transaction-lifecycle.mdx)”). 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. @@ -75,7 +74,6 @@ On top of the delay itself, the `forceInclusion` path has the downside of uncert 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. - ### How the Sequencer Publishes the Sequence So how do nodes get the sequence? The Sequencer publishes it in two ways: a real-time feed, and batches posted on L1 Ethereum. @@ -86,7 +84,6 @@ The Sequencer also publishes its sequence on the L1 Ethereum chain. Periodically The Sequencer's batches are compressed using a general-purpose data compression algorithm called "brotli", on its highest-compression setting. - ## Instant confirmation Without a Sequencer, a node can predict what the results of a client transaction will be, but the node can't be sure, because it can't know or control how the transactions it submits will be ordered in the inbox, relative to transactions submitted by other nodes. 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 index f3ffa206d..5e1e9ac3e 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -23,8 +23,6 @@ The State Transition Function consists of the bottom Geth layer, and a portion o 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/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. @@ -46,7 +44,6 @@ Arbitrum uses various hooks to modify Geth's behavior when processing transactio 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) @@ -315,8 +312,6 @@ Genesis block in nitro is not necessarily block #0. Nitro supports importing blo [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. @@ -423,4 +418,3 @@ ArbOS's per-block gas limit is distinct from Geth's block limit, which ArbOS [se [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 index def946120..80085f8c1 100644 --- a/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx @@ -7,7 +7,6 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou 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.) @@ -34,4 +33,4 @@ As an example, the state of a Nitro chain is maintained in Ethereum's state tree 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. \ No newline at end of file +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 index 50cd0bcc1..e7e110704 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -73,8 +73,6 @@ The parties who participate in the protocol are called _validators_. Some valida 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 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. @@ -237,19 +235,16 @@ The first unresolved RBlock can be rejected if: 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/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. - ### Detailed Spec For a more detailed breakdown / specification of the assertion tree protocol, see [Inside Arbitrum](/how-arbitrum-works/assertion-tree.mdx). - ## 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. @@ -274,4 +269,4 @@ Who will be validators? Anyone will be able to do it, but most people will choos - 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. \ No newline at end of file +- 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 index 4cfa74934..0c60a71bd 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -7,7 +7,6 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- - Suppose the rollup chain looks like this: ![img](https://lh4.googleusercontent.com/kAZY9H73dqcHvboFDby9nrtbYZrbsHCYtE5X9NIZQsvcz58vV0WUWUq1xsYKzYWQSc1nPZ8W86LLX0lD3y-ctEaG2ISa2Wpz2pYxTzW09P1UvqSDuoqkHlGDYLLMTzLqX4rlP8Ca) @@ -66,10 +65,10 @@ The challenge protocol is designed so that the dispute can be resolved with a mi 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: @@ -131,8 +130,6 @@ 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 @@ -209,7 +206,6 @@ 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. @@ -272,7 +268,6 @@ 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, @@ -348,8 +343,6 @@ For these instruction descriptions, all pointers and offsets are represented as | 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 @@ -383,7 +376,6 @@ Floating point to integer truncation will saturate on overflow, instead of error 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. diff --git a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx index 7180f3709..0ca414de5 100644 --- a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx +++ b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx @@ -71,4 +71,4 @@ When the Arbitrum sequencer produces a data batch that it wants to post using th 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. -If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. \ No newline at end of file +If the Sequencer fails to collect enough signatures within a few minutes, it will abandon the attempt to use the Committee, and will "fall back to rollup" by posting the full data directly to the L1 chain, as it would do in a non-AnyTrust chain. The L2 software can understand both data posting formats (via DACert or via full data) and will handle each one correctly. diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index ad1c6c8be..57ebc7055 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -14,23 +14,78 @@ 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 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. -## Gas Price Floor +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/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 Gas +### 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.) -## Tips in L2 +### 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 +### 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. @@ -40,7 +95,43 @@ Gas estimation for Retryable submissions is possible via the [NodeInterface](/bu [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. \ No newline at end of file +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/10-l1-to-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index ff1fcb6da..d2efa4d1a 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -7,12 +7,11 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- -In the [Transaction Lifecycle](/how-arbitrum-works/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. +In the [Transaction Lifecycle](/how-arbitrum-works/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. - +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 @@ -82,7 +81,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket - ### Automatic Redemption 4. It is very important to note that the submission of a ticket on L1 is separable / asynchronous from its execution on L2, i.e., a successful L1 ticket creation does not guarantee a successful redemption. Once the ticket is successfully created, the two following conditions are checked: (1) if the user's L2 balance is greater than (or equal to) `maxFeePerGas * gasLimit` **and** (2) if the `maxFeePerGas` (provided by the user in the ticket submission process) is greater than (or equal to) the `l2Basefee`. If these conditions are both met, ticket's submission is followed by an attempt to execute it on L2 (i.e., an **auto-redeem** using the supplied gas, as if the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile had been called). Depending on how much gas the sender has provided in step 1, ticket's redemption can either (1) immediately succeed or (2) fail. We explain both situations here: @@ -123,7 +121,6 @@ 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. @@ -167,7 +164,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket - :::caution Avoid Losing Funds! If a ticket expires after 7 days without being redeemed or re-scheduled to a future date, any message and value (other than the escrowed `callvalue`) it carries could be lost without possibility of being recovered. @@ -244,4 +240,4 @@ modifier onlyFromMyL1Contract() override { 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)). \ No newline at end of file +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 index 7aad30cc7..c9c1897a8 100644 --- a/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx @@ -26,4 +26,4 @@ Unlike Retryables, which have an option to provide Ether for automatic L2 execut 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. \ No newline at end of file +\*\* 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/assertion-tree.mdx b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx index d8d6a3526..1669c1944 100644 --- a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx +++ b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx @@ -30,4 +30,4 @@ The only delay that users experience during a dispute is of their [L2 to L1 mess ### 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). \ No newline at end of file +For a more detailed breakdown / specification of the assertion tree protocol, see [Inside Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.mdx#arbitrum-rollup-protocol). From 101a7c2e57a1a0a0943168fbbb21525ea3a11318 Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 12 Dec 2024 15:30:29 -0600 Subject: [PATCH 26/35] resolving broken links --- .../01-quickstart-solidity-hardhat.mdx | 2 +- .../02-how-to-estimate-gas.mdx | 10 +- .../03-public-chains.mdx | 8 +- .../04-cross-chain-messaging.mdx | 4 +- .../01-comparison-overview.mdx | 6 +- .../02-block-numbers-and-time.mdx | 2 +- .../arbitrum-vs-ethereum/03-rpc-methods.mdx | 10 +- .../04-solidity-support.mdx | 2 +- .../precompiles/02-reference.mdx | 2 +- .../reference/08-mainnet-risks.mdx | 2 +- .../token-bridging/02-token-bridge-ether.mdx | 2 +- .../token-bridging/03-token-bridge-erc20.mdx | 4 +- .../02-how-to-bridge-tokens-standard.mdx | 2 +- .../01-a-gentle-introduction.mdx | 2 +- .../02-transaction-lifecycle.mdx | 26 ++--- .../how-arbitrum-works/03-sequencer.mdx | 4 +- .../04-geth-at-the-core.mdx | 12 +- .../06-optimistic-rollup.mdx | 2 +- .../07-interactive-fraud-proofs.mdx | 8 +- .../how-arbitrum-works/09-gas-fees.mdx | 107 +----------------- .../10-l1-to-l2-messaging.mdx | 4 +- .../11-l2-to-l1-messaging.mdx | 4 +- .../how-arbitrum-works/assertion-tree.mdx | 6 +- .../bold/gentle-introduction.mdx | 6 +- .../concepts/custom-gas-token-sdk.md | 2 +- .../how-tos/manage-fee-collectors.md | 4 +- .../how-tos/orbit-chain-finality.md | 6 +- .../orbit-sdk-deploying-token-bridge.md | 2 +- .../how-tos/use-a-custom-gas-token.mdx | 2 +- .../orbit-sdk-introduction.md | 12 +- .../monitoring-tools-and-considerations.mdx | 2 +- .../partials/_gentle-intro-partial.mdx | 4 +- .../arbos-releases/01-overview.mdx | 2 +- .../arbos-releases/arbos11.mdx | 2 +- .../01-get-started.mdx | 2 +- .../02-deploy-das.mdx | 4 +- .../04-configure-dac.mdx | 4 +- arbitrum-docs/stylus/concepts/how-it-works.md | 4 +- arbitrum-docs/welcome/get-started.mdx | 26 ++--- .../archive}/arbos/introduction.mdx | 0 40 files changed, 105 insertions(+), 210 deletions(-) rename {arbitrum-docs/how-arbitrum-works => website/archive}/arbos/introduction.mdx (100%) 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 984e56a4d..7b275eaf4 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..c54b86550 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 1b1389eb6..f08f33131 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 Ethereum. There ## 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 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/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..88220f9e0 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 at some later time. In Arbitrum, clients submit transactions by posting messages to the Ethereum chain, either [through the sequencer](/how-arbitrum-works/03-sequencer.mdx#happycommon-case-sequencer-is-live-and-well-behaved) or via the chain's [delayed inbox](/how-arbitrum-works/03-sequencer.mdx#unhappyuncommon-case-sequencer-isnt-doing-its-job). 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 5f3923793..9d2df5565 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..daf80d289 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 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/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..9596a59e9 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 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/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..bda6dde3d 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 know 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/how-arbitrum-works/01-a-gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx index 1c9153861..9cb237a09 100644 --- a/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx +++ b/arbitrum-docs/how-arbitrum-works/01-a-gentle-introduction.mdx @@ -11,7 +11,7 @@ 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/anytrust-protocol.mdx), which is used by the Arbitrum Nova chain. +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? diff --git a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx index 742653084..f5ecb72dd 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -29,7 +29,7 @@ We'll now go step-by-step over the phases an Arbitrum transaction goes through, 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 section will focus 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. +This section will focus on the Arbitrum Rollup protocol; see [Inside AnyTrust](/how-arbitrum-works/08-anytrust-protocol.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). @@ -47,8 +47,8 @@ Alternatively, a client can send a message to the Sequencer by signing and publi **See**: -- [Retryables](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) -- [The Sequencer](/how-arbitrum-works/sequencer.mdx) +- [Retryables](/how-arbitrum-works/10-l1-to-l2-messaging.mdx) +- [The Sequencer](/how-arbitrum-works/03-sequencer.mdx) - [Token Bridge](/build-decentralized-apps/token-bridging/01-overview.mdx) ### 2. Sequencer orders transaction (off-chain) @@ -61,9 +61,9 @@ Upon receiving a transaction, the Sequencer will: **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) +- [ArbOS](/how-arbitrum-works/04-geth-at-the-core#arbos.mdx) +- [Geth](/how-arbitrum-works/04-geth-at-the-core#geth.mdx) +- [L1 pricing](/how-arbitrum-works/09-gas-fees.mdx) / [L2 Gas](/how-arbitrum-works/09-gas-fees.mdx) #### ~ ~ ~ FINALITY CHECK: Trusted / Soft Confirmation ~ ~ ~ @@ -91,7 +91,7 @@ The Sequencer is forced to include messages from the delayed Inbox in the queued **See:** -- ["The Sequencer / Censorship Resistance."](/how-arbitrum-works/sequencer.mdx) +- ["The Sequencer / Censorship Resistance."](/how-arbitrum-works/03-sequencer.mdx) #### ~ ~ ~ FINALITY CHECK: Ethereum-Equivalent Finality! ~ ~ ~ @@ -110,9 +110,9 @@ A staked, active validator will then run the Arbitrum VM over the inputs in the **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) +- [ArbOS](/how-arbitrum-works/04-geth-at-the-core.mdx#arbos) +- [Geth](/how-arbitrum-works/04-geth-at-the-core.mdx#geth) +- [L1 pricing](/how-arbitrum-works/09-gas-fees.mdx) / [L2 Gas](/how-arbitrum-works/09-gas-fees.mdx) :::note @@ -122,7 +122,7 @@ RBlock assertions include claims about the state of the Outbox; if our transacti **See**: -- [The Outbox](/how-arbitrum-works/arbos/l2-l1-messaging.mdx) +- [The Outbox](/how-arbitrum-works/11-l2-to-l1-messaging.mdx) #### 4a. RBlock is valid / goes unchallenged @@ -136,8 +136,8 @@ A dispute consists of two staked validators dissecting their disagreement down t **See:** -- [Challenges](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx) -- [Wasm/WAVM](/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx) +- [Challenges](/how-arbitrum-works/07-interactive-fraud-proofs.mdx#challenge-manager) +- [Wasm/WAVM](/how-arbitrum-works/07-interactive-fraud-proofs.mdx#wasm-wavm) 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." diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 5bf5725c4..278bdf452 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -17,7 +17,7 @@ Clients interact with the Sequencer in exactly the same way they would interact ## 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](/how-arbitrum-works/arbos/transaction-lifecycle.mdx)”). 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. +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](/how-arbitrum-works/02-transaction-lifecycle.mdx)”). 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 @@ -56,7 +56,7 @@ Calls from L2 to L1 operate in a similar way, with a ticket-based system. An L2 These L2-to-L1 tickets have unlimited lifetime, until they’re successfully redeemed. No rent is required, as the tickets (actually a Merkle hash of the tickets) are recorded in Ethereum storage, which does not require rent. (The cost of allocating storage for the ticket Merkle roots is covered by L2 transaction fees.) -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/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. +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/10-l1-to-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. 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 index 5e1e9ac3e..a7974878c 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -21,7 +21,7 @@ Because the top and bottom layers rely heavily on code from geth, this structure 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/separating-execution-from-proving.mdx). +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 @@ -197,11 +197,11 @@ Represents a user deposit from L1 to L2. This increases the user's balance by th #### [`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. +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/arbos/l1-l2-messaging.mdx#retryable-tickets) for more info. +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} @@ -249,7 +249,7 @@ Nitro's Geth may be configured with the following [l2-specific chain parameters] #### `EnableArbos` -Introduces [ArbOS](/how-arbitrum-works/arbos/introduction.mdx), converting what would otherwise be a vanilla L1 chain into an L2 Arbitrum rollup. +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` @@ -277,7 +277,7 @@ To aid with [outbox proof construction][proof_link], the root hash and leaf coun #### Retryable Support -Retryables are mostly implemented in [ArbOS](/how-arbitrum-works/arbos/introduction.mdx#retryables). Some modifications were required in Geth to support them. +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. @@ -352,7 +352,7 @@ An [`L1IncomingMessage`][l1incomingmessage_link] represents an incoming sequence ### 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/arbos/l1-l2-messaging.mdx). +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 diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx index e7e110704..01a2598ec 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -239,7 +239,7 @@ A consequence of these rules is that once the first unresolved RBlock's deadline 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/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 diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index 0c60a71bd..0181e3bd8 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -1,5 +1,5 @@ --- -title: Challenges: Interactive Fraud Proofs +title: Challenges/:/ Interactive Fraud Proofs description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' author: pete-vielhaber sme: TucksonDev @@ -65,7 +65,7 @@ The challenge protocol is designed so that the dispute can be resolved with a mi 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'; +import ChallengeManagerDiagram from '../diagrams/_challenge-manager.mdx'; ## ChallengeManager @@ -211,7 +211,7 @@ which is limited by EIP-170 to about 24KB. 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). +which are documented in [`wavm-custom-opcodes`](#wavm-custom-opcodes-not-in-wasm). ### `block` and `loop` @@ -281,7 +281,7 @@ which are not part of WASM nor any WASM proposal. 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).) +These invariants are maintained by WASM validation and Arbitrator codegen. (See [One Step Proof Assumptions](#one-step-proof-assumptions).) ### Codegen internal diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index 57ebc7055..171f2c6f3 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -18,7 +18,7 @@ The L1 component is the product of the transaction's estimated contribution to i 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/l1-to-l2-messaging.mdx). +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 @@ -132,108 +132,3 @@ After allocating funds and paying what is owed, the L1 Pricer adjusts the L1 Gas 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/10-l1-to-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index d2efa4d1a..850c188fa 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -7,7 +7,7 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- -In the [Transaction Lifecycle](/how-arbitrum-works/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. +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). @@ -209,7 +209,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 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 index c9c1897a8..a8816a116 100644 --- a/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx @@ -7,7 +7,7 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou 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/arbos/l1-l2-messaging.mdx) (Retryables), "in reverse" though with a few differences. +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 @@ -24,6 +24,6 @@ An important feature in the design of the Outbox system is that calls to `confir 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) +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/assertion-tree.mdx b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx index 1669c1944..207b9d75e 100644 --- a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx +++ b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx @@ -16,7 +16,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 +26,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/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/launch-orbit-chain/concepts/custom-gas-token-sdk.md b/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md index 2f6cb58de..7d72603b7 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 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/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 amount of native tokens must be approved and allocated on 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/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..909db9377 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/03-sequencer.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#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. 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/orbit-sdk-introduction.md b/arbitrum-docs/launch-orbit-chain/orbit-sdk-introduction.md index 032fa5e21..005d87415 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](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. | +| 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), 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 1a34615f3..bf27b569b 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, by necessity, 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/data-availability-committees/01-get-started.mdx b/arbitrum-docs/run-arbitrum-node/data-availability-committees/01-get-started.mdx index ae6fa069e..84370391f 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 familiarized 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/stylus/concepts/how-it-works.md b/arbitrum-docs/stylus/concepts/how-it-works.md index a92a3dd2e..a6892502a 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/welcome/get-started.mdx b/arbitrum-docs/welcome/get-started.mdx index e38391356..45b384383 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/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/stylus-gentle-introduction) | 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/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 From 2ca62c76c8f346988f43a321b92d8f3c30c8ea67 Mon Sep 17 00:00:00 2001 From: Pete Date: Thu, 12 Dec 2024 15:51:38 -0600 Subject: [PATCH 27/35] Updated frontmatter to be more specific --- .../how-arbitrum-works/02-transaction-lifecycle.mdx | 4 ++-- arbitrum-docs/how-arbitrum-works/03-sequencer.mdx | 2 +- arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx | 4 ++-- .../05-separating-execution-from-proving.mdx | 4 ++-- arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx | 4 ++-- .../how-arbitrum-works/07-interactive-fraud-proofs.mdx | 4 ++-- arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx | 4 ++-- arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx | 4 ++-- arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx | 4 ++-- arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx | 4 ++-- arbitrum-docs/how-arbitrum-works/assertion-tree.mdx | 5 +++++ 11 files changed, 24 insertions(+), 19 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx index f5ecb72dd..62e2c350c 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -1,9 +1,9 @@ --- title: Sequencing, Followed by Deterministic Execution -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +description: 'Learn the fundamentals of the Arbitrum Transaction Lifecycle, sequencing, and deterministic execution.' author: pete-vielhaber sme: TucksonDev -user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +user_story: As a current or prospective Arbitrum user, I need to learn more about the transaction lifecycle. content_type: get-started --- diff --git a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx index 278bdf452..86bdcb31e 100644 --- a/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx +++ b/arbitrum-docs/how-arbitrum-works/03-sequencer.mdx @@ -3,7 +3,7 @@ title: The Sequencer and Censorship Resistance description: 'Learn the fundamentals of the Arbitrum Sequencer.' author: pete-vielhaber sme: TucksonDev -user_story: As a current or prospective Arbitrum user, I need to learn more about Nitros design. +user_story: As a current or prospective Arbitrum user, I need to learn more about the Sequencer. content_type: get-started --- 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 index a7974878c..bd0095922 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -1,9 +1,9 @@ --- title: Geth at the core -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +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 Nitros design. +user_story: As a current or prospective Arbitrum user, I need to learn more about Geth and ArbOS. content_type: get-started --- 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 index 80085f8c1..26819a1ca 100644 --- a/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx +++ b/arbitrum-docs/how-arbitrum-works/05-separating-execution-from-proving.mdx @@ -1,9 +1,9 @@ --- title: Separating Execution from Proving -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +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 Nitros design. +user_story: As a current or prospective Arbitrum user, I need to learn more about the Arbitrum Rollup protocol. content_type: get-started --- diff --git a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx index 01a2598ec..061558412 100644 --- a/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx +++ b/arbitrum-docs/how-arbitrum-works/06-optimistic-rollup.mdx @@ -1,9 +1,9 @@ --- title: Optimistic Rollup -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +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 Nitros design. +user_story: As a current or prospective Arbitrum user, I need to learn more about Arbitrum's Optimistic Rollup protocol. content_type: get-started --- diff --git a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx index 0181e3bd8..5e6cc4151 100644 --- a/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx +++ b/arbitrum-docs/how-arbitrum-works/07-interactive-fraud-proofs.mdx @@ -1,9 +1,9 @@ --- title: Challenges/:/ Interactive Fraud Proofs -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +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 Nitros design. +user_story: As a current or prospective Arbitrum user, I need to learn more about Interactive Fraud Proofs and challenges. content_type: get-started --- diff --git a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx index 0ca414de5..8a77e119a 100644 --- a/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx +++ b/arbitrum-docs/how-arbitrum-works/08-anytrust-protocol.mdx @@ -1,9 +1,9 @@ --- title: AnyTrust Protocol -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +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 Nitros design. +user_story: As a current or prospective Arbitrum user, I need to learn more about AnyTrust. content_type: get-started --- diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index 171f2c6f3..d822bdbc7 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -1,9 +1,9 @@ --- title: Gas and Fees -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +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 Nitros design. +user_story: As a current or prospective Arbitrum user, I need to learn more about gas/fee calculations on Arbitrum. content_type: get-started --- diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index 850c188fa..61acdb120 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -1,9 +1,9 @@ --- title: L1 to L2 messaging -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +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 Nitros design. +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 --- 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 index a8816a116..cafcd9f9c 100644 --- a/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/11-l2-to-l1-messaging.mdx @@ -1,9 +1,9 @@ --- title: L2 to L1 messaging -description: 'Learn the fundamentals of Arbitrum Transaction Lifecycle.' +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 Nitros design. +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 --- diff --git a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx index 207b9d75e..eb4dd0cc5 100644 --- a/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx +++ b/arbitrum-docs/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 From 1810eaa0a819bc761d08f041c8a2baea59e3193a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Thu, 12 Dec 2024 14:59:51 -0800 Subject: [PATCH 28/35] fix: add imports for mermaid diagram and address aliases --- arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index 61acdb120..26eb334ed 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -7,6 +7,10 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- +import { AddressAliasHelper } from '@site/src/components/AddressAliasHelper'; +import { MermaidWithHtml, Nodes, Node, Connection, NodeDescriptions, 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). From d27dac5e5094def98896bac3b39cfd6464e84e9f Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 13 Dec 2024 08:08:18 -0600 Subject: [PATCH 29/35] yarn format fixes --- .../how-arbitrum-works/10-l1-to-l2-messaging.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx index 26eb334ed..b440d9bce 100644 --- a/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx +++ b/arbitrum-docs/how-arbitrum-works/10-l1-to-l2-messaging.mdx @@ -8,8 +8,14 @@ content_type: get-started --- import { AddressAliasHelper } from '@site/src/components/AddressAliasHelper'; -import { MermaidWithHtml, Nodes, Node, Connection, NodeDescriptions, NodeDescription, } from '/src/components/MermaidWithHtml/MermaidWithHtml'; - +import { + MermaidWithHtml, + Nodes, + Node, + Connection, + NodeDescriptions, + 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. From b3a70744cef9cd70b3acbea53d8f2419d7a50c5c Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 13 Dec 2024 08:23:25 -0600 Subject: [PATCH 30/35] resolved vercel issues --- .../how-arbitrum-works/02-transaction-lifecycle.mdx | 8 ++++---- .../how-arbitrum-works/04-geth-at-the-core.mdx | 10 +++++----- .../launch-orbit-chain/orbit-sdk-introduction.md | 10 +++++----- 3 files changed, 14 insertions(+), 14 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx index 62e2c350c..63372d2bf 100644 --- a/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx +++ b/arbitrum-docs/how-arbitrum-works/02-transaction-lifecycle.mdx @@ -61,8 +61,8 @@ Upon receiving a transaction, the Sequencer will: **See**: -- [ArbOS](/how-arbitrum-works/04-geth-at-the-core#arbos.mdx) -- [Geth](/how-arbitrum-works/04-geth-at-the-core#geth.mdx) +- [ArbOS](/how-arbitrum-works/04-geth-at-the-core.mdx#arbos) +- [Geth](/how-arbitrum-works/04-geth-at-the-core.mdx#geth) - [L1 pricing](/how-arbitrum-works/09-gas-fees.mdx) / [L2 Gas](/how-arbitrum-works/09-gas-fees.mdx) #### ~ ~ ~ FINALITY CHECK: Trusted / Soft Confirmation ~ ~ ~ @@ -136,8 +136,8 @@ A dispute consists of two staked validators dissecting their disagreement down t **See:** -- [Challenges](/how-arbitrum-works/07-interactive-fraud-proofs.mdx#challenge-manager) -- [Wasm/WAVM](/how-arbitrum-works/07-interactive-fraud-proofs.mdx#wasm-wavm) +- [Challenges](/how-arbitrum-works/07-interactive-fraud-proofs.mdx#challengemanager) +- [Wasm/WAVM](/how-arbitrum-works/07-interactive-fraud-proofs.mdx#wasm-to-wavm) 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." 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 index bd0095922..b2a221528 100644 --- a/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx +++ b/arbitrum-docs/how-arbitrum-works/04-geth-at-the-core.mdx @@ -51,7 +51,7 @@ Below is [`ApplyTransaction`][applytransaction_link]'s callgraph, with additiona - [`StartTxHook`](#StartTxHook) - `core.transitionDbImpl` - if `IsArbitrum()` remove tip - - [`GasChargingHook`](#GasChargingHook) + - [`GasChargingHook`](/how-arbitrum-works/geth-at-the-core#gascharginghook) - `evm.Call` - `core.vm.EVMInterpreter.Run` - [`PushCaller`](#PushCaller) @@ -78,7 +78,7 @@ If the transaction is an `ArbitrumSubmitRetryableTx`, ArbOS creates a retryable The hook returns `true` for both of these transaction types, signifying that the state transition is complete. -#### [`GasChargingHook`][gascharginghook_link]{#GasChargingHook} +#### [`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. @@ -99,7 +99,7 @@ In Arbitrum, the BlockHash and Number operations return data that relies on unde #### [`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). +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} @@ -399,9 +399,9 @@ Based on this information, ArbOS maintains an L1 data fee, also tracked as part 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](geth#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]. +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](geth#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. +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. diff --git a/arbitrum-docs/launch-orbit-chain/orbit-sdk-introduction.md b/arbitrum-docs/launch-orbit-chain/orbit-sdk-introduction.md index 005d87415..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/08-anytrust-protocol), 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. | +| 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 From ed263dbf058d9fa9fe7837c7e423be2de3a16511 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 13 Dec 2024 08:26:00 -0600 Subject: [PATCH 31/35] added mermaid w/html helper --- arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index d822bdbc7..f900f2e56 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -7,6 +7,16 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- +import { AddressAliasHelper } from '@site/src/components/AddressAliasHelper'; +import { + MermaidWithHtml, + Nodes, + Node, + Connection, + NodeDescriptions, + NodeDescription, +} from '/src/components/MermaidWithHtml/MermaidWithHtml'; + 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: From 91434eb539e5dc0f50b7e77b94491a342a6ec7e2 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 13 Dec 2024 08:26:51 -0600 Subject: [PATCH 32/35] rolled back --- arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx index f900f2e56..d822bdbc7 100644 --- a/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx +++ b/arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx @@ -7,16 +7,6 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: get-started --- -import { AddressAliasHelper } from '@site/src/components/AddressAliasHelper'; -import { - MermaidWithHtml, - Nodes, - Node, - Connection, - NodeDescriptions, - NodeDescription, -} from '/src/components/MermaidWithHtml/MermaidWithHtml'; - 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: From 0cec2eb2eae6863ea25a9515d3cd04d9129d056d Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 13 Dec 2024 08:44:54 -0600 Subject: [PATCH 33/35] add'l vercel build issues --- arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx | 2 +- arbitrum-docs/welcome/get-started.mdx | 2 -- arbitrum-sdk | 2 +- stylus-by-example | 2 +- 4 files changed, 3 insertions(+), 5 deletions(-) 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/welcome/get-started.mdx b/arbitrum-docs/welcome/get-started.mdx index 3c9b6cfd8..ea510728d 100644 --- a/arbitrum-docs/welcome/get-started.mdx +++ b/arbitrum-docs/welcome/get-started.mdx @@ -14,7 +14,6 @@ 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/06-optimistic-rollup.mdx) | A **protocol** for scaling Ethereum smart contracts. | @@ -27,7 +26,6 @@ The Arbitrum suite includes the protocols, chains, services, and SDKs that power | [Arbitrum Orbit](https://orbit.arbitrum.io/) | Lets you run your own Rollup and AnyTrust chains. | | [Arbitrum Stylus](/stylus/stylus-gentle-introduction) | Lets you write EVM-compatible smart contracts in Rust and any other language that compiles to Wasm. | - ## Arbitrum for users **Users** interact with Arbitrum either through the Arbitrum bridge or by using dApps that have been deployed to an Arbitrum chain. diff --git a/arbitrum-sdk b/arbitrum-sdk index 31852e262..f5b3d04ba 160000 --- a/arbitrum-sdk +++ b/arbitrum-sdk @@ -1 +1 @@ -Subproject commit 31852e2620641bd842c66e19005964c0b823563e +Subproject commit f5b3d04baf62356032f5475057637d989da5b6c1 diff --git a/stylus-by-example b/stylus-by-example index 262ea1344..508777e63 160000 --- a/stylus-by-example +++ b/stylus-by-example @@ -1 +1 @@ -Subproject commit 262ea1344634b0c454c2e692cd87e7dc59d47a46 +Subproject commit 508777e63fb38b7d27426a8ae0f2ffacf1c184c9 From ef43d4972257f5c04fb6748a27d691513493057d Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 13 Dec 2024 08:47:42 -0600 Subject: [PATCH 34/35] fixing vercel build issue within welcome for stylus link --- arbitrum-docs/welcome/get-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arbitrum-docs/welcome/get-started.mdx b/arbitrum-docs/welcome/get-started.mdx index ea510728d..25a4860c8 100644 --- a/arbitrum-docs/welcome/get-started.mdx +++ b/arbitrum-docs/welcome/get-started.mdx @@ -24,7 +24,7 @@ The Arbitrum suite includes the protocols, chains, services, and SDKs that power | [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/stylus-gentle-introduction) | Lets you write EVM-compatible smart contracts in Rust and any other language that compiles to Wasm. | +| [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 From c379532fa12b5d82e38ef4b6369200b5e6058b97 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 13 Dec 2024 08:49:10 -0600 Subject: [PATCH 35/35] build issues --- arbitrum-docs/welcome/get-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arbitrum-docs/welcome/get-started.mdx b/arbitrum-docs/welcome/get-started.mdx index 25a4860c8..25fd1709b 100644 --- a/arbitrum-docs/welcome/get-started.mdx +++ b/arbitrum-docs/welcome/get-started.mdx @@ -24,7 +24,7 @@ The Arbitrum suite includes the protocols, chains, services, and SDKs that power | [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 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