# Upgrade Setup

We will use the `UpgradeBeacon` pattern to implement three upgradable contract types: `Home`, `Replica`, and `GovernanceRouter`.

Each upgradable contract will have:

* **Proxy**
  * the permanent address of the contract that external entities interact with
  * holds the storage of the contract
  * uses the logic specified by `Implementation`
  * uses `delegatecall` to forward contract calls from `Proxy` → `UpgradeBeacon` → `Implementation`
* **UpgradeBeacon**
  * stores the (mutable) address of the `Implementation`
  * forwards `delegatecalls` to the `Implementation`
  * accepts new `Implementation` addresses from its `Controller` (thereby performing upgrades for all `Proxies`)
* **Implementation**
  * specifies the logic of the contract
  * code is the same as a normal, non-upgradable contract implementation (though it should use upgrade-safe storage)

Each of the three `UpgradeBeacon` contracts will share a the same `Controller` — the contract with the power to perform upgrades.

The **Controller** contract will have two roles: controller and saver.

* `controller`
  * is a transferrable role that should be performing upgrades in almost every case.
  * will be set to the `GovernanceRouter Proxy`, so that the Governance xApp ultimately controls the upgrades of the entire system. Note that this creates a circular dependency which makes upgrades of the `GovernanceRouter Implementation` particularly sensitive.
* `saver`
  * is a transferrable(?) role that is responsible for recovering the system in a catastrophic failure case. Actions performed by the `saver` will be subject to a timelock enforced by the Controller contract.
  * will be set to a multisig contract where the signatories are a set of known / trusted community members. the signatories for the `saver` multisig be the same on every chain

### Diagrams[#](https://docs.nomad.xyz/dev/upgrade-setup.html#diagrams) <a href="#diagrams" id="diagrams"></a>

![Upgrade Setup Diagram 1](https://docs.nomad.xyz/Upgrade-Setup-1.png)

![Upgrade Setup Diagram 2](https://docs.nomad.xyz/Upgrade-Setup-2.png)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nomad.xyz/developers/core-developers/upgrade-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.