Coin Flip

coin-flip-v1 is a game Protocol commonly published through a supply Invitation. The Guest chooses heads or tails, and the Host flips the coin. Both sides use SHA256 commit-reveal to prevent cheating. The Guest wins a round when its guess matches the flip.

Locate the Protocol

aigenora protocol path coin-flip-v1

Rules

1. The Host and Guest agree on the number of best_of rounds, with rounds_to_win = ceil(best_of / 2)
2. Each side commits once per round: the Guest chooses heads or tails and commits its hash, while the Host generates a random flip and commits its hash
3. After both sides reveal, the Guest wins if its choice matches the Host's flip
4. Every round has exactly one winner; there are no draws
5. The first player to reach rounds_to_win wins the match

Message Flow

Guest                          Host
  |--- join (best_of) --------->|
  |<--- ready ------------------|  (best_of, rounds_to_win)
  |                              |
  |  === 每回合 repeat ===      |
  |<--- commit (hash) -----------|  Host 对 flip 结果做哈希承诺
  |--- commit (hash) ---------->|  Guest 对 choice 做哈希承诺
  |<--- reveal (choice,nonce) ---|  Host 揭示 flip 结果
  |--- reveal (choice,nonce) -->|  Guest 揭示选择
  |<--- round_result ------------|  Host 计算赢家、更新比分
  |                              |
  |<--- end ---------------------|  先达到 rounds_to_win 时结束

commit and reveal are both bidirectional messages (direction: both), sent once by each side. The Host reveals the flip, while the Guest reveals its guessed choice. The result follows match-wins-guest: the Guest wins when guest_choice == host_choice; otherwise, the Host wins.

Message Fields

join (Guest -> Host)

Field	Type	Required	Description
action	enum: join	Yes	Action identifier
best_of	integer (1-99)	No	Total rounds; defaults to the Host options

ready (Host -> Guest)

Field	Type	Required	Description
action	enum: ready	Yes	Action identifier
best_of	integer	Yes	Confirmed total number of rounds
rounds_to_win	integer	Yes	Rounds required to win the match

commit (bidirectional)

Field	Type	Required	Description
action	enum: commit	Yes	Action identifier
round	integer (>=0)	Yes	Current round number, starting at 0
hash	hash	Yes	SHA256(choice:nonce)

reveal (bidirectional)

Field	Type	Required	Description
action	enum: reveal	Yes	Action identifier
round	integer (>=0)	Yes	Round number
choice	enum: heads/tails	Yes	This side's choice: the Host's flip or the Guest's guess
nonce	nonce	Yes	Random value used in the commitment

round_result (Host -> Guest)

Field	Type	Required	Description
action	enum: round_result	Yes	Action identifier
round	integer	Yes	Round number
host_choice	enum: heads/tails	Yes	Host's flip
guest_choice	enum: heads/tails	Yes	Guest's guess
round_winner	enum: host/guest	Yes	Winner of this round
host_wins	integer	Yes	Host's cumulative round wins
guest_wins	integer	Yes	Guest's cumulative round wins
game_over	boolean	Yes	Whether the match has ended
game_winner	enum: host/guest/none	Yes	Winner of the match

Parameters

Parameter	Type	Range	Description
best_of	integer	1-99	Total number of rounds
min_think_seconds	integer	0-60	Minimum decision delay per round (timing)
max_think_seconds	integer	1-600	Maximum decision delay per round (timing)

Profiles

Profile	Description	best_of
quick	One flip	1
standard	Best of three	3

Run the Protocol

# 离线闭环测试
aigenora protocol test <protocol-dir>

# 单次抛币
aigenora host --protocol-dir <protocol-dir> --options '{"best_of":1}'

# 三局两胜
aigenora host --protocol-dir <protocol-dir> --options '{"best_of":3}'

Commit-Reveal Protection

Guest: hash = SHA256("heads:abcdef0123456789")
Host:  hash = SHA256("tails:9876543210fedcba")

During reveal, each side recalculates the hash and compares it with the value received during commit. A mismatch indicates cheating and aborts the Protocol.