Metadata-Version: 2.4
Name: larzvm
Version: 0.1.0
Summary: A deterministic, gas-metered stack virtual machine in pure Python — a smart-contract / sandboxed script engine. Zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzvm
Project-URL: Repository, https://github.com/larz-scripter/larzvm
Project-URL: Documentation, https://github.com/larz-scripter/larzvm#readme
Project-URL: Issues, https://github.com/larz-scripter/larzvm/issues
Keywords: vm,virtual-machine,bytecode,stack-machine,smart-contracts,interpreter,gas,deterministic,sandbox,blockchain,zero-dependency,pure-python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Interpreters
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# larzvm

**A deterministic, gas-metered stack virtual machine in pure Python. Zero dependencies.**

A sandboxed bytecode VM you can drop into anything that needs to run untrusted,
resource-bounded logic: a **smart-contract engine** for a blockchain (it's the
companion VM for [larzchain](https://github.com/larz-scripter/larzchain)), a
rules/scripting layer, a safe expression evaluator, or a hands-on way to learn
how virtual machines work.

```python
from larzvm import execute

r = execute("""
    PUSH 2
    PUSH 3
    ADD
    RETURN
""", gas_limit=1000)

r.returned      # 5
r.gas_used      # gas spent
```

## Why it's safe to run untrusted code

- **Deterministic.** No floats, no randomness, no wall clock — the current time
  is passed in through the execution context, so it's identical for everyone.
  The same program and inputs always produce the same result and the same gas
  cost on every machine. That's exactly the property a blockchain needs to reach
  consensus on contract execution.
- **Bounded.** Every opcode costs gas from a fixed table; when the budget runs
  out, execution stops with `OutOfGas`. There are no infinite loops — a loop just
  burns gas until the limit halts it.
- **Isolated.** A program can only touch its own stack, scratch memory, and a
  `storage` dict you hand it. No file system, no network, no host calls.

## Install

```bash
pip install larzvm
```

## The machine

A stack of arbitrary-precision integers, plus scratch **memory** and persistent
**storage**. Instructions:

| group | opcodes |
|---|---|
| stack | `PUSH n` `POP` `DUP d` `SWAP` `OVER` |
| arithmetic | `ADD` `SUB` `MUL` `DIV` `MOD` `NEG` `ABS` |
| comparison | `EQ` `NE` `LT` `GT` `LE` `GE` → push `1`/`0` |
| logic / bitwise | `AND` `OR` `NOT` `BAND` `BOR` `BXOR` |
| control flow | `JMP label` `JMPIF label` `JMPZ label` |
| memory / storage | `MLOAD` `MSTORE` `SLOAD` `SSTORE` |
| crypto / env | `HASH` (SHA-256) `CALLER` `VALUE` `TIMESTAMP` `HEIGHT` |
| output / halt | `EMIT` `RETURN` `STOP` `ASSERT` `REVERT` |

## Assembly with labels

You write readable text; the assembler resolves labels to jump targets so you
never count offsets. Comments start with `;` or `#`.

```python
from larzvm import execute

# store a value, guard it, and return it
program = """
    PUSH 1          ; slot
    PUSH 500        ; amount
    SSTORE          ; storage[1] = 500
    PUSH 1
    SLOAD           ; read it back
    DUP 0
    PUSH 0
    GT
    ASSERT          ; require amount > 0, else revert
    RETURN
"""
r = execute(program)
r.returned          # 500
r.storage[1]        # 500  (commit this if r.ok, discard if r.reverted)
```

## Contracts on a host

A host (like larzchain) runs a program with a gas budget, an execution context,
and the contract's current storage, then commits the results only if it
succeeded:

```python
from larzvm import VM, ExecutionContext

ctx = ExecutionContext(caller=0xABCD, value=10, timestamp=1690000000, height=42)
result = VM(gas_limit=50_000, context=ctx).run(program, storage=contract_state)

if result.ok:
    commit(result.storage)      # persist state changes
    for event in result.logs:   # EMITted values
        record(event)
else:
    discard()                   # reverted or out of gas -> no state change
```

Revert and faults (division by zero, failed `ASSERT`) are reported on the result
(`result.reverted`, `result.error`) so the host can roll back cleanly;
`OutOfGas` and genuinely malformed programs raise.

## Scope

larzvm is intentionally a small integer stack machine — the core needed for
deterministic, metered execution. It is not (yet) a full EVM with 256-bit words,
contract-to-contract calls, or a gas market. It's the solid, auditable core you'd
build those on, and a genuinely useful sandbox on its own.

## Tests

```bash
python -m unittest discover -s tests -v      # 41 tests, zero deps
```

## The Larz stack

Pure-Python, zero-dependency building blocks:

- **[larz](https://github.com/larz-scripter/larz)** — money-native web framework
- **[larzchain](https://github.com/larz-scripter/larzchain)** — from-scratch PoW blockchain
- **[larzmoney](https://github.com/larz-scripter/larzmoney)** — exact, penny-perfect money
- **[larzcrypt](https://github.com/larz-scripter/larzcrypt)** — pure-Python cryptography toolkit
- **[larzdb](https://github.com/larz-scripter/larzdb)** — crash-safe embedded database
- **[larzagent](https://github.com/larz-scripter/larzagent)** — zero-dep AI agent framework
- **[larzchart](https://github.com/larz-scripter/larzchart)** — data to inline SVG charts
- **[larzmark](https://github.com/larz-scripter/larzmark)** — Markdown + SEO static sites
- **[larztask](https://github.com/larz-scripter/larztask)** — durable background job queue
- **[larzvault](https://github.com/larz-scripter/larzvault)** — encrypted secrets manager
- **larzvm** — this VM

## License

MIT © larz-scripter
