Skip to content

Commit b1b8f4b

Browse files
authored
docs: update README (#259)
* Update README.md * Delete architecture.png * Delete flowchart.png
1 parent 20d753a commit b1b8f4b

File tree

3 files changed

+12
-81
lines changed

3 files changed

+12
-81
lines changed

README.md

Lines changed: 12 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,9 @@
1313
* [Stopping the service](#stopping-the-service)
1414
* [Using an image cache service](#using-an-image-cache-service)
1515
* [Service architecture](#service-architecture)
16-
* [External](#external)
17-
* [Internal](#internal)
18-
* [Blockchain importer](#smart-contract-importer)
19-
* [Smart Contract Monitor](#smart-contract-monitor)
20-
* [Job Queue](#job-queue)
21-
* [Process Smart Contract Job](#process-smart-contract-job)
22-
* [Process Token Job](#process-token-job)
16+
* [Job Queue](#job-queue)
17+
* [Process Smart Contract Job](#process-smart-contract-job)
18+
* [Process Token Job](#process-token-job)
2319
* [Bugs and Feature Requests](#bugs-and-feature-requests)
2420
* [Contribute](#contribute)
2521
* [Community](#community)
@@ -63,11 +59,9 @@ The Token Metadata Service is a microservice that has hard dependencies on other
6359
components. Before you start, you'll need to have access to:
6460

6561
1. A fully synchronized [Stacks node](https://github.com/stacks-network/stacks-blockchain)
66-
1. A fully synchronized instance of the [Stacks Blockchain
67-
API](https://github.com/hirosystems/stacks-blockchain-api) running in `default` or `write-only`
68-
mode, with its Postgres database exposed for new connections. A read-only DB replica is also
69-
acceptable.
62+
1. A fully synchronized instance of [Chainhook](https://github.com/hirosystems/chainhook)
7063
1. A local writeable Postgres database for token metadata storage
64+
1. (Optional) A Google Cloud Storage bucket for storing token images
7165

7266
### Running the service
7367

@@ -110,77 +104,14 @@ disconnected.
110104

111105
### Using an image cache service
112106

113-
The Token Metadata Service allows you to specify the path to a custom script that can pre-process
114-
every image URL detected by the service before it's inserted into the DB. This allows you to serve
115-
CDN image URLs in your metadata responses instead of raw URLs, providing key advantages such as:
116-
117-
* Improves image load speed
118-
* Increases reliability in case original image becomes unavailable
119-
* Protects original image hosts from DDoS attacks
120-
* Increases user privacy
121-
* etc.
122-
123-
An example IMGIX processor script is included in
124-
[`config/image-cache.js`](https://github.com/hirosystems/token-metadata-api/blob/develop/config/image-cache.js).
125-
You can customize the script path by altering the `METADATA_IMAGE_CACHE_PROCESSOR` environment
126-
variable.
107+
The Token Metadata API allows you to specify a Google Cloud Storage bucket to store the token images
108+
scanned by the metadata processor. This is recommended if you're looking to optimize your image speeds
109+
when using the API via a wallet, etc. See the `env.ts` file for more information on which environment
110+
variables you need to provide.
127111

128112
## Service architecture
129113

130-
### External
131-
132-
![Architecture](architecture.png)
133-
134-
The Stacks Token Metadata Service connects to three different systems to operate:
135-
136-
1. A Stacks Blockchain API database to import all historical smart contracts when booting up, and to
137-
listen for new contracts that may be deployed. Read-only access is recommended as this service
138-
will never need to write anything to this DB.
139-
1. A Stacks node to respond to all read-only contract calls required when fetching token metadata
140-
(calls to get token count, token metadata URIs, etc.)
141-
1. A local Postgres DB to store all processed metadata info
142-
143-
The service will also need to fetch external metadata files (JSONs, images) from the Internet, so it
144-
must have access to external networks.
145-
146-
### Internal
147-
148-
![Flowchart](flowchart.png)
149-
150-
#### Blockchain importer
151-
152-
The
153-
[`BlockchainImporter`](https://github.com/hirosystems/token-metadata-api/blob/develop/src/token-processor/blockchain-api/blockchain-importer.ts)
154-
component is only used on service boot.
155-
156-
It connects to the Stacks Blockchain API database and scans the entire `smart_contracts` table
157-
looking for any contract that conforms to SIP-009, SIP-010 or SIP-013. When it finds a token
158-
contract, it creates a
159-
[`ProcessSmartContractJob`](https://github.com/hirosystems/token-metadata-api/blob/develop/src/token-processor/process-smart-contract-job.ts)
160-
job and adds it to the [Job queue](#job-queue) so its tokens can be read and processed thereafter.
161-
162-
This process is only run once. If the Token Metadata Service is ever restarted, though, this
163-
component re-scans the API `smart_contracts` table from the last processed block height so it can
164-
pick up any newer contracts it might have missed while the service was unavailable.
165-
166-
#### Smart Contract Monitor
167-
168-
The
169-
[`BlockchainSmartContractMonitor`](https://github.com/hirosystems/token-metadata-api/blob/develop/src/token-processor/blockchain-api/blockchain-smart-contract-monitor.ts)
170-
component constantly listens for the following Stacks Blockchain API events:
171-
172-
* **Smart contract log events**
173-
174-
If a contract `print` event conforms to SIP-019, it finds the affected tokens and marks them for
175-
metadata refresh.
176-
177-
* **Smart contract deployments**
178-
179-
If the new contract is a token contract, it saves it and enqueues it for token processing.
180-
181-
This process is kept alive throughout the entire service lifetime.
182-
183-
#### Job Queue
114+
### Job Queue
184115

185116
The role of the
186117
[`JobQueue`](https://github.com/hirosystems/token-metadata-api/blob/develop/src/token-processor/queue/job-queue.ts)
@@ -204,13 +135,13 @@ There are two env vars that can help you tune how the queue performs:
204135

205136
This queue runs continuously and can handle an unlimited number of jobs.
206137

207-
##### Process Smart Contract Job
138+
#### Process Smart Contract Job
208139

209140
This job makes a contract call to the Stacks node in order to determine the total number of tokens
210141
declared by the given contract. Once determined, it creates and enqueues all of these tokens for
211142
metadata ingestion.
212143

213-
##### Process Token Job
144+
#### Process Token Job
214145

215146
This job fetches the metadata JSON object for a single token as well as other relevant properties
216147
depending on the token type (symbol, decimals, etc.). Once fetched, it parses and ingests this data

architecture.png

-112 KB
Binary file not shown.

flowchart.png

-289 KB
Binary file not shown.

0 commit comments

Comments
 (0)