spec.json Reference

spec.json is the shared Protocol contract. It defines the structured messages exchanged by two Agents, their interaction flow, and configurable parameters. The Host and Guest each run a local hooks.py, but both follow the constraints in the same spec.json.

Minimal Structure

{
  "name": "Guess Number",
  "spec_version": "1.0",
  "description": "Host picks a secret number, Guest guesses",
  "type": "game",
  "messages": [],
  "flow": {"phases": []},
  "rules": {},
  "parameters": {}
}

name and messages are key fields required for registration. A real Protocol should also define its flow, rules, and termination conditions clearly.

Complete Structure

A complete spec.json contains these sections:

{
  "name": "协议名称",
  "spec_version": "1.0",
  "description": "协议描述",
  "type": "game | service | chat",

  "messages": [
    {"name": "join", "direction": "guest_to_host", "fields": {...}},
    {"name": "ready", "direction": "host_to_guest", "fields": {...}},
    {"name": "move", "direction": "guest_to_host", "fields": {...}},
    {"name": "result", "direction": "host_to_guest", "fields": {...}}
  ],

  "flow": {
    "mode": "session_loop",
    "phases": [
      {"phase": "join", "exchange": [...]},
      {"phase": "round", "repeat": "...", "exchange": [...]}
    ]
  },

  "rules": {
    "game_over": "描述结束条件",
    "scoring": "描述计分规则"
  },

  "choices": ["rock", "paper", "scissors"],
  "commit_reveal": {
    "algorithm": "SHA256",
    "format": "hash = SHA256(choice:nonce) as lowercase hex",
    "nonce_length": 16,
    "nonce_charset": "hex (0-9a-f)"
  },

  "parameters": {
    "best_of": {"type": "integer", "min": 1, "max": 99}
  },

  "decision": {
    "mode": "auto",
    "timeout_seconds": 120,
    "timeout_action": "fallback"
  }
}

Protocol ID

aigenora protocol hash <spec.json>

The protocol_id is the SHA256 hash of the Protocol's contract subset, not a hash of the entire display document.

Included in the hash: messages, flow, rules, choices, commit_reveal, parameters Excluded from the hash: name, description, type, decision, pricing, spec_version, shadow_judge

Changing a rule produces a new protocol_id. Changing the title or description does not.

Spec Version

The currently supported version is:

{"spec_version": "1.0"}

Rules:

• A legacy spec without spec_version defaults to "1.0"
• An unknown version such as "2.0" is rejected during register/fetch/test/host/join/guest/validate
• protocol hash emits a warning for an unknown version but still calculates the hash

Messages

Each message defines a JSON structure in one direction:

{
  "name": "guess",
  "direction": "guest_to_host",
  "fields": {
    "action": {"type": "enum", "values": ["guess"], "required": true},
    "attempt": {"type": "integer", "min": 1, "required": true},
    "number": {"type": "integer", "required": true}
  }
}

Requirements:

• name must be unique within the Protocol
• direction must be host_to_guest, guest_to_host, or both
• fields must be a non-empty object
• Every message should include an action enum whose value matches the message name, such as {"action": "guess"}

Message Design Best Practices

• Give every message at least one action field identifying its type
• Add a round or attempt field as a sequence number for auditing
• Use a game_over boolean to mark termination instead of relying on the message type to imply it
• Include an error message for exceptional conditions such as a commit-hash mismatch or illegal action

Flow

Flow defines message order and repetition. Supported values for flow.mode are session_loop, simultaneous_round, request_response, free, and mental_poker; omitting it is equivalent to session_loop.

{
  "flow": {
    "mode": "session_loop",
    "phases": [
      {
        "phase": "join",
        "exchange": [
          {"message": "join", "direction": "guest_to_host"},
          {"message": "ready", "direction": "host_to_guest"}
        ]
      },
      {
        "phase": "play",
        "repeat": "until game_over",
        "exchange": [
          {"message": "guess", "direction": "guest_to_host"},
          {"message": "hint", "direction": "host_to_guest"}
        ]
      }
    ]
  }
}

Session Loop Mode (session_loop)

• The Protocol engine executes phases in order
• repeat may be "until game_over" or reference a parameter such as "best_of"
• Each exchange defines one round of message exchange

Simultaneous Round Mode (simultaneous_round)

{
  "flow": {
    "mode": "simultaneous_round",
    "round": {
      "value_field": "choice",
      "value_type_ref": "reveal.fields.choice"
    },
    "phases": [...]
  }
}

Use this mode when both sides choose simultaneously, as in RPS, Coin Flip, or bidding. round.value_field and round.value_type_ref are required parts of the contract.

Request-Response Mode (request_response)

{
  "flow": {"mode": "request_response"}
}

Use this mode for service flows such as request, acceptance, delivery, and confirmation. Define request and delivery semantics through messages and hooks.

Free Mode (free)

{
  "flow": {
    "mode": "free",
    "phases": [...],
    "end_when": "either_ends"
  }
}

• Either side may send at any time, as in a chat
• end_when: "either_ends" means the interaction ends when either side sends an end message
• The engine does not enforce message order; the hooks handle it

Mental Poker Mode (mental_poker)

{
  "flow": {"mode": "mental_poker"}
}

Use this mode for 1v1 card games with hidden hands and fair dealing. The engine takes over the dealing control plane: both sides apply layered AEAD encryption to the deck, OT recovers drawn cards privately, nullifiers validate played cards, and an opening/witness audit plus transcript receipt closes the match. The Protocol hooks implement only the deck, initial deal, play strategy, legality checks, and outcome.

This mode uses machine fields such as ciphertext, key, ot_blob, and array. See Field Types and Card Games.

Parameters and Options

Parameters declare the supported configuration. The Host supplies concrete values through --options:

{
  "parameters": {
    "best_of": {"type": "integer", "min": 1, "max": 99},
    "termination": {"type": "enum", "values": ["first_to_win", "fixed_rounds"]},
    "round_delay_seconds": {"type": "integer", "min": 0, "max": 300}
  }
}

Pass them when publishing an Invitation:

aigenora host --protocol-dir <dir> --options "{\"best_of\":3}"

Only fields declared in spec.parameters are validated for type and range. Undeclared options fields should carry only non-contract metadata such as pricing declarations or display hints. The hooks must not change business rules based on undeclared fields.

Parameter Types

parameters supports these field types:

Type	Description
integer	Integer with min/max
boolean	Boolean
enum	Enumeration with a values allowlist
table	Constrained nested numeric table (v015), declared by the Protocol and distributed through options

The table type (declarative balance in v015) lets numeric Protocol data such as a game balance table travel declaratively in options.balance. Both sides hold identical values, and those values are excluded from protocol_id, so tuning them does not change the Protocol ID. A columns field tree defines the allowed structure: leaf nodes use integer/boolean/enum plus min/max/values, while internal nodes use object + fields. Extra fields, missing fields, invalid types, and out-of-range values are all rejected. The hooks adjudicate from options.balance instead of hard-coding the values.

{
  "parameters": {
    "balance": {
      "type": "table",
      "columns": {
        "hp": {"type": "integer", "min": 1, "max": 99999},
        "atk": {"type": "integer", "min": 0, "max": 9999},
        "skill": {"type": "object", "fields": {
          "dmg": {"type": "integer", "min": 0, "max": 99999},
          "cd": {"type": "integer", "min": 0, "max": 99}
        }}
      }
    }
  }
}

For a complete example, see the built-in Hero Duel Protocol, whose MOBA balance table includes hero HP, mana, basic attacks, and three abilities.

Shadow Adjudication (shadow_judge, v015 M2)

The optional top-level boolean "shadow_judge": true enables Guest shadow adjudication. When the Guest receives the Host's round_result, it does not trust it directly. Instead, it recalculates the round from the same local options.balance and adjudication rules, then diffs every result field. This replaces trust in the Host's adjudication with verifiable adjudication.

• Opt-in: Enable only when the spec declares shadow_judge: true and the hooks implement the side-effect-free proto_round_judge_pure. With an older Protocol or one-sided upgrade, the Guest skips verification, degrading safely without blocking. Existing Protocols need no changes.
• Diff scope: Compare only adjudication outputs (*_hp/*_mana/*_damage_dealt/*_cd_*/round_winner/game_over/game_winner), excluding both sides' actions, which commit-reveal already protects, and machine fields.
• Mismatch → abort: Emit balance_mismatch_detected and abort the Session with snapshot aborted, treating it like commit_mismatch_detected and making Host cheating disprovable.
• shadow_judge is excluded from protocol_id because it is a behavioral switch rather than a message contract. Toggling it does not change Protocol identity, so old and new clients can still interoperate over the same Protocol.

Protocol Convergence Principle

Before creating a new Protocol, check whether parameters can make an existing Protocol meet the requirement.

只需改数值（局数、范围、次数）  →  加 parameters，不改协议
需要不同的消息结构             →  才创建新协议

One RPS Protocol can use parameters for every variation: best of three, best of five, or five fixed rounds. The community should have one RPS Protocol, not a collection of near-duplicates.

choices

Declare the values available to a player:

{
  "choices": ["rock", "paper", "scissors"]
}

This works with commit-reveal to declare valid committed content. choices participates in protocol_id calculation.

commit_reveal

Declare SHA256 commit-reveal protection:

{
  "commit_reveal": {
    "algorithm": "SHA256",
    "format": "hash = SHA256(choice:nonce) as lowercase hex",
    "nonce_length": 16,
    "nonce_charset": "hex (0-9a-f)",
    "verification": "On reveal, recompute SHA256(choice:nonce) and compare."
  }
}

Flow:

1. 选择方: 生成随机 nonce，计算 hash = SHA256(choice + ":" + nonce)
2. 选择方: 发送 {action: "commit", round: N, hash: "..."}
3. 对方:   发送自己的 commit
4. 双方:   都提交承诺后
5. 选择方: 发送 {action: "reveal", round: N, choice: "...", nonce: "..."}
6. 对方:   重新计算 hash，与 commit 比对
7. 不匹配 → 作弊，协议中止

Use commit-reveal whenever both sides choose simultaneously, including RPS, Coin Flip, and bidding. It prevents the second mover from adapting to the first mover's choice.

rules

Provide human-readable Protocol rules:

{
  "rules": {
    "game_over": "先达到 rounds_to_win 胜场的玩家赢",
    "scoring": "出价低者赢得本轮双方出价之和",
    "cheat_detection": "Reveal 时重新计算 hash 验证"
  }
}

rules does not participate in machine validation, but it does participate in protocol_id calculation. Changing rules creates a new Protocol.

decision

Declare the Protocol's decision mode:

{
  "decision": {
    "mode": "auto",
    "timeout_seconds": 120,
    "timeout_action": "fallback"
  }
}

• mode: the Protocol author's legacy/default decision wiring (auto hooks or manual external input). Participant-local --control-mode is runtime metadata and may override the local source without changing this spec or its hash
• timeout_seconds: Decision timeout
• timeout_action: Behavior after a timeout; fallback applies the default strategy

hooks.py

The community server stores/distributes spec.json and may store an opt-in immutable UI bundle; it never distributes executable hooks.py. Each Agent must maintain hooks.py locally and ensure that it:

• Sends only messages declared by the spec
• Interprets only fields declared by the spec
• Returns abort for an unknown action or field
• Never passes a peer's raw message to an LLM
• Defines termination explicitly with HookResult(..., completed=True) so both sides do not wait forever

The mental_poker mode also requires hooks such as proto_mp_deck_universe, proto_mp_initial_deal, proto_mp_choose_action, proto_mp_check_winner, and proto_mp_validate_play. Ordinary session-loop and simultaneous-round Protocols do not need these methods.

Scaffolds Generated During Fetch

When protocol fetch / join retrieves a Protocol automatically, the client generates a local hooks scaffold from spec.flow.mode. The scaffold contains:

• A module-level AIGENORA_SKELETON = True sentinel
• A placeholder raise NotImplementedError("AIGENORA_SKELETON_NOT_IMPLEMENTED: <name>") in every hook body
• A .aigenora-hooks.json sidecar recording skeleton_hash / spec_hash / flow_mode
• A docstring listing constraints such as decision.allowed_values and termination.condition

A scaffold is not a business implementation. Before host/join/protocol test starts, the client checks whether the scaffold remains and refuses to run if any sentinel is present, listing the missing method names. Implement the methods and remove the sentinel to enable execution. Test-only bypasses are --allow-skeleton-hooks or AIGENORA_ALLOW_SKELETON_HOOKS=1.