documentation

everything you need to know about the uniluck protocol

◆ overview

UniLuck is a lucky holder lottery token built on Ethereum using Uniswap v4 hooks. Every 15 minutes, one eligible holder wins the entire accumulated swap tax from that period.

The protocol uses Chainlink VRF for provably fair randomness and Chainlink Automation for trustless draw triggers.

◈ how_it_works

hold

Hold at least 1,000,000 LUCK tokens in your wallet to be eligible for draws.

accumulate

Every swap on the LUCK/ETH pool incurs a 3% tax. This tax accumulates in the prize pool.

draw

Every 15 minutes, Chainlink Automation triggers a new draw. Chainlink VRF generates a provably random number.

win

The random number selects a winner from all eligible holders. Winners are weighted by a square-root formula based on holdings.

claim

Winners have 24 hours to claim their ETH prize. Unclaimed prizes roll over to the next round.

◇ eligibility

To participate in draws, you must hold at least 1,000,000 LUCK (0.1% of total supply).

Your number of entries is calculated using a square-root formula:

entries = floor(sqrt(balance / minThreshold))

This means holding more tokens gives you more entries, but with diminishing returns. A holder with 4x the minimum gets 2 entries, not 4.

■ token_stats

total supply	1,000,000,000 LUCK
swap tax	3% (buy & sell)
tax distribution	100% to prize pool
draw interval	15 minutes
min holding	1,000,000 LUCK
claim window	24 hours
network	ethereum mainnet

▣ smart_contracts

The protocol consists of three core contracts:

UniLuckToken

ERC20 token with 1B fixed supply. No mint function, no proxy.

UniLuckHook

Uniswap v4 afterSwap hook. Collects 3% tax on every swap and holds it for the lottery.

LotteryManager

Manages draws, VRF requests, merkle verification, and prize claims. Integrates Chainlink VRF v2.5 and Automation.

▶ security

The protocol uses several security measures:

Chainlink VRF v2.5 for tamper-proof randomness
Merkle proofs for gas-efficient holder verification
ReentrancyGuard on all external calls
24-hour claim window with automatic rollover
Owner-configurable parameters with safety bounds
No proxy pattern — immutable token contract

◊ faq

How do I become eligible?

Hold at least 1,000,000 LUCK tokens in your wallet. Your eligibility is checked automatically.

How often are draws?

Every 15 minutes. The countdown on the dashboard shows time until the next draw.

How is the winner selected?

Chainlink VRF generates a random number. This number maps to a ticket range based on holder entries (sqrt-weighted).

What happens if I don't claim?

Unclaimed prizes roll over to the next round after 24 hours.

Is there a burn mechanism?

No. 100% of swap tax goes to the prize pool. No burn, no treasury.

Can the owner rug?

The owner can adjust tax rate (max 10%) and draw interval (5min-24h). They cannot access the prize pool or mint tokens.