Augur Reference Implementation

This project serves as a reference implementation of the Augur Bitcoin fee estimation library. It demonstrates how to:

• Connect to a Bitcoin Core instance and persist mempool snapshots
• Calculate fee estimates using Augur's prediction model
• Expose fee estimates via a REST API

This reference service is intended to showcase the features of the Augur library, and is meant as a tool for exploring the fee estimation data that Augur generates. It serves as example code on how to integrate the library into a Kotlin codebase; it is not intended to be used as a production-ready fee estimation service.

Features

• Mempool Data Collection: Connects to Bitcoin Core via RPC and collects mempool data at regular intervals
• Persistence: Stores mempool snapshots for later analysis and fee estimation
• Fee Estimation: Uses the Augur library to calculate fee estimates based on historical mempool data
• REST API: Exposes fee estimates through a simple HTTP endpoint

Getting Started

Prerequisites

• Java 17 or higher
• Access to a Bitcoin Node with RPC access (specifically, requires the getrawmempool and getblockchaininfo RPC methods)

Configuration

The application uses YAML for configuration with support for environment variable overrides.

Configuration Methods (in order of precedence)

1. Environment Variables: Highest priority
2. External Config File: Specified by AUGUR_CONFIG_FILE environment variable
3. Default Config: From config.yaml in resources

Configuration Options

Setting	Environment Variable	Default	Description
server.host	AUGUR_SERVER_HOST	0.0.0.0	HTTP server host
server.port	AUGUR_SERVER_PORT	8080	HTTP server port
bitcoinRpc.url	BITCOIN_RPC_URL	http://localhost:8332	Bitcoin Core RPC URL
bitcoinRpc.username	BITCOIN_RPC_USERNAME	(empty)	Bitcoin Core RPC username
bitcoinRpc.password	BITCOIN_RPC_PASSWORD	(empty)	Bitcoin Core RPC password
persistence.dataDirectory	AUGUR_DATA_DIR	mempool_data	Directory for storing mempool snapshots

Sample YAML Configuration

server:
  host: "0.0.0.0"
  port: 8080

bitcoinRpc:
  url: "http://localhost:8332"
  username: "rpcuser"
  password: "rpcpassword"

persistence:
  dataDirectory: "mempool_data"

Building

This project uses CashApp's Hermit. Hermit ensures that your team, your contributors, and your CI have the same consistent tooling. Here are the installation instructions.

Activate Hermit either by enabling the shell hooks (one-time only, recommended) or manually sourcing the env with . ./bin/activate-hermit.

Use gradle to run all tests:

bin/gradle build

Running the Application

Using Default Configuration

bin/gradle run

Using Environment Variables

BITCOIN_RPC_USERNAME=myuser BITCOIN_RPC_PASSWORD=mypassword bin/gradle run

Using External Config File

AUGUR_CONFIG_FILE=/path/to/my-config.yaml bin/gradle run

Using Docker

Alternatively, you can use Docker by first defining the bitcoinRpc username and password in the config.yaml file, and then using:

docker build -t bitcoin-augur-reference .
docker run -p 8080:8080 bitcoin-augur-reference

API Usage

Once running, the application exposes fee estimates at:

GET /fees

Example response:

{
  "mempool_update_time": "2025-03-03T19:13:50.043Z",
  "estimates": {
    "3": {
      "probabilities": {
        "0.05": {
          "fee_rate": 2.0916
        },
        "0.20": {
          "fee_rate": 3.0931
        },
        "0.50": {
          "fee_rate": 3.4846
        },
        "0.80": {
          "fee_rate": 4.0535
        },
        "0.95": {
          "fee_rate": 5.0531
        }
      }
    },
    "6": {
      "probabilities": {
        "0.05": {
          "fee_rate": 1.9631
        },
        "0.20": {
          "fee_rate": 2.9441
        },
        "0.50": {
          "fee_rate": 3.1191
        },
        "0.80": {
          "fee_rate": 3.4903
        },
        "0.95": {
          "fee_rate": 4.8708
        }
      }
    },
    "9": {
      "probabilities": {
        "0.05": {
          "fee_rate": 1.8778
        },
        "0.20": {
          "fee_rate": 2.8979
        },
        "0.50": {
          "fee_rate": 3.1154
        },
        "0.80": {
          "fee_rate": 3.4903
        },
        "0.95": {
          "fee_rate": 4.2041
        }
      }
    }
  }
}

Historical fee estimates at:

GET /historical_fee?timestamp=<unix_timestamp>

Example response:

{
  "mempool_update_time" : "2025-08-16T14:05:44.854Z",
  "estimates" : {
    "3" : {
      "probabilities" : {
        "0.05" : {
          "fee_rate" : 1.0
        },
        "0.20" : {
          "fee_rate" : 1.0
        },
        "0.50" : {
          "fee_rate" : 1.0
        },
        "0.80" : {
          "fee_rate" : 1.0
        },
        "0.95" : {
          "fee_rate" : 1.0
        }
      }
    },
    "6" : {
      "probabilities" : {
        "0.05" : {
          "fee_rate" : 1.0
        },
        "0.20" : {
          "fee_rate" : 1.0
        },
        "0.50" : {
          "fee_rate" : 1.0
        },
        "0.80" : {
          "fee_rate" : 1.0
        },
        "0.95" : {
          "fee_rate" : 1.0
        }
      }
    },
    "9" : {
      "probabilities" : {
        "0.05" : {
          "fee_rate" : 1.0
        },
        "0.20" : {
          "fee_rate" : 1.0
        },
        "0.50" : {
          "fee_rate" : 1.0
        },
        "0.80" : {
          "fee_rate" : 1.0
        },
        "0.95" : {
          "fee_rate" : 1.0
        }
      }
    }
  }
}

Local Development

If you'd like to use a local version of Augur within your reference implementation:

• Within Augur, run bin/gradle shadowJar to build a fat jar of Augur.
• Copy the file lib/build/libs/augur.jar into this reference implementation app/libs directory.
• Change implementation(libs.augur) to implementation(files("libs/augur.jar")) in the app/build.gradle.kts file.
• Within the reference implementation, run bin/gradle build to build the project with the local version of Augur.

Project Structure

• config: Configuration classes
• bitcoin: Bitcoin Core RPC client
• persistence: Mempool snapshot persistence
• service: Core application services
• api: API endpoints
• server: HTTP server setup

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.