docs: add get_clarity_mark_value and get_clarity_metadata documentation

Author: hugoclrd

docs/rpc-endpoints.md

@@ -172,6 +172,35 @@ 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.
 
+### GET /v2/clarity_marf_value/[Clarity MARF Key]
+Attempt to fetch the value of a MARF key. The key is identified with [Clarity MARF Key].
+
+Returns JSON data in the form:
+
+```json
+{
+  "data": "0x01ce...",
+  "proof": "0x01ab...",
+}
+```
+
+Where data is the hex serialization of the value.
+
+### GET /v2/clarity_metadata/[Stacks Address]/[Contract Name]/[Clarity Metadata Key]
+Attempt to fetch the metadata of a contract.
+ The contract is identified with [Stacks Address] and [Contract Name] in the URL path.
+ The metadata key is identified with [Clarity Metadata Key].
+
+Returns JSON data in the form:
+
+```json
+{
+  "data": "'{\"contract_identifier\":{...}'",
+}
+```
+
+Where data is the metadata formatted as a JSON string.
+
 ### GET /v2/constant_val/[Stacks Address]/[Contract Name]/[Constant Name]
 Attempt to fetch a constant from a contract. The contract is identified with [Stacks Address] and 
  [Contract Name] in the URL path. The constant is identified with [Constant Name].

docs/rpc/api/core-node/get-clarity-marf-value.example.json

@@ -0,0 +1,4 @@
+{
+  "data": "0x0a0c000000010a6d6f6e737465722d69640100000000000000000000000000000001",
+  "proof": "0x123..."
+}

docs/rpc/api/core-node/get-clarity-marf-value.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Response of get Clarity MARF value request",
+  "title": "ClarityMARFValueResponse",
+  "type": "object",
+  "required": ["data"],
+  "properties": {
+    "data": {
+      "type": "string",
+      "description": "Hex-encoded string"
+    },
+    "proof": {
+      "type": "string",
+      "description": "Hex-encoded string of the MARF proof for the data"
+    }
+  }
+}

docs/rpc/api/core-node/get-clarity-metadata.example.json

@@ -0,0 +1,3 @@
+{
+  "data": "'{\"contract_identifier\":{...}, \"private_function_types\":{...}'"
+}

docs/rpc/api/core-node/get-clarity-metadata.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "description": "Response of get clarity metadata request",
+  "title": "ClarityMetadataResponse",
+  "type": "object",
+  "required": ["data"],
+  "properties": {
+    "data": {
+      "type": "string",
+      "description": "Metadata value formatted as a JSON string"
+    }
+  }
+}

docs/rpc/openapi.yaml

@@ -519,7 +519,94 @@ paths:
         description: |
           The Stacks chain tip to query from.
           If tip == "latest", the query will be run from the latest known tip (includes unconfirmed state).
-          If the tip is left unspecified, the stacks chain tip will be selected (only includes confirmed state). 
+          If the tip is left unspecified, the stacks chain tip will be selected (only includes confirmed state).
+
+  /v2/clarity_marf_value/{clarity_marf_key}:
+    post:
+      summary: Get the MARF value for a given key
+      tags:
+        - Smart Contracts
+      operationId: get_clarity_marf_value
+      description: |
+        Attempt to fetch the value of a MARF key. The key is identified with [Clarity MARF Key].
+
+        In the response, `data` is the hex serialization of the value.
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: ./api/core-node/get-clarity-marf-value.schema.json
+              example:
+                $ref: ./api/core-node/get-clarity-marf-value.example.json
+        400:
+          description: Failed to retrieve MARF key
+      parameters:
+        - name: clarity_marf_key
+          in: path
+          required: true
+          description: MARF key
+          schema:
+            type: string
+        - name: proof
+          in: query
+          description: Returns object without the proof field when set to 0
+          schema:
+            type: integer
+        - name: tip
+          in: query
+          schema:
+            type: string
+          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
+            known tip (includes unconfirmed state).
+
+  /v2/clarity_metadata/{contract_address}/{contract_name}/{clarity_metadata_key}:
+    post:
+      summary: Get the contract metadata for the metadata key
+      tags:
+        - Smart Contracts
+      operationId: get_clarity_metadata_key
+      description: |
+        Attempt to fetch the metadata of a contract. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The metadata key is identified with [Clarity Metadata Key].
+
+        In the response, `data` is formatted as JSON.
+      responses:
+        200:
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: ./api/core-node/get-clarity-metadata.schema.json
+              example:
+                $ref: ./api/core-node/get-clarity-metadata.example.json
+        400:
+          description: Failed to retrieve constant value from contract
+      parameters:
+        - name: contract_address
+          in: path
+          required: true
+          description: Stacks address
+          schema:
+            type: string
+        - name: contract_name
+          in: path
+          required: true
+          description: Contract name
+          schema:
+            type: string
+        - name: clarity_metadata_key
+          in: path
+          required: true
+          description: Metadata key
+          schema:
+            type: string
+        - name: tip
+          in: query
+          schema:
+            type: string
+          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
+            known tip (includes unconfirmed state).
 
   /v2/constant_val/{contract_address}/{contract_name}/{constant_name}:
     post:
@@ -633,7 +720,7 @@ paths:
 
   /v3/blocks/{block_id}:
     get:
-      summary: Fetch a Nakamoto block 
+      summary: Fetch a Nakamoto block
       tags:
         - Blocks
       operationId: get_block_v3
@@ -674,7 +761,7 @@ paths:
             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