Chialisp Python Tools

Common errors

• ERROR: Could not build wheels for clvm-tools-rs, which is required to install pyproject.toml-based projects

  cause The underlying `clvm_tools_rs` Rust package could not be compiled because a Rust toolchain (compiler, cargo) is missing or misconfigured on your system.
  fix Install Rust and Cargo using `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` (Linux/macOS) or download from `rustup.rs`. Ensure Rust is in your system's PATH.

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

  cause The `chialisp` package is not installed in your current environment, or the import path is incorrect (e.g., a typo in `binutils`).
  fix Ensure `chialisp` is installed with `pip install chialisp`. Verify that your Python environment is active and the import statement matches official documentation.

• Error: Bad encoding for atom 2 2

  cause Invalid Chialisp syntax, incorrect data types, or a malformed expression provided to `assemble` or `compile_clvm`.
  fix Review the Chialisp program for correct syntax, valid opcodes, and appropriate atom encoding. Consult the official Chialisp documentation for syntax rules and examples.

Warnings

• gotcha Installation may fail if pre-compiled wheels for the `clvm_tools_rs` dependency are not available for your platform and a Rust toolchain is not installed on your system.
  Fix: Ensure you have a Rust toolchain (compiler and Cargo) installed before attempting to `pip install chialisp`. Refer to `rustup.rs` for installation instructions.
• gotcha The interpretation and compilation of Chialisp programs can change between versions due to updates in the underlying CLVM specification or compiler logic.
  Fix: Always test Chialisp programs with the specific `chialisp` library version intended for deployment. Consult Chia-Network documentation for CLVM specification changes.
• gotcha While `chialisp` depends on `clvm_tools_rs`, its core functionalities are exposed through the `chialisp.clvm_tools` namespace. Direct imports from `clvm_tools_rs` are generally not intended for external use and may lead to unexpected behavior or API instability.
  Fix: Always import compiler and assembly utilities from `chialisp.clvm_tools` (e.g., `from chialisp.clvm_tools.binutils import assemble`).

Install

• pip install chialisp Install latest version

Imports

• assemble

  from chialisp.clvm_tools.binutils import assemble

• disassembler

  from chialisp.clvm_tools.binutils import disassembler

• compile_clvm

  from chialisp.clvm_tools.clvmc import compile_clvm

  Primarily used for compiling Chialisp files (modules) rather than simple expressions. Expects file paths as arguments.

Quickstart

This quickstart demonstrates the core functionality of `chialisp` for assembling Chialisp source code into CLVM byte representations and disassembling CLVM bytes back into human-readable Chialisp. It uses the `assemble` and `disassembler` functions from `chialisp.clvm_tools.binutils`.

from chialisp.clvm_tools.binutils import assemble, disassembler

# Chialisp source code
chialisp_source = "(a (q 2 2) (q 1 3))"

# 1. Assemble Chialisp source into a CLVM program (bytes)
print(f"Original Chialisp source: {chialisp_source}")
assembled_program = assemble(chialisp_source)
print(f"Assembled CLVM program (bytes): {assembled_program.hex()}")

# 2. Disassemble a CLVM program back into Chialisp source (approximate)
disassembled_source = disassembler(assembled_program)
print(f"Disassembled Chialisp source: {disassembled_source}")

# Example with a slightly more complex structure
complex_source = "(a (q . 1) (q (a (q 2 2) (q 1 3)) (c (q 5) (q 1))))"
assembled_complex = assemble(complex_source)
print(f"\nComplex Chialisp source: {complex_source}")
print(f"Assembled complex program (bytes): {assembled_complex.hex()}")
print(f"Disassembled complex program: {disassembler(assembled_complex)}")