Changelog & migration guide: Operator API v2

2.0.0—2026-09-27

• launch_game replay after the session ends (text correction, GA’s behaviour is unchanged). The guide (§4.1, Appendix A.2) said the same token always returns the same session. It does only while that session is open. Once the session is closed (close_session, or a newer launch of the same game for the same player) or past expires_at, the same token gets 409 ERROR_CODE_IDEMPOTENCY_CONFLICT (session_token_conflict): GA never reopens a closed session. While the first launch with a token is still running, a repeat gets 503 ERROR_CODE_INTERNAL with retryable: true (launch_in_progress). Don’t retry the 409; launch with a fresh token.

2.0.0—2026-09-25

• One error model. Every error from /v2/aggregator/* and /v2/features/* is one application/json body {"code", "message", "retryable"} (ErrorDetail, codes from the closed ERROR_CODE_* list), including signature and key problems (401 → ERROR_CODE_INVALID_REQUEST, 403 → ERROR_CODE_BUSINESS_REJECTED) and a read-only key on a write call (403). message starts with a stable token. GA doesn’t change /v1 answers.
• New event round.failed on the event stream (§4.6), payload Round. Two new RoundStatus values. ROUND_STATUS_FAILED = 4—your wallet declined an operation of the round, no money moved. ROUND_STATUS_REFUND_FAILED = 5—GA couldn’t complete a rollback it owed, the stake stays debited, and the round needs manual reconciliation. A parser that ignores unknown enum values keeps working. Subscribe to round.failed to see these rounds.

Operators already live on v2

What doesn’t change.

• GA doesn’t remove or rename any published method, field, enum value, route, header, or envelope.
• The only additions are the error code IDEMPOTENCY_CONFLICT and the response field original_found. The closed enum is 15 codes plus the ERROR_CODE_UNSPECIFIED default.

What may change for you. Check each item against your implementation.

1. Unknown original. If you return UNKNOWN_ORIGINAL to a Rollback or to a Reconcile, change to a success with original_found=false for Rollback, and to NOT_APPLIED for Reconcile. Certification check W2-G4 already requires success for a Rollback of an unknown original.
2. Barrier. If you don’t remember the id of an unknown original, start remembering it. The Debit must check it in the same atomic step that records the debit.
3. Order of checks. If you check session, player status, limits, or balance before the op_id lookup, reorder per item 2.2.
4. Late Credit, Rollback, and SettleGrant. If you refuse them for session, player block, or limits, stop doing so (item 2.4).
5. Same op_id, different fingerprint. If you currently return the stored success or apply the new request, return IDEMPOTENCY_CONFLICT (item 2.3).
6. Retention. Keep op_id records for at least 4 months. For v1 bridges the 7-day window remains the hard minimum.
7. Concurrent duplicates. Serialise per op_id (item 2.6).
8. Validation. Apply the mappings of item 2.8.
9. Promo and bonus credits. Don’t require a bet or a live session for them (item 2.10).
10. New certification checks. The six checks of section 3 apply to operators certifying on the v2 contract.

Legacy behaviour GA tolerates.

• Some operators answer “transaction not found” to a Rollback and don’t guarantee the barrier of item 2.1.
• GA treats such an answer as final only if GA sent THAT Rollback after original.ts + 300 s. This relies on the operator rejecting the stuck original by its timestamp once the window has passed.
• GA resends an earlier Rollback after the window.
• The same holds for Reconcile: NOT_APPLIED of an unknown DEBIT on native v2 bindings, where GA calls Reconcile before Rollback. It’s final only if GA sent that Reconcile after the window. Otherwise GA proceeds to Rollback.
• This applies to Debit/DebitCredit only. For a Credit, NOT_APPLIED means “resend it”. GA never rolls back a Credit.
• Operators on the v2 contract certify the barrier, so for them “not found” is final at once.

---

Version 2.0.0 (2026-09-13)

Operator API v2 is a major architectural evolution unifying Game Alligators’ operator integration into a single canonical Protobuf core (ga.operator.v2). GA serves it over three transports: native gRPC, HTTP/JSON (protojson), and the Softgaming-compatible adapter.

---

Key architectural enhancements

1. Single canonical contract across three transports

• v1: gRPC v1 and HTTP v1 had separate definitions.
• v2: All three transports use the one Protobuf package in proto/.

2. Deterministic idempotency: op_id vs request_id

• v1: A gRPC v1 Rollback carried a GA id instead of your original op_id, and a retry wasn’t distinguished from a new operation.
• v2: op_id is the business operation deduplication key generated deterministically by GA for every distinct wager, win, rollback, or settlement. Replays with the identical op_id return the original cached response and never move balance twice. request_id is an ephemeral universally unique identifier (UUID) generated per network attempt / retry.

3. Structured metadata & provider passthrough (ProviderData)

• v1: Provider attributes, jackpot flags, and raw payloads didn’t reach the operator.
• v2: Every money request carries CallMeta with typed ProviderData containing the provider slug, round details, and raw provider payloads.

4. Expanded financial primitives

• Atomic DebitCredit: Single remote procedure call (RPC) performing atomic wager and payout in one ledger step.
• CloseRound with Netto: Explicit round closure notification providing the round result (net_win, bet_total, win_total).
• Flexible Rollback:
  • Supports partial amount rollback of a Credit. A rollback of a Debit is always full.
  • Supports debit_mode controlling operator ledger behavior when reversing credits: REJECT (fail if insufficient balance), ALLOW_NEGATIVE (permit negative player balance), or PARTIAL (drain available balance).
• CreditKind and MoneyComponent: Clear distinction between regular wins, bonuses, promotional payouts, jackpots, and free spins, with optional balance component breakdowns.

5. Explicit reconciliation & non-financial lifecycle

• Reconcile: Allows GA to query whether an uncertain or timed-out operation completed on the operator ledger, returning APPLIED, NOT_APPLIED, or UNKNOWN, along with the operator transaction ID.
• Notify: Asynchronous notification for non-monetary lifecycle events such as free spins start/end, session expiry, and responsible gaming limits.

6. Dynamic capability negotiation (wallet_capabilities)

• Operators declare supported actions in their configuration or via GetOperatorCapabilities. GA doesn’t send optional actions you haven’t declared.

7. Standardized error handling

• Structured ErrorCode enum mapping cleanly across gRPC status codes and HTTP envelopes, distinguishing between retryable transport errors (MAINTENANCE, RATE_LIMITED, INTERNAL) and terminal business refusals (INSUFFICIENT_FUNDS, LIMIT_EXCEEDED, SESSION_EXPIRED).

8. Automated certification (ga-operator-certify)

• The suite provides 55 automated test cases (W2-*) validating idempotency, edge cases, error shapes, and brand isolation across all transports.

---

Migration checklist: upgrading from v1 to v2