docs: added examples for Rosetta API's - AccountIdentifier, Hash and Construction (#1288)

* Added examples for construction, account and hash API's

* docs: cleaned up OpenAPI.yaml for consistency with all the examples (#1282)

* Added examples for missing API's

* fix the hash example for v1/block/{hash}

* Fixed examples for string types

* Updated examples to follow yaml syntax

* Examples for Rosetta and Smart contracts

* Reframed a sentence

Author: LakshmiLavanyaKasturi

docs/api/rosetta/rosetta-account-identifier-request-body.example.json renamed to docs/api/rosetta/rosetta-account-identifier-publickey-request-body.example.json

@@ -4,7 +4,7 @@
     "network": "mainnet"
   },
   "public_key": {
-    "hex_bytes": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662",
+    "hex_bytes": "025c13b2fc2261956d8a4ad07d481b1a3b2cbf93a24f992249a61c3a1c4de79c51",
     "curve_type": "secp256k1"
   },
   "metadata": {}

docs/api/rosetta/rosetta-construction-metadata-request-schema-body.example.json

@@ -0,0 +1,34 @@
+{
+  "network_identifier": {
+    "blockchain": "stacks",
+    "network": "mainnet"
+  },
+  "options": {
+    "sender_address": "SP3Y0BBCCCBFAMYCYN3F35CX9MH1J2GATP53JX3FA",
+    "type": "stack_stx",
+    "status": "success",
+    "token_transfer_recipient_address": "string",
+    "amount": "500000",
+    "symbol": "STX",
+    "decimals": 6,
+    "gas_limit": 0,
+    "gas_price": 0,
+    "suggested_fee_multiplier": 0,
+    "max_fee": "12380898",
+    "fee": "fee",
+    "size": 260,
+    "memo": "test.memo",
+    "number_of_cycles": 0,
+    "contract_address": "SP112T7BYCNEDCZ9TCYXCXFNJG9WXX5Q5SG6DSBAM",
+    "contract_name": "STX transfer",
+    "burn_block_height": 0,
+    "delegate_to": "cb3df38053d132895220b9ce471f6b676db5b9bf0b4adefb55f2118ece2478df01.STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6",
+    "pox_addr": "1Xik14zRm29UsyS6DjhYg4iZeZqsDa8D3"
+  },
+  "public_keys": [
+    {
+      "hex_bytes": "publicKey",
+      "curve_type": "secp256k1"
+    }
+  ]
+}

docs/api/rosetta/rosetta-hash-signed-transaction-request-schema-body.example.json

@@ -0,0 +1,7 @@
+{
+  "network_identifier": {
+    "blockchain": "stacks",
+    "network": "mainnet"
+  },
+  "signed_transaction": "0x80800000000400539886f96611ba3ba6cef9618f8c78118b37c5be000000000000000000000000000000b400017a33a91515ef48608a99c6adecd2eb258e11534a1acf66348f5678c8e2c8f83d243555ed67a0019d3500df98563ca31321c1a675b43ef79f146e322fe08df75103020000000000051a1ae3f911d8f1d46d7416bfbe4b593fd41eac19cb000000000007a12000000000000000000000000000000000000000000000000000000000000000000000"
+}

docs/api/rosetta/rosetta-network-transaction-from-signarures-request.example.json

@@ -0,0 +1,26 @@
+{
+  "network_identifier": {
+    "blockchain": "stacks",
+    "network": "mainnet"
+  },
+  "unsigned_transaction": "00000000010400539886f96611ba3ba6cef9618f8c78118b37c5be0000000000000000000000000000006400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003020000000000051ab71a091b4b8b7661a661c620966ab6573bc2dcd3000000000007a12074657374207472616e73616374696f6e000000000000000000000000000000000000",
+  "signatures": [
+    {
+      "signing_payload": {
+        "address": "string",
+        "account_identifier": {
+          "address": "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6",
+          "metadata": {}
+        },
+        "hex_bytes": "string",
+        "signature_type": "ecdsa"
+      },
+      "public_key": {
+        "hex_bytes": "025c13b2fc2261956d8a4ad07d481b1a3b2cbf93a24f992249a61c3a1c4de79c51",
+        "curve_type": "secp256k1"
+      },
+      "signature_type": "ecdsa",
+      "hex_bytes": "string"
+    }
+  ]
+}

docs/api/rosetta/rosetta-submit-signed-transaction-request.example.json

@@ -0,0 +1,7 @@
+{
+  "network_identifier": {
+    "blockchain": "stacks",
+    "network": "mainnet"
+  },
+  "signed_transaction": "0x80800000000400539886f96611ba3ba6cef9618f8c78118b37c5be000000000000000000000000000000b400017a33a91515ef48608a99c6adecd2eb258e11534a1acf66348f5678c8e2c8f83d243555ed67a0019d3500df98563ca31321c1a675b43ef79f146e322fe08df75103020000000000051a1ae3f911d8f1d46d7416bfbe4b593fd41eac19cb000000000007a12000000000000000000000000000000000000000000000000000000000000000000000"
+}

docs/api/rosetta/rosetta-submit-unsigned-transaction-unsigned-payloads-request.example.json

@@ -0,0 +1,27 @@
+{
+  "network_identifier": {
+    "blockchain": "stacks",
+    "network": "mainnet"
+  },
+  "operations": [
+    {
+      "operation_identifier": {
+        "index": 0,
+        "network_index": 0
+      },
+      "related_operations": [
+        {
+          "index": 0,
+          "network_index": 0
+        }
+      ],
+      "type": "stack_stx",
+      "status": "success",
+      "account": {
+        "address": "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6",
+        "metadata": {}
+      }
+      
+    }
+  ]
+}

docs/entities/contracts/get-specific-data-map-inside-contract.example.json

@@ -0,0 +1 @@
+"0x0100000000000000000000000000000095"

docs/entities/contracts/read-only-function-args-request-body.example.json

@@ -0,0 +1,6 @@
+{
+  "sender": "STM9EQRAB3QAKF8NKTP15WJT7VHH4EWG3DJB4W29",
+  "arguments": [
+    "0x0100000000000000000000000000000095"
+  ]
+}

docs/openapi.yaml

@@ -601,9 +601,9 @@ paths:
           in: query
           description: index of first block to fetch
           required: false
-          example: 42000
           schema:
             type: integer
+            example: 42000
       responses:
         200:
           description: List of blocks
@@ -1085,20 +1085,21 @@ paths:
           description: Stacks address
           schema:
             type: string
-            example: "SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C"
+            example: "SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11"
         - name: contract_name
           in: path
           required: true
           description: Contract name
           schema:
             type: string
-            example: satoshibles
+            example: newyorkcitycoin-core-v2
         - name: map_name
           in: path
           required: true
           description: Map name
           schema:
             type: string
+            example: approved-contracts
         - name: proof
           in: query
           description: Returns object without the proof field when set to 0
@@ -1117,6 +1118,8 @@ paths:
           application/json:
             schema:
               type: string
+            example: 
+              $ref: ./entities/contracts/get-specific-data-map-inside-contract.example.json
 
   /v2/contracts/source/{contract_address}/{contract_name}:
     get:
@@ -1192,20 +1195,21 @@ paths:
           description: Stacks address
           schema:
             type: string
-            example: "SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C"
+            example: "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7"
         - name: contract_name
           in: path
           required: true
           description: Contract name
           schema:
             type: string
-            example: satoshibles
+            example: imaginary-friends-zebras
         - name: function_name
           in: path
           required: true
           description: Function name
           schema:
             type: string
+            example: get-token-uri
         - name: tip
           in: query
           schema:
@@ -1219,11 +1223,8 @@ paths:
           application/json:
             schema:
               $ref: './entities/contracts/read-only-function-args.schema.json'
-              example:
-                sender: 'SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info'
-                arguments:
-                  - '0x0011...'
-                  - '0x00231...'
+            example:
+              $ref: './entities/contracts/read-only-function-args-request-body.example.json'
 
   /extended/v1/address/{principal}/balances:
     get:
@@ -2205,6 +2206,8 @@ paths:
           application/json:
             schema:
               $ref: ./api/rosetta/rosetta-construction-derive-request.schema.json
+            example: 
+              $ref: ./api/rosetta/rosetta-account-identifier-publickey-request-body.example.json
 
   /rosetta/v1/construction/hash:
     post:
@@ -2232,6 +2235,8 @@ paths:
           application/json:
             schema:
               $ref: ./api/rosetta/rosetta-construction-hash-request.schema.json
+            example:
+              $ref: ./api/rosetta/rosetta-hash-signed-transaction-request-schema-body.example.json
 
   /rosetta/v1/construction/metadata:
     post:
@@ -2259,6 +2264,8 @@ paths:
           application/json:
             schema:
               $ref: ./api/rosetta/rosetta-construction-metadata-request.schema.json
+            example:
+              $ref: ./api/rosetta/rosetta-construction-metadata-request-schema-body.example.json
 
   /rosetta/v1/construction/parse:
     post:
@@ -2321,7 +2328,7 @@ paths:
         - Rosetta
       summary: Submit a Signed Transaction
       operationId: rosetta_construction_submit
-      description: Submit a pre-signed transaction to the node.
+      description: Submit a pre-signed transaction to the node. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.
       responses:
         200:
           description: Success
@@ -2341,14 +2348,16 @@ paths:
           application/json:
             schema:
               $ref: ./api/rosetta/rosetta-construction-submit-request.schema.json
+            example:
+              $ref: ./api/rosetta/rosetta-submit-signed-transaction-request.example.json
 
   /rosetta/v1/construction/payloads:
     post:
       tags:
         - Rosetta
       summary: Generate an Unsigned Transaction and Signing Payloads
       operationId: rosetta_construction_payloads
-      description: Generate and unsigned transaction from operations and metadata
+      description: Generate an unsigned transaction from operations and metadata. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.
       responses:
         200:
           description: Success
@@ -2368,14 +2377,16 @@ paths:
           application/json:
             schema:
               $ref: ./api/rosetta/rosetta-construction-payloads-request.schema.json
+            example:
+              $ref: ./api/rosetta/rosetta-submit-unsigned-transaction-unsigned-payloads-request.example.json
 
   /rosetta/v1/construction/combine:
     post:
       tags:
         - Rosetta
       summary: Create Network Transaction from Signatures
       operationId: rosetta_construction_combine
-      description: Take unsigned transaction and signature, combine both and return signed transaction
+      description: Take unsigned transaction and signature, combine both and return signed transaction. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.
       responses:
         200:
           description: Success
@@ -2395,6 +2406,8 @@ paths:
           application/json:
             schema:
               $ref: ./api/rosetta/rosetta-construction-combine-request.schema.json
+            example:
+              $ref: ./api/rosetta/rosetta-network-transaction-from-signarures-request.example.json
 
   /v2/prices/namespaces/{tld}:
     get:
@@ -3210,6 +3223,7 @@ paths:
     get:
       operationId: get_contract_nft_metadata
       summary: Non fungible tokens metadata for contract ID
+      deprecated: true
       description: Retrieves metadata for non fungible tokens for a given contract id. More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts).
       tags:
         - Non-Fungible Tokens