A single reference for the terms used across Checkmate-Escrow's contracts, services, and documentation. New contributors can start here, then follow the links into the deeper guides.
Terms are listed alphabetically. Where a term maps directly to something in the code, the relevant contract function, struct field, or error is named so you can find it quickly.
The privileged contract role set at deployment (emitted in the escrow / init event alongside the oracle address). The admin manages operational controls rather than match outcomes: pausing and unpausing the contract, rotating the oracle, transferring the admin role, configuring the match timeout, and managing the token allowlist via add_allowed_token. The admin cannot decide who wins a match — only the oracle can submit results. See runbook-rotation.md and runbook-pause.md.
The admin-managed set of tokens accepted for new matches. By default, before any token has been added, any Stellar token address is accepted. Once the admin adds at least one token with add_allowed_token, only allowlisted tokens may be used to create matches; attempting to use any other token fails with TokenNotAllowed. The allowlist is enforced in create_match.
A terminal match state. A match reaches Cancelled when either player calls cancel_match while it is still Pending, or when anyone calls expire_match after the timeout has elapsed. Any stake already deposited is refunded, and completed_ledger is recorded. See the match lifecycle.
A terminal match state reached when the oracle submits a result for an Active match via submit_result (or submit_result_with_oracle_record). The payout executes inline as part of the same transaction, escrow holds zero funds afterward, and completed_ledger is recorded.
A match state. A match becomes Active once both players have completed their deposits while it was Pending. The escrow now holds 2 × stake (the pot), the game is in progress, and only the oracle can advance the match to Completed.
The act of a player transferring their stake_amount into the escrow contract (deposit). A match starts Pending with no deposits; each player deposits once. When both deposits are present, the match transitions to Active. Deposits are refunded if the match is later Cancelled.
A match outcome (the Draw variant of the Winner enum) where neither player wins. Instead of paying the whole pot to one player, each player's stake is returned to them, and the match moves to Completed.
A general blockchain term for a defined period or checkpoint used to group activity or coordinate state changes. Stellar itself does not expose a Checkmate-specific "epoch"; the network measures the passage of time in ledgers, and Checkmate-Escrow's time-based rules (such as match expiry and storage TTL) are expressed in ledger sequence numbers rather than epochs.
The Soroban smart contract (and the funds it custodies) that holds both players' stakes from deposit until the match reaches a terminal state. The escrow enforces the rules for creating matches, depositing, cancelling, expiring, and paying out, so that no party can withhold or redirect funds. This is the core contract of the project (contracts/escrow).
A browser-extension wallet for Stellar. Users connect Freighter to the Checkmate-Escrow frontend to sign transactions such as creating a match or depositing a stake. See wallet-integration.md; the integration lives in frontend/src/wallets/freighter.
The identifier that links an on-chain match to a specific chess game on Lichess or Chess.com. It is supplied to create_match and must be non-empty and within the maximum allowed length (InvalidGameId otherwise) and must not already be registered for another match (DuplicateGameId). The oracle uses the game_id to fetch and verify the real-world result.
Stellar's unit of finalized state — a batch of transactions closed by the network, roughly every few seconds, identified by an increasing sequence number. Checkmate-Escrow records ledger sequence numbers to mark when matches are created, completed, or cancelled (completed_ledger), and to enforce time-based rules such as expiry and storage TTL (time-to-live, also measured in ledgers).
A single wagered chess game between two players, represented by the Match struct. It carries the participants, stake_amount, token address, game_id, lifecycle state, deposit flags, and outcome. Matches move through the lifecycle states below.
The states a match moves through, modeled by the MatchState enum: Pending → Active → Completed, with Cancelled as the alternative terminal state reached from Pending. Completed and Cancelled are terminal. The full state machine, including every guard and error path, is documented in match-lifecycle.md.
The authorized off-chain service together with its on-chain account that bridges external chess-platform data to the contract. The oracle reads the result of the game identified by game_id from Lichess/Chess.com and submits the verified outcome with submit_result. Only the oracle's authorization is accepted for result submission, which is what makes payouts automatic without a human middleman. The oracle address is set at initialization and can be rotated by the admin. Use get_oracle_address (view function) to query the currently configured oracle address from off-chain clients. See oracle.md and contracts/oracle.
The admin-controlled process of replacing the escrow contract's trusted oracle address with a new one. This operation is performed via the update_oracle function and is used when the oracle keypair is compromised, the oracle service is being migrated to a new instance, or as part of regular security best practices. Oracle rotation ensures continuity of operations while maintaining the integrity of the escrow contract. Once rotated, all result submissions must come from the new oracle address; the old oracle is immediately deactivated. See runbook-rotation.md for step-by-step procedures and oracle.md for technical details about oracle operation and integration.
The settlement transfer that happens when a match completes: the full pot (2 × stake) is sent to the winning player, or — in a draw — each player's stake is returned. Payout executes inline within the result-submission transaction, so settlement is immediate.
The initial match state after create_match, while the contract awaits deposits. Zero, one, or both deposits may be present; the match stays Pending until both arrive (then Active) or it is Cancelled via cancel_match or expire_match.
The total amount held in escrow for an Active match: 2 × stake, i.e. both players' stakes combined. On a decisive result the entire pot is paid to the winner; on a draw it is split back to each player as their original stake.
Stellar's smart contract platform. Contracts are written in Rust, compiled to WebAssembly (WASM), and deployed to the Stellar network. Checkmate-Escrow's escrow and oracle contracts are Soroban contracts (see contracts/).
The token amount each player commits to a match, recorded as stake_amount and required to be greater than zero (InvalidAmount otherwise). Both players stake the same amount; together they form the pot that is paid out on completion.
A label applied to GitHub issues that have been vetted and prepared for contribution under the project's Drips Wave program. Wave-ready issues carry a point value by complexity and can be claimed by commenting /wave claim. See the Drips Wave Contributor Guide.
The native asset of the Stellar network, also called the lumen. XLM pays Stellar transaction and Soroban resource fees. Match stakes are not restricted to XLM — any allowlisted Stellar token can be used (subject to the allowlist) — but XLM is always needed to cover network fees.
- Architecture Overview — components, public API, and data model
- Match Lifecycle — the complete state machine
- Oracle Design — how results are verified and submitted
- Drips Wave Contributor Guide — claiming wave-ready issues
- Error Codes Reference — every contract error and how to recover
- FAQ — common questions