games.atplay.calculation.drawPile Documentation (EN)

main object

Coordination state for a single hidden-pile operation (shuffle or reveal). The pile contents themselves live in _piles under shared or individual state; this calculation tracks the multi-player cryptographic protocol needed to transform them.

Properties

actions array of object Required

Work queue of required actions. When empty and any pending decryption has been applied, the calculation is deleted from transient.

minLength: 1 items

id string Required

A unique id for this operation, typically of the form '<pileId>:shuffle' or '<pileId>:reveal:<ciphertext>'. Sized to hold a pileId plus one Pohlig-Hellman ciphertext (~134 chars on a 768-bit prime) with headroom.

maxLength: 256 bytes

pile ref #pile Optional

The pile this calculation concerns. Absent if it concerns no pile.

revealTargets array of stringdid Optional

For reveal calcs: the list of players who should end up able to decrypt the reveal's ciphertext. Each listed player's secrets will hold a sufficient key set after the calc drains. When this list covers every player in state.individual, the protocol additionally replaces the ciphertext in the pile with its plaintext (public reveal). Absent or empty on shuffle calcs.

shared array of object Optional

Accumulated shared keys for reveal operations. Consumed when all required keys are present.

minLength: 1 items

View raw schema

{
  "type": "object",
  "required": [
    "id",
    "actions"
  ],
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 256,
      "description": "A unique id for this operation, typically of the form '<pileId>:shuffle' or '<pileId>:reveal:<ciphertext>'. Sized to hold a pileId plus one Pohlig-Hellman ciphertext (~134 chars on a 768-bit prime) with headroom."
    },
    "pile": {
      "ref": "#pile",
      "type": "ref",
      "description": "The pile this calculation concerns. Absent if it concerns no pile."
    },
    "shared": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "player",
          "target",
          "key"
        ],
        "properties": {
          "key": {
            "type": "string",
            "maxLength": 160,
            "description": "The multibase-encoded Pohlig-Hellman key (~134 chars on a 768-bit prime)"
          },
          "player": {
            "type": "string",
            "format": "did",
            "description": "The player who contributed this key"
          },
          "target": {
            "type": "string",
            "maxLength": 160,
            "description": "The ciphertext this key unlocks (multibase-encoded, ~134 chars on a 768-bit prime)"
          }
        },
        "description": "A key shared by one player, usable by the reveal target"
      },
      "minLength": 1,
      "description": "Accumulated shared keys for reveal operations. Consumed when all required keys are present."
    },
    "actions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "player",
          "operation"
        ],
        "properties": {
          "player": {
            "type": "string",
            "format": "did",
            "description": "The player who must perform this action"
          },
          "targets": {
            "type": "array",
            "items": {
              "type": "string",
              "maxLength": 160
            },
            "description": "For reveal: the specific ciphertexts to share keys for (each is a multibase-encoded Pohlig-Hellman value — ~134 chars on a 768-bit prime). For enc operations: absent or empty means 'all items in the pile'."
          },
          "operation": {
            "type": "string",
            "maxLength": 32,
            "minLength": 1,
            "description": "The action to perform: 'enc-shuf' = encrypt+shuffle (SRA stage 1), 'enc-final' = per-item re-encrypt stripping the stage-1 key (SRA stage 2), 'reveal' = share keys for specific ciphertexts",
            "knownValues": [
              "enc-shuf",
              "enc-final",
              "reveal"
            ]
          }
        },
        "description": "A pending action in the work queue. Removed once performed."
      },
      "minLength": 1,
      "description": "Work queue of required actions. When empty and any pending decryption has been applied, the calculation is deleted from transient."
    },
    "revealTargets": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "did"
      },
      "description": "For reveal calcs: the list of players who should end up able to decrypt the reveal's ciphertext. Each listed player's secrets will hold a sufficient key set after the calc drains. When this list covers every player in state.individual, the protocol additionally replaces the ciphertext in the pile with its plaintext (public reveal). Absent or empty on shuffle calcs."
    }
  },
  "description": "Coordination state for a single hidden-pile operation (shuffle or reveal). The pile contents themselves live in _piles under shared or individual state; this calculation tracks the multi-player cryptographic protocol needed to transform them."
}

pile object

A reference to a pile: whose it is, and which of theirs.

Properties

id string Required

The id of the pile, within its owner's namespace.

maxLength: 64 bytes

player string did RequiredNullable

The DID of the player who owns the pile. Null means it's a table pile.

View raw schema

{
  "type": "object",
  "nullable": [
    "player"
  ],
  "required": [
    "id",
    "player"
  ],
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 64,
      "description": "The id of the pile, within its owner's namespace."
    },
    "player": {
      "type": "string",
      "format": "did",
      "description": "The DID of the player who owns the pile. Null means it's a table pile."
    }
  },
  "description": "A reference to a pile: whose it is, and which of theirs."
}