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. |
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. The core JARs require JDK 8 or JDK 9. Some optional JARs require later JDK versions.
module | Description | JDK | Notes |
---|---|---|---|
omnij-cli |
Omni consensus-checking command-line tool. |
17 |
Can be natively compiled with GraalVM |
omnij-core |
Core OmniJ classes |
11 |
Android-compatible |
omnij-dsl |
Groovy Domain Specific Language (DSL) support for Omni |
11 |
Useful in Spock unit and integration tests. Uses the Apache Groovy Language |
omnij-jsonrpc |
|
11 |
|
omnij-money |
JavaMoney support for Omni currency codes and exchanges |
11 |
|
omnij-net-api |
Http interfaces and objects for Omniwallet & Omni Core with a common interface. |
11 |
|
omnij-rest-client-jdk |
Omniwallet REST client using JDK 11+ |
11 |
|
omnij-rest-client-retrofit |
Omniwallet REST client using Retrofit library |
11 |
Android-compatible |
omnij-rpc |
Omni Core RegTest/Integration Tests, Groovy JSON-RPC clients, command-line API/tools |
11 |
Uses the Apache Groovy Language |
omnij-tx-records |
Omni Transactions defined as Java records and services that use them. |
17 |
A Bitcoin JSON-RPC client (base class), and other components used by OmniJ are in the ConsensusJ project.
-
OmniJ JavaDoc
-
OmniJ GroovyDoc
-
OmniJ Unit Test Results (currently unavailable)
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
.
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.7.0-alpha3</version>
</dependency>
If you are using the omnij-jsonrpc
JAR, add the following:
<dependency>
<groupId>foundation.omni</groupId>
<artifactId>omnij-jsonrpc</artifactId>
<version>0.7.0-alpha3</version>
</dependency>
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.7.0-alpha3"
If you are using the omnij-jsonrpc
JAR, add the following:
implementation "foundation.omni:omnij-jsonrpc:0.7.0-alpha3"
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.
-
Check out this project using Git
$ git clone https://github.com/OmniLayer/OmniJ.git
-
Open a shell and set the current working directory
cd OmniJ
-
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 |
---|---|
|
|
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.
- Bitcoin RegTest Tests
-
Test Bitcoin RPC calls against an instance of
bitcoind
running in RegTest mode.
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.
-
Check out this project using Git
$ git clone https://github.com/OmniLayer/OmniJ.git
-
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
-
Open a shell and set the current working directory
cd OmniJ
-
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.
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
incopied-artifacts/src
directory. - test-omni-consensus-mainnet.sh
-
Runs consensus tests against a built executable of
omnicored
incopied-artifacts/src
directory.
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 = creationTx.propertyId
then: "the transaction is valid"
creationTx.valid
and: "it has the specified values"
creationTx.txiId == creationTxid.toString()
creationTx.typeInt == 54
creationTx.divisible == false
creationTx.propertyname == "ManagedTokens"
creationTx.amount == 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"
}
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).
Before building you’ll need a GraalVM setup on your system. Besides intalling the Graal JDK, you’ll need to do the following:
-
Set
GRAAL_HOME
to theJAVA_HOME
of the GraalVM JDK -
With the GraalVM active, type
gu install native-image
to install the optionalnative-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
.
To run use the following command:
./omnij-cli/build/omnij-consensus-tool -?
This will output the tool’s command line options.
See the omnij-consensus-tool Man Page for further instructions.
The doc
directory of this project contains some additional documents that might be of interest: