Skip to content

About

High-performance deterministic physics verifier, channel account settlement daemon, and Soroban indexer for Stellar Splash

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

197 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

๐ŸŒŠ Stellar Splash Engine

Backend Engine, Deterministic Game Verifier & Stellar Testnet Indexer

Stellar Network Live Frontend Contract Deployed Tests Passing Security Hardened

The backend orchestration and verification layer for the Stellar Splash gaming platform. It manages tournament lifecycles, issues anti-cheat session tokens, computes deterministic scores from raw game events, verifies real Stellar Testnet funding transactions, and reconciles prize pools against on-chain ledger records.


๐Ÿš€ Live Deployments & Verified On-Chain Contract

Resource / Transaction Details / Stellar Explorer Link
Live Web Application (Netlify) https://stellar-splash.netlify.app
Soroban Smart Contract ID CACHWJEZY6JN36VFACWRQ7FP4T5EPRRRNBVLOSFHXTJHETZY36JD7QYJ
Stellar Expert Contract Explorer View Contract on Stellar Expert
Stellar Lab Contract Explorer View Contract in Stellar Lab
Contract Deploy Transaction 36e93d93...6fb0 (Stellar Expert Tx)
WASM Upload Transaction 268685ea...fbe0 (Stellar Expert Tx)
Admin Initialization Transaction 27b3773d...1a11 (Stellar Expert Tx)
Live Tournament Test Tx 022786a7...2d7 (Stellar Expert Tx)
Contract Admin Address GCQ3OLBMJUGWN3PHYE3SDIKKIPVLJSFFWG4Q4CEABGHWGBEBPBKMY6OW
WASM Code Hash f4c5ffc8ce6364eccb4c2a3daac045c508ba4f2d16b3a345d3c5f208057fb2d5
Network Stellar Testnet (Passphrase: Test SDF Network ; September 2015)
Horizon RPC https://horizon-testnet.stellar.org
Soroban RPC https://soroban-testnet.stellar.org

๐Ÿ“ธ Product Operations & Screenshots

1. Tournament Indexing & Real-Time Vault Tracking

The engine indexes Stellar ledger transactions to independently verify creator prize deposits before opening tournaments.

Tournament Discovery and Indexing


2. High-Frequency Game Event Replay

Replays raw gameplay event streams to detect client score tampering and issue cryptographic match attestations.

Gameplay Event Replay


3. Prize Agreement Validation & Basis Points Invariant

Enforces the 10,000 basis points rule ($100.00%$), integer floor rounding, and dust allocation to Rank 1 before creator approval.

Prize Agreement Validation


4. Deterministic Standings & Canonical 32-Byte Ranking Hash

Computes finalized tournament rankings using a 3-tier tie-breaking algorithm and produces a canonical SHA-256 ranking hash.

Deterministic Standings


5. Multi-Recipient Settlement Execution

Evaluates the 5-point eligibility pipeline, authorizes payout batches, and executes Stellar Testnet transfers with individual receipt tracking.

Multi-Recipient Settlement


6. Player Payout Indexing & Historical Receipts

Provides dedicated REST endpoints for player payout histories, indexing on-chain transactions and verifying accounting reconciliation.

Player Payout History


๐Ÿ›๏ธ Architecture & Domain Modules

                                  +-----------------------+
                                  |    Express REST API   |
                                  |    & SSE Broadcaster  |
                                  +-----------------------+
                                              |
               +------------------------------+------------------------------+
               |                              |                              |
               v                              v                              v
      +-----------------+            +-----------------+            +-----------------+
      |  Game & Match   |            |   Tournament    |            |   Blockchain    |
      |     Engine      |            |     Engine      |            |     Indexer     |
      +-----------------+            +-----------------+            +-----------------+
      | - Session token |            | - Registration  |            | - Horizon API   |
      | - Event stream  |            | - State machine |            | - Tx validation |
      | - Integer score |            | - Capacity rule |            | - Vault auditor |
      | - Result hash   |            | - Leaderboard   |            | - Reconcile     |
      +-----------------+            +-----------------+            +-----------------+
               |                              |                              |
               +------------------------------+------------------------------+
                                              |
                                              v
                                  +-----------------------+
                                  | Store / Audit Ledger  |
                                  +-----------------------+

๐Ÿ›ก๏ธ Security Architecture & Anti-Cheat Controls

  • Statistical Anomaly Detection (AnomalyDetectorService): Replay verification inspects timestamp intervals, variance, spatial distribution, click trajectory, and impossible reaction bounds (<60ms). Replays with riskScore >= 90 are automatically rejected to eliminate macro/bot tampering.
  • OWASP Security Headers: Global securityHeadersMiddleware injects strict defense headers including HSTS (Strict-Transport-Security: max-age=31536000; includeSubDomains), Content Security Policy (CSP), X-Content-Type-Options: nosniff, and X-Frame-Options: DENY.
  • Proxy-Aware Rate Limiting: Hardened with app.set('trust proxy', 1), providing accurate client IP tracking behind load balancers/reverse proxies, paired with HMAC-authenticated bypass headers (X-Engine-Bypass-Token).
  • Role-Based Access Control: adminAuthMiddleware protects sensitive administrative actions (channel account registration, privileged settlement authorization).

๐Ÿ“‹ REST API Reference

Tournaments

  • GET /api/tournaments: List all tournaments and states.
  • GET /api/tournaments/:id: Fetch specific tournament configuration.
  • POST /api/tournaments: Create a new tournament (initializes in FUNDING state).
  • POST /api/tournaments/:id/join: Register a player wallet into an open tournament.
  • GET /api/tournaments/:id/leaderboard: Query live leaderboard distinguishing Current Score from Final Verified Result.

Result Verification & Attestations

  • POST /api/verification/match/:id: Trigger independent replay verification of a completed match, with automated statistical anomaly detection (riskScore >= 90 rejection).
  • GET /api/verification/match/:id: Retrieve verification record and signed cryptographic attestation.

Tournament Rankings

  • GET /api/rankings/:tournamentId: Retrieve deterministic tournament ranking.
  • POST /api/rankings/:tournamentId/finalize: Finalize tournament ranking and commit to canonical ranking hash.

Prize Agreements & Financial Rules

  • GET /api/agreements/:tournamentId: List all versioned prize agreements for a tournament.
  • GET /api/agreements/:tournamentId/active: Retrieve active (or LOCKED) prize agreement.
  • POST /api/agreements: Create a new prize agreement version (enforces 10,000 bps rule).
  • POST /api/agreements/:tournamentId/:version/approve: Creator approves specific agreement version and hash.
  • POST /api/agreements/:tournamentId/:version/lock: Lock agreement permanently.

Settlements & Multi-Recipient Payouts

  • GET /api/settlements/:tournamentId/eligibility: Evaluate strict 5-point settlement eligibility pipeline.
  • GET /api/settlements/:tournamentId/preview: Preview deterministic basis-point allocations, residual dust handling, and accounting invariants.
  • POST /api/settlements/:tournamentId/authorize: Cryptographically authorize settlement against exact agreement and ranking commitments (creator/admin authorized).
  • POST /api/settlements/:tournamentId/execute: Submit multi-recipient Stellar Testnet transfers with real transaction tracking (creator/admin authorized).
  • GET /api/settlements/:tournamentId: Retrieve settlement record and reconciliation status.
  • POST /api/settlements/:settlementId/reconcile: Trigger independent verification comparing expected vs observed on-chain allocations.
  • GET /api/settlements/player/:playerWallet: Retrieve player's historical payouts with explorer links.

Real-Time Events

  • GET /api/events: Server-Sent Events (SSE) streaming channel.

๐Ÿงช Testing & Verification

Run the automated test suite covering all modules:

npm test

All 256 unit, integration, and security tests across 72 test suites execute cleanly:

  • tournament.test.ts
  • scoring.test.ts
  • verification.test.ts
  • ranking.test.ts
  • agreement.test.ts
  • settlement.test.ts
  • anomaly-detector.test.ts
  • security-headers.test.ts
  • admin-auth.test.ts
  • rate-limiter.test.ts
  • account-synchronizer.test.ts
  • circuit-breaker.test.ts
  • ...and 60 additional test suites covering edge cases and concurrency.

๐Ÿ’ป Local Setup & Running

npm install
npm run build
npm start

By default, the server listens on http://localhost:4000.


๐Ÿ› ๏ธ Engine Architecture, Operations & Judge Evaluation Tools

Component / Guide Description & Link
Replay Verification Specification docs/REPLAY_VERIFICATION_SPEC.md - 60Hz physics, entropy checks
Channel Account Architecture docs/CHANNEL_ACCOUNTS_ARCHITECTURE.md - Parallel transaction execution
Disaster Recovery & RPC Failover docs/DISASTER_RECOVERY_RPC.md - Circuit breaking & retry queues
Postman API Collection (v2.1) docs/StellarSplash_Engine.postman_collection.json
Generate Postman Collection node scripts/generate-postman-collection.cjs
Verify Full Engine Pipeline npm run verify:pipeline
Synthetic Load Test Runner node scripts/load-test-synthetic.cjs
Memory Benchmark Profiler node scripts/benchmark-memory.cjs
Docker Compose Orchestration docker compose up --build (Includes Prometheus on port 9090)

About

High-performance deterministic physics verifier, channel account settlement daemon, and Soroban indexer for Stellar Splash

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages