Merge pull request #1092 from hirosystems/beta

Release v3.0.0 - merge beta into master

Author: rafaelcr

.env

@@ -118,3 +118,8 @@ MAINNET_SEND_MANY_CONTRACT_ID=SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.send-man
 # Specify max number of STX address to store in an in-memory LRU cache (CPU optimization).
 # Defaults to 50,000, which should result in around 25 megabytes of additional memory usage.
 # STACKS_ADDRESS_CACHE_SIZE=10000
+
+# Specify a URL to redirect from /doc. If this URL is not provided, server renders local documentation
+# of openapi.yaml for test / development NODE_ENV. 
+# For production, /doc is not served if this env var is not provided.
+# API_DOCS_URL="https://docs.hiro.so/api" 

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - master
       - develop
+      - beta
     tags-ignore:
       - '**'
     paths-ignore:

CHANGELOG.md

@@ -1,3 +1,43 @@
+# [3.0.0-beta.3](https://github.com/hirosystems/stacks-blockchain-api/compare/v3.0.0-beta.2...v3.0.0-beta.3) (2022-02-28)
+
+
+### Bug Fixes
+
+* remove unused indices, add others for re-org queries ([#1087](https://github.com/hirosystems/stacks-blockchain-api/issues/1087)) ([2a2fb8d](https://github.com/hirosystems/stacks-blockchain-api/commit/2a2fb8d415e1910cb4e7ae721c28c0f711a11601))
+
+# [3.0.0-beta.2](https://github.com/hirosystems/stacks-blockchain-api/compare/v3.0.0-beta.1...v3.0.0-beta.2) (2022-02-28)
+
+
+### Bug Fixes
+
+* deactivate indices before subdomain import ([#1086](https://github.com/hirosystems/stacks-blockchain-api/issues/1086)) ([d8d4d4c](https://github.com/hirosystems/stacks-blockchain-api/commit/d8d4d4c35e0fd197668b0b6c56700f437290c734))
+* index principal_stx_txs tx_id to speed up reorg updates ([#1080](https://github.com/hirosystems/stacks-blockchain-api/issues/1080)) ([f6d7d0c](https://github.com/hirosystems/stacks-blockchain-api/commit/f6d7d0cbf6b0bfd5a2cf0406570ed1c5d99e9220))
+
+# [3.0.0-beta.1](https://github.com/hirosystems/stacks-blockchain-api/compare/v2.1.1...v3.0.0-beta.1) (2022-02-25)
+
+
+### Bug Fixes
+
+* capture re-organized txs correctly in `/extended/v1/:address/transactions` ([#1074](https://github.com/hirosystems/stacks-blockchain-api/issues/1074)) ([81d039d](https://github.com/hirosystems/stacks-blockchain-api/commit/81d039d72219c51d517d27e69cedfc0cc8e10c7e))
+* principal_stx_txs sorting ([#1056](https://github.com/hirosystems/stacks-blockchain-api/issues/1056)) ([b0a0e94](https://github.com/hirosystems/stacks-blockchain-api/commit/b0a0e94ecd40bab5ea7d3c7705198ac9ea0ab399))
+* sort NFT events by event_index too ([#1063](https://github.com/hirosystems/stacks-blockchain-api/issues/1063)) ([77b2587](https://github.com/hirosystems/stacks-blockchain-api/commit/77b25878f652393a6066dad5c6b39569eb8a194a))
+
+
+* chore!: major version bump for breaking db schema changes ([296c619](https://github.com/hirosystems/stacks-blockchain-api/commit/296c619f81c480db9246ab8ea0b9fbf3c7b982b1))
+
+
+### Features
+
+* add `chain_tip` materialized view to track chain tip stats ([#1028](https://github.com/hirosystems/stacks-blockchain-api/issues/1028)) ([803ac18](https://github.com/hirosystems/stacks-blockchain-api/commit/803ac189c25b6a31ae94063a6f1a4ede1f0dba98))
+* add chain tip info to `/extended/v1/status` ([#1070](https://github.com/hirosystems/stacks-blockchain-api/issues/1070)) ([fb573b1](https://github.com/hirosystems/stacks-blockchain-api/commit/fb573b11e4b8768d87e6b9c557fec92945fadd9a))
+* added feature for rendering docs ([#991](https://github.com/hirosystems/stacks-blockchain-api/issues/991)) ([a521a39](https://github.com/hirosystems/stacks-blockchain-api/commit/a521a390b2d973851f94a8962ec2b70a5937c6a7))
+* change string and hex column indices to Hash method ([#1042](https://github.com/hirosystems/stacks-blockchain-api/issues/1042)) ([aae6cc0](https://github.com/hirosystems/stacks-blockchain-api/commit/aae6cc0c643a5c6056e596768080119e2c84bb21))
+
+
+### BREAKING CHANGES
+
+* use event-replay to upgrade, this version includes breaking changes to the db sql schema
+
 ## [2.1.1](https://github.com/hirosystems/stacks-blockchain-api/compare/v2.1.0...v2.1.1) (2022-02-09)
 
 

Dockerfile

@@ -5,7 +5,7 @@ COPY . .
 
 RUN apk add --no-cache --virtual .build-deps alpine-sdk python3 git openjdk8-jre cmake
 RUN echo "GIT_TAG=$(git tag --points-at HEAD)" >> .env
-RUN npm config set unsafe-perm true && npm install && npm run build && npm prune --production
+RUN npm config set unsafe-perm true && npm install && npm run build && npm run build:docs && npm prune --production
 RUN apk del .build-deps
 
 CMD ["node", "./lib/index.js"]

docs/api/info/get-status.example.json

@@ -1,4 +1,11 @@
 {
-  "server_version": "stacks-blockchain-api v0.64.1 (master:439d4f46)",
-  "status": "ready"
+  "server_version": "stacks-blockchain-api v1.0.7 (master:77b25878)",
+  "status": "ready",
+  "chain_tip": {
+    "block_height": 48902,
+    "block_hash": "0xa5a2923c405f8356925213bb8c479beb06d3b68ca66dd2b7397b54f8c08c5eac",
+    "index_block_hash": "0xf46401bf3cb6a6b6181536b7de414a1fd9e004a6ece99a05de72a781b17f9819",
+    "microblock_hash": "0xec89a572d3583b959e490bc45e0f521b775ed51d7ed13087b6df8eb82cbe75d3",
+    "microblock_sequence": 0
+  }
 }

docs/api/info/get-status.schema.json

@@ -15,6 +15,9 @@
     "status": {
       "type": "string",
       "description": "the current server status"
+    },
+    "chain_tip": {
+      "$ref": "../../entities/info/chain-tip.schema.json"
     }
   }
 }

docs/entities/info/chain-tip.example.json

@@ -0,0 +1,7 @@
+{
+  "block_height": 48902,
+  "block_hash": "0xa5a2923c405f8356925213bb8c479beb06d3b68ca66dd2b7397b54f8c08c5eac",
+  "index_block_hash": "0xf46401bf3cb6a6b6181536b7de414a1fd9e004a6ece99a05de72a781b17f9819",
+  "microblock_hash": "0xec89a572d3583b959e490bc45e0f521b775ed51d7ed13087b6df8eb82cbe75d3",
+  "microblock_sequence": 0
+}

docs/entities/info/chain-tip.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ChainTip",
+  "description": "Current chain tip information",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "block_height",
+    "block_hash",
+    "index_block_hash"
+  ],
+  "properties": {
+    "block_height": {
+      "type": "integer",
+      "description": "the current block height"
+    },
+    "block_hash": {
+      "type": "string",
+      "description": "the current block hash"
+    },
+    "index_block_hash": {
+      "type": "string",
+      "description": "the current index block hash"
+    },
+    "microblock_hash": {
+      "type": "string",
+      "description": "the current microblock hash"
+    },
+    "microblock_sequence": {
+      "type": "integer",
+      "description": "the current microblock sequence number"
+    }
+  }
+}

docs/generated.d.ts

@@ -151,6 +151,7 @@ export type SchemaMergeRootStub =
   | {
       target_block_time: number;
     }
+  | ChainTip
   | AbstractMempoolTransaction
   | MempoolTokenTransferTransaction
   | MempoolSmartContractTransaction
@@ -1707,6 +1708,32 @@ export interface ServerStatusResponse {
    * the current server status
    */
   status: string;
+  chain_tip?: ChainTip;
+}
+/**
+ * Current chain tip information
+ */
+export interface ChainTip {
+  /**
+   * the current block height
+   */
+  block_height: number;
+  /**
+   * the current block hash
+   */
+  block_hash: string;
+  /**
+   * the current index block hash
+   */
+  index_block_hash: string;
+  /**
+   * the current microblock hash
+   */
+  microblock_hash?: string;
+  /**
+   * the current microblock sequence number
+   */
+  microblock_sequence?: number;
 }
 /**
  * GET request that returns network target block times

docs/openapi.yaml

@@ -12,7 +12,7 @@ info:
   description: |
     Welcome to the API reference overview for the <a href="https://docs.hiro.so/get-started/stacks-blockchain-api">Stacks Blockchain API</a>.
 
-    <a href="/collection.json" download="stacks-api-collection.json">Download Postman collection</a>
+    <a href="https://hirosystems.github.io/stacks-blockchain-api/collection.json" download="stacks-api-collection.json">Download Postman collection</a>
 tags:
   - name: Accounts
     description: Read-only endpoints to obtain Stacks account details
@@ -234,7 +234,10 @@ paths:
       tags:
         - Transactions
       operationId: get_mempool_transaction_list
-      description: Retrieves all transactions that have been recently broadcast to the mempool. These are pending transactions awaiting confirmation.
+      description: |
+          Retrieves all transactions that have been recently broadcast to the mempool. These are pending transactions awaiting confirmation.
+
+          If you need to monitor new transactions, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.
       parameters:
         - name: sender_address
           in: query
@@ -487,7 +490,10 @@ paths:
       tags:
         - Microblocks
       operationId: get_microblock_list
-      description: Retrieves a list of microblocks.
+      description: |
+          Retrieves a list of microblocks.
+
+          If you need to actively monitor new microblocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.
       parameters:
         - name: limit
           in: query
@@ -557,7 +563,10 @@ paths:
   /extended/v1/block:
     get:
       summary: Get recent blocks
-      description: Retrieves a list of recently mined blocks
+      description: |
+          Retrieves a list of recently mined blocks
+
+          If you need to actively monitor new blocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.
       tags:
         - Blocks
       operationId: get_block_list
@@ -1247,7 +1256,10 @@ paths:
   /extended/v1/address/{principal}/transactions:
     get:
       summary: Get account transactions
-      description: Retrieves a list of all Transactions for a given Address or Contract Identifier. More information on Transaction types can be found [here](https://docs.stacks.co/understand-stacks/transactions#types).
+      description: |
+          Retrieves a list of all Transactions for a given Address or Contract Identifier. More information on Transaction types can be found [here](https://docs.stacks.co/understand-stacks/transactions#types).
+
+          If you need to actively monitor new transactions for an address or contract id, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.
       tags:
         - Accounts
       operationId: get_account_transactions
@@ -1658,10 +1670,11 @@ paths:
                 $ref: ./api/core-node/get-info.schema.json
               example:
                 $ref: ./api/core-node/get-info.example.json
+
   /extended/v1/status:
     get:
-      summary: Get Blockchain API status
-      description: Retrieves the current status of the blockchain API, including the server version
+      summary: API status
+      description: Retrieves the running status of the Stacks Blockchain API, including the server version and current chain tip information.
       tags:
         - Info
       operationId: get_status
@@ -2649,71 +2662,71 @@ paths:
               example:
                 $ref: ./api/bns/errors/bns-unsupported-blockchain.example.json
 
-  /v1/subdomains:
-    get:
-      summary: Get All Subdomains
-      description: Retrieves a list of all subdomains known to the node.
-      tags:
-        - Names
-      operationId: get_all_subdomains
-      parameters:
-        - name: page
-          in: query
-          description: names are returned in pages of size 100, so specify the page number.
-          required: true
-          example: 3
-          schema:
-            type: integer
-      responses:
-        200:
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.schema.json
-              example:
-                $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.example.json
-        400:
-          description: Error
-          content:
-            application/json:
-              schema:
-                $ref: ./api/bns/errors/bns-error.schema.json
-              example:
-                $ref: ./api/bns/errors/bns-invalid-page.example.json
-
-  /v1/subdomains/{txid}:
-    get:
-      summary: Get Subdomain at Transaction
-      description: Retrieves the list of subdomain operations processed by a given transaction. The returned array includes subdomain operations that have not yet been accepted as part of any subdomain’s history (checkable via the accepted field). If the given transaction ID does not correspond to a Stacks transaction that introduced new subdomain operations, and empty array will be returned.
-      tags:
-        - Names
-      operationId: get_subdomain_at_transaction
-      parameters:
-        - name: txid
-          in: path
-          description: transaction id
-          required: true
-          example: d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe
-          schema:
-            type: string
-      responses:
-        200:
-          description: Success
-          content:
-            application/json:
-              schema:
-                $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.schema.json
-              example:
-                $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.example.json
-        400:
-          description: Error
-          content:
-            application/json:
-              schema:
-                $ref: ./api/bns/errors/bns-error.schema.json
-              example:
-                $ref: ./api/bns/errors/bns-invalid-tx-id.example.json
+#  /v1/subdomains:
+#    get:
+#      summary: Get All Subdomains
+#      description: Retrieves a list of all subdomains known to the node.
+#      tags:
+#        - Names
+#      operationId: get_all_subdomains
+#      parameters:
+#        - name: page
+#          in: query
+#          description: names are returned in pages of size 100, so specify the page number.
+#          required: true
+#          example: 3
+#          schema:
+#            type: integer
+#      responses:
+#        200:
+#          description: Success
+#          content:
+#            application/json:
+#              schema:
+#                $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.schema.json
+#              example:
+#                $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.example.json
+#        400:
+#          description: Error
+#          content:
+#            application/json:
+#              schema:
+#                $ref: ./api/bns/errors/bns-error.schema.json
+#              example:
+#                $ref: ./api/bns/errors/bns-invalid-page.example.json
+#
+#  /v1/subdomains/{txid}:
+#    get:
+#      summary: Get Subdomain at Transaction
+#      description: Retrieves the list of subdomain operations processed by a given transaction. The returned array includes subdomain operations that have not yet been accepted as part of any subdomain’s history (checkable via the accepted field). If the given transaction ID does not correspond to a Stacks transaction that introduced new subdomain operations, and empty array will be returned.
+#      tags:
+#        - Names
+#      operationId: get_subdomain_at_transaction
+#      parameters:
+#        - name: txid
+#          in: path
+#          description: transaction id
+#          required: true
+#          example: d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe
+#          schema:
+#            type: string
+#      responses:
+#        200:
+#          description: Success
+#          content:
+#            application/json:
+#              schema:
+#                $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.schema.json
+#              example:
+#                $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.example.json
+#        400:
+#          description: Error
+#          content:
+#            application/json:
+#              schema:
+#                $ref: ./api/bns/errors/bns-error.schema.json
+#              example:
+#                $ref: ./api/bns/errors/bns-invalid-tx-id.example.json
 
   /extended/v1/tx/block/{block_hash}:
     get: