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
6359components. Before you start, you'll need to have access to:
6460
65611 . 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 )
70631 . 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
185116The 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
205136This queue runs continuously and can handle an unlimited number of jobs.
206137
207- ##### Process Smart Contract Job
138+ #### Process Smart Contract Job
208139
209140This job makes a contract call to the Stacks node in order to determine the total number of tokens
210141declared by the given contract. Once determined, it creates and enqueues all of these tokens for
211142metadata ingestion.
212143
213- ##### Process Token Job
144+ #### Process Token Job
214145
215146This job fetches the metadata JSON object for a single token as well as other relevant properties
216147depending on the token type (symbol, decimals, etc.). Once fetched, it parses and ingests this data
0 commit comments