{"id":9591,"library":"clvm","title":"CLVM: Chia Contract Language Virtual Machine","description":"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.","status":"active","version":"0.9.15","language":"en","source_language":"en","source_url":"https://github.com/Chia-Network/clvm","tags":["blockchain","chia","chialisp","virtual-machine","cryptocurrency","smart-contracts"],"install":[{"cmd":"pip install clvm","lang":"bash","label":"Install core CLVM library"},{"cmd":"pip install clvm clvm_tools","lang":"bash","label":"Install CLVM and Chialisp assembly tools"}],"dependencies":[{"reason":"Rust-accelerated CLVM runtime for performance.","package":"clvm_rs","optional":false},{"reason":"Provides Chialisp assembly/disassembly utilities (e.g., 'assemble'). Essential for working with human-readable Chialisp.","package":"clvm_tools","optional":false},{"reason":"Required for BLS signature operations within CLVM programs.","package":"bls-signatures","optional":false},{"reason":"Rust bindings for various Chia primitives.","package":"chia_rs","optional":false}],"imports":[{"symbol":"SExp","correct":"from clvm.SExp import SExp"},{"symbol":"Program","correct":"from clvm.Program import Program"},{"symbol":"run_program","correct":"from clvm.operators import run_program"},{"note":"The 'assemble' function for compiling Chialisp is part of the 'clvm_tools' package, not 'clvm' itself. It needs to be installed separately.","wrong":"from clvm import assemble","symbol":"assemble","correct":"from clvm_tools.binutils import assemble"}],"quickstart":{"code":"from clvm.SExp import SExp\nfrom clvm.operators import run_program\nfrom clvm_tools.binutils import assemble\n\n# Define a simple Chialisp program: multiply an argument by 2\nchialisp_code = '(mod (X) (* X 2))'\nprogram = assemble(chialisp_code)\n\n# Define arguments for the program as an SExp object (e.g., 5)\nargs = assemble('(5)') # Arguments must also be assembled or created as SExp\n\n# Run the program\ncost, result = run_program(program, args)\n\nprint(f\"Chialisp program: {chialisp_code}\")\nprint(f\"Arguments: {args.as_python()}\")\nprint(f\"Execution Cost: {cost}\")\nprint(f\"Result: {result.as_int()}\") # Convert the SExp result back to a Python int\n\n# Example 2: Simple addition of two numbers provided as constants in the program\nchialisp_code_add = '(+ 2 3)'\nprogram_add = assemble(chialisp_code_add)\n\n# For this program, no external arguments are needed\ncost_add, result_add = run_program(program_add, assemble('()'))\n\nprint(f\"\\nChialisp program: {chialisp_code_add}\")\nprint(f\"Execution Cost: {cost_add}\")\nprint(f\"Result: {result_add.as_int()}\")","lang":"python","description":"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."},"warnings":[{"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)`.","message":"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.","severity":"gotcha","affected_versions":"<0.9.13"},{"fix":"Convert all program inputs and outputs to `SExp` using `Program.to(...)`, `SExp.to(...)`, or `clvm_tools.binutils.assemble` (e.g., `args = assemble('(5)')`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure `clvm_tools` is installed (`pip install clvm_tools`) and correctly import `assemble` from `clvm_tools.binutils`.","message":"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`).","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Convert the integer to an `SExp` object first. For example, `args = assemble('(5)')` or `args = SExp.to(5)`.","cause":"Attempting to pass a native Python integer directly as a program argument to `run_program` or an `SExp` method.","error":"TypeError: 'int' object is not callable"},{"fix":"Add the import: `from clvm_tools.binutils import assemble`.","cause":"The `assemble` function for compiling Chialisp code is part of the `clvm_tools` package and needs to be explicitly imported.","error":"NameError: name 'assemble' is not defined"},{"fix":"Carefully review the Chialisp string for syntactical correctness. Chialisp follows s-expression rules, requiring balanced parentheses and valid atom definitions.","cause":"The Chialisp code provided to `assemble` contains syntax errors, such as unbalanced parentheses, invalid atoms, or incorrect operator usage.","error":"clvm.clvm_tools.binutils.assemble.AssembleError: bad expression"},{"fix":"Install `clvm_tools` via pip: `pip install clvm_tools`.","cause":"The `clvm_tools` package, which provides essential utilities like `assemble` and `disassemble`, is a separate dependency and has not been installed.","error":"ModuleNotFoundError: No module named 'clvm_tools'"}]}