feat: add superchain-registry

pages/stack/superchain-registry.mdx

@@ -0,0 +1,126 @@
+# Overview of the Superchain Registry
+
+<Callout type="info">
+ ⚠️ This repository is a work in progress. At a later date, it will be proposed to, and must be approved by, Optimism Governance. Until that time, the configuration described here is subject to change.
+
+</Callout>
+
+The Superchain Registry is a critical component of the Optimism ecosystem, particularly in managing the inclusion and 
+configuration of Layer 2 (L2) chains within the Superchain framework. Optimism's vision for scalability involves the 
+creation of a network of L2 chains, referred to as the Superchain, which leverages the OP Stack—a modular and open-source
+ set of tools for building these chains.
+ The Superchain Registry functions as an index that tracks which chains are part of the Superchain. 
+ It ensures transparency by documenting the configuration parameters for each chain, 
+ such as their protocol versions and governance settings. This registry is essential for maintaining consistency and 
+ security across the network by verifying that all included chains meet the criteria set forth by their 
+ respective Blockspace Charters​ [Optimism Collective](https://gov.optimism.io/t/season-6-introducing-blockspace-charters-superchain-first-governance/8133)​ 
+ [Optimism Docs](https://docs.optimism.io/chain/addresses)​.
+
+The Superchain Registry repository hosts Superchain-configuration data in a minimal human-readable form. 
+This includes mainnet and testnet Superchain targets, and their respective member chains.
+
+Other configuration, such as contract-permissions, and `SystemConfig` parameters are hosted and governed onchain.
+
+The superchain configs are made available in minimal form, to embed in OP-Stack software. 
+Full deployment artifacts and genesis-states can be derived from the minimal form using the reference [op-chain-ops](https://github.com/ethereum-optimism/optimism/tree/develop/op-chain-ops) tooling.
+
+The `semver.yaml` files each represent the semantic versioning lockfile for all the smart contracts in that superchain.
+ It is meant to be used when building transactions that upgrade the implementations set in the proxies.
+
+If you would like to contribute a new chain or superchain, please see our [contributing guide](https://github.com/ethereum-optimism/superchain-registry/blob/main/CONTRIBUTING.md).
+
+# Superchain Go Module
+Superchain configs can be imported as Go-module:
+
+``` go get github.com/ethereum-optimism/superchain-registry/superchain@latest```
+
+See [op-chain-ops](https://github.com/ethereum-optimism/optimism/tree/develop/op-chain-ops) for config tooling and for smart-contract bindings.
+
+# Validation Go Module
+
+A second module exists in this repo whose purpose is to validate the config exported by the `superchain` module. 
+It is a separate module to avoid import cycles and polluting downstream dependencies with things like `go-ethereum` 
+(which is used in the validation tests). 
+The modules are tracked by a top-level go.work file.
+The associated `go.work.sum` file is gitignored and not crucial to typical workflows,
+(perchain-registry/blob/main/.circleci/config.yml).
+
+# CheckSecurityConfigs
+
+The `CheckSecurityConfigs.s.sol` script is used in CI to perform security checks of OP Chains registered in the superchain directory. 
+At high level, it performs checks to ensure privileges are properly granted to the right addresses. 
+More specifically, it checks the following privilege grants and role designations:
+
+### 1. Generic privileges:
+
+i. Proxy admins. For example, `L1ERC721BridgeProxy` and `OptimismMintableERC20FactoryProxy` specify 
+the proxy admin addresses who can change their implementations.
+
+ii. Address managers. For example, `ProxyAdmin` specifies the address manager it trusts to look up certain addresses by name.
+iii. Contract owners. For example, many `Ownable` contracts use this role to specify the message senders allowed to make privileged calls.
+
+### 2. Optimism privileged cross-contract calls:
+
+i. Trusted messengers. For example, `L1ERC721BridgeProxy` and `L1StandardBridgeProxy` specify 
+ the cross domain messenger address they trust with cross domain message sender information.
+ii. Trusted bridges. For example, `OptimismMintableERC20FactoryProxy` specifies 
+the L1 standard bridge it trusts to mint and burn tokens.
+iii. Trusted portal. For example, `L1CrossDomainMessengerProxy` specifies 
+the portal it trusts to deposit transactions and get L2 senders.
+iv. Trusted oracles. For example, `OptimismPortalProxy` specifies the L2 oracle they trust with the L2 state root information.
+a. After the FPAC upgrade, the `OptimismPortalProxy` specifies the `DisputeGameFactory` they trust rather than the legacy `L2OutputOracle` contract. 
+v. Trusted system config. For example, `OptimismPortalProxy` specifies the system config they trust to get resource config from. TODO(issues/37): add checks for the ResourceMetering contract.
+3. Optimism privileged operational roles:
+
+i. Guardians. This is the role that can pause withdraws in the Optimism protocol.
+ a. After the FPAC upgrade, the `Guardian` can also blacklist dispute games and change the respected game type in the `OptimismPortal`.
+ii. Challengers. This is the role that can delete `L2OutputOracleProxy`'s output roots in the Optimism protocol 
+a. After the FPAC upgrade, the `CHALLENGER` is a permissionless role in the `FaultDisputeGame`. 
+However, in the PermissionedDisputeGame, the `CHALLENGER` role is the only party allowed to dispute 
+output proposals created by the `PROPOSER` role.
+
+
+As a result, here is a visualization of all the relationships the CheckSecurityConfigs.s.sol script checks:
+
+ L1ERC721BridgeProxy -- "admin()" --> ProxyAdmin
+ L1ERC721BridgeProxy -- "messenger()" --> L1CrossDomainMessengerProxy
+
+ OptimismMintableERC20FactoryProxy -- "admin()" --> ProxyAdmin
+ OptimismMintableERC20FactoryProxy -- "BRIDGE()" --> L1StandardBridgeProxy
+
+ ProxyAdmin -- "addressManager()" --> AddressManager
+ ProxyAdmin -- "owner()" --> ProxyOwnerMultisig
+
+ L1CrossDomainMessengerProxy -- "PORTAL()" --> OptimismPortalProxy
+ L1CrossDomainMessengerProxy -- "addressManager[address(this)]" --> AddressManager
+
+ L1StandardBridgeProxy -- "getOwner()" --> ProxyAdmin
+ L1StandardBridgeProxy -- "messenger()" --> L1CrossDomainMessengerProxy
+
+ AddressManager -- "owner()" --> ProxyAdmin
+
+ OptimismPortalProxy -- "admin()" --> ProxyAdmin
+ OptimismPortalProxy -- "GUARDIAN()" --> GuardianMultisig
+ OptimismPortalProxy -- "L2_ORACLE()" --> L2OutputOracleProxy
+ OptimismPortalProxy -- "SYSTEM_CONFIG()" --> SystemConfigProxy
+ OptimismPortalProxy -- "disputeGameFactory()" --> DisputeGameFactoryProxy
+
+ L2OutputOracleProxy -- "admin()" --> ProxyAdmin
+ L2OutputOracleProxy -- "CHALLENGER()" --> ChallengerMultisig
+
+ SystemConfigProxy -- "admin()" --> ProxyAdmin
+ SystemConfigProxy -- "owner()" --> SystemConfigOwnerMultisig
+
+ DisputeGameFactoryProxy -- "admin()" --> ProxyAdmin
+ DisputeGameFactoryProxy -- "owner()" --> ProxyAdminOwner
+
+ AnchorStateRegistryProxy -- "admin()" --> ProxyAdmin
+
+ DelayedWETHProxy -- "admin()" --> ProxyAdmin
+ DelayedWETHProxy -- "owner()" --> ProxyAdminOwner
+
+
+
+
+
+