= ConsensusJ Sean Gilligan https://github.com/msgilligan v0.7.0-alpha3 :description: ConsensusJ README document. :consensusj-version: 0.7.0-alpha3 :bitcoinj-version: 0.17-alpha2 :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

Bitcoin currency provider implementation for http://javamoney.github.io[JavaMoney].
Multi-currency exchange "ticker" implementations using http://javamoney.github.io[JavaMoney] and http://knowm.org/open-source/xchange/[XChange].

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:

A natively-compiled binary jrpc JSON-RPC tool.
A JVM-based jrpc-echod tool.
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]

<repositories> <repository> <id>consensusj-gitlab-maven</id> <url>https://gitlab.com/api/v4/projects/8482916/packages/maven</url> </repository> </repositories> ----

==== 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

GitHub Actions: image:https://github.com/ConsensusJ/consensusj/workflows/Build/badge.svg["GitHub Actions Build", link="https://github.com/ConsensusJ/consensusj/actions/workflows/build.yml"]
GitLab CI: image:https://gitlab.com/ConsensusJ/consensusj/badges/master/pipeline.svg[link="https://gitlab.com/ConsensusJ/consensusj/pipelines",title="pipeline status"]

// 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.

|<<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

|===

|<<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

|===

|<<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.

|===

Consensusj

Install / Use

README

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

Once installed:

jrpc --help

For example:

[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'

[source]

[source]