bitcoin-spring-boot-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 computations.

Hint: Of course you can make use of the libraries even if you are not working with Spring!

Note: Most code is still experimental - use with caution. This project is under active development. Pull requests and issues are welcome. Look at the changelog to track notable changes. Also, developing this project is fun.

Table of Contents

• Install
• Modules
• Examples
• Development
• Contributing
• Resources
• License

Install

Download from Maven Central.

Gradle

repositories {
    mavenCentral()
    maven {
        // needed for netlayer packages
        url "https://jitpack.io"
    }
    maven {
        // needed for consensusj
        url "https://gitlab.com/api/v4/projects/8482916/packages/maven"
    }
}

implementation "io.github.theborakompanioni:bitcoin-jsonrpc-client-starter:${bitcoinSpringBootStarterVersion}"

Maven

<dependency>
    <groupId>io.github.theborakompanioni</groupId>
    <artifactId>bitcoin-jsonrpc-client-starter</artifactId>
    <version>${bitcoinSpringBootStarter.version}</version>
</dependency>

The example above imports module bitcoin-jsonrpc-client-starter - you can import any module by its name.

Modules

This project contains various modules that can be integrated into your project depending on your requirements.

You can find a small selection in the following table. But there is much more to discover.

Module	Description
bitcoin-jsonrpc-client	Connect to Bitcoin Core via ConsensusJ Bitcoin Core JSON-RPC API client.
bitcoin-zeromq-client	Connect to Bitcoin Core via zmq.
bitcoin-regtest	Integration and regression testing your own application.
cln-grpc-client	Connect to cln via gRPC.
lnd-grpc-client	Connect to lnd via gRPC using LightningJ.
xchange-jsr354	Exchange rates from Bitcoin exchanges for your application.
spring-xchange	Automatically create and configure XChange beans. Remember to get your coins off of exchanges!
spring-tor	Automatically expose your application as Tor Hidden Service.
spring-lnurl	Spring Security configurations for authentication with lnurl-auth.

See modules.md for general information about specific modules.

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.

• bitcoin-autodca: Stacking Sats on Kraken: Auto DCA example application
• bitcoin-exchange-rate: Currency Conversion API example application
• ln-playground: Lightning Network Playground example application
• lnurl-auth: Spring Security Authentication with lnurl-auth example application

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

./gradlew -p incubator/spring-lnurl/spring-lnurl-auth-example-application bootRun --args="--spring.profiles.active=development --debug"

Development

Requirements

• java >=17
• 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 work.

Build

./gradlew build -x test

Test

./gradlew test integrationTest --rerun-tasks

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 pass arguments -PexampleTest and -PtestcontainerTest:

./gradlew test integrationTest -PtestcontainerTest -PexampleTest

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

Dependency Verification

Gradle is used for checksum and signature verification of dependencies.

# write metadata for dependency verification
./gradlew --write-verification-metadata pgp,sha256 --export-keys
# update buildscript dependency locks
./gradlew dependencies --write-locks

See Gradle Userguides Verifying dependencies and Locking dependency versions for more information.

Checkstyle

Checkstyle with adapted google_checks is used for checking Java source code for adherence to a Code Standard.

# check for code standard violations with checkstyle
./gradlew checkstyleMain --rerun-tasks

SpotBugs

SpotBugs is used for static code analysis.

# invoke static code analysis with spotbugs
./gradlew spotbugsMain --rerun-tasks

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

• Bitcoin: https://bitcoin.org/en/getting-started
• Lightning Network: https://lightning.network
• JSR354 (GitHub): https://github.com/JavaMoney/jsr354-api
• Spring Boot (GitHub): https://github.com/spring-projects/spring-boot
• Testcontainers (GitHub): https://github.com/testcontainers/testcontainers-java
• Tor: https://www.torproject.org

---

• Bitcoin Core (GitHub): https://github.com/bitcoin/bitcoin (Docker)
• bitcoin-kmp (GitHub): https://github.com/ACINQ/bitcoin-kmp
• bitcoinj (GitHub): https://github.com/bitcoinj/bitcoinj
• cln (GitHub): https://github.com/ElementsProject/lightning (Docker)
• lnd (GitHub): https://github.com/LightningNetwork/lnd (Docker)
• lnurl (GitHub): https://github.com/fiatjaf/lnurl-rfc
• LightningJ (GitHub): https://github.com/lightningj-org/lightningj
• cln gRPC client (GitHub): https://github.com/theborakompanioni/cln-grpc-client
• lightning-kmp (GitHub): https://github.com/ACINQ/lightning-kmp
• ElectrumX Server (GitHub): https://github.com/spesmilo/electrumx (Docker)
• Electrum Personal Server (GitHub): https://github.com/chris-belcher/electrum-personal-server (Docker)
• Electrum Client (GitHub): https://github.com/spesmilo/electrum (Docker)
• ConsensusJ (GitHub): https://github.com/ConsensusJ/consensusj
• JeroMq (GitHub): https://github.com/zeromq/jeromq
• jMolecules (GitHub): https://github.com/xmolecules/jmolecules
• springdoc-openapi (GitHub): https://github.com/springdoc/springdoc-openapi
• sqlite (GitHub): https://github.com/xerial/sqlite-jdbc
• Project Reactor (GitHub): https://github.com/reactor/reactor-core
• Protocol Buffers: https://developers.google.com/protocol-buffers
• XChange (GitHub): https://github.com/knowm/XChange

License

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