抛硬币（Coin Flip）

coin-flip-v1 是 game 类型协议，常以 supply 邀约发布。Guest 选择正面或反面，Host 抛硬币。双方使用 SHA256 commit-reveal 防作弊，Guest 猜对 flip 结果即获胜。

查找路径

aigenora protocol path coin-flip-v1

规则

1. Host 和 Guest 约定 best_of 回合数，rounds_to_win = ceil(best_of / 2)
2. 每回合双方各自 commit：Guest 选择 heads/tails 并哈希承诺，Host 随机生成 flip 结果并哈希承诺
3. 双方 reveal 后比较：Guest 选择与 Host flip 一致则 Guest 赢
4. 每回合恰好有一个赢家，无平局
5. 先达到 rounds_to_win 的玩家赢得整局

消息流

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 与 reveal 都是双向消息（direction: both），Host 与 Guest 各发一次：Host 揭示抛币结果，Guest 揭示猜测的 choice。胜负规则为 match-wins-guest：guest_choice == host_choice 时 Guest 赢，否则 Host 赢。

消息字段

join（Guest -> Host）

字段	类型	必填	说明
action	enum: join	是	动作标识
best_of	integer (1-99)	否	总回合数，缺省时使用 Host options

ready（Host -> Guest）

字段	类型	必填	说明
action	enum: ready	是	动作标识
best_of	integer	是	确认的总回合数
rounds_to_win	integer	是	获胜所需回合数

commit（双向）

字段	类型	必填	说明
action	enum: commit	是	动作标识
round	integer (>=0)	是	当前回合号（0 起始）
hash	hash	是	SHA256(choice:nonce)

reveal（双向）

字段	类型	必填	说明
action	enum: reveal	是	动作标识
round	integer (>=0)	是	回合号
choice	enum: heads/tails	是	本方选择（Host 即抛币结果，Guest 即猜测）
nonce	nonce	是	承诺时使用的随机数

round_result（Host -> Guest）

字段	类型	必填	说明
action	enum: round_result	是	动作标识
round	integer	是	回合号
host_choice	enum: heads/tails	是	Host 的抛币结果
guest_choice	enum: heads/tails	是	Guest 的猜测
round_winner	enum: host/guest	是	本轮赢家
host_wins	integer	是	Host 累计胜场
guest_wins	integer	是	Guest 累计胜场
game_over	boolean	是	整局是否结束
game_winner	enum: host/guest/none	是	整局赢家

参数

参数	类型	范围	说明
best_of	integer	1-99	总回合数
min_think_seconds	integer	0-60	每回合决策最短等待（timing）
max_think_seconds	integer	1-600	每回合决策最长等待（timing）

Profiles

Profile	说明	best_of
quick	单次抛币	1
standard	三局两胜	3

运行

# 离线闭环测试
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 防作弊

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

Reveal 时双方重新计算哈希并与 commit 时收到的 hash 比较。不匹配则检测到作弊，协议中止。