io.github.CloudCorpRecords/fairdraw

fairdraw

A raffle nobody has to take your word for. fairdraw picks winners from the public drand randomness beacon: the winning names are a pure function of a drand round's published randomness and the entrant list, so after a draw anyone can recompute the ranking by hand and check that the announced winners are the ones the beacon actually produced.

How a result is decided:

1. The entrant list is deduplicated and sorted.
2. Each entrant is scored with sha256(randomness + "|" + entrant) (hex digest).
3. Entrants are ranked by score, lowest first — the lowest scores win, in ranked order.

The three tools:

• pick_winner_now — draw immediately against the latest drand round and get the winner (or winners) right away, with the round number and the start of the randomness in the result so the draw can be rechecked.
• create_scheduled_draw — seal a draw to a future reveal. The drand round is committed the instant the draw is created, from the chain's timing: the first round whose randomness becomes available at or after now + delay_sec. The reply carries a draw id.
• verify_draw — look a scheduled draw up by id. While its round is still unpublished you get a pending note naming the committed round; once the round is out, you get the winners recomputed from that round's randomness, marked as verified.

Scheduled draws are kept in the server process's memory: they live as long as the process does, and a draw id is only meaningful to the process that created it.

CLI

Each tool is a subcommand taking one JSON argument string:

npx @reneturcios/fairdraw pick_winner_now '{"entrants":["alice","bob","carol"],"winners":2}'
npx @reneturcios/fairdraw create_scheduled_draw '{"title":"Spring raffle","entrants":["alice","bob"],"delay_sec":3600}'
npx @reneturcios/fairdraw verify_draw '{"id":"<draw id>"}'
npx @reneturcios/fairdraw --version

Output is the tool's result text. Exit codes: 0 on success, 1 on a runtime error (including a validation or drand failure), 2 on a usage error.

MCP server

npx -y @reneturcios/fairdraw mcp

MCP client config:

{
  "mcpServers": {
    "fairdraw": {
      "command": "npx",
      "args": ["-y", "@reneturcios/fairdraw", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/fairdraw
docker run --rm ghcr.io/cloudcorprecords/fairdraw pick_winner_now '{"entrants":["alice","bob"]}'

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch + fake clock, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios