# titon-network-fortuna-sdk

> Python SDK for **Fortuna** — TON's threshold-BLS VRF. Request randomness,
> decode events, verify beta. 1:1 surface parity with
> `@titon-network/fortuna-sdk` (TS).

## Docs (load these first)

- [README.md](README.md) — install + 3 quickstart examples + surface map.
- [AGENTS.md](AGENTS.md) — agent map; mental model + persona table + mirror
  checklist with TS SDK.
- [AGENT-PROMPT.md](AGENT-PROMPT.md) — drop-in system prompt for an agent
  helping a user integrate.

## Skills (each is a self-contained recipe)

- [skills/fortuna-integrate-consumer.md](skills/fortuna-integrate-consumer.md)
  — Tolk consumer + Python client.
- [skills/fortuna-monitor-events.md](skills/fortuna-monitor-events.md) —
  indexer / dashboard.
- [skills/fortuna-owner-ops.md](skills/fortuna-owner-ops.md) — pause /
  config / withdraw / upgrade.
- [skills/fortuna-debug.md](skills/fortuna-debug.md) — exit codes + bounce
  decode.

## Examples

- [examples/01_request_randomness.py](examples/01_request_randomness.py)
- [examples/02_decode_events.py](examples/02_decode_events.py)

## Source layout

- `src/fortuna_sdk/__init__.py` — public re-exports (~84 names).
- `src/fortuna_sdk/contracts/fortuna.py` — `Fortuna` wrapper + body
  builders + send_* + get_*.
- `src/fortuna_sdk/vrf.py` — alpha/beta/req_key + sign + aggregate
  (`py_ecc.bls.G2ProofOfPossession`).
- `src/fortuna_sdk/events/` — typed event dataclasses + decoder.
- `src/fortuna_sdk/errors.py` — `explain_error` + `FortunaError`.
- `src/fortuna_sdk/diagnostics.py` — `summarize_tx` + `QueryIdStream` +
  `submission_jitter`.
- `src/fortuna_sdk/deployments.py` — `FORTUNA_TESTNET` / `FORTUNA_MAINNET`
  + `assert_deployment`.
- `src/fortuna_sdk/artifacts/` — bundled `Fortuna.compiled.json` +
  `load_fortuna_code`.

## Tests (every test = runnable usage example)

- [tests/test_opcodes.py](tests/test_opcodes.py)
- [tests/test_errors.py](tests/test_errors.py)
- [tests/test_vrf.py](tests/test_vrf.py)
- [tests/test_contracts.py](tests/test_contracts.py)
- [tests/test_events.py](tests/test_events.py)
- [tests/test_diagnostics.py](tests/test_diagnostics.py)
- [tests/test_deployments.py](tests/test_deployments.py)
- [tests/test_artifacts.py](tests/test_artifacts.py)
- [tests/test_address_parity.py](tests/test_address_parity.py) — proves
  Python-derived deploy address matches the live testnet, confirming
  init-cell byte-identity with the TS SDK.

## Sibling repos

- [TS SDK (canonical)](../typescript/) — `@titon-network/fortuna-sdk`.
- [Fortuna contract](../../contracts/fortuna.tolk).
- [Fortuna repo CLAUDE.md](../../CLAUDE.md) — repo-wide AI dev guide.

## Audit posture

🛡️ Built on the Fortuna contract that cleared TSA static analysis with
**zero findings**. The SDK is a transliteration of the audited TS SDK; same
byte-for-byte alpha / beta / request-key derivation.
