iGaming Codex

stake-engine-wallet-api-flow

время чтения ~2 мин.

Stake Engine wallet API flow

Зачем это важно

Даже если RGS не Stake, сама последовательность round lifecycle типовая для индустрии:

  1. authenticate сессии,
  2. play (дебет ставки + результат раунда),
  3. event для восстановления in-progress состояния,
  4. end-round для финализации payout.

Этот порядок снижает риски рассинхрона между фронтом и кошельком и напрямую связан с result determination / interrupted gambling.

Базовый flow

sequenceDiagram
  participant FE as Frontend
  participant RGS as Wallet/RGS
  FE->>RGS: POST /wallet/authenticate (sessionID)
  RGS-->>FE: balance + config + round?
  FE->>RGS: POST /wallet/play (sessionID, amount, mode)
  RGS-->>FE: balance(after debit) + round(state, multipliers)
  loop during round animation / user actions
    FE->>RGS: POST /bet/event (sessionID, event)
    RGS-->>FE: event ack
  end
  alt payout > 0
    FE->>RGS: POST /wallet/end-round (sessionID)
    RGS-->>FE: balance(after payout)
  else payout = 0
    Note over RGS: round auto-completed
  end

Ключевые operational правила

  • Все wallet-endpoints требуют валидный sessionID; без этого типичная ошибка уровня invalid session.
  • play.amount обязан лежать в диапазоне и шаге, возвращенных в authenticate.config.
  • play.mode должен соответствовать допустимому mode для конкретной game config.
  • event используем для восстановления mid-round состояния после disconnect.
  • end-round вызываем только когда payout ненулевой; zero-payout раунды auto-complete на стороне RGS.

Семантика round при повторной аутентификации

Если в authenticate возвращается round, это сигнал незавершенного payout-процесса:

  • фронт сначала отображает результат игроку,
  • затем вызывает end-round для финального credit.

Если round = null после недавнего spin, это часто означает, что раунд был zero-payout и уже закрыт автоматически.

Что переносим в нашу архитектуру

  • Связка [[kb/05-rgs/state-recovery|state recovery]] + event-лог как минимальный контракт interruption handling.
  • Явное разделение debit (play) и credit (end-round) с idempotent-guard на стороне кошелька.
  • В UX/telemetry отмечаем ветки:
    • AUTO_COMPLETED_ZERO_PAYOUT
    • PENDING_PAYOUT_REQUIRES_END_ROUND

Риски интеграции

  • Пропуск end-round для payout > 0 ведет к подвисшим выигрышам.
  • Жестко захардкоженный bet-step ломает часть валютных/юрисдикционных сессий.
  • Отсутствие event-фиксации усложняет доказуемое восстановление раунда.

Связанные страницы

Вид графа