sonic-sdk 0.1.0

Multi-currency settlement engine with cryptographic receipt attestation for the SmartBlocks Network.

Sonic SDK Installation Guide

Package	Description	Version
sonic-sdk	Multi-currency settlement engine with cryptographic receipt attestation	0.1.0

---

Prerequisites

• Python 3.10+
• GitHub access to ToweraiDev/sonic-pay (private repo)
• One of: SSH key linked to GitHub, or a GitHub Personal Access Token (PAT)

---

Install via SSH (recommended)

If you have SSH keys configured with GitHub:

pip install "sonic-sdk @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git"

With optional extras:

# Database support (SQLAlchemy, asyncpg, Alembic)
pip install "sonic-sdk[db] @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git"

# Redis support
pip install "sonic-sdk[redis] @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git"

# Everything
pip install "sonic-sdk[all] @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git"

Install via Personal Access Token

For CI/CD pipelines or machines without SSH:

# Create a PAT at https://github.com/settings/tokens
# Classic: needs `repo` scope
# Fine-grained: needs "Contents" read access to ToweraiDev/sonic-pay

export GH_TOKEN=ghp_xxxxxxxxxxxx

pip install "sonic-sdk @ git+https://${GH_TOKEN}@github.com/ToweraiDev/sonic-pay.git"

Install via GitHub CLI

If you have gh authenticated:

pip install "sonic-sdk @ git+https://$(gh auth token)@github.com/ToweraiDev/sonic-pay.git"

---

Adding to your project

requirements.txt

sonic-sdk @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git

Or with extras:

sonic-sdk[all] @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git

pyproject.toml (pip/setuptools)

[project]
dependencies = [
    "sonic-sdk @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git",
]

pyproject.toml (Poetry)

[tool.poetry.dependencies]
sonic-sdk = {git = "ssh://[e-mail]/ToweraiDev/sonic-pay.git"}

---

Pin to a specific commit or tag

Append @<ref> to pin a version:

# Pin to a commit
pip install "sonic-sdk @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git@abc1234"

# Pin to a tag
pip install "sonic-sdk @ git+ssh://[e-mail]/ToweraiDev/sonic-pay.git@v0.1.0"

---

Local development

Clone and install in editable mode:

git clone [e-mail]:ToweraiDev/sonic-pay.git
cd sonic-pay
python -m venv .venv
source .venv/bin/activate        # Linux/macOS
# .venv\Scripts\activate         # Windows

pip install -r requirements.txt  # installs -e .[all,dev]

---

Quick Start

from sonic import Transaction, TxState, SonicReceipt, SbnClient

# Build a transaction through the state machine
tx = Transaction(tx_id="tx-001", merchant_id="m-acme")
event = tx.advance(TxState.RECEIVABLE_DETECTED, amount=100.00, currency="USD")

# Seal receipt to SBN for tamper-evident attestation
sbn = SbnClient(api_key="sbn_live_...")
sbn_hash = sbn.seal({"receipt_hash": event.receipt_hash})

Core modules

from sonic.core.engine import Transaction, TxState, TxEvent, InvalidTransition
from sonic.core.receipt_builder import SonicReceipt, ReceiptChain, canonical_hash
from sonic.core.finality_gate import FinalityGate, FinalityPolicy, FinalityStatus
from sonic.core.treasury import Treasury, ConversionQuote
from sonic.core.payout_executor import PayoutExecutor, PayoutInstruction, PayoutResult
from sonic.events.types import EventType
from sonic.events.emitter import EventEmitter
from sonic.sbn import SbnClient, SbnAttester, ReceiptCoupler
from sonic.sbn.frontier import SONIC_FRONTIER
from sonic.config import SonicSettings, settings

Vendored SDKs

sonic-sdk vendors sbn-sdk, snapchore-core, and dominion-sdk — no separate install needed.

# Dominion payroll client (re-exported at top level)
from sonic import DominionSbnClient, DominionSonicClient

# Direct access to vendored packages
from sonic._vendor.sbn import SbnClient as RawSbnClient, SlotSummary
from sonic._vendor.snapchore import SmartBlock, SnapChoreChain, snapchore_capture
from sonic._vendor.dominion import DominionSbnClient, DominionSonicClient

---

Optional Extras

Extra	Packages	Use case
db	sqlalchemy, asyncpg, alembic	Postgres persistence
redis	redis	Event bus / attestation queue
server	fastapi, uvicorn, psycopg2, python-jose	Running the Sonic HTTP API server
all	db + redis	Everything (without server)
dev	pytest, pytest-asyncio, ruff, mypy, python-dotenv	Development & testing

---

Dependencies

Core (always installed)

• httpx >= 0.27.0
• cryptography >= 42.0
• pydantic >= 2.5
• pydantic-settings >= 2.1

Vendored (included in package — no separate install)

• sbn-sdk 0.2.0 — SmartBlocks Network client
• snapchore-core 0.1.0 — Cryptographic integrity for stateful events
• dominion-sdk 0.1.0 — Sovereign Compression Payroll Router