Metadata-Version: 2.4
Name: titon-network-themis-sdk
Version: 0.3.0
Summary: Python SDK for Themis — TON-native sealed-bid threshold-decryption mechanism. Encrypt bids, decode events, drive a chamber. TSA-audited zero findings.
Project-URL: Homepage, https://github.com/titon-network/themis
Project-URL: Repository, https://github.com/titon-network/themis.git
Project-URL: Issues, https://github.com/titon-network/themis/issues
Author: titon.network
License-Expression: MIT
License-File: LICENSE
Keywords: atlas,blockchain,bls12-381,chacha20-poly1305,elgamal,forgeton,sealed-bid,themis,threshold-bls,threshold-decryption,tolk,ton
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: py-ecc>=7.0.0
Requires-Dist: pytoniq-core>=0.1.40
Requires-Dist: pytoniq>=0.1.40
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# titon-network-themis-sdk

Python SDK for [Themis](https://github.com/titon-network/themis) — a TON-native
sealed-bid threshold-decryption mechanism on top of [Atlas](https://github.com/titon-network/atlas)
(BLS group key) and [ForgeTON](https://github.com/titon-network/forgeton) (stake + slash).
1:1 surface parity with the TypeScript SDK ([`@titon-network/themis-sdk`](https://www.npmjs.com/package/@titon-network/themis-sdk)),
snake_case mirror.

> 🛡️ **TSA-audited** — the contracts behind this SDK are static-analysis clean (zero findings). Full posture: [`../../AUDIT.md`](../../AUDIT.md).

## What this gives you

- **Sealed-bid auctions, MEV-resistant DEX swaps, confidential governance** — encrypt user intents under Atlas's group key, batch-decrypt off-chain via operator threshold, dispatch to your consumer contract.
- **`ThemisFactory` + `ThemisChamber` wrappers** — every `send_*` + `get_*` method, deterministic state-init derivation, bundled compiled bytecode.
- **Bidder crypto** — `encrypt_bid()` produces a `(c1, aead_cell)` pair ready for `SubmitCiphertext`. ChaCha20-Poly1305 over an ElGamal-on-G1 KEM.
- **Consumer crypto** — `decode_reveal_callback()` + `decrypt_bid()` recover the original bidder plaintext from a `RevealCallback`. Integrity is by AEAD MAC: a dishonest D is ignored.
- **Typed event decoder** — 16 dataclasses covering every `EVT_*` opcode. For indexers, monitors, and tests.
- **`SealedLimitOrder`** — reference Jetton↔Jetton sealed-bid call-auction consumer with its own event decoder + plaintext codec.

## Install

```bash
pip install titon-network-themis-sdk
```

## Bidder flow

```python
from pytoniq import LiteBalancer
from pytoniq_core import Address
from themis_sdk import (
    THEMIS_TESTNET,
    ThemisChamber,
    encrypt_bid,
)

# Pick a chamber (your protocol's chamber address comes from DeployChamber).
chamber = ThemisChamber.create_from_address(
    THEMIS_TESTNET.slo_chamber,
    client=LiteBalancer.from_testnet_config(trust_level=2),
)

# Read the chamber's cached group key + current round.
gk = await chamber.get_group_key()
round_state = await chamber.get_current_round()

# Encrypt your bid plaintext (opaque to the chamber — the consumer parses it).
plaintext = b"protocol-specific bid bytes; for SealedLimitOrder see encode_bid_plaintext"

bid = encrypt_bid(
    plaintext=plaintext,
    group_pk=gk.group_pk,
    chamber=chamber.address,
    round_id=round_state.round_id,
)

# Submit. `value` covers the chamber's `submitFee + minXcGas + gas headroom`.
await chamber.send_submit_ciphertext(
    wallet,
    value=200_000_000,  # 0.2 TON; tune via chamber.get_config().submit_fee
    query_id=42,
    c1=bid.c1,
    aead_cell=bid.aead_cell,
)
```

## Consumer flow (Tolk-side dispatch is yours; Python decodes the callback)

```python
from themis_sdk import decode_reveal_callback, decrypt_bid

decoded = decode_reveal_callback(reveal_callback_body)
for b in decoded.bids:
    plaintext = decrypt_bid(
        aead_cell=b.aead_ct,
        c1=b.c1,
        d=b.d,
        chamber=decoded.chamber,
        round_id=decoded.round_id,
    )
    # plaintext is your protocol's bid bytes — parse + dispatch in your consumer.
```

## Operator-side reveal (for tests / sandbox)

```python
from themis_sdk import build_reveal, BuildRevealArgs, RevealEntryInput, random_group_key, group_decrypt, new_ephemeral

gk = random_group_key()      # solo mode
eph = new_ephemeral()
D = group_decrypt(eph.c1, gk.sk)

built = build_reveal(BuildRevealArgs(
    chamber=chamber.address,
    round_id=1,
    group_epoch=1,
    entries=[RevealEntryInput(idx=0, c1=eph.c1, d=D)],
    group_key=gk,
))

await chamber.send_reveal_round(
    operator_wallet,
    value=500_000_000,
    signed_data_ref=built.signed_data_ref,
    decryptions_ref=built.decryptions_ref,
    agg_sig_ref=built.agg_sig_ref,
)
```

## When to reach for which SDK

- **TypeScript (`@titon-network/themis-sdk`)** — canonical. Has the full surface plus the @ton/sandbox testing helpers. Required for end-to-end probes + scaffolded Tolk consumers.
- **Python (`titon-network-themis-sdk`, this package)** — for dapp builders / indexers / off-chain operator daemons written in Python. Same `ThemisFactory` / `ThemisChamber` wrappers, same crypto primitives (`py_ecc.bls.G2ProofOfPossession` matches noble-curves DST byte-for-byte), same error explainer.

When editing one, mirror the other. See [`../../CLAUDE.md`](../../CLAUDE.md) for the workspace mirror checklist; [`AGENTS.md`](./AGENTS.md) for the per-file map.

## Further reading

- [`AGENTS.md`](./AGENTS.md) — SDK navigator + mirror checklist
- [`skills/`](./skills/) — persona-grouped agent playbooks (bidder, integrate-consumer, operator-helpers, deploy-chamber, debug)
- [`../../CLAUDE.md`](../../CLAUDE.md) — Themis architecture, opcode + error ranges, trust model
- [`../../PLAN.md`](../../PLAN.md) — design rationale + execution plan
- [`../../AUDIT.md`](../../AUDIT.md) — TSA static-analysis audit posture

## License

MIT
