Skip to content

docs: add SuperchainDefinition type to superchain-config spec #867

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

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+79 −0
Open

docs: add SuperchainDefinition type to superchain-config spec #867

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15e69ea
docs: add SuperchainDefinition type to superchain-config spec
Himess Nov 29, 2025
ae02602
docs: add Hardforks and SuperchainL1 type definitions
Himess Dec 4, 2025
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
78 changes: 78 additions & 0 deletions specs/protocol/superchain-config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,10 @@
**Table of Contents**

- [Overview](#overview)
- [Configuration Data Structure](#configuration-data-structure)
- [SuperchainDefinition](#superchaindefinition)
- [Hardforks](#hardforks)
- [SuperchainL1](#superchainl1)
- [Invariants](#invariants)
- [iSUPC-001: The Guardian and Pause Deputy must be able to trigger the Pause Mechanism](#isupc-001-the-guardian-and-pause-deputy-must-be-able-to-trigger-the-pause-mechanism)
- [Impact](#impact)
Expand All @@ -29,6 +33,80 @@
The SuperchainConfig contract is used to manage global configuration values for multiple OP Chains
within a single Superchain network.

## Configuration Data Structure

The `SuperchainDefinition` type represents the configuration for a
Superchain target, containing information about L1 contract addresses
and network parameters.

### SuperchainDefinition

```javascript
SuperchainDefinition {
Name string
ProtocolVersionsAddr checksummedAddress
SuperchainConfigAddr checksummedAddress
OPContractsManagerAddr checksummedAddress
Hardforks Hardforks
L1 SuperchainL1
}
```

**Fields:**

- `Name`: The name of the superchain (e.g., "mainnet", "sepolia")
- `ProtocolVersionsAddr`: Address of the ProtocolVersions contract on L1
- `SuperchainConfigAddr`: Address of the SuperchainConfig contract on L1
- `OPContractsManagerAddr`: Address of the OP Contracts Manager on L1
- `Hardforks`: Hardfork activation configuration for the superchain
Copy link
Member

@emhane emhane Dec 4, 2025

Choose a reason for hiding this comment

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

we should probably have this type in specs too somewhere, perhaps it's already in the specs in another location? or if it's simply a map, that should be stated here. basically it should say which data type the field is.

Copy link
Author

@Himess Himess Dec 4, 2025

Choose a reason for hiding this comment

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

Done

- `L1`: L1 chain information including chain ID, RPC endpoint, and explorer URL
Copy link
Member

@emhane emhane Dec 4, 2025

Choose a reason for hiding this comment

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

we should probably have this type in the spec too, and link to it here

Copy link
Author

@Himess Himess Dec 4, 2025

Choose a reason for hiding this comment

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

Done


### Hardforks

The `Hardforks` type contains optional activation timestamps for each network upgrade.

```javascript
Hardforks {
CanyonTime uint64
DeltaTime uint64
EcotoneTime uint64
FjordTime uint64
GraniteTime uint64
HoloceneTime uint64
IsthmusTime uint64
InteropTime uint64
}
```

**Fields:**

- `CanyonTime`: Activation timestamp for the Canyon upgrade
- `DeltaTime`: Activation timestamp for the Delta upgrade
- `EcotoneTime`: Activation timestamp for the Ecotone upgrade
- `FjordTime`: Activation timestamp for the Fjord upgrade
- `GraniteTime`: Activation timestamp for the Granite upgrade
- `HoloceneTime`: Activation timestamp for the Holocene upgrade
- `IsthmusTime`: Activation timestamp for the Isthmus upgrade
- `InteropTime`: Activation timestamp for the Interop upgrade

### SuperchainL1

The `SuperchainL1` type contains L1 chain information for the superchain.

```javascript
SuperchainL1 {
ChainID uint64
PublicRPC string
Explorer string
}
```

**Fields:**

- `ChainID`: The chain ID of the L1 network (e.g., 1 for Ethereum mainnet, 11155111 for Sepolia)
- `PublicRPC`: Public RPC endpoint URL for the L1 network
- `Explorer`: Block explorer URL for the L1 network

## Invariants

### iSUPC-001: The Guardian and Pause Deputy must be able to trigger the Pause Mechanism
Expand Down
1 change: 1 addition & 0 deletions words.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ cellborder
chainid
Chainid
checkpointed
checksummedAddress
clabby
codehash
configurables
Expand Down