docs: add documentation for /v2/headers and /v2/data_var

docs/rpc-endpoints.md

@@ -77,6 +77,96 @@ Reason types without additional information will not have a
 
 Get current PoX-relevant information. See OpenAPI [spec](./rpc/openapi.yaml) for details.
 
+### GET /v2/headers/[Count]
+
+Get a given number of ancestral Stacks block headers, in order from newest to
+oldest.  If the `?tip=` query parameter is given, the headers will be loaded
+from the block identified by the tip.  If no `?tip=` query parameter is given,
+then the canonical Stacks chain tip will be used.  The first header in the list
+is the header of the `?tip=` query parameter (or the canonical tip of the blockchain);
+the second header is the parent block's header; the third header is the
+grandparent block's header, and so on. [Count] determines how many headers, including this first header, to return.
+
+Up to 2100 headers (one PoX reward cycle) may be returned by this endpoint.
+Callers who wish to download more headers will need to issue this query
+multiple times, with a `?tip=` query parameter set to the index block hash of
+the earliest header received.
+
+Returns a
+[SIP-003](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md)-encoded
+vector with length up to [Count] that contains a list of the following SIP-003-encoded
+structures:
+
+```
+struct ExtendedStacksHeader {
+    consensus_hash: ConsensusHash,
+    header: StacksBlockHeader,
+    parent_block_id: StacksBlockId,
+}
+```
+
+Where `ConsensusHash` is a 20-byte byte buffer.
+
+Where `StacksBlockId` is a 32-byte byte buffer.
+
+Where `StacksBlockHeader` is the following SIP-003-encoded structure:
+
+```
+struct StacksBlockHeader {
+    version: u8,
+    total_work: StacksWorkScore,
+    proof: VRFProof,
+    parent_block: BlockHeaderHash,
+    parent_microblock: BlockHeaderHash,
+    parent_microblock_sequence: u16,
+    tx_merkle_root: Sha512Trunc256Sum,
+    state_index_root: TrieHash,
+    microblock_pubkey_hash: Hash160,
+}
+```
+
+Where `BlockHeaderHash`, `Sha512Trunc256Sum`, and `TrieHash` are 32-byte byte
+buffers.
+
+Where `Hash160` is a 20-byte byte buffer.
+
+Where `StacksWorkScore` and `VRFProof` are the following SIP-003-encoded structures:
+
+```
+struct StacksWorkScore {
+    burn: u64,
+    work: u64,
+}
+```
+
+```
+struct VRFProof {
+    Gamma: [u8; 32]
+    c: [u8; 16]
+    s: [u8; 32]
+}
+```
+
+The interpretation of most these fields is beyond the scope of this document (please
+see
+[SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md)
+for details).  However, it is worth pointing out that `parent_block_id` is a
+valid argument to the `?tip=` query parameter.  If the caller of this API
+endpoint wants to receive more than 2100 contiguous headers, it would use the
+oldest header's `parent_block_id` field from the previous call as the `?tip=`
+argument to the next call in order to fetch the next batch of ancestor headers.
+
+This API endpoint may return a list of zero headers if `?tip=` refers to the
+hash of the Stacks genesis block.
+
+This API endpoint will return HTTP 404 if the `?tip=` argument is given but
+refers to a nonexistent Stacks block, or a Stacks block that has not yet been
+processed by the node.
+
+The `?tip=` argument may refer to a Stacks block that is not on the canonical
+fork.  In this case, this endpoint behaves as described above, except that
+non-canonical headers will be returned instead.
+
 ### GET /v2/accounts/[Principal]
 
 Get the account data for the provided principal.
@@ -104,6 +194,25 @@ object with balance and nonce of 0.
 This endpoint also accepts a querystring parameter `?proof=` which when supplied `0`, will return the
 JSON object _without_ the `balance_proof` or `nonce_proof` fields.
 
+### GET /v2/data_var/[Stacks Address]/[Contract Name]/[Var Name]
+
+Attempt to vetch a data var from a contract. The contract is identified with [Stacks Address] and
+ [Contract Name] in the URL path. The variable is identified with [Var Name].
+ 
+Returns JSON data in the form:
+
+```
+{
+ "data": "0x01ce...",
+ "proof": "0x01ab...",
+}
+```
+
+Where data is the hex serialization of the variable value.
+
+This endpoint also accepts a querystring parameter `?proof=` which when supplied `0`, will return the
+JSON object _without_ the `proof` field.
+
 ### POST /v2/map_entry/[Stacks Address]/[Contract Name]/[Map Name]
 
 Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and
@@ -343,4 +452,4 @@ object of the following form:
 
 Determine whether a given trait is implemented within the specified contract (either explicitly or implicitly).
 
-See OpenAPI [spec](./rpc/openapi.yaml) for details.
+See OpenAPI [spec](./rpc/openapi.yaml) for details.