org.lichess.puzzle.defs

Documentation

puzzleView object

The shared representation of a chess puzzle returned by the puzzle queries.

Properties

fen string Required

the FEN string of the position before the opponent makes their move.

gameId string Optional

the unique identifier of the specific game and move the puzzle was extracted from. The game would be accessible at https://lichess.org/{GameId}

id string Required

the id of the puzzle.

moves string Required

the solution to the puzzle. All player moves of the solution are "only moves", i.e. playing any other move would considerably worsen the player position. An exception is made for mates in one: there can be several. Any move that checkmates should win the puzzle.

nbPlays integer Optional

the number of times a puzzle was played.

openingTags array of string Optional

a list of openings. This is only set for puzzles starting before move 20.

popularity integer Optional

a number between 100 (best) and -100 (worst), calculated as 100 * (upvotes - downvotes)/(upvotes + downvotes). Votes are weighted by various factors such as whether the puzzle was solved successfully or the solver's puzzle rating in comparison to the puzzle's.

minimum: -100maximum: 100

rating integer Required

the Glicko-2 rating of the puzzle.

ratingDeviation integer Required

the Glicko-2 rating deviation of the puzzle.

themes array of string Optional

a list of puzzle themes.

View raw schema

{
  "type": "object",
  "required": [
    "id",
    "fen",
    "moves",
    "rating",
    "ratingDeviation"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "the id of the puzzle."
    },
    "fen": {
      "type": "string",
      "description": "the FEN string of the position before the opponent makes their move."
    },
    "moves": {
      "type": "string",
      "description": "the solution to the puzzle. All player moves of the solution are \"only moves\", i.e. playing any other move would considerably worsen the player position. An exception is made for mates in one: there can be several. Any move that checkmates should win the puzzle."
    },
    "gameId": {
      "type": "string",
      "description": "the unique identifier of the specific game and move the puzzle was extracted from. The game would be accessible at https://lichess.org/{GameId}"
    },
    "rating": {
      "type": "integer",
      "description": "the Glicko-2 rating of the puzzle."
    },
    "themes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "a list of puzzle themes."
    },
    "nbPlays": {
      "type": "integer",
      "description": "the number of times a puzzle was played."
    },
    "popularity": {
      "type": "integer",
      "maximum": 100,
      "minimum": -100,
      "description": "a number between 100 (best) and -100 (worst), calculated as 100 * (upvotes - downvotes)/(upvotes + downvotes). Votes are weighted by various factors such as whether the puzzle was solved successfully or the solver's puzzle rating in comparison to the puzzle's."
    },
    "openingTags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "a list of openings. This is only set for puzzles starting before move 20."
    },
    "ratingDeviation": {
      "type": "integer",
      "description": "the Glicko-2 rating deviation of the puzzle."
    }
  },
  "description": "The shared representation of a chess puzzle returned by the puzzle queries."
}

resultAttestation object

The payload a puzzle service signs when it judges a ranked attempt: proof that the service verified playerMoves against the puzzle's solution with the given solved result. The signature over it is stored in the org.lichess.puzzle.attempt record's sig field; this object itself is never stored, since every field is recoverable from the attempt record and the repo it lives in. To verify: rebuild this object from the record (kind is the constant below; player is the DID of the repo the record lives in), encode it as canonical DAG-CBOR (sorted map keys), and check the record's sig — an unpadded base64url low-S ECDSA signature over the sha256 of those bytes — against the service DID's published atproto verification key.

Properties

kind string Required

always "org.lichess.puzzle.defs#resultAttestation"; domain-separates these signatures from anything else the service key signs.

nonce string Required

nonce of the challenge this result resolves (the attempt record's nonce field).

player string did Required

DID of the player the result belongs to — the repo the attempt record lives in. Binds the signature to its owner so it cannot be replayed into another player's repo.

playerMoves string Required

the solution line the player submitted, exactly as judged (the attempt record's playerMoves field).

puzzle string Required

Lichess puzzle ID (the attempt record's puzzleId field).

service string did Required

DID of the service that judged the attempt (the attempt record's service field).

solved boolean Required

the server-judged result (the attempt record's solved field).

View raw schema

{
  "type": "object",
  "required": [
    "kind",
    "service",
    "player",
    "puzzle",
    "nonce",
    "solved",
    "playerMoves"
  ],
  "properties": {
    "kind": {
      "type": "string",
      "const": "org.lichess.puzzle.defs#resultAttestation",
      "description": "always \"org.lichess.puzzle.defs#resultAttestation\"; domain-separates these signatures from anything else the service key signs."
    },
    "nonce": {
      "type": "string",
      "description": "nonce of the challenge this result resolves (the attempt record's nonce field)."
    },
    "player": {
      "type": "string",
      "format": "did",
      "description": "DID of the player the result belongs to — the repo the attempt record lives in. Binds the signature to its owner so it cannot be replayed into another player's repo."
    },
    "puzzle": {
      "type": "string",
      "description": "Lichess puzzle ID (the attempt record's puzzleId field)."
    },
    "solved": {
      "type": "boolean",
      "description": "the server-judged result (the attempt record's solved field)."
    },
    "service": {
      "type": "string",
      "format": "did",
      "description": "DID of the service that judged the attempt (the attempt record's service field)."
    },
    "playerMoves": {
      "type": "string",
      "description": "the solution line the player submitted, exactly as judged (the attempt record's playerMoves field)."
    }
  },
  "description": "The payload a puzzle service signs when it judges a ranked attempt: proof that the service verified playerMoves against the puzzle's solution with the given solved result. The signature over it is stored in the org.lichess.puzzle.attempt record's sig field; this object itself is never stored, since every field is recoverable from the attempt record and the repo it lives in. To verify: rebuild this object from the record (kind is the constant below; player is the DID of the repo the record lives in), encode it as canonical DAG-CBOR (sorted map keys), and check the record's sig — an unpadded base64url low-S ECDSA signature over the sha256 of those bytes — against the service DID's published atproto verification key."
}

themeView object

A puzzle theme with its display name and description.

Properties

description string Required

a sentence describing the theme.

key string Required

the theme identifier used in puzzle themes and the getRandom themes filter (e.g. "fork").

name string Required

the human-readable display name of the theme (e.g. "Fork").

View raw schema

{
  "type": "object",
  "required": [
    "key",
    "name",
    "description"
  ],
  "properties": {
    "key": {
      "type": "string",
      "description": "the theme identifier used in puzzle themes and the getRandom themes filter (e.g. \"fork\")."
    },
    "name": {
      "type": "string",
      "description": "the human-readable display name of the theme (e.g. \"Fork\")."
    },
    "description": {
      "type": "string",
      "description": "a sentence describing the theme."
    }
  },
  "description": "A puzzle theme with its display name and description."
}