docs(cli/verify): initial version (#2744)

Co-authored-by: Kevin Ingersoll <[email protected]>
Co-authored-by: Fraser Scott <[email protected]>

docs/pages/cli/_meta.js

@@ -3,6 +3,7 @@ export default {
   worldgen: "mud worldgen",
   test: "mud test",
   deploy: "mud deploy",
+  verify: "mud verify",
   "dev-contracts": "mud dev-contracts",
   "abi-ts": "mud abi-ts",
   faucet: "mud faucet",

docs/pages/cli/deploy.mdx

@@ -1,3 +1,5 @@
+import { Callout } from "nextra/components";
+
 # mud deploy
 
 This command deploys a MUD app to a blockchain.
@@ -52,6 +54,12 @@ These are the command line options you can specify on `mud deploy`:
 
 (1) The hostname `localhost` may not work. If that is the case, use `127.0.0.1` instead.
 
+<Callout type="info" emoji="ℹ️">
+  If you want to [verify](./verify) the contracts that make up the `World`, do it right after deployment. Verification
+  only works with the original source code, compiler options, and compiled artifacts. Otherwise, the generated bytecode
+  is different and therefore verification fails.
+</Callout>
+
 ## Examples
 
 ### New `World`
@@ -66,12 +74,14 @@ This command also writes the `World`'s address to `worlds.json`.
 
 ### Upgrading a World
 
-To upgrade a `World` (add or modify `System`s, tables, etc.) you can use this command line:
+To upgrade a `World`'s `System`s and tables, you can use this command line:
 
 ```sh copy
 pnpm mud deploy --rpc <url> --worldAddress <address>
 ```
 
+If properly configured, [there is also a way to upgrade the core MUD contracts](/world/upgrade)
+
 ## Debugging
 
 To generate debug messages, use this command:

docs/pages/cli/verify.mdx

@@ -0,0 +1,67 @@
+import { Callout } from "nextra/components";
+
+# mud verify
+
+This command uploads the source code for the deployed contracts to a public repository, such as a block explorer.
+The repository then compiles the source code and verifies that the compiled version is identical to what is deployed onchain.
+
+The best time to perform verification is immediately after [deployment](./deploy).
+Verification only works with the original source code, compiler options, and compiled artifacts.
+Otherwise, the generated bytecode is different and therefore verification fails.
+
+<Callout type="info" emoji="ℹ️">
+  Currently, on Etherscan and Blockscout `mud verify` verifies the `System`s that are part of your application, but not
+  the MUD contracts themselves. On Sourcify `mud verify` verifies all the contracts.
+</Callout>
+
+## Using the command
+
+1. If using Etherscan or Blockscout, specify the API key:
+
+   ```sh copy
+   export ETHERSCAN_API_KEY=<value goes here>
+   ```
+
+   With Blockscout you don't _have_ to specify the API key.
+   However, there is a limited number of requests allowed for accounts without an API key per second, so you get much more reliable service if you do.
+
+1. Run the command.
+
+   ```sh copy
+   pnpm mud verify --worldAddress <address here> --rpc <RPC to the blockchain> [--verifier <verifier>]
+   ```
+
+   These are the command line options you can specify on `mud verify`:
+
+   | Option           | Meaning                                                | Type    | Default value                |
+   | ---------------- | ------------------------------------------------------ | ------- | ---------------------------- |
+   | `--worldAddress` | Verify the contracts of the World at the given address | string  | none, error if unspecified   |
+   | `--configPath`   | Path to the config file                                | string  | `mud.config.ts`              |
+   | `--verifier`     | The verifier to use (`sourcify`, or `blockscout`)      | string  | `sourcify`                   |
+   | `--verifierUrl`  | URL to use to access the verifier's API                | string  | depends on the verifier used |
+   | `--profile`      | The foundry profile to use                             | string  | `local`                      |
+   | `--rpc`          | URL to the blockchain                                  | string  |                              |
+   | `--srcDir`       | Source directory                                       | string  | Foundry `src` directory      |
+   | `--version`      | Show version number                                    | boolean | `false`                      |
+
+   Note that it takes block explorers some time to process new contracts.
+   You should wait 5-10 minutes past deployment before you verify the contract on Etherscan and/or Blockscout.
+
+## Examples
+
+- To verify the world at that address on Holesky on [sourcify](https://sourcify.dev/):
+
+  ```sh
+  WORLD_ADDRESS=0x816038e244ff78b86a5e7dec9bf281634fb6d2a2
+  HOLESKY_RPC=https://ethereum-holesky.publicnode.com
+  pnpm mud verify --rpc $HOLESKY_RPC --worldAddress $WORLD_ADDRESS
+  ```
+
+- To verify a contract on Holesky for users of [Blockscout](https://www.blockscout.com/):
+
+  ```sh
+  WORLD_ADDRESS=0x816038e244ff78b86a5e7dec9bf281634fb6d2a2
+  HOLESKY_RPC=https://ethereum-holesky.publicnode.com
+  export ETHERSCAN_API_KEY= ** blockscout API key goes here **
+  pnpm mud verify --rpc $HOLESKY_RPC --worldAddress $WORLD_ADDRESS --verifier blockscout --verifier-url https://eth-holesky.blockscout.com/api
+  ```