fairdice

README

fairdice

Commit-reveal dice (and fair randomness) between untrusting peers — no trusted server, no dealer. Useful for peer-to-peer games where either side could otherwise cheat the roll.

A roll is a three-message exchange:

1. The roller generates random bytes and broadcasts a commitment SHA-256(deterministic-CBOR(reveal)).
2. The opponent broadcasts its own random contribution.
3. The roller reveals; everyone (spectators too) checks the reveal against the commitment and derives the dice from the combined randomness.

The roller can't pick the outcome (it's bound before seeing the opponent's contribution) and the opponent can't either (any contribution yields uniform dice against the unknown-but-fixed commitment). A reveal that doesn't match its commitment is caught by every participant.

reveal, commit, _ := fairdice.NewRoll()      // roller: broadcast commit
rb, _ := fairdice.NewResponse()              // opponent: broadcast rb
// roller broadcasts reveal; everyone verifies + derives:
if fairdice.Verify(commit, reveal) {
    d1, d2 := fairdice.Dice(reveal, rb)      // uniform 1..6 each, deterministic
}

Opening derives an unequal opening pair (the backgammon convention). Dice are uniform via rejection sampling over an expandable hash stream.

Install

go get github.com/richardwooding/fairdice

Extracted from kibitz, where it drives provably-fair backgammon dice.

License

MIT

Documentation

Overview

Package fairdice implements commit-reveal dice between untrusting peers.

Neither player can be trusted to roll alone (there's no server — the relay is blind), so a roll is a three-message exchange:

1. The roller generates random bytes RA and a salt, and broadcasts Commit = SHA-256(deterministic-CBOR(Reveal{RA, Salt})).
2. The opponent broadcasts its own random RB (no commitment needed — it moves second and the roller is already bound).
3. The roller broadcasts Reveal{RA, Salt}; everyone (spectators too) checks it against the commit and derives Dice(RA, RB).

The roller can't pick dice (bound before seeing RB); the opponent can't either (RA is fixed but unknown when choosing RB, so any RB yields uniformly distributed dice). A roller whose reveal doesn't match its commit is caught by every participant.

Extracted from https://github.com/richardwooding/kibitz

Index

• func Dice(r Reveal, rb Response) (d1, d2 int)
• func NewRoll() (Reveal, Commit, error)
• func Opening(r Reveal, rb Response) (rollerDie, responderDie int)
• func Verify(c Commit, r Reveal) bool
• type Commit
• type Response
  • func NewResponse() (Response, error)
• type Reveal
  • func (r Reveal) Commitment() (Commit, error)

Functions

func Dice

func Dice(r Reveal, rb Response) (d1, d2 int)

Dice derives two dice from the combined randomness, uniformly via rejection sampling. Deterministic: every participant derives the same pair from the same (reveal, response).

func NewRoll

func NewRoll() (Reveal, Commit, error)

NewRoll starts a roll: fresh randomness plus its commitment.

func Opening

func Opening(r Reveal, rb Response) (rollerDie, responderDie int)

Opening derives the backgammon opening roll: one die for the roller, one for the responder, guaranteed unequal (equal pairs are skipped, mirroring the tabletop re-roll rule). The higher die's owner moves first, playing both dice.

func Verify

func Verify(c Commit, r Reveal) bool

Verify reports whether a reveal matches its earlier commitment. False means the roller cheated (or the messages were corrupted — either way, the roll is void).

Types

type Commit

type Commit [32]byte

Commit is the roller's binding hash.

type Response

type Response [32]byte

Response is the opponent's contribution.

func NewResponse

func NewResponse() (Response, error)

NewResponse is the opponent's random contribution.

type Reveal

type Reveal struct {
	RA   [32]byte `cbor:"1,keyasint"`
	Salt [16]byte `cbor:"2,keyasint"`
}

Reveal is what the roller discloses after the opponent responds. It is CBOR-encoded (deterministic mode, integer keys) before hashing, so the commitment preimage is unambiguous.

func (Reveal) Commitment

func (r Reveal) Commitment() (Commit, error)

Commitment computes the binding hash of a Reveal.