README.adoc

April 28, 2026 ยท View on GitHub

= ConsensusJ Sean Gilligan https://github.com/msgilligan v0.7.0-beta2 :description: ConsensusJ README document. :consensusj-version: 0.7.0-beta2 :bitcoinj-version: 0.17.1 :bitcoinj-apidoc: https://bitcoinj.org/javadoc/{bitcoinj-version}/ :cj-apidoc: https://consensusj.github.io/consensusj/apidoc :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning:

image:https://github.com/ConsensusJ/consensusj/workflows/Build/badge.svg["GitHub Actions Build", link="https://github.com/ConsensusJ/consensusj/actions/workflows/build.yml"] image:https://gitlab.com/ConsensusJ/consensusj/badges/master/pipeline.svg[link="https://gitlab.com/ConsensusJ/consensusj/pipelines",title="pipeline status"] image:https://img.shields.io/matrix/consensusj:matrix.org?logo=matrix&label=ConsensusJ[link="https://matrix.to/#/#consensusj:matrix.org"]

Modular Bitcoin component libraries for Java, JVM languages, and Android. (Some of the core libraries, such as the base JSON-RPC client may be useful for other applications.)

== Features

=== Core JSON-RPC Features

  • A Java JSON-RPC client for any JSON-RPC server.
  • A Groovy JSON-RPC client that can use dynamic methods for scripting, experimentation and functional testing of any JSON-RPC server.
  • jrpc: A JSON-RPC command-line client for testing and debugging JSON-RPC servers and applications. It can be natively compiled with https://www.graalvm.org[GraalVM]. It can launch, call the server and print output in under 50 milliseconds.
  • jrpc-echod: A Micronaut-based JSON-RPC echo server. It can be natively compiled using https://www.graalvm.org[GraalVM].

=== Bitcoin Features

  • A JSON-RPC Java client for the https://bitcoin.org/en/developer-reference#bitcoin-core-apis[Bitcoin Core API] with strong, static types.
  • JSON library using https://github.com/FasterXML/jackson[Jackson] to convert between Bitcoin types and JSON ** bitcoinj types <--> JSON (e.g. {bitcoinj-apidoc}/org/bitcoinj/core/Address.html[Address], {bitcoinj-apidoc}/org/bitcoinj/core/Sha256Hash.html[Sha256Hash], {bitcoinj-apidoc}/org/bitcoinj/core/Transaction.html[Transaction]) ** Strongly-typed {cj-apidoc}/org/consensusj/bitcoin/json/pojo/package-summary.html[Java POJOs] <--> Bitcoin Core standard JSON (e.g. {cj-apidoc}/org/consensusj/bitcoin/json/pojo/BlockChainInfo.html[BlockChainInfo], {cj-apidoc}/org/consensusj/bitcoin/json/pojo/UnspentOutput.html[UnspentOutput], {cj-apidoc}/org/consensusj/bitcoin/json/pojo/ChainTip.html[ChainTip])
  • jakarta.inject-compatible Bitcoin server components for server-side JSON-RPC.
  • walletd: A lightweight, SPV-based subset of bitcoind. It can be natively compiled using https://www.graalvm.org[GraalVM].
  • cj-btc-cli - a command line tool and supporting libraries for accessing the JSON-RPC API.
  • A Groovy-language Domain Specific Language for scripting and testing with bitcoinj
  • Functional tests of bitcoind (and walletd) JSON-RPC services, that run in https://bitcoinj.org/testing#regression-test-mode[regression test mode].

=== JavaMoney and Exchange Support

WARNING: Do not use this software with your private keys without doing a rigorous audit of the code first. (Feedback welcome.)

WARNING: The API is not final and prior to a 1.0 release may change without warning. Most of the API changes are fairly manageable though, and we try to deprecate before making significant changes.

=== Many small modules to help you manage dependencies

This project is a mono-repo with many submodules/components that are published as independent binary libraries. Since it is easy to pull in just the modules you need via Maven coordinates, this allows you to manage your transitive dependencies and build lightweight, fast-starting, applications and servers. Fewer dependencies also helps with natively-compiled, Java Module System-based (including jlink) applications.

== Overview

=== Binaries

Although the API is changing, binary packages are available on https://gitlab.com/ConsensusJ/consensusj/-/packages[GitLab.com]. You can download JARs or use the provided Maven coordinates to link to them directly from your pom.xml or build.gradle.

=== Nix Package

An experimental Nix Package which includes:

  1. A natively-compiled binary jrpc JSON-RPC tool.
  2. A JVM-based jrpc-echod tool.
  3. A JVM-based walletd tool.

You can install these tools with Nix, via:

nix profile install github:ConsensusJ/consensusj#consensusj-tools

Once installed:

jrpc --help

Create ~/.config/jrpc/config.toml with your local Bitcoin (or other JSON-RPC) servers.

For example:

[default] bitcoin-network = "regtest" uri = "http://localhost:18443" username = "xx" password = "yy"

[btcmain] bitcoin-network = "main" uri = "http://localhost:8332" username = "aa" password = "bb"

jrpc help # Get RPC help from default server jrpc -c btcmain help # Get RPC help from 'btcmain' in 'config.toml'

The jrpc-echod and walletd tools do not currently have help and are mainly used for integration testing.

==== Maven

Add the following to your pom.xml:

[source]

consensusj-gitlab-maven https://gitlab.com/api/v4/projects/8482916/packages/maven ----

==== Gradle

Add the following to the repositories section of your build.gradle:

[source]

maven { url 'https://gitlab.com/api/v4/projects/8482916/packages/maven' }

=== API Documentation

We have published {cj-apidoc}/index.html[preliminary JavaDoc] to our GitHub pages site.

=== Continuous Integration

// Jenkins Widget doesn't display correctly because of ci.omni.foundation self-signed SSL // image:https://ci.omni.foundation/buildStatus/icon?job=consensusj[link="https://ci.omni.foundation/job/consensusj/"]

//* Omni Foundation Jenkins build: https://ci.omni.foundation/job/consensusj/[consensusj job] (note: self-signed SSL certificate)

=== Requirements

  • Most modules now require Java 11 or later.
  • bitcoinj-util and bitcoinj-dsl-gvy still work with JDK 9
  • The server libraries and daemons require Java 17 or later.
  • The command-line tools/libraries require Java 21 or later.

=== ConsensusJ Modules

We have completed refactoring all modules into the new org.consensusj package namespace and have assigned Java Module names via the Automatic Module mechanism. This provides a more consistent package structure and a smooth migration to Java Module descriptors.

.Core JSON-RPC Modules [cols="4,1,3,4"] |=== |Name |Min JDK |Java module name |Description

|<<consensusj-jrpc,consensusj-jrpc>> | 21 | org.consensusj.jrpc | The jrpc JSON-RPC command-line tool

|<<consensusj-jsonrpc,consensusj-jsonrpc>> | 11 | org.consensusj.jsonrpc | JSON-RPC clients: one using java.net.http and one legacy.

|<<consensusj-jsonrpc-gvy,consensusj-jsonrpc-gvy>> | 11 | org.consensusj.jsonrpc.groovy | Groovy JSON-RPC client (dynamic RPC methods)

|consensusj-jsonrpc-cli | 21 | org.consensusj.jsonrpc.cli | JSON-RPC command-line interface libraries

|<<consensusj-jrpc-echod, consensusj-jrpc-echod>> | 17 | n/a | JSON-RPC Sample Server

|consensusj-rx-jsonrpc | 11 | org.consensusj.rx.jsonrpc | RxJava 3 support for JSON-RPC

|consensusj-rx-zeromq | 11 | org.consensusj.rx.zeromq | RxJava 3 ZeroMQ client

|===

.Bitcoin Modules [cols="4,1,3,4"] |=== |Name |Min JDK |Java module name |Description

|<<cj-btc-json,cj-btc-json>> | 11 | org.consensusj.bitcoin.json |Jackson serializers, deserializers & POJOs for Bitcoin JSON-RPC

|<<cj-btc-jsonrpc,cj-btc-jsonrpc>> | 11 | org.consensusj.bitcoin.jsonrpc | Java JSON-RPC Bitcoin client

|<<cj-btc-jsonrpc-gvy,cj-btc-jsonrpc-gvy>> | 11 | org.consensusj.bitcoin.jsonrpc.groovy | Groovy JSON-RPC Bitcoin client (dynamic RPC methods)

|<<cj-btc-cli,cj-btc-cli>> | 21 | org.consensusj.bitcoin.cli | Command-line JSON-RPC client for Bitcoin

|<<cj-btc-walletd,cj-btc-walletd>> | 17 | n/a |JSON-RPC Bitcoin server daemon prototype, using Micronaut.

|<<cj-btc-services,cj-btc-services>> | 17 | org.consensusj.bitcoin.services | Bitcoin Service-Layer objects - compatible with jakarta.inject (https://jcp.org/en/jsr/detail?id=330[JSR-330])

|<<cj-btc-jsonrpc-integ-test,cj-btc-jsonrpc-integ-test>> | 17 |n/a |Bitcoin JSON-RPC integration tests (RegTest)

|cj-btc-rx | 11 |org.consensusj.bitcoin.rx |Reactive interfaces for Bitcoin.

|cj-btc-rx-jsonrpc | 11 |org.consensusj.bitcoin.rx.jsonrpc |RxJava 3 JSON-RPC/ZeroMQ Client for Bitcoin Core

|cj-btc-rx-peergroup | 11 |org.consensusj.bitcoin.rx.peergroup |RxJava 3 JSON-RPC/ZeroMQ Client using bitcoinj PeerGroup

|===

.bitcoinj Enhancement Modules [cols="4,1,3,4"] |=== |Name |Min JDK |Java module name |Description

|<<cj-bitcoinj-dsl-gvy,cj-bitcoinj-dsl-gvy>> | 9 |org.consensusj.bitcoinj.dsl.groovy |Groovy DSL support.

|cj-bitcoinj-dsl-js | 17 |org.consensusj.bitcoinj.dsl.js |JavaScript DSL support for Nashorn. Includes JSON-RPC client.

|<<cj-bitcoinj-spock,cj-bitcoinj-spock>> | 17 |org.consensusj.bitcoinj.spock |https://spockframework.org[Spock] tests of bitcoinj classes.

|cj-bitcoinj-util | 9 |org.consensusj.bitcoinj.util |bitcoinj utilities and enhancements. Some will be submitted upstream.

|===

.JavaMoney and Exchange Rate Support [cols="4,1,3,4"] |=== |Name |Min JDK |Java module name |Description

|<<consensusj-currency,consensusj-currency>> | 11 | org.consensusj.currency | http://javamoney.github.io[JavaMoney] Currency Provider(s)

|<<consensusj-exchange,consensusj-exchange>> | 11 | org.consensusj.exchange | http://javamoney.github.io[JavaMoney] Exchange Providers. Adapter to use http://knowm.org/open-source/xchange/[XChange] Exchange implementations as JavaMoney ExchangeRateProviders.

|===

.Miscellaneous Modules [cols="4,1,3,4"] |=== |Name |Min JDK |Java module name |Description

|consensusj-analytics | 11 | org.consensusj.analytics | Rich-list calculation support

|===

[#consensusj-jsonrpc] ==== consensusj-jsonrpc

Java implementation of a JSON-RPC client. {cj-apidoc}/org/consensusj/jsonrpc/JsonRpcClientHttpUrlConnection.html[JsonRpcClientHttpUrlConnection] can be subclassed or called directly using the send() method and Object parameters.

[#consensusj-jsonrpc-gvy] ==== consensusj-jsonrpc-gvy

Dynamic RPC methods are implemented via the DynamicRPCFallback Groovy trait. DynamicRPCClient can be used to talk to any JSON-RPC server using standard Java types and Jackson JSON conversion.

[#cj-btc-jsonrpc] ==== cj-btc-jsonrpc

Java Bitcoin JSON-RPC client and supporting types, both bitcoinj types and POJOs for Bitcoin Core JSON.

If the RPC procedure takes a Bitcoin address as parameter, then the Java method will take an org.bitcoinj.core.Address. If the RPC returns a transaction, the Java method will return an org.bitcoinj.core.Transaction.

See the JavaDoc for {cj-apidoc}/org/consensusj/bitcoin/rpc/BitcoinClient.html[BitcoinClient] to see the methods implemented.

[#cj-btc-jsonrpc-gvy] ==== cj-btc-jsonrpc-gvy

Subclass of Bitcoin JSON-RPC client with fallback to dynamic methods (using DynamicRPCFallback). This is useful when new methods are added to the server/protocol and static methods and types haven't been written for them yet.

[#cj-btc-cli] ==== cj-btc-cli: An Bitcoin RPC command-line client

An alternative implementation of bitcoin-cli in Java. If converted to a fat jar, it is executable with java -jar. The command:

[subs="attributes"] java -jar cj-btc-cli-{consensusj-version}.jar -rpcport=8080 getblockcount

will output:

Connecting to: http://127.0.0.1:8080/
0

NOTE: Only a few RPCs are currently supported. Pull requests welcome.

For help type:

[subs="attributes"] java -jar bitcoinj-cli-{consensusj-version}.jar -?

or read the https://consensusj.github.io/consensusj/manpage-cj-bitcoin-cli.html[manual page].

[#cj-btc-json] ==== cj-btc-json

https://github.com/FasterXML/jackson/wiki[Jackson] serializers, deserializers & POJOs used to create and parse JSON by both client and server implementations of Bitcoin JSON-RPC.

[#cj-btc-services] ==== cj-btc-services

Service-Layer object(s) that power the Daemon. These objects rely solely on https://docs.oracle.com/javase/8/docs/api/javax/annotation/package-summary.html[javax.annotation] and https://jakarta.ee/specifications/dependency-injection/2.0/apidocs/jakarta/inject/package-summary.html[jakarta.inject] for configuration and can be wired with Spring, https://docs.micronaut.io/latest/guide/index.html#ioc[Micronaut IOC], or https://github.com/google/guice[Guice].

Built as a fat, executable jar, so it can be run with java -jar.

[#cj-btc-walletd] ==== bitcoinj and SPV-based Bitcoin daemon

A proof-of-concept, bitcoinj-SPV-based Bitcoin daemon using the https://micronaut.io[Micronaut] framework.

A very limited and incomplete bitcoind equivalent using bitcoinj. It currently serves a small subset of the https://bitcoin.org/en/developer-reference#remote-procedure-calls-rpcs[Bitcoin RPC API] (Bitcoin uses http://www.jsonrpc.org[JSON-RPC].)

It builds as a native binary using GraalVM.

[#cj-bitcoinj-dsl-gvy] ==== cj-bitcoinj-dsl-gvy

Groovy DSL support to write things like:

assert 1.btc == 100_000_000.satoshi

and

assert 100.satoshi == Coin.MICROCOIN

[#cj-bitcoinj-spock] === cj-bitcoinj-spock

https://github.com/spockframework/spock/blob/master/README.md[Spock] tests of bitcoinj classes. Initial focus is learning and documentation, not test coverage.

[#cj-btc-jsonrpc-integ-test] ==== cj-btc-jsonrpc-integ-test: RegTest mode integration tests using JSON-RPC

Bitcoin Core integration test framework and tests (Regression Tests using Spock)

===== Sample Spock Integration Tests

These sample Spock "feature tests" show the RPC client in action and are from the file https://github.com/ConsensusJ/consensusj/blob/master/cj-btc-jsonrpc-integ-test/src/integ/groovy/org/consensusj/bitcoin/rpc/BitcoinSpec.groovy#L45-L73[BitcoinSpec.groovy].

[source,groovy]

def "Use RegTest mode to generate a block upon request"() {
    given: "a certain starting height"
    def startHeight = blockCount

    when: "we generate 1 new block"
    generateBlock()

    then: "the block height is 1 higher"
    blockCount == startHeight + 1
}

def "When we send an amount to a newly created address, it arrives"() {
    given: "A new, empty Bitcoin address"
    def destinationAddress = getNewAddress()

    when: "we send it testAmount (from coins mined in RegTest mode)"
    sendToAddress(destinationAddress, testAmount, "comment", "comment-to")

    and: "we generate 1 new block"
    generateBlock()

    then: "the new address has a balance of testAmount"
    testAmount == getReceivedByAddress(destinationAddress)
}

[#consensusj-currency] ==== consensusj-currency

http://javamoney.github.io[JavaMoney] (also known as http://javamoney.github.io/api.html[JSR 354]) is the new Java Standard for advanced and flexible currency handling on the Java platform.

[quote, JavaMoney Web Site] JSR 354 provides a portable and extensible framework for handling of Money & Currency. The API models monetary amounts and currencies in a platform independent and portable way, including well-defined extension points.

Support for virtual currencies is one of the key design goals in the specification. The consensusj-currency module allows Bitcoin to be used by standard Java APIs in the same ways as fiat currencies.

consensusj-currency contains BitcoinCurrencyProvider which will add "BTC" as a standard currency code to any applications that includes the consensusj-currency JAR in its classpath.

[#consensusj-exchange] ==== consensusj-exchange

The JavaMoney Reference Implementation (aka "Moneta") contains implementations of ExchangeRateProvider for ECB (European Central Bank) and IMF (International Monetary Fund). There is also U.S. FRB (Federal Reserve Bank) and Yahoo Finance ExchangeRateProvider in the JavaMoney financial library add-on module.

The #consensusj-exchange module includes an adapter class BaseXChangeExchangeRateProvider that adapts implementations of the Exchange interface in the popular and complete http://knowm.org/open-source/xchange/[XChange] library to be used by JavaMoney-compatible applications.

== Building and Running

Before running ./gradlew wrapper script you must have JDK 21 or later (JDK 25 is recommended) installed and your JAVA_HOME set correctly. To build native images you'll need a GraalVM JDK 25 or later and GRAALVM_HOME set correctly.

=== Full Build

./gradlew build

[#consensusj-jrpc] === Build jrpc, the JSON-RPC Command-Line Tool

To build the JSON-RPC CLI tool native image jrpc:

./gradlew :consensusj-jrpc:nativeCompile

To run it and display a list of command line options:

./consensusj-jrpc/build/jrpc --help

[#consensusj-jrpc-echod] === Build and Run JSON-RPC Echo Daemon

To build and run from Gradle:

./gradlew :consensusj-jrpc-echod:run

To build an "installable" JVM application and run:

./gradlew :consensusj-jrpc-echod:installDist
./consensusj-jrpc-echod/build/install/jrpc-echod/bin/jrpc-echod

To build a native image and run:

./gradlew :consensusj-jrpc-echod:nativeCompile
./consensusj-jrpc-echod/build/native/nativeCompile/jrpc-echod

=== Build and Run JSON-RPC Bitcoin Daemon

To build and run from Gradle:

./gradlew :cj-btc-walletd:run --args="-walletd.config.network-id=testnet"

To build an "installable" JVM application and run:

./gradlew :cj-btc-walletd:installDist
./cj-btc-walletd/build/install/walletd/bin/walletd -walletd.config.network-id=testnet

(The native-image build of walletd is still in need of fine-tuning.)