Metadata-Version: 2.2
Name: tsrkit-pvm
Version: 0.2.1
Summary: Polkadot Virtual Machine (PVM) implementation with interpreter and recompiler as specified in GP
Author-email: Chainscore Labs <hello@chainscore.finance>
License: MIT
Project-URL: Homepage, https://github.com/Chainscore/tsrkit-pvm
Project-URL: Repository, https://github.com/Chainscore/tsrkit-pvm
Project-URL: Issues, https://github.com/Chainscore/tsrkit-pvm/issues
Keywords: polkadot,pvm,virtual-machine,blockchain,jam,recompiler,interpreter
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Cython
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tsrkit-types<2.0.0,>=0.1.9
Requires-Dist: tsrkit-asm>=0.1.0
Requires-Dist: bitarray<4.0.0,>=3.7.1
Requires-Dist: setuptools>=80.9.0
Requires-Dist: mypy>=1.18.1
Requires-Dist: cython>=3.1.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# Tessera PVM

Tessera PVM is a Python implementation of the Tessera virtual machine, offering two execution modes: a straightforward interpreter and a more performant recompiler.

## Project Structure

-   `tsrkit_pvm/`: The main package.
    -   `core/`: Abstract base classes and core PVM components.
    -   `common/`: Shared utilities and data structures.
    -   `interpreter/`: The interpreter-based PVM implementation.
    -   `recompiler/`: The recompiler-based PVM implementation.
-   `tests/`: The project's test suite, which includes PVM test cases and schemas.

## Core Components

The fundamental building blocks of the PVM are defined in `tsrkit_pvm/core/`:

-   `ipvm.py`: Contains the `PVM` abstract base class.
-   `program_base.py`: Defines the base class for PVM programs.
-   `memory.py`: Provides the base class for memory management.

## Implementations

1.  **Interpreter**: Located in `tsrkit_pvm/interpreter/`, this implementation executes bytecode instruction by instruction. It is easier to debug and inspect.
2.  **Recompiler**: Found in `tsrkit_pvm/recompiler/`, this implementation recompiles PVM bytecode into native machine code for significantly faster execution.

## Installation

Install the package using pip:

```bash
pip install .
```

## Usage

The primary way to run a PVM program is to use the static `execute` method on either the `Interpreter` or `Recompiler` class.

Here is a corrected example of how to execute a PVM program with the interpreter:

```python
from tsrkit_pvm.interpreter.pvm import Interpreter
from tsrkit_pvm.interpreter.program import Program
from tsrkit_pvm.interpreter.memory import INT_Memory
from tsrkit_pvm.common.status import ExecutionStatus

# Your PVM bytecode
bytecode = bytes([0, 0, 14, 40, 2, 200, 50, 1, 40, 2, 200, 67, 2, 51, 1, 40, 246, 165, 20])

# 1. Decode the bytecode into a Program object
# The `decode` method returns a single Program instance.
program = Program.decode(bytecode)

# 2. Initialize memory, registers, and gas
# INT_Memory takes a dictionary for initial memory, a list for input, and a list for output.
memory = INT_Memory({}, [], [])
registers = [0] * 13  # PVM has 13 registers
gas = 100_000

# 3. Execute the program
status, final_pc, remaining_gas, final_registers, final_memory = Interpreter.execute(
    program=program,
    program_counter=0,
    gas=gas,
    registers=registers,
    memory=memory
)

# 4. Check the result
if status == ExecutionStatus.OUT_OF_GAS:
    print("Execution finished: Out of gas.")
    print(f"Gas consumed: {gas - remaining_gas}")
else:
    print(f"Execution finished with status: {status}")

```

## Testing

To run the comprehensive test suite and verify the functionality of both the interpreter and recompiler, use `pytest`:

```bash
poetry run pytest
```
