When there is a new Chain Spec version how do we know where to add things?

Question

We're updating our relay chain test and its time to create a chain spec.

When i generate a plain chain spec (from polkadot repo) it seems i still get some raw output:

./target/release/polkadot build-spec > new-spec.json

I get a structure i am not familiar with, something called codeSubstitutes, where it seems the wasm blob goes. but in genesis > raw > top, where the wasm used to go is now encoded data plus wasm wedged in between it.

In a plain spec file i do not want encoded data.

"codeSubstitutes": {
    "5203203": "0x0061736d01000000...
  }
"genesis": {
    "raw": {
      "top": {
        "0x0b76934f4cc08dee01012d059e1b83ee5e0621c4869aa60c02be9adcc98a0d1d": "0x1856f0bb1f6307...

When i try to add validators and balances to the new chain spec I am not sure where it should be put. I append it to the end after "childrenDefault": {}, but i get this error:

Error: 
   0: Other: Error parsing spec file: unknown field `babe`, expected `top` or `childrenDefault` at line 11677 column 12

The docs on substrate don't tell me where to add things like this:

"babe": {
          "authorities": [],
          "epochConfig": {
            "c": [
              1,
              4
            ],
            "allowed_slots": "PrimaryAndSecondaryVRFSlots"
          }
        },
        "indices": {
          "indices": []
        },
        "balances": {
          "balances": [
            [
              "5D7DGQNjk5gAwatPSMf555VB1W8UCq1sQomHX2eRwiLqhc4t",
              1000000000000000000
            ],
            [
              "5CdEXeeTzGDxgtMtXPTte71ManNn39QmFCSxCTzsqdwdejrs",
              100000000000000
            ],
            [
              "5H6bg61yQzQBXcnuBbDzX4Nue5mJgGqhPj9HDJ8Kg5nn9Jem",
              100000000000000
            ],
            [
              "5CQ7S9CMzpqft1zEk6fr5uzxLhsc7zhNScvVa3YiGmmoSSVg",
              100000000000000
            ]
          ]
        },
        "transactionPayment": null,
        "session": {
          "keys": [
            [
              "5CdEXeeTzGDxgtMtXPTte71ManNn39QmFCSxCTzsqdwdejrs",
              "5CdEXeeTzGDxgtMtXPTte71ManNn39QmFCSxCTzsqdwdejrs",
              {
                "grandpa": "5GboBX4hqNVopiBQVsXWAw3SzD5dpKxqjK3iDA38GPxJEi6w",
                "babe": "5HTALD3kTwmDHNKEKxsquepU56Quzq59xKGmhksekpcF3C5T",
                "im_online": "5ELHgNfi7bXWmmoyjdmBnY3B2MPBXgyAesdRkpC4Kgwm5ZUd",
                "para_validator": "5GxMs7yfgUtsG8zqU2412HAihc8NZ1jtMX69z6sdnSQKPwY2",
                "para_assignment": "5Dqxxx4CbppCEuMFqiHNNVXNGBptsG1PJyDW7kv7GTmPQQGR",
                "authority_discovery": "5DksLz7S316tdyDg554mhCCYmBhkYbR7XQnWHtft3Kowatat",
                "beefy": "KWBh8XBfoyenpdXN5qY1deY6tpkN2Hvw4skhERZRi2neimHBR"
              }
            ],
            [
              "5H6bg61yQzQBXcnuBbDzX4Nue5mJgGqhPj9HDJ8Kg5nn9Jem",
              "5H6bg61yQzQBXcnuBbDzX4Nue5mJgGqhPj9HDJ8Kg5nn9Jem",
              {
                "grandpa": "5FUibppET3z3SRqbfgGAzMTRUgBcdVzWw2Kv9pCsQLd6qsp8",
                "babe": "5CcLtfQuroSgXRYgcVacAAopnF8gN1PrJEGdqxTgh9ZvUzHK",
                "im_online": "5HpSZnVXxhFpfVdBRxxnPgg4okeMKEHyxR7c2zU5TcTJZiq8",
                "para_validator": "5HjAJp37Bjamrnc1vsGGG2aqWDh7osgszzc9Eb7NP3S7GPEa",
                "para_assignment": "5Cu9mwCPHm6uybwLJy4zQFTH5TjTLBu37uUgaUogWqZjpv4e",
                "authority_discovery": "5D5VTDy2mwbC51yuco6SsafSjxqqz3SrtakDr2T23Lavhh6p",
                "beefy": "KW3FkcrJAy6Z5ysiRQupzvP4dcwfSnJCBwjtGsSsgcBwhapCv"
              }
            ],
            [
              "5CQ7S9CMzpqft1zEk6fr5uzxLhsc7zhNScvVa3YiGmmoSSVg",
              "5CQ7S9CMzpqft1zEk6fr5uzxLhsc7zhNScvVa3YiGmmoSSVg",
              {
                "grandpa": "5EX7Uw8VbNgDtdEbTa3rGVkR7VsGcPoFpFfPYs4iexyKVw72",
                "babe": "5Gekpirt85FG8J3eaZGyCbx8CT64oPrTPXCXmUqAU1tvrb1U",
                "im_online": "5FLZ8nsw6v1tKQ4dAfbMX5z6cH33m4iVBmKiABR5uRx1x1Ay",
                "para_validator": "5Gmub5hEKcrmS53QE2Ls6afE7YhsFQTepPUqhF9vFipkterU",
                "para_assignment": "5Hg2T4obKFrXyrCvtdpVSMT7Fru7VSBTdtKEDXFXQaXUHXk9",
                "authority_discovery": "5CcgDBN7sWqf5bq3AnVXffAX2rCApivCPGc4imRmB6Da3gyX",
                "beefy": "KWDc8ncrJx3NtMFeKxNMGpqU1FrnJTR2Yf1aqFdxNRP2ihJex"
              }
            ]
          ]
        },
        "grandpa": {
          "authorities": []
        },
        "imOnline": {
          "keys": []
        },
        "authorityDiscovery": {
          "keys": []
        },
        "configuration": {
          "config": {
            "max_code_size": 3145728,
            "max_head_data_size": 32768,
            "max_upward_queue_count": 8,
            "max_upward_queue_size": 1048576,
            "max_upward_message_size": 1048576,
            "max_upward_message_num_per_candidate": 5,
            "hrmp_max_message_num_per_candidate": 5,
            "validation_upgrade_cooldown": 2,
            "validation_upgrade_delay": 2,
            "max_pov_size": 5242880,
            "max_downward_message_size": 1048576,
            "ump_service_total_weight": 100000000000,
            "hrmp_max_parachain_outbound_channels": 4,
            "hrmp_max_parathread_outbound_channels": 4,
            "hrmp_sender_deposit": 0,
            "hrmp_recipient_deposit": 0,
            "hrmp_channel_max_capacity": 8,
            "hrmp_channel_max_total_size": 8192,
            "hrmp_max_parachain_inbound_channels": 4,
            "hrmp_max_parathread_inbound_channels": 4,
            "hrmp_channel_max_message_size": 1048576,
            "code_retention_period": 1200,
            "parathread_cores": 0,
            "parathread_retries": 0,
            "group_rotation_frequency": 20,
            "chain_availability_period": 4,
            "thread_availability_period": 4,
            "scheduling_lookahead": 0,
            "max_validators_per_core": null,
            "max_validators": null,
            "dispute_period": 6,
            "dispute_post_conclusion_acceptance_period": 100,
            "dispute_max_spam_slots": 2,
            "dispute_conclusion_by_time_out_period": 200,
            "no_show_slots": 2,
            "n_delay_tranches": 25,
            "zeroth_delay_tranche_width": 0,
            "needed_approvals": 2,
            "relay_vrf_modulo_samples": 2,
            "ump_max_individual_weight": 20000000000,
            "pvf_checking_enabled": false,
            "pvf_voting_ttl": 2,
            "minimum_validation_upgrade_delay": 5
          }
        },
        "paras": {
          "paras": []
        },
        "hrmp": {
          "preopenHrmpChannels": []
        },
        "registrar": {
          "nextFreeParaId": 2000
        },
        "sudo": {
          "key": "5D7DGQNjk5gAwatPSMf555VB1W8UCq1sQomHX2eRwiLqhc4t"
        },
        "beefy": {
          "authorities": []
        },
        "bridgeRococoGrandpa": {
          "owner": "5D7DGQNjk5gAwatPSMf555VB1W8UCq1sQomHX2eRwiLqhc4t",
          "initData": null
        },
        "bridgeWococoGrandpa": {
          "owner": "5D7DGQNjk5gAwatPSMf555VB1W8UCq1sQomHX2eRwiLqhc4t",
          "initData": null
        },
        "bridgeRococoMessages": {
          "operatingMode": "Normal",
          "owner": "5D7DGQNjk5gAwatPSMf555VB1W8UCq1sQomHX2eRwiLqhc4t",
          "phantom": null
        },
        "bridgeWococoMessages": {
          "operatingMode": "Normal",
          "owner": "5D7DGQNjk5gAwatPSMf555VB1W8UCq1sQomHX2eRwiLqhc4t",
          "phantom": null
        },
        "collective": {
          "phantom": null,
          "members": []
        },
        "membership": {
          "members": [],
          "phantom": null
        },
        "xcmPallet": {
          "safeXcmVersion": 2
        }
      },
      "session_length_in_blocks": null

Where can i find how to structure a plain chain spec?

Answer 1

There are two types of chain spec: "raw" and "human readable". Where the difference between both is that genesis entry is either hex key and values or a json that contains the runtime pallets. You want to have the human readable version to add validator etc to experiment.

Your problem is that you take a raw chain spec and export this into a new chain spec. A raw chain spec can only be converted into a raw chain spec and not into the human readable one. You used the polkadot mainnet chain spec to start with.

The solution to your problem is to use a chain spec that is "present" as human readable or better can be converted into this. This would be for example poladot-dev, kusama-dev, etc. So, you need to use the following command:

polkadot build-spec --chain "polkadot-dev" > new-spec.json

To your question on what code-substitutes are: When there is a bug in the on chain wasm file, a code substitute can be used to replace the this on chain wasm file. The format is block_number: wasm_file, where block number is the first block number from where the wasm file should be replaced on chain.