Metadata-Version: 2.4
Name: cashscript-py
Version: 1.0.1
Summary: Python SDK for Bitcoin Cash (BCH) CashScript smart contracts.
Author: CashScript-Py contributors
Maintainer: CashScript-Py maintainers
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: bitcash~=1.1.1
Requires-Dist: coincurve~=21.0.0
Requires-Dist: semver~=3.0.4
Requires-Dist: typing-extensions~=4.15.0
Description-Content-Type: text/markdown

# CashScript-Py

CashScript-Py is a Python SDK for Bitcoin Cash (BCH) smart contract development. It is a port of the original TypeScript
[CashScript SDK](https://cashscript.org/). The goal is to enable Python developers (e.g., those working on server-side
tools, bots, and Electron Cash plugins) to construct and interact with smart contracts on the BCH blockchain without
re-implementing common low-level details.

This project is actively maintained and ready for experimentation and integration. Expect occasional breaking changes as
features evolve.

CashScript-Py builds on earlier work by Jonald Fyookball on the
[anyhedge-ec-plugin](https://github.com/fyookball/anyhedge-ec-plugin).

Note: CashScript-Py currently targets real networks (including chipnet, a public BCH testnet). A fully local mock network
provider (mocknet) is not available yet. For experiments and tests on chipnet, this repo includes
`cashscript_py_support.utils` and uses `FAUCET_WIF` to reduce funding/cleanup boilerplate.

## Installation

Install from PyPI:

```bash
pip install cashscript-py
```

If you use `uv`:

```bash
uv add cashscript-py
```

## Minimal example

```python
from cashscript_py import Contract, ElectrumNetworkProvider, SignatureTemplate, TransactionBuilder

provider = ElectrumNetworkProvider("chipnet")
contract = Contract(artifact, constructor_args, provider)

unlocker = contract.unlock["spend"](SignatureTemplate(alice_wif))
builder = TransactionBuilder(provider).add_input(contract_utxo, unlocker).add_output(...)
tx_hex = builder.build()
print(tx_hex)
```

## Documentation

- Getting started guide: https://gitlab.com/cashscript-py/cashscript-py/-/blob/master/docs/guide/getting-started.md
- Runnable examples: `examples/` (e.g. `uv run python examples/op_return_memo.py`, `uv run python examples/hodl_vault.py`)
- API docs (Sphinx): see `docs/` and https://gitlab.com/cashscript-py/cashscript-py/-/blob/master/STYLEGUIDE.md
- SDK user guide (in development): link to be added

## Developer notes

### Prerequisites:
  - Python 3.11 or above
  - uv installed (recommended via pipx or Homebrew)
    - pipx: `pipx install uv`
    - Homebrew (macOS/Linux): `brew install uv`

### Environment setup (using uv):
  - Create a virtual environment:
    - `uv venv`
  - Activate the environment:
    - Linux/macOS: `source .venv/bin/activate`
    - Windows (PowerShell): `.venv\Scripts\Activate.ps1`
  - Install dependencies from pyproject.toml:
    - Runtime dependencies only: `uv sync`
    - With development tools (ruff, pytest, sphinx): `uv sync --group dev`

### Debugging
For runtime debug output (e.g., preimage/sighash/signature/script details), set:
  - Linux/macOS: `export CASHSCRIPT_PY_DEBUG=1`
  - Windows (PowerShell): `$env:CASHSCRIPT_PY_DEBUG = "1"`

### Testing:
  - Run tests with: `uv run pytest`

### Coding standards and development process:
  - See: https://gitlab.com/cashscript-py/cashscript-py/-/blob/master/STYLEGUIDE.md

## Acknowledgements
- Original CashScript SDK: https://cashscript.org/
- AnyHedge Plugin: https://github.com/fyookball/anyhedge-ec-plugin
- Bitcash library: https://pybitcash.github.io/bitcash/
