Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
817 changes: 597 additions & 220 deletions .ai/categories/parachains.md

Large diffs are not rendered by default.

154 changes: 154 additions & 0 deletions .ai/categories/smart-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .ai/categories/tooling.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,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

Expand All @@ -70,7 +70,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.

Expand All @@ -84,20 +84,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

Expand Down
Loading
Loading