Merge pull request #708 from PaulRBerg/docs/enhancements-and-typos

cpengilly · web-flow · commit 0796b914c59e · 2024-06-09T13:37:50.000-07:00
docs: enhancements and typos
diff --git a/pages/chain/differences.mdx b/pages/chain/differences.mdx
@@ -52,7 +52,7 @@ In all other cases, the transaction sender address is set according to the same
 
 ### Transaction Fees
 
-Transactions OP Mainnet must pay for an [L1 data fee](/stack/transactions/fees#the-l1-data-fee) on top of the standard [execution gas fee](/stack/transactions/fees#execution-gas-fee) you would expect on Ethereum.
+Transactions on OP Mainnet must pay for an [L1 data fee](/stack/transactions/fees#the-l1-data-fee) on top of the standard [execution gas fee](/stack/transactions/fees#execution-gas-fee) you would expect on Ethereum.
 Refer to the guide on [OP Mainnet Transaction Fees](/stack/transactions/fees) for more information.
 
 ### EIP-1559 Parameters
diff --git a/pages/stack/design-principles.mdx b/pages/stack/design-principles.mdx
@@ -115,5 +115,4 @@ Extensibility is a key design principle that unlocks the superpower of collabora
 
 The OP Stack is a decentralized software stack that anyone can contribute to.
 If you're interested in contributing to the OP Stack, check out [the Contributing section on our Community pages](https://community.optimism.io).
-Of course, software that has impact for the Optimism Collective is eligible to receive [Retroactive Public Goods Funding](https://app.optimism.io/retropgf).
-Build for the OP Stack — get rewarded for writing great open source software. What's not to love?
+Of course, software that has impact for the Optimism Collective is eligible to receive [Retroactive Public Goods Funding](https://app.optimism.io/retropgf). Build for the OP Stack — get rewarded for writing great open source software. What's not to love?
diff --git a/pages/stack/differences.mdx b/pages/stack/differences.mdx
@@ -52,7 +52,7 @@ In all other cases, the transaction sender address is set according to the same
 
 ### Transaction Fees
 
-Transactions OP Stack chains must pay for an [L1 data fee](/stack/transactions/fees#the-l1-data-fee) on top of the standard [execution gas fee](/stack/transactions/fees#execution-gas-fee) you would expect on Ethereum.
+Transactions on OP Stack chains must pay for an [L1 data fee](/stack/transactions/fees#the-l1-data-fee) on top of the standard [execution gas fee](/stack/transactions/fees#execution-gas-fee) you would expect on Ethereum.
 Refer to the guide on [OP Stack Transaction Fees](/stack/transactions/fees) for more information.
 
 ### EIP-1559 Parameters
diff --git a/pages/stack/explainer.mdx b/pages/stack/explainer.mdx
diff --git a/pages/stack/protocol/outages.mdx b/pages/stack/protocol/outages.mdx
@@ -35,7 +35,7 @@ Users may observe that the network appears to be "stuck" at a particular block h
 ### Mitigation
 
 Users can always bypass the Sequencer by sending L2 transactions directly to the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/111f3f3a3a2881899662e53e0f1b2f845b188a38/packages/contracts-bedrock/src/L1/OptimismPortal.sol#L209) contract on L1.
-Refer to the [Bypassing the Sequencer](#bypassing-the-sequencer) section for more information about this functionality.
+Refer to the [Bypassing the Sequencer](#bypassing-the-sequencer) section below for more information about this functionality.
 
 ## Transaction Submission Outages
 
diff --git a/pages/stack/protocol/rollup/deposit-flow.mdx b/pages/stack/protocol/rollup/deposit-flow.mdx
@@ -23,8 +23,7 @@ Information is encapsulated in lower layer packets on the sending side and then
 
     *   `_target`, target address on L2.
     *   `_message`, the L2 transaction's calldata, formatted as per the [ABI](https://docs.soliditylang.org/en/v0.8.19/abi-spec.html) of the target account.
-    *   `_minGasLimit`, the minimum gas limit allowed for the transaction on L2. Note that this is a *minimum* and the actual amount provided on L2 may be higher (but never lower) than the specified gas limit.
-        Note that the actual amount provided on L2 will be higher, because the portal contract on L2 needs to do some processing before submitting the call to `_target`.
+    *   `_minGasLimit`, the minimum gas limit allowed for the transaction on L2. Note that this is a *minimum* and the actual amount provided on L2 may be higher (but never lower) than the specified gas limit. The actual amount provided on L2 is often higher because the portal contract on L2 performs some processing before submitting the call to `_target`.
 
 2.  The L1 cross domain messenger calls [its own `_send` function](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/L1/L1CrossDomainMessenger.sol#L42-L52).
     It uses these parameters:
@@ -52,15 +51,15 @@ Information is encapsulated in lower layer packets on the sending side and then
 
 2.  Next, `op-node` [converts](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/op-node/rollup/derive/deposits.go#L35-L51) those `TransactionDeposited` events into [deposit transactions](https://specs.optimism.io/protocol/deposits.html#user-deposited-transactions).
 
-3.  In most cases user deposit transactions call the [`relayMessage`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol#L291-L413) function of [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol).
+3.  In most cases, user deposit transactions call the [`relayMessage`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol#L291-L413) function of [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol).
 
 4.  `relayMessage` runs a few sanity checks and then, if everything is good, [calls the real target contract with the relayed calldata](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol#L394).
 
 ## Denial of service (DoS) prevention
 
 As with all other L1 transactions, the L1 costs of a deposit are borne by the transaction's originator.
 However, the L2 processing of the transaction is performed by the Optimism nodes.
-If there were no cost attached, an attacker could be able to submit a transaction that had high costs of run on L2, and that way perform a denial of service attack.
+If there were no cost attached, an attacker could submit a transaction that had high execution costs on L2, and that way perform a denial of service attack.
 
 To avoid this DoS vector, [`depositTransaction`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/L1/OptimismPortal.sol#L422-L483), and the functions that call it, require a gas limit parameter.
 [This gas limit is encoded into the \[\]`TransactionDeposited` event](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/L1/OptimismPortal.sol#L469-L477), and used as the gas limit for the user deposit transaction on L2.
@@ -74,7 +73,7 @@ Deposits transactions can fail due to several reasons:
 *   Not enough gas provided.
 *   The state on L2 does not allow the transaction to be successful.
 
-It is possible to replay a failed deposit, possibly with more gas,
+It is possible to replay a failed deposit, possibly with more gas.
 
 ### Replays in action
 
@@ -124,7 +123,7 @@ To see how replays work, you can use [this contract on OP Sepolia](https://sepol
 
 5.  The next step is to find the hash of the failed relay.
     The easiest way to do this is to look in [the internal transactions of the destination contract](https://sepolia-optimism.etherscan.io/address/0xEF60cF6C6D0C1c755be104843bb72CDa3D778630#internaltx), and select the latest one that appears as a failure.
-    It should be a call to L2CrossDomainMessenger at address `0x420...007`. This is the call you need to replay.
+    It should be a call to `L2CrossDomainMessenger` at address `0x420...007`. This is the call you need to replay.
 
     If the latest internal transaction is a success, it probably means your transaction hasn't relayed yet. Wait until it is, that may take a few minutes.
 
@@ -185,10 +184,9 @@ To see how replays work, you can use [this contract on OP Sepolia](https://sepol
 
 ## Debugging
 
-To debug deposit transactions you can ask the L2 cross domain messenger for the state of the transaction.
+To debug deposit transactions, you can ask the L2 cross domain messenger for the state of the transaction.
 
-1.  Look on Etherscan to see the `FailedRelayedMessage` event.
-    Set `MSG_HASH` to that value.
+1.  Look on Etherscan to see the `FailedRelayedMessage` event. Set `MSG_HASH` to that value.
 
 2.  To check if the message is listed as failed, run this:
 
diff --git a/pages/stack/protocol/rollup/overview.mdx b/pages/stack/protocol/rollup/overview.mdx
@@ -36,20 +36,20 @@ Optimism block production is primarily managed by a single party, called the "se
 *   Submitting user transactions to L1.
 
 In Bedrock, the sequencer does have a mempool, similar to L1 Ethereum, but the mempool is private to avoid opening opportunities for MEV.
-In OP Mainnet blocks are produced every two seconds, regardless of whether they are empty (no transactions), filled up to the block gas limit with transactions, or anything in between.
+In OP Mainnet, blocks are produced every two seconds, regardless of whether they are empty (no transactions), filled up to the block gas limit with transactions, or anything in between.
 
 Transactions get to the sequencer in two ways:
 
-1.  Transactions submitted on L1 (called *deposits*) are included in the chain in the appropriate L2 block.
+1.  Transactions submitted directly to the sequencer.
+    These transactions are a lot cheaper to submit, as they do not require the expense of a separate L1 transaction. However, they cannot be made censorship resistant since the sequencer is the only participant that knows about them.
+
+2.  Transactions submitted on L1 (called *deposits*) are included in the chain in the appropriate L2 block.
     Every L2 block is identified by the "epoch" (the L1 block to which it corresponds, which typically has happened a few minutes before the L2 block) and its serial number within that epoch.
     The first block of the epoch includes all the deposits that happened in the L1 block to which it corresponds.
-    If the sequencer attempts to ignore a legitimate L1 transaction it ends up with a state that is inconsistent with the verifiers, same as if the sequencer tried to fake the state by other means.
+    If the sequencer attempts to ignore a legitimate L1 transaction, it ends up with a state that is inconsistent with the verifiers, same as if the sequencer tried to fake the state by other means.
     This provides OP Mainnet with L1 Ethereum level censorship resistance.
     You can read more about this mechanism [in the protocol specifications](https://specs.optimism.io/protocol/derivation.html#deriving-the-transaction-list).
 
-2.  Transactions submitted directly to the sequencer.
-    These transactions are a lot cheaper to submit, as they do not require the expense of a separate L1 transaction. However, they cannot be made censorship resistant since the sequencer is the only participant that knows about them.
-
 For the moment, [The Optimism Foundation](https://www.optimism.io/) runs the only block producer on OP Mainnet. Refer to [Protocol specs](overview) section for more information about how we plan to decentralize the Sequencer role in the future.
 
 ## Block Execution
@@ -70,8 +70,8 @@ Optimism is designed so that users can send arbitrary messages between smart con
 This makes it possible to transfer ETH or tokens, including ERC20 tokens, between the two networks.
 The exact mechanism by which this communication occurs differs depending on the direction in which messages are being sent.
 
-OP Mainnet uses this functionality in the Standard bridge to allow users to deposit tokens from Ethereum to OP Mainnet and also allow withdrawals of the same from OP Mainnet back to Ethereum.
-See the [developer documentation and examples](/builders/app-developers/bridging/standard-bridge) on details on the inner workings of the Standard bridge.
+OP Mainnet uses this functionality in the Standard bridge to allow users to deposit tokens from Ethereum to OP Mainnet and also allow withdrawals of the same tokens from OP Mainnet back to Ethereum.
+See the [developer documentation and examples](/builders/app-developers/bridging/standard-bridge) for details on the inner workings of the Standard bridge.
 
 ### Moving from Ethereum to OP Mainnet
 
diff --git a/pages/stack/protocol/rollup/smart-contracts.mdx b/pages/stack/protocol/rollup/smart-contracts.mdx
@@ -8,8 +8,7 @@ import { Callout } from 'nextra/components'
 
 # Smart Contract Overview
 
-This guide provides an overview of smart contract functionality
-for the smart contract components. You can also find [contract addresses](/chain/addresses) on OP Mainnet.
+This guide provides an overview of the functionality of the smart contract components. You can also find [contract addresses](/chain/addresses) on OP Mainnet.
 
 ## L1 contracts
 
@@ -19,8 +18,8 @@ This contract enables a delay before a call is forwarded to a target contract,
 and during the delay period the call can be vetoed by the authorized vetoer.
 This contract does not support value transfers, only data is forwarded.
 Additionally, this contract cannot be used to forward calls with data beginning
-with the function selector of the queuedAt(bytes32) function. This is because
-of input validation checks which solidity performs at runtime on functions
+with the function selector of the `queuedAt(bytes32)` function. This is because
+of input validation checks performed by Solidity at runtime on functions
 which take an argument.
 
 ### [L1CrossDomainMessenger](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.3.0/packages/contracts-bedrock/src/L1/L1CrossDomainMessenger.sol)
@@ -63,7 +62,7 @@ Users are encouraged to use the `L1CrossDomainMessenger` for a higher-level inte
 
 ### [ProtocolVersions](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.3.0/packages/contracts-bedrock/src/L1/ProtocolVersions.sol)
 
-The `ProtocolVersions` contract is used to manage superchain protocol version information.
+The `ProtocolVersions` contract is used to manage Superchain protocol version information.
 
 ### [ResourceMetering](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.3.0/packages/contracts-bedrock/src/L1/ResourceMetering.sol)
 
@@ -72,7 +71,7 @@ updates automatically based on current demand.
 
 ### [SuperchainConfig](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.3.0/packages/contracts-bedrock/src/L1/SuperchainConfig.sol)
 
-The `SuperchainConfig` contract is used to manage configuration of global superchain values.
+The `SuperchainConfig` contract is used to manage configuration of global Superchain values.
 
 ### [SystemConfig](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.3.0/packages/contracts-bedrock/src/L1/SystemConfig.sol)
 
@@ -161,7 +160,7 @@ transaction processing and block production.
 
 ## Legacy Contracts
 
-Those are legacy contracts from the old version of the OP Stack.
+These are legacy contracts from the old version of the OP Stack.
 
 ### [AddressManager](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.3.0/packages/contracts-bedrock/src/legacy/AddressManager.sol)
 
diff --git a/pages/stack/protocol/rollup/withdrawal-flow.mdx b/pages/stack/protocol/rollup/withdrawal-flow.mdx
@@ -13,7 +13,7 @@ In Optimism terminology, a *withdrawal* is a transaction sent from L2 (OP Mainne
 Withdrawals require the user to submit three transactions:
 
 1.  **Withdrawal initiating transaction**, which the user submits on L2.
-2.  **Withdrawal proving transaction**, which the user submits on L1 to prove that the withdrawal is legitimate (based on a merkle patricia trie root that commits to the state of the `L2ToL1MessagePasser`'s storage on L2)
+2.  **Withdrawal proving transaction**, which the user submits on L1 to prove that the withdrawal is legitimate (based on a Merkle-Patricia trie root that commits to the state of the `L2ToL1MessagePasser`'s storage on L2)
 3.  **Withdrawal finalizing transaction**, which the user submits on L1 after the fault challenge period has passed, to actually run the transaction on L1.
 
 <Callout type="info">
@@ -22,7 +22,7 @@ Withdrawals require the user to submit three transactions:
 
 ## Withdrawal initiating transaction
 
-1.  On L2 somebody (either an externally owned account (EOA) directly or a contract acting on behalf of an EOA) calls the [`sendMessage`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol#L249-L289) function of [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol).
+1.  On L2, a user, either an externally owned account (EOA) directly or a contract acting on behalf of an EOA, calls the [`sendMessage`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol#L249-L289) function of the [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/62c7f3b05a70027b30054d4c8974f44000606fb7/packages/contracts-bedrock/contracts/universal/CrossDomainMessenger.sol) contract.
 
     This function accepts three parameters:
 
