CLVM Tools

Common errors

• ModuleNotFoundError: No module named 'clvm_tools.clvm_tools.binutils'

  cause Attempting to import modules based on the repository's internal folder structure rather than the installed package's top-level module.
  fix The correct import path for installed packages is `from clvm_tools.binutils import ...`. The nested `clvm_tools` folder is part of the internal source structure, not the importable package name.

• TypeError: 'Program' object is not callable

  cause Attempting to execute a CLVM program that returns an invalid type or when program arguments are incorrectly formatted for the CLVM runtime.
  fix Ensure your CLVM program's return value is handled correctly by `brun` or subsequent operations. Verify that arguments passed to `brun` are correctly wrapped in `clvm.Program.to((arg1, arg2, ...))`.

• ValueError: CLVM compilation failed: ...

  cause The input CLVM source code contains a syntax error, an undefined opcode, or other structural issues preventing successful compilation.
  fix Carefully review your CLVM source code for typos, incorrect Lisp syntax (e.g., mismatched parentheses), or invalid opcodes. Use a CLVM linter or debugger if available, and consult official CLVM specifications.

Warnings

• gotcha Performance of CLVM execution can be significantly slower without the `clvm_rs` backend. The `clvm-tools` library defaults to a pure Python backend unless `clvm_rs` (or `clvm_tools_rs`) is installed.
  Fix: Install `clvm-tools` with the recommended performance dependencies: `pip install clvm-tools[clvm_rs]`.
• breaking Compatibility with `clvm_rs` can be sensitive to version mismatches. Upgrading `clvm_rs` independently of `clvm-tools` might lead to runtime errors or unexpected behavior due to API changes.
  Fix: Ensure `clvm-tools` and `clvm_rs` versions are compatible. It's often best to install `clvm-tools` using its `clvm_rs` extra (`pip install clvm-tools[clvm_rs]`) to ensure compatible versions are pulled in. Pin dependency versions in your `requirements.txt`.
• gotcha Debugging syntax errors in CLVM code can be challenging as error messages from `assemble` might be terse or difficult to pinpoint to the exact line/token in complex programs.
  Fix: Develop CLVM code incrementally, test small components, and leverage `disassemble` to understand the compiled output. Refer to the official CLVM documentation for syntax specifics.

Install

• pip install clvm-tools Install core library
• pip install clvm-tools[clvm_rs] Install with CLVM_RS backend for performance

Imports

• assemble
  wrong:

  from clvm_tools.clvm_tools.binutils import assemble

  correct:

  from clvm_tools.binutils import assemble

  The canonical import path is `clvm_tools.binutils` after installation, despite the source code's nested `clvm_tools/clvm_tools` directory structure.
• brun

  from clvm_tools.binutils import brun

  Used for running compiled CLVM programs with arguments.
• disassemble

  from clvm_tools.binutils import disassemble

  Used to convert compiled CLVM back into human-readable code.

Quickstart

This quickstart demonstrates how to compile a basic CLVM program using `assemble` and then execute it using `brun`. It shows how to pass arguments to the CLVM program and interpret the result. For production use, consider installing `clvm-tools` with the `clvm_rs` extra for performance.

from clvm_tools.binutils import assemble, brun
from clvm.Program import Program

# A simple CLVM program that adds 1 to its argument
clvm_source_code = "(mod (A) (+ A 1))"

# Compile the CLVM source code
compiled_program_bytes = assemble(clvm_source_code)
print(f"Compiled CLVM (hex): {compiled_program_bytes.hex()}")

# Define the arguments for the program (e.g., A = 5)
program_arguments = Program.to((5,))

# Run the compiled program with the arguments
# `brun` can leverage clvm_rs if installed for better performance.
result = brun(compiled_program_bytes, program_arguments)

print(f"Result of program with A=5: {result.as_int()}")