Skip to content

Commit

Permalink
Non prescriptive terms for standard config introduced (#98)
Browse files Browse the repository at this point in the history 
* Add initial configurability.

* docs: Added more config properties based on docs.

* Update specs/glossary.md

Co-authored-by: protolambda <[email protected]>

* docs: toc for batch submission frequency

* Update specs/protocol/configurability.md

Co-authored-by: protolambda <[email protected]>

* Update specs/glossary.md

Co-authored-by: Ben Jones <[email protected]>

* Update specs/protocol/configurability.md

Co-authored-by: Ben Jones <[email protected]>

* fix: Bens comments addressed. Admin column added.

* docs: adding administers to the specs doc for standard config.

* Update specs/glossary.md

Co-authored-by: Matt Solomon <[email protected]>

* fix: removed L1 smart contracts as a configurable variable (versioning has to be used for these.). Fee vault not referenced individually, as that's a predeploy.

* Update specs/protocol/configurability.md

Co-authored-by: Ben Jones <[email protected]>

* Update specs/protocol/configurability.md

Co-authored-by: Ben Jones <[email protected]>

* Update specs/protocol/configurability.md

Co-authored-by: Ben Jones <[email protected]>

* Update specs/protocol/configurability.md

Co-authored-by: Ben Jones <[email protected]>

* Update specs/protocol/configurability.md

Co-authored-by: Ben Jones <[email protected]>

* docs: batch submitter address is administrator for batch submission frequency.

* Update specs/protocol/configurability.md

Co-authored-by: Ben Jones <[email protected]>

* docs: batcher is also admin of compression ratio.

* docs: Data Availability Type added as a policy param.

---------

Co-authored-by: Kevin Kz <[email protected]>
Co-authored-by: protolambda <[email protected]>
Co-authored-by: Ben Jones <[email protected]>
Co-authored-by: Matt Solomon <[email protected]>
  • Loading branch information
@blmalone @protolambda
@ben-chain @mds1
5 people authored Mar 26, 2024
1 parent c2c5a8b commit 559b35a
Show file tree
Hide file tree
Showing 3 changed files with 93 additions and 0 deletions.
1 change: 1 addition & 0 deletions specs/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
- [Superchain Configuration](./protocol/superchain-configuration.md)
- [Superchain Upgrades](./protocol/superchain-upgrades.md)
- [System Config](./protocol/system_config.md)
- [Configurability](./protocol/configurability.md)
- [Experimental]()
- [Fault Proof](./experimental/fault-proof/index.md)
- [Cannon Fault Proof VM](./experimental/fault-proof/cannon-fault-proof-vm.md)
Expand Down
17 changes: 17 additions & 0 deletions specs/glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@
- [Channel Frame](#channel-frame)
- [Batcher](#batcher)
- [Batcher Transaction](#batcher-transaction)
- [Batch submission frequency](#batch-submission-frequency)
- [Channel Timeout](#channel-timeout)
- [L2 Output Root Proposals](#l2-output-root-proposals)
- [Proposer](#proposer)
Expand Down Expand Up @@ -483,6 +484,22 @@ When submitted to Ethereum calldata, the batcher transaction's receiver must be
transaction must also be signed by a recognized batch submitter account. The recognized batch submitter account
is stored in the [System Configuration][system-config].

## Batch submission frequency

Within the [sequencing-window] constraints the batcher is permitted by the protocol to submit L2 blocks for
data-availability at any time. The batcher software allows for dynamic policy configuration by its operator.
The rollup enforces safety guarantees and liveness through the sequencing window, if the batcher does not submit
data within this allotted time.

By submitting new L2 data in smaller more frequent steps, there is less delay in confirmation of the L2 block
inputs. This allows verifiers to ensure safety of L2 blocks sooner. This also reduces the time to finality of
the data on L1, and thus the time to L2 input-finality.

By submitting new L2 data in larger less frequent steps, there is more time to aggregate more L2 data, and
thus reduce fixed overhead of the batch-submission work. This can reduce batch-submission costs, especially
for lower throughput chains that do not fill data-transactions (typically 128 KB of calldata, or 800 KB
of blobdata) as quickly.

## Channel Timeout

[channel-timeout]: glossary.md#channel-timeout
Expand Down
75 changes: 75 additions & 0 deletions specs/protocol/configurability.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# OP Stack Configurability

<!-- 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**

- [Consensus Parameters](#consensus-parameters)
- [Policy Parameters](#policy-parameters)
- [Admin Roles](#admin-roles)
- [Service Roles](#service-roles)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

When deploying the OP Stack software to a production environment,
certain parameters about the protocol can be configured. These
configurations can include a variety of parameters which affect the
resulting properties of the blockspace in question.

There are four categories of OP Stack configuration options:

- **Consensus Parameters**: Parameters and properties of the chain that may
be set at genesis and fixed for the lifetime of the chain, or may be
changeable through a privileged account or protocol upgrade.
- **Policy Parameters**: Parameters of the chain that might be changed without
breaking consensus. Consensus is enforced by the protocol, while policy parameters
may be changeable within constraints imposed by consensus.
- **Admin Roles**: These roles can upgrade contracts, change role owners,
or update protocol parameters. These are typically cold/multisig wallets not
used directly in day to day operations.
- **Service Roles**: These roles are used to manage the day-to-day
operations of the chain, and therefore are often hot wallets.

## Consensus Parameters

| Config Property | Description | Administrator |
|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|
| [Batch Inbox address](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/SystemConfig.sol#L176) | L1 address where calldata/blobs are posted (see [Batcher Transaction](../glossary.md#batcher-transaction)). | [L1 Proxy Admin](#admin-roles) |
| [Chain ID](https://github.com/ethereum-optimism/superchain-registry/blob/main/superchain/configs/chainids.json) | Unique ID of Chain used for TX signature validation. | |
| [Challenge Period](https://github.com/ethereum-optimism/superchain-registry/pull/44) | Length of time for which an output root can be removed, and for which it is not considered finalized. | [L1 Proxy Admin](#admin-roles) |
| [Fee margin](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/SystemConfig.sol#L281-L283) | Markup on transactions compared to the raw L1 data cost. | [System Config Owner](#admin-roles) |
| Genesis state | Initial state at chain genesis, including code and storage of predeploys (all L2 smart contracts). See [Predeploy](../glossary.md#l2-genesis-block). | |
| [L2 block time](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/L2OutputOracle.sol#L105) | Frequency with which blocks are produced as a result of derivation. | [L1 Proxy Admin](#admin-roles) |
| [Resource config](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/SystemConfig.sol#L338-L340) | Config for the EIP-1559 based curve used for the deposit gas market. | [System Config Owner](#admin-roles) |
| Sequencing window | Maximum allowed batch submission gap, after which L1 fallback is triggered in derivation. | |
| [Start block](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/SystemConfig.sol#L184) | Block at which the system config was initialized the first time. | [L1 Proxy Admin](#admin-roles) |
| Superchain target | Choice of cross-L2 configuration. May be omitted in isolated OP Stack deployments. Includes SuperchainConfig and ProtocolVersions contract addresses. | |

## Policy Parameters

| Config Property | Description | Administrator |
|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|
| Data Availability Type | Batcher can currently be configured to use blobs or calldata (See [Data Availability Provider](../glossary.md#data-availability-provider)). | [Batch submitter address](#service-roles) |
| Batch submission frequency | Frequency with which batches are submitted to L1 (see [Batcher Transaction](../glossary.md#batcher-transaction)). | [Batch submitter address](#service-roles) |
| Compression ratio | How much compression the batch submitter applies to batches before submission (see [Channel](../glossary.md#channel)). | [Batch submitter address](#service-roles) |
| [Output frequency](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/L2OutputOracle.sol#L104) | Frequency with which output roots are submitted to L1. | [L1 Proxy Admin](#admin-roles) |

## Admin Roles

| Config Property | Description | Administrator | Administers |
|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|-------------------------------------|
| [L1 Proxy Admin](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/universal/ProxyAdmin.sol#L30) | Account authorized to upgrade L1 contracts. | [L1 Proxy Admin Owner](#admin-roles) | [Batch Inbox Address](#consensus-parameters), [Start block](#consensus-parameters), [Proposer address](#service-roles), [Challenger address](#service-roles), [Guardian address](#service-roles), [Challenge Period](#consensus-parameters), [Output frequency](#policy-parameters), [L2 block time](#consensus-parameters), [L1 smart contracts](#consensus-parameters)
| L1 ProxyAdmin owner | Account authorized to update the L1 Proxy Admin. | | [L1 Proxy Admin](#admin-roles)
| [L2 Proxy Admin](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/universal/ProxyAdmin.sol#L30) | Account authorized to upgrade L2 contracts. | [L2 Proxy Admin Owner](#admin-roles) | [Predeploys](./predeploys.md#overview)
| L2 ProxyAdmin owner | Account authorized to update the L2 Proxy Admin. | | [L2 Proxy Admin](#admin-roles)
| [System Config Owner](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/SystemConfig.sol#L14C26-L14C44) | Account authorized to change values in the SystemConfig contract. All configuration is stored on L1 and picked up by L2 as part of the [derviation](./derivation.md) of the L2 chain. | | [Batch submitter address](#service-roles), [Sequencer P2P / Unsafe head signer](#service-roles), [Fee Margin](#consensus-parameters), [Gas limit](#consensus-parameters), [Resource config](#consensus-parameters), [System Config Owner](#admin-roles)

## Service Roles

| Config Property | Description | Administrator |
|---------------------------------------|------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|
| [Batch submitter address](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/SystemConfig.sol#L265) | Account which authenticates new batches submitted to L1 Ethereum. | [System Config Owner](#admin-roles) |
| [Challenger address](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/L2OutputOracle.sol#L109) | Account which can delete output roots before challenge period has elapsed. | [L1 Proxy Admin](#admin-roles) |
| [Guardian address](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/SuperchainConfig.sol#L50) | Account authorized to pause L1 withdrawals from contracts. | [L1 Proxy Admin](#admin-roles) |
| [Proposer address](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/L2OutputOracle.sol#L108) | Account which can propose output roots to L1. | [L1 Proxy Admin](#admin-roles) |
| [Sequencer P2P / Unsafe head signer](https://github.com/ethereum-optimism/optimism/blob/c927ed9e8af501fd330349607a2b09a876a9a1fb/packages/contracts-bedrock/src/L1/SystemConfig.sol#L250) | Account which authenticates the unsafe/pre-submitted blocks for a chain at the P2P layer. | [System Config Owner](#admin-roles) |

0 comments on commit 559b35a

Please sign in to comment.