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

.ai/categories/polkadot-protocol.md

@@ -8332,6 +8332,186 @@ You must contact specific registrars individually to request judgment. Each regi
 </div>
 
 
+---
+
+Page Title: Polkadot Hub Assets
+
+- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-assets.md
+- Canonical (HTML): https://docs.polkadot.com/reference/polkadot-hub/assets/
+- Summary: Learn about asset management on Polkadot Hub, including on-chain assets, foreign asset integration, and XCM for cross-chain asset transfers.
+
+# Assets on Polkadot Hub
+
+## Introduction
+
+Polkadot Hub is Polkadot's system parachain for issuing and managing on-chain assets. While the relay chain provides security, Polkadot Hub handles asset logic—minting, burning, transfers, and metadata—efficiently and cost-effectively.
+
+Polkadot Hub supports native assets issued on the parachain and foreign assets from other chains, both of which can move seamlessly across the network via XCM.
+
+This guide explains how assets are created, managed, and moved across chains, including key operations, roles, and the differences between native and foreign assets.
+
+## Why Use Polkadot Hub?
+
+Polkadot Hub provides a standardized framework for creating and managing fungible and non-fungible assets. Projects can issue tokens, manage supply, and transfer assets across parachains, extending the functionality of the Polkadot relay chain, which only supports its native token (DOT).
+
+**Key features**:
+
+- **Built-in asset operations**: Mint, burn, and transfer like ERC-20 on Ethereum, but native to Polkadot's runtime.
+- **Custom asset creation**: Issue tokens or NFTs with configurable permissions and metadata.
+- **Low fees**: Transactions cost roughly one-tenth of relay chain fees.
+- **Lower deposits**: Minimal on-chain storage costs for asset data.
+- **Pay fees in any asset**: Users don’t need DOT to transact; supported assets can cover fees.
+- **Cross-chain ready**: Assets can be transferred to other parachains using XCM.
+
+## Types of Assets
+
+Polkadot Hub supports two types of assets:
+
+- **Native assets**: Tokens and NFTs issued directly on Polkadot Hub using the Assets pallet. These assets benefit from the platform's custom features, such as configurable permissions and low fees
+- **Foreign assets**: Tokens originating from other Polkadot parachains or external networks (like Ethereum, via bridges). Once registered on Polkadot Hub, they are treated similarly to native assets.
+
+## Asset Structure
+
+Each asset is identified by a unique ID and stores:
+
+- Asset administrators
+- Total supply and holder count
+- Minimum balance configuration
+- Sufficiency–whether the asset can keep an account alive without DOT
+- Metadata (name, symbol, decimals)
+
+If a balance falls below the configured minimum, called the [existential deposit](/reference/glossary/#existential-deposit){target=\_blank}, it may be removed as “dust.” This ensures efficient storage while giving developers control over asset economics.
+
+## How Native Assets Work
+
+Native assets on Polkadot Hub are created and managed via the Assets pallet from the Polkadot SDK. This pallet defines the runtime logic for issuing, configuring, and administering fungible assets with customizable permissions.
+
+It supports both permissioned and permissionless asset creation, enabling everything from simple user-issued tokens to governed assets controlled by teams or DAOs.
+
+For implementation details, see the [Assets Pallet Rust docs](https://paritytech.github.io/polkadot-sdk/master/pallet_assets/index.html){target=\_blank}.
+
+### Asset Operations
+
+The Assets pallet provides both state-changing operations and read-only queries for full lifecycle management of assets.
+
+Core operations include:
+
+- **Asset issuance**: Create new assets and assign initial supply.
+- **Transfers**: Move assets between accounts with balance tracking.
+- **Burning**: Reduce total supply by destroying tokens.
+- **Delegated transfers**: Approve transfers on behalf of another account without giving up custody.
+- **Freezing and thawing**: Temporarily lock and unlock an account's balance.
+
+For a complete list of extrinsics, see the [`pallet-assets` dispatchable functions reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/enum.Call.html){target=\_blank}.
+
+Data queries make it possible to:
+
+- Check account balances and total supply.
+- Retrieve asset metadata and configuration details.
+- Inspect account and asset status on-chain.
+
+For a full list of queries, see the [Pallet reference](https://docs.rs/pallet-assets/latest/pallet_assets/pallet/struct.Pallet.html){target=\_blank}.
+
+### Roles and Permissions
+
+The Assets pallet uses role-based permissions to control who can manage different parts of an asset’s lifecycle:
+
+- **Owner**: Overarching control, including destroying an asset class; can set or update Issuer, Freezer, and Admin roles.
+- **Admin**: Can freeze assets and forcibly transfer balances between accounts. Admins can also reduce the balance of an asset class across arbitrary accounts.
+- **Issuer**: Responsible for minting new tokens. When new assets are created, the Issuer is the account that controls their distribution to other accounts.
+- **Freezer**: Can lock the transfer of assets from an account, preventing the account holder from moving their balance.
+
+These roles allow projects to enforce governance and security policies around their assets.
+
+### Freezing Assets
+
+Assets can be temporarily locked to prevent transfers from specific accounts. This is useful for dispute resolution, fraud prevention, or compliance controls.
+
+**How it works**:
+
+- Only authorized parties can freeze or unfreeze (thaw) assets.
+- Freezing pauses the movement of the asset without burning or removing it.
+- Once thawed, the asset can be transferred normally.
+
+Freezing provides a safe way to control asset flow while maintaining full ownership.
+
+**Key functions**: `freeze` and `thaw`.
+
+### Delegated Transfers
+
+Polkadot Hub supports delegated asset transfers, allowing one account to authorize another to move a limited amount of its assets—without giving up full control. This is useful for escrow logic, automated payments, and multi-party applications.
+
+**How it works**:
+
+- An account can grant permission to another account to transfer a specific amount of its assets.
+- Permissions can be revoked at any time, preventing further transfers.
+- Authorized accounts can execute transfers on behalf of the original owner within the approved limits.
+
+Delegated transfers simplify multi-step transactions and enable complex asset flows.
+
+**Key functions**: `approve_transfer`, `cancel_approval`, and `transfer_approved`.
+
+## How Foreign Assets Work
+
+Foreign assets are assets originating from other chains and are managed on Polkadot Hub via an instance of the Assets pallet that is configured specifically for foreign assets. It enables transfers, balance checks, and other standard asset operations, while handling foreign-asset specifics such as:
+
+- **Asset identifiers**: Foreign assets use an XCM multilocation as their identifier, rather than a numeric AssetId. This ensures assets from different chains can be referenced and moved safely across parachains.
+
+- **Transfers**: Once registered on Polkadot Hub, foreign assets can be transferred between accounts just like native assets. If supported, they can also be returned to their original blockchain using cross-chain messaging.
+
+This unified interface makes it easy for dApps to handle both native and cross-chain assets.
+
+## Moving Assets Across Chains
+
+Polkadot Hub enables assets to move safely between parachains and the relay chain using XCM (Cross-Consensus Messaging). XCM ensures assets can move securely between chains while preserving ownership and traceability
+
+To learn more about asset transfers with XCM, please refer to the [Introduction to XCM](/parachains/interoperability/get-started/) page.
+
+
+---
+
+Page Title: Polkadot Hub Smart Contracts
+
+- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/reference-polkadot-hub-smart-contracts.md
+- Canonical (HTML): https://docs.polkadot.com/reference/polkadot-hub/smart-contracts/
+- Summary: Learn how Polkadot Hub supports smart contracts through the REVM, a Rust-based Ethereum Virtual Machine compatible runtime.
+
+# Smart Contracts on Polkadot Hub
+
+## Introduction
+
+Polkadot Hub enables developers to deploy and interact with Solidity contracts through REVM, a high-performance, Rust-based Ethereum Virtual Machine implementation. This brings Ethereum compatibility to Polkadot Hub, letting teams use familiar Solidity tooling, integrate with on-chain features like governance and XCM, and take advantage of cross-chain interoperability.
+
+For projects that require maximum computational performance, Polkadot Hub also supports PolkaVM (PVM), a native RISC-V execution engine. PVM is optional and designed for high-throughput, performance-intensive smart contracts.
+
+### REVM Smart Contracts
+
+[REVM](https://github.com/bluealloy/revm){target=_blank} brings full EVM compatibility to Polkadot Hub through a fast, memory-safe Rust implementation of the Ethereum Virtual Machine. Unlike PolkaVM, which compiles contracts to RISC-V for native execution, REVM executes standard Ethereum bytecode directly—making it ideal for teams who want to migrate existing Solidity projects to Polkadot with minimal changes.
+
+With REVM, developers can:
+
+- Deploy existing Solidity contracts without rewriting them.
+- Use familiar Ethereum tooling like Hardhat, Foundry, Remix, and MetaMask.
+- Interact with other parachains and on-chain assets using XCM and Polkadot Hub features.
+
+REVM builds on Rust’s safety guarantees and performance optimizations while retaining full opcode compatibility with the EVM. This provides a reliable path for Ethereum-native developers to access Polkadot’s native features—such as governance, treasury, multisig, and XCM—within a unified, interoperable runtime environment.
+
+### PVM Smart Contracts
+
+PVM is Polkadot Hub’s native, high-performance smart contract engine. Instead of emulating EVM bytecode, it runs contracts compiled to a [RISC-V](https://en.wikipedia.org/wiki/RISC-V){target=_blank} instruction set, unlocking higher performance and parallel execution while staying friendly to Ethereum-style development.
+
+With PVM, developers can:
+
+- Write Solidity contracts and use familiar tooling (e.g., Hardhat, Foundry) targeting PVM
+- Benefit from fast, predictable execution with carefully metered gas/weight.
+- Access detailed observability through Substrate events and contract logs for indexing and debugging.
+
+PolkaVM delivers maximum performance for computationally intensive contracts, offering a native, high-throughput option for Ethereum-style developers on Polkadot Hub.
+
+!!! smartcontract "PolkaVM Preview Release"
+    PolkaVM smart contracts with Ethereum compatibility are in **early-stage development and may be unstable or incomplete**.
+
+
 ---
 
 Page Title: Polkadot SDK Accounts

.ai/categories/smart-contracts.md

@@ -10585,6 +10585,160 @@ Your local development environment is now active and accessible at `http://local
 You can connect wallets, deploy contracts using Remix or Hardhat, and interact with your smart contracts as you would on any Ethereum-compatible network.
 
 
+---
+
+Page Title: Migration FAQs and Considerations
+
+- Source (raw): https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/master/.ai/pages/smart-contracts-for-eth-devs-migration.md
+- Canonical (HTML): https://docs.polkadot.com/smart-contracts/for-eth-devs/migration/
+- Summary: Learn how to migrate your existing Ethereum contracts to the Polkadot Hub using REVM and PolkaVM by following these considerations.
+
+# Migration FAQs and Considerations
+
+## Introduction
+
+This guide helps Ethereum developers migrate their smart contracts to Polkadot Hub. Most contracts work without modifications on the REVM backend, while the PolkaVM backend offers enhanced performance with minimal adaptation for standard patterns.
+
+## Migration Considerations
+
+Take into account the following considerations before migrating your contracts:
+
+- Standard ERC-20, ERC-721, ERC-1155 tokens work without changes.
+- DeFi protocols, DEXs, and AMMs migrate seamlessly.
+- DAOs and governance contracts are fully compatible.
+- Most Solidity contracts deploy identically to Ethereum.
+
+## Migration Checklist
+
+Before migrating your contracts, review this checklist:
+
+- Factory contracts using PVM bytecode need pre-uploaded dependencies.
+- Contracts using `EXTCODECOPY` for runtime manipulation require review (for projects that will use PVM bytecode, not EVM bytecode).
+- Replace `transfer()` and `send()` with proper reentrancy guards (for projects that will use PVM bytecode, not EVM bytecode).
+
+## Migration FAQs
+
+### Which backend should I choose?
+
+- Choose REVM if you want:
+
+    - Zero-modification deployment of existing Ethereum contracts.
+    - Exact EVM behavior for audited code.
+    - Compatibility with tools that inspect EVM bytecode.
+    - Rapid deployment without optimization.
+
+- Choose PolkaVM if you want:
+
+    - Better performance for computation-heavy applications.
+    - Lower execution costs for intensive operations.
+    - Access to next-generation smart contract features.
+
+If you are unsure which to choose, start with REVM for immediate compatibility, then consider PolkaVM for performance optimization once deployed.
+
+### Do I need to rewrite my Solidity code?
+
+No, for most contracts. Standard Solidity patterns work on both backends.
+
+### What about factory contracts?
+
+- **REVM**: Factory contracts work identically to Ethereum with no changes needed. 
+
+    The original factory pattern is:
+
+    ```solidity
+    contract TokenFactory {
+        function createToken(string memory name) public returns (address) {
+            // Creates new contract at runtime
+            Token newToken = new Token(name);
+            return address(newToken);
+        }
+    }
+    ```
+
+- **PolkaVM**: Factory contracts require pre-uploading dependent contracts. 
+
+    Here's how to adapt the original factory pattern:
+
+    ```solidity
+    contract TokenFactory {
+        // Reference pre-uploaded Token contract by hash
+        bytes32 public tokenCodeHash;
+
+        constructor(bytes32 _tokenCodeHash) {
+            tokenCodeHash = _tokenCodeHash;
+        }
+
+        function createToken(string memory name) public returns (address) {
+            // Instantiate from pre-uploaded code
+            Token newToken = new Token{salt: keccak256(abi.encode(name))}(name);
+            return address(newToken);
+        }
+    }
+    ```
+
+The deployment steps for PolkaVM factories are:
+
+1. Upload the contract code to the chain.
+2. Note the returned code hash.
+3. Deploy the Factory contract with the contract code hash.
+4. Factory can now instantiate contracts using the pre-uploaded code.
+
+### How do gas costs compare?
+
+For more information on gas costs, see the [Gas Model](/smart-contracts/for-eth-devs/gas-model/){target=\_blank} page.
+
+### Which Solidity features are not supported?
+
+For REVM, any Solidity feature will function smoothly without requiring changes or adaptations. For PVM, there are considerations, as was mentioned above. 
+
+For PolkaVM, there are some considerations:
+
+- `EXTCODECOPY`: Only works in constructor code.
+- Runtime code modification: Use on-chain constructors instead.
+- **Gas stipends**: `address.send()` and `address.transfer()` don't provide reentrancy protection.
+- **Unsupported operations**: `pc`, `extcodecopy`, `selfdestruct`, `blobhash`, and `blobbasefee` (blob-related operations).
+
+### How do I handle the existential deposit?
+
+Polkadot requires accounts to maintain a minimum balance (existential deposit or ED) to remain active.
+
+This is handled automatically for you:
+
+- Balance queries via Ethereum RPC automatically deduct the ED.
+- New account transfers include ED in transaction fees.
+- Contract-to-contract transfers draw ED from the transaction signer.
+
+You typically don't need to do anything special, but be aware:
+
+- Accounts below ED threshold are automatically deleted.
+- ED is around 0.01 DOT (varies by network).
+- Your contracts don't need to manage this explicitly.
+
+### Can I use my existing development tools?
+
+Yes. Both backends support:
+
+- **Wallets**: [MetaMask](https://metamask.io/){target=\_blank}, [Talisman](https://talisman.xyz/){target=\_blank}, [SubWallet](https://www.subwallet.app/){target=\_blank}
+- **Development frameworks**: [Hardhat](/smart-contracts/cookbook/smart-contracts/deploy-basic/hardhat/){target=\_blank}, [Foundry](/smart-contracts/cookbook/smart-contracts/deploy-basic/foundry/){target=\_blank}, [Remix](/smart-contracts/cookbook/smart-contracts/deploy-basic/remix/){target=\_blank} (just consider that for PVM bytecode, you will use the Polkadot version of the tooling)
+- **Libraries**: [ethers.js](/smart-contracts/libraries/ethers-js/){target=\_blank}, [web3.js](/smart-contracts/libraries/web3-js/){target=\_blank}, [viem](/smart-contracts/libraries/viem/){target=\_blank}
+- **Testing tools**: Your existing test suites work
+
+Connect to Polkadot Hub's Ethereum JSON-RPC endpoint and use your familiar workflow.
+
+## Conclusion
+
+Most Ethereum contracts migrate to Polkadot Hub with minimal or no changes. Use REVM for seamless compatibility or PolkaVM for enhanced performance.
+
+There are a few key points to keep in mind during migration:
+
+- Replace `transfer()` and `send()` with `.call{value}("")` and use reentrancy guards (for projects that will use PVM bytecode, not EVM bytecode).
+- PolkaVM factory contracts using PVM bytecode need pre-uploaded dependencies.
+- Don't hardcode gas values.
+- Test thoroughly on [TestNet](/smart-contracts/connect/#__tabbed_1_1){target=\_blank} before mainnet deployment.
+
+Your existing Solidity knowledge and tooling transfer directly to Polkadot Hub, making migration straightforward for standard smart contract patterns.
+
+
 ---
 
 Page Title: Networks

.ai/categories/tooling.md

@@ -25913,7 +25913,7 @@ export default buildModule("StorageModule", (m) => {
 Deploy the contract to Polkadot Hub TestNet:
 
 ```bash
-npx hardhat ignition deploy ./ignition/modules/Storage.ts --network polkadotHub
+npx hardhat ignition deploy ./ignition/modules/Storage.ts --network polkadotTestNet
 ```
 
 You should see output similar to: