diff --git a/app/consumer/genesis.go b/app/consumer/genesis.go index 024ff9785e..eaa4676344 100644 --- a/app/consumer/genesis.go +++ b/app/consumer/genesis.go @@ -5,8 +5,6 @@ import ( "fmt" "os" "path/filepath" - "sort" - "strings" "github.com/spf13/cobra" @@ -28,19 +26,10 @@ import ( // object provided to it during init. type GenesisState map[string]json.RawMessage -type ( - // Transformation callback for a consumer genesis 'section' exported from a - // specific version of a provider - TransformationCallback func([]byte, client.Context) (json.RawMessage, error) - - // TransformationMap defines the mapping from a version to a transformation callback - TransformationMap map[string]TransformationCallback -) - -// Migration of consumer genesis content as it is exported from a provider version v2 -// (ICS provider module version) to a format readable by current consumer implementation. -func migrateFromV2(jsonRaw []byte, ctx client.Context) (json.RawMessage, error) { - // v2 uses deprecated fields of GenesisState type +// Migration of consumer genesis content as it is exported from a provider version v1,2,3 +// to a format readable by current consumer implementation. +func transform(jsonRaw []byte, ctx client.Context) (json.RawMessage, error) { + // v1,2,3 uses deprecated fields of GenesisState type oldConsumerGenesis := consumerTypes.GenesisState{} err := ctx.Codec.UnmarshalJSON(jsonRaw, &oldConsumerGenesis) if err != nil { @@ -78,28 +67,17 @@ func migrateFromV2(jsonRaw []byte, ctx client.Context) (json.RawMessage, error) return newJson, nil } -// Mapping of provider module version to related transformation function -var transformationMap = TransformationMap{ - "v2": migrateFromV2, -} - // Transform a consumer genesis json file exported from a given ccv provider version // to a consumer genesis json format supported by current ccv consumer version. // Result will be written to defined output. -func TransformConsumerGenesis(cmd *cobra.Command, args []string, transformationMap TransformationMap) error { - sourceVersion := args[0] - sourceFile := args[1] +func TransformConsumerGenesis(cmd *cobra.Command, args []string) error { + sourceFile := args[0] jsonRaw, err := os.ReadFile(filepath.Clean(sourceFile)) if err != nil { return err } - transform, exists := transformationMap[sourceVersion] - if !exists { - return fmt.Errorf("error transforming consumer genesis content: Unsupported versions %s", sourceVersion) - } - clientCtx := client.GetClientContextFromCmd(cmd) newConsumerGenesis, err := transform(jsonRaw, clientCtx) if err != nil { @@ -120,36 +98,24 @@ func TransformConsumerGenesis(cmd *cobra.Command, args []string, transformationM return nil } -// List of provider versions supported by consumer genesis transformations -func getSupportedTransformationVersions() []string { - var keys []string - for k := range transformationMap { - keys = append(keys, k) - } - sort.Strings(keys) - return keys -} - // NewDefaultGenesisState generates the default state for the application. func NewDefaultGenesisState(cdc codec.JSONCodec) GenesisState { return ModuleBasics.DefaultGenesis(cdc) } -// GetConsumerGenesisTransformCmd transforms Consumer Genesis JSON content exported from a specific -// provider version to a JSON format supported by this consumer version. -// Note: Provider module version can be received by querying 'module_versions' on the 'upgrade' module. +// GetConsumerGenesisTransformCmd transforms Consumer Genesis JSON content exported from a +// provider version v1,v2 or v3 to a JSON format supported by this consumer version. func GetConsumerGenesisTransformCmd() *cobra.Command { cmd := &cobra.Command{ - Use: "transform [source-version] [genesis-file]", - Short: "Transform CCV consumer genesis from a specified provider version", - Long: fmt.Sprintf(`Transform the consumer genesis file from a specified provider version to a version supported by this consumer. Result is printed to STDOUT. -Supported provider versions: %s + Use: "transform [genesis-file]", + Short: "Transform CCV consumer genesis from an older provider version not supporting current format", + Long: fmt.Sprintf(`Transform the consumer genesis file from a provider version v1,v2 or v3 to a version supported by this consumer. Result is printed to STDOUT. Example: -$ %s transform v2 /path/to/consumer_genesis.json `, strings.Join(getSupportedTransformationVersions(), ", "), version.AppName), - Args: cobra.ExactArgs(2), +$ %s transform /path/to/ccv_consumer_genesis.json `, version.AppName), + Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { - return TransformConsumerGenesis(cmd, args, transformationMap) + return TransformConsumerGenesis(cmd, args) }, } diff --git a/app/consumer/genesis_test.go b/app/consumer/genesis_test.go index ae023cee8d..f23e4c58d1 100644 --- a/app/consumer/genesis_test.go +++ b/app/consumer/genesis_test.go @@ -183,7 +183,7 @@ func TestConsumerGenesisTransformationV2(t *testing.T) { cmd, err := getGenesisTransformCmd() require.NoError(t, err, "Error setting up transformation command: %s", err) - cmd.SetArgs([]string{version, filePath}) + cmd.SetArgs([]string{filePath}) output := new(bytes.Buffer) cmd.SetOutput(output) diff --git a/docs/docs/consumer-development/changeover-procedure.md b/docs/docs/consumer-development/changeover-procedure.md index 825a0bdae4..446f91775b 100644 --- a/docs/docs/consumer-development/changeover-procedure.md +++ b/docs/docs/consumer-development/changeover-procedure.md @@ -48,7 +48,7 @@ RevisionNumber: 0, RevisionHeight: 111 * `spawn_time` listed in the proposal MUST be before the `upgrade_height` listed in the the upgrade proposal on the standalone chain. :::caution -`spawn_time` must occur before the `upgrade_height` on the standalone chain is reached becasue the `provider` chain must generate the `ConsumerGenesis` that contains the **validator set** that will be used after the changeover. +`spawn_time` must occur before the `upgrade_height` on the standalone chain is reached because the `provider` chain must generate the `ConsumerGenesis` that contains the **validator set** that will be used after the changeover. ::: * `unbonding_period` must correspond to the value used on the standalone chain. Otherwise, the clients used for the ccv protocol may be incorrectly initialized. @@ -128,7 +128,7 @@ To help validators and other node runners onboard onto your chain, please prepar This should include (at minimum): -- [ ] genesis.json with CCV data (after spawn time passes) +- [ ] genesis.json with CCV data (after spawn time passes). Check if CCV data needs to be transformed (see [Transform Consumer Genesis](./consumer-genesis-transformation.md)) - [ ] information about relevant seed/peer nodes you are running - [ ] relayer information (compatible versions) - [ ] copy of your governance proposal (as JSON) diff --git a/docs/docs/consumer-development/consumer-genesis-transformation.md b/docs/docs/consumer-development/consumer-genesis-transformation.md new file mode 100644 index 0000000000..b6d892988d --- /dev/null +++ b/docs/docs/consumer-development/consumer-genesis-transformation.md @@ -0,0 +1,29 @@ +--- +sidebar_position: 6 +--- + +# Consumer Genesis Transformation + +Preparing a consumer chain for onboarding requires some information explaining how to run your chain. This includes a genesis file with CCV data where the CCV data is exported from the provider chain and added to the consumers genesis file (for more details check the documentaion on [Onboarding](./onboarding.md) and [Changeover](./changeover-procedure.md)). +In case that the provider chain is running an older version of the InterChainSecurity (ICS) module than the consumer chain the exported CCV data might need to be transformed to the format supported by the ICS implementation run on the consumer chain. This is the case if the cosumer chain runs consensus version 4 of ICS or later and the provider is running consensus version 3 or older of the ICS module. + +To transform such CCV data follow the instructions below + +## 1. Prerequisite +- Provider chain is running consensus version 3 or older of the ICS provider module +- Consumer is running consensus version 4 or later of the ICS consumer module. +- interchain-security-cd application complies to the version run on the consumer chain + +## 2. Export the CCV data +Export the CCV data from the provider chain as descibed in the [Onboarding](./onboarding.md) and [Changeover](./changeover-procedure.md)) your following. +As a result the CCV data will be stored in a file in JSON format. + +## 3. Transform CCV data +To transform the CCV data to the newer format run the following command. +``` +interchain-security-cd genesis transform [genesis-file] +``` +where 'genesis-file' is the path to the file containing the CCV data exported in [step 2](#2-export-the-ccv-data). +As a result the CCV data in the new format will be written to standard output. + +Use the new CCV data as described in the procedure you're following. \ No newline at end of file diff --git a/docs/docs/consumer-development/onboarding.md b/docs/docs/consumer-development/onboarding.md index c9b503ed66..893af0a3b1 100644 --- a/docs/docs/consumer-development/onboarding.md +++ b/docs/docs/consumer-development/onboarding.md @@ -21,7 +21,7 @@ To help validators and other node runners onboard onto your chain, please prepar This should include (at minimum): - [ ] genesis.json without CCV data (before the proposal passes) -- [ ] genesis.json with CCV data (after spawn time passes) +- [ ] genesis.json with CCV data (after spawn time passes). Check if CCV data needs to be transformed (see [Transform Consumer Genesis](./consumer-genesis-transformation.md)) - [ ] information about relevant seed/peer nodes you are running - [ ] relayer information (compatible versions) - [ ] copy of your governance proposal (as JSON)