Skip to content
Edit this page

Upgrade MultiGov Contracts on EVM Chains＃

MultiGov is designed to be flexible but stable. Due to the system's complexity and cross-chain nature, upgrades should be rare and carefully considered. When upgrades are necessary, they must be meticulously planned and executed to ensure system integrity and continuity.

Key Considerations for Upgrades＃

  • HubGovernor:

    • Not upgradeable. A new deployment requires redeploying several components of the MultiGov system. Refer to the Process for Major System Upgrade section for more details.

  • HubVotePool:

    • Can be replaced by setting a new HubVotePool on the HubGovernor.
    • Requires re-registering all spokes on the new HubVotePool.
    • Must register the query type and implementation for vote decoding by calling registerQueryType on the new HubVotePool.
    • A new proposal would have to authorize the governor to use the newly created hub vote pool and will also handle registering the appropriate query decoders and registering the appropriate spoke SpokeVoteAggregators.

  • SpokeMessageExecutor:

    • Upgradeable via UUPS proxy pattern.
    • Stores critical parameters in SpokeMessageExecutorStorage.

  • HubEvmSpokeAggregateProposer:

    • Needs redeployment if HubGovernor changes.
    • Requires re-registering all spokes after redeployment.

  • HubProposalMetadata:

    • Needs redeployment if HubGovernor changes, as it references HubGovernor as a parameter.

  • SpokeMetadataCollector:

    • Requires redeployment if the hub chain ID changes or if HubProposalMetadata changes.

Process for Major System Upgrade＃

  1. Deploy the new HubGovernor contract.
  2. Redeploy the following contracts:
    • HubEvmSpokeAggregateProposer with the new HubGovernor address.
    • HubProposalMetadata referencing the new HubGovernor.
    • If hub chain ID changes, redeploy SpokeMetadataCollector on all spoke chains.
  3. Update the HubVotePool contract:
    • Set the new HubVotePool on the new HubGovernor.
    • Register all spokes on the new HubVotePool.
    • Register the query type and implementation for vote decoding (HubEvmSpokeVoteDecoder).
  4. Re-register all spokes on the new HubEvmSpokeAggregateProposer.
  5. Conduct thorough testing of the new system setup and verify all cross-chain interactions are functioning correctly.
  6. Create a proposal to switch the timelock to the new governor and communicate clearly to the community what changes were made.
  7. Implement a transition period where the new system is closely monitored and address any issues that arise promptly.

Important Considerations＃

  • Always prioritize system stability, upgrades should only be performed when absolutely necessary.
  • Thoroughly audit all new contract implementations before proposing an upgrade.
  • Account for all affected components across all chains in the upgrade plan.
  • Provide comprehensive documentation for the community about the upgrade process and any changes in functionality.
  • Always test upgrades extensively on testnets before implementing in production.