content changes, frontmatter additions

arbitrum-docs/how-arbitrum-works/03-sequencer.mdx

@@ -15,27 +15,27 @@ 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.
 
 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
+### 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.
 

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.
 
-<!-- 
-	We should add one more paragraph here explaining that the rest of the section in this page go into the technical details of both ArbOS and geth. That way the average non-deep-technical reader is aware that the next sections might not be relevant for them.
-	from arbos/introduction -->
+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

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.

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
 ---
 
-<!-- from inside-arbitrum-nitro -->
-<!-- VALIDATION -->
-
 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.

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'; -->
+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:
 
-<!--         <ChallengeManagerDiagram />        -->
+<ChallengeManagerDiagram />
 
 ### Block challenge
 

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.

arbitrum-docs/how-arbitrum-works/09-gas-fees.mdx

@@ -42,7 +42,7 @@ Gas estimation for Retryable submissions is possible via the [NodeInterface](/bu
 
 
 
-<!-- REMOVE and incorporate all below to the above sections where applicable -->
+<!-- REMOVE and incorporate all below to the above sections where applicable
 
 ### The Speed Limit
 
@@ -88,9 +88,7 @@ The price per estimated byte is set by a dynamic algorithm that compares the tot
 
 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.
 
-<!-- -->
 
-<!-- from l1-gas-pricing -->
 
 ## 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. -->

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
 ---
 
-<!-- from sequencer needs reworked as an intro -->
-### 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
 
-<!-- vercel having issues
 <MermaidWithHtml>
   <Nodes title="Ticket Submission">
     <Node id="1">🧍</Node>
@@ -86,7 +82,6 @@ Here we walk through the different stages of the lifecycle of a retryable ticket
   </NodeDescriptions>
 </MermaidWithHtml>
 
--->
 
 ### 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).
 
-<!-- vercel having issues
 <MermaidWithHtml>
   <Nodes title="Automatic Redemption of the Ticket">
     <Node id="1">Auto-redeem succeeds?</Node>
@@ -128,7 +122,7 @@ Here we walk through the different stages of the lifecycle of a retryable ticket
     </NodeDescription>
   </NodeDescriptions>
 </MermaidWithHtml>
--->
+
 
 ### 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
 
-<!-- vercel having issues
 <MermaidWithHtml>
   <Nodes title="Manual Redemption of the Ticket">
     <Node id="1">Ticket manually cancelled or not redeemed in 7 days?</Node>
@@ -173,7 +166,7 @@ Here we walk through the different stages of the lifecycle of a retryable ticket
     </NodeDescription>
   </NodeDescriptions>
 </MermaidWithHtml>
--->
+
 
 :::caution Avoid Losing Funds!
 
@@ -232,7 +225,7 @@ L2_Alias = L1_Contract_Address + 0x1111000000000000000000000000000000001111
 
 :::tip Try it out
 
-<!--         <AddressAliasHelper />          -->
+<AddressAliasHelper />
 
 :::
 
@@ -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)).