# com.imlunahey.leaderboard.score

> Published by [imlunahey.com](https://lexicon.garden/identity/did:plc:k6acu4chiwkixvdedcmdgmal)

✓ This is the authoritative definition for this NSID.

## Description

A signed leaderboard score. Users play locally, call /api/sign-score on the site which validates the run and returns a server HMAC, then createRecord on their own PDS. Records without a valid server signature are ignored when rendering the leaderboard.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:k6acu4chiwkixvdedcmdgmal/com.imlunahey.leaderboard.score)
- [Documentation](https://lexicon.garden/lexicon/did:plc:k6acu4chiwkixvdedcmdgmal/com.imlunahey.leaderboard.score/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:k6acu4chiwkixvdedcmdgmal/com.imlunahey.leaderboard.score/examples)

## Definitions

### `com.imlunahey.leaderboard.score`

**Type**: `record`

**Key**: `tid`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `did` | `string` (did) | Yes | The author's DID, copied into the record so the server HMAC binds the score to the player. Must match the record repo's DID when displayed. |
| `sig` | `string` | Yes | Base64url-encoded HMAC-SHA256 of the canonical {game, score, did, achievedAt} payload, signed with a server secret. The leaderboard renderer verifies this and drops records that don't match. |
| `game` | `string` | Yes | The game identifier. Includes the variant for games with multiple boards (e.g. typing-30). |
| `score` | `integer` | Yes | The numeric score. Meaning depends on the game — for snake, food eaten; for typing, wpm; for wordle, guesses used (lower is better). |
| `replay` | `string` | No | Optional compact replay data (input log, guess sequence, typed text hash). Not required; when present, the signing server may use it for additional validation before signing. |
| `subject` | `string` (at-uri) | Yes | AT-URI of the leaderboard marker record this score is claiming against. |
| `achievedAt` | `string` (datetime) | Yes | Timestamp assigned by the signing server, part of the HMAC payload. |

## Raw Schema

```json
{
  "id": "com.imlunahey.leaderboard.score",
  "defs": {
    "main": {
      "key": "tid",
      "type": "record",
      "record": {
        "type": "object",
        "required": [
          "game",
          "score",
          "subject",
          "did",
          "achievedAt",
          "sig"
        ],
        "properties": {
          "did": {
            "type": "string",
            "format": "did",
            "description": "The author's DID, copied into the record so the server HMAC binds the score to the player. Must match the record repo's DID when displayed."
          },
          "sig": {
            "type": "string",
            "maxLength": 128,
            "description": "Base64url-encoded HMAC-SHA256 of the canonical {game, score, did, achievedAt} payload, signed with a server secret. The leaderboard renderer verifies this and drops records that don't match."
          },
          "game": {
            "type": "string",
            "maxLength": 64,
            "description": "The game identifier. Includes the variant for games with multiple boards (e.g. typing-30).",
            "knownValues": [
              "snake",
              "wordle",
              "typing-15",
              "typing-30",
              "typing-60"
            ]
          },
          "score": {
            "type": "integer",
            "minimum": 0,
            "description": "The numeric score. Meaning depends on the game — for snake, food eaten; for typing, wpm; for wordle, guesses used (lower is better)."
          },
          "replay": {
            "type": "string",
            "maxLength": 4000,
            "description": "Optional compact replay data (input log, guess sequence, typed text hash). Not required; when present, the signing server may use it for additional validation before signing."
          },
          "subject": {
            "type": "string",
            "format": "at-uri",
            "description": "AT-URI of the leaderboard marker record this score is claiming against."
          },
          "achievedAt": {
            "type": "string",
            "format": "datetime",
            "description": "Timestamp assigned by the signing server, part of the HMAC payload."
          }
        }
      }
    }
  },
  "$type": "com.atproto.lexicon.schema",
  "lexicon": 1,
  "description": "A signed leaderboard score. Users play locally, call /api/sign-score on the site which validates the run and returns a server HMAC, then createRecord on their own PDS. Records without a valid server signature are ignored when rendering the leaderboard."
}
```