Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: enhancements and typos #708

Merged
merged 3 commits into from
Jun 9, 2024
Merged

docs: enhancements and typos #708

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
54aea3e
docs: enhancements and typos
PaulRBerg May 21, 2024
c802029
Update pages/stack/protocol/rollup/deposit-flow.mdx
PaulRBerg May 22, 2024
94f789a
linter fix
cpengilly Jun 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion pages/chain/differences.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
PaulRBerg marked this conversation as resolved.
Show resolved Hide resolved
Refer to the guide on [OP Mainnet Transaction Fees](/stack/transactions/fees) for more information.

### EIP-1559 Parameters
Expand Down
3 changes: 1 addition & 2 deletions pages/stack/design-principles.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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?
2 changes: 1 addition & 1 deletion pages/stack/differences.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
PaulRBerg marked this conversation as resolved.
Show resolved Hide resolved
Refer to the guide on [OP Stack Transaction Fees](/stack/transactions/fees) for more information.

### EIP-1559 Parameters
Expand Down
62 changes: 33 additions & 29 deletions pages/stack/explainer.mdx
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pages/stack/protocol/outages.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
16 changes: 7 additions & 9 deletions pages/stack/protocol/rollup/deposit-flow.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 will be higher because the portal contract on L2 needs to do some processing before submitting the call to `_target`.
PaulRBerg marked this conversation as resolved.
Show resolved Hide resolved

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:
Expand Down Expand Up @@ -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.
PaulRBerg marked this conversation as resolved.
Show resolved Hide resolved

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.
Expand All @@ -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

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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.
PaulRBerg marked this conversation as resolved.
Show resolved Hide resolved

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:

Expand Down
16 changes: 8 additions & 8 deletions pages/stack/protocol/rollup/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
PaulRBerg marked this conversation as resolved.
Show resolved Hide resolved

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.
PaulRBerg marked this conversation as resolved.
Show resolved Hide resolved
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
Expand All @@ -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

Expand Down
13 changes: 6 additions & 7 deletions pages/stack/protocol/rollup/smart-contracts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand Down Expand Up @@ -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)

Expand All @@ -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)

Expand Down Expand Up @@ -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)

Expand Down
4 changes: 2 additions & 2 deletions pages/stack/protocol/rollup/withdrawal-flow.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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">
Expand All @@ -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:

Expand Down