README.md

IOTA Java Library

This is the official Java library for the IOTA Core. It's a simple Java wrapper around IOTA node’s JSON-REST HTTP interface and allows to connect to a local or a remote IOTA node easily using it's Java API interface.

The IOTA Java wrapper is designed to be thread-safe and kept as simple as possible in order to be easily maintainable, accordingly with the ongoing natural evolution of IOTA’s API. All the boilerplate code for connecting to the node REST interface has been hidden as implementation detail (using Retrofit 2) — you'll only interact with pure Java.

Table of Contents

1. Installation
   1. Gradle Dependency
   2. Maven Dependency
   3. Manual
2. Documentation
   1. Getting Started
   2. Threading
   3. Javadoc
   4. API
   5. Examples
3. Technologies & dependencies
   1. Dependencies
4. Changes
5. Disclaimer
6. Supporting the project
   1. Join the Discussion
7. License

Installation

The IOTA Java library is available on jitpack.io.

Gradle Dependency

To use the IOTA Java library in your Gradle build add this in your root build.gradle file (not your module build.gradle file):

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

Add this in your module build.gradle file:

dependencies {
    compile 'com.github.iotaledger:iota-java:1.0.0-beta3'
}

Maven Dependency

To use the IOTA Java library in your Maven build add this to your root pom.xml file:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

Add this in your module pom.xml file:

<dependency>
    <groupId>com.github.iotaledger.iota-java</groupId>
    <artifactId>jota</artifactId>
    <classifier>jar-with-dependencies</classifier>
    <version>[VERSION_INFORMATION]</version>
</dependency>

For the [VERSION_INFORMATION], you can choose to set it to a release number, or the first 10 characters of a commit hash. <version>a98de8ea50</version> or <version>1.0.0-beta3</version> Or check it out at Jitpack for more specific information

Manual

To use the IOTA Java library by building the library yourself, the following steps can be used.

Linking library

Clone or download the project and import it into your favorite IDE. This will result in two projects; jota and jota-parent. Reference your new project to the "jota" project.

Linking jar

In order to build the jar; the following command should be run on the "jota" project: 'mvn clean install'

This will generate a jar with the following format: jota-[VERSION]-jar-with-dependencies.jar

Documentation

It should be noted that this is a temporary home for the official documentation. We are currently transitioning to a new developer hub, where we will have a dedicated website for the API documentation with concrete examples. The below documentation should be sufficient in enabling you to get started in the meantime.

Getting Started

After you've successfully installed the library dependency, it is fairly easy to get started by simply creating a new IotaAPI instance using the IotaAPI.Builder.

Connecting to your device's local node with the default settings and fetching the node info is quite straightforward:

IotaAPI api = new IotaAPI.Builder().build();
GetNodeInfoResponse response = api.getNodeInfo();

It doesn't get much more complicated if you need to connect to a remote node:

IotaAPI api = new IotaAPI.Builder()
        .protocol("http")
        .host("somewhere_over_the_rainbow")
        .port("14265")
        .build();
GetNodeInfoResponse response = api.getNodeInfo();

In order to separate your node configuration from the implementation, you can also specify node configuration using a Java .properties file or command line properties which is very useful if you develop an open-source app which is deployed on a CI and don't want contributors to see the internal node configuration:

iota.node.protocol=http
iota.node.host=127.0.0.1
iota.node.port=14265

Threading

It should be noted that most API calls are done synchronously. What this means is that you have to call the API from a background or worker thread, not from the main or UI thread!

Javadoc

A hosted version of the complete Javadoc for the latest release can be found here. If you think there's something missing in the Javadoc, submit an issue or open a pull request.

API

The IOTA Java library implements both the official API, as well as some newly proposed functionality (such as signing, bundles, utilities and conversion).

A full list of all IOTA JSON-REST API commands currently supported by the IOTA Java library can be found in the commands enum.

Here are some of the most commonly used API functions. Each list item below links to its corresponding Javadoc where you can find method signatures, preconditions, side-effects and invariants.

IotaAPI

• getTransactionsObjects()
• findTransactionObjects() - getTransactionsObjects()
• getLatestInclusion()
• broadcastAndStore()
• getNewAddress()
• getInputs()
• prepareTransfers()
• sendTrytes()
• sendTransfer()
• replayBundle()
• getBundle()
• getTransfers()
• initiateTransfer()
• getAccountData()

IotaUnitConverter

• convertUnits()

Checksum

• addChecksum()
• removeChecksum()
• isValidChecksum()

InputValidator

• checkAddress()
• isAddress()
• isArrayOfHashes()
• isArrayOfTrytes()
• inNinesTrytes()
• isTransfersCollectionValid()
• isTrytes()
• isValidSeed()
• isValidTransfer()
• isValue()

Transaction

• toTrytes()

Converter

• trytes()
• trits()

Signing

• validateSignatures()

Multisig

• getKey()
• getDigest()
• finalizeAddress()
• validateAddress()
• addSignature()

Examples

There's an extensive list of test cases on the src/test/java directory that can be used as reference when developing apps with IOTA. A good starter is the IotaAPITest case.

Technologies & dependencies

The IOTA Java library has been designed to be used with Java 6 or higher, in order to promote full compatibility with Android.

Dependencies:

The following third party library dependencies and versions are used by the IOTA Java library internally:

• Retrofit 2 type-safe HTTP client: 2.3.0
• Simple Logging Facade for Java: 1.7.25
• Apache Commons Lang: 3.6
• Apache Commons IO: 2.5
• Legion of the Bouncy Castle Java cryptography APIs: 1.58

Changes:

• Changes in 1.0.0-beta3
• Changes in 1.0.0-beta2
• Changes in 1.0.0-beta1
• Changes in v0.9.10
• Changes in v0.9.6
• Changes in v0.9.5
• Changes in v0.9.4
• Changes in v0.9.3
• Changes in v0.9.2
• Changes in v0.9.1

Warning / Disclaimer

• This is pre-release software!
• There may be performance and stability issues.
• You may loose all your money :)
• Please report any issues using our issue tracker.

Supporting the project

If the IOTA Java library has been useful to you and you feel like contributing, consider posting a bug report, feature request or a pull request.
We have some basic contribution guidelines to keep our code base stable and consistent.

Join the Discussion

If you want to get involved in the community, need help with getting setup, have any issues related with the library or just want to discuss Blockchain, Distributed Ledgers and IoT with other people, feel free to join our Discord.
You can also ask questions on our dedicated IOTA Forum.

License:

The full license text can be found here.

Copyright 2017 IOTA Foundation

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.