Comprehensive Raffle Module

A practical skill for building raffle and giveaway systems — covering entry management, random winner selection, fairness validation, multi-tier prize distribution, and raffle administration for events, promotions, and community engagement.

When to Use This Skill

Choose Comprehensive Raffle Module when you need to:

• Build a fair, transparent raffle or giveaway system
• Implement weighted random selection for tiered prizes
• Manage entries with duplicate prevention and eligibility checks
• Create verifiable random draws for regulatory compliance
• Build automated raffle workflows for recurring events

Consider alternatives when:

• You need a full contest platform (use a contest management tool)
• You need payment/ticketing (use an event ticketing skill)
• You need gamification features (use a gamification skill)

Quick Start

Copy
import random
import hashlib
from datetime import datetime

class Raffle:
    def __init__(self, name, seed=None):
        self.name = name
        self.entries = []
        self.seed = seed or int(datetime.now().timestamp())
        self.drawn = False
        self.winners = []

    def add_entry(self, user_id, name, tickets=1):
        if any(e["user_id"] == user_id for e in self.entries):
            raise ValueError(f"User {user_id} already entered")
        self.entries.append({
            "user_id": user_id,
            "name": name,
            "tickets": tickets,
            "entered_at": datetime.now().isoformat(),
        })

    def draw(self, num_winners=1, exclude_previous=True):
        if self.drawn:
            raise RuntimeError("Raffle already drawn")

        pool = []
        for entry in self.entries:
            pool.extend([entry] * entry["tickets"])

        random.seed(self.seed)
        random.shuffle(pool)

        winners = []
        seen = set()
        for candidate in pool:
            if candidate["user_id"] not in seen:
                winners.append(candidate)
                seen.add(candidate["user_id"])
                if len(winners) == num_winners:
                    break

        self.winners = winners
        self.drawn = True
        return winners

    def verify(self):
        """Reproduce the draw with the same seed."""
        original_winners = self.winners
        self.drawn = False
        reproduced = self.draw(len(original_winners))
        return all(
            o["user_id"] == r["user_id"]
            for o, r in zip(original_winners, reproduced)
        )

# Usage
raffle = Raffle("Holiday Giveaway", seed=42)
raffle.add_entry("u1", "Alice", tickets=1)
raffle.add_entry("u2", "Bob", tickets=2)
raffle.add_entry("u3", "Carol", tickets=1)
winners = raffle.draw(num_winners=1)
print(f"Winner: {winners[0]['name']}")
print(f"Verifiable: {raffle.verify()}")

Core Concepts

Raffle System Components

Component	Purpose	Implementation
Entry Management	Collect and validate entries	Database + validation rules
Random Selection	Fair winner selection	Seeded PRNG + verification
Prize Assignment	Map winners to prizes	Tiered distribution logic
Audit Trail	Prove fairness after the fact	Seed + entry log + timestamp
Notification	Inform winners and participants	Email/SMS notifications

Fairness Mechanisms

Copy
## Ensuring Raffle Fairness

### Verifiable Randomness
- Use a published seed (e.g., future stock market close)
- Commit to the seed before entries close
- Anyone can reproduce the draw with the seed

### Duplicate Prevention
- One entry per user ID (email, phone, or account)
- Hash-based deduplication for anonymous entries
- Entry window with clear open/close times

### Weighted Entries
| Entry Method       | Tickets | Fair? |
|-------------------|---------|-------|
| Standard entry    | 1       | ✅    |
| Referral bonus    | +1 each | ✅ (capped) |
| Purchase-based    | varies  | Check local laws |
| Social share      | +1      | ✅    |

### Audit Requirements
- Entry log with timestamps
- Random seed published before draw
- Draw algorithm source code available
- Winner notification log

Configuration

Parameter	Description	Example
raffle_name	Name of the raffle/giveaway	"Holiday Giveaway"
seed	Random seed for reproducibility	42 or timestamp
max_entries	Maximum entries per user	1
num_winners	Number of winners to draw	3
entry_window	Open/close times for entries	"Dec 1-15, 2024"
prize_tiers	Prize distribution tiers	[1st, 2nd, 3rd]

Best Practices

1. Publish the random seed before drawing — Commit to a seed publicly (e.g., "We'll use tomorrow's S&P 500 closing value") before entries close. This proves the draw wasn't rigged to favor specific participants.

2. Log every entry with a timestamp and hash — Create an immutable entry log. Each entry gets a hash of (user_id + timestamp + raffle_id). This audit trail is necessary for dispute resolution and regulatory compliance.

3. Cap weighted entries to prevent dominance — If referrals give bonus tickets, cap at 5-10 extra. Without caps, power users accumulate hundreds of tickets and dominate the pool, making the raffle feel unfair to casual participants.

4. Test the draw algorithm with known seeds — Before running a real raffle, run the algorithm with a fixed seed on test data multiple times. Verify it produces the same results each time (deterministic) and that the distribution is fair across many simulations.

5. Check local regulations before launching — Many jurisdictions have laws about raffles, sweepstakes, and lotteries. Purchase-required entries may classify as a lottery (often illegal without a license). Free-entry alternatives are usually safer.

Common Issues

Same user wins multiple draws in recurring raffles — Without exclusion logic, prolific entrants may win repeatedly. Implement a cooldown period (e.g., winners are ineligible for the next 3 raffles) or weighted disadvantaging for recent winners.

Entry validation fails to catch duplicate accounts — Users create multiple accounts to increase their odds. Use multiple validation signals (email, phone, IP address, device fingerprint) to detect duplicate entries. No single signal is foolproof.

Random selection isn't actually random — Using Math.random() without a seed is non-reproducible and potentially biased. Use a cryptographically seeded PRNG for production raffles. Python's random.seed() with a published seed provides reproducibility; secrets module provides cryptographic randomness.