Sandbox & Testing

Velo provides a certification sandbox mode for integration testing. The sandbox uses an in-memory wallet that simulates operator responses — including configurable error injection — so you can validate your integration without connecting to a live wallet.

Activating Sandbox Mode

Set the environment variable before starting the RGS:

WALLET_MODE=sandbox cargo run -p velo-rgs

When active, the RGS logs:

INFO Using sandbox wallet (certification mode)

Pre-Seeded Test Players

The sandbox ships with 5 pre-seeded players, each with a $10,000 balance:

Player ID	Balance
sandbox-player-1	$10,000
sandbox-player-2	$10,000
sandbox-player-3	$10,000
sandbox-player-4	$10,000
sandbox-player-5	$10,000

Any unknown player token passed to /wallet/authenticate is auto-registered with the default balance.

Features

Feature	Description
In-memory balances	No database required — balances are tracked in memory
Idempotency	Duplicate transaction_id returns the original response
Error injection	Configurable InsufficientBalance and NetworkError triggers
Full API compatibility	Implements all 6 wallet endpoints (authenticate, debit, credit, rollback, balance, end_round)

Error Injection

The sandbox supports configurable error injection to validate your system handles operator-side failures gracefully. This mirrors the Aristocrat Fusion certification requirement of intentionally illogical responses.

Injected InsufficientBalance

Trigger an InsufficientBalance error on the Nth debit, even if the player has sufficient funds. This tests your error-handling resilience.

Injected Timeout

Simulate a NetworkError (timeout) on the Nth credit. This tests your retry logic, backoff behavior, and idempotency implementation.

Why Test Illogical Errors?

In production, operator wallets may return unexpected errors due to AML holds, concurrent session conflicts, or internal platform issues. Your integration must handle these gracefully — never locking the player's session or corrupting game state.

Certification Phases

Follow this structured testing progression before going live. Each phase increases transaction volume to validate resilience at scale.

Phase 1: Basic Flow (5 users × 50 transactions)

Validate the core debit/credit/settle cycle:

• [ ] Authenticate all 5 sandbox players
• [ ] Place bets across multiple rounds
• [ ] Verify debit amounts match stake
• [ ] Verify credit amounts match calculated payout
• [ ] Verify end_round acknowledgment
• [ ] Verify balance consistency after all rounds

Phase 2: Error Handling (5 users × 500 transactions)

Validate error resilience and edge cases:

• [ ] Handle InsufficientBalance errors gracefully (no locked sessions)
• [ ] Handle NetworkError timeouts (verify retry + idempotency)
• [ ] Verify debit-timeout auto-rollback (funds returned after timeout)
• [ ] Handle duplicate transaction_id (same response, no re-processing)
• [ ] Verify TIMESTAMP_EXPIRED rejection for stale HMAC requests
• [ ] Handle PLAYER_BLOCKED and SESSION_EXPIRED errors

Phase 3: Volume Stress (5 users × 5,000 transactions)

Validate performance under sustained load:

• [ ] No balance drift after 5,000 transactions
• [ ] Retry backoff with jitter — no thundering herd
• [ ] No memory leaks or connection pool exhaustion
• [ ] All transaction IDs unique and traceable
• [ ] Reconciliation API returns accurate totals

Go-Live Validation Checklist

Before requesting production credentials, verify:

Check	Status
All 6 wallet endpoints implemented and responding	☐
HMAC-SHA256 signature verification on all callbacks	☐
Timestamp freshness validation (±5 min)	☐
Idempotency on transaction_id (no double-debit/credit)	☐
Rollback sent on debit timeout	☐
Error codes handled without session lock	☐
Game Launch API returning valid sessions	☐
Game rendering correctly in iframe	☐
postMessage events flowing correctly	☐
Reconciliation API returning accurate round data	☐

---

Ready to go live? Contact hi@velo.games with your certification results.