sonic-sdk 0.1.0
Multi-currency settlement engine with cryptographic receipt attestation for the SmartBlocks Network.
Requires Python: >=3.10
Keywords: sonic, settlement, smartblocks, sbn, snapchore, gec, payments

# 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:

```bash
pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
```

With optional extras:

```bash
# Database support (SQLAlchemy, asyncpg, Alembic)
pip install "sonic-sdk[db] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"

# Redis support
pip install "sonic-sdk[redis] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"

# Everything
pip install "sonic-sdk[all] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git"
```

## Install via Personal Access Token

For CI/CD pipelines or machines without SSH:

```bash
# 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:

```bash
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://git@github.com/ToweraiDev/sonic-pay.git
```

Or with extras:

```
sonic-sdk[all] @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git
```

### pyproject.toml (pip/setuptools)

```toml
[project]
dependencies = [
    "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git",
]
```

### pyproject.toml (Poetry)

```toml
[tool.poetry.dependencies]
sonic-sdk = {git = "ssh://git@github.com/ToweraiDev/sonic-pay.git"}
```

---

## Pin to a specific commit or tag

Append `@<ref>` to pin a version:

```bash
# Pin to a commit
pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git@abc1234"

# Pin to a tag
pip install "sonic-sdk @ git+ssh://git@github.com/ToweraiDev/sonic-pay.git@v0.1.0"
```

---

## Local development

Clone and install in editable mode:

```bash
git clone git@github.com: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

```python
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

```python
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.

```python
# 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