/spring-boot-bitcoin-starter

Write enterprise Bitcoin applications with Spring Boot. Starter projects with multiple Bitcoin related modules that you can include in your application.

Primary LanguageJavaApache License 2.0Apache-2.0

Build Status Download License

Logo

spring-boot-bitcoin-starter

Write enterprise Bitcoin applications with Spring Boot.

Spring boot starter projects with convenient dependency descriptors for multiple Bitcoin related modules that you can include in your application. Strong focus on integration and regression testing your own application or module. Included are features for representing, transporting, and performing comprehensive calculations and tests with Bitcoin in financial applications and monetary computations.

Note: Most code is still experimental - do not use in production. This project is under active development. Pull requests and issues are welcome.

Table of Contents

Install

Simply define JitPack as an artifact repository and add the desired modules as dependencies. See spring-boot-bitcoin-starter on JitPack to find the most recent releases. The examples below import bitcoin-jsonrpc-client-starter but you can import any module by its name.

Gradle

repositories {
    maven {
        // needed for spring-boot-bitcoin-starter packages
        url 'https://jitpack.io'
    }
}
dependencies {
    implementation "com.github.theborakompanioni.spring-boot-bitcoin-starter:bitcoin-jsonrpc-client-starter:${springBootBitcoinStarterVersion}"
}

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>
<dependency>
    <groupId>com.github.theborakompanioni.spring-boot-bitcoin-starter</groupId>
    <artifactId>bitcoin-jsonrpc-client-starter</artifactId>
    <version>${springBootBitcoinStarter.version}</version>
</dependency>

Modules

bitcoin-jsonrpc-client

A module containing a spring boot starter for a ConsensusJ Bitcoin Core JSON-RPC API client. The starter will automatically create an autowireable BitcoinClient bean:

org.tbk.bitcoin.jsonrpc.client:
  enabled: true
  network: mainnet
  rpchost: http://localhost
  rpcport: 8332
  rpcuser: myrpcuser
  rpcpassword: 'myrpcpassword'

bitcoin-zeromq-client

A module containing a spring boot starter for a Bitcoin Core ZeroMq API client. The starter will automatically create autowireable ZeroMqMessagePublisherFactory beans for every zmq endpoint:

org.tbk.bitcoin.zeromq:
  network: mainnet
  zmqpubrawblock: tcp://localhost:28332
  zmqpubrawtx: tcp://localhost:28333
  zmqpubhashblock: tcp://localhost:28334
  zmqpubhashtx: tcp://localhost:28335

Also, if you have bitcoinj in the classpath, it will create a bean of type BitcoinjTransactionPublisherFactory and BitcoinjBlockPublisherFactory which will emit bitcoinj types for your convenience.

lnd-grpc-client

A module containing a spring boot starter for a Lightningj lnd gRPC API client. The starter will automatically create autowireable AsynchronousLndAPI and SynchronousLndAPI beans:

org.tbk.lightning.lnd.grpc:
  enabled: true
  rpchost: localhost
  rpcport: 10009
  macaroon-file-path: '/lnd/.lnd/data/chain/bitcoin/regtest/admin.macaroon'
  cert-file-path: '/lnd/.lnd/tls.cert'

bitcoin-fee

A generalized and extensible interface of multiple Bitcoin Fee Recommendation APIs. The following providers are available out of the box:

  • Bitcoin Core JSON-RPC Api (estimatestmartfee)
  • bitcoiner.live API
  • Bitgo API
  • Bitcore API
  • Blockchain.info API (deprecated - will be removed as it is not compatible with "block target" recommendations)
  • Blockchair API
  • BlockCypher API
  • Blockstream.info API
  • BTC.com API
  • earn.com API
  • mempool.space API

spring-xchange

A module containing a spring boot starter for automatically creating and configuring XChange beans! This starter makes it easy to fetch the current price of bitcoin, programmatically place orders, withdraw your bitcoin or manage your account!

org.tbk.xchange:
  enabled: true # whether auto-config should run - default is `true`
  specifications: # provide specifications for all exchange you want to use - default is empty (no beans created)
    krakenExchange:
      exchange-class: org.knowm.xchange.kraken.KrakenExchange
      api-key: 'your-api-key' # change this value to your api key
      secret-key: 'your-secret-key' #  change this value to your secret key

spring-tor

A module containing a spring boot starter for an embedded Tor daemon. The starter will automatically expose your application as hidden service!

org.tbk.tor:
  enabled: true  # whether auto-config should run - default is `true`
  auto-publish-enabled: true # auto publish the web port as hidden service - default is `true`
  working-directory: 'my-tor-directory' # the working directory for tor - default is `tor-working-dir`
  startup-timeout: 30s # max startup duration for tor to successfully start - default is `60s`

bitcoin-jsr354

Contains a JSR354 compliant CurrentyUnit implementation representing Bitcoin.

spring-jsr354

A module containing a spring boot starter for convenient handling of JSR354 beans. This module creates an application context aware JSR354 Service Provider (javax.money.spi.ServiceProvider) that provides beans in the application context to be used by JSR354 factories (javax.money.Monetary).

xchange-jsr354

A module containing a spring boot starter for integrating XChange in JSR354 currency conversions. Provides a javax.money.convert.ExchangeRateProvider implementation that uses org.knowm.xchange.Exchange beans to supply exchange rates from popular Bitcoin exchanges.

e.g.

CurrencyConversion btcToUsdConversion = MonetaryConversions.getConversion(ConversionQueryBuilder.of()
    .setBaseCurrency(Monetary.getCurrency("BTC"))
    .setTermCurrency(Monetary.getCurrency("USD"))
    .build());

Money singleBitcoin = Money.of(BigDecimal.ONE, "BTC");
Money singleBitcoinInUsd = singleBitcoin.with(btcToUsdConversion);

log.info("{} equals {}", singleBitcoin, singleBitcoinInUsd);
// e.g. "BTC 1.00 equals USD 13806.90"

spring-testcontainer

This module contains a fast and easy way to start one or multiple instances of external services within docker containers programmatically directly from your application. Please note, that these modules are intended to be used in regtest mode only.

Start and run:

Most of these spring boot starter modules contain a simple example application. They can be used in combination with other modules like bitcoin-jsonrpc-client, bitcoin-zeromq-client, lnd-grpc-client, etc.

incubator

This subproject is home to all almost-ready modules.

tbk-electrum-daemon-client

A module containing a spring boot starter for a Electrum daemon JSON-RPC API client. It can be used in combination with spring-testcontainer-electrum-daemon-starter!

Examples

Besides, that most starter modules also have their own example applications, there are also stand-alone example applications showing basic usage of the functionality provided by these modules.

Example apps can be started with a single command, e.g.:

./gradlew -p examples/lnd-playground-example-application bootRun

Development

Requirements

  • java >=11
  • docker

A Bitcoin Core Testcontainer running in regtest mode is started for most examples. Having access to a Bitcoin Core node running on mainnet is quite useful if you want to try everything. Optional: A node should publish rawtx and rawblock messages via zmq for some features to be working.

Build

./gradlew build -x test

Test

./gradlew test integrationTest

Tests in example application modules or modules that start a lot of docker containers (modules named "-example-application" or "spring-testcontainer-") are excluded from the default test phase and must be manually enabled if you want to run them. To run all tests you must pass -PexampleTest and -PtestcontainerTest:

./gradlew test integrationTest -PtestcontainerTest -PexampleTest

Be aware this might take several minutes to complete (>= 15 minutes).

Dependency Checks

# verifies checksums of dependencies
./gradlew verifyChecksums
# calculate checksums of dependencies
./gradlew -q calculateChecksums | grep -v "spring-boot-bitcoin-starter" > checksums.gradle

Contributing

All contributions and ideas are always welcome. For any question, bug or feature request, please create an issue. Before you start, please read the contributing guidelines.

Resources

License

The project is licensed under the Apache License. See LICENSE for details.