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), a rules/scripting layer, a safe expression evaluator, or a hands-on way to learn how virtual machines work.

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

pip install larzvm

The machine

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

Assembly with labels

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

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:

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

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

The Larz stack

Pure-Python, zero-dependency building blocks:

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

License

MIT © larz-scripter