Gov V1 to OpenGov: A Technical Migration Guide


This post serves as a guide for runtime developers wishing to upgrade their Substrate-based chain from Gov V1 to OpenGov.

We will assume a Gov V1 configuration similar to those that existed on Polkadot and Kusama, before those chains migrated to OpenGov.

Throughout this guide, we will reference the two primary PRs responsible for migrating the Polkadot relay chain to OpenGov:

You may wish to give the PRs a skim read before proceeding.

Step 1: Add dependencies

Add the following OpenGov crates from polkadot-sdk to your runtime Cargo.toml:

  • sp-arithmetic
  • pallet-conviction-voting
  • pallet-referenda
  • pallet-whitelist

Don’t forget to propagate features to your new dependencies (example).

Step 2: Configure OpenGov for your runtime

Primarily, this involves defining your new origins and spending tracks.

For reference see how OpenGov is configured for Polkadot.

Step 3: Add your OpenGov configuration to your runtime

For reference, see changes made to the runtime/polkadot/src/ file in this PR.

Step 4: Update XCM Config

Primarily, this involves defining new XCM origins for Collectives and Fellows.

For reference, see changes made to the Polkadot XCM config for OpenGov.

Step 5: Remove Gov V1 from your runtime

For reference, see changes made under runtime/polkadot/** when Gov V1 was removed from Polkadot.

Step 6: Add Migrations to Unlock/Unreserve Gov V1 Funds and Remove Old Storage

6a) Create an UnlockConfig

Gov V1 pallets have been removed from your runtime, so you will need to implement a special UnlockConfig mirroring their old configuration to access their storage

For reference, see how this was implemented for Polkadot.

6b) Add migrations for unlocking/unreserving funds from Gov V1 pallets that would otherwise become lost

For reference, see how these migrations were introduced for Polkadot.

6c) Add migrations cleaning up keys from old Gov V1 pallets

For reference, see how these migrations were introduced for Polkadot.


Enjoy OpenGov!

If you’re following the guide and I’ve missed a step or anything is unclear feel free to reply here and I’ll try my best to help.