Raffle Smart Contract

A robust and secure raffle system built on the Stacks blockchain using Clarity smart contracts. This contract enables fair and transparent raffles with automated winner selection and prize distribution.

Features

• Secure Entry System: Players pay an entry fee in STX to participate
• Fair Winner Selection: Cryptographically secure random winner selection using block data
• Automated Prize Distribution: Winners receive their prize automatically upon drawing
• Owner Fee Structure: Configurable owner fee (default 5%, max 20%)
• Raffle History: Complete tracking of past raffles and winners
• Emergency Controls: Owner can close raffles and issue refunds if needed
• Anti-Spam Protection: Users can only enter once per raffle

Contract Overview

Key Parameters

• Entry Fee: Configurable per raffle (minimum 1 microSTX)
• Max Participants: Up to 100 participants per raffle
• Owner Fee: 5% default, adjustable up to 20%
• Prize Pool: Total entries minus owner fee

Core Functions

For Contract Owner

• start-new-raffle(entry-fee, max-participants) - Create a new raffle
• draw-winner() - Select winner and distribute prizes
• emergency-close-raffle() - Close active raffle
• refund-participants() - Refund all participants (emergency use)
• update-owner-fee(percentage) - Adjust owner fee percentage

For Participants

• enter-raffle() - Enter the current active raffle
• get-raffle-info() - View current raffle details
• has-user-entered(user) - Check if user has entered

Read-Only Functions

• get-participants(raffle-id) - List all participants
• get-participant-count(raffle-id) - Number of participants
• get-raffle-history(raffle-id) - Historical raffle data
• get-contract-balance() - Current contract STX balance

How It Works

1. Raffle Creation: Contract owner starts a new raffle with specified entry fee and participant limit
2. Entry Phase: Users pay the entry fee to join the raffle (one entry per user)
3. Winner Selection: Owner calls draw-winner() which uses blockchain data for randomness
4. Prize Distribution: Winner receives the prize pool (total fees minus owner commission)
5. History Recording: Raffle results are permanently stored on-chain

Security Features

• Owner-Only Controls: Critical functions restricted to contract deployer
• Duplicate Entry Prevention: Users cannot enter the same raffle twice
• State Validation: Comprehensive checks prevent invalid operations
• Automatic Cleanup: User entries cleared between raffles
• Error Handling: Detailed error codes for all failure scenarios

Error Codes

• u100 - Owner-only function called by non-owner
• u101 - Resource not found
• u102 - User already entered this raffle
• u103 - Raffle is closed/inactive
• u104 - Raffle is already active
• u105 - Insufficient payment provided
• u106 - No participants in raffle
• u107 - Winner already drawn
• u108 - STX transfer failed
• u109 - Invalid amount specified

Usage Example

;; Owner starts a raffle: 1 STX entry fee, 50 max participants
(contract-call? .raffle start-new-raffle u1000000 u50)

;; User enters raffle (pays 1 STX)
(contract-call? .raffle enter-raffle)

;; Owner draws winner when ready
(contract-call? .raffle draw-winner)

;; Check raffle results
(contract-call? .raffle get-raffle-info)

Deployment Notes

• Contract owner is set to the transaction sender at deployment
• Initial raffle ID starts at 0
• No raffle is active upon deployment
• Owner fee percentage defaults to 5%

Security Considerations

This contract implements best practices for smart contract security, including proper access controls, state management, and error handling. The random number generation uses block height and hash data, providing sufficient unpredictability for fair winner selection.