Welcome to bitcoinj

The bitcoinj library is a Java implementation of the Bitcoin protocol, which allows it to maintain a wallet and send/receive transactions without needing a local copy of Bitcoin Core. It comes with full documentation and some example apps showing how to use it.

Technologies

• Java 8+ (needs Java 8 API or Android 8.0 API, compiles to Java 8 bytecode) for base and core module

• Java 17+ for tools, wallettool, examples and the JavaFX-based wallettemplate

• Gradle

  • Gradle 8.5+ for building the whole project or

  • Debian Gradle 4.4 for just the base, core, tools, wallettool and examples modules (see "reference build" below)

• Google Protocol Buffers - for use with serialization and hardware communications

Getting started

To get started, it is best to have the latest JDK and Gradle installed. The HEAD of the master branch contains the latest development code and various production releases are provided on feature branches.

Building from the command line

Official builds are currently using JDK 17. Our GitHub Actions build and test with JDK 17 and 21.

gradle clean build

The outputs are under the build directory.

To perform a full build without unit/integration tests use:

gradle clean assemble

Building from an IDE

Alternatively, just import the project using your IDE. IntelliJ has Gradle integration built-in and has a free Community Edition. Simply use File | New | Project from Existing Sources and locate the build.gradle in the root of the cloned project source tree.

Building and Using the Wallet Tool

The bitcoinj wallettool subproject includes a command-line Wallet Tool (wallet-tool) that can be used to create and manage bitcoinj-based wallets (both the HD keychain and SPV blockchain state.) Using wallet-tool on Bitcoin’s test net is a great way to learn about Bitcoin and bitcoinj.

To build an executable shell script that runs the command-line Wallet Tool, use:

gradle bitcoinj-wallettool:installDist

You can now run the wallet-tool without parameters to get help on its operation:

./wallettool/build/install/wallet-tool/bin/wallet-tool

To create a test net wallet file in ~/bitcoinj/bitcoinj-test.wallet, you would use:

mkdir ~/bitcoinj

./wallettool/build/install/wallet-tool/bin/wallet-tool --net=TESTNET --wallet=$HOME/bitcoinj/bitcoinj-test.wallet create

To sync the newly created wallet in ~/bitcoinj/bitcoinj-test.wallet with the test net, you would use:

./wallettool/build/install/wallet-tool/bin/wallet-tool --net=TESTNET --wallet=$HOME/bitcoinj/bitcoinj-test.wallet sync

To dump the state of the wallet in ~/bitcoinj/bitcoinj-test.wallet with the test net, you would use:

./wallettool/build/install/wallet-tool/bin/wallet-tool --net=TESTNET --wallet=$HOME/bitcoinj/bitcoinj-test.wallet dump

Note	These instructions are for macOS/Linux, for Windows use the wallettool/build/install/wallet-tool/bin/wallet-tool.bat batch file with the equivalent Windows command-line commands and options.

Building and Running the Wallet Template

The bitcoinj wallettemplate subproject includes a template JavaFX wallet application (bitcoinj-wallettemplate) that can be used as a starting point for building a JavaFX-based bitcoinj wallet application.

To build an executable shell script that runs the wallettemplate, use:

gradle bitcoinj-wallettemplate:installDist

You can now run bitcoinj-wallettemplate to launch the application:

./wallettemplate/build/install/bitcoinj-wallettemplate/bin/bitcoinj-wallettemplate

NOTE: On Windows, use `bitcoinj-wallettemplate.bat`.

You can also use jlink to build and run the application with a bundled JVM runtime:

gradle bitcoinj-wallettemplate:jlink
./wallettemplate/build/image/bin/bitcoinj-wallettemplate

Building the reference build

Our reference build (which is also used for our releases) is running within a container to provide good reproducibility. Buildah 1.26+, Podman 4.1+ and Docker (with BuildKit) are supported. We tested various combinations of host OSes (Debian, Ubuntu, macOS, Windows+WSL) and architectures (amd64, arm64). For usage instructions see build.Containerfile.

This uses Debian Gradle with the settings-debian.gradle settings. If you happen to use Debian and have Gradle installed from the Debian repository, you can invoke these settings directly:

gradle --settings-file settings-debian.gradle clean build

Example applications

These are found in the examples module.

Where next?

Now you are ready to follow the tutorial.

Testing a SNAPSHOT build

Building apps with official releases of bitcoinj is covered in the tutorial.

If you want to develop or test your app with a Jitpack-powered build of the latest master or release-0.17 branch of bitcoinj follow the dynamically-generated instructions for that branch by following the correct link.

• master branch

• release-0.17 branch