kylefang/stacks-blockchain-api
1
0
Fork 0
mirror of https://github.com/alexgo-io/stacks-blockchain-api.git synced 2026-04-30 22:02:35 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: add initial overview.md

Browse Source
This commit is contained in:
Matthew Little
2021-05-18 15:41:50 +02:00
committed by Diwaker Gupta
parent 0565d4f7f3
commit 1573ced4cd
1 changed files with 65 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
overview.md Normal file
View File

@@ -0,0 +1,65 @@
```
┌──────────────────┐ ┌─────────────────┐ ┌────────────┐
│ ├─────event-observer────► │ stacks │ │ │
│ stacks node │ │ blockchain api ├───────────► │ postgres │
│ (event-emitter) │ ◄─────rpc-api────────────┤ │ │ │
│ │ └──┬──────────────┘ └────────────┘
└──────────────────┘ │ ▲
│ │
│ │
┌──────────────────┐ │ │
│ stacks node pool │ │ │
│ (load balanced) │ │ ┌──┴─────────────────────────────┐
│ ┌─┐ ┌─┐ ┌─┐ ┌──┐ │ ◄─────proxied-endpoints─────┘ │ │
│ │1│ │2│ │3│ │..│ │ │ clients │
│ └─┘ └─┘ └─┘ └──┘ │ │ │
│ │ │ ┌─────────────┐ │
└──────────────────┘ │ │ wallet │ │
│ │ ┌───────────┴─┐ │
│ │ │ explorer │ │
│ └─┤ ┌───────────┴──┐ │
│ │ │ exchanges │ │
│ └─┤ ┌────────────┴──┐ │
│ │ │ other apps │ │
│ └─┤ using STX, │ │
│ │ BNS, etc.. │ │
│ └───────────────┘ │
│ │
└────────────────────────────────┘
```
* The `stacks-node` has it's own minimal set of http endpoints referred to as `RPC endpoints`
* See: https://github.com/blockstack/stacks-blockchain/blob/master/docs/rpc-endpoints.md
* Some common ones:
`POST /v2/transactions` - broadcast a tx.
`GET /v2/pox` - get current PoX-relevant information.
`GET /v2/accounts/<address>` - used to get the current `nonce` required for creating transactions.
* The `stacks-blockchain-api` allows clients to access these endpoints by proxying them through to a load-balanced pool of `stacks-nodes`.
* The endpoints implemented by `stacks-blockchain-api` provide data that the `stacks-node` can't due to various constraints.
* Typically this is either data that the `stacks-node` doesn't persist, or data that it cannot efficiently serve to many clients.
For example, the `stacks-node` can return the current STX balance of an account, but it can't return a history of account transactions.
* The API also implements the Rosetta spec created by Coinbase -- "an open standard designed to simplify blockchain deployment and interaction."
* See: https://www.rosetta-api.org/
* The API also implements the BNS (Blockchain Naming System) endpoints.
* See https://docs.stacks.co/build-apps/references/bns
* See `/src/api` for the Express.js routes.
* The API creates an "event observer" http server which listens for events from a `stacks-node` "event emitter"
* These events are http POST requests that contain things like blocks, transactions, byproducts of executed transactions.
* Transaction "byproducts" are things like asset transfers, smart-contract log data, execution cost data.
* The API processes and stores these as relational data in postgres.
* See `/src/event-stream` for the "event observer" code.
* All http endpoints and responses are defined in OpenAPI and JSON Schema.
* See `/docs/openapi.yaml`
* These are used to auto generate the docs at https://blockstack.github.io/stacks-blockchain-api/
* The JSON Schemas are converted into Typescript interfaces, which are used internally by the db controller module to transform SQL query results into the correct object shapes.
* ALSO the OpenAPI + JSONSchemas are used to generate a standalone `@stacks/blockchain-api-client`.
* The easiest/quickest way to develop in this repo is using the vscode debugger. It uses docker-compose to setup a `stacks-node` and postgres instance.
* Alternatively, you can run `npm run dev:integrated` which does the same thing but without a debugger.