Як працює API джекпот-систем

Повний текст статті

💡 18+. Матеріал - інженерно-прикладний, без заклику до гри. Терміни: платформа - PAM/гаманець/каса/бонуси/RG; RGS - Remote Game Server (ядро ігор студії); агрегатор - уніфікований шар для безлічі RGS; JP - jackpot-сервіс.

1) Що таке джекпот-система і де вона стоїть в екосистемі

Джекпот-система - це окремий сервіс (іноді кластер сервісів), який збирає внески зі ставок, управляє пулами і тригерами виграшів, розраховує розподіл призів і ініціює виплати через платіжний контур оператора. Вона інтегрується:

з RGS (повідомлення про ставки/результати і кваліфікації), з платформою/гаманцем (списання внесків і кредитування виграшів), з агрегатором (роутинг від безлічі студій/брендів), з BI/регулятором (телеметрія і звітність).

2) Типи джекпотів (і що змінюється в API)

1. Фіксований (Fixed): заздалегідь відома сума призу. В API немає пулу, тільки перевірка умов і кредит.

2. Прогресивний (Progressive): пул зростає від внесків ставок. Потрібні ендпоінти внеску та публікація поточного розміру.

3. Багаторівневий (Multi-tier: Mini/Major/Grand): кілька паралельних пулів з різними шансами і капами.

4. Локальний vs мережевий: локальний пул - у одного оператора/бренду; мережевий - сумарний по безлічі операторів/брендів/регіонів (мультитенантність і реплікація критичні).

5. Тимчасовий/івентовий: пул з дедлайном або за розкладом (потрібні таймери і авто-розіграші).

3) Грошові інваріанти

Джерело істини по балансу - гаманець/ledger платформи. JP зберігає тільки стан пулів і зобов'язання.

Всі грошові операції - ідемпотентні (ключі'jp _ contrib _ id','jp _ trigger _ id','jp _ payout _ id').

«Втрачених/дубльованих виплат» = 0. Компенсації - тільки подіями (саги), не ручними правками БД.

Розділяйте внесок (contribution), тригер (trigger) і виплату (payout) як самостійні транзакції з власною телеметрією.

4) Еталонні контракти API

4. 1 RGS/агрегатор → JP (внески і тригери)

'POST/v1/jp/contributions'- облік внеску в пул

json
{
"jp_contrib_id": "uuid-1",  "tenant_id": "brand-42",  "pool_id": "grand-eu-01",  "player_id": "p_abc",  "game_id": "studio:slot_777",  "round_id": "r_123",  "bet": {"amount": 2. 00, "currency": "EUR"},  "contrib": {"amount": 0. 02, "currency": "EUR"},  "occurred_at": "2025-10-23T15:12:05Z",  "idempotency_key": "round_r_123"
}

'POST/v1/jp/candidates'- заявка на участь/перевірка умов (опціонально)

Відповідь: `eligible: true/false', вага або шанс, правила.

'POST/v1/jp/triggers'- фіксація факту спрацьовування

json
{
"jp_trigger_id": "uuid-2",  "pool_id": "grand-eu-01",  "reason": "random_hit",  "selector": {"player_id": "p_abc", "round_id": "r_123"},  "occurred_at": "2025-10-23T15:12:06Z",  "idempotency_key": "jp_t_grand_r_123"
}

💡 Примітка: в деяких моделях ініціатором тригера виступає сам JP (внутрішня рулетка), а RGS тільки повідомляє про раунд. Тоді «triggers» викликаються JP→platforma, а RGS підписується на подію.

4. 2 JP → платформа (виплати/резерви)

'POST/v1/wallet/reserve'- (опціонально) резерв під майбутню виплату

'POST/v1/wallet/credit'- кредит виграшу гравцеві

json
{
"jp_payout_id": "uuid-3",  "tenant_id": "brand-42",  "player_id": "p_abc",  "pool_id": "grand-eu-01",  "amount": {"amount": 500000. 00, "currency": "EUR"},  "meta": {"tax": "withheld=false", "tier": "grand"},  "idempotency_key": "jp_p_grand_r_123"
}

Відповіді платфоми: `credit. ok	failed', з кодами причин (RG/AML, ліміти виведення, санкції, гео-блок).

4. 3 Публікація статусу пулу (для фронтів/віджетів)

'GET/v1/jp/pools/{ pool _ id}'→ поточний розмір, seed, кап, число учасників, ETA та ін.

'GET/v1/jp/pools'→ список пулів по бренду/регіону з фільтрами.

5) Подієва модель (Kafka/Pulsar) і схеми

Базові топіки:

`jp. contribution. recorded`
`jp. pool. updated'( розмір, конкурентні оновлення)
`jp. triggered`

`jp. payout. requested	credited	failed`
`wallet. credit.'( дзеркалювання для саг)
`rg. limit. hit`, `aml. alert. opened'( якщо виплата блокується)
`audit. config. changed'( ліміти, seed, cap, розподіл)

Контракти: Avro/JSON Schema + Schema Registry, ключі партіонування'tenant _ id','pool _ id','player _ id'. Версіонування - backward-compatible.

6) Алгоритми тригера (високорівнево)

Імовірнісний (p-стійкий): на кожен кваліфікований раунд генеруємо hit з імовірністю'p'( залежною від пулу/типу рівня).

Діапазонний (must-drop): пул зобов'язаний впасти до cap-суми або дедлайну - тримаємо внутрішній random в діапазоні [min, max], публікуємо cap/ETA.

Сід- і entropy-управління: серверний seed + per-round salt; відмова від клієнтських сидів для джекпотів. Всі зміни seed - під WORM-аудитом.

Чесність: тригер не повинен залежати від конкретної особистості гравця (крім правил гео/ліцензії/кваліфікації). Будь-яке «персональне» таргетування - табу.

7) SLO і продуктивність

p95'contribution'< 120 мс, p99 <250 мс.

p95'trigger→credit'< 500 мс (без зовнішніх платіжних хопів).

«Втрачених/дубльованих виплат» = 0 (перевіряється контрактними тестами).

Доставка подій в BI ≤ 5 хв.

Доступність JP API для критичних шляхів ≥ 99. 95%.

8) Безпека та комплаєнс

mTLS + підписи (HMAC/EdDSA) на всіх S2S-викликах; короткоживучі токени.

Zero-trust: мережеві політики/mesh, мінімальні привілеї, сегментація по регіонах.

WORM-аудит змін лімітів, формул, seed/entropy, конфігів пулів.

GDPR/Data residency/PCI: PII і логи - в регіоні; токенізація чутливих полів; заборона крос-регіонних читань.

RG/AML: синхронні стоп-сигнали на виплаті; SAR/STR-вивантаження автоматизовані.

9) Узгодженість і саги

Внесок ('contribution') - фіксуємо в JP, публікуємо'jp. contribution. recorded`.

Тригер («triggered») - створює зобов'язання; JP запускає сагу'payout'.

Виплата ('payout. requested → wallet. credit. ok') - завершує сагу; при фейлі - ретраї з дедуплікацією.

Outbox/CDC - єдиний шлях публікації подій; ніяких «обхідних» логгерів.

10) Телеметрія і дашборди

Бізнес:

`pool_size`, `contrib_rate`, `avg_contrib_per_bet`, `time_to_drop`, `payouts_count/sum`, `tier_distribution`.

Технічні:

p50/p95/p99 по `contribution`, `trigger`, `payout`;
error rate с типами (5xx/4xx/business), retry storms, queue lag;
`wallet. credit` latency/ok-rate; конфліктність оновлення пулу.

Алерти:

зростання'payout. failed'> X% по бренду/регіону,'pool _ size'> cap - Y% часу (помилка конфігурації), drift між'pool _ size'і сумою внесків по звірці> Z ppm.

11) Мультитенантність та ізоляція

Всі запити та події позначені'tenant _ id/brand _ id/license/region'.

Локальні/мережеві пули розділені фізично (DB/cluster) при різних ліцензіях/регіонах.

Row-level security (RLS) і маскування у вітринах BI.

Окремі ключі/секрети і схематичні простори на бренд/регіон.

12) Інтеграція з бонусами/турнірами

Внески не збільшують вейджер безпосередньо; внесок у бонус - йде від ставки, а не від внеску.

Турніри можуть нараховувати очки за «участь в JP» або «потрапляння в топ-вклади». Джерело - події'jp. contribution. recorded` и `jp. triggered`.

Обов'язкове правило: джекпот-механіка не змінює базовий RTP гри; інакше потрібна окрема сертифікація.

13) Тестування та хаос-практики

Контрактні тести RGS↔JP↔koshelyok: дубль-доставки, затримки, out-of-order, rollback.

Навантажувальні тести: шторм ставок і тригерів, масштабування воркерів пулу.

Хаос-навчання: падіння регіону JP, офлайн гаманця, розсинхронізація часу; перевірка outbox і деградацій (pause triggers/no new contributions).

14) Чек-листи

Для студії/RGS

Ідемпотентні'contribution'і коректні'round _ id '/' bet _ id'.
Немає публікацій «в обхід» транзакцій (тільки outbox/CDC).
Тести дублів/повторних тригерів/компенсацій.
Ліміти max bet/кваліфікація передаваються в JP.

Для оператора/платформи

Ledger - джерело істини,'wallet. credit'з дедупом.
RG/AML-стопи обробляються на виплаті; звіти SAR/STR.
Дашборди p95'trigger→credit', error rate, звірки пулів.

Для власника JP

WORM-аудит змін формул/seed/лімітів.
Схеми подій в Registry і versioning.
DR: RPO ≤ 5 хв, RTO ≤ 30 хв; Регулярні навчання.
RLS/ізоляція за брендами/ліцензіями; ключі/секрети per region.

15) Червоні прапори (анти-патерни)

Ручні правки розмірів пулів і виплат в БД.

Відсутність ідемпотентності → дублі кредитів.

Публікація телеметрії без outbox/CDC → «втрачені» внески/тригери.

Змішування PII і грошових даних різних регіонів.

Джекпот, який впливає на RTP базової гри без нової сертифікації.

Немає звірок гаманця і пулу; звіти будуються по бойовій OLTP.

API джекпот-систем - це грошово-подієвий контракт між студією, платформою і оператором. Його фундамент: ідемпотентність і саги, жорстка ізоляція грошей, чіткі схеми подій, безпека і WORM-аудит, спостережуваність і SLO. На такому дизайні фікс/прогресивні і мережеві пули масштабуються передбачувано, виплати залишаються коректними, а регуляторна і бізнес-звітність - прозорою і достовірною.