HomeCollectionRoadmapTokenomicsAboutCommunity
Join Community
Open Source Algorithm

Provably Fair Draw Algorithm

The exact code that selects lottery winners. Available in Python and JavaScript. Anyone can run it, verify it, and audit it.

How It Works

The Algorithm Explained

No math degree required. Here is exactly what happens, step by step, in plain language.

1. Entry Hashing

Every participant entry gets a unique SHA-256 fingerprint. This fingerprint is built from the entry ID, its weight, and the VRF seed. Even a tiny change in any of these values completely changes the hash, making tampering impossible.

SHA-256(entry_id + ':' + weight + ':' + seed)

2. VRF Seed Commitment

The randomness source is a publicly verifiable seed from Chainlink VRF. This seed is published on-chain before the draw, so everyone knows the randomness source in advance and nobody can manipulate it.

seed = on-chain VRF output (64-char hex)

3. Cumulative Weighting

All entry weights are capped at the maximum (e.g. 3.0×) and then stacked into a running total. Each entry 'owns' a slice of this total proportional to its weight. The bigger the weight, the bigger the slice.

cumulative[i] = sum(weights[0..i])

4. Deterministic Random Pick

A random number between 0 and the total weight is generated using the VRF seed. Because the PRNG is fully deterministic, anyone who knows the seed can reproduce the exact same random values.

pick = rng.random() * total_weight

5. Binary Search Selection

The random pick lands somewhere on the cumulative weight line. A fast binary search finds exactly which entry 'owns' that spot. This is efficient even with millions of entries (O(log n) per winner).

bisect_left(cumulative, pick) → winner_index

6. No-Replacement Draw

After a winner is picked, they are removed from the pool so they cannot win again. The remaining entries are re-cumulative-weighted and the process repeats for each prize rank (1st, 2nd, 3rd).

available.remove(winner) → redraw
Source Code

Implementation Code

The same algorithm running on our servers. Copy it, run it, verify it.

lottery_draw.py
python
1
def weighted_lottery_draw(entries, winner_count, vrf_seed_hex, max_weight_cap=3.0):
2
import hashlib, random
3
 
4
# 1. Cap all entry weights
5
capped = [(e["id"], min(e["weight"], max_weight_cap)) for e in entries]
6
 
7
# 2. SHA-256 hash each entry (id + weight + seed)
8
hashes = [
9
hashlib.sha256(f"{e[0]}:{e[1]}:{vrf_seed_hex}".encode()).hexdigest()
10
for e in capped
11
]
12
 
13
# 3. Build cumulative weight distribution
14
cumulative = []
15
running = 0.0
16
for _, w in capped:
17
running += w
18
cumulative.append(running)
19
total = running
20
 
21
# 4. Seed deterministic PRNG with VRF seed
22
rng = random.Random(int(vrf_seed_hex, 16))
23
 
24
# 5. Draw winners (no replacement)
25
winners = []
26
available = list(range(len(capped)))
27
for rank in range(1, winner_count + 1):
28
avail_cum = []
29
avail_run = 0.0
30
for idx in available:
31
avail_run += capped[idx][1]
32
avail_cum.append(avail_run)
33
 
34
pick = rng.random() * avail_run
35
 
36
# Binary search on cumulative array
37
lo, hi = 0, len(avail_cum)
38
while lo < hi:
39
mid = (lo + hi) // 2
40
if avail_cum[mid] < pick:
41
lo = mid + 1
42
else:
43
hi = mid
44
sel = available.pop(lo)
45
winners.append({"rank": rank, "id": capped[sel][0], "weight": capped[sel][1]})
46
 
47
return {"winners": winners, "seed": vrf_seed_hex, "total_weight": total}

Public API

Test the draw algorithm yourself using our public API. Send your own entries, get deterministic winners back, and verify everything independently.

EndpointPOST /api/v1/lottery/draw
AuthNone — fully public
Rate Limit100 req/minute
ReturnsWinners, seed, hashes, draw log
example.sh
javascript
1
curl -X POST https://api.winfinity.club/api/v1/lottery/draw \
2
-H "Content-Type: application/json" \
3
-d '{
4
"entries": [
5
{"id": "user1", "weight": 2.0},
6
{"id": "user2", "weight": 1.0}
7
],
8
"winner_count": 1,
9
"seed": "0xabc..."
10
}'
Trust But Verify

How to Verify a Draw

Four simple steps to independently confirm that any draw result is fair and unmanipulated.

1

Download the published entry list (IDs + weights) from the API

2

Note the VRF seed hex string published on-chain before the draw

3

Run the algorithm locally using the same seed, entries, and max_weight_cap

4

Compare your output winners, cumulative weights, and entry hashes — they must match exactly

Ready to Test the Algorithm?

Use the public API to run your own draws and verify the results.