Overview

Settlement and recovery

Automatic results, retries, rollback, and reconciliation
View as Markdown

Settlement and recovery

Automatic settlement is initiated by Wuzzlo. The operator does not poll the game or calculate winners. Wuzzlo determines the result and sends a signed POST /resultrequest callback to the configured operator credit path.

Normal lifecycle

OPEN
  ├─ betrequest succeeds ──> DEBITED
  │                           ├─ resultrequest ──> SETTLED
  │                           └─ rollbackrequest ─> ROLLED_BACK
  └─ betrequest rejected ──> no wallet transaction

SETTLED and ROLLED_BACK are terminal for the original debit. A callback that conflicts with a terminal state must return the documented lifecycle error and must not change balance.

Automatic settlement behavior

  1. The game engine closes or resolves a wager.
  2. Wuzzlo creates the wallet settlement operation with stable identifiers.
  3. Wuzzlo sends the signed result callback.
  4. The operator verifies, applies, and durably records the result in one transaction.
  5. If delivery fails or its outcome is uncertain, Wuzzlo may retry. The same identifiers make the retry safe.
  6. Background recovery can redeliver pending wallet operations. Therefore idempotency must survive process restarts and long delays.

Some games settle on an explicit cashout; others settle when a round closes or through a server-side safety worker. This difference is internal to Wuzzlo. The operator handles every result through the same signed, idempotent wallet contract.

Retry rules

  • An exact request replay uses the same reqId and must not repeat the mutation.
  • A repeated logical transaction with a new reqId must follow the transaction lifecycle status for that endpoint.
  • Do not expire idempotency records after a short in-memory replay window. Retain them according to the financial record-retention agreement.
  • Do not create a new transaction identifier merely because an HTTP request timed out.

Ambiguous outcomes

An outcome is ambiguous when a caller cannot know whether the remote side committed—for example, a timeout after sending a request. Do not assume failure.

Operators can query:

  • POST /api/operator/get-bet-info for Wuzzlo’s view of one transaction.
  • POST /api/operator/get-market-result for aggregate and item-level round reconciliation.

These endpoints are signed, read-only evidence. They do not replace the operator’s durable callback handling and must not themselves create a second settlement.

Reconciliation job

Run a scheduled job that finds old DEBITED, locally pending, or ambiguous records and compares them with Wuzzlo. Correlate by operatorId, transactionId, roundId, and gameId. Escalate disagreements instead of silently adjusting balances.

For a round, compare totalBets, settledBets, openBets, totalStake, and totalPayout before comparing individual items.

Operational monitoring

Alert on:

  • callbacks that remain pending after retries;
  • signature failures or unexpected source networks;
  • repeated lifecycle conflicts;
  • balance or currency mismatches;
  • growing unsettled transaction age;
  • reconciliation differences;
  • elevated callback latency or HTTP failures.

Never include private keys, full session tokens, or sensitive player data in logs. Preserve request hashes and correlation identifiers for auditability.