[Plan] 🎯 Advanced Random Airdrop System with Chainlink VRF & Automation

Documentation

A comprehensive Solidity project that combines Chainlink VRF (Verifiable Random Function) and Chainlink Automation to create a fully automated, fair, and transparent airdrop distribution system.

🌟 What Makes This Project Special

This isn't just another airdrop contract. It's a complete automated ecosystem that demonstrates advanced smart contract patterns, Chainlink integrations, and real-world deployment strategies.

• Fully Automated: No manual intervention required after setup
• Provably Fair: Uses Chainlink VRF for verifiable randomness

🎓 Learning Objectives

🔗 Chainlink VRF Integration

• Requesting and handling verifiable random numbers
• Managing VRF subscriptions and LINK payments
• Implementing callback functions with proper error handling
• Working with request IDs and async responses

🤖 Chainlink Automation (Keepers)

• Setting up automated time-based triggers
• Implementing checkUpkeep and performUpkeep functions
• Managing contract state transitions automatically
• Handling complex automation logic

🏗️ Advanced Smart Contract Patterns

• Custom Errors: Gas-efficient error handling
• Events: Comprehensive logging and monitoring
• Enums: Clean state management
• Modifiers: Access control and validation
• CEI Pattern: Checks-Effects-Interactions security

🧪 Professional Testing & Deployment

• Unit tests with Foundry
• Integration tests with forked networks
• Fuzz testing for edge cases
• Mock contracts for local development
• Deployment scripts for multiple networks
• Gas optimization techniques

🧪 Testing Strategy

Unit Tests

forge test --match-test testRegistration
forge test --match-test testVRFCallback
forge test --match-test testAutomation

Integration Tests

forge test --fork-url $SEPOLIA_RPC_URL

Fuzz Tests

forge test --match-test testFuzz_MultipleRegistrations

Gas Analysis

forge test --gas-report

🚀 Deployment & Interaction

Local Development

# Start local blockchain
anvil

# Deploy to local
forge script script/DeployAirdrop.s.sol --rpc-url http://localhost:8545 --broadcast

Testnet Deployment

# Deploy to Sepolia
make deploy ARGS="--network sepolia"

# Verify contract
make verify ARGS="--network sepolia"

Interaction Scripts

# Register for airdrop
cast send $CONTRACT_ADDRESS "registerForAirdrop()" --private-key $PRIVATE_KEY

# Check registration status
cast call $CONTRACT_ADDRESS "isRegistered(address)" $YOUR_ADDRESS

📚 Dependencies

This project uses the following libraries:

• Chainlink contracts for VRF (Verifiable Random Function) and Automation
• OpenZeppelin contracts for security and utility functions
• Forge Standard Library for testing

Installing Dependencies

To install all required libraries with Foundry, run:

# Install all dependencies at once
forge install

# Or install each dependency individually
forge install smartcontractkit/chainlink-brownie-contracts --no-commit
forge install foundry-rs/forge-std --no-commit
forge install OpenZeppelin/openzeppelin-contracts --no-commit

Note: The --no-commit flag prevents Foundry from committing the changes to your repository.

🎯 Project Milestones

Week 1: Foundation

• Project setup and basic contract structure
• Registration system implementation
• Basic VRF integration
• Initial testing framework

Week 1: Automation

• Chainlink Automation integration
• Automated phase transitions
• Winner selection logic
• Integration testing

Week 2: Advanced Features

• Multi-tier prize system (optional)
• Weighted selection algorithm (optional)
• Anti-Sybil protection
• Gas optimization

Week 2: Production Ready

• Comprehensive testing
• Deployment scripts
• Documentation
• Security review

🏆 Success Metrics

By the end of this project, you'll have:

• ✅ A fully functional automated airdrop system
• ✅ Deep understanding of Chainlink VRF and Automation
• ✅ Professional-grade testing and deployment skills
• ✅ Gas-optimized and secure smart contracts
• ✅ Real-world deployment experience

Contents

• Errors
• Events

Errors

Git Source

Errors

AirDrop_WrongAmountOfETHSent

error AirDrop_WrongAmountOfETHSent(uint256 msgValue, uint256 i_entranceFee);

AirDrop_NotTheWinner

error AirDrop_NotTheWinner();

AirDrop_NoActiveLottery

error AirDrop_NoActiveLottery();

Events

Git Source

Events

Registration

Emitted when a user successfully registers for the current lottery

event Registration(address indexed user);

Parameters

RaffleStarted

Emitted when a raffle is started and ready for winner selection

event RaffleStarted(uint256 amountOfParticipants, uint256 amountOfTokens, uint256 changesToWinPerParticipant);

Parameters

winnerSelected

Emitted when a winner has been selected for the lottery

event winnerSelected(address indexed winner);

Parameters

Airdrop

Git Source

Inherits: VRFConsumerBaseV2Plus, ReentrancyGuard, Errors, Events

State Variables

NUM_WORDS

uint32 private constant NUM_WORDS = 1;

REQUEST_CONFIRMATIONS

uint16 private constant REQUEST_CONFIRMATIONS = 3;

i_entranceFee

uint256 private immutable i_entranceFee;

i_amountOfParticipantsPerLottery

uint256 private immutable i_amountOfParticipantsPerLottery;

i_subId

uint256 private immutable i_subId;

i_keyHash

bytes32 private immutable i_keyHash;

i_callbackGasLimit

uint32 private immutable i_callbackGasLimit;

lotteries

lottery[] private lotteries;

s_currentLotteryId

uint256 private s_currentLotteryId;

Functions

constructor

constructor(
    uint256 _entranceFee,
    uint256 _amountOfParticipantsPerLottery,
    address _vrfCoordinator,
    uint256 _subId,
    bytes32 _keyHash,
    uint32 _callbackGasLimit
) VRFConsumerBaseV2Plus(_vrfCoordinator);

registerForAirdrop

function registerForAirdrop() external payable;

fulfillRandomWords

function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) internal override;

startTheRaffle

function startTheRaffle() public;

claimTheRewards

function claimTheRewards(uint256 _lotteryId) public nonReentrant;

Structs

Participant

struct Participant {
    bool active;
    uint256 currentLotteryId;
    uint256 amountToClaim;
}

lottery

struct lottery {
    State state;
    Participant[] participants;
    uint256 amountOfParticipants;
    uint256 amountOfTokens;
    uint256 changesToWinPerParticipant;
    address theWinner;
    uint256 time;
}

Enums

State

enum State {
    Registration,
    Waiting,
    Finished
}