docs(world/upgrade): explain how to make an upgradeable World (latt…

…icexyz#2754) Co-authored-by: Kevin Ingersoll <kingersoll@gmail.com>
tenetxyz · Apr 28, 2024 · 1beb016 · 1beb016
1 parent 75ed6f1
commit 1beb016
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 8 deletions.
diff --git a/docs/pages/cli/deploy.mdx b/docs/pages/cli/deploy.mdx
@@ -39,7 +39,6 @@ These are the command line options you can specify on `mud deploy`:
 
 | Option                  | Meaning                                          | Type    | Default value                                              |
 | ----------------------- | ------------------------------------------------ | ------- | ---------------------------------------------------------- |
-| `--version`             | Show version number                              | boolean | `false`                                                    |
 | `--configPath`          | Path to the config file                          | string  | `mud.config.ts`                                            |
 | `--printConfig`         | Print the resolved config                        | boolean | `false`                                                    |
 | `--saveDeployment`      | Save the deployment info to a file               | boolean | `true`                                                     |
@@ -51,6 +50,7 @@ These are the command line options you can specify on `mud deploy`:
 | `--skipBuild`           | Skip rebuilding the contracts before deploying   | boolean | `false`                                                    |
 | `--alwaysRunPostDeploy` | Run `PostDeploy.s.sol` after each deploy         | boolean | `false` (run the script only when deploying a new `World`) |
 | `--help`                | Show help                                        | boolean | `false`                                                    |
+| `--version`             | Show version number                              | boolean | `false`                                                    |
 
 (1) The hostname `localhost` may not work. If that is the case, use `127.0.0.1` instead.
 
@@ -80,7 +80,7 @@ To upgrade a `World`'s `System`s and tables, you can use this command line:
 pnpm mud deploy --rpc <url> --worldAddress <address>
 ```
 
-If properly configured, [there is also a way to upgrade the core MUD contracts](/world/upgrade)
+If properly configured, [there is also a way to upgrade the core MUD contracts](/world/upgrades).
 
 ## Debugging
 

diff --git a/docs/pages/config.mdx b/docs/pages/config.mdx
@@ -124,4 +124,4 @@ The global configuration keys are all optional.
 
   - <a id="upgradeableWorldImplementation" />
     **`upgradeableWorldImplementation`** a `bool`: Whether the `World` is to be deployed behind a proxy to [enable upgrades
-    of the core World implementation](/world/upgrade). The default is `false`.
+    of the core World implementation](/world/upgrades). The default is `false`.
diff --git a/docs/pages/world/_meta.js b/docs/pages/world/_meta.js
@@ -9,7 +9,7 @@ export default {
   balance: "Balance",
   "account-delegation": "Account Delegation",
   "batch-calls": "Batch Calls",
-  "upgrade": "Upgrading",
+  "upgrades": "Upgrading",
   modules: "Modules",
   reference: "Reference",
 };
diff --git a/docs/pages/world/upgrade.mdx → docs/pages/world/upgrades.mdx b/docs/pages/world/upgrade.mdx → docs/pages/world/upgrades.mdx
@@ -3,13 +3,39 @@ import { Callout } from "nextra/components";
 
 # Upgrading worlds
 
-The [`System`s](./systems) can be upgraded without changing the underlying `World` code.
-However, if the `World` was deployed [behind a proxy](/config#upgradeableWorldImplementation) it is also possible to upgrade the `World` itself.
+The [`System`s](./systems) can be upgraded without changing the underlying `World` code, using [`mud deploy --worldAddress`](/cli/deploy#upgrading-a-world).
+However, you can also upgrade the `World` contract itself if the `World` was deployed [behind a proxy](/config#upgradeableWorldImplementation).
 This allows you to upgrade to a future version of MUD, but adds some gas overhead for all calls (due to one more level of indirection).
 
-## Are upgrades possible?
+## Making an upgradeable `World`
 
-As per [ERC-1967](https://eips.ethereum.org/EIPS/eip-1967#logic-contract-address), the storage slot `0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc` stores the address of the `World` implementation in a proxy.
+To make a `World` upgradeable, edit the [`mud.config.ts`](/config) file and set `deploy.upgradeableWorldImplementation` to `true`.
+
+<CollapseCode>
+
+```typescript filename="mud.config.ts" copy showLineNumbers {4-6}
+import { defineWorld } from "@latticexyz/world";
+
+export default defineWorld({
+  deploy: {
+    upgradeableWorldImplementation: true,
+  },
+  tables: {
+    Counter: {
+      schema: {
+        value: "uint32",
+      },
+      key: [],
+    },
+  },
+});
+```
+
+</CollapseCode>
+
+## Testing if upgrades are possible
+
+As per [ERC-1967](https://eips.ethereum.org/EIPS/eip-1967#logic-contract-address), the storage slot `0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc` stores the address of the contract implementation in a proxy.
 So to identify if a `World` is deployed behind a proxy run these commands:
 
 ```sh copy