StreetHeist — Technical Overview
Architecture, API surface and current integration status for aggregators and studios
Build information loading…
This document describes the CURRENT, implemented scope of the StreetHeist server-authoritative demo build — not a roadmap or a marketing claim. Every capability below is marked Implemented only where the running code does it today; everything else is marked Demo-only, Planned or None. Read alongside the one-page Game Sheet and the landing page's Integration section.
1 · System diagram
Text alternative: the list below IS the diagram — read top to bottom (or left to right on wide screens) as one request/response pipeline.
- Player BrowserInput & presentation
- StreetHeist HTML5 Clientstreetheist/scripts/* — rendering, state machine, animation only
- StreetHeist Game APIapi-routes.js / api-route-table.js — session, round, verify
- Server-Authoritative Engineengine.js — commit-reveal RNG & payout math
- Mock Walletwallet.js — demo ledger, not a real payment rail
- Idempotency store idempotency.js — dedupes start/step/cashout retries
- Round repository round-repository.js / file-round-repository.js — session & round storage
- Structured logger observability/logger.js — redacted JSON audit lines
- Casino wallet client streetheist/operator/ — casino sessions: signed bet / win / rollback to the casino's own wallet; off unless a casino is configured
2 · Client / server responsibilities
Client (browser)
- Draws the hand-drawn vector city in real time (WebGL) and plays result/motion animation
- Drives the round UI through the state machine below
- Calls the API; never computes an outcome or a payout itself
- Restores an in-progress round from server data on load
Server (Node, dependency-free)
- Owns session, balance and round state (round-repository.js)
- Resolves every outcome via commit-reveal RNG (engine.js)
- Computes integer minor-unit payouts; applies them via the mock wallet, or the casino's wallet for a casino session
- Validates every request field; rejects unknown fields (api-validators.js)
3 · Current API endpoints
| Method | Path | Purpose |
|---|---|---|
GET | /api/config | Public odds/config for rendering (no secrets) |
POST | /api/session | Create or resume a session |
POST | /api/fair/client-seed | Set the player's client seed |
POST | /api/fair/rotate | Reveal the previous server seed, issue a new commitment |
POST | /api/round/start | Start a round for a bet (idempotent) |
POST | /api/round/step | Rob the next target (idempotent) |
POST | /api/round/cashout | Bank the current pot (idempotent) |
POST | /api/verify | Recompute a revealed round for independent fairness verification |
GET | /api/districts | The street catalogue with its disclosed RTP and bust chance |
POST | /api/district | Select the street a session plays in (one street today) |
POST | /api/session/code, /api/session/resume | Resume codes — carry a demo to another device. No credentials: the server mints a random 80-bit code, stores only its SHA-256, and exchanges it for the session it points at. Nothing stored identifies a player. |
POST | /api/operator/launch, /api/operator/session | Real-money mode: the casino's signed launch, then the game page trades the one-time launch code for the session. 404 unless a casino is configured |
POST | /api/hub88/game/url, /game/list, /game/round | Hub88's signed calls (RSA-SHA256). 404 unless Hub88 is configured |
POST | /api/payments/coinbase/* | Sandbox top-up demonstration (config, checkout, status, simulate, mode) — test funds only, never a real payment rail |
Any other method on a known path returns 405 with an Allow header; an unknown path returns 404.
4 · Round state machine
Client-side machine (streetheist/scripts/client-machine.js) — the transition table there is the single source of truth; UI code never branches around it.
- BOOTING
- RESTORING
- READY
- STARTING
- ACTIVE
- ACTION_PENDING
- RESULT_PRESENTING
- CASHOUT_PENDING
- SETTLED
- FAILED
- ERROR
ERROR is a connection/technical state, kept visually distinct from FAILED (a confirmed lost round) — the two are never presented the same way.
5 · Integer minor-unit model
Every money value on the wire and in storage is an integer count of minor units of the session currency (cents; satoshi for BTC; 10⁻⁸ ETH for ETH) — betCents, potCents, balanceCents. No float ever represents money. The server floors the final multiplier-derived payout to whole minor units before crediting, and every persistence adapter asserts money fields are integers before writing them to disk.
6 · Commit-reveal overview
Before a round starts, the server generates a server seed and publishes only its SHA-256 commitment. Round outcomes are derived deterministically from the (server seed, client seed, nonce) triple via HMAC-SHA256; the same triple decides how many targets each step offers — four, five or six, equally likely. Every round records the rule it was dealt under, so rounds from the earlier five-target rule still replay exactly. The server seed is revealed only after the round it protects is over (/api/fair/rotate), so a player can confirm afterwards, via /api/verify, that the revealed seed matches the earlier commitment and reproduces the exact round they played. No seed value, HMAC key material, or other secret is published anywhere in this document.
7 · Idempotency status
Implemented — every state-changing route (start/step/cashout) accepts an optional requestId. A repeated id with the same payload replays the original response instead of re-running the round logic; the same id with a different payload is rejected with a conflict error. The dedupe store itself is in-memory, bounded per session, and time-limited — a demo-scale safeguard, not a distributed/durable idempotency layer.
8 · Restore status
Implemented — reloading the page (or losing the connection) resumes the session and re-renders whatever round state the server holds — active, busted, or cashed — without ever re-submitting a start/step/cashout call. Persistence backing that state: Demo-only (not production) — local runs can use memory or a file adapter; the hosted presentation build requires the Postgres adapter. Certification-grade retention, export and operational controls remain outstanding.
9 · Mock wallet status
Wallet: Demo-only (not production). Demo sessions' bet debits and payout credits flow through a small, transaction-audited, idempotent interface (wallet.js) rather than a raw balance mutation — a demo ledger, not a payment rail. Casino sessions bypass it: their stakes and wins go to the casino's own wallet as signed, idempotent bet / win / rollback calls (see §10).
10 · Known production gaps
- The Postgres adapter durably stores the current session/round document, but a complete immutable game-cycle history with regulatory retention and export is not implemented.
- The demo wallet is a mock (demo-only). Real money moves only through a casino's own wallet, and only on a server configured for that casino; without one the casino routes answer 404, as on the public demo.
- Certification: None — no real-money certification or licensing has been obtained.
- Aggregator integration: Implemented — the casino wallet protocol (signed launch; idempotent bet / win / rollback) and a Hub88 adapter, tested against a reference casino and a Hub88 simulator. Not yet connected to any live casino; other aggregators' own APIs are mapped per integration, and a server crash between a bet and its answer is not yet reconciled automatically.
- No real identity, KYC, age verification, deposit or withdrawal flow of any kind — those stay with the casino, whose wallet holds all real money. The account system was removed in favour of resume codes: this build holds no username, password hash, or email, so it is not a controller of player credentials.
- Rate limits and the external audit sink are not yet shared across every server instance; those controls must be durable before regulated multi-instance operation.
11 · Build & algorithm version
| Product version | Loading… |
|---|---|
| API version | Loading… |
| Math / algorithm model | Loading… |
| Build date | Loading… |
Demonstration build only. The demo balance has no monetary value · no real-money deposits or withdrawals · not licensed real-money gambling software. This document is a technical status snapshot, not a commercial commitment.