From 559b35a7ed2f5ac7726ea5cdd1e54068cac163a0 Mon Sep 17 00:00:00 2001 From: Blaine Malone Date: Tue, 26 Mar 2024 14:39:30 -0400 Subject: [PATCH] Non prescriptive terms for standard config introduced (#98) * Add initial configurability. * docs: Added more config properties based on docs. * Update specs/glossary.md Co-authored-by: protolambda * docs: toc for batch submission frequency * Update specs/protocol/configurability.md Co-authored-by: protolambda * Update specs/glossary.md Co-authored-by: Ben Jones * Update specs/protocol/configurability.md Co-authored-by: Ben Jones * 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 * 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 * Update specs/protocol/configurability.md Co-authored-by: Ben Jones * Update specs/protocol/configurability.md Co-authored-by: Ben Jones * Update specs/protocol/configurability.md Co-authored-by: Ben Jones * Update specs/protocol/configurability.md Co-authored-by: Ben Jones * docs: batch submitter address is administrator for batch submission frequency. * Update specs/protocol/configurability.md Co-authored-by: Ben Jones * docs: batcher is also admin of compression ratio. * docs: Data Availability Type added as a policy param. --------- Co-authored-by: Kevin Kz Co-authored-by: protolambda Co-authored-by: Ben Jones Co-authored-by: Matt Solomon --- specs/SUMMARY.md | 1 + specs/glossary.md | 17 +++++++ specs/protocol/configurability.md | 75 +++++++++++++++++++++++++++++++ 3 files changed, 93 insertions(+) create mode 100644 specs/protocol/configurability.md diff --git a/specs/SUMMARY.md b/specs/SUMMARY.md index ca1c0a863..dca759513 100644 --- a/specs/SUMMARY.md +++ b/specs/SUMMARY.md @@ -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) diff --git a/specs/glossary.md b/specs/glossary.md index 1e9440f10..513fa178a 100644 --- a/specs/glossary.md +++ b/specs/glossary.md @@ -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) @@ -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 diff --git a/specs/protocol/configurability.md b/specs/protocol/configurability.md new file mode 100644 index 000000000..8ef3e8ecb --- /dev/null +++ b/specs/protocol/configurability.md @@ -0,0 +1,75 @@ +# OP Stack Configurability + + + +**Table of Contents** + +- [Consensus Parameters](#consensus-parameters) +- [Policy Parameters](#policy-parameters) +- [Admin Roles](#admin-roles) +- [Service Roles](#service-roles) + + + +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) |