From edcf4d1a8ddd01f979118d2a9e7bfab3fd6f6c75 Mon Sep 17 00:00:00 2001 From: Kevin Britz Date: Mon, 26 Aug 2024 01:20:22 -0700 Subject: [PATCH 1/5] add guide --- runbooks/MIGRATION_v2.3.md | 82 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 runbooks/MIGRATION_v2.3.md diff --git a/runbooks/MIGRATION_v2.3.md b/runbooks/MIGRATION_v2.3.md new file mode 100644 index 000000000..751fa4eed --- /dev/null +++ b/runbooks/MIGRATION_v2.3.md @@ -0,0 +1,82 @@ +# Perennial v2.3 Migration Runbook + +## Checklist + +0. [Pre-upgrade action items](#pre-upgrade-action-items) +2. [Enter *settle only* mode, and settle all accounts on all markets / vaults](#enter-settle-only-mode-and-settle-all-accounts-on-all-markets--vaults) +3. [Upgrade to v2.3](#upgrade-to-v23) + +## Pre-upgrade action items + +- Deploy v2.3 protocol implementations +- Deploy fresh v2.3 Pyth oracle instance +- [Clean up v2.2 Checkpoint migration](#checkpoint-migration) + +### Checkpoint Migration + +If not otherwise complete, settle all accounts on all markets (with a fresh price), to trigger the post-v2.2 Checkpoint migration logic. + +see: https://github.com/equilibria-xyz/perennial-v2/pull/284. + +## Enter *settle only* mode, and settle all accounts on all markets / vaults + +Next we turn on the `settle` parameter to `true`. This pauses all new updates to the markets, while still allowing settlement. + +We must then go through and settle every single account that has an unsettled position present in each market. This can be batched via a multicall contract. + +This has multiple effects for the migration: + +### Version + +Version has a considerable amount of new fields. + +Each of these new fields is non-aggregating, i.e. is reset each version and only use to track things like position fees for the specified version. + +This is upgrade safe since the legacy aggregated fields are unchanged in their storage position, and the new fields are reset to zero upon preparing a new version. + +see: https://github.com/equilibria-xyz/perennial-v2/pull/291 + +### Oracle + +`IOracleProvider.at()` now has a new return type, returning a `OracleReceipt` in addition to the `OracleVersion`. + +To ensure that the first settlement after the switchover processes correctly, we must settle up the latest global version after entering settle only mode. + +see: https://github.com/equilibria-xyz/perennial-v2/pull/373. + +## Upgrade to v2.3 + +The upgrade to v2.3 must be processed atomically, similarly to the upgrade to v2.2: + +- Upgrade implementations to v2.3 +- [Run the global Position migration](#position-migration) +- [Update Risk / Market / Protocol Parameters to new format](#update-risk--market--protocol-parameters-to-new-format) +- [Update sub-oracles to v2.2-based oracles](#update-sub-oracles-to-v22-based-oracles-implementations) + +### Position Migration + +- Call `.migrate()` on each market to migrate the storage pattern of the global `Position` of each market. + +see: https://github.com/equilibria-xyz/perennial-v2/pull/424 + +### Update Risk / Market / Protocol Parameters to new format + +All parameter sets have a new format. Each needs to be updated for all markets. +- RiskParameter adds `minScale`, see: https://github.com/equilibria-xyz/perennial-v2/pull/362. +- VaultParameter adds `minDeposit`, see: https://github.com/equilibria-xyz/perennial-v2/pull/373. + +### Update sub-oracles to v2.3-based oracles implementations + +A new PythOracle implementation will be deployed with this release. A standard sub-oracle update is required on each market's oracle to transition to the new sub-oracles. + +see: + - https://github.com/equilibria-xyz/perennial-v2/pull/372 + - https://github.com/equilibria-xyz/perennial-v2/pull/379 + +## Post Upgrade Cleanup + +### Position Migration + +After posting a new price, each account on each market should be settled once. This ensures that each local Position has upgraded to the v1 storage layout, which allows us to remove this functionality in the next version. + +see: https://github.com/equilibria-xyz/perennial-v2/pull/424. \ No newline at end of file From 4e2e17ec46ec55c778d7465d9495b80f5bd06bba Mon Sep 17 00:00:00 2001 From: Kevin Britz Date: Wed, 28 Aug 2024 21:38:06 -0700 Subject: [PATCH 2/5] fix typo --- runbooks/MIGRATION_v2.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/runbooks/MIGRATION_v2.3.md b/runbooks/MIGRATION_v2.3.md index 751fa4eed..bcec42dbb 100644 --- a/runbooks/MIGRATION_v2.3.md +++ b/runbooks/MIGRATION_v2.3.md @@ -51,7 +51,7 @@ The upgrade to v2.3 must be processed atomically, similarly to the upgrade to v2 - Upgrade implementations to v2.3 - [Run the global Position migration](#position-migration) - [Update Risk / Market / Protocol Parameters to new format](#update-risk--market--protocol-parameters-to-new-format) -- [Update sub-oracles to v2.2-based oracles](#update-sub-oracles-to-v22-based-oracles-implementations) +- [Update sub-oracles to v2.3-based oracles](#update-sub-oracles-to-v23-based-oracles-implementations) ### Position Migration From 384e956dfe1ce8dbc2c3a49496ff00a68ef635af Mon Sep 17 00:00:00 2001 From: Kevin Britz Date: Wed, 4 Sep 2024 19:12:02 -0700 Subject: [PATCH 3/5] add more notes --- runbooks/MIGRATION_v2.3.md | 32 +++++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/runbooks/MIGRATION_v2.3.md b/runbooks/MIGRATION_v2.3.md index bcec42dbb..80274a04f 100644 --- a/runbooks/MIGRATION_v2.3.md +++ b/runbooks/MIGRATION_v2.3.md @@ -9,6 +9,8 @@ ## Pre-upgrade action items - Deploy v2.3 protocol implementations + - Including new GasOracle and Verifier externalized helper contracts +- Deploy MultiCall4 instance - Deploy fresh v2.3 Pyth oracle instance - [Clean up v2.2 Checkpoint migration](#checkpoint-migration) @@ -62,7 +64,22 @@ see: https://github.com/equilibria-xyz/perennial-v2/pull/424 ### Update Risk / Market / Protocol Parameters to new format All parameter sets have a new format. Each needs to be updated for all markets. -- RiskParameter adds `minScale`, see: https://github.com/equilibria-xyz/perennial-v2/pull/362. +- Oracle + - OracleParameter + - KeeperOracleParameter (per sub-oracle) +- Market + - ProtocolParameter + - RiskParameter (per market) + - MarketParameter (per market) +- Vault + - VaultParameter (per vault) + +Notable fields changes for reference: +- MarketParameter + - removes `.oracleFee` and `.settlementFee`, see: https://github.com/equilibria-xyz/perennial-v2/pull/373. + - replaces `.positionFee` with `.makerFee` and `.takerFee`, see: https://github.com/equilibria-xyz/perennial-v2/pull/291. +- RiskParameter removes `.makerFee.adiabaticFee`, see: https://github.com/equilibria-xyz/perennial-v2/pull/317. +- ProtocolParameter adds `minScale`, see: https://github.com/equilibria-xyz/perennial-v2/pull/362. - VaultParameter adds `minDeposit`, see: https://github.com/equilibria-xyz/perennial-v2/pull/373. ### Update sub-oracles to v2.3-based oracles implementations @@ -75,6 +92,19 @@ see: ## Post Upgrade Cleanup +### Instance Metadata + +We've added a few new metadata fields to the oracle system. These should be populated after the migration to aid with off-chain discovery, however are not required logically within the protocol. + +- `Oracle.updateName(string name)` +- `OracleFactory.updateId(IOracle Provider oracleProvider, bytes32 id)` + +New oracles deployed post-v2.3 will automatically include this information. + +see: + - https://github.com/equilibria-xyz/perennial-v2/pull/423 + - https://github.com/equilibria-xyz/perennial-v2/pull/339 + ### Position Migration After posting a new price, each account on each market should be settled once. This ensures that each local Position has upgraded to the v1 storage layout, which allows us to remove this functionality in the next version. From 419f6a8aa7368b7047d92f3b1c1341d4f9d603f5 Mon Sep 17 00:00:00 2001 From: Kevin Britz Date: Thu, 5 Sep 2024 22:28:17 -0700 Subject: [PATCH 4/5] add Oracle.register() note --- runbooks/MIGRATION_v2.3.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/runbooks/MIGRATION_v2.3.md b/runbooks/MIGRATION_v2.3.md index 80274a04f..3dbce023c 100644 --- a/runbooks/MIGRATION_v2.3.md +++ b/runbooks/MIGRATION_v2.3.md @@ -86,6 +86,8 @@ Notable fields changes for reference: A new PythOracle implementation will be deployed with this release. A standard sub-oracle update is required on each market's oracle to transition to the new sub-oracles. +Must also register each market with its oracle via `Oracle.register(market)`. This step must be done whenever launching a new oracle going forward as well. + see: - https://github.com/equilibria-xyz/perennial-v2/pull/372 - https://github.com/equilibria-xyz/perennial-v2/pull/379 From 183c31be270ecfec59f20bf0041a020ef0f881f6 Mon Sep 17 00:00:00 2001 From: Kevin Britz Date: Wed, 16 Oct 2024 23:44:02 -0700 Subject: [PATCH 5/5] address comments --- runbooks/MIGRATION_v2.3.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/runbooks/MIGRATION_v2.3.md b/runbooks/MIGRATION_v2.3.md index 3dbce023c..676c5d64f 100644 --- a/runbooks/MIGRATION_v2.3.md +++ b/runbooks/MIGRATION_v2.3.md @@ -66,7 +66,7 @@ see: https://github.com/equilibria-xyz/perennial-v2/pull/424 All parameter sets have a new format. Each needs to be updated for all markets. - Oracle - OracleParameter - - KeeperOracleParameter (per sub-oracle) + - KeeperOracleParameter - Market - ProtocolParameter - RiskParameter (per market) @@ -84,7 +84,7 @@ Notable fields changes for reference: ### Update sub-oracles to v2.3-based oracles implementations -A new PythOracle implementation will be deployed with this release. A standard sub-oracle update is required on each market's oracle to transition to the new sub-oracles. +New PythFactory and CryptexFactory implementations will be deployed with this release. A standard sub-oracle update is required on each market's oracle to transition to the new sub-oracles. Must also register each market with its oracle via `Oracle.register(market)`. This step must be done whenever launching a new oracle going forward as well.