op-deployer: update devdocs, flag defaults, error message (#15364)

* op-deployer: update devdocs

* default to OPStackSupport for bootstrap protocol-version flags

* return all valid tags in error message

* add validation to --l1-contracts-locator flag

* remove L1ContractsRelease flag (auto-set)

Author: bitwiseguy

op-deployer/book/src/reference-guide/artifacts-locators.md

@@ -12,6 +12,9 @@ Locators can be one of three types:
   downloaded using a tagged locator are validated against a hardcoded checksum in the OP Deployer implementation.
   This prevents tampering with the contract artifacts once they have been tagged. Additionally, tagged locators are
   cached on disk to avoid repeated downloads.
+  - ex: `tag://op-contracts/v1.8.0-rc.4`
 - `https://` locators, which point to a tarball of contract artifacts somewhere on the web. HTTP locators are cached
   just like tagged locators are, but they are not validated against a checksum.
-- `file://` locators, which point to a directory on disk containing the artifacts.
+  - ex: `https://<url-to-remote-forge-artifacts>`
+- `file://` locators, which point to a directory on local disk containing the artifacts.
+  - ex: `file://<path-to-repo-root>/packages/contracts-bedrock/forge-artifacts`

op-deployer/book/src/user-guide/bootstrap.md

@@ -1,34 +1,70 @@
 # The Bootstrap Commands
 
-Bootstrap commands are used to deploy global singletons and implementation contracts for use with future invocations 
-of `apply`. Most users won't need to use these commands, since `op-deployer apply` will automatically use 
-predeployed contracts if they are available. However, you may need to use bootstrap commands if you're deploying 
-chains to an L1 that isn't natively supported by `op-deployer`.
+> Note: if you are joining an existing superchain, you can skip to the `init` and `apply` commands to create your L2 chain(s)
 
-There are several bootstrap commands available, which you can view by running `op-deployer bootstrap --help`. We'll 
-focus on the most important ones below.
+Bootstrap commands are used to deploy global singletons and implementation contracts for new superchains.
+The deployed contract be then be use with future invocations of `apply` so that new L2 chains can join that superchain.
+Most users won't need to use these commands, since `op-deployer apply` will automatically use predeployed contracts if they are available. However, you may need to use bootstrap commands if you're deploying chains to an L1 that isn't natively supported by `op-deployer`.
 
-## Implementations
+There are several bootstrap commands available, which you can view by running `op-deployer bootstrap --help`. We'll
+focus on the most important ones, which should be run in the sequence listed below.
 
-You can bootstrap implementations by running a command like this:
+**It is safe to call these commands from a hot wallet.** None of the contracts deployed by these command are "ownable,"
+so the deployment address has no further control over the system.
+
+# 1. bootstrap superchain
+
+```shell
+op-deployer bootstrap superchain \
+  --l1-rpc-url="<rpc url>" \
+  --private-key="<contract deployer private key>" \
+  --artifacts-locator="<locator>" \
+  --outfile="./.deployer/bootstrap_superchain.json" \
+  --superchain-proxy-admin-owner="<role address>" \
+  --protocol-versions-owner="<role address>" \
+  --guardian="<role address>"
+```
+
+### --required-protocol-version, --recommended-protocol-version (optional)
+Defaults to `OPStackSupport` value read from `op-geth`, but can be overridden by these flags.
+
+### --superchain-proxy-admin-owner, --protocol-versions-owner, --guardian
+In a dev environment, these can all be hot wallet EOAs. In a production environment, `--guardian` should be an HSM (hardward security module) protected hot wallet and the other two should be multisig cold-wallets (e.g. Gnosis Safes).
+
+### Output
+
+This command will deploy several contracts, and output a JSON like the one below:
+
+```json
+{
+  "proxyAdminAddress": "0x269b95a33f48a9055b82ce739b0c105a83edd64a",
+  "superchainConfigImplAddress": "0x2f4c87818d67fc3c365ea10051b94f98893f3c64",
+  "superchainConfigProxyAddress": "0xd0c74806fa114c0ec176c0bf2e1e84ff0a8f91a1",
+  "protocolVersionsImplAddress": "0xbded9e39e497a34a522af74cf018ca9717c5897e",
+  "protocolVersionsProxyAddress": "0x2e8e4b790044c1e7519caac687caffd4cafca2d4"
+}
+```
+
+# 2. bootstrap implementations
 
 ```shell
 op-deployer bootstrap implementations \
-  --artifacts-locator <locator> \ 
-  --l1-contracts-release op-contracts/<your-release> \
-  --l1-rpc-url <rpc url> \
-  --mips-version <1 or 2, for MIPS32 or MIPS64> \
-  --private-key <some private key> \ 
-  --protocol-versions-proxy <protocol versions proxy address> \
-  --superchain-config-proxy <superchain config proxy address> \
-  --upgrade-controller <upgrade controller address>
+  --artifacts-locator="<locator>" \
+  --l1-rpc-url="<rpc url>" \
+  --outfile="./.deployer/bootstrap_implementations.json" \
+  --mips-version="<1 or 2, for MIPS32 or MIPS64>" \
+  --private-key="<contract deployer private key>" \
+  --protocol-versions-proxy="<address output from bootstrap superchain>" \
+  --superchain-config-proxy="<address output from bootstrap superchain>" \
+  --upgrade-controller="<superchain-proxy-admin-owner used in bootstrap superchain>"
 ```
 
-This command will deploy implementations, blueprints, and the OPCM. Deployments are (for the most part) 
-deterministic, so contracts will only be deployed once per chain as long as the implementation and constructor args 
-remain the same. This applies to the `op-deployer apply` pipeline - that is, if someone else ran `op-deployer 
-boostrap implementations` at some point on a given L1 chain, then the `apply` pipeline will re-use those 
-implementations.
+### Output
+
+This command will deploy implementations, blueprints, and the OPCM. Deployments are (for the most part)
+deterministic, so contracts will only be deployed once per chain as long as the implementation and constructor args
+remain the same. This applies to the `op-deployer apply` pipeline - that is, if someone else ran `op-deployer boostrap implementations`
+at some point on a given L1 chain, then the `apply` pipeline will re-use those implementations.
 
 The command will output a JSON like the one below:
 
@@ -50,6 +86,3 @@ The command will output a JSON like the one below:
   "ProtocolVersionsImpl": "0x37e15e4d6dffa9e5e320ee1ec036922e563cb76c"
 }
 ```
-
-**It is safe to call this command from a hot wallet.** None of the contracts deployed by this command are "ownable," 
-so the deployment address has no further control over the system.

op-deployer/book/src/user-guide/init.md

@@ -32,7 +32,7 @@ l1ChainID = 11155420
 fundDevAccounts = false
 useInterop = false
 l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4"
-l2ContractsLocator = "op-contracts/v1.7.0-beta.1+l2-contracts"
+l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts"
 
 [superchainRoles]
   proxyAdminOwner = "0xeAAA3fd0358F476c86C26AE77B7b89a069730570"
@@ -58,6 +58,22 @@ l2ContractsLocator = "op-contracts/v1.7.0-beta.1+l2-contracts"
 ```
 
 Before you can use your intent file for a deployment, you will need to update all zero values to whatever is
-appropriate for your chain.
+appropriate for your chain. For dev environments, it is ok to use all EOAs/hot-wallets.
+
+## Production Setup
+In production environments, you should use a more secure setup with cold-wallet multisigs (e.g. Gnosis Safes) for the following:
+* `baseFeeVaultRecipient`
+* `l1FeeVaultRecipient`
+* `sequencerFeeVaultRecipient`
+* `l1ProxyAdminOwner`
+* `l2ProxyAdminOwner`
+* `systemConfigOwner`
+
+HSMs (hardware security modules) are recommended for the following hot-wallets:
+* `unsafeBlockSigner`
+* `batcher`
+* `proposer`
+* `challenger`
+
 
 [stages]: ../architecture/pipeline.md

op-deployer/pkg/deployer/bootstrap/flags.go

@@ -108,11 +108,6 @@ var (
 		Usage:   "Recommended protocol version (semver)",
 		EnvVars: deployer.PrefixEnvVar("RECOMMENDED_PROTOCOL_VERSION"),
 	}
-	L1ContractsReleaseFlag = &cli.StringFlag{
-		Name:    L1ContractsReleaseFlagName,
-		Usage:   "Release version to set OPCM implementations for, of the format `op-contracts/vX.Y.Z`.",
-		EnvVars: deployer.PrefixEnvVar("L1_CONTRACTS_RELEASE"),
-	}
 	SuperchainConfigProxyFlag = &cli.StringFlag{
 		Name:    "superchain-config-proxy",
 		Usage:   "Superchain config proxy.",
@@ -145,7 +140,6 @@ var ImplementationsFlags = []cli.Flag{
 	deployer.PrivateKeyFlag,
 	OutfileFlag,
 	deployer.ArtifactsLocatorFlag,
-	L1ContractsReleaseFlag,
 	MIPSVersionFlag,
 	WithdrawalDelaySecondsFlag,
 	MinProposalSizeBytesFlag,

op-deployer/pkg/deployer/bootstrap/implementations.go

@@ -70,8 +70,10 @@ func (c *ImplementationsConfig) Check() error {
 	if c.ArtifactsLocator == nil {
 		return errors.New("artifacts locator must be specified")
 	}
-	if c.L1ContractsRelease == "" {
-		return errors.New("L1 contracts release must be specified")
+	if c.ArtifactsLocator.IsTag() {
+		c.L1ContractsRelease = c.ArtifactsLocator.Tag
+	} else {
+		c.L1ContractsRelease = "dev"
 	}
 	if c.MIPSVersion != 1 && c.MIPSVersion != 2 {
 		return errors.New("MIPS version must be specified as either 1 or 2")

op-deployer/pkg/deployer/bootstrap/superchain.go

@@ -113,15 +113,24 @@ func SuperchainCLI(cliCtx *cli.Context) error {
 		Paused:                    paused,
 	}
 
-	if err := cfg.RequiredProtocolVersion.UnmarshalText([]byte(requiredVersionStr)); err != nil {
-		return fmt.Errorf("failed to parse required protocol version: %w", err)
+	// Default to op-geth params.OPStackSupport if not specified for required and recommended protocolversions
+	if requiredVersionStr != "" {
+		if err := cfg.RequiredProtocolVersion.UnmarshalText([]byte(requiredVersionStr)); err != nil {
+			return fmt.Errorf("failed to parse required protocol version: %w", err)
+		}
+	} else {
+		cfg.RequiredProtocolVersion = params.OPStackSupport
 	}
-	if err := cfg.RecommendedProtocolVersion.UnmarshalText([]byte(recommendedVersionStr)); err != nil {
-		return fmt.Errorf("failed to parse required protocol version: %w", err)
+
+	if recommendedVersionStr != "" {
+		if err := cfg.RecommendedProtocolVersion.UnmarshalText([]byte(recommendedVersionStr)); err != nil {
+			return fmt.Errorf("failed to parse recommended protocol version: %w", err)
+		}
+	} else {
+		cfg.RecommendedProtocolVersion = params.OPStackSupport
 	}
 
 	ctx := ctxinterrupt.WithCancelOnInterrupt(cliCtx.Context)
-
 	dso, err := Superchain(ctx, cfg)
 	if err != nil {
 		return fmt.Errorf("failed to deploy superchain: %w", err)

op-deployer/pkg/deployer/standard/standard.go

@@ -204,7 +204,11 @@ func ProtocolVersionsOwner(chainID uint64) (common.Address, error) {
 func ArtifactsURLForTag(tag string) (*url.URL, error) {
 	release, ok := taggedReleases[tag]
 	if !ok {
-		return nil, fmt.Errorf("unsupported tag: %s", tag)
+		var validTagsStr string
+		for t := range taggedReleases {
+			validTagsStr += fmt.Sprintf("  %s\n", t)
+		}
+		return nil, fmt.Errorf("unsupported tag: %s\nValid tags are:\n%s", tag, validTagsStr)
 	}
 
 	return url.Parse(release.URL())