{"id":25918112,"url":"https://github.com/hirosystems/bitcoin-indexer","last_synced_at":"2025-10-24T13:25:20.265Z","repository":{"id":38192968,"uuid":"240430005","full_name":"hirosystems/bitcoin-indexer","owner":"hirosystems","description":"Index Bitcoin meta-protocols like Ordinals, BRC-20, and Runes","archived":false,"fork":false,"pushed_at":"2025-04-11T15:36:16.000Z","size":21332,"stargazers_count":209,"open_issues_count":73,"forks_count":59,"subscribers_count":21,"default_branch":"develop","last_synced_at":"2025-04-12T14:58:09.369Z","etag":null,"topics":["bitcoin","brc-20","ordinals","ordinals-nft","runes"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hirosystems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-14T04:46:12.000Z","updated_at":"2025-04-04T11:05:11.000Z","dependencies_parsed_at":"2023-11-27T04:23:21.939Z","dependency_job_id":"bc71069e-7455-4499-ab18-285db6b8b9dc","html_url":"https://github.com/hirosystems/bitcoin-indexer","commit_stats":null,"previous_names":["lgalabru/clarity-lsp","hirosystems/ordhook","hirosystems/hord","hirosystems/bitcoin-indexer"],"tags_count":53,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fbitcoin-indexer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fbitcoin-indexer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fbitcoin-indexer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hirosystems%2Fbitcoin-indexer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hirosystems","download_url":"https://codeload.github.com/hirosystems/bitcoin-indexer/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248586249,"owners_count":21128997,"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":["bitcoin","brc-20","ordinals","ordinals-nft","runes"],"created_at":"2025-03-03T14:04:32.520Z","updated_at":"2025-10-24T13:25:20.260Z","avatar_url":"https://github.com/hirosystems.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"       /     /   ▶ Bitcoin Indexer\n      / --- /      Index Bitcoin meta-protocols like Ordinals, BRC-20, and Runes.\n     /     /\n\n- [Features](#features)\n- [Quick Start](#quick-start)\n  - [Installing](#installing)\n  - [Running the Indexer](#running-the-indexer)\n  - [Running an API](#running-an-api)\n- [Configuration](#configuration)\n- [System Requirements](#system-requirements)\n  - [Postgres](#postgres)\n- [Contribute](#contribute)\n  - [Code of Conduct](#code-of-conduct)\n  - [Contributing Guide](#contributing-guide)\n- [Community](#community)\n\n***\n\n# Features\n\n**Bitcoin Indexer** is a tool that continuously reads Bitcoin blocks from a connected Bitcoin\nnode in order to extract and index meta-protocol data contained within it. Once indexed, data is\nstored in a Postgres DB and can be made available to clients or users via REST APIs.\n\n# Quick Start\n\n## Installing\n\n```console\n$ git clone https://github.com/hirosystems/bitcoin-indexer.git\n$ cd bitcoin-indexer\n$ cargo bitcoin-indexer-install\n```\n\nDocker images are also available at https://hub.docker.com/r/hirosystems/bitcoin-indexer\n\nNote: You may need to install additional LLVM and Clang dependencies if they are not already available on your system.\n\n## Running the Indexer\n\nThe following command will start indexing Ordinals activity and will continue to stream new blocks\nonce it reaches the Bitcoin chain tip.\n```console\n$ bitcoin-indexer ordinals service start --config-path \u003cpath\u003e\n```\n\nA similar command exists for indexing Runes\n```console\n$ bitcoin-indexer runes service start --config-path \u003cpath\u003e\n```\n\nA fully synced Bitcoin node is required for indexing to start.\n\n### Running Tests\n\nThe test suite can be run in a Docker environment that includes all necessary dependencies (PostgreSQL, Rust toolchain, etc.). This ensures consistent test execution across all development environments.\n\nTo run the tests:\n\n```bash\n./scripts/run-tests.sh\n```\n\nThis script will:\n1. Start a PostgreSQL container\n2. Build the Bitcoin Indexer Docker image\n3. Run all tests in the Docker environment\n4. Clean up containers after completion\n\nFor more granular test control, you can run specific test suites using cargo:\n\n```bash\n# Start docker postgres\ndocker compose -f dockerfiles/docker-compose.dev.postgres.yml up -d\n\n# Run all tests\ncargo test --workspace\n\n# Run tests for a specific component\ncargo test -p components/bitcoind\n\n# Stop and remove docker postgres\ndocker compose -f dockerfiles/docker-compose.dev.postgres.yml down -v -t 0\n```\n\n## Running an API\n\nOnce the index starts advancing, you can deploy the Ordinals API or Runes API to read the same data\nvia REST endpoints.\n\n# Configuration\n\nIndexer configurations are set via a TOML file. To generate a new config file, run this command:\n```console\n$ bitcoin-indexer config new\n```\n\nPostgres database configurations are set like this. Each index will have its own database.\n```toml\n[ordinals.db]\ndatabase = \"ordinals\"\nhost = \"localhost\"\nport = 5432\nusername = \"postgres\"\npassword = \"postgres\"\n```\n\nOrdinals meta-protocols like BRC-20 are also configured in this file\n```toml\n[ordinals.meta_protocols.brc20]\nenabled = true\nlru_cache_size = 10000\n\n[ordinals.meta_protocols.brc20.db]\ndatabase = \"brc20\"\nhost = \"localhost\"\nport = 5432\nusername = \"postgres\"\npassword = \"postgres\"\n```\n\n# System Requirements\n\nThe Bitcoin Indexer is resource-intensive, demanding significant CPU, memory and disk capabilities.\nAs we continue to refine and optimize, keep in mind the following system requirements and\nrecommendations to ensure optimal performance:\n\n* CPU: The ordhook tool efficiently utilizes multiple cores when detected at runtime, parallelizing\ntasks to boost performance.\n\n* Memory: A minimum of 16GB RAM is recommended.\n\n* Disk: To enhance I/O performance, SSD or NVMe storage is suggested.\n\n* OS Requirements: Ensure your system allows for a minimum of 4096 open file descriptors.\nConfiguration may vary based on your operating system. On certain systems, this can be adjusted\nusing the `ulimit` command or the `launchctl limit` command.\n\n## Postgres\n\nTo store indexed data, a Postgres database is required per index (ordinals, runes, etc.).\nIt is recommended to use Postgres 17+ for optimal performance.\n\n## Bitcoin Node\n\nTo index data, a Bitcoin Node is required.\nThe indexer officially supports Bitcoin Core versions 0.24.x and 0.25.x.\n\n# Contribute\n\nDevelopment of this product happens in the open on GitHub, and we are grateful\nto the community for contributing bugfixes and improvements. Read below to learn\nhow you can take part in improving the product.\n\n## Code of Conduct\nPlease read our [Code of conduct](../../../.github/blob/main/CODE_OF_CONDUCT.md)\nsince we expect project participants to adhere to it. \n\n## Contributing Guide\nRead our [contributing guide](.github/CONTRIBUTING.md) to learn about our\ndevelopment process, how to propose bugfixes and improvements, and how to build\nand test your changes.\n\n# Community\n\nJoin our community and stay connected with the latest updates and discussions:\n\n- [Join our Discord community chat](https://discord.gg/ZQR6cyZC) to engage with\n  other users, ask questions, and participate in discussions.\n\n- [Visit hiro.so](https://www.hiro.so/) for updates and subcribing to the\n  mailing list.\n\n- Follow [Hiro on Twitter.](https://twitter.com/hirosystems)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhirosystems%2Fbitcoin-indexer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhirosystems%2Fbitcoin-indexer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhirosystems%2Fbitcoin-indexer/lists"}