kryten-economy

Channel engagement currency microservice for CyTube, built on the kryten ecosystem.

What It Does

kryten-economy turns passive viewers into active participants by rewarding channel presence, chat activity, and social interaction with Z-Coins — a fully configurable virtual currency. Users spend Z on queueing media, vanity items, tipping, and gambling. A B-movie-themed rank system (Extra → Stunt Double → … → Director) grants real perks like queue discounts and extra queue slots.

Feature Highlights

• Presence earning — per-minute Z rewards with night-watch bonuses and hourly milestones
• Chat triggers — 12+ earning triggers for long messages, kudos, laughs, conversation starters, and more
• Daily streaks — consecutive-day bonuses with milestone multipliers and bridge recovery
• Gambling — slot machine, coin flip, player duels, and cooperative channel heists
• Media queue — search and queue content from a MediaCMS instance, paid with Z
• Tipping — alias-aware peer-to-peer transfers with self-tip prevention
• Vanity shop — custom greetings, chat colors, titles, channel GIFs (with admin approval)
• Achievements — one-time badges with Z rewards for milestones
• Rank progression — automatic rank-ups with CyTube rank promotions
• Multiplier events — scheduled and ad-hoc earning multipliers, daily competitions, user bounties
• Admin tooling — 16 admin commands for grants, bans, economy health, trigger analytics, config hot-reload
• Monitoring — Prometheus metrics endpoint with per-trigger, per-command, and per-channel gauges

Everything is configurable via a single YAML file — every rate, threshold, reward, cost, and message template.

Requirements

• Python 3.11+
• NATS server (via kryten infrastructure)
• kryten-py >= 0.11.5 — CyTube ↔ NATS client library
• kryten-robot — event source bridging CyTube websocket events to NATS
• kryten-userstats — alias resolution for tip self-transfer prevention
• Optional: MediaCMS instance for content queue features

Installation

From PyPI

pip install kryten-economy

From GitHub

pip install git+https://github.com/grobertson/kryten-economy.git

Development Install

git clone https://github.com/grobertson/kryten-economy.git
cd kryten-economy
python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows
pip install -e ".[dev]"

Quick Start

# 1. Copy the example config
cp config.example.yaml config.yaml

# 2. Edit with your NATS and channel settings
$EDITOR config.yaml

# 3. Run
kryten-economy --config config.yaml

# Or as a module
python -m kryten_economy --config config.yaml

systemd Deployment

sudo cp systemd/kryten-economy.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now kryten-economy

The included service file has resource limits (MemoryMax=512M, CPUQuota=50%) and security hardening (NoNewPrivileges, ProtectSystem=strict).

Configuration

See config.example.yaml for the complete reference with inline documentation. Key sections:

Environment variable substitution is supported: ${NATS_URL}, ${VAR:-default}.

Database backend status

SQLite remains the production data layer, and remains the default. The postgres backend is complete as of 0.16.0 and is verified against a live PostgreSQL 16 server — an asyncpg store covering the full EconomyDatabase surface, with transactional, row-locked currency mutations.

Do not switch production over by editing config.yaml. Moving live currency is a deliberate, reversible operation with its own procedure — see docs/postgres-cutover.md for the cutover, verification, smoke-test, and rollback steps, and docs/admin-guide.md for the data-migration tool itself. Rollback is database.backend: "sqlite" plus a restart; the SQLite file is left untouched and stays valid for one full release.

The PostgreSQL schema is managed by Alembic (the single schema authority for this service):

uv run alembic upgrade head

Alembic resolves its database URL from KRYTEN_ECONOMY_ALEMBIC_URL, or from the service's own database.postgres block, so no database credential is stored in the repository.

When PostgreSQL connection plumbing is used, DSN resolution follows this precedence:

1. The environment variable named by postgres.dsn_env
2. postgres.dsn
3. A DSN assembled from host, port, user, dbname, and the password selected by password_env (preferred) or password

Prefer KRYTEN_ECONOMY_DSN for a complete DSN or KRYTEN_ECONOMY_PG_PASSWORD for only the password. Keep secrets out of config.yaml and source control.

Note that the migration tool reads a DSN through its own --pg-dsn-env name and does not share Alembic's KRYTEN_ECONOMY_ALEMBIC_URL; see the runbook.

Documentation

• User Guide - PM commands, queue flow, event window behavior, and troubleshooting
• Admin Guide - operator setup, admin commands, and full configuration reference
• PostgreSQL Cutover Runbook - migrating the economy from SQLite to PostgreSQL, verification, and rollback
• Configuration Migration Guide - config changes from v0.8.10 to v0.9.2 and how to upgrade config.yaml

PM Commands

User Commands

Admin Commands (CyTube Rank ≥ 4)

Testing

# Run the whole suite
uv run pytest

# With coverage
uv run pytest --cov=kryten_economy --cov-report=term-missing

# Skip the tests that need a real PostgreSQL server
uv run pytest -m "not postgres"

# Just the PostgreSQL backend + ETL tests (requires KRYTEN_ECONOMY_TEST_DSN)
uv run pytest -m postgres -v

# Specific sprint area
uv run pytest tests/test_gambling_engine.py tests/test_slots.py tests/test_flip.py -v

Most tests need no external services: no NATS server and no database. The PostgreSQL backend is the exception — it is validated against a real PostgreSQL server rather than a mock, because a mock would pass while asyncpg failed in production. Those tests carry the postgres marker and skip cleanly when no DSN is configured:

export KRYTEN_ECONOMY_TEST_DSN='postgresql://kryten:...@host:5432/kryten_economy_test'
uv run alembic upgrade head   # apply the schema to that database first
uv run pytest -m postgres -v

Point that at a disposable database — the PostgreSQL tests create and drop rows, and the ETL tests truncate tables. CI does this automatically with a postgres:16-alpine service.

Monitoring

Prometheus metrics served at http://localhost:28286/metrics (port configurable).

Counters: Z earned by trigger, Z spent by type, gamble in/out, events processed, commands processed, trigger hits, achievements awarded, rank promotions, competitions, bounties.

Gauges: Active users, total circulation, median balance, participation rate, active multiplier, rank distribution — all per-channel.

Architecture

kryten-economy/
├── kryten_economy/
│   ├── __init__.py              # Version from metadata
│   ├── __main__.py              # CLI entry, signal handling
│   ├── main.py                  # EconomyApp orchestrator
│   ├── config.py                # Pydantic config models
│   ├── database.py              # SQLite store (default backend)
│   ├── db/                      # PostgreSQL backend
│   │   ├── protocol.py          # EconomyStore Protocol (backend contract)
│   │   ├── boundary.py          # SQLite≡PostgreSQL value normalisation
│   │   ├── pool.py              # DSN resolution + asyncpg pool
│   │   └── database_pg.py       # asyncpg store (full EconomyDatabase surface)
│   ├── migrate_sqlite_to_pg.py  # One-time SQLite → PostgreSQL ETL (operator tool)
│   ├── presence_tracker.py      # Dwell tracking, join debounce
│   ├── earning_engine.py        # Centralized earning + multipliers
│   ├── spending_engine.py       # Spending validation + rank discounts
│   ├── gambling_engine.py       # Slots, flip, challenge, heist
│   ├── pm_handler.py            # 34 PM commands + rate limiting
│   ├── command_handler.py       # NATS request-reply API
│   ├── achievement_engine.py    # One-time badges
│   ├── rank_engine.py           # B-movie rank progression
│   ├── multiplier_engine.py     # Multiplier stack
│   ├── competition_engine.py    # Daily competitions
│   ├── bounty_manager.py        # User bounties
│   ├── event_announcer.py       # Chat announcements (dedup + batching)
│   ├── greeting_handler.py      # Custom greetings on join
│   ├── admin_scheduler.py       # Snapshots + digests
│   ├── scheduled_event_manager.py  # Cron-based events
│   ├── metrics_server.py        # Prometheus endpoint
│   ├── media_client.py          # MediaCMS API client
│   └── utils.py                 # Shared utilities
├── tests/                       # 65 test files, 574 tests
├── config.example.yaml          # Full reference config (~570 lines)
├── systemd/
│   └── kryten-economy.service   # Production systemd unit
├── pyproject.toml
├── LICENSE
└── CHANGELOG.md

Design Principles

• Zero raw NATS — all messaging through kryten-py wrappers
• Atomic debits — single-transaction debit-or-fail prevents negative balances
• SQLite WAL — write-ahead logging with busy_timeout=30s for concurrent access
• Transactional currency — credit/debit/refund apply the balance change and write the ledger row in one transaction on both backends, so a balance can never move without a matching transactions row. debit is a conditional UPDATE ... WHERE balance >= $ on PostgreSQL, so simultaneous spends serialise on the row lock and a debit that cannot be covered updates zero rows rather than going negative.
• Error isolation — every event handler wrapped in try/except; one bad event never crashes the service
• Hot-reloadable config — admin reload command re-validates via Pydantic and applies without restart

Publishing to PyPI

# Build
python -m build

# Upload to TestPyPI first
python -m twine upload --repository testpypi dist/*

# Upload to PyPI
python -m twine upload dist/*

License

MIT

Contributing

This is part of the kryten ecosystem. Issues and PRs welcome at github.com/grobertson/kryten-economy.