A comprehensive suite of smart contracts built on the Stacks blockchain using Clarity, featuring interactive gaming contracts and decentralized finance (DeFi) protocols.
This project demonstrates advanced Clarity smart contract development patterns for gaming and financial applications on the Stacks blockchain. It includes both the games module (gaming contracts with wagers and multiplayer mechanics) and the tapit module (core DeFi infrastructure).
stacks-tapit/
├── games/ # Gaming contracts module
│ ├── contracts/
│ │ ├── CoinTossingGame.clar # Single-player coin flip game
│ │ ├── PingPong.clar # Two-player competitive game with powerups
│ │ └── NumberGuesser.clar # Number guessing game contract
│ ├── tests/ # Vitest test suite
│ ├── settings/
│ │ ├── Devnet.toml
│ │ ├── Testnet.toml
│ │ └── Mainnet.toml
│ ├── Clarinet.toml # Clarinet project config
│ ├── package.json
│ ├── tsconfig.json
│ └── vitest.config.ts
│
└── tapit/ # Core DeFi infrastructure
├── contracts/
├── tests/
├── settings/
└── [Standard Clarinet structure]
Purpose: Single-player coin flip game with escrowed wagers
Key Features:
- Create games with specified wagers
- Fund games with STX
- Flip coins and determine winners
- Claim winnings or request refunds
- Full game lifecycle management
Key Functions:
create-game (stake-amount)- Initialize a new gamefund-game (game-id)- Fund a game with STXflip-coin (game-id guess)- Flip and guess outcomeclaim-winnings (game-id)- Claim winning payoutscancel-game (game-id)- Cancel active gamerequest-refund (game-id)- Request refund for unresolved games
Technical Details:
- Minimum stake: 10 STX (10,000,000 microSTX)
- Game states: Pending, Funded, Completed, Cancelled
- Error handling with 9 distinct error codes
- Event logging for game lifecycle
Purpose: Two-player competitive game with staking, powerups, and timeout refunds
Key Features:
- Multi-round competitive gameplay
- Powerup system (health, damage boost, freeze)
- Staking mechanism for player investment
- Timeout refund protection
- Developer fee vault
- Game pause functionality
Key Functions:
create-game (opponent stake-amount)- Create new gamejoin-game (game-id stake-amount)- Accept and join gameplay-round (game-id move)- Execute game moveend-game (game-id result)- Conclude gamegrant-powerup (game-id player powerup-type)- Award powerupuse-powerup (game-id powerup-id)- Use powerup in gameclaim-timeout-refund (game-id)- Refund after timeoutwithdraw-dev-fees ()- Contract admin withdrawal
Technical Details:
- Game states: Created, Active, Completed, Refunded
- 3 powerup types: Health (+50 HP), Damage (2x damage), Freeze (skip opponent turn)
- Max 100 rounds per game
- Timeout: 1,440 blocks (≈6 hours on Stacks)
- Dev fee: 2.5% of winning amount
- Query functions for game state inspection
Purpose: Number guessing game with range prediction
Key Features:
- Guess numbers within dynamic ranges
- Adjustable difficulty levels
- Scoring based on proximity to target
- Multi-guess rounds
The tapit module contains core infrastructure for DeFi applications (details to be expanded based on contract implementations).
- Node.js (v16+)
- Clarinet CLI - Installation guide
- Git
# Clone the repository
git clone <repository-url>
cd stacks-tapit
# Install dependencies for games module
cd games
npm install
# Install dependencies for tapit module
cd ../tapit
npm install# Test games contracts
cd games
npm run test # Run all tests
npm run test:watch # Watch mode with coverage
npm run test:report # Generate coverage report
# Test tapit contracts
cd ../tapit
npm run test# Start Clarinet development environment
clarinet console
# In the Clarinet console:
(contract-call? .coin-toss-game create-game u10000000)- Data Variables: Track global state (counters, pools, totals)
- Maps: Store structured data (games, groups, member histories)
- Error Codes: Consistent error handling (u1-u9 range)
- Principal-based access control
- STX transfer validation with error handling
- Guard assertions for pre-condition checks
- Immutable game state transitions
- Public Functions: State-modifying operations (begin with
define-public) - Read-Only Functions: Query operations (begin with
define-read-only) - Private Functions: Internal utilities (begin with
define-private)
| Code | Description |
|---|---|
| u1 | Invalid group/game ID |
| u2 | Insufficient stake amount |
| u3 | Group/game not active |
| u4 | Member/player not found |
| u5 | Unauthorized access |
| u6 | Invalid stake amount |
| u7 | Duplicate member |
| u8 | History not found |
| u9 | Transfer failed |
- Clarity: Smart contract language for Stacks
- Stacks Blockchain: Layer-1 smart contract platform for Bitcoin
- Vitest: Unit testing framework
- Clarinet: Development environment and testing framework
- TypeScript: Test suite language
Edit the appropriate settings file:
# games/settings/Devnet.toml
[network]
name = "devnet"
node_rpc_address = "http://localhost:20443"Available configurations:
Devnet.toml- Local developmentTestnet.toml- Stacks TestnetMainnet.toml- Stacks Mainnet
;; Create and manage coin toss games
(create-game (stake-amount uint))
(fund-game (game-id uint))
(flip-coin (game-id uint) (guess bool))
(claim-winnings (game-id uint))
(cancel-game (game-id uint))
;; Queries
(get-game-details (game-id uint))
(get-active-games-count)
(get-player-win-rate (player principal));; Game management
(create-game (opponent principal) (stake-amount uint))
(join-game (game-id uint) (stake-amount uint))
(play-round (game-id uint) (move uint))
(end-game (game-id uint) (result bool))
;; Powerup system
(grant-powerup (game-id uint) (player principal) (powerup-type uint))
(use-powerup (game-id uint) (powerup-id uint))
;; Withdrawals
(claim-timeout-refund (game-id uint))
(withdraw-dev-fees)
;; Queries
(get-game-state (game-id uint))
(get-player-stats (player principal))
(get-active-games (player principal))- Create a feature branch:
git checkout -b feature/new-contract - Implement contract changes
- Add comprehensive tests in
tests/directory - Ensure all tests pass:
npm run test - Commit with meaningful messages
- Push and create a pull request
Tests are written in TypeScript using Vitest and the Clarinet SDK:
// Example test structure
describe("CoinTossingGame", () => {
it("should create a game", () => {
const wallet = accounts.deployer;
const response = simnet.callPublicFn(
"coin-toss-game",
"create-game",
[Cl.uint(10000000)],
wallet.address
);
expect(response.result).toBeOk();
});
});cd games
clarinet deploy --testnet# IMPORTANT: Ensure thorough testing before mainnet deployment
clarinet deploy --mainnet- Map Size Limits: Lists capped at 1,000 items per map entry
- Block Time: ~10 minutes per Stacks block
- Transaction Cost: Varies based on bytecode size
- Gas Optimization: Use efficient map queries and avoid nested loops
# View contract calls in development
clarinet console
# Check transaction history
(contract-call? .coin-toss-game get-active-games-count)
# Debug with detailed output
npm run test:report- Maximum list size: 1,000 members per group/game
- Map iteration not natively supported (requires manual tracking)
- No cross-contract calls to external protocols (planned for future versions)
- Single STX denomination (no other tokens currently)
- Multi-token support (sNS, others)
- Cross-contract composability
- Advanced powerup mechanics
- Tournament bracket system
- DAO governance layer
- Mainnet launch
Current Status: In Development - Not audited for production
Before mainnet deployment:
- Internal code review
- Security audit by third party
- Formal verification of critical functions
- Community testing on testnet
- Issues: Report bugs via GitHub Issues
- Discussions: Join Stacks Discord
- Documentation: See
docs/folder for detailed guides
ISC License - See LICENSE file for details
These contracts are provided as-is for educational and development purposes. Use at your own risk. Always conduct thorough security audits before deploying to mainnet with real assets.
Last Updated: December 19, 2025
Project Version: 1.0.0
Clarity Version: 3.0+
Stacks Network: Compatible with Stacks 2.4+