polkadot-omni-node: para_id key from generated chain specs is deprecated

[iulianbarbu]

This: paritytech/polkadot-sdk#8651 introduces a new way of specifying the parachain id to nodes. Runtimes will need to implement a new runtime API called cumulus_primitives_core::GetParachainInfo, and we must give a basic guide for how to do it. It should reference a few things:

• a guide for runtime upgrades (I hope there is one - if there isn't, it might be the case to do it)
• a small section where we reference the runtime upgrade docs and parachain-template-runtime, or more specifically where we implemented the new trait (after merging the linked PR I'll follow here with a commit SHA based link).
• linking back the new docs & updated public docs in polkadot-sdk codebase where para_id key shows as deprecated, as an alternative to it.

We already have some public docs for how to update the parachain id in the generated chain specs here: https://docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/deploy-to-testnet/#generate-the-chain-specification. This will not be relevant anymore.

cc @nkpar

[iulianbarbu]

There is a page for runtime upgrades, but not an example/guide: https://docs.polkadot.com/develop/parachains/maintenance/runtime-upgrades/. Maybe there is a guide though and I miss it?

[nhussein11]

@iulianbarbu @nkpar, thank you for bringing this up! Yes, you are right, there is currently no tutorial for performing runtime upgrades; we only have the guide you mentioned here - https://docs.polkadot.com/develop/parachains/maintenance/runtime-upgrades/.

So, I will create a new page in the zero-to-hero tutorials to show how to perform a runtime upgrade (following the context of the previous tutorials, set up a template, build a custom pallet, pallet unit testing, etc). What’s unclear to me is this part:.

more specifically where we implemented the new trait

I was thinking of adding a new call or an additional extrinsic (like reset counter()) to the custom pallet created in previous tutorials. Do you suggest also including the API cumulus_primitives_core::GetParachainIdentity as part of the same runtime upgrade to show that the para-id parameter is no longer required for further actions? I'm concerned about straying slightly from the tutorial's focus.

[iulianbarbu]

Hey @nhussein11 ! Just to double check I am getting you right:

I was thinking of adding a new call or an additional extrinsic (like reset counter()) to the custom pallet created in previous tutorials.

Is this like something that precedes and suggests to a runtime upgrade? If yes, I think this is a good way to introduce the runtime upgrade.

Do you suggest also including the API cumulus_primitives_core::GetParachainIdentity as part of the same runtime upgrade to show that the para-id parameter is no longer required for further actions? I'm concerned about straying slightly from the tutorial's focus.

TLDR, I wouldn't reference the new trait in the runtime upgrade tutorial, but please read the rest of my comment for more context.

When it comes to the trait, please note that we merged it with the name GetParachainInfo. What I would do is to mention about the trait here: docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/deploy-to-testnet/#generate-the-chain-specification. What we can say is that the para_id field from JSON chainspecs, added via chain-spec-builder command, is currently read by nodes for configuration purposes. Starting with stable2509 the para_id field is not required anymore, but runtimes will need to upgrade to a new version that implements the cumulus_primitives_core::GetParachainInfo trait to be able to successfully be started with nodes that use chain specs without para_id field. And then, with 2512, para_id field support is removed in favor of the newly added runtime API, so new nodes will not be able to start chain specs that still contains it, with runtimes that don't implement the trait.

What would've been ideal here is to link a code sample with how to implement the new trait, but also a link to how a regular runtime upgrade is done. Currently all parachains must use the ParachainInfo pallet, which is used by most of the new trait implementations to get the para_id number and return it. So I was thinking here to also have some docs about what is mandatory for parachain runtimes to have in terms of pallets and runtime APIs to be successfully registered on a relay chain, for certain functionality (we should keep it minimal). If it comes to a full list of pallets, I am not sure if I have it, but I am confident the parachain runtimes must have parachain_info & parachain_system at least. Probably others too (we can look for this info offline). For runtime APIs I know about one - the newly added trait. Which other runtime API is mandatory is not very clear to me yet, maybe we can make an effort to clear that out if you're not very familiar either.

Hope this gives more context about the necessary docs update. Let me know if something is not clear, if you'd need help with suggested updates, and please propose anything if you know how to simplify things.

[nhussein11]

Hi @iulianbarbu,

Thanks so much for the detailed explanation.

Is this like something that precedes and suggests to a runtime upgrade? If yes, I think this is a good way to introduce the runtime upgrade.

Yes, I've already used the reset_counter() example to introduce runtime upgrades in [Add] - runtime upgrade tutorial #760. We can definitely use this tutorial for future references.

When it comes to the trait, please note that we merged it with the name GetParachainInfo. What I would do is to mention about the trait here: docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/deploy-to-testnet/#generate-the-chain-specification.

Okay, I understand now, thank you! I agree that docs.polkadot.com/tutorials/polkadot-sdk/parachains/zero-to-hero/deploy-to-testnet/#generate-the-chain-specification would be the best location for this explanation. For now, I can add a note there with the considerations you've outlined and link to the recently created runtime upgrade page. This will help make developers aware of this newly introduced trait.

So I was thinking here to also have some docs about what is mandatory for parachain runtimes to have in terms of pallets and runtime APIs to be successfully registered on a relay chain, for certain functionality (we should keep it minimal)

I really like the idea of creating a dedicated page or guide for parachain developers that explains these essential components. We can certainly create a page detailing the minimum specifications for parachain components and provide explanations for each. We could also showcase how the cumulus_primitives_core::GetParachainInfo trait can be implemented and integrated via a runtime upgrade on this new page. We can link the note I'll create to this page once it's ready, so everything is aligned and properly linked.

I believe we should aim to have this page ready once 2509 is live. However, I'd suggest opening a new ticket specifically for creating this page. This will help us stay organized and avoid deviating too much from the original issue you created.