HooLotto LotteryRewardsHook

A Uniswap V4 hook that implements a gamified lottery-based rewards system for liquidity providers (LPs) and swappers. Built on Uniswap V4's hook architecture, it transforms DeFi participation into an engaging experience with randomized multipliers, NFT boosts, and weekly jackpots.

Overview

The LotteryRewardsHook collects a 2% fee on all pool operations and redistributes rewards through a lottery system:

• 1.8% goes to the rewards pool (distributed to participants)
• 0.2% goes to the protocol owner

Key Features

Feature	Description
🎰 Lottery Multipliers	LPs earn 1-5x, swappers earn 1-3x on their contributions
💰 Hybrid LP Rewards	LPs earn from both liquidity provision AND ongoing swaps (50/50 split)
🏆 Weekly Jackpots	10% of epoch rewards accumulate for weekly lottery drawings
📊 Volume Milestones	Pool-wide bonuses at $100K (1.2x), $500K (1.5x), $1M (2x)
🎨 NFT Boosts	Hold partner NFTs for 1.1x-2x reward multipliers
⏰ 24-Hour Epochs	Daily reward distribution cycles

How It Works

Reward Flow

┌─────────────────────────────────────────────────────────────────┐
│                         2% Total Fee                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────────┐         ┌─────────────────┐               │
│   │  1.8% Rewards   │         │   0.2% Owner    │               │
│   └────────┬────────┘         └─────────────────┘               │
│            │                                                    │
│   ┌────────┴────────┐                                           │
│   │                 │                                           │
│   ▼                 ▼                                           │
│ ┌─────────┐   ┌─────────────┐                                   │
│ │   90%   │   │    10%      │                                   │
│ │ Epoch   │   │  Jackpot    │                                   │
│ │ Rewards │   │   Pool      │                                   │
│ └────┬────┘   └─────────────┘                                   │
│      │                                                          │
│      ▼                                                          │
│ ┌────────────────────────────────────────┐                      │
│ │     Distributed Based On:              │                      │
│ │  • Contribution amount                 │                      │
│ │  • Random multiplier (1-5x LP, 1-3x)   │                      │
│ │  • Volume tier bonus (up to 2x)        │                      │
│ │  • NFT boost (up to 2x)                │                      │
│ └────────────────────────────────────────┘                      │
└─────────────────────────────────────────────────────────────────┘

Hybrid LP Rewards Mechanism

LPs don't just earn from their own liquidity operations—they also earn a share of all swap fees in the pool:

                    Swap Fees (1.8% rewards portion)
                              │
                              ▼
              ┌───────────────┴───────────────┐
              │                               │
              ▼                               ▼
        ┌───────────┐                  ┌───────────┐
        │    50%    │                  │    50%    │
        │  Swapper  │                  │ LP Pool   │
        │  Lottery  │                  │  Rewards  │
        └───────────┘                  └─────┬─────┘
                                             │
                                             ▼
                          ┌──────────────────────────────┐
                          │  Distributed proportionally  │
                          │  to LP liquidity share       │
                          │  × lottery multiplier (1-5x) │
                          │  × volume bonus              │
                          │  × NFT boost                 │
                          └──────────────────────────────┘

Example:

• LP1 provides 25% of pool liquidity → earns 25% of LP swap rewards pool
• LP2 provides 75% of pool liquidity → earns 75% of LP swap rewards pool
• Both also apply lottery multipliers and bonuses to their share

Multiplier System

Multipliers are revealed after the epoch ends to prevent manipulation:

Participant Type	Multiplier Range	Reveal Timing
Liquidity Providers	1x - 5x	At epoch distribution
Swappers	1x - 3x	At epoch distribution
LP Swap Rewards	1x - 5x	At epoch distribution

The multiplier is calculated deterministically using:

keccak256(blockhash(endBlock), poolId, epochId, participant)

Volume Tier Bonuses

When combined epoch volume reaches milestones, all participants get boosted:

Tier	Volume Threshold	Bonus Multiplier
None	< $100K	1.0x
🥉 Bronze	≥ $100K	1.2x
🥈 Silver	≥ $500K	1.5x
🥇 Gold	≥ $1M	2.0x

NFT Boosts

Configure partner NFT collections for additional reward multipliers:

Tier	Boost Multiplier
Common	1.1x
Rare	1.25x
Epic	1.5x
Legendary	2.0x

The highest tier NFT held by a participant is used.

Weekly Jackpot

• 10% of each epoch's rewards go to the jackpot pool
• Drawing occurs after 7 epochs (1 week)
• Winner selected weighted by weekly participation
• Higher participation = more "tickets"

Installation

# Clone the repository
git clone https://github.com/BahadorGh/HooLotto.git
cd HooLotto

# Install dependencies
forge install

# Build
forge build

Testing

# Run all tests
forge test

# Run with fork (for mainnet integration tests)
forge test --fork-url https://ethereum-rpc.publicnode.com

# Run specific test suites
forge test --match-contract LotteryRewardsHookTest        # Unit tests
forge test --match-contract Integration                   # Integration tests  
forge test --match-contract Fork                          # Fork tests

# Run with verbosity
forge test -vvv

Test Coverage

Test Suite	Tests	Description
Unit Tests	65	Core functionality
Integration Tests	15	End-to-end scenarios
Fork Tests	24	Mainnet DAI/WETH pool
Total	104	Full coverage

Usage

Enabling a Pool

// After deploying the hook and initializing a pool
hook.enablePool(poolId);

Claiming Rewards

// Claim all pending rewards across epochs
(uint128 claimed0, uint128 claimed1) = hook.claimRewards(poolId);

Checking Claimable Rewards

(uint128 claimable0, uint128 claimable1) = hook.getClaimableRewards(poolId, userAddress);

Configuring NFT Boosts (Owner)

// Enable NFT boost for a collection
hook.configureNFTBoost(
    nftContractAddress,
    ILotteryRewardsHook.NFTBoostTier.Legendary,
    true // enabled
);

Drawing Weekly Jackpot

// Anyone can trigger (after week ends)
hook.drawJackpot(poolId);

Architecture

src/
├── LotteryRewardsHook.sol      # Main hook implementation
└── interfaces/
    └── ILotteryRewardsHook.sol # Interface with all types and events

test/
├── LotteryRewardsHook.t.sol           # Unit tests (65 tests)
├── LotteryRewardsHook.integration.t.sol # Integration tests (15 tests)
└── LotteryRewardsHook.fork.t.sol      # Fork tests (24 tests)

Key Constants

Constant	Value	Description
REWARDS_FEE_BPS	180 (1.8%)	Fee for rewards pool
OWNER_FEE_BPS	20 (0.2%)	Fee for protocol
LP_SWAP_FEE_SHARE_BPS	5000 (50%)	LP share of swap fees
EPOCH_DURATION	24 hours	Epoch length
MAX_LP_MULTIPLIER	5	Maximum LP lottery multiplier
MAX_SWAP_MULTIPLIER	3	Maximum swapper lottery multiplier
JACKPOT_PERCENTAGE_BPS	1000 (10%)	Jackpot allocation

Events

Event	Description
EpochStarted	New epoch begins
EpochDistributed	Rewards distributed for epoch
ParticipantRegistered	User registered for epoch
MultiplierRevealed	Lottery multiplier assigned
RewardsClaimed	User claimed rewards
SwapRewardsSplit	Swap fee split between swapper/LP pools
LPPositionUpdated	LP liquidity tracking updated
JackpotWon	Weekly jackpot claimed
VolumeMilestoneReached	Volume tier unlocked
NFTBoostApplied	NFT boost applied to participant

Security Considerations

1. Delayed Multiplier Reveal: Multipliers are calculated from block hash after epoch ends, preventing front-running
2. Reentrancy Protection: All external functions use nonReentrant modifier
3. Safe Token Transfers: Uses OpenZeppelin's SafeERC20
4. Owner Controls: Pool enabling/disabling and NFT configuration require owner

Partner Integrations

No partner integrations (EigenLayer, Fhenix) are not used in this submission.

This hook is a standalone implementation focused on gamified reward distribution mechanics.

Hookathon Submission

• Submission Type: Uniswap Hook Incubator (UHI)
• Demo Video: [I Link to demo video]
• GitHub: https://github.com/BahadorGh/HooLotto

What's New

• Gamified lottery-based rewards for Uniswap V4
• Hybrid LP rewards mechanism (LPs earn from swaps)
• Weekly jackpot system
• NFT boost integration
• Volume milestone bonuses
• 104 comprehensive tests (unit, integration, mainnet fork)

License

MIT

Author

HooLotto Team