From d356a59296f1950bb96c3cc1ab1129298fca26e0 Mon Sep 17 00:00:00 2001
From: Jude Nelson <judecn@gmail.com>
Date: Wed, 20 Mar 2024 15:14:37 -0400
Subject: [PATCH] chore: update the openapi.yaml file with the new API calls

---
 docs/rpc/api/core-node/get_tenure_info.json |  9 +++
 docs/rpc/openapi.yaml                       | 70 ++++++++++++++++++++-
 2 files changed, 76 insertions(+), 3 deletions(-)
 create mode 100644 docs/rpc/api/core-node/get_tenure_info.json

diff --git a/docs/rpc/api/core-node/get_tenure_info.json b/docs/rpc/api/core-node/get_tenure_info.json
new file mode 100644
index 0000000000..052f5bc614
--- /dev/null
+++ b/docs/rpc/api/core-node/get_tenure_info.json
@@ -0,0 +1,9 @@
+{
+  "consensus_hash": "4c5a49be0e34dc603b66f090fd07d28a2f76a2ad",
+  "parent_consensus_hash": "fa8a04af41957499afdd4082b9b702ffca9a4370",
+  "parent_tenure_start_block_id": "0cfec8433849d353ad6b2fe1173da143e3d4a3ab452588a14eb074d0181ac202",
+  "reward_cycle": 8,
+  "tenure_start_block_id": "0425099d51547c714df6a7864c040c1a605b198ff07f71d19a823139c88a35f8",
+  "tip_block_id": "52d64f5e47abc7666c4fed3fe850f381f93f2d588ee2a92a4e07b44f14588d5e",
+  "tip_height": 416
+}
diff --git a/docs/rpc/openapi.yaml b/docs/rpc/openapi.yaml
index ceaf0e4a9d..2463666b2b 100644
--- a/docs/rpc/openapi.yaml
+++ b/docs/rpc/openapi.yaml
@@ -3,7 +3,7 @@ servers:
   - url: http://localhost:20443/
     description: Local
 info:
-  title: Stacks 2.0 RPC API
+  title: Stacks 2.0+ RPC API
   version: '1.0.0'
   description: |
     This is the documentation for the `stacks-node` RPC interface.
@@ -560,8 +560,8 @@ paths:
       operationId: post_block_proposal
       description: |
         Used by stackers to validate a proposed Stacks block from a miner.
-        
-        **This endpoint will only accept requests over the local loopback network interface.**
+
+        **This API endpoint requires a basic Authorization header.**
       responses:
         202:
           description: Block proposal has been accepted for processing. The result will be returned via the event observer.
@@ -607,3 +607,67 @@ paths:
             application/json:
               example:
                 $ref: ./api/core-node/get_stacker_set.400.example.json
+
+  /v3/blocks/{block_id}:
+    get:
+      summary: Fetch a Nakamoto block 
+      tags:
+        - Blocks
+      operationId: get_block_v3
+      description:
+        Fetch a Nakamoto block by its index block hash.
+      responses:
+        200:
+          description: The raw SIP-003-encoded block will be returned.
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        404:
+          description: The block could not be found
+          content:
+            application/text-plain: {}
+
+  /v3/tenures/info:
+    get:
+      summary: Fetch metadata about the ongoing Nakamoto tenure
+      tags:
+        - Blocks
+      operationId: get_tenure_info
+      description:
+        Fetch metadata about the ongoing Nakamoto tenure. This information is sufficient to obtain and authenticate the highest complete tenure, as well as obtain new tenure blocks.
+      responses:
+        200:
+          description: Metadata about the ongoing tenure
+          content:
+            application/json:
+              example:
+                *ref: ./api/core-node/get_tenure_info.json
+  
+  /v3/tenures/{block_id}:
+    get:
+      summary: Fetch a sequence of Nakamoto blocks in a tenure
+      tags:
+        - Blocks
+      operationId: get_tenures
+      description:
+        Fetch a sequence of Nakamoto blocks in a tenure.  The blocks will be served in order from highest to lowest.  The blocks will be encoded in their SIP-003 wire format, and concatenated together.
+      responses:
+        200:
+          description: SIP-003-encoded Nakamoto blocks, concatenated together
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+    parameters:
+      name: stop
+      in: query
+      description:
+          The block ID hash of the highest block in this tenure that is already known to the caller.  Neither the corresponding block nor any of its ancestors will be served.  This is used to fetch tenure blocks that the caller does not have.
+      required: false
+      schema:
+        type: string
+        format: 64-character hex string
+