{"id":28431727,"url":"https://github.com/block/bitcoin-augur-reference","last_synced_at":"2025-08-11T00:46:26.610Z","repository":{"id":294520511,"uuid":"984282269","full_name":"block/bitcoin-augur-reference","owner":"block","description":"Reference usage of augur, a mempool-based bitcoin fee estimation library","archived":false,"fork":false,"pushed_at":"2025-06-24T20:55:49.000Z","size":63,"stargazers_count":2,"open_issues_count":2,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-27T03:48:11.218Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Kotlin","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/block.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-15T17:16:45.000Z","updated_at":"2025-07-16T02:43:30.000Z","dependencies_parsed_at":"2025-05-20T21:23:47.108Z","dependency_job_id":null,"html_url":"https://github.com/block/bitcoin-augur-reference","commit_stats":null,"previous_names":["block/bitcoin-augur-reference"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/block/bitcoin-augur-reference","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fbitcoin-augur-reference","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fbitcoin-augur-reference/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fbitcoin-augur-reference/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fbitcoin-augur-reference/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/block","download_url":"https://codeload.github.com/block/bitcoin-augur-reference/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/block%2Fbitcoin-augur-reference/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269814220,"owners_count":24479355,"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","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-06-05T16:08:12.556Z","updated_at":"2025-08-11T00:46:26.577Z","avatar_url":"https://github.com/block.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Augur Reference Implementation\n\nThis project serves as a reference implementation of the [augur](https://github.com/block/bitcoin-augur) Bitcoin fee estimation library. It demonstrates how to:\n\n- Connect to a Bitcoin Core instance and persist mempool snapshots\n- Calculate fee estimates using Augur's prediction model\n- Expose fee estimates via a REST API\n\n## Features\n\n- **Mempool Data Collection**: Connects to Bitcoin Core via RPC and collects mempool data at regular intervals\n- **Persistence**: Stores mempool snapshots for later analysis and fee estimation\n- **Fee Estimation**: Uses the Augur library to calculate fee estimates based on historical mempool data\n- **REST API**: Exposes fee estimates through a simple HTTP endpoint\n\n## Getting Started\n\n### Prerequisites\n\n- Java 17 or higher\n- Access to a Bitcoin Node with RPC access (specifically, requires the `getrawmempool` and `getblockchaininfo` RPC methods)\n\n### Configuration\n\nThe application uses YAML for configuration with support for environment variable overrides.\n\n#### Configuration Methods (in order of precedence)\n\n1. **Environment Variables**: Highest priority\n2. **External Config File**: Specified by `AUGUR_CONFIG_FILE` environment variable\n3. **Default Config**: From `config.yaml` in resources\n\n#### Configuration Options\n\n| Setting | Environment Variable | Default | Description |\n|---------|---------------------|---------|-------------|\n| `server.host` | `AUGUR_SERVER_HOST` | `0.0.0.0` | HTTP server host |\n| `server.port` | `AUGUR_SERVER_PORT` | `8080` | HTTP server port |\n| `bitcoinRpc.url` | `BITCOIN_RPC_URL` | `http://localhost:8332` | Bitcoin Core RPC URL |\n| `bitcoinRpc.username` | `BITCOIN_RPC_USERNAME` | _(empty)_ | Bitcoin Core RPC username |\n| `bitcoinRpc.password` | `BITCOIN_RPC_PASSWORD` | _(empty)_ | Bitcoin Core RPC password |\n| `persistence.dataDirectory` | `AUGUR_DATA_DIR` | `mempool_data` | Directory for storing mempool snapshots |\n\n#### Sample YAML Configuration\n\n```yaml\nserver:\n  host: \"0.0.0.0\"\n  port: 8080\n\nbitcoinRpc:\n  url: \"http://localhost:8332\"\n  username: \"rpcuser\"\n  password: \"rpcpassword\"\n\npersistence:\n  dataDirectory: \"mempool_data\"\n```\n\n### Building\n\nThis project uses CashApp's [Hermit](https://cashapp.github.io/hermit/). Hermit ensures that your team, your contributors,\nand your CI have the same consistent tooling. Here are the [installation instructions](https://cashapp.github.io/hermit/usage/get-started/#installing-hermit).\n\n[Activate Hermit](https://cashapp.github.io/hermit/usage/get-started/#activating-an-environment) either\nby [enabling the shell hooks](https://cashapp.github.io/hermit/usage/shell/) (one-time only, recommended) or manually\nsourcing the env with `. ./bin/activate-hermit`.\n\nUse gradle to run all tests:\n\n```shell\nbin/gradle build\n```\n\n### Running the Application\n\n#### Using Default Configuration\n\n```bash\nbin/gradle run\n```\n\n#### Using Environment Variables\n\n```bash\nBITCOIN_RPC_USERNAME=myuser BITCOIN_RPC_PASSWORD=mypassword bin/gradle run\n```\n\n#### Using External Config File\n\n```bash\nAUGUR_CONFIG_FILE=/path/to/my-config.yaml bin/gradle run\n```\n\n#### Using Docker\nAlternatively, you can use Docker by first defining the `bitcoinRpc` username and password in the `config.yaml` file,\nand then using:\n```bash\ndocker build -t bitcoin-augur-reference .\ndocker run -p 8080:8080 bitcoin-augur-reference\n```\n\n## API Usage\n\nOnce running, the application exposes fee estimates at:\n\n```\nGET /fees\n```\n\nExample response:\n\n```json\n{\n  \"mempool_update_time\": \"2025-03-03T19:13:50.043Z\",\n  \"estimates\": {\n    \"3\": {\n      \"probabilities\": {\n        \"0.05\": {\n          \"fee_rate\": 2.0916\n        },\n        \"0.20\": {\n          \"fee_rate\": 3.0931\n        },\n        \"0.50\": {\n          \"fee_rate\": 3.4846\n        },\n        \"0.80\": {\n          \"fee_rate\": 4.0535\n        },\n        \"0.95\": {\n          \"fee_rate\": 5.0531\n        }\n      }\n    },\n    \"6\": {\n      \"probabilities\": {\n        \"0.05\": {\n          \"fee_rate\": 1.9631\n        },\n        \"0.20\": {\n          \"fee_rate\": 2.9441\n        },\n        \"0.50\": {\n          \"fee_rate\": 3.1191\n        },\n        \"0.80\": {\n          \"fee_rate\": 3.4903\n        },\n        \"0.95\": {\n          \"fee_rate\": 4.8708\n        }\n      }\n    },\n    \"9\": {\n      \"probabilities\": {\n        \"0.05\": {\n          \"fee_rate\": 1.8778\n        },\n        \"0.20\": {\n          \"fee_rate\": 2.8979\n        },\n        \"0.50\": {\n          \"fee_rate\": 3.1154\n        },\n        \"0.80\": {\n          \"fee_rate\": 3.4903\n        },\n        \"0.95\": {\n          \"fee_rate\": 4.2041\n        }\n      }\n    }\n  }\n}\n```\n\n## Local Development\nIf you'd like to use a local version of [augur](https://github.com/block/bitcoin-augur) within your reference implementation:\n- Within augur, run `bin/gradle shadowJar` to build a fat jar of augur.\n- Copy the file `lib/build/libs/augur.jar` into this reference implementation `app/libs` directory.\n- Change\n  `implementation(libs.augur)` to `implementation(files(\"libs/augur.jar\"))` in the `app/build.gradle.kts` [file](https://github.com/block/bitcoin-augur-reference/blob/main/app/build.gradle.kts).\n- Within the reference implementation, run `bin/gradle build` to build the project with the local version of augur.\n\n## Project Structure\n\n- `config`: Configuration classes\n- `bitcoin`: Bitcoin Core RPC client\n- `persistence`: Mempool snapshot persistence\n- `service`: Core application services\n- `api`: API endpoints\n- `server`: HTTP server setup\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock%2Fbitcoin-augur-reference","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblock%2Fbitcoin-augur-reference","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblock%2Fbitcoin-augur-reference/lists"}