add /v3/sortitions to openapi.yaml

Author: kantai

docs/rpc/api/core-node/get_sortitions.example.json

@@ -0,0 +1,15 @@
+[
+  {
+    "burn_block_hash": "0x046f54cd1924a5d80fc3b8186d0334b7521acae90f9e136e2bee680c720d0e83",
+    "burn_block_height": 231,
+    "burn_header_timestamp": 1726797570,
+    "sortition_id": "0x8a5116b7b4306dc4f6db290d1adfff9e1347f3e921bb793fc4c33e2ff05056e2",
+    "parent_sortition_id": "0xdaf479110cf859e58c56b6ae941f8a14e7c7992c57027183dfbda4a4b820897c",
+    "consensus_hash": "0x8d2c51db737597a93191f49bcdc9c7bb44b90892",
+    "was_sortition": true,
+    "miner_pk_hash160": "0x6bc51b33e9f3626944eb879147e18111581f8f9b",
+    "stacks_parent_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490",
+    "last_sortition_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490",
+    "committed_block_hash": "0xeea47d6d639c565027110e192e308fb11656183d5c077bcd718d830652800183"
+  }
+]

docs/rpc/api/core-node/get_sortitions_latest_and_prior.example.json

@@ -0,0 +1,28 @@
+[
+  {
+    "burn_block_hash": "0x046f54cd1924a5d80fc3b8186d0334b7521acae90f9e136e2bee680c720d0e83",
+    "burn_block_height": 231,
+    "burn_header_timestamp": 1726797570,
+    "sortition_id": "0x8a5116b7b4306dc4f6db290d1adfff9e1347f3e921bb793fc4c33e2ff05056e2",
+    "parent_sortition_id": "0xdaf479110cf859e58c56b6ae941f8a14e7c7992c57027183dfbda4a4b820897c",
+    "consensus_hash": "0x8d2c51db737597a93191f49bcdc9c7bb44b90892",
+    "was_sortition": true,
+    "miner_pk_hash160": "0x6bc51b33e9f3626944eb879147e18111581f8f9b",
+    "stacks_parent_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490",
+    "last_sortition_ch": "0x697357c72da55b759b1d6b721676c92c69f0b490",
+    "committed_block_hash": "0xeea47d6d639c565027110e192e308fb11656183d5c077bcd718d830652800183"
+  },
+  {
+    "burn_block_hash": "0x496ff02cb63a4850d0bdee5fab69284b6eb0392b4538e1c462f82362c5becfa4",
+    "burn_block_height": 230,
+    "burn_header_timestamp": 1726797570,
+    "sortition_id": "0xdaf479110cf859e58c56b6ae941f8a14e7c7992c57027183dfbda4a4b820897c",
+    "parent_sortition_id": "0xf9058692055cbd879d7f71e566e44b905a887b2b182407ed596b5d6499ceae2a",
+    "consensus_hash": "0x697357c72da55b759b1d6b721676c92c69f0b490",
+    "was_sortition": true,
+    "miner_pk_hash160": "0x6bc51b33e9f3626944eb879147e18111581f8f9b",
+    "stacks_parent_ch": "0xf7d1bd7d9d5c5a5c368402b6ef9510bd014d70f7",
+    "last_sortition_ch": "0xf7d1bd7d9d5c5a5c368402b6ef9510bd014d70f7",
+    "committed_block_hash": "0x36ee5f7f7271de1c1d4cd830e36320b51e01605547621267ae6e9b4e9b10f95e"
+  }
+]

docs/rpc/openapi.yaml

@@ -675,3 +675,43 @@ paths:
         schema:
           type: string
 
+  /v3/sortitions/{lookup_kind}/{lookup}:
+    get:
+      summary: Fetch information about evaluated burnchain blocks (i.e., sortitions).
+      tags:
+        - Blocks
+      operationId: get_sortitions
+      description:
+        Fetch sortition information about a burnchain block. If the `lookup_kind` and `lookup` parameters are empty, it will return information about the latest burn block.
+      responses:
+        "200":
+          description: Information for the given reward cycle
+          content:
+            application/json:
+              example:
+                $ref: ./api/core-node/get_sortitions.example.json
+        "200":
+          description: Sortition information about the latest burn block with a winning miner, and the previous such burn block.
+          content:
+            application/json:
+              example:
+                $ref: ./api/core-node/get_sortitions_latest_and_prior.example.json
+    parameters:
+      - name: lookup_kind
+        in: path
+        description: |-
+          The style of lookup that should be performed. If not given, the most recent burn block processed will be returned.
+          Otherwise, the `lookup_kind` should be one of the following strings:
+            * `consensus` - find the burn block using the consensus hash supplied in the `lookup` field.
+            * `burn_height` - find the burn block using the burn block height supplied in the `lookup` field.
+            * `burn` - find the burn block using the burn block hash supplied in the `lookup` field.
+            * `latest_and_last` - return information about the latest burn block with a winning miner *and* the previous such burn block
+        required: false
+        schema:
+          type: string
+      - name: lookup
+        in: path
+        description: The value to use for the lookup if `lookup_kind` is `consensus`, `burn_height`, or `burn`
+        required: false
+        schema:
+          type: string