Stx-Raffle Smart Contract

[oyin-da]

Raffle Smart Contract - Detailed Description

Overview

This Clarity smart contract implements a comprehensive raffle system on the Stacks blockchain, designed for fair and transparent prize distribution. The contract manages the entire raffle lifecycle from participant entry to winner selection and prize disbursement, with built-in security measures and administrative controls.

Core Architecture

The contract operates on a single-raffle-at-a-time model, where each raffle has a unique ID and maintains complete isolation from previous raffles. The system uses a combination of data variables for current state management and data maps for historical record-keeping and participant tracking.

State Management:

• Current raffle tracking via incrementing raffle IDs
• Active/inactive status controls to prevent overlapping raffles
• Participant lists stored as bounded lists (max 100 participants)
• Entry validation through user-to-raffle mapping
• Prize pool accumulation with automatic fee calculation

Functional Components

Entry System

The entry mechanism requires participants to pay a configurable STX fee to join the active raffle. The contract enforces strict validation rules: users can only enter once per raffle, payments must match the exact entry fee, and the raffle must be active with available slots. All entry fees are accumulated in the contract balance to form the prize pool.

Winner Selection Algorithm

Winner selection employs a pseudo-random algorithm that combines multiple blockchain variables for unpredictability:

• Current block height for temporal variance
• Previous block hash for cryptographic randomness
• Current raffle ID for uniqueness
• Modulo operation against participant count for fair distribution

This approach ensures that winners cannot be predicted in advance while maintaining deterministic reproducibility for verification.

Prize Distribution

Upon winner selection, the contract automatically calculates and distributes funds:

1. Owner Fee Calculation: Configurable percentage (default 5%, max 20%) deducted from total prize pool
2. Winner Prize: Remaining amount after owner fee deduction
3. Automatic Transfer: Both owner fee and winner prize transferred via contract-controlled STX transfers
4. Transaction Atomicity: All transfers occur within a single transaction to prevent partial failures

Administrative Controls

The contract owner (deployer address) has exclusive access to critical functions:

• Raffle Creation: Set entry fees and participant limits for new raffles
• Winner Drawing: Trigger the selection and payout process
• Emergency Management: Close active raffles and issue full refunds to participants
• Fee Adjustment: Modify owner fee percentage within defined limits

Security Architecture

Access Control

The contract implements strict role-based access control with owner verification on all administrative functions. The owner address is immutably set at deployment and cannot be changed, ensuring consistent control authority.

State Validation

Comprehensive validation prevents common attack vectors:

• Double Entry Prevention: User entries tracked to prevent multiple participations
• State Consistency: Raffle status checks ensure operations only occur in valid states
• Amount Validation: Entry fees and participant limits validated for reasonable ranges
• Transfer Verification: All STX transfers wrapped in error handling to prevent fund loss

Data Integrity

The contract maintains complete audit trails through immutable historical records stored in maps. Each completed raffle generates a permanent record including winner, prize amount, participant count, and timestamp for full transparency.

Technical Implementation Details

Random Number Generation

The randomness source combines block-height entropy with hash-based unpredictability. While not cryptographically perfect, this approach provides sufficient randomness for fair lottery systems within the constraints of deterministic blockchain execution.

Memory Management

Participant lists are implemented as bounded Clarity lists with a maximum of 100 entries, ensuring predictable gas costs and preventing unbounded growth attacks. User entry mappings are automatically cleared between raffles to prevent memory bloat.

Error Handling

The contract defines specific error codes for all failure scenarios, enabling precise debugging and user feedback. All operations use Clarity's built-in error propagation to ensure transaction rollback on any failure condition.

Economic Model

The contract operates on a simple economic model where participants contribute entry fees to create a prize pool, with the majority going to the winner and a small percentage retained by the contract owner for operational costs. The fee structure is transparent and adjustable within reasonable bounds to maintain fairness while enabling sustainable operation.

This design creates aligned incentives: participants get fair chances at significant prizes, winners receive the majority of the pool, and operators are compensated for providing the service infrastructure.