Metadata-Version: 2.4
Name: xian-tech-contracting
Version: 1.0.5
Summary: Xian Network Python Contracting Engine
Author-email: Xian Network <info@xian.org>
License-Expression: GPL-3.0-only
Project-URL: Repository, https://github.com/xian-technology/xian-contracting
Keywords: blockchain,xian,contracting,python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: autopep8<2,>=1.5.7
Requires-Dist: cachetools<8,>=5
Requires-Dist: lmdb<3,>=1.6
Requires-Dist: pynacl<2,>=1.5.0
Requires-Dist: xian-tech-runtime-types<0.2,>=0.1.0
Provides-Extra: native
Requires-Dist: xian-tech-fastpath-core<0.2,>=0.1.0; extra == "native"
Requires-Dist: xian-tech-native-tracer<0.2,>=0.1.0; extra == "native"
Provides-Extra: zk
Requires-Dist: xian-tech-zk<0.2,>=0.1.0; extra == "zk"
Dynamic: license-file

# xian-contracting

`xian-contracting` is the Python contract runtime for Xian. It owns contract
compilation, secure execution, storage semantics, metering, and the runtime
rules that contracts must obey.

## Quick Start

Install the runtime:

```bash
pip install xian-tech-contracting
```

If you want contract-side zk proof verification, install the optional zk
backend too:

```bash
pip install 'xian-tech-contracting[zk]'
```

The published PyPI package name is `xian-tech-contracting`. The repo name
remains `xian-contracting`, and the import surface remains `contracting`.

Submit and call a contract:

```python
from contracting.client import ContractingClient

client = ContractingClient()
client.submit(name="con_token", code=contract_source)
token = client.get_contract("con_token")
token.transfer(amount=100, to="bob")
```

Access storage directly:

```python
from contracting.storage.driver import Driver

driver = Driver()
driver.set("example.key", "value")
print(driver.get("example.key"))
```

## Principles

- Contracts use Python syntax, but execution rules are consensus-sensitive and
  intentionally narrower than general Python.
- Metering, storage encoding, import restrictions, and runtime helpers must
  stay version-aligned across validators.
- Optional native tracing is an implementation detail. The contract model and
  runtime rules should remain understandable without it.
- Built-in helpers should serve the execution model, not grow into a general
  convenience framework.

## Key Directories

- `src/contracting/`: runtime, storage, compilation, and stdlib bridge code
- `packages/`: shared packages such as `xian-runtime-types`, `xian-accounts`,
  the native tracer, and `xian-zk`
- `tests/`: unit, integration, and security coverage
- `docs/`: architecture, backlog, and execution notes

## What It Covers

- compilation and linting
- runtime execution and metering
- storage drivers and encoding
- contract-side runtime helpers
- optional native tracing backend
- native zero-knowledge verifier building blocks

## Validation

```bash
uv sync --group dev
uv run ruff check .
uv run ruff format --check .
uv run pytest
```

If you change the zk runtime surface or the native verifier package, run:

```bash
uv sync --group dev --extra zk
uv run --extra zk pytest -q tests/unit/test_zk_stdlib.py tests/integration/test_zk_bridge.py
cd packages/xian-zk && uv sync --group dev && uv run maturin develop && uv run pytest -q
```

If you change metering, tracing, storage encoding, or import restrictions, run
the relevant `tests/security/` and `tests/integration/` paths explicitly too.

## Related Docs

- [AGENTS.md](AGENTS.md)
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- [docs/BACKLOG.md](docs/BACKLOG.md)
- [docs/README.md](docs/README.md)
