From 5071e56d9777cd1b244f586123d7d20637272ce2 Mon Sep 17 00:00:00 2001 From: Nikolaos Dymitriadis Date: Tue, 10 Dec 2024 14:05:42 +0100 Subject: [PATCH 1/6] correct file name Signed-off-by: Nikolaos Dymitriadis --- docs/developer-guides/migration-guide-1.4.0.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/developer-guides/migration-guide-1.4.0.md b/docs/developer-guides/migration-guide-1.4.0.md index ef8645b67..2e0c688f6 100644 --- a/docs/developer-guides/migration-guide-1.4.0.md +++ b/docs/developer-guides/migration-guide-1.4.0.md @@ -103,7 +103,7 @@ After this step the SPO should be ready to be included in post-migration committ *Important:* * the `chain-spec.json` file is only used for registrations and should **not** be used to run the nodes. The SPOs should discard it after this section. -* The register commands require the `partner-chains-cli-keys.json` file to be present in the run directory. If the SPO +* The register commands require the `partner-chains-public-keys.json` file to be present in the run directory. If the SPO used `partner-chains-cli` for the previous registration, they should re-use the file generated then. If the SPO no longer has the file, it can be manually created based on the following schema: ```json From 41803df8b81f18824a3de8c945abd39abbe2829b Mon Sep 17 00:00:00 2001 From: Nikolaos Dymitriadis Date: Tue, 10 Dec 2024 14:12:24 +0100 Subject: [PATCH 2/6] mention the keystore for registrations Signed-off-by: Nikolaos Dymitriadis --- docs/developer-guides/migration-guide-1.4.0.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/developer-guides/migration-guide-1.4.0.md b/docs/developer-guides/migration-guide-1.4.0.md index 2e0c688f6..4799b502c 100644 --- a/docs/developer-guides/migration-guide-1.4.0.md +++ b/docs/developer-guides/migration-guide-1.4.0.md @@ -103,16 +103,10 @@ After this step the SPO should be ready to be included in post-migration committ *Important:* * the `chain-spec.json` file is only used for registrations and should **not** be used to run the nodes. The SPOs should discard it after this section. -* The register commands require the `partner-chains-public-keys.json` file to be present in the run directory. If the SPO -used `partner-chains-cli` for the previous registration, they should re-use the file generated then. -If the SPO no longer has the file, it can be manually created based on the following schema: -```json -{ - "sidechain_pub_key": "", - "aura_pub_key": "", - "grandpa_pub_key": "" -} -``` +* For the register commands to be run correctly, the `partner-chains-public-keys.json` file needs to be present +in the run directory and the base path configured in `partner-chains-cli-resources.json` should point to a valid +directory containing the keystore with the private keys. +If the SPO used `partner-chains-cli` for the previous registration, they should re-use the keys generated then. New SPOs should run the `generate-keys` command instead. ### Upgrade the runtime to v1.4.0 From 5e379d626ec51d9fe8cea0c93cbd9bc9708c6efc Mon Sep 17 00:00:00 2001 From: Nikolaos Dymitriadis Date: Tue, 10 Dec 2024 14:17:48 +0100 Subject: [PATCH 3/6] add notices Signed-off-by: Nikolaos Dymitriadis --- docs/developer-guides/migration-guide-1.4.0.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/developer-guides/migration-guide-1.4.0.md b/docs/developer-guides/migration-guide-1.4.0.md index 4799b502c..a85e17336 100644 --- a/docs/developer-guides/migration-guide-1.4.0.md +++ b/docs/developer-guides/migration-guide-1.4.0.md @@ -1,5 +1,11 @@ # v1.4.0 Migration guide +**Important:** +- Please read the whole document before attempting to perform any actions. +- Whenever the guide requires running the `partner-chains-cli` binary, make sure the `pc-contracts-cli` +of the version specified in the compatibility matrix is present in your active directory. In case of the +1.4.0 release it should be v7.0.1. + ## Context This guide describes the process of migrating from Partner Chains SDK v1.3.0 to v1.4.0 for an already From ac1ee234217791e8422507e55a4360eff6a1c50e Mon Sep 17 00:00:00 2001 From: Nikolaos Dymitriadis Date: Tue, 10 Dec 2024 16:00:21 +0100 Subject: [PATCH 4/6] add big picture descripton Signed-off-by: Nikolaos Dymitriadis --- docs/developer-guides/migration-guide-1.4.0.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/developer-guides/migration-guide-1.4.0.md b/docs/developer-guides/migration-guide-1.4.0.md index a85e17336..ee6cf463f 100644 --- a/docs/developer-guides/migration-guide-1.4.0.md +++ b/docs/developer-guides/migration-guide-1.4.0.md @@ -17,6 +17,17 @@ version v7.0.1, which: - removes "sidechain params" as part of the definition of a Partner Chain, replacing them with the genesis utxo (which is the utxo burned when establishing a governance) +## Overview of the migration + +The migration requires multiple detailed steps but to follow them successfuly it's good to understand the big picture first: +The 1.4.0 version introduces some backwards-incompatible data schemas. This means that a simple runtime upgrade +using `system/setCode` extrinsic would leave the chain in an inconsistent state and unable to produce blocks. +To avoid this issue, the migration involves the following general steps: +1. Upgrade to a transitory version of the runtime 1.3.1, which only introduces a special helper extrinsic `upgrade_and_set_addresses`. +2. Establish a brand new Partner Chain on Cardano using the new 1.4.0 version. +3. Use the `upgrade_and_set_addresses` to atomically upgrade the runtime to version 1.4.0 and switch the addresses +observed for committee selection to the new Partner Chain. + ## Migration Steps ### Prerequisites From e28ecf6a7299605df2d4be7c27793426736da122 Mon Sep 17 00:00:00 2001 From: Nikolaos Dymitriadis Date: Tue, 10 Dec 2024 16:00:51 +0100 Subject: [PATCH 5/6] build chain spec after adding permissioned candidates Signed-off-by: Nikolaos Dymitriadis --- docs/developer-guides/migration-guide-1.4.0.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/developer-guides/migration-guide-1.4.0.md b/docs/developer-guides/migration-guide-1.4.0.md index ee6cf463f..733f41f86 100644 --- a/docs/developer-guides/migration-guide-1.4.0.md +++ b/docs/developer-guides/migration-guide-1.4.0.md @@ -97,12 +97,12 @@ The address associated with the keys should have enough ADA to cover transaction 2. Run the `prepare-configuration` command of `partner-chains-cli` (v1.4.0) in a fresh directory. This step will involve selecting the _genesis UTXO_ to be spent intializing the governance mechanism. Save the `partner-chains-cli-chain-config.json` file produced by this step. -3. Run the `create-chain-spec` command of `partner-chains-cli`. Save the `chain-spec.json` file produced by this step. -4. Add the permissioned candidates in the `partner-chains-cli-chain-config.json` file. These can be copied from the chain config file +3. Add the permissioned candidates in the `partner-chains-cli-chain-config.json` file. These can be copied from the chain config file used when setting up the Partner Chain previously, or obtained by querying the `sidechain_getAriadneParameters` jsonRPC method: ```sh curl "" -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "id":0, "method":"sidechain_getAriadneParameters","params":[] }' | jq '.result.permissionedCandidates' ``` +4. Run the `create-chain-spec` command of `partner-chains-cli`. Save the `chain-spec.json` file produced by this step. 5. Run the `setup-main-chain-state` command of `partner-chains-cli`, setting up the D-param and permissioned candidates. After these steps, the new Partner Chain will be initialized on Cardano. From a2c1512dab90132683cd939434c4b0d472ac72bd Mon Sep 17 00:00:00 2001 From: Nikolaos Dymitriadis Date: Tue, 10 Dec 2024 18:30:41 +0100 Subject: [PATCH 6/6] prefix extrinsic with pallet --- docs/developer-guides/migration-guide-1.4.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/developer-guides/migration-guide-1.4.0.md b/docs/developer-guides/migration-guide-1.4.0.md index 733f41f86..70f598861 100644 --- a/docs/developer-guides/migration-guide-1.4.0.md +++ b/docs/developer-guides/migration-guide-1.4.0.md @@ -23,9 +23,9 @@ The migration requires multiple detailed steps but to follow them successfuly it The 1.4.0 version introduces some backwards-incompatible data schemas. This means that a simple runtime upgrade using `system/setCode` extrinsic would leave the chain in an inconsistent state and unable to produce blocks. To avoid this issue, the migration involves the following general steps: -1. Upgrade to a transitory version of the runtime 1.3.1, which only introduces a special helper extrinsic `upgrade_and_set_addresses`. +1. Upgrade to a transitory version of the runtime 1.3.1, which only introduces a special helper extrinsic `sidechain/upgrade_and_set_addresses`. 2. Establish a brand new Partner Chain on Cardano using the new 1.4.0 version. -3. Use the `upgrade_and_set_addresses` to atomically upgrade the runtime to version 1.4.0 and switch the addresses +3. Use the `sidechain/upgrade_and_set_addresses` to atomically upgrade the runtime to version 1.4.0 and switch the addresses observed for committee selection to the new Partner Chain. ## Migration Steps @@ -39,7 +39,7 @@ and observing configuration and registrations created using smart contracts of v ### Runtime upgrade to v1.3.1 -This patch version extends the Sidechain pallet with a new extrinsic `upgrade_and_set_addresses` +This patch version extends the Sidechain pallet with a new extrinsic `sidechain/upgrade_and_set_addresses` which allows the on-chain governance to atomically upgrade the runtime and set the genesis utxo and new main chain scripts to observe. @@ -55,7 +55,7 @@ impl pallet_sidechain::Config for Runtime { } } ``` -This will allow the `upgrade_and_set_addresses` extrinsic to update configuration of the SessionValidatorManagement +This will allow the `sidechain/upgrade_and_set_addresses` extrinsic to update configuration of the SessionValidatorManagement pallet together with the Runtime code. 3. Increment the `spec_version` in your runtime configuration. 4. Build the new Runtime WASM (you can do it by running `cargo build --release`)