Add explanation to each line in the .env.example file (#387)

* add explanation to each line in the .env.example file

remove SCR_CHAIN_TYPE

* remove unused util

* fix up e2e tests

* add omitempty option to contract_versions_tag

Author: geoknee

.env.example

@@ -1,25 +1,37 @@
-# Required for both Standard Chains and Frontier Chains
-SCR_CHAIN_NAME=awesomechain # L2 chain name
+# Your chain must be listed in https://github.com/ethereum-lists/chains
+# And you must use the exact same name in this field:
+SCR_CHAIN_NAME=awesomechain
 
 # The superchain that this chain will belong to (mainnet or sepolia)
 SCR_SUPERCHAIN_TARGET=mainnet
 
+# The short name will be used to identify the chain within the registry.
+# Ideally it does not contain spaces.
 # Not that this is _NOT_ the short name from https://github.com/ethereum-lists/chains.
 # It does not need to be globally unique, only unique within the particular superchain.
-# In this repository, the chain is identified by {SUPERCHAIN_TARGET}/{CHAIN_SHORT_NAME}
+# In this repository, the chain is identified by {SCR_SUPERCHAIN_TARGET}/{SCR_CHAIN_SHORT_NAME}
 # For example, mainnet/op and sepolia/op have the same chain short name.
 SCR_CHAIN_SHORT_NAME=awsm
 
-SCR_CHAIN_TYPE=frontier # chain type (frontier or standard)
-
 # Set to true to run most of the validation checks for standard chains
-# CHAIN_TYPE must be frontier
 SCR_STANDARD_CHAIN_CANDIDATE=false
 
+# This is the path to your local fork of the github.com/ethereum-optimism/optimism monorepo
+# It is defined for convenience and reuse by other vars below
 SCR_MONOREPO_DIR=../optimism # path to local "ethereum-optimism/optimism" monorepo
+
+# The following vars point to three input files required for adding a chain
+# Data will be scraped from these files in order to construct the required registry data
 SCR_DEPLOYMENTS_DIR=${SCR_MONOREPO_DIR}/packages/contracts-bedrock/deployments/getting-started
 SCR_ROLLUP_CONFIG=${SCR_MONOREPO_DIR}/op-node/rollup.json
 SCR_GENESIS=${SCR_MONOREPO_DIR}/op-node/genesis.json
+
+# Your chain's endpoint for ETHEREUM JSON-RPC requests
 SCR_PUBLIC_RPC="http://awe.some.rpc" # new OP Stack L2 RPC URL
+
+# Your chain's sequencer endpoint for eth_sendRawTransaction.
+# This can be set the same as SCR_PUBLIC_RPC if you don't have a separate endpoint.
 SCR_SEQUENCER_RPC="http://awe.some.seq.rpc" # new OP Stack L2 sequencer RPC URL
+
+# Your chain's block explorer (e.g. Blockscout, Etherscan)
 SCR_EXPLORER="https://awesomescan.org" # new OP Stack L2 block explorer URL

README.md

@@ -42,7 +42,8 @@ You will need [`jq`](https://jqlang.github.io/jq/download/) and [`foundry`](http
 
 To contribute a standard OP-Stack chain configuration, in addition to user-supplied metadata (chain name) the following data is required: contracts deployment, rollup config, L2 genesis. We provide a tool to scrape this information from your local [monorepo](https://github.com/ethereum-optimism/optimism) folder.
 
-First, make a copy of `.env.example` named `.env`, and alter the variables to appropriate values.
+First, make a copy of `.env.example` named `.env`, and alter the variables to appropriate values. Each value is explained in a comment in `.env.example`.
+
 #### Frontier chains
 To contribute a frontier OP-Stack chain configuration, you set the `SCR_CHAIN_TYPE=frontier` in the `.env` file. This will set `superchain_level = 1` in the registry's config file for this chain.
 

add-chain/e2e_test.go

@@ -32,41 +32,38 @@ var tests = []struct {
 		chainShortName:   "testchain_b",
 		rollupConfigFile: "./testdata/monorepo/op-node/rollup_baseline.json",
 		deploymentsDir:   "./testdata/monorepo/deployments",
-		chainType:        "standard",
 	},
 	{
 		name:                   "zorasep",
 		chainName:              "testchain_zorasep",
 		chainShortName:         "testchain_zs",
 		rollupConfigFile:       "./testdata/monorepo/op-node/rollup_zorasep.json",
 		deploymentsDir:         "./testdata/monorepo/deployments",
-		chainType:              "frontier",
 		standardChainCandidate: true,
 	},
 	{
-		name:             "plasma",
-		chainName:        "testchain_plasma",
-		chainShortName:   "testchain_p",
-		rollupConfigFile: "./testdata/monorepo/op-node/rollup_plasma.json",
-		deploymentsDir:   "./testdata/monorepo/deployments",
-		chainType:        "standard",
+		name:                   "plasma",
+		chainName:              "testchain_plasma",
+		chainShortName:         "testchain_p",
+		rollupConfigFile:       "./testdata/monorepo/op-node/rollup_plasma.json",
+		deploymentsDir:         "./testdata/monorepo/deployments",
+		standardChainCandidate: true,
 	},
 	{
 		name:                   "standard-candidate",
 		chainName:              "testchain_standard-candidate",
 		chainShortName:         "testchain_sc",
 		rollupConfigFile:       "./testdata/monorepo/op-node/rollup_standard-candidate.json",
-		chainType:              "frontier",
 		deploymentsDir:         "./testdata/monorepo/deployments",
 		standardChainCandidate: true,
 	},
 	{
-		name:             "faultproofs",
-		chainName:        "testchain_faultproofs",
-		chainShortName:   "testchain_fp",
-		rollupConfigFile: "./testdata/monorepo/op-node/rollup_faultproofs.json",
-		chainType:        "standard",
-		deploymentsDir:   "./testdata/monorepo/deployments-faultproofs",
+		name:                   "faultproofs",
+		chainName:              "testchain_faultproofs",
+		chainShortName:         "testchain_fp",
+		rollupConfigFile:       "./testdata/monorepo/op-node/rollup_faultproofs.json",
+		deploymentsDir:         "./testdata/monorepo/deployments-faultproofs",
+		standardChainCandidate: true,
 	},
 }
 
@@ -83,7 +80,6 @@ func TestAddChain_Main(t *testing.T) {
 
 			args := []string{
 				"add-chain",
-				"--chain-type=" + tt.chainType,
 				"--chain-name=" + tt.chainName,
 				"--chain-short-name=" + tt.chainShortName,
 				"--rollup-config=" + tt.rollupConfigFile,

add-chain/flags/flags.go

@@ -15,13 +15,6 @@ func prefixEnvVars(names ...string) []string {
 }
 
 var (
-	ChainTypeFlag = &cli.StringFlag{
-		Name:     "chain-type",
-		Value:    "frontier",
-		EnvVars:  prefixEnvVars("CHAIN_TYPE"),
-		Usage:    "Type of chain (either standard or frontier)",
-		Required: false,
-	}
 	ChainNameFlag = &cli.StringFlag{
 		Name:     "chain-name",
 		Value:    "",

add-chain/main.go

@@ -2,7 +2,6 @@ package main
 
 import (
 	"encoding/json"
-	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -13,6 +12,7 @@ import (
 	"github.com/ethereum-optimism/superchain-registry/add-chain/cmd"
 	"github.com/ethereum-optimism/superchain-registry/add-chain/config"
 	"github.com/ethereum-optimism/superchain-registry/add-chain/flags"
+	"github.com/ethereum-optimism/superchain-registry/superchain"
 	"github.com/joho/godotenv"
 	"github.com/urfave/cli/v2"
 )
@@ -26,7 +26,6 @@ var app = &cli.App{
 		flags.ExplorerFlag,
 		flags.SuperchainTargetFlag,
 		flags.MonorepoDirFlag,
-		flags.ChainTypeFlag,
 		flags.ChainNameFlag,
 		flags.ChainShortNameFlag,
 		flags.RollupConfigFlag,
@@ -72,16 +71,9 @@ func runApp(args []string) error {
 }
 
 func entrypoint(ctx *cli.Context) error {
-	chainType := ctx.String(flags.ChainTypeFlag.Name)
 	standardChainCandidate := ctx.Bool(flags.StandardChainCandidateFlag.Name)
-	if standardChainCandidate && chainType == "standard" {
-		return errors.New("cannot set both chainType=standard and standard-chain-candidate=true")
-	}
 
-	superchainLevel, err := getSuperchainLevel(chainType)
-	if err != nil {
-		return fmt.Errorf("failed to get superchain level: %w", err)
-	}
+	superchainLevel := superchain.Frontier // All chains enter as frontier chains
 
 	publicRPC := ctx.String(flags.PublicRpcFlag.Name)
 	sequencerRPC := ctx.String(flags.SequencerRpcFlag.Name)

add-chain/testdata/superchain/configs/sepolia/expected_baseline.yaml

@@ -4,10 +4,8 @@ public_rpc: http://awe.some.rpc
 sequencer_rpc: http://awe.some.seq.rpc
 explorer: https://awesomescan.org
 
-superchain_level: 2
+superchain_level: 1
 superchain_time: null # Missing hardfork times are NOT yet inherited from superchain.yaml
-contracts_version_tag: op-contracts/v1.3.0 # Multi-Chain Prep (MCP) https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts%2Fv1.3.0
-
 batch_inbox_addr: "0xFf00000000000000000000000000000000042069"
 
 genesis:

add-chain/testdata/superchain/configs/sepolia/expected_faultproofs.yaml

@@ -4,7 +4,8 @@ public_rpc: http://awe.some.rpc
 sequencer_rpc: http://awe.some.seq.rpc
 explorer: https://awesomescan.org
 
-superchain_level: 2
+superchain_level: 1
+standard_chain_candidate: true # This is a temporary field which causes most of the standard validation checks to run on this chain
 superchain_time: null # Missing hardfork times are NOT yet inherited from superchain.yaml
 contracts_version_tag: op-contracts/v1.4.0 # Fault Proofs https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts%2Fv1.4.0
 

add-chain/testdata/superchain/configs/sepolia/expected_plasma.yaml

@@ -4,7 +4,8 @@ public_rpc: http://awe.some.rpc
 sequencer_rpc: http://awe.some.seq.rpc
 explorer: https://awesomescan.org
 
-superchain_level: 2
+superchain_level: 1
+standard_chain_candidate: true # This is a temporary field which causes most of the standard validation checks to run on this chain
 superchain_time: null # Missing hardfork times are NOT yet inherited from superchain.yaml
 contracts_version_tag: op-contracts/v1.3.0 # Multi-Chain Prep (MCP) https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts%2Fv1.3.0
 

add-chain/utils.go

@@ -5,8 +5,6 @@ import (
 	"fmt"
 	"os/exec"
 	"strings"
-
-	"github.com/ethereum-optimism/superchain-registry/superchain"
 )
 
 func castCall(contractAddress, calldata, l1RpcUrl string) (string, error) {
@@ -26,16 +24,3 @@ func castCall(contractAddress, calldata, l1RpcUrl string) (string, error) {
 
 	return address, nil
 }
-
-func getSuperchainLevel(chainType string) (superchain.SuperchainLevel, error) {
-	switch chainType {
-	case "standard":
-		fmt.Printf("Adding standard chain to superchain-registry...\n\n")
-		return superchain.Standard, nil
-	case "frontier":
-		fmt.Printf("Adding frontier chain to superchain-registry...\n\n")
-		return superchain.Frontier, nil
-	}
-
-	return 0, fmt.Errorf("invalid chain type: %s", chainType)
-}

superchain/superchain.go

@@ -95,7 +95,7 @@ type ChainConfig struct {
 	// An op-contracts tag from github.com/ethereum-optimism/optimism
 	// from which contracts were deployed. Example: "op-contracts/v1.4.0".
 	// May be nil for frontier chains.
-	ContractsVersionTag *string `yaml:"contracts_version_tag"`
+	ContractsVersionTag *string `yaml:"contracts_version_tag,omitempty"`
 
 	BatchInboxAddr Address `yaml:"batch_inbox_addr"`