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 surface parity with the TypeScript SDK (@titon-network/themis-sdk), snake_case mirror.

🛡️ TSA-audited — the contracts behind this SDK are static-analysis clean (zero findings). Full posture: ../../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

pip install titon-network-themis-sdk

Bidder flow

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)

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)

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 for the workspace mirror checklist; AGENTS.md for the per-file map.

Further reading

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

License

MIT