From 1beb016c6d72cd6b3cbf9d15939ff78bcda598a6 Mon Sep 17 00:00:00 2001 From: Ori Pomerantz Date: Sun, 28 Apr 2024 04:10:58 -0500 Subject: [PATCH] docs(world/upgrade): explain how to make an upgradeable `World` (#2754) Co-authored-by: Kevin Ingersoll --- docs/pages/cli/deploy.mdx | 4 +-- docs/pages/config.mdx | 2 +- docs/pages/world/_meta.js | 2 +- .../pages/world/{upgrade.mdx => upgrades.mdx} | 34 ++++++++++++++++--- 4 files changed, 34 insertions(+), 8 deletions(-) rename docs/pages/world/{upgrade.mdx => upgrades.mdx} (77%) diff --git a/docs/pages/cli/deploy.mdx b/docs/pages/cli/deploy.mdx index 0b87e5b661..7e19f91953 100644 --- 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 --worldAddress
``` -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 index d251fd99ad..ed7d9f3876 100644 --- a/docs/pages/config.mdx +++ b/docs/pages/config.mdx @@ -124,4 +124,4 @@ The global configuration keys are all optional. - **`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 index 506ec2a1df..f24184929c 100644 --- 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 b/docs/pages/world/upgrades.mdx similarity index 77% rename from docs/pages/world/upgrade.mdx rename to docs/pages/world/upgrades.mdx index fc3ea7597d..103f027fab 100644 --- a/docs/pages/world/upgrade.mdx +++ b/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`. + + + +```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: [], + }, + }, +}); +``` + + + +## 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