{"id":18254747,"url":"https://github.com/bitcoin-sv/block-headers-service","last_synced_at":"2025-04-04T17:30:51.775Z","repository":{"id":37095298,"uuid":"380277997","full_name":"bitcoin-sv/block-headers-service","owner":"bitcoin-sv","description":"A headers only peer on the Bitcoin p2p network, with a private web API to allow Merkle root validation.","archived":false,"fork":false,"pushed_at":"2024-04-26T18:21:17.000Z","size":297928,"stargazers_count":26,"open_issues_count":5,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-04-28T19:29:54.017Z","etag":null,"topics":["bsv","client","go","golang","headers","spv","spv-wallet-team","spv-wallet-toolkit"],"latest_commit_sha":null,"homepage":"https://bsvblockchain.org","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitcoin-sv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-25T15:20:34.000Z","updated_at":"2024-08-01T12:20:41.165Z","dependencies_parsed_at":"2023-02-15T07:46:42.539Z","dependency_job_id":"27e6c4b1-e915-41cb-a96f-bb4508d3d32d","html_url":"https://github.com/bitcoin-sv/block-headers-service","commit_stats":null,"previous_names":["libsv/bitcoin-hc","bitcoin-sv/pulse","bitcoin-sv/block-headers-service","libsv/pulse"],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcoin-sv%2Fblock-headers-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcoin-sv%2Fblock-headers-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcoin-sv%2Fblock-headers-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitcoin-sv%2Fblock-headers-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitcoin-sv","download_url":"https://codeload.github.com/bitcoin-sv/block-headers-service/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223150706,"owners_count":17095959,"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":["bsv","client","go","golang","headers","spv","spv-wallet-team","spv-wallet-toolkit"],"created_at":"2024-11-05T10:13:25.869Z","updated_at":"2024-11-05T10:13:26.451Z","avatar_url":"https://github.com/bitcoin-sv.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Release](https://img.shields.io/github/release-pre/bitcoin-sv/block-headers-service.svg?logo=github\u0026style=flat\u0026v=1)](https://github.com/bitcoin-sv/block-headers-service/releases)\n[![Build Status](https://img.shields.io/github/workflow/status/bitcoin-sv/block-headers-service/go?logo=github\u0026v=3)](https://github.com/bitcoin-sv/block-headers-service/actions)\n[![Report](https://goreportcard.com/badge/github.com/bitcoin-sv/block-headers-service?style=flat\u0026v=1)](https://goreportcard.com/report/github.com/bitcoin-sv/block-headers-service)\n[![Go](https://img.shields.io/github/go-mod/go-version/bitcoin-sv/block-headers-service?v=1)](https://golang.org/)\n\u003cbr /\u003e\n\n\u003ch1 id=\"top\" align=\"center\"\u003eBlock Headers Service\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Go application used to collect and return information about blockchain headers\n\u003c/p\u003e\n\n\u003ch4 id=\"top\" align=\"center\"\u003eFormerly known as \"Pulse\"\u003c/h1\u003e\n\n## Table of contents\n\u003cdetails\u003e\n  \u003c!--\u003csummary\u003eTable of Contents\u003c/summary\u003e --\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#main-functionality\"\u003eMain Functionality\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n\u003cli\u003e\n      \u003ca href=\"#how-to-use-it\"\u003eHow to use it\u003c/a\u003e\n\u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#docker-image\"\u003eDocker image\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#endpoints-documentation\"\u003eEndpoints documentation\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#authentication\"\u003eAuthentication\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#websocket\"\u003eWebsocket\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#webhooks\"\u003eWebhooks\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n\u003ca href=\"#Running-from-source\"\u003eRunning from source\u003c/a\u003e\n\u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#Running-from-source\"\u003eRun application\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n      \n    \u003c/li\u003e\n    \n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\nBlock header service is a go service which connects into BSV P2P network to gather and then serve information about all exisiting and new headers. It is build to work as a standaolne app or a module in bigger system.\n\n#### Main functionality\nThe main functionality of the application is synchornization with peers and collecting all headers. After starting the server, it creates default objects and connects to BSV P2P network. Application has defined checkpoints (specific headers) which are used in synchronization. During this process, server is asking peers for headers (from checkpoint to checkpoint) in batches of 2000. Every header received from peers is saved in memory. After full synchronization, server is changing the operating mode and start to listening for new header. After when new block has been mined, this information should be sended from peers to our server.\n\nFor in-depth information and guidance, please refer to the [SPV Wallet Documentation](https://bsvblockchain.gitbook.io/docs).\n\n## How to use it\n\n### Docker image\n\nPull image from docker hub https://hub.docker.com/r/bsvb/block-headers-service\n1. ```docker pull bsvb/block-headers-service```\n\nStarting new instance\n1. ```docker run bsvb/block-headers-service:latest```\n\n\n### Endpoints documentation\nFor endpoints documentation you can visit swagger which is exposed on port 8080 by default.\n```\nhttp://localhost:8080/swagger/index.html\n```\n\n### Authentication\n\n#### Enabled by Default\n\nThe default assumes you want to use Authentication. This requires a single environment variable.  \n\n`BHS_HTTP_AUTH_TOKEN=replace_me_with_token_you_want_to_use_as_admin_token`  \n\n#### Disabling Auth Requirement  \n\nTo disable authentication exposing all endpoints openly, set the following environment variable. \nThis is available if you prefer to use your own authentication in a separate proxy or similar. \nWe do not recommend you expose the server to the internet without authentication, \nas it would then be possible for anyone to prune your headers at will.  \n\n`BHS_HTTP_USE_AUTH=false`  \n\n#### Authenticate with admin token\n\nAfter the setup of authentication you can use provided token to authenticate.\nTo do it, just add the following header to all the requests to block-headers-service.\n```\nAuthorization Bearer replace_me_with_token_you_want_to_use_as_admin_token\n```\n\n#### Additional tokens\n\nIf you have a need for additional tokens to authenticate in block-headers-service.\nyou can generate such with the following request:\n```http request\nPOST https://{{block-headers-service_url}}/api/v1/access\nAuthorization: Bearer replace_me_with_token_you_want_to_use_as_admin_token\n```\nIn response you should receive something like\n```json\n{\n  \"token\": \"some_token_created_by_server\",\n  \"createdAt\": \"2023-05-11T10:20:16.227582Z\",\n  \"isAdmin\": false\n}\n```\nNow you can put a value from \"token\" property from the response and use it in all requests to server by setting header:\n```http header\nAuthorization: Bearer some_token_created_by_server\n```\n\nIf at some point you want to revoke this additional token you can make a request:\n```http request\nDELETE https://{{block-headers-service_url}}/api/v1/access/{{some_token_created_by_server}}\nAuthorization: Bearer replace_me_with_token_you_want_to_use_as_admin_token\n```\nAfter this request succeeded the token can't be used to authenticate in block-headers-service.\n\n### Websocket\n\nBlock headers service can notify a client via websockets that new header was received and store by it.\n\n#### Subscribing\n\nBlock headers service use [centrifugal/centrifuge](https://github.com/centrifugal/centrifuge) to run a server.\nTherefore, to integrate you need to choose a client library matching a programming language of your choice.\n\nExample how to subscribe using GO lang library [centrifugal/centrifuge-go](https://github.com/centrifugal/centrifuge-go) \ncan be found in [./examples/ws-subscribe-to-new-headers/](./examples/ws-subscribe-to-new-headers/main.go)\n\n### Webhooks\n\n#### Creating webhook\nCreating a new webhook is done via POST request\n```http request\n POST https://{{block-headers-service_url}}/api/v1/webhook\n ```\n\n Data which should be sent in body:\n ```\n{\n  \"url\": \"\u003cserver_url\u003e\",\n  \"requiredAuth\": {\n    \"type\": \"BEARER|CUSTOM_HEADER\",\n    \"token\": \"\u003cauthorization_token\u003e\",\n    \"header\": \"\u003ccustom_header_name\u003e\",      \n  }\n}\n ```\n\n Information:\n  - If authorization is enabled this request also requires `Authorization` header\n  - url have to include http or https protocol example: `https://test-url.com`\n  - requiredAuth is used to define authorization for webhook\n    - type `BEARER` - token will be placed in `Authorization: Bearer {{token}}` header\n    - type `CUSTOM_HEADER`  - authorization header will be build from given variables `{{header}}: {{token}}`\n\nExample response:\n````json\n{\n  \"url\": \"http://example.com/api/v1/webhook/new-header\",\n  \"createdAt\": \"2023-05-11T13:05:23.297808+02:00\",\n  \"lastEmitStatus\": \"\",\n  \"lastEmitTimestamp\": \"0001-01-01T00:00:00Z\",\n  \"errorsCount\": 0,\n  \"active\": true\n}\n````\nAfter that webhook is created and will be informed about new headers.\n\n#### Check webhook\nTo check webhook you can use the GET request which will return webhook object (same as when creating new webhook) from which you can get all the information\n```http request\n GET https://{{block-headers-service_url}}/api/v1/webhook?url={{webhook_url}}\n ```\n\n#### Revoke webhook\nIf you want to revoke webhook you can use the following request:\n```http request\n DELETE https://{{block-headers-service_url}}/api/v1/webhook?url={{webhook_url}}\n ```\nThis request will delete webhook permanently\n\n#### Refresh webhook\nIf the number of failed requests wil exceed `WEBHOOK_MAXTRIES`, webhook will be set to inactive. To refresh webhook you can use this same endpoint as for webhook creation.\n\n### Running from source\n\n1. Install Go according to the installation instructions here: http://golang.org/doc/install\n\nOptions to run Block Headers Service:\n\na) Clone the repo\n\n   ```sh\n  git clone https://github.com/bitcoin-sv/block-headers-service\n   ``` \n1. ```go run ./cmd/main.go```\n\nOr run app with docker\n1. ```docker compose up --build```\n\nb) Get package from ``pkg.dev.go``\n1. ```go get -u https://pkg.go.dev/github.com/bitcoin-sv/block-headers-service```\n2. ```go build -o block-headers-service```\n3. ```./block-headers-service```\n\n\n## Usage\n\n\u003e Every variable which is used and can be configured is described in [config.example.yaml](config.example.yaml)\n\n### Defaults\n\nIf you run block headers service without editing anything, it will use the default configuration from file [defaults.go](/config/defaults.go). It is set up to use _sqlite_ database with enabled authorization (with default auth key) for http server.\n\n### Config Variables\n\nDefault config variables can be overridden by (in this order of importance):\n\n1. Flags (only the ones below)\n2. ENV variables\n3. Config file\n\n#### Flags\n\nAvailable flags:\n\n```bash\n  -C, --config_file string                       custom config file path\n  -h, --help                                     show help\n  -v, --version                                  show version\n  -d, --dump_config                              dump config to file, specified by config_file (-C) flag\n  -e, --export_headers                           export headers to file\n```\n\nTo generate config file with defaults, use the --dump flag, or:\n\n```bash\ngo run ./cmd/main.go -d\n```\n\nThe default config file path is **program root**, and the default file name is **config.yaml**. This can be overridden by -C flag.\n\n```bash\ngo run ./cmd/main.go -C /my/config.yaml\n```\n\n#### Environment variables\n\nTo override any config variable with ENV, use the \"headers-service\\_\" prefix with mapstructure annotation path with \"_\" as a delimiter in all uppercase. Example:\n\nLet's take this fragment of AppConfig from `config.example.yaml`:\n\n```yaml\nwebsocket:\n  # Maximum number of history items\n  history_max: 300\n  # History time-to-live\n  history_ttl: 10\n```\n\nTo override history_max in websocket config, use the path with \"_\" as a path delimiter and bhs\\_ as prefix. So:\n\n```bash\nBHS_HISTORY_MAX=300\n```\n\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\n## Updating predefined database\n\nWhen you start the application, and synchronization process is long when using prepared database, it's recommended to use the `-e` flag to export fresh database with all headers. This will speed up the process of synchronization in the future.\n\n\u003e **Note:**: Export feature works only with SQLite database.\n\n```bash\ngo run ./cmd/main.go -e\n```\n\nThis will create a new .csv file with all headers in the same directory as the database file.\nCommit your changes and create a pull request with the new database file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoin-sv%2Fblock-headers-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitcoin-sv%2Fblock-headers-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitcoin-sv%2Fblock-headers-service/lists"}