feat: enhance Polkadot smart contract documentation with dual virtual machine architecture overview

Author: nhussein11

smart-contracts/for-eth-devs/index.md

@@ -1,3 +1,9 @@
+---
+title: Dual Virtual Machine Stack
+description: Overview of Polkadot's dual virtual machine architecture, offering flexibility in choosing the right execution backend for developers.
+categories: Basics, Smart Contracts
+---
+
 # Dual Virtual Machine Stack
 
 ## Introduction
@@ -6,329 +12,62 @@ Polkadot's smart contract platform provides developers with a unique dual virtua
 
 The dual-stack architecture consists of:
 
-- **REVM Backend**: Provides full Ethereum Virtual Machine compatibility, enabling unchanged Solidity contracts and familiar tooling
-- **PolkaVM (PVM) Backend**: A RISC-V-based virtual machine optimized for performance and enabling new use cases
+- **[REVM Backend](#revm-backend){target=\_blank}**: Provides full Ethereum Virtual Machine compatibility, enabling unchanged Solidity contracts and familiar tooling
+- **[PolkaVM Backend](#polkavm-backend){target=\_blank}**: A RISC-V-based virtual machine optimized for performance and enabling new use cases
 
 Both backends share common infrastructure including RPC interfaces, tooling support, and precompiles, ensuring consistent developer experience while offering distinct performance characteristics.
 
 ```mermaid
 graph TD
-    subgraph "Smart Contract Platform"
-        subgraph "Dual VM Architecture"
-            REVM["REVM Backend<br/>(EVM Compatible)"]
-            PVM["PolkaVM Backend<br/>(RISC-V Based)"]
-        end
-        
-        subgraph "Shared Infrastructure"
-            RPC["Ethereum JSON-RPC"]
-            Tools["Developer Tooling<br/>(Hardhat, Foundry)"]
-            Precompiles["Precompiles<br/>(Polkadot-specific features)"]
-        end
-        
-        REVM --> RPC
-        PVM --> RPC
-        RPC --> Tools
-        REVM --> Precompiles
-        PVM --> Precompiles
-    end
-    
-    Dev1["Ethereum Developers"] --> REVM
-    Dev2["Performance-Focused Developers"] --> PVM
+    Devs["Developers"] --> REVM["REVM (EVM-compatible)"]
+    Devs --> PVM["PolkaVM (RISC-V)"]
+    REVM --> Infra["Shared Infrastructure<br/>(Ethereum JSON-RPC, Tooling, Precompiles)"]
+    PVM --> Infra
 ```
 
-## REVM Backend: EVM Compatibility
-
-The REVM backend integrates a complete Ethereum Virtual Machine implementation, enabling Solidity contracts to run unchanged on Polkadot's smart contract platform.
-
-### Key Features
-
-- **Full EVM compatibility**: Execute unmodified Solidity contracts compiled to EVM bytecode
-- **Broad Solidity version support**: Compatible with multiple Solidity compiler versions, including older releases
-- **Familiar tooling**: Works seamlessly with Ethereum development tools like Hardhat and Foundry
-- **Standard bytecode**: Uses traditional EVM bytecode format, ensuring compatibility with existing tools and infrastructure
-
-### Architecture
+## REVM Backend
 
-```mermaid
-flowchart LR
-    Dev[Developer] --> |Solidity<br>Source| Solc[Solidity Compiler]
-    Solc --> |EVM<br>Bytecode| REVM[REVM Backend]
-    REVM --> |Execution| Runtime[pallet_revive Runtime]
-    Runtime --> Chain[Polkadot Chain]
-```
+The [REVM backend](https://github.com/bluealloy/revm){target=\_blank} integrates a complete Ethereum Virtual Machine implementation, enabling Solidity contracts to run unchanged on Polkadot's smart contract platform.
 
-### Use Cases
+This allows developers to use their existing Ethereum tooling and infrastructure to build on Polkadot.
 
 The REVM backend is ideal for:
 
-- **Quick migration**: Projects porting existing Ethereum dApps without code modifications
+- Quick migration: Projects porting existing Ethereum dApps without code modifications
 - **Established tooling**: Teams leveraging mature Ethereum development infrastructure
 - **Third-party integrations**: Applications requiring standard EVM bytecode inspection
 - **Compatibility requirements**: Contracts needing exact EVM behavior for audited code
 
-### Trade-offs
-
-While REVM provides seamless compatibility, developers should consider:
-
-- **Performance**: EVM's stack-based architecture may not match PVM's register-based efficiency
-- **Compute limits**: Bound by traditional EVM computational constraints
-- **Innovation path**: Limited to Ethereum's architectural decisions and evolution
-
-## PolkaVM (PVM) Backend: Performance & Innovation
-
-PolkaVM represents a next-generation virtual machine built on RISC-V architecture, optimized for high-performance smart contract execution while maintaining Solidity compatibility through the Revive compiler.
-
-### Core Architecture Differences
-
-PolkaVM introduces fundamental architectural improvements over the EVM:
-
-```mermaid
-flowchart TB
-    subgraph "EVM Architecture"
-        EVMStack[Stack-Based Operations]
-        EVM256[256-bit Word Size]
-        EVMGas[Single Gas Metric]
-    end
-    
-    subgraph "PolkaVM Architecture"
-        PVMReg[Register-Based Operations]
-        PVM64[64-bit Word Size]
-        PVMWeight[Multi-Dimensional Resources]
-    end
-    
-    EVMStack -.->|vs| PVMReg
-    EVM256 -.->|vs| PVM64
-    EVMGas -.->|vs| PVMWeight
-```
-
-#### Register-Based Design
-
-PolkaVM's RISC-V register-based approach provides several advantages:
-
-- **Hardware alignment**: Efficient translation to modern CPU architectures through simple 1:1 mapping to x86-64
-- **Optimized execution**: Reduced compilation complexity via strategic register limitation
-- **Performance gains**: Direct register allocation eliminates stack manipulation overhead
-
-#### 64-bit Word Size
-
-Operating with native 64-bit words enables:
-
-- **Hardware-supported operations**: Direct arithmetic without emulation overhead
-- **Compatibility preservation**: Maintains Solidity's 256-bit operations through YUL translation
-- **Mixed-language support**: Integration of performance-critical components in lower-level languages
-- **Reduced overhead**: Eliminates unnecessary precision costs for standard operations
-
-#### Multi-Dimensional Resource Metering
-
-Unlike EVM's single gas metric, PolkaVM meters three distinct resources:
-
-| Resource            | Purpose                                      | Comparison to EVM        |
-|:--------------------|:---------------------------------------------|:-------------------------|
-| **`ref_time`**      | Computational time (closest to gas)          | Similar to EVM gas       |
-| **`proof_size`**    | State proof size for validator verification  | No EVM equivalent        |
-| **`storage_deposit`** | State bloat management through deposits    | Partially similar to gas |
-
-All resources can be limited at the transaction level, and the Ethereum RPC proxy maps all three dimensions into the single gas dimension for seamless user experience.
-
-### Compilation Process
-
-PolkaVM contracts go through a sophisticated compilation pipeline:
-
-```mermaid
-flowchart LR
-    Dev[Developer] --> |Solidity<br>Source| Solc[solc Compiler]
-    Solc --> |YUL IR| Revive[Revive Compiler]
-    Revive --> |LLVM IR| LLVM[LLVM Optimizer]
-    LLVM --> |RISC-V ELF| Linker[PVM Linker]
-    Linker --> |PVM Blob<br>+ Metadata| Deploy[Deployment]
-```
-
-The process integrates:
-
-1. **Solc**: Standard Solidity compiler producing YUL intermediate representation
-2. **Revive Compiler**: Transforms YUL IR to LLVM IR for optimization
-3. **LLVM**: Industry-standard compiler infrastructure providing optimization passes
-4. **PVM Linker**: Produces final PolkaVM blob with metadata
-
-### Execution Model
-
-PolkaVM features dual-mode execution for optimal performance:
-
-- **Interpreter**: Immediate code execution without compilation overhead, ideal for short-running contracts
-- **JIT Compiler** (planned): Advanced just-in-time compilation for compute-intensive workloads
-- **Lazy interpretation**: Eliminates upfront compilation costs for contracts with minimal execution
-
-### Key Features
-
-#### Performance Optimizations
+## PolkaVM Backend
 
-- **Benchmark-based pricing**: Gas values reflect actual execution costs, making computation cheaper relative to I/O
-- **Efficient instruction set**: RISC-V instructions map directly to hardware operations
-- **Reduced overhead**: Register-based design eliminates stack manipulation costs
+[PolkaVM](https://github.com/paritytech/polkavm){target=\_blank} represents a next-generation virtual machine built on [RISC-V](https://en.wikipedia.org/wiki/RISC-V){target=\_blank} architecture, optimized for high-performance smart contract execution while maintaining Solidity compatibility through the Revive compiler.
 
-#### Advanced Memory Management
+### Core PVM concepts
 
-PolkaVM implements fixed memory limits per contract:
-
-| Limit                                        | Maximum     |
-|:---------------------------------------------|:------------|
-| Call stack depth                             | 5           |
-| Event topics                                 | 4           |
-| Event data payload size (including topics)   | 416 bytes   |
-| Storage value size                           | 416 bytes   |
-| Transient storage variables                  | 128 uint    |
-| Immutable variables                          | 16 uint     |
-| Contract code blob size                      | ~100 KB     |
-
-This approach:
-
-- Provides predictable resource usage for contract nesting calculations
-- Enables clear capacity planning for developers
-- Eliminates dynamic memory pricing complexity
-- May be enhanced with dynamic metering in future iterations
-
-#### On-Chain Constructors
-
-PolkaVM introduces an elegant alternative to runtime code modification:
-
-- Enables contract instantiation without modifying bytecode
-- Requires code to be pre-uploaded before instantiation
-- Supports factory patterns through code hash references
-- Eliminates security risks from runtime code generation
-
-### Use Cases
-
-The PVM backend excels for:
-
-- **Compute-intensive applications**: Games, simulations, complex algorithms
-- **Performance-critical contracts**: High-throughput DeFi protocols
-- **Innovation-focused projects**: Leveraging Polkadot-specific capabilities
-- **Long-term optimization**: Projects prioritizing execution efficiency
-
-### Important Considerations
-
-#### Bytecode Differences
-
-- **Format**: RISC-V bytecode instead of EVM bytecode
-- **Inspection tools**: Standard EVM tools cannot parse PVM bytecode
-- **Code introspection**: Limited `EXTCODECOPY` support, replaced by on-chain constructors
-
-#### Deployment Model
-
-PVM follows a two-step deployment process:
-
-1. **Code upload**: Contract bytecode must be uploaded to the chain first
-2. **Instantiation**: Contracts reference pre-uploaded code via hash
-
-This affects:
-
-- Factory contract patterns (must reference uploaded code hashes)
-- Dynamic contract creation (requires pre-uploaded dependencies)
-- Runtime code generation (not supported)
-
-#### Gas Model Adaptations
-
-- **Dynamic pricing**: Gas values are benchmark-based, not fixed
-- **Cross-contract calls**: Resource limits forwarded automatically, not manually specified
-- **Reentrancy protection**: Cannot rely on gas stipends; must implement explicit guards
+- **Architecture**: Register-based RISC-V VM with native 64-bit words. Solidity is supported via Revive/LLVM, offering lower overhead than the EVM's stack-based, 256-bit design.
+- **Resources (pricing)**: Dimensions like `ref_time` (compute), `proof_size` (state proof), `storage_deposit` (state bloat) are mapped to a single gas number at the RPC layer.
+- **Execution**: Interpreter at the time of writing; JIT planned for heavy workloads. Lazy interpretation avoids upfront compilation cost.
+- **Deployment**: Two-step flow. First upload code, and then instantiate by code hash. On-chain constructors replace runtime code generation (no dynamic codegen).
+- **Limits**: Fixed caps (stack depth, event topics/data, storage value size, transient/immutable vars, code size) for predictable nesting and capacity planning.
+- **Tooling/bytecode**: Ethereum JSON-RPC and common tooling work. PVM bytecode is RISC-V (EVM bytecode inspectors won't parse); limited `EXTCODECOPY`.
+- **Calls and safety**: Cross-contract calls forward resource limits automatically. Use explicit reentrancy guards; do not rely on gas stipends. Pricing is benchmark-based, making compute cheaper relative to I/O.
 
 ## Choosing the Right Backend
 
 The dual-stack architecture allows developers to select the optimal backend based on their specific requirements:
 
-### Choose REVM When:
-
-- Migrating existing Ethereum contracts without modifications
-- Requiring exact EVM behavior for audited code
-- Using tools that inspect EVM bytecode
-- Prioritizing rapid deployment over optimization
-- Working with established Ethereum infrastructure
-
-### Choose PolkaVM When:
-
-- Building performance-critical applications
-- Requiring intensive computation (games, simulations)
-- Optimizing for lower execution costs
-- Leveraging Polkadot-specific features
-- Focusing on long-term platform innovation
-
-### Shared Capabilities
-
-Both backends provide:
-
-- **Ethereum JSON-RPC**: Standard interface for wallets and dApps
-- **Development tooling**: Hardhat and Foundry compatibility
-- **Precompiles**: Access to Polkadot-specific functionality (XCM, etc.)
-- **18-decimal DOT**: Aligned with Ethereum conventions
-
-```mermaid
-graph LR
-    subgraph "Decision Factors"
-        Compat[EVM Compatibility Required?]
-        Perf[Performance Critical?]
-        Tools[Existing EVM Tooling?]
-        Compute[High Compute Needs?]
-    end
-    
-    Compat -->|Yes| REVM[Choose REVM]
-    Compat -->|No| Perf
-    Perf -->|Yes| PVM[Choose PolkaVM]
-    Perf -->|No| Tools
-    Tools -->|Yes| REVM
-    Tools -->|No| Compute
-    Compute -->|Yes| PVM
-    Compute -->|No| Either[Either Backend Suitable]
-```
-
-## Architecture Comparison Summary
-
-| Feature                  | REVM Backend                           | PolkaVM Backend                        |
-|:-------------------------|:---------------------------------------|:---------------------------------------|
-| **Instruction Set**      | Stack-based EVM                        | Register-based RISC-V                  |
-| **Bytecode Format**      | Standard EVM bytecode                  | RISC-V format                          |
-| **Compiler**             | Standard Solidity compiler             | Revive compiler (Solidity support)     |
-| **Performance**          | Traditional EVM performance            | Optimized via register-based design    |
-| **Memory Model**         | Dynamic with gas costs                 | Fixed limits per contract              |
-| **Resource Metering**    | Single gas metric                      | Multi-dimensional (ref_time, proof_size, storage_deposit) |
-| **Contract Deployment**  | Single-step deployment                 | Two-step: upload then instantiate      |
-| **Code Introspection**   | Full EXTCODECOPY support               | Limited, alternatives via constructors |
-| **Reentrancy Protection**| Gas stipends provide basic protection  | Requires explicit guards               |
-| **Tooling Compatibility**| Native EVM tool support                | Requires Revive-aware tools            |
-| **Solidity Versions**    | All versions                           | Via-IR compilation mode                |
-| **Innovation Path**      | Follows Ethereum evolution             | Polkadot-native optimizations          |
-
-## Future Development
-
-Both backends continue to evolve:
-
-### REVM Roadmap
-
-- Enhanced gas mapping alignment with PVM
-- Ethereum block storage optimization
-- Expanded precompile library
-- Performance benchmarking against reference implementations
-
-### PolkaVM Roadmap
-
-- JIT compiler implementation for advanced optimization
-- Dynamic memory metering for deeper contract nesting
-- Additional language support beyond Solidity
-- Extended precompile ecosystem
-
-### Shared Infrastructure
-
-- Anvil-compatible local test nodes
-- Comprehensive test suites from major Ethereum applications
-- Differential testing against reference implementations
-- Stress testing and benchmarking tools
+- Choose REVM when:
 
-## Getting Started
+    - Migrating existing Ethereum contracts without modifications
+    - Requiring exact EVM behavior for audited code
+    - Using tools that inspect EVM bytecode
+    - Prioritizing rapid deployment over optimization
+    - Working with established Ethereum infrastructure
 
-Developers can begin building on either backend:
+- Choose PolkaVM when:
 
-1. **Development environment**: Set up Hardhat or Foundry with Polkadot smart contract platform
-2. **Backend selection**: Choose REVM for compatibility or PVM for performance
-3. **Local testing**: Use Anvil-compatible test nodes for both backends
-4. **Deployment**: Deploy to testnet (Kusama) before mainnet (Polkadot)
+    - Building performance-critical applications
+    - Requiring intensive computation
+    - Optimizing for lower execution costs
 
 The dual-stack architecture ensures developers have the flexibility to optimize for their specific use case while maintaining access to Polkadot's advanced capabilities through shared infrastructure and precompiles.