Skip to content

OmniLayer/OmniJ

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.

OmniJ Project

Warning
This software is EXPERIMENTAL software for REGTEST and TESTNET TRANSACTIONS only. USE ON MAINNET AT YOUR OWN RISK.
Caution
This is pre-release software and APIs may change without notice.

OmniJ

Build Status Build Status Build Status

A Java/JVM implementation of the Omni Layer, an open-source, fully decentralized asset creation platform built on the Bitcoin blockchain.

There are currently ten active subprojects of OmniJ. Each of which builds a JAR artifact. Most JARs require JDK 8 or later, and others require JDK 11 or later.

module Description JDK Notes

omnij-cli

Omni consensus-checking command-line tool.

11

Can be natively compiled with GraalVM native-image.

omnij-core

Core OmniJ classes

8

Android-compatible

omnij-dsl

Groovy Domain Specific Language (DSL) support for Omni

8

Useful in Spock unit and integration tests. Uses the Apache Groovy Language

omnij-jsonrpc

OmniClient JSON-RPC client and JSON-RPC support.

8

omnij-money

JavaMoney support for Omni currency codes and exchanges

8

omnij-net-api

Http interfaces and objects for Omniwallet & Omni Core with a common interface.

9

omnij-rest-client-retrofit

Omniwallet REST client using Retrofit library

9

Android-compatible

omnij-rest-client-jdk

Omniwallet REST client using JDK 11+ java.net.http

11

omnij-rpc

Omni Core RegTest/Integration Tests, Groovy JSON-RPC clients, command-line API/tools

11

Uses the Apache Groovy Language

A Bitcoin JSON-RPC client (base class), and other components used by OmniJ are in the ConsensusJ project.

OmniLayer Documentation

OmniJ Documentation and Build Reports

Including the OmniJ Maven Artifacts (JARs) in your build

Warning
These binaries have not been audited. Use only on TestNet or RegTest.

Although the API is changing, binary releases are available on Gitlab.com. You can download JARs or use the provided Maven coordinates to link to them directly from your pom.xml or build.gradle.

Maven

Add the following to the <repositories> section of your pom.xml:

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

In the <dependencies> section of your pom.xml add a <dependency> element that references the OmniJ JAR that you need. For example if you are using classes from omnij-core add the following <dependency> configuration:

    <dependency>
      <groupId>foundation.omni</groupId>
      <artifactId>omnij-core</artifactId>
      <version>0.5.21</version>
    </dependency>

If you are using the omnij-jsonrpc JAR, add the following:

    <dependency>
      <groupId>foundation.omni</groupId>
      <artifactId>omnij-jsonrpc</artifactId>
      <version>0.5.21</version>
    </dependency>

Gradle

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

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

In the dependencies section of your build.gradle add an implementation configuration that references the OmniJ JAR that you need. For example if you are using classes from omnij-core add the following implementation configuration:

    implementation "foundation.omni:omnij-core:0.5.21"

If you are using the omnij-jsonrpc JAR, add the following:

    implementation "foundation.omni:omnij-jsonrpc:0.5.21"

Building OmniJ

The only prerequisite for building OmniJ is having Java JDK 11 or later installed (JDK 17 is recommended.) All other prerequisites are downloaded automatically by the Gradle Wrapper script.

  1. Check out this project using Git

    $ git clone https://github.com/OmniLayer/OmniJ.git
  2. Open a shell and set the current working directory

    cd OmniJ
  3. Build and test with the provided Gradle wrapper scripts. For Unix/Mac:

    ./gradlew build

    or for Windows:

    ./gradlew.bat build

After a successful build, each omnij-module JAR can be found in a standard location:

module jar path

omnij-module

omnij-module/build/libs/omnij-module-version.jar

Omni Integration Testing with Spock Framework

Integration testing for Bitcoin and Omni Protocol using the Spock Framework.

There are currently two integration test suites contained in this project.

Omni RegTest Tests

Test Bitcoin and Omni Core RPC calls against an instance of omnicored running in RegTest mode.

Omni Consensus Tests

Use the omni_getallbalancesforid RPC to get balances for multiple Omni Protocol currencies and compare them against balance information from several well-known public Omni Protocol servers with consensus-checking Web APIs.

In ConsensusJ

Bitcoin RegTest Tests

Test Bitcoin RPC calls against an instance of bitcoind running in RegTest mode.

Installing pre-requisites

The only prerequisite for running these tests is an installed Java Runtime Environment. Either an Oracle or OpenJDK VM will work. Java 11 or later is required.

All other dependencies are automatically downloaded and cached by the test startup script.

Running the tests manually

  1. Check out this project using Git

    $ git clone https://github.com/OmniLayer/OmniJ.git
  2. Start Omni Core (or bitcoind) on MainNet listening on the standard RPC port on localhost. The tests are configured to use the following username and password:

    rpcuser=bitcoinrpc
    rpcpassword=pass
  3. Open a shell and set the current working directory

    cd OmniJ
  4. Run the tests with the provided Gradle wrapper scripts. For Unix/Mac:

    ./gradlew :omnij-rpc:consensusTest

    or for Windows:

    ./gradlew.bat :omnij-rpc:consensusTest

    The above examples are for the Consensus Test, to run the other test suites replace the :omnij-rpc:consensusTest Gradle target with :omnij-rpc:regTest for the Omni RegTests or with :bitcoin-rpc:regTest for the Bitcoin RegTests.

Running the tests from Jenkins

To run the test from Jenkins we are using the following (UNIX) shell scripts:

test-omni-integ-regtest.sh

Runs Omni Core RPC regtest test against a built executable of omnicored in copied-artifacts/src directory.

test-omni-consensus-mainnet.sh

Runs consensus tests against a built executable of omnicored in copied-artifacts/src directory.

In ConsensusJ project

bitcoinj-rpcclient/run-bitcoind-regtest.sh

Runs BTC RPC RegTest tests against a built executable of bitcoind in copied-artifacts/src directory.

Caution
Read the scripts carefully to make sure you understand how they work. Take special care to notice the rm -rf commands.

Sample Spock Integration Tests

These sample Spock "feature tests" are from the file ManagedPropertySpec.groovy.

    def "A managed property can be created with transaction type 54"() {
        when:
        creationTxid = omniSendIssuanceManaged(actorAddress, Ecosystem.OMNI,
                          PropertyType.INDIVISIBLE,
                          new CurrencyID(0),
                          "Test Category", "Test Subcategory",
                          "Managed Token Name",
                          "http://www.omnilayer.org",
                          "This is a test for managed properties")
        generateBlocks(1)
        def creationTx = omniGetTransaction(creationTxid)
        currencyID = new CurrencyID(creationTx.propertyid as Long)

        then: "the transaction is valid"
        creationTx.valid

        and: "it has the specified values"
        creationTx.txid == creationTxid.toString()
        creationTx.type_int == 54
        creationTx.divisible == false
        creationTx.propertyname == "ManagedTokens"
        creationTx.amount as Integer == 0

        and: "there is a new property"
        omniListProperties().size() == old(omniListProperties().size()) + 1
    }

    def "A managed property has a category, subcategory, name, website and description"() {
        when:
        def propertyInfo = omniGetProperty(currencyID)

        then:
        propertyInfo.propertyid == currencyID.getValue()
        propertyInfo.divisible == false
        propertyInfo.name == "ManagedTokens"
        propertyInfo.category == "Test Category"
        propertyInfo.subcategory == "Test Subcategory"
        propertyInfo.url == "http://www.omnilayer.org"
        propertyInfo.data == "This is a test for managed properties"
    }

OmniJ Command-line Consensus tool

The command-line consensus tool, omnij-consensus-tool can be built into a native, self-contained, executable using GraalVM. You’ll need a Java 11 (or later) version of GraalVM, we currently recommend version 21.3.0 (java11).

Building

Before building you’ll need a GraalVM setup on your system. Besides intalling the Graal JDK, you’ll need to do the following:

  1. Set GRAAL_HOME to the JAVA_HOME of the GraalVM JDK

  2. With the GraalVM active, type gu install native-image to install the optional native-image tool.

On Ubuntu you might need to do: sudo apt install gcc g++ binutils. Similar installs of development tools may be needed on other Linux distros.

The OmniJ Command-line Consensus tool can be built with the following command:

./gradlew :omnij-cli:nativeCompile

This will produce a self-contained, executable jar in omnij-cli/build/omnij-consensus-tool.

Running

To run use the following command:

./omnij-cli/build/omnij-consensus-tool -?

This will output the tool’s command line options.

Man Page

See the omnij-consensus-tool Man Page for further instructions.

Additional Documentation

The doc directory of this project contains some additional documents that might be of interest: