pyhalsimplicity 0.1.0

Python bindings and CLI for hal-simplicity via PyO3

hal-simplicity -- a Simplicity-enabled extension of hal -- python interface

This is a fork of Blockstreams hal-simplicity which in turn is a fork of Steven Roose's hal-elements which in turn is an extension of his Bitcoin tool hal.

This project is a research study to create a convinient python interface to hal-simplicity

Usage (Python)

pyhalsimplicity provides Python bindings for the HAL-Simplicity library. You can invoke its CLI commands directly from Python using the run_cli_command function.

Installation

pip install pyhalsimplicity

Basic Example

import sys
import pyhalsimplicity

def main():
    # Setup logging (optional)
    pyhalsimplicity.setup_logger("info")
    
    # Prepare the CLI command as a space-separated string
    cli_args = sys.argv[1:]
    cmdline = " ".join(cli_args)
    
    # Execute the command
    result = pyhalsimplicity.run_cli_command(cmdline)
    
    print(result)

    # Uncomment to see the internal logger buffer
    # print(pyhalsimplicity.get_logs(), flush=True)

if __name__ == "__main__":
    main()

Example Usage

python example.py tx create ...
python example.py keypair generate

Features

• Run all built-in HAL-Simplicity CLI commands from Python.
• Capture logs via setup_logger and get_logs.
• Supports scripting HAL-Simplicity commands in Python workflows.

GitHub Repository

The source code and development repository is available at: https://github.com/coremoon/hal-simplicity

Please note that the sources have been forked from the original project https://github.com/blockstreamresearch/hal-simplicity

Installation (from GitHub source)

⚠️ This section is only relevant if you are building from the GitHub repository. If you installed pyhalsimplicity from PyPI, you can skip this.

To build the Python wheel and CLI binaries directly from source, follow these steps:

1. Build the complete Rust project The resulting binary (hal-simplicity or hal-simplicity.exe on Windows) will be in target/debug or target/release.

cargo build

2. Create and activate a Python virtual environment

python -m venv .venv
# Activate:
. .venv/bin/activate      # Linux / macOS
. .venv/Scripts/activate  # Windows (Git Bash)

3. Install Python dependencies using Poetry

poetry update

4. Build the Python wheel

• Debug wheel (located in target/wheels):

maturin build --manifest-path pyhalsimplicity/Cargo.toml

• Release wheel (optimized build):

maturin build --manifest-path pyhalsimplicity/Cargo.toml --release

5. Quick install of the newly built wheel

poetry run pip install --force-reinstall "$(ls -t target/wheels/pyhalsimplicity*.whl | head -n 1)"

6. Optional: run everything in one step via poe

poetry run poe build-wheel

7. Optional: decode a simplicity binary via poetry run python in the terminal try running

 poetry run python -m python.main simplicity info e4fba0509b4df120e1d320451f14172c46476646daf8d0d6da80e84c986cc5e073f80ed4dcf0210284187248126ac8e671544245742660022ae160c5e14b09ec0c2a17584bf5c548c85961c02b6efc010c03109ad2420c3f00140b16ab91cd75dcbc1e84ea7a320719cbfc6dc95e5194f9eca996d55a7b2d768c511e2a310e1806240a1241b70a35627302ef7da851f75a1f471748121a2b6978930a58ccaee2309401bd1b6e9fcbb0018601881a80e12071190284906e2a37159c2a162cdba0e67e0aad66c82658ec0c7f2a5a2cc38c3f61a892acd0da3a133ff9ead668873dc60c0310b5b0730445fea038d226980c2e6f7e4be9e895848d1fd97f2100db43004cb4eaddefc50601885c078170e6f13a1848e019ef88de2e7a3c1561d1828b3be0f290def9feebf54da94249472c0c0312050920fc8238dc861438a059b630e6ef256702d23cf92f32979f4fcd9ff3909cf7b32538aafb0e3a23ec40079b1d130c03103785c207e4c8201c5a072580e4e0

which should give

{
  "jets": "core",
  "commit_base64": "5PugUJtN8SDh0yBFHxQXLEZHZkba+NDW2oDoTJhsxeBz+A7U3PAhAoQYckgSasjmcVRCRXQmYAIq4WDF4UsJ7AwqF1hL9cVIyFlhwCtu/AEMAxCa0kIMPwAUCxarkc113LwehOp6MgcZy/xtyV5RlPnsqZbVWnstdoxRHioxDhgGJAoSQbcKNWJzAu99qFH3Wh9HF0gSGitpeJMKWMyu4jCUAb0bbp/LsAGGAYgagOEgcRkChJBuKjcVnCoWLNug5n4KrWbIJljsDH8qWizDjD9hqJKs0No6Ez/56tZohz3GDAMQtbBzBEX+oDjSJpgMLm9+S+nolYSNH9l/IQDbQwBMtOrd78UGAYhcB4Fw5vE6GEjgGe+I3i56PBVh0YKLO+DykN75/uv1TalCSUcsDAMSBQkg/II43IYUOKBZtjDm7yVnAtI8+S8yl59PzZ/zkJz3syU4qvsOOiPsQAebHRMMAxA3hcIH5MggHFoHJYDk4A==",
  "commit_decode": "(witness  & iden); (((unit; const 0xbe241c3a6408a3e282e588c8ecc8db5f1a1adb501d09930d98bc0e7f01da9b9e ) & iden); (((IOH; ((((false & unit); assertl drop jet_sha_256_ctx_8_init ) & iden); ((((false & (OH & IH)); assertl drop jet_sha_256_ctx_8_add_32 ) & iden); ((false & OH); assertl drop jet_sha_256_ctx_8_finalize )))) & iden); ((((false & ((false & (OH & IOH)); assertl drop jet_eq_256 )); assertl drop jet_verify ) & ((((false & unit); assertl drop jet_sig_all_hash ) & iden); ((false & ((IIIOH & OH) & witness )); assertl drop jet_bip_0340_verify ))); IH)))",
  "type_arrow": "1 → 1",
  "cmr": "7fd424f70498ef2fb6dd05ffbb7368dc796e6c47f24404e0b1ff138cfce89a7a",
  "liquid_address_unconf": "ex1pyuvwaqedernfdc7c6qf7r67en3szas6s0sdegzq3jxduhj4mhles29dz23",
  "liquid_testnet_address_unconf": "tex1pyuvwaqedernfdc7c6qf7r67en3szas6s0sdegzq3jxduhj4mhlestul9m7",
  "is_redeem": false
}

Once installed, you can use pyhalsimplicity in Python or run the hal-simplicity CLI directly.