Architectural Workflow for Joining and Initializing Play as White in Reversteem

puncakbukit (79)in Steem Dev • 4 days ago

5% of the rewards of this post are for @steem.amal

Implementing a decentralized, serverless turn-based board game on the Steem blockchain requires a strict protocol for state derivation and message validation. In Reversteem, a game lifecycle begins with a root post created by the Black player (type: "game_start"). To transition a game from an open state to active play, a secondary participant must register as the White player via an on-chain Join Comment.

This technical overview details the protocol mechanics, payload schemas, and validation rules governing how a client discovers, signs, and processes a join operation as the White player.

1. On-Chain Game State Model & Root Discovery

Reversteem maps every match to a single Steem post thread, where the root post defines the foundational parameters of the board session.

Root Post (Black): The creator of the post acts as the Black player and initializes the match metadata, including the per-minute time limit (timeoutMinutes), optional invite arrays, and discovery tags.
White Player State: At creation, the white field in the root post metadata is explicitly set to null. The participant who occupies this role is determined entirely by the first valid Join Comment posted as a direct reply to the root post.

2. Join Comment Payload Schema

To register as White, the client constructs a JSON metadata payload with the protocol identifier (reversteem/0.1) and dispatches a reply directly to the root post using Steem Keychain.

{
  "app": "reversteem/0.1",
  "action": "join"
}

Validation Rules During Deterministic Replay

Because game state is never stored in a centralized database, every client independently replays chronological event logs to derive the active player set. During chronological sorting and evaluation, a Join Comment is accepted only if it satisfies all of the following criteria:

Single Registration: No White player has already been successfully registered in the event stream (whitePlayer === null).
Distinct Identity: The comment author must not match the Black player (author !== blackPlayer).
Invite List Enforcement: If an invites array is defined in the root post metadata, author.toLowerCase() must explicitly appear within that array. (Note: Replay logic re-reads invite parameters directly from the root post to prevent cache-poisoning vulnerabilities).

3. Clock Initialization and Turn Sequencing

The exact moment an accepted Join Comment is recorded on-chain triggers the official start of the match clock:

$$\text{gameStartTime} = \text{lastMoveTime} = \text{reply.created}$$

Clock Activation: The time control timer does not begin ticking at root post creation; it activates exclusively when White successfully joins. This ensures the Black player cannot trigger an unfair timeout before an opponent is present.
Turn Order: Black always moves first. Once White joins and the initial standard Reversi pieces are established on the board (board[27] = white, board[28] = black, board[35] = black, board[36] = white), the turn pointer is set to "black".
White's First Action: The client interface filters incoming move commands so that White can only broadcast a valid move payload (action: "move", matching index $0-63$) when currentPlayer === "white" and appliedMoves matches the sequence counter.

Repository: https://github.com/puncakbukit/reversteem

Assisted by https://Gemini.google.com/