# titon-network-themis-sdk

> Python SDK for Themis — a TON-native sealed-bid threshold-decryption mechanism on top of Atlas (BLS group key) and ForgeTON (stake + slash). 1:1 parity with @titon-network/themis-sdk (TypeScript), snake_case mirror.

Install:  pip install titon-network-themis-sdk

## Public surface (matters most)

- ThemisFactory / ThemisChamber / SealedLimitOrder — contract wrappers. `create_from_address` for live, `create_from_config` for fresh deploy with bundled bytecode.
- encrypt_bid / decrypt_bid / group_decrypt / new_ephemeral — bidder + consumer crypto (ElGamal-on-G1 KEM + ChaCha20-Poly1305).
- build_reveal / build_decryptions_cell / build_signed_reveal_bytes — operator-side reveal builder.
- random_group_key / simulate_dkg / sign_alpha / aggregate_signatures / bls_public_key / bls_public_key_g2 — BLS primitives (min-pk, G2-PoP).
- decode_event / decode_events / try_decode_event / decode_reveal_callback — typed event decoders.
- explain_error / ThemisError — structured exit-code explainer with optional `force_origin='forgeton'/'atlas'` for sibling-contract reverts.
- THEMIS_TESTNET / THEMIS_MAINNET / assert_deployment — canonical live addresses + schema pins.
- load_factory_code / load_chamber_code / load_sealed_limit_order_code — bundled compiled bytecode.

## Wire-format invariants (do not drift)

- AEAD payload:  aeadVersion(8) | nonce(96) | ciphertext+tag.  AEAD_VERSION=1.
- HKDF:  IKM = sharedSecret||c1.  salt = sha256("titon::themis::aead-key-v1").  info = chamber.hash||roundIdBE(8).  L=32.
- Nonce:  sha256(c1||roundIdBE(8))[:12].
- SignedReveal (76B): chamberBinding(32) | roundIdBE(8) | groupEpochBE(4) | decryptionsRoot(32).
- chamberBindingHash(wc=0 address) = address.hash_part.
- BLS ciphersuite: min-pk, DST BLS_SIG_BLS12381G2_XMD:SHA-256_SSWU_RO_POP_.

## Trust model

- Integrity-by-AEAD: dishonest operator D fails Poly1305 MAC → consumer ignores that bid; chamber state unaffected.
- Liveness-by-refund: missed reveal → permissionless AdvanceRound refunds all bidders.
- No on-chain cryptographic slashing in v1. ChallengeReveal (0x94) is reserved; the wire carries groupPkG2 for the future pairing-based DLEQ proof.

## Skills (load when matching your task)

- skills/themis-bidder-flow.md     — encrypt + submit a bid
- skills/themis-integrate-consumer.md — decode RevealCallback + decrypt bids
- skills/themis-operator-helpers.md — build a RevealRound payload (solo/multi-op)
- skills/themis-deploy-chamber.md   — DeployChamber + ChamberDeployParams tuning
- skills/themis-debug.md            — symptom → exit code → fix

## More docs

- AGENTS.md   — SDK navigator + mirror checklist
- README.md   — quickstart + cross-SDK notes
- ../../CLAUDE.md — Themis architecture, opcode + error ranges, trust model
- ../../PLAN.md   — design + execution rationale
- ../../AUDIT.md  — TSA static-analysis audit posture
