Refactor and improve Technical Reference > Parachain > Consensus > Assets & Smart Contracts

[kapetan3sid]

This PR introduces two new pages in the Technical Reference section:

• Assets – Explains how to work with assets on Asset Hub, including native assets, foreign assets, and asset management using the Assets pallet.
• Smart Contracts – Describes smart contract deployment options on Asset Hub and outlines the technical differences between PolkaVM and REVM.

[Copilot]

Pull Request Overview

This PR splits the existing "Assets and Smart Contracts" page into two dedicated pages—Assets and Smart Contracts—in the Technical Reference section. The refactoring improves content organization by separating asset management concepts from smart contract deployment options on Asset Hub.

Key changes:

• Creates dedicated assets.md page covering Asset Hub's asset management features, pallets, and XCM integration
• Introduces smart-contracts.md page explaining PolkaVM and REVM contract deployment options
• Updates navigation files to reflect the new structure

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
reference/polkadot-hub/smart-contracts.md	New page documenting smart contract options (PolkaVM and REVM) on Asset Hub
reference/polkadot-hub/assets.md	New page covering asset management, pallets, foreign assets, and XCM monitoring
reference/polkadot-hub/assets-and-smart-contracts.md	Removed original combined page
reference/polkadot-hub/.nav.yml	Updated navigation to link to separate assets and smart-contracts pages
.nav.yml	Added Technical Reference section to main navigation

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[nhussein11]

Thank you @kapetan3sid ! Left some comments, maybe after the refactoring of the assets page, the combination assets.md + smart-contracts.md is not that lenghty and it could fit everything under the same page

[eshaben]

@kapetan3sid let me know when it's ready. Seems like there are some major changes that need to be made and approved by Nico before I step in.

[kapetan3sid]

@nhussein11 I applied changes - this is ready for re-review

[nhussein11]

Thank you very much @kapetan3sid !

Left some comments, but I believe those can be taken over by the @polkadot-developers/docs-formatting-team. Just a quick note, the ai files were not pushed and there are some instances of target={_blank} that I did not flag

[kapetan3sid]

@erin ready for your review

[eshaben]

Assets Page:

I removed a lot of the technical references from this page, because they were used for like querying the data, but not most of the core extrinsics. Since this page is conceptual, I didn't think we need to callout the exact function signature and details. So I removed that.

I also removed the part about monitoring XCM transfers because it just felt out of place. I think this content should be in the XCM guides instead if needed.

---

Contracts Page:

Overall, this page doesn't seem to have a clear purpose.

It mentioned PolkaVM so I commented that out. Then what was left was very little and is duplicated elsewhere in the docs. Maybe someone can tell me what the purpose of this page is? Especially versus this page: https://beta-docs.polkadot.com/smart-contracts/for-eth-devs/contract-deployment/#revm-deployment

[brunopgalvao]

Please do not commit TODO's.

[eshaben]

I committed the TODO because I think we need an answer on this before merging in the PR.

[brunopgalvao]

Similar to my comment in the smart contracts intro, I would not start this by saying what the Polkadot Relay chain limitation or its scope.

[eshaben]

How would you rewrite it? I sometimes think it's helpful to define the problem first and then provide the solution to the problem.

[brunopgalvao]

Please clarify that this is existential deposit and link to glossary.

[brunopgalvao]

Foreign assets are managed by an instance of the assets pallet configured specifically for foreign assets.
See:
https://github.com/polkadot-fellows/runtimes/blob/9d08bff9f32e2a8eecada06e0af5d178d7eef92f/system-parachains/asset-hubs/asset-hub-polkadot/src/lib.rs#L395-L402

[eshaben]

So it's not referred to as the Foreign Assets Pallet? What is the correct terminology? How are people going to most resonate with it?

[brunopgalvao]

Contracts Page:

Overall, this page doesn't seem to have a clear purpose.

It mentioned PolkaVM so I commented that out. Then what was left was very little and is duplicated elsewhere in the docs. Maybe someone can tell me what the purpose of this page is? Especially versus this page: https://beta-docs.polkadot.com/smart-contracts/for-eth-devs/contract-deployment/#revm-deployment

I agree. Also the Assets page should be less of a reference to the assets pallet API and more of how assets work on the Polkadot Hub. We need to be telling the story of what Polkadot Hub is, in terms of asset creation and management, smart contract functionality, etc.

[eshaben]

Also the Assets page should be less of a reference to the assets pallet API and more of how assets work on the Polkadot Hub. We need to be telling the story of what Polkadot Hub is, in terms of asset creation and management, smart contract functionality, etc.

Yeah, I agree. So it sounds like this page will need DevRel attention then. So I propose we ship it with what's there and then a ticket be created for the backlog so that you or Nico can circle back to it.

[brunopgalvao]

Also the Assets page should be less of a reference to the assets pallet API and more of how assets work on the Polkadot Hub. We need to be telling the story of what Polkadot Hub is, in terms of asset creation and management, smart contract functionality, etc.

Yeah, I agree. So it sounds like this page will need DevRel attention then. So I propose we ship it with what's there and then a ticket be created for the backlog so that you or Nico can circle back to it.

Sounds good to me.