PVM

PVM (Polkadot Virtual Machine)

The jam.pvm module implements the Polkadot Virtual Machine (PVM), which provides the execution environment for smart contracts and services in Tessera.

PVM Components

The PVM implementation consists of several key components:

Virtual Machine

The core VM for executing WebAssembly (Wasm) code:

• Wasm Runtime: Execute WebAssembly bytecode
• Memory Management: Manage memory allocation and access
• Instruction Execution: Execute Wasm instructions
• Stack Machine: Implement the Wasm stack machine

Host Functions

Host functions provide the interface between the VM and the node:

• Storage Access: Read and write state storage
• Cryptographic Operations: Access cryptographic primitives
• Environmental Information: Access chain and block information
• Logging and Debugging: Emit logs and debug information

Contract Interface

The contract interface manages interaction with smart contracts:

• Contract Deployment: Deploy new contracts to the chain
• Contract Execution: Execute contract methods
• Contract Upgrades: Handle contract upgrades and migrations
• Contract State: Manage contract state

Usage

from jam.pvm import PVM, ContractExecutor

# Initialize PVM
pvm = PVM()

# Deploy a contract
contract_code = load_wasm_code("contract.wasm")
contract_address = pvm.deploy_contract(contract_code, constructor_args=[42])

# Execute a contract method
result = pvm.execute_contract(
    contract_address,
    method="transfer",
    args=["0xalice", "0xbob", 100]
)

# Use the contract executor for more options
executor = ContractExecutor(pvm)
result = executor.execute(
    contract_address,
    method="transfer",
    args=["0xalice", "0xbob", 100],
    gas_limit=1000000,
    value=0
)

Contract Lifecycle

The PVM manages the full lifecycle of a contract:

1. Compilation: Compile high-level language to Wasm
2. Deployment: Deploy Wasm bytecode to the chain
3. Initialization: Initialize contract state
4. Execution: Execute contract methods
5. Upgrades: Upgrade contract code when needed
6. Termination: Terminate and remove contracts

Gas System

The PVM includes a gas system to limit computation:

• Gas Metering: Track resource usage during execution
• Gas Limits: Enforce maximum gas usage
• Gas Pricing: Calculate gas costs for operations

# Execute with gas limit
result = pvm.execute_contract(
    contract_address,
    method="complex_calculation",
    args=[input_data],
    gas_limit=1000000
)

# Check gas usage
print(f"Gas used: {result.gas_used}")

Error Handling

The PVM provides detailed error handling:

from jam.pvm import PVMError, ContractError

try:
    result = pvm.execute_contract(
        contract_address,
        method="transfer",
        args=["0xalice", "0xbob", 100]
    )
except ContractError as e:
    # Contract-specific error
    print(f"Contract error: {e}")
except PVMError as e:
    # General PVM error
    print(f"PVM error: {e}")

Advanced Features

Precompiles

The PVM includes precompiled contracts for common operations:

• Cryptography: Elliptic curve operations, hashing
• Verification: Signature verification
• Data Structures: Merkle tree operations

Contract Development

The module provides tools for contract development:

from jam.pvm import ContractTester

# Create a contract tester
tester = ContractTester(contract_code)

# Test a method
result = tester.test_method(
    method="transfer",
    args=["0xalice", "0xbob", 100],
    initial_state={"balances": {"0xalice": 1000, "0xbob": 500}}
)

# Assert on the result
assert result.success
assert result.return_value == True
assert result.state["balances"]["0xalice"] == 900
assert result.state["balances"]["0xbob"] == 600