CLVM: Chia Contract Language Virtual Machine

0.9.15 · active · verified Fri Apr 17

CLVM is the Python implementation of the Contract Language (Chialisp) Virtual Machine, a core component of the Chia blockchain. It provides the low-level logic for evaluating Chialisp programs, handling s-expression data structures, and executing CLVM opcodes. Currently at version 0.9.15, it receives regular updates, often in sync with the broader Chia ecosystem, to enhance security, performance, and type correctness.

Common errors

```
TypeError: 'int' object is not callable
```
cause Attempting to pass a native Python integer directly as a program argument to `run_program` or an `SExp` method.

fix Convert the integer to an `SExp` object first. For example, `args = assemble('(5)')` or `args = SExp.to(5)`.
```
NameError: name 'assemble' is not defined
```
cause The `assemble` function for compiling Chialisp code is part of the `clvm_tools` package and needs to be explicitly imported.

fix Add the import: `from clvm_tools.binutils import assemble`.
```
clvm.clvm_tools.binutils.assemble.AssembleError: bad expression
```
cause The Chialisp code provided to `assemble` contains syntax errors, such as unbalanced parentheses, invalid atoms, or incorrect operator usage.

fix Carefully review the Chialisp string for syntactical correctness. Chialisp follows s-expression rules, requiring balanced parentheses and valid atom definitions.
```
ModuleNotFoundError: No module named 'clvm_tools'
```
cause The `clvm_tools` package, which provides essential utilities like `assemble` and `disassemble`, is a separate dependency and has not been installed.

fix Install `clvm_tools` via pip: `pip install clvm_tools`.

Warnings

gotcha Uncontrolled serialization size can lead to denial-of-service. Functions like `clvm.serialize` and `SExp.as_bin` now support a `max_size` parameter to limit the output size.
Fix: Always specify `max_size` when serializing CLVM objects from untrusted sources or when there's a risk of maliciously large data. Example: `result.as_bin(max_size=1024 * 1024)`.
gotcha CLVM operations exclusively use `SExp` objects. Directly passing native Python integers, bytes, or strings where an `SExp` is expected will raise `TypeError` or produce incorrect results.
Fix: Convert all program inputs and outputs to `SExp` using `Program.to(...)`, `SExp.to(...)`, or `clvm_tools.binutils.assemble` (e.g., `args = assemble('(5)')`).
gotcha The `clvm` library provides the core Virtual Machine. To assemble Chialisp code from human-readable text into CLVM program objects, you *must* also install and import from `clvm_tools` (e.g., `from clvm_tools.binutils import assemble`).
Fix: Ensure `clvm_tools` is installed (`pip install clvm_tools`) and correctly import `assemble` from `clvm_tools.binutils`.

Install

pip install clvm Install core CLVM library
pip install clvm clvm_tools Install CLVM and Chialisp assembly tools

Imports

SExp
```
from clvm.SExp import SExp
```
Program
```
from clvm.Program import Program
```
run_program
```
from clvm.operators import run_program
```
assemble
wrong:
```
from clvm import assemble
```
correct:
```
from clvm_tools.binutils import assemble
```
The 'assemble' function for compiling Chialisp is part of the 'clvm_tools' package, not 'clvm' itself. It needs to be installed separately.

Quickstart

This quickstart demonstrates how to compile a Chialisp program using `clvm_tools.binutils.assemble`, prepare arguments as `SExp` objects, and execute the program using `clvm.operators.run_program`. It also shows how to interpret the `SExp` result.

from clvm.SExp import SExp
from clvm.operators import run_program
from clvm_tools.binutils import assemble

# Define a simple Chialisp program: multiply an argument by 2
chialisp_code = '(mod (X) (* X 2))'
program = assemble(chialisp_code)

# Define arguments for the program as an SExp object (e.g., 5)
args = assemble('(5)') # Arguments must also be assembled or created as SExp

# Run the program
cost, result = run_program(program, args)

print(f"Chialisp program: {chialisp_code}")
print(f"Arguments: {args.as_python()}")
print(f"Execution Cost: {cost}")
print(f"Result: {result.as_int()}") # Convert the SExp result back to a Python int

# Example 2: Simple addition of two numbers provided as constants in the program
chialisp_code_add = '(+ 2 3)'
program_add = assemble(chialisp_code_add)

# For this program, no external arguments are needed
cost_add, result_add = run_program(program_add, assemble('()'))

print(f"\nChialisp program: {chialisp_code_add}")
print(f"Execution Cost: {cost_add}")
print(f"Result: {result_add.as_int()}")

view raw JSON →