Skip to content

Latest commit

 

History

History
313 lines (199 loc) · 14.3 KB

README.adoc

File metadata and controls

313 lines (199 loc) · 14.3 KB
Raw

  • WE ARE NOT CURRENTLY USING IT

ConensusJ (formerly bitcoinj-addons)

Sean Gilligan https://github.com/msgilligan v0.2.6 :description: ConensusJ README document. :consensusj-version: 0.2.6 :bitcoinj-version: 0.14.5 :tip-caption: :bulb: :note-caption: :information_source: :important-caption: :heavy_exclamation_mark: :caution-caption: :fire: :warning-caption: :warning:

Build Status download

Cryptocurrency libraries based on bitcoinj, including:

  • A JSON-RPC Java client for the Bitcoin Core API

  • JSON library using Jackson to convert between Bitcoin types and JSON

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

Warning
 Do not use this software with your Bitcoin private keys without doing a rigorous audit of the code. (Feedback welcome.)
Warning
 The API is not final and may change without warning (we try to deprecate first).

We’re hoping that one or more modules will be accepted into the bitcoinj project. Most of these components are fairly new, but all are useful and ready for pull requests.

Overview

Binaries download

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.

API Documentation

We have published preliminary JavaDoc to our Github pages site.

Continuous Integration

ConsensusJ is used by OmniJ and is tested by the Omni Foundation Continuous Integration Server (self-signed SSL certificate). You can check the bitcoinj-addons job for build status.

There is also a Travis CI build: Build Status

Requirements

  • Most modules use JDK 7 (subset) for Android compatibility (see table, below)

  • Server modules and Spring Boot Apps require JDK 8 or later

Modules

See the table below for an overview of the modules. The JDK column indicates the version of Java required. The Grooviness column describes the use of the Groovy Programming Language within that module.

Table 1. Modules
Name JDK Grooviness Description

bitcoinj-cli

7

Tests only

Command line RPC tool and CLI support/utility classes

bitcoinj-rpcclient

7

Optional + tests

Bitcoin JSON-RPC client

bitcoinj-json

7

Tests only (TBD)

Jackson serializers, deserializers & POJOs for Bitcoin JSON-RPC

bitcoinj-server

8

Tests only (TBD)

Service objects used by the server apps

bitcoinj-proxy

8

Tests only (TBD)

Ratpack-based server for proxying bitcoind and/or building microservices.

bitcoinj-daemon

8

Tests only (TBD)

JSON-RPC bitcoin server daemon — to replace bitcoind someday ;)

bitcoinj-peerserver

8

Tests only (TBD)

Peer and transaction info over HTTP + WebSocket/STOMP. JSON-RPC server, too.

bitcoinj-money

7

Tests only (TBD)

JavaMoney currency and exchange support. Adapter to use XChange Exchange implementations as JavaMoney `ExchangeRateProvider`s.

bitcoinj-dsl

7

Uses Groovy

Groovy DSL support.

bitcoinj-spock

7

Spock is a Groovy DSL for unit tests

Spock tests of bitcoinj classes.

bitcoinj-cli: An Bitcoin RPC command-line client

An alternative implementation of bitcoin-cli in Java. Built as a fat jar executable with java -jar. The command:

java -jar bitcoinj-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:

java -jar bitcoinj-cli-{consensusj-version}.jar -?

or read the manual page.

bitcoinj-rpcclient: A Bitcoin JSON-RPC client using bitcoinj types

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.

Sample Spock Integration Tests

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

bitcoinj-json

Jackson serializers, deserializers & POJOs used to create and parse JSON by both client and server implementations of Bitcoin JSON-RPC.

bitcoinj-server

Service objects that power the Daemon and PeerServer. Some objects, such as PeerGroupService, rely solely on javax.annotation and javax.inject for configuration and can be wired with either Spring or (in theory) Guice. The current focus is on Spring Boot, but we’re hoping to build a Ratpack server in the future.

bitcoinj-daemon

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

Uses a PeerGroup to power the limited RPCs. Will use a BlockStore. (Pull requests welcome.)

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

bitcoinj-peerserver

PeerServer is a bitcoinj-powered Spring Boot application that provides the following functions:

  1. A Bitcoin JSON-RPC service at http://[host]:[port]/bitcoinrpc

    1. This is hard to connect to using bitcoin-cli as 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.

    2. There may be issues with the security configuration on this URL. We’re currently investigating.

  2. A STOMP protocol WebSocket service that live-streams pending Bitcoin transactions from the P2P network.

    1. The page at /peers.html lists connected peers and streams Transactions from the P2P network.

    2. You must login using username: admin, password: admin to view this page.

    3. 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-{consensusj-version}.jar command.

bitcoinj-proxy

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.

bitcoinj-money

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 extendible 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.
— JavaMoney Web Site

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

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.

bitcoinj-money contains BitcoinCurrencyProvider which will add "BTC" as a standard currency code to any applications including the bitcoinj-money JAR in its classpath. and "BTC" will be available to your applications.

The bitcoinj-money module also includes an adapter class BaseXChangeExchangeRateProvider that along with a 1-line subclass adapts implementations of the Exchange interface in the popular and complete XChange library to be used by JavaMoney-compatible applications.

bitcoinj-dsl

Groovy DSL support to write things like:

assert 1.btc == 100_000_000.satoshi
and
assert 100.satoshi == Coin.MICROCOIN

bitcoinj-spock

Spock tests of bitcoinj classes. Initial focus is learning and documentation, not test coverage.

Building and Running

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`
Note
 The first time you run the build all dependency JARS will be downloaded.

Full Build

./gradlew build

Build CLI tool

To build the CLI executable jar:

./gradlew :bitcoinj-cli:shadowJar

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

java -jar bitcoinj-cli/build/libs/bitcoinj-cli-{consensusj-version}.jar -?

Build and Run PeerServer Locally Using Gradle

  1. Build and Run with Gradle Wrapper

    ./gradlew :bitcoinj-peerserver:bootRun
Note
 This will connect to the Bitcoin P2P network

Build an Executable JAR

./gradlew :bitcoinj-peerserver:assemble

The JAR will be built at build/libs/peerserver-{consensusj-version}.jar and can be run with:

java -jar bitcoinj-peerserver/build/libs/peerserver-{consensusj-version}.jar