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

inbox contract v2 #3

Closed
wants to merge 18 commits into from
Closed

inbox contract v2 #3

Changes from 14 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
ee2eceb
add inbox-contract.md
blockchaindevsh Jul 23, 2024
fa2dee8
add more details and migration process
blockchaindevsh Jul 24, 2024
cb4affe
update about resend
blockchaindevsh Jul 24, 2024
0ff37bf
update
blockchaindevsh Jul 28, 2024
fb51959
more update
blockchaindevsh Jul 29, 2024
79fa1a5
partial fix
blockchaindevsh Jul 30, 2024
ea9b6b0
optimize for `n`
blockchaindevsh Jul 30, 2024
ebddbec
add SystemConfig.initialize section
blockchaindevsh Jul 30, 2024
2f22e44
remove the term "replacement"
blockchaindevsh Jul 30, 2024
bc70be1
mod definition for canonical batch inbox
blockchaindevsh Jul 30, 2024
0f0609a
add a section about "Inbox Sender"
blockchaindevsh Jul 31, 2024
b7448c1
add section for L1Block
blockchaindevsh Jul 31, 2024
6296a62
fix typo
blockchaindevsh Jul 31, 2024
7248e23
update about upgrade process
blockchaindevsh Aug 2, 2024
eeee178
mod language for review
blockchaindevsh Aug 2, 2024
01a41b0
add a section for `L1InfoDeposit` function
blockchaindevsh Aug 3, 2024
f47c082
update upgrade section
blockchaindevsh Aug 3, 2024
601763d
fix for review
blockchaindevsh Aug 3, 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
189 changes: 189 additions & 0 deletions specs/experimental/inbox-contract.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
# Inbox Contract

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**
- [Inbox Contract](#inbox-contract)
blockchaindevsh marked this conversation as resolved.
Show resolved Hide resolved
- [Motivation](#motivation)
- [How It Works](#how-it-works)
- [Supporting Dynamic Updates to Inbox Address](#supporting-dynamic-updates-to-inbox-address)
- [SystemConfig](#systemconfig)
- [setBatchInbox](#setbatchinbox)
- [initialize](#initialize)
- [UpdateType](#updatetype)
- [L1Block](#l1block)
- [batchInbox](#batchinbox)
- [setL1BlockValuesEcotone](#setl1blockvaluesecotone)
- [How `op-node` knows the canonical batch inbox](#how-op-node-knows-the-canonical-batch-inbox)
- [How `op-batcher` knows canonical batch inbox](#how-op-batcher-knows-canonical-batch-inbox)
- [Upgrade](#upgrade)
- [Security Considerations](#security-considerations)
- [Inbox Sender](#inbox-sender)
- [Reference Implementation](#reference-implementation)

## Motivation

The batch inbox is currently an Externally Owned Account (EOA), which has both advantages and disadvantages:

Advantages:
- Low submission gas cost due to the absence of onchain execution.
- Verification logic is moved offchain to the derivation part, protected by a fault dispute game with a correct absolute prestate.

Disadvantage:
- Onchain verification is not possible.


This specification aims to allow the batch inbox to be a contract, enabling customized batch submission conditions such as:
- Requiring the batch transaction to be signed by a quorum of sequencers in a decentralized sequencing network; or
- Mandating that the batch transaction call a BLOB storage contract (e.g., EthStorage) with a long-term storage fee, which is then distributed to data nodes that prove BLOB storage over time.


## How It Works

The integration process consists of three primary components:
1. The [`BatchInboxAddress`](https://github.com/ethereum-optimism/optimism/blob/db107794c0b755bc38a8c62f11c49320c95c73db/op-chain-ops/genesis/config.go#L77) can now be set to either an Externally Owned Account (EOA) or a smart contract. When a contract is used, it assumes responsibility for verifying and enforcing batch submission conditions.
2. Modification of the `op-node` derivation process: The `op-node` will be updated to exclude failed batch transactions during the derivation process. This change ensures that only successfully executed batch transactions are processed and included in the derived state.
3. Modification of the op-batcher submission process: The op-batcher will be updated to [call `recordFailedTx`](https://github.com/blockchaindevsh/optimism/blob/02e3b7248f1b590a2adf1f81488829760fa2ba03/op-batcher/batcher/driver.go#L537) for failed batch transactions. This modification ensures that the data contained in failed transactions will be resubmitted automatically.
1. Most failures will be detected during the [`EstimateGas`](https://github.com/ethereum-optimism/optimism/blob/8f516faf42da416c02355f9981add3137a3db190/op-service/txmgr/txmgr.go#L266) call. However, under certain race conditions, failures may occur after the transaction has been included in a block.

These modifications aim to enhance the security and efficiency of the batch submission and processing pipeline, allowing for more flexible and customizable conditions while maintaining the integrity of the derived state.


## Supporting Dynamic Updates to Inbox Address

### SystemConfig

The `SystemConfig` is the source of truth for the address of inbox. It stores information about the inbox address and passes the information to L2 as well.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should describe how initialize works for the address (whether the current behavior is the same or not?).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a section for initialize: ebddbec



#### setBatchInbox

A new function `setBatchInbox` is introduced to the `SystemConfig` contract, enabling dynamic updates to the inbox:

```solidity
/// @notice Updates the batch inbox address. Can only be called by the owner.
/// @param _batchInbox New batch inbox address.
function setBatchInbox(address _batchInbox) external onlyOwner {
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if _batchInbox is set to 0?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The 0 address will be used as inbox, which is also EOA.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe if address is 0, then op-node will be Rollup config's inbox to derive. Please double check.

Copy link
Collaborator Author

@blockchaindevsh blockchaindevsh Jul 30, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Currently ProcessSystemConfigUpdateLogEvent doesn't support dynamic update for inbox, it only supports dynamic update for batcher address. It will be modified to handle inbox change.

_setBatchInbox(_batchInbox);
}

/// @notice Updates the batch inbox address.
/// @param _batchInbox New batch inbox address.
function _setBatchInbox(address _batchInbox) internal {
Storage.setAddress(BATCH_INBOX_SLOT, _batchInbox);

bytes memory data = abi.encode(_batchInbox);
emit ConfigUpdate(VERSION, UpdateType.BATCH_INBOX, data);
}

```


#### initialize

The `SystemConfig` now emits an event when the inbox is initialized, while retaining its existing support for inbox configuration during initialization.

```solidity
function initialize(
address _owner,
uint32 _basefeeScalar,
uint32 _blobbasefeeScalar,
bytes32 _batcherHash,
uint64 _gasLimit,
address _unsafeBlockSigner,
ResourceMetering.ResourceConfig memory _config,
address _batchInbox,
SystemConfig.Addresses memory _addresses
)
public
initializer
{
...
// Storage.setAddress(BATCH_INBOX_SLOT, _batchInbox);
// initialize inbox by `_setBatchInbox` so that an event is emitted.
_setBatchInbox(_batchInbox);
...
}
```

#### UpdateType

A new enum value `BATCH_INBOX` is added to the `UpdateType` enumeration.

```solidity
enum UpdateType {
BATCHER,
GAS_CONFIG,
GAS_LIMIT,
UNSAFE_BLOCK_SIGNER,
BATCH_INBOX
}
```

### L1Block
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest following the description of custom gas token:

L1Block
The L1Block contract is upgraded with a permissioned function setGasPayingToken that is used to set information about the gas paying token. The DEPOSITOR_ACCOUNT MUST be the only account that can call the setter function. This setter is differentiated from the setL1BlockValues functions because the gas paying token is not meant to be dynamic config whereas the arguments to setL1BlockValues are generally dynamic in nature.

Any L2 contract that wants to learn the address of the gas paying token can call the getter on the L1Block contract.


The `L1Block` stores Layer 1 (L1) related information on Layer 2 (L2). It is extended to also store the inbox address.
blockchaindevsh marked this conversation as resolved.
Show resolved Hide resolved

#### batchInbox

A new field `batchInbox` is added to the `L1Block`:

```solidity
/// @notice The canonical batch inbox.
bytes32 public batchInbox;
```

#### setL1BlockValuesEcotone

This function stores Layer 1 (L1) block values for Layer 2 (L2) since the Ecotone upgrade of the OP Stack. It is enhanced to also store the inbox address.

```solidity
function setL1BlockValuesEcotone() external {
...
sstore(batchInbox.slot, calldataload(164)) // bytes32
}

```

### How `op-node` knows the canonical batch inbox

We define that the canonical batch inbox at a specific L2 block is the batch inbox of `SystemConfig` of the origin of the L2 block.

Under normal conditions, `op-node` knows the canonical batch inbox through the derivation pipeline:
1. The `L1Traversal` component first identifies the L1 `SystemConfig` changes while traversing the L1 block, via [`UpdateSystemConfigWithL1Receipts`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_traversal.go#L78).
1. The [`ProcessSystemConfigUpdateLogEvent`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/system_config.go#L59) function will be modified to parse the newly added inbox change.
2. The `L1Retrieval` component then fetches the canonical batch inbox from the `L1Traversal` componenet and [pass](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_retrieval.go#L57) it to the `DataSourceFactory` component, via `OpenData` function, similar to how [`SystemConfig.BatcherAddr`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-service/eth/types.go#L382) is handled.
3. The `FetchingAttributesBuilder` component is updated to incorporate the canonical batch inbox into the `DepositTx`, via [`L1InfoDeposit`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/l1_block_info.go#L263). This modified `DepositTx` is subsequently used to obtain the `SystemConfig` during L2 chain reorganization.

During L2 reorganization, `op-node` knows the canonical batch inbox using the `SystemConfig` parameter of [`ResettableStage.Reset(context.Context, eth.L1BlockRef, eth.SystemConfig)`](https://github.com/ethereum-optimism/optimism/blob/71928829ca7ece48152159daa1d231eac2df03b3/op-node/rollup/derive/pipeline.go#L38) function, where `SystemConfig` is derived from the `DepositTx` of the corresponding L2 block.

### How `op-batcher` knows canonical batch inbox

Immediately before submitting a new batch, `op-batcher` fetches the current inbox address from L1 and submits to that address. After the transaction is successfully included in L1 at block `N`, `op-batcher` verifies that the inbox address hasn't changed at block `N`. If the address has changed, it resubmits the batch to the new address.

## Upgrade
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would recommend to follow https://github.com/ethstorage/specs/blob/7248e23a6c93053a5cae5906c8521f30b55165c0/specs/experimental/custom-gas-token.md#upgrade for a better description of upgrade.


To use this feature, existing OP Stack instances must complete two steps:
1. Upgrade the `SystemConfig` and set an inbox contract on L1.
2. Upgrade the `L1Block` on L2.

Note that according to the [Optimism Style Guide](https://github.com/ethereum-optimism/optimism/blob/9d31040ecf8590423adf267ad24b03bc1bf7273b/packages/contracts-bedrock/STYLE_GUIDE.md), The process for upgrading the implementation is as follows:
1. Upgrade the implementation to the `StorageSetter` contract.
2. Use that to set the initialized slot (typically slot 0) to zero.
3. Upgrade the implementation to the desired new implementation and initialize it.

For a practical example of this process, refer to [this](https://github.com/ethereum-optimism/superchain-ops/blob/55e9520e27c7e916d8992ce351c6d5cfa8a511d8/tasks/eth/009-fp-upgrade/EXEC.md) execution document in the Optimism Superchain Operations repository.

## Security Considerations

### Inbox Sender

The inbox contract is a special contract that, if invoked by the batcher, all of its calldata / blob will be used as L2 derivation data, unless the transaction fails. In order to invoke and modify the state of the inbox contract, it is recommended to use a non-batcher sender.


## Reference Implementation

1. [example inbox contract for EthStorage](https://github.com/blockchaindevsh/es-op-batchinbox/blob/main/src/BatchInbox.sol)
2. [op-node & op-batcher changes](https://github.com/blockchaindevsh/optimism/compare/5137f3b74c6ebcac4f0f5a118b0f4909df03aec6...02e3b7248f1b590a2adf1f81488829760fa2ba03)

TODO: implement `Supporting Dynamic Updates to Inbox Address` mentioned above.