{"id":13581818,"url":"https://github.com/trustwallet/blockatlas","last_synced_at":"2025-04-06T10:33:01.344Z","repository":{"id":34537312,"uuid":"175346438","full_name":"trustwallet/blockatlas","owner":"trustwallet","description":"Clean and lightweight cross-chain transaction API","archived":true,"fork":false,"pushed_at":"2022-03-16T08:35:35.000Z","size":19449,"stargazers_count":373,"open_issues_count":0,"forks_count":230,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-01-05T23:46:50.021Z","etag":null,"topics":["blockchain","blockchain-explorer","crypto"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trustwallet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null}},"created_at":"2019-03-13T04:30:13.000Z","updated_at":"2024-12-17T16:14:29.000Z","dependencies_parsed_at":"2022-08-08T01:15:14.811Z","dependency_job_id":null,"html_url":"https://github.com/trustwallet/blockatlas","commit_stats":null,"previous_names":[],"tags_count":61,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustwallet%2Fblockatlas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustwallet%2Fblockatlas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustwallet%2Fblockatlas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trustwallet%2Fblockatlas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trustwallet","download_url":"https://codeload.github.com/trustwallet/blockatlas/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247470525,"owners_count":20944146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","blockchain-explorer","crypto"],"created_at":"2024-08-01T15:02:15.595Z","updated_at":"2025-04-06T10:32:56.327Z","avatar_url":"https://github.com/trustwallet.png","language":"Go","funding_links":[],"categories":["Go","Market data libraries"],"sub_categories":[],"readme":"# Block Atlas by Trust Wallet\n\nTHIS REPO IS NO LONGER MAINTAINED\n\n---\n\n![Go Version](https://img.shields.io/github/go-mod/go-version/TrustWallet/blockatlas)\n[![codecov](https://codecov.io/gh/trustwallet/blockatlas/branch/master/graph/badge.svg)](https://codecov.io/gh/trustwallet/blockatlas)\n[![Go Report Card](https://goreportcard.com/badge/trustwallet/blockatlas)](https://goreportcard.com/report/TrustWallet/blockatlas)\n\n\u003e BlockAtlas is a clean explorer API and transaction observer for cryptocurrencies.\n\nBlockAtlas connects to nodes or explorer APIs of the supported coins and maps transaction data,\naccount transaction history into a generic, easy to work with JSON format.\n\nThe observer API watches the chain for new transactions and generates notifications by guids.\n\n#### Supported Coins\n\nBlock Atlas supports more than 25 blockchains: Bitcoin, Ethereum, Binance Chain etc, The full feature matrix is [here](docs/features.csv).\n\n## Architecture\n\nBlockatlas allows to:\n\n-   Get information about transactions, tokens, staking details, collectibles for supported coins.\n-   Subscribe for price notifications via Rabbit MQ\n\nPlatform API is independent service and can work with the specific blockchain only (like Bitcoin, Ethereum, etc)\n\nNotifications:\n\n-   Subscriber Producer - Create new blockatlas.SubscriptionEvent [Not implemented at Atlas, write it on your own]\n\n-   Subscriber - Get subscriptions from queue, set them to the DB\n\n-   Parser - Parse the block, convert block to the transactions batch, send to queue\n\n-   Notifier - Check each transaction for having the same address as stored at DB, if so - send tx data and id to the next queue\n\n-   Notifier Consumer - Notify the user [Not implemented at Atlas, write it on your own]\n\n\n```\nNew Subscriptions --(Rabbit MQ)--\u003e Subscriber --\u003e DB\n                                                   |\n                      Parser  --(Rabbit MQ)--\u003e Notifier --(Rabbit MQ)--\u003e Notifier Consumer --\u003e User\n\n```\n\nThe whole flow is not available at Atlas repo. We will have integration tests with it. Also there will be examples of all instances soon.\n\n## Setup\n\n### Prerequisite\n\n-   [Go Toolchain](https://golang.org/doc/install) versions 1.14+\n\n    Depends on what type of Blockatlas service you would like to run will also be needed.\n-   [Postgres](https://www.postgresql.org/download) to store user subscriptions and latest parsed block number\n-   [Rabbit MQ](https://www.rabbitmq.com/#getstarted) to pass subscriptions and send transaction notifications\n\n### Quick Start\n\n#### Get source code\n\nDownload source to `GOPATH`\n\n```shell\ngo get -u github.com/trustwallet/blockatlas\ncd $(go env GOPATH)/src/github.com/trustwallet/blockatlas\n```\n\n#### Build and run\n\nRead [configuration](#configuration) info\n\n```shell\n# Start Platform API server at port 8420 with the path to the config.yml ./\ngo build -o api-bin cmd/api/main.go \u0026\u0026 ./api-bin -p 8420\n\n# Start parser with the path to the config.yml ./ \ngo build -o parser-bin cmd/parser/main.go \u0026\u0026 ./parser-bin\n\n# Start notifier with the path to the config.yml ./ \ngo build -o notifier-bin cmd/notifier/main.go \u0026\u0026 ./notifier-bin\n\n# Start subscriber with the path to the config.yml ./ \ngo build -o subscriber-bin cmd/subscriber/main.go \u0026\u0026 ./subscriber-bin\n```\n\n### make command\n\nBuild and start all services:\n\n```shell\nmake go-build\nmake start\n```\n\nBuild and start individual service:\n\n```shell\nmake go-build-api\nmake start\n```\n\n### Docker\n\nBuild and run all services:\n\n```shell\ndocker-compose build\ndocker-compose up\n```\n\nBuild and run individual service:\n\n```shell\ndocker-compose build api\ndocker-compose start api\n```\n\n## Configuration\n\nWhen any of Block Atlas services started they look up inside [default configuration](./config.yml).\nMost coins offering public RPC/explorer APIs are enabled, thus Block Atlas can be started and used right away, no additional configuration needed.\nBy default starting any of the [services](#architecture) will enable all platforms\n\nTo run a specific service only by passing environmental variable, e.g: `ATLAS_PLATFORM=ethereum` :\n\n```shell\nATLAS_PLATFORM=ethereum go run cmd/api/main.go\n\nATLAS_PLATFORM=ethereum binance bitcoin go run cmd/api/main.go # for multiple platforms\n```\n\nor change in config file\n\n```yaml\n# Single\nplatform: [ethereum]\n# Multiple \nplatform: [ethereum, binance, bitcoin]\n```\n\nThis way you can one platform per binary, for scalability and sustainability.\n\nTo enable use of private endpoint:\n\n```yaml\nnimiq:\n  api: http://localhost:8648\n```\n\nIt works the same for worker - you can run all observer at 1 binary or 30 coins per 30 binaries\n\n#### Environment\n\nThe rest gets loaded from environment variables.\nEvery config option is available under the `ATLAS_` prefix. Nested keys are joined via `_`.\n\nExample:\n\n```shell\nATLAS_NIMIQ_API=http://localhost:8648\n```\n\n## Tests\n\n### Unit tests\n\n    make test\n\n### Mocked tests\n\nEnd-to-end tests with calls to external APIs has great value, but they are not suitable for regular CI verification, beacuse any external reason could break the tests.\n\n    # Start API server with mocked config, at port 8437 ./ \n    go build -o api-bin cmd/api/main.go \u0026\u0026 ./api-bin -p 8437 -c configmock.yml\n\nTherefore mocked API-level tests are used, whereby external APIs are replaced by mocks.\n\n-   External mocks are implemented as a simple, own, golang `mockserver`.  It listens locally, and returns responses to specific API paths, taken from json data files.\n-   There is a file where API paths and corresponding data files are listed.\n-   Tests invoke into blockatlas through public APIs only, and are executed using _newman_ (Postman cli -- `make newman-mocked`).\n-   Product code, and even test code should not be aware whether it runs with mocks or the real external endpoints.\n-   See Makefile for targets with 'mock'; platform can be started locally with mocks using `make start-platform-api-mock`.\n-   The newman tests can be executed with unmocked external APIs as well, but verifications may fail, because some APIs return variable responses.  Unmocked tests are not intended for regular CI execution, but as ad-hoc development tests.\n-   General steps for creating new mocked tests: replace endpoint to localhost:3347, observe incoming calls (visible in mockserver's output), obtain real response from external API (with exact same parameters), place response in a file, add path + file to data file list.  Restart mock, and verify that blockatlas provides correct output.  Also, add verifications of results to the tests.\n\n## Docs\n\nSwagger API docs provided at path `/swagger/index.html`\n\nor you can install `go-swagger` and render it locally (macOS example)\n\nInstall:\n\n```shell\nbrew tap go-swagger/go-swagger\nbrew install go-swagger\n```\n\nRender: \n\n```shell\nswagger serve docs/swagger.yaml\n```\n\n#### Updating Docs\n\n-   After creating a new route, add comments to your API source code, [See Declarative Comments Format](https://swaggo.github.io/swaggo.io/declarative_comments_format/).\n\n-   Run `$ make go-gen-docs` in root folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrustwallet%2Fblockatlas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrustwallet%2Fblockatlas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrustwallet%2Fblockatlas/lists"}