Modular cryptocurrency libraries for Java, JVM languages, and Android. Including:
-
A Java JSON-RPC client that serves as a base class for any cryptocurrency platform that uses JSON-RPC for communication.
-
A Groovy JSON-RPC client that can use dynamic methods for scripting, experimentation and functional tests of any JSON-RPC server.
-
A JSON-RPC Java client for the Bitcoin Core API with strong, static types.
-
JSON library using Jackson to convert between Bitcoin types and JSON
-
bitcoinj types ←→ JSON (e.g. Address, Sha256Hash, Transaction)
-
Strongly-typed Java POJOs ←→ Bitcoin Core standard JSON (e.g. BlockChainInfo, UnspentOutput, ChainTip)
-
-
Spring and Guice-compatible Bitcoin server components for server-side JSON-RPC.
-
bitcoinj-proxy - A high-performance, non-blocking Ratpack server for proxying access to bitcoind or building Bitcoin-based microservices.
-
bitcoinj-daemon - A Spring Boot-based framework for a Java-based implementation of bitcoind.
-
bitcoinj-peerserver - A Spring Boot-based web application that connects to the Bitcoin P2P network and streams events to a browser using the STOMP protocol over WebSocket.
-
Bitcoin currency and exchange implementations for JavaMoney.
-
bitcoinj-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 bitcoinj-daemon) JSON-RPC services, that run in regression test mode.
|
|
Do not use this software with your private keys without doing a rigorous audit of the code first. (Feedback welcome.) |
|
|
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 first. |
This project is a mono-repo with a large number of 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 small, tight applications and servers. Most of these components are fairly new, but all are useful and ready for pull requests.
Although the API is changing, binary releases are available on Bintray. You can download JARs or use the provided Maven coordinates to link to them directly from your pom.xml or build.gradle.
We have published preliminary JavaDoc to our Github pages site.
ConsensusJ is used by OmniJ and is tested by the Omni Foundation Continuous Integration Server. There are also Travis CI and GitLab CI builds.
-
Omni Foundation Jenkins build: consensusj job (note: self-signed SSL certificate)
-
Travis CI build:
-
GitLab CI build:
-
All modules now require Java 8 (Android 7) or later.
-
The command-line tools/libraries now require Java 9 or later (and will require Java 11 or later after Issue #55: JavaDoc won’t build on JDK 11 is resolved.)
We are in the process of refactoring all modules into the new org.consensusj namespace. As part of this process, once all the packages in a module are under org.consensusj and there are no split packages, we are assigning JPMS module names via the "Automatic Module" mechanism. This results in a consistent package structure, easier usage by Java 9+, and a smooth migration to JPMS module descriptors.
The new modules also more clearly separate Java from Groovy, so the core Java modules have zero dependencies on Groovy JARs.
| Name | Min JDK | Java module name | Description |
|---|---|---|---|
8 |
|
JavaMoney Currency Provider(s) |
|
8 |
|
Preliminary, experimental, W3C DID and BTCR DID Method support |
|
8 |
|
JavaMoney Exchange Providers. Adapter to use XChange |
|
8 |
|
JSON-RPC client |
|
9 |
|
JSON-RPC command-line interface (CLI) libraries and tool |
|
consensusj-jsonrpc-daemon |
8 |
|
JSON-RPC Sample Server |
8 |
|
Groovy JSON-RPC client (dynamic RPC methods) |
|
9 |
not yet |
Command-line JSON-RPC client for Bitcoin |
|
8 |
not yet |
JSON-RPC Bitcoin server daemon prototype, using Micronaut. |
|
8 |
not yet |
Java JSON-RPC Bitcoin client |
|
8 |
not yet |
Groovy JSON-RPC Bitcoin client (dynamic RPC methods) |
|
8 |
not yet |
Bitcoin Service-Layer objects - compatible with |
|
8 |
not yet |
Java JSON-RPC Ethereum client (proof-of-concept) |
|
8 |
not yet |
Groovy JSON-RPC Ethereum client (dynamic RPC methods) |
|
8 |
not yet |
Namecoin daemon work-in-progress |
|
8 |
not yet |
Java JSON-RPC Namecoin client (proof-of-concept) |
|
8 |
not yet |
Groovy JSON-RPC Namecoin client (dynamic RPC methods) |
JavaMoney (also known as JSR 354) is the new Java Standard for advanced and flexible currency handling on the Java platform.
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.
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 XChange library to be used by JavaMoney-compatible applications.
Java implementation of a JSON-RPC client. RPCClient can be subclassed or called directly using the send() method and Object parameters.
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.
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 BitcoinClient to see the methods implemented.
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.
An alternative implementation of bitcoin-cli in Java. If converted to a fat jar, it is executable with java -jar. The command:
java -jar cj-btc-cli-0.5.4.jar -rpcport=8080 getblockcount
will output:
Connecting to: http://127.0.0.1:8080/ 0
|
ℹ️
|
Only a few RPCs are currently supported. Pull requests welcome. |
For help type:
java -jar bitcoinj-cli-0.5.4.jar -?
or read the manual page.
See the table below for an overview of the modules in the old com.msgilligan namespace.
The JDK column indicates the version of Java required.
The Grooviness column describes the use of the Groovy Programming Language within that module.
| Name | JDK | Grooviness | Description |
|---|---|---|---|
8 |
Optional + tests |
Bitcoin JSON-RPC integration tests |
|
8 |
Tests only (TBD) |
Jackson serializers, deserializers & POJOs for Bitcoin JSON-RPC |
|
8 |
Tests only (TBD) |
Ratpack-based server for proxying bitcoind and/or building microservices. |
|
8 |
Tests only (TBD) |
JSON-RPC Bitcoin server daemon — equivalent to |
|
8 |
Tests only (TBD) |
Peer and transaction info over HTTP + WebSocket/STOMP. JSON-RPC server, too. |
|
8 |
Uses Groovy |
Groovy DSL support. |
|
8 |
Spock is a Groovy DSL for unit tests |
Spock tests of bitcoinj classes. |
Most of the previous functionality of this module has been moved to the new org.consensusj modules. What remains is:
-
Bitcoin Core integration test framework and tests (Regression Tests using Spock)
-
A Namecoin (NMC) JSON-RPC Client
-
An Ethereum (ETH) JSON-RPC Client
The remaining classes will be refactored into 3 new org.consensusj modules.
These sample Spock "feature tests" show the RPC client in action and are from the file BitcoinSpec.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)
}Jackson serializers, deserializers & POJOs used to create and parse JSON by both client and server implementations of Bitcoin JSON-RPC.
Service-Layer objects that power the Daemon(s) and PeerServer. These objects rely solely on javax.annotation and javax.inject for configuration and can be wired with either Spring, Micronaut IOC, or Guice.
A starting point for building a complete bitcoind equivalent using bitcoinj. Currently serves a very small subset of the Bitcoin RPC API (Bitcoin uses JSON-RPC.)
Built as a fat, executable jar, so it can be run with java -jar.
An experimental port of bitcoinj-daemon to Micronaut.
PeerServer is a bitcoinj-powered Spring Boot application that provides the following functions:
-
A Bitcoin JSON-RPC service at
http://[host]:[port]/bitcoinrpc-
This is hard to connect to using
bitcoin-clias it expects the RPCs to be accessible at the root path ('/'), but you can use the Java RPC client or CLI tool to talk to it. -
There may be issues with the security configuration on this URL. We’re currently investigating.
-
-
A STOMP protocol WebSocket service that live-streams pending Bitcoin transactions from the P2P network.
-
The page at
/peers.htmllists connected peers and streams Transactions from the P2P network. -
You must login using username:
admin, password:adminto view this page. -
The `peers.html' page is currently unstyled HTML.
-
No bitcoind is required. The server uses a bitcoinj PeerGroup to connect directly to the Bitcoin network. I’m considering renaming it to PeerGroupServer for this reason. The JAR is entirely self-contained and can be run on any system with Java 8 with the java -jar peerserver-0.5.4.jar command.
A Ratpack-based proxy server that can proxy JSON-RPC commands to a connected bitcoind (or Omni Core) server. It can also be used as a starting point for JSON-RPC interoperable microservices.
Spock tests of bitcoinj classes. Initial focus is learning and documentation, not test coverage.
Before running ./gradlew wrapper script you must have JDK 8 installed and your JAVA_HOME set correctly. For example:
export JAVA_HOME=`/usr/libexec/java_home -v1.8`
|
ℹ️
|
The first time you run the build all dependency JARS will be downloaded. |
To build the CLI executable jar:
./gradlew :consensusj-jsonrpc-cli:shadowJar
To run it and display a list of command line options:
java -jar consensusj-jsonrpc-cli/build/libs/consensusj-jsonrpc-cli-0.5.4.jar -?
To build the CLI executable jar:
./gradlew :cj-btc-cli:shadowJar
To run it and display a list of command line options:
java -jar cj-btc-cli/build/libs/cj-btc-cli-0.5.4.jar -?
-
Build and Run with Gradle Wrapper
./gradlew :bitcoinj-peerserver:bootRun
|
ℹ️
|
This will connect to the Bitcoin P2P network |