ethereum-optimism · krofax · Jan 17, 2025 · Jan 16, 2025 · Jan 16, 2025 · Jan 16, 2025
@@ -16,7 +16,7 @@ However, Cannon is Optimism's default Fault Proof Virtual Machine (FPVM). Cannon
 *   Onchain `MIPS.sol`: EVM implementation to verify execution of a single MIPS instruction.
 *   Offchain `mipsevm`: Go implementation to produce a proof for any MIPS instruction to verify onchain.
 
-Note that Cannon is just one example of a FPVM that can be used to resolve disputes.
+Note that Cannon is just one example of an FPVM that can be used to resolve disputes.
 
 This documentation will go into detail about the subcomponents that make up the offchain Cannon implementation as a whole.
 Additionally, we will explore the differences between Cannon and the onchain `MIPS.sol`. For more information about the onchain
@@ -52,7 +52,7 @@ where the code that has been compiled into MIPS instructions is OP-Program.
 OP-Program is golang code that will be compiled into MIPS instructions and run within the Cannon FPVM. OP-Program, whether run as standalone
 golang code or in Cannon, fetches all necessary data used for deriving the state of the L2. It is built such that the 
 same inputs will produce not only the same outputs, but the same execution trace. This allows all participants in a fault dispute game to run
-OP-Program such that, given the same L2 output root state transition, can generate the same execution traces. This in turn generates the same
+OP-Program such that, given the same L2 output root state transition, they can generate the same execution traces. This in turn generates the same
 witness proof for the exact same MIPS instruction that will be run onchain.
 
 ## Overview of offchain Cannon components
@@ -155,7 +155,7 @@ is used to parse all the symbols stored in the ELF file. Understanding which ELF
 they are located is important for other functionality, such as understanding if the current `PC` is running within a specific function.
 
 Another step that occurs while loading the ELF file is patching the binary of any incompatible functions. This step is crucial, as a key design decision
-important**, as a key design decision in both the onchain and offchain `mipsevm` implementations is that neither implementation
+in both the onchain and offchain `mipsevm` implementations is that neither implementation
 has access to a kernel. This is primarily due to the limitations within the EVM itself, and since the offchain Cannon
 implementation must match functionality exactly with its onchain counterpart, kernel access is also not available within Cannon. This means that the VMs
 cannot replicate behavior that would otherwise be performed by a kernel 1:1, which primarily impacts system calls (syscalls).
@@ -169,9 +169,9 @@ within the ELF file, and effectively stubbing out the function by returning imme
 Once the MIPS binary is loaded into Cannon, we can then begin to run MIPS instructions one at a time.
 [`run.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/cmd/run.go) contains the top-level
 code responsible for stepping through MIPS instructions. Additionally, before each MIPS instruction, `run.go` will determine whether
-separate action(s) needs to be performed. The actions to be performed are configured by the user, and can include logging information,
+separate action(s) need(s) to be performed. The action(s) to be performed are configured by the user, and can include logging information,
 stopping at a certain instruction, taking a snapshot at a certain instruction, or signaling to the VM to generate the witness proof.
-Actions to be performed are instantiated and checked by [`matcher.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/cmd/matcher.go),
+The action(s) to be performed are instantiated and checked by [`matcher.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/cmd/matcher.go),
 which generates a match function that triggers when the configured regular expression is true.
 
 Within `run.go`, the `StepFn` is the wrapper that initiates the MIPS instruction to be run.

@@ -43,7 +43,7 @@ graph TD;
 `op-challenger` assesses each claim's validity, countering only those deemed invalid, following this logic:
 
 1.  If the trusted node agrees with the output, `op-challenger` takes no action. An honest challenger does nothing because there are no claims it disagrees with. It continues to monitor the game in case someone posts a counter-claim to the valid root claim, in which case the challenger will participate in the game to defend the proposal.
-2.  If the trusted node disagrees, `op-challenger` posts a counter-claim to challenge the proposed output. In contrast to the above, an honest challenger aims to delete any output roots that its trusted node disagrees with in order to claim the bond attached to it. The honest challenger assumes that their rollup node is synced to the canonical state and that the fault proof program is correct, so it is willing to put its money on the line to counter any faults.
+2.  If the trusted node disagrees, `op-challenger` posts a counter-claim to challenge the proposed output. In contrast to the above scenario, an honest challenger aims to delete any output roots that its trusted node disagrees with in order to claim the bond attached to it. The honest challenger assumes that their rollup node is synced to the canonical state and that the fault proof program is correct, so it is willing to put its money on the line to counter any faults.
 
 ## Fault dispute game responses
 

@@ -55,7 +55,7 @@ The `FaultDisputeGame` contracts store bonds within a `DelayedWETH` contract tha
 ### Cumulative security impact
 
 As with the original system, the cumulative effect of these security capabilities is that the `Guardian` role provides fast response capabilities while the `SystemOwner` can always step in to resolve all classes of bugs that could result in a loss of funds.
-The most significant change in security model with the introduction of Fault Proof Mainnet is that `SystemOwner` can take a more passive role as invalid proposals will generally be rejected by the Fault Proof System while the `Guardian` can act as a backstop only in case of a failure in the fault proof game.
+With the introduction of Fault Proof Mainnet, The most significant change in the security model is that `SystemOwner` can take a more passive role. Invalid proposals will generally be rejected by the Fault Proof System, while the `Guardian` can act as a backstop only in case of a failure in the fault proof game.
 
 ## Next steps
 

@@ -22,7 +22,7 @@ The `FaultDisputeGame.sol` interacts with `MIPS.sol` and then `MIPS.sol` calls i
 *   Pre-images contain data from both L1 and L2,  which includes information such as block headers, transactions, receipts, world state nodes, and more. Pre-images are used as the inputs to the derivation process used to calculate the true L2 state, and subsequently the true L2 state is used to resolve a dispute game.
 *   A Fault Dispute Game, at a high-level, will effectively determine what L2 state is currently agreed-upon, and move through L2 state until the first disagreed-upon state is found. How the Pre-images are determined and populated into the `PreimageOracle.sol` contract is out-of-scope for this reference document on the `MIPS.sol` contract, as that contract only consumes Pre-images that have already been populated by the off-chain Cannon implementation.
 
-The `MIPS.sol` contract is called by a running instance of a dispute game i.e. by a `FaultDisputeGame.sol` contract, and is only called once a dispute game reaches a leaf node in the state transition tree that is currently being disputed.
+The `MIPS.sol` contract is called by a running instance of a dispute game (i.e. by a `FaultDisputeGame.sol` contract), and is only called once a dispute game reaches a leaf node in the state transition tree that is currently being disputed.
 A leaf node represents a single MIPS instruction (in the case that we're using Cannon as the FPVM) that can then be run onchain. Given a Pre-image, which is the previously agreed-upon L2 state up until this instruction, and the instruction
 state to run in the `MIPS.sol` contract, the fault dispute game can determine the true post state (or Post-image). This true post state will then be used to determine the outcome of the fault dispute game by comparing the disputed post-state
 at the leaf node with the post-state proposed by the disputer.
@@ -69,7 +69,7 @@ The following information is stored in the `State` struct. See [doc reference](h
 ### State hash
 
 The state hash is the `bytes32` value returned to the active Fault Dispute Game upon the completion of a single MIPS instruction in the `MIPS.sol` contract.
-The hash is derived by taking the `keccak256` of the above packed VM execution `State` struct, and then replacing the first byte of the hash with a value that represents the status of the VM.
+The hash is derived by taking the `keccak256` of the above packed VM execution `State` struct, then replacing the first byte of the hash with a value that represents the status of the VM.
 This value is derived from the `exitCode` and `exited` values, and can be:
 
 *   Valid (0)
@@ -78,19 +78,19 @@ This value is derived from the `exitCode` and `exited` values, and can be:
 *   Unfinished (3)
 
 The reason for adding the VM status to the state hash is to communicate to the dispute game whether the VM determined the proposed output root was valid or not.
-This in turn prevents a user from disputing an output root during a dispute game, but provides the state hash from a cannon trace that actually proves the output root is valid.
+This in turn prevents a user from disputing an output root during a dispute game, while providng the state hash from a cannon trace that actually proves the output root is valid.
 
 ### Memory proofs
 
 Using a 32-bit ISA means that the total size of the address space (assuming no virtual address space) is `2^32 = 4GiB`. Additionally, the `MIPS.sol` contract is stateless, so it does not store the MIPS memory in contract storage. The primary reason for this is because having to load the entire memory into the `MIPS.sol` contract in order to execute a single instruction onchain is prohibitively expensive. Additionally, the entire memory would need to be loaded per fault proof game, requiring multiple instances of the `MIPS.sol` contract. Therefore, in order to optimize the amount of data that needs to be provided per onchain instruction execution while still maintaining integrity over the entire 32-bit address space, Optimism has converted the memory into a binary merkle tree.
 
-The binary merkle tree (or hash tree) used to store the memory of the MIPS VM has leaf values that are 32 bytes and has a fixed depth of 27 levels. This in turn allows the binary merkle tree to span the full 32-bit address space: `2^27 * 32 = 2^32` (See [memory proofs](https://github.com/ethereum-optimism/optimism/blob/546fb2c7a5796b7fe50b0b7edc7666d3bd281d6f/cannon/docs/README.md#memory-proofs) for more details). In order to ensure the integrity of the entire address space each time memory is read or written to, one or more memory proofs are provided by the FaultDisputeGame.sol contract each time a MIPS instruction is executed onchain in MIPS.sol. A memory proof consists of the current leaf value and 27 sibling nodes (28, 32-byte values in total), where the sibling nodes are the `keccak256` hash of its own child nodes. Using the leaf value, its 27 sibling nodes, and the memory address converted to its binary representation as a guide (0 or 1 tells the order to concatenate left and right values), we can calculate a merkle root. This merkle root should be exactly the same as the merkle root stored in the VM execution State struct.
+The binary merkle tree (i.e. hash tree) used to store the memory of the MIPS VM has leaf values that are 32 bytes and has a fixed depth of 27 levels. This in turn allows the binary merkle tree to span the full 32-bit address space: `2^27 * 32 = 2^32` (See [memory proofs](https://github.com/ethereum-optimism/optimism/blob/546fb2c7a5796b7fe50b0b7edc7666d3bd281d6f/cannon/docs/README.md#memory-proofs) for more details). In order to ensure the integrity of the entire address space each time memory is read or written to, one or more memory proofs are provided by the FaultDisputeGame.sol contract each time a MIPS instruction is executed onchain in MIPS.sol. A memory proof consists of the current leaf value and 27 sibling nodes (28, 32-byte values in total), where the sibling nodes are the `keccak256` hash of its own child nodes. Using the leaf value, its 27 sibling nodes, and the memory address converted to its binary representation as a guide (0 or 1 tells the order to concatenate left and right values), we can calculate a merkle root. This merkle root should be exactly the same as the merkle root stored in the VM execution State struct.
 
-Reading to memory and writing to memory work similarly, both involve calculating the merkle root. In the case of a memory write, `MIPS.sol` must take care to verify the provided proof for the memory location to write to is correct. Additionally, writing to memory will change the merkle root stored in the VM execution `State` struct.
+Reading to memory and writing to memory work similarly, both involve calculating the merkle root. In the case of a memory write, `MIPS.sol` must take care to verify that the provided proof for the memory location to write to is correct. Additionally, writing to memory will change the merkle root stored in the VM execution `State` struct.
 
 ### State calculation
 
-While the `MIPS.sol` contract may only execute a single instruction onchain, the off-chain Cannon implementation executes all prerequisite MIPS instructions for all state transitions in the disputed L2 state required to reach the disputed instruction that will be executed onchain. This ensures that the MIPS instruction executed onchain has the correct VM state and necessary Pre-images stored in the `PreimageOracle.sol`  contract to generate the true post-state that can be used to resolve the dispute game.
+While the MIPS.sol contract may only execute a single instruction onchain, the off-chain Cannon implementation executes all prerequisite MIPS instructions for all state transitions in the disputed L2 state. These transitions are required to reach the disputed instruction that will be executed onchain. This ensures that the MIPS instruction executed onchain has the correct VM state and necessary Pre-images stored in the `PreimageOracle.sol`  contract to generate the true post-state that can be used to resolve the dispute game.
 
 ## Functions
 

@@ -8,7 +8,7 @@ import { Callout } from 'nextra/components'
 
 # SendRawTransactionConditional explainer
 
-A sequencer rpc, `eth_sendRawTransactionConditional`, allowing callers to conditionally include a transaction based on a set of provided options.
+A sequencer RPC method, `eth_sendRawTransactionConditional`, allows callers to conditionally include a transaction based on a set of provided options.
 
 This feature is meant to unblock use cases that require atomic inclusion, otherwise possible on Ethereum through specialized block builders like Flashbots. Some examples:
 

@@ -11,9 +11,9 @@ import { Card, Cards } from 'nextra/components'
 The big idea that makes Optimism possible is the Optimistic Rollup. We'll go through a brief explainer of *how* Optimistic Rollups work at a high l...
 
 <Cards>
+  <Card title="Rollup protocol overview" href="/stack/rollup/overview" />
+
   <Card title="Derivation pipeline" href="/stack/rollup/derivation-pipeline" />
 
   <Card title="Sequencer outages" href="/stack/rollup/outages" />
-
-  <Card title="Rollup protocol overview" href="/stack/rollup/overview" />
 </Cards>
@@ -13,7 +13,7 @@ The derivation pipeline is a fundamental component of the OP Stack protocol, res
 The following are key functions of the derivation pipeline:
 
 *   **Batch Submission and Sequencing**: Transactions are collected and sequenced into batches by the sequencer. These batches are then submitted to Layer 1 (L1) for finality and inclusion in the blockchain.
-*   **Safe Head and Unsafe Blocks**: The derivation pipeline maintains two types of heads: the Safe Head and the Unsafe Head. The Safe Head represents the most recent confirmed state on L1, while Unsafe Blocks are those that have been sequenced but not yet confirmed on L1.
+*   **Safe Head and Unsafe Blocks**: The derivation pipeline maintains two types of heads: the Safe Head and the Unsafe Head. The Safe Head represents the most recent confirmed state on L1, while the Unsafe Head represents the highest unsafe L2 block that the rollup node knows about. Unsafe Blocks are those that have been sequenced but not yet confirmed on L1 (i.e. those from above the Safe Head up to and including the Unsafe Head).
 *   **Reorg and Recovery**: If the sequencing window (typically 12 hours) is exceeded without a valid batch being discovered on L1, the pipeline will revert all Unsafe Blocks from that period. The pipeline then progresses using a default block that is empty except for deposits, allowing the network to recover and continue processing new transactions.
 
 ## Sequencer window

@@ -23,7 +23,7 @@ Keep reading to learn more about these potential outages and how to handle them.
 ### Description
 
 Sequencer downtime outages occur when the Sequencer is unable to receive and/or process L2 transactions from users.
-Outages of this type may be caused by any number of different issues including bugs in client software, cloud outages, or other similar errors.
+Outages of this type may be caused by any number of different issues, including bugs in client software, cloud outages, or other similar errors.
 Exact causes of Sequencer downtime outages can be dependent on the specific infrastructure used to run the Sequencer for any given OP Stack chain.
 
 ### Impact