polkadot-developers · nhussein11 · Oct 16, 2025 · Oct 16, 2025 · Oct 28, 2025 · Oct 29, 2025
@@ -25,6 +25,8 @@ Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/re
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/dev-environments/remix/get-started.md [type: other]
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/explorers.md [type: other]
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/faucet.md [type: other]
+Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/migration.md [type: other]
+Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/get-started.md [type: other]
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/integrations/wallets.md [type: other]
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/libraries/ethers-js.md [type: other]
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/libraries/viem.md [type: other]
@@ -2268,6 +2270,151 @@ For Polkadot Hub TestNet, you can use the [Polkadot Faucet](https://faucet.polka
 Getting started with test tokens is the first step in your Polkadot development journey. These free resources enable you to build, experiment with, and refine your applications without financial constraints, ensuring your projects are robust and ready for deployment on MainNet.
 --- END CONTENT ---
 
+Doc-Content: https://docs.polkadot.com/smart-contracts/for-eth-devs/migration/
+--- BEGIN CONTENT ---
+---
+title: Migration FAQs and Considerations
+description: Learn how to migrate your existing Ethereum contracts to the Polkadot Hub using REVM and PolkaVM.
+categories: Smart Contracts
+---
+
+# 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.
+
+## Quick Migration Checklist
+
+Before migrating your contracts, review this checklist:
+
+- 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
+- Factory contracts on PolkaVM need pre-uploaded dependencies
+- Contracts using `EXTCODECOPY` for runtime manipulation require review
+- Replace `transfer()` and `send()` with proper reentrancy guards
+
+## 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
+
+**Not sure?** 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, Solidity features are supported. 
+
+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`, `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.
+
+**Good news**: 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 1 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, Talisman, SubWallet
+- **Development frameworks**: Hardhat, Foundry, Remix
+- **Libraries**: ethers.js, web3.js, viem
+- **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. The key differences to remember:
+
+- Replace `transfer()` with `.call{value}("")` and use reentrancy guards
+- PolkaVM factory contracts need pre-uploaded dependencies
+- Don't hardcode gas values
+- Test thoroughly on TestNet before mainnet deployment
+
+Your existing Solidity knowledge and tooling transfer directly to Polkadot Hub, making migration straightforward for standard smart contract patterns.
+--- END CONTENT ---
+
 Doc-Content: https://docs.polkadot.com/smart-contracts/get-started/
 --- BEGIN CONTENT ---
 ---

@@ -6,7 +6,6 @@ Polkadot. Polkadot is an open-source, multichain network protocol that facilitat
 Documentation: https://docs.polkadot.com/
 
 ## List of doc pages:
-Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/.venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/idna/LICENSE.md
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/chain-interactions/accounts/create-account.md
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/chain-interactions/accounts/query-accounts.md
 Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/chain-interactions/index.md
@@ -261,41 +260,6 @@ Doc-Page: https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/re
 
 ## Full content for each doc page
 
-Doc-Content: https://docs.polkadot.com/.venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/idna/LICENSE/
---- BEGIN CONTENT ---
-BSD 3-Clause License
-
-Copyright (c) 2013-2024, Kim Davies and contributors.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are
-met:
-
-1. Redistributions of source code must retain the above copyright
-   notice, this list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright
-   notice, this list of conditions and the following disclaimer in the
-   documentation and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
-TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
-PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
-LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
-NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
---- END CONTENT ---
-
 Doc-Content: https://docs.polkadot.com/chain-interactions/accounts/create-account/
 --- BEGIN CONTENT ---
 TODO
@@ -29490,7 +29454,147 @@ If an error occurs, the response will include an error object:
 
 Doc-Content: https://docs.polkadot.com/smart-contracts/for-eth-devs/migration/
 --- BEGIN CONTENT ---
-TODO
+---
+title: Migration FAQs and Considerations
+description: Learn how to migrate your existing Ethereum contracts to the Polkadot Hub using REVM and PolkaVM.
+categories: Smart Contracts
+---
+
+# 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.
+
+## Quick Migration Checklist
+
+Before migrating your contracts, review this checklist:
+
+- 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
+- Factory contracts on PolkaVM need pre-uploaded dependencies
+- Contracts using `EXTCODECOPY` for runtime manipulation require review
+- Replace `transfer()` and `send()` with proper reentrancy guards
+
+## 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
+
+**Not sure?** 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, Solidity features are supported. 
+
+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`, `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.
+
+**Good news**: 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 1 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, Talisman, SubWallet
+- **Development frameworks**: Hardhat, Foundry, Remix
+- **Libraries**: ethers.js, web3.js, viem
+- **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. The key differences to remember:
+
+- Replace `transfer()` with `.call{value}("")` and use reentrancy guards
+- PolkaVM factory contracts need pre-uploaded dependencies
+- Don't hardcode gas values
+- Test thoroughly on TestNet before mainnet deployment
+
+Your existing Solidity knowledge and tooling transfer directly to Polkadot Hub, making migration straightforward for standard smart contract patterns.
 --- END CONTENT ---
 
 Doc-Content: https://docs.polkadot.com/smart-contracts/get-started/

@@ -4,7 +4,6 @@
 
 ## Docs
 
-- [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/.venv/lib/python3.13/site-packages/pip-25.2.dist-info/licenses/src/pip/_vendor/idna/LICENSE.md): No description available.
 - [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/chain-interactions/accounts/create-account.md): No description available.
 - [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/chain-interactions/accounts/query-accounts.md): No description available.
 - [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/chain-interactions/index.md): No description available.
@@ -210,7 +209,7 @@
 - [PolkaVM Design](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/dual-vm-stack.md): Discover PolkaVM, a high-performance smart contract VM for Polkadot, enabling Ethereum compatibility via pallet_revive, Solidity support & optimized execution.
 - [Gas Model on the Polkadot Hub](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/gas-model.md): Learn how gas estimation, pricing, and weight mapping work in the Polkadot Hub.
 - [JSON-RPC APIs](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/json-rpc-apis.md): JSON-RPC APIs guide for Polkadot Hub, covering supported methods, parameters, and examples for interacting with the chain.
-- [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/migration.md): No description available.
+- [Migration FAQs and Considerations](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/for-eth-devs/migration.md): Learn how to migrate your existing Ethereum contracts to the Polkadot Hub using REVM and PolkaVM.
 - [Get Started with Smart Contracts](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/get-started.md): Practical examples for building and deploying smart contracts on Polkadot Hub, from connecting and tooling to deployment, integrations, and precompiles.
 - [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/integrations/indexers.md): No description available.
 - [Untitled](https://raw.githubusercontent.com/polkadot-developers/polkadot-docs/refs/heads/master/smart-contracts/integrations/oracles.md): No description available.