add chain interactions overview

Author: brunopgalvao

.ai/categories/parachains.md

@@ -1256,9 +1256,9 @@ Any language that can compile to PolkaVM bytecode and utilize `pallet-revive`'s
 
 ### Key Benefits
 
-- **Unified Platform**: Deploys both PolkaVM-optimized and EVM-compatible contracts using a single pallet.
+- **Unified platform**: Deploys both PolkaVM-optimized and EVM-compatible contracts using a single pallet.
 - **Performance**: PolkaVM execution provides improved performance compared to the traditional EVM, leveraging the [RISC-V](https://en.wikipedia.org/wiki/RISC-V){target=\_blank} architecture to map instructions to the CPU and requires little transpiling.
-- **Ethereum Compatibility**: Supports full integration with Ethereum tooling via RPC adapter.
+- **Ethereum compatibility**: Supports full integration with Ethereum tooling via RPC adapter.
 
 ### Implementation Examples
 
@@ -1276,7 +1276,7 @@ Frontier offers flexible integration depending on your compatibility needs:
 
 For basic EVM support using Polkadot SDK native APIs:
 
-- **[`pallet-evm`](https://github.com/polkadot-evm/frontier/tree/master/frame/evm){target=\_blank}**: Provides the core EVM execution environment
+- **[`pallet-evm`](https://github.com/polkadot-evm/frontier/tree/master/frame/evm){target=\_blank}**: Provides the core EVM execution environment.
 
 This configuration allows EVM contract execution but requires using Polkadot SDK-specific APIs for interaction.
 
@@ -1290,20 +1290,20 @@ For complete Ethereum ecosystem integration with Ethereum RPC support:
 
 ### Key Benefits
 
-- **Ethereum tooling compatibility**: Full compatibility with MetaMask, Hardhat, Remix, Truffle, and other Ethereum development tools
-- **Minimal-friction migration**: Deployment of existing Ethereum dApps with minimal or no modifications
-- **Native Ethereum formats**: Support for Ethereum transaction formats, signatures, and gas mechanics
-- **Block emulation**: Ethereum-style block structure within Substrate's block production
+- **Ethereum tooling compatibility**: Full compatibility with MetaMask, Hardhat, Remix, Foundry, and other Ethereum development tools.
+- **Minimal-friction migration**: Deployment of existing Ethereum dApps with minimal or no modifications.
+- **Native Ethereum formats**: Support for Ethereum transaction formats, signatures, and gas mechanics.
+- **Block emulation**: Ethereum-style block structure within Substrate's block production.
 
 ### Implementation Examples
 
 Production implementations demonstrate Frontier's capabilities:
 
-- **Moonbeam**: See their implementation of [`pallet-evm`](https://github.com/moonbeam-foundation/moonbeam/blob/9e2ddbc9ae8bf65f11701e7ccde50075e5fe2790/runtime/moonbeam/src/lib.rs#L532){target=\_blank} and [`pallet-ethereum`](https://github.com/moonbeam-foundation/moonbeam/blob/9e2ddbc9ae8bf65f11701e7ccde50075e5fe2790/runtime/moonbeam/src/lib.rs#L698){target=\_blank}
+- **Moonbeam**: See their implementation of [`pallet-evm`](https://github.com/moonbeam-foundation/moonbeam/blob/9e2ddbc9ae8bf65f11701e7ccde50075e5fe2790/runtime/moonbeam/src/lib.rs#L532){target=\_blank} and [`pallet-ethereum`](https://github.com/moonbeam-foundation/moonbeam/blob/9e2ddbc9ae8bf65f11701e7ccde50075e5fe2790/runtime/moonbeam/src/lib.rs#L698){target=\_blank}.
 
 ## pallet-contracts (Legacy)
 
-[`pallet-contracts`](https://docs.rs/pallet-contracts/latest/pallet_contracts/index.html#contracts-pallet){target=\_blank} is the original Wasm-based smart contract pallet for Polkadot SDK chains. While still functional, it's considered legacy as development efforts have shifted to pallet-revive.
+[`pallet-contracts`](https://docs.rs/pallet-contracts/latest/pallet_contracts/index.html#contracts-pallet){target=\_blank} is the original Wasm-based smart contract pallet for Polkadot SDK chains. While still functional, it's considered legacy as development efforts have shifted to `pallet-revive`.
 
 ### Implementation Example
 

.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:

.ai/pages/chain-interactions.md

@@ -1,5 +1,95 @@
 ---
+title: Chain Interactions Overview
+description: Learn how to query data, send transactions, enable cross-chain communication, and manage accounts across the Polkadot ecosystem.
+categories: Chain Interactions
 url: https://docs.polkadot.com/chain-interactions/
 ---
 
-TODO
+# Chain Interactions
+
+## Introduction
+
+Chain interactions form the foundation of building applications on Polkadot. Whether you're querying on-chain data, executing transactions, enabling cross-chain communication, or managing accounts, understanding how to interact with Polkadot-based chains is essential for application developers.
+
+This section provides comprehensive guidance on the various ways to interact with Polkadot chains, from basic queries to complex cross-chain operations. You'll learn how to:
+
+- Query on-chain state and subscribe to blockchain events
+- Send transactions and manage their lifecycle
+- Enable interoperability between parachains through XCM
+- Manage tokens and perform token operations
+- Create and manage accounts programmatically
+
+Whether you're building a frontend application, a backend service, or integrating with the Polkadot ecosystem, these guides will equip you with the knowledge and tools to effectively interact with chains across the network.
+
+## Core Interaction Patterns
+
+### Query On-Chain Data
+
+Accessing blockchain state is fundamental to building responsive applications. Polkadot provides multiple methods to query on-chain data, each suited for different use cases.
+
+- **SDK Integration**: Use [Polkadot API (PAPI)](https://papi.how/){target=\_blank}, [Polkadot.js](https://polkadot.js.org/docs/){target=\_blank}, [Dedot](https://dedot.dev/){target=\_blank}, [PSI](https://github.com/paritytech/psi){target=\_blank}, or [Subxt](https://docs.rs/subxt/latest/subxt/){target=\_blank} to read blockchain state programmatically
+
+- **REST API Access**: Query chain data through standardized REST endpoints for simpler integration
+
+- **Runtime API Calls**: Execute runtime APIs directly for specialized queries and operations
+
+Learn how to efficiently retrieve account balances, query storage, subscribe to events, and decode blockchain data in your applications.
+
+### Send Transactions
+
+Transactions are the primary mechanism for modifying blockchain state. Understanding transaction construction, signing, and submission is crucial for building interactive applications.
+
+- **Transaction Construction**: Build transactions using various SDKs with proper encoding and formatting
+- **Fee Estimation**: Calculate transaction fees to ensure sufficient balance and optimize costs
+- **Multi-Token Fees**: Learn how to pay transaction fees with different tokens on supported chains
+
+### Interoperability
+
+Polkadot's true power lies in its native cross-chain capabilities. Through Cross-Consensus Messaging (XCM), chains can securely communicate and transfer assets across the ecosystem.
+
+- **XCM Fundamentals**: Understand how to construct and send XCM messages between parachains using [ParaSpell XCM SDK](https://paraspell.github.io/docs/){target=\_blank} and [Polkadot API (PAPI)](https://papi.how/){target=\_blank}
+- **Asset Transfers**: Transfer tokens and other assets between different chains seamlessly
+- **Cross-Chain Communication**: Enable your applications to interact with multiple parachains
+- **Bridge Integration**: Connect to blockchains outside the Polkadot ecosystem using Snowbridge and other bridge solutions
+
+Master the tools for estimating transfer costs, debugging XCM messages, and implementing robust cross-chain workflows.
+
+### Token Operations
+
+Polkadot Hub provides a unified platform for managing assets across the ecosystem. Understanding token operations is essential for DeFi applications and multi-chain asset management.
+
+- **Asset Registration**: Learn how local and foreign assets are registered on the network
+- **Asset Hub Integration**: Interact with Polkadot's central asset management hub using [Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank}
+- **Cross-Chain Assets**: Handle assets that exist across multiple parachains
+
+### Accounts
+
+Account management forms the basis of user identity and authentication in blockchain applications. Learn how to create, manage, and query accounts programmatically.
+
+- **Account Creation**: Generate accounts using various SDKs in Rust, Python, and JavaScript
+- **Account Queries**: Retrieve account information including balances, nonces, and metadata
+
+## Development Tools and SDKs
+
+The Polkadot ecosystem offers a rich set of tools and libraries to facilitate chain interactions:
+
+- **[Polkadot API (PAPI)](https://papi.how/){target=\_blank}**: Modern, type-safe TypeScript library with full metadata support
+- **[Polkadot.js](https://polkadot.js.org/docs/){target=\_blank}**: Comprehensive JavaScript library with extensive ecosystem support
+- **[Dedot](https://dedot.dev/){target=\_blank}**: Lightweight TypeScript library optimized for performance
+- **[PSI](https://github.com/paritytech/psi){target=\_blank}**: Polkadot Substrate Interface for streamlined development
+- **[Subxt](https://docs.rs/subxt/latest/subxt/){target=\_blank}**: Rust library for building robust substrate-based applications
+- **[Polkadot.js Apps](https://polkadot.js.org/apps/){target=\_blank}**: Web-based interface for exploring and interacting with chains
+
+Each tool has its strengths, and choosing the right one depends on your project requirements, programming language preference, and specific use cases.
+
+## Next Steps
+
+Explore the sections below to dive deeper into specific chain interaction patterns:
+
+- **[Query On-Chain Data](/chain-interactions/query-data/query-sdks/)**: Learn to read blockchain state efficiently  
+- **[Send Transactions](/chain-interactions/send-transactions/with-sdks/)**: Master transaction construction and submission
+- **[Interoperability](/chain-interactions/send-transactions/interoperability/transfer-assets-parachains/)**: Enable cross-chain communication with XCM
+- **[Token Operations](/chain-interactions/token-operations/register-local-asset/)**: Manage assets across the Polkadot ecosystem
+- **[Accounts](/chain-interactions/accounts/create-account/)**: Create and query accounts programmatically
+
+Each section provides practical examples, code snippets, and comprehensive guides to help you build production-ready applications on Polkadot.