bitcoinj/README.adoc

image:https://github.com/bitcoinj/bitcoinj/workflows/Java%20CI/badge.svg[GitHub Build Status,link=https://github.com/bitcoinj/bitcoinj/actions]
image:https://gitlab.com/bitcoinj/bitcoinj/badges/master/pipeline.svg[GitLab Build Status,link=https://gitlab.com/bitcoinj/bitcoinj/-/pipelines]
image:https://coveralls.io/repos/bitcoinj/bitcoinj/badge.png?branch=master[Coverage Status,link=https://coveralls.io/r/bitcoinj/bitcoinj?branch=master]

image::https://img.shields.io/badge/chat-Join%20bitcoinj--users%20on%20Matrix-blue[Join the bitcoinj-users Matrix room, link=https://matrix.to/#/#bitcoinj-users:matrix.org]

### 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`
* https://gradle.org/[Gradle]
** Gradle 7.3+ for building the whole project or
** Debian Gradle 4.4 for just the `base`, `core`, `tools`, `wallettool` and `examples` modules (see "reference build" below)
* https://github.com/google/protobuf[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. http://www.jetbrains.com/idea/download/[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 https://bitcoinj.github.io/getting-started[follow the tutorial].

### Testing a SNAPSHOT build

Building apps with official releases of *bitcoinj* is covered in the https://bitcoinj.github.io/getting-started[tutorial].

If you want to develop or test your app with a https://jitpack.io[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.

* https://jitpack.io/#bitcoinj/bitcoinj/master-SNAPSHOT[master] branch
* https://jitpack.io/#bitcoinj/bitcoinj/release-0.17-SNAPSHOT[release-0.17] branch