A unique twist on the classic Tetris game that integrates with the Bitcoin network and Nostr protocol.
Important: Blockstr requires both an API server and frontend dev server to run.
# 1. Clone and install
git clone <your-repo-url>
cd blockstr
npm install
# 2. Configure environment variables
cp .env.example .env
# Edit .env and add your BLOCKSTR_NSEC
# 3. Start development servers (both API + frontend)
npm run devThis starts:
- Express API Server on
http://localhost:3000(handles score signing) - Vite Dev Server on
http://localhost:8080(React frontend)
Open http://localhost:8080 in your browser.
npm run dev (not just vite). Both servers must be running.
See DEPLOYMENT.md for detailed setup and production deployment instructions.
- Time-Based Difficulty: Game speed increases every 2 minutes for progressive challenge
- Countdown Timer: Live countdown showing time until next difficulty adjustment
- Bitcoin Block Integration: Scores transfer from mempool to mined when Bitcoin blocks are found
- Retro 8-bit Aesthetic: Pixel-perfect graphics with classic arcade styling
- Bonus Blocks: 1-in-100 chance for golden bonus blocks that give 10x points
- Dual Notifications: Separate alerts for difficulty increases and Bitcoin block mining
- Pay-to-Play: Lightning payments required to start a game (demo mode available)
- Nostr Integration: Scores published to the decentralized Nostr network
- Social Sharing: Share your achievements with the Nostr community
- React 18 with TypeScript
- TailwindCSS with custom retro styling
- Nostr Protocol for decentralized score sharing
- Bitcoin Mempool API for real-time block detection
- Lightning Network for payments (demo mode available)
- Press Start 2P retro pixel font
- Login with Nostr (browser extension or nsec bunker) or play anonymously
- Connect Wallet (WebLN extension or NWC) for Lightning payments
- Zap to Play: Send 210 sats to the Blockstr account to start (or use free play in demo mode)
- Classic Tetris controls:
- Arrow keys or WASD for movement
- Up arrow or W to rotate pieces
- Down arrow or S to soft drop
- Space bar for hard drop
- P to pause
- Difficulty Increases automatically every 2 minutes
- Mempool Score: Points accumulate in your mempool score during gameplay
- Mined Score: When Bitcoin blocks are found, mempool score transfers to mined score
- Bonus Points for clearing lines containing golden bonus blocks (★)
- Score Publishing: Only mined scores count and are published to gamestr.io
Game settings are centralized in /src/config/gameConfig.ts:
- Initial game speed and acceleration per level
- Level duration (2 minutes per level)
- Scoring multipliers and bonus chances
- Payment settings:
costToPlay: Fee in satoshis (default: 210 sats)zapMemo: Default zap message (customizable by players)freePlayEnabled: Toggle free play for testing (set tofalsein production)blockstrPubkey: Nostr pubkey receiving payments
- Board dimensions and visual settings
- Game identity and version
See PAYMENT_SYSTEM.md for detailed payment configuration.
Blockstr uses server-side signing to securely sign score events. The game's private key is stored as an environment variable on the server, never exposed to the client:
- Generate a keypair for Blockstr (one-time setup)
- Set environment variable
BLOCKSTR_NSECwith the private key - Deploy to VPS (Replit, DigitalOcean, etc.)
- Score events are signed by the server after validation
- Social posts are signed by the player's key
This architecture ensures:
- Score authenticity (signed by game provider)
- Player privacy (player pubkey in p-tag)
- Anti-cheat validation (server-side checks)
- Decentralized score storage
- Private key never exposed to client
See DEPLOYMENT.md for detailed setup instructions.
Blockstr implements a dual-score system with Bitcoin integration:
- Mempool Score: Points earned during gameplay (yellow) - builds up as you play
- Mined Score: Points transferred when Bitcoin blocks are mined (green) - permanent record
- Score Publishing: Only mined scores are published to gamestr.io
- Bitcoin Integration: Mempool scores transfer to mined when blocks are found
- Kind 30762: Addressable/replaceable game score events
- Signed by: Blockstr's bunker key (game provider)
- Player Reference: Player pubkey in p-tag
- Required Tags: d (identifier), p (player), game, score
- Optional Tags: state, match, difficulty, duration, version, referee, genre
- Leaderboards: Query and rank scores across the network
- Verification: Cryptographic proof of game completion (signed by game)
- Replaceability: Scores can be updated using the same d-tag identifier
- Anonymous Play: Temporary keypairs for guests
- Score Publishing: Permanent score records on Nostr
- Social Sharing: Post achievements to your Nostr feed
- Leaderboards: Query top scores from the network
- Decentralized: No central game servers required
- Pay-to-Play: Zap 210 sats to the Blockstr account to start games
- WebLN Support: Browser extension wallet integration (Alby, Mutiny, etc.)
- NWC Compatible: Nostr Wallet Connect support for remote wallets
- Custom Messages: Players can customize zap messages
- Demo Mode: Free play option for testing (configurable in
gameConfig.ts) - Multiple Wallets: Support for multiple NWC connections with wallet switching
- Fallback Payment: Manual invoice payment if automatic methods fail
- 8-bit Retro: Authentic arcade game appearance
- Pixel Perfect: Sharp, blocky graphics
- Retro Font: Press Start 2P for authentic feel
- Color Coding: Different piece colors and bonus indicators
- Scanlines Effect: Optional CRT monitor simulation
- Responsive: Works on desktop and mobile devices
- Real-time Blocks: Connects to mempool.space API
- Mempool Scoring: Scores accumulate in mempool until blocks are mined
- Block Notifications: Toast alerts when Bitcoin blocks are mined and scores transfer
- Difficulty Notifications: Alerts every 2 minutes when difficulty increases
- Statistics: Track how many blocks were mined during gameplay
Track your progress with:
- High Scores: Personal and global leaderboards
- Block Survival: How many Bitcoin blocks you survived
- Line Clearing: Total lines cleared across all games
- Bonus Points: Points earned from golden bonus blocks
- Time Played: Total game duration and session times
Blockstr is built as a PWA with:
- Offline Play: Core game works without internet
- App Installation: Add to home screen on mobile
- Push Notifications: New Bitcoin block alerts
- Full Screen: Immersive gaming experience
Built with the MKStack template:
- Modern React development environment
- TypeScript for type safety
- TailwindCSS for styling
- Vite for fast builds
- Comprehensive testing setup
- Font: Press Start 2P by CodeMan38
- Inspiration: Classic Tetris and Bitcoin community
- APIs: Mempool.space for Bitcoin data
- Framework: Vibed with MKStack
Play Blockstr: Where Bitcoin blocks meet falling blocks!
Built on Nostr. Powered by Bitcoin. Played by everyone.