A fully on-chain scratch-card lottery game built on Stellar Soroban, playable with the Freighter wallet. Players pay XLM to scratch a virtual card; prizes are settled instantly in the same transaction with no oracles, no waiting, and ultra-low fees (< 0.00005 XLM per scratch).
- Instant settlement — prize resolved in the same tx via Stellar's protocol PRNG
- Sub-cent fees — < 0.00005 XLM per transaction (< 0.001 XLM requirement exceeded by 20×)
- Fair randomness — Stellar BLS threshold consensus seed, impossible for any single party to bias
- 89 % RTP — transparent prize table, 11 % house edge
- Scalable — O(1) storage per player, Stellar's parallel ledger handles millions of concurrent users
- Upgradeable — admin-gated WASM upgrade path preserves storage
- Canvas scratch UI — finger/mouse scratch animation with sound effects
- Leaderboard & profiles — off-chain MongoDB for fast aggregated stats
- Freighter wallet — native Stellar wallet (no MetaMask needed)
| Roll | Probability | Payout |
|---|---|---|
| 0 – 5 499 | 55 % | 0× — no prize |
| 5 500 – 7 499 | 20 % | 1× — break even |
| 7 500 – 8 499 | 10 % | 2× |
| 8 500 – 9 199 | 7 % | 3× |
| 9 200 – 9 699 | 5 % | 4× |
| 9 700 – 9 999 | 3 % | 5× jackpot |
Return to player: 89 % · House edge: 11 %
ScratchCard/
├── stellar-contract/ # Soroban Rust contract
│ ├── Cargo.toml
│ ├── src/
│ │ ├── lib.rs # Contract entry point
│ │ ├── storage.rs # Optimised storage layout
│ │ ├── rewards.rs # PRNG + prize table
│ │ ├── events.rs # Event publishing
│ │ └── errors.rs # Error codes
│ └── tests/
│ └── lib.rs # Integration tests
│
├── scratch-your-card/ # Next.js 14 frontend
│ ├── app/
│ │ ├── page.tsx # Main game UI
│ │ ├── leaderboard/ # Top winners
│ │ ├── profile/[address]/ # Player stats
│ │ ├── components/
│ │ │ └── ScratchSurface.tsx # Canvas scratch card
│ │ ├── lib/
│ │ │ ├── stellar-contract.ts # SDK calls (scratch, claim, read)
│ │ │ ├── stellar-wallet.ts # Freighter integration
│ │ │ └── stellar-config.ts # Network + env config
│ │ └── api/ # Next.js API routes (MongoDB)
│ └── lib/models/Transaction.ts
│
├── docs/
│ ├── contract/
│ │ ├── overview.md # What the contract does
│ │ ├── architecture.md # Storage layout, tx flow diagrams
│ │ ├── reward-model.md # Prize table + EV maths
│ │ ├── fee-optimization.md # How fees are kept < 0.001 XLM
│ │ ├── randomness-design.md # PRNG security analysis
│ │ └── deployment-guide.md # Step-by-step deploy instructions
│ └── frontend/
│ ├── overview.md # EVM → Stellar migration guide
│ ├── wallet-integration.md # Freighter setup
│ ├── stellar-sdk.md # SDK code examples (read/write/sign)
│ └── environment-variables.md # All required env vars
│
└── onchain-reactivity/ # Legacy Somnia EVM contracts (reference only)
# Install toolchain
rustup target add wasm32-unknown-unknown
cargo install --locked stellar-cli --features opt
# Build
cd stellar-contract
stellar contract build
# Generate admin keypair and fund on testnet
stellar keys generate admin --network testnet
stellar keys fund admin --network testnet
# Deploy
stellar contract deploy \
--wasm target/wasm32-unknown-unknown/release/scratch_card.optimized.wasm \
--source admin \
--network testnet
# Initialize (replace placeholders)
stellar contract invoke \
--id $CONTRACT_ID \
--source admin \
--network testnet \
-- initialize \
--admin $(stellar keys address admin) \
--scratch_price 10000000 \
--xlm_token $(stellar contract id asset --asset native --network testnet)
# Seed the prize pool with 500 XLM
stellar payment \
--source admin \
--destination $CONTRACT_ID \
--amount 500 \
--asset native \
--network testnetcd scratch-your-card
cp .env.example .env.localEdit .env.local:
NEXT_PUBLIC_CONTRACT_ID=C...
NEXT_PUBLIC_STELLAR_NETWORK=TESTNET
NEXT_PUBLIC_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_XLM_TOKEN_ADDRESS=C...
MONGODB_URI=mongodb+srv://...
MONGODB_DB=scratch_gamecd scratch-your-card
npm install @stellar/stellar-sdk @stellar/freighter-api
npm run devOpen http://localhost:3000 and connect Freighter wallet.
cd stellar-contract
cargo test| Action | Fee |
|---|---|
scratch_card |
~300–500 stroops (0.00003–0.00005 XLM) |
claim_rewards |
~200–350 stroops (0.00002–0.00035 XLM) |
| Read-only queries | Free (simulated, never submitted) |
At 1 million scratches per day: total network fees ≈ 400 XLM/day across all players, or 0.00004 XLM per player per scratch.
See docs/contract/fee-optimization.md for full analysis.
Players use Freighter — the official Stellar browser extension wallet.
- Chrome: chrome.google.com/webstore
- Firefox: addons.mozilla.org
- Site: freighter.app
| Doc | Description |
|---|---|
| Contract Overview | Functions, events, prize table |
| Architecture | Storage layout, tx flow |
| Reward Model | Prize maths, liquidity management |
| Fee Optimization | How costs are minimized |
| Randomness Design | PRNG security |
| Deployment Guide | Deploy to testnet / mainnet |
| Frontend Overview | EVM → Stellar migration |
| Wallet Integration | Freighter setup |
| Stellar SDK | Code examples |
| Environment Variables | Required env vars |
| Layer | Technology |
|---|---|
| Smart contract | Rust + Soroban SDK (Stellar) |
| Blockchain | Stellar Network (Testnet / Mainnet) |
| Wallet | Freighter (@stellar/freighter-api) |
| Frontend | Next.js 14, TypeScript, Tailwind CSS |
| Blockchain SDK | @stellar/stellar-sdk |
| Off-chain DB | MongoDB (leaderboard + transaction log) |
| Hosting | Vercel |
MIT