Home

Hyperledger Quilt is an implementation of the Interledger Protocol.

It is a Maven project with numerous sub-modules.

ILP Core

ilp-core is a foundational library for Interledger projects, providing service interfaces and data models. This library also offers codecs for encoding and decoding Interledger objects according to the ASN.1 specifications using OER (Octet Encoding Rules).

For more information about Interledger specifications that underpin this library, please reference https://github.com/interledger/rfcs.

Get it!

Maven

This library is contained in the Java package org.interledger, and can be included in your project by first adding a Snapshot Repository, like this:

<repositories>
    ...
    <repository>
        <id>sonatype</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
    </repository>
    ...
</repositories>

Next, add the following Maven dependency:

<dependencies>
  ...
  <dependency>
    <groupId>org.interledger</groupId>
    <artifactId>java-ilp-core</artifactId>
    <version>0.7.0-SNAPSHOT</version>
  </dependency>
  ...
</dependencies>

Gradle

To import this library into a project that uses gradle, first add the Snapshot Repository to your gradle.properties file, like this:

repositories {
    mavenCentral()
    maven {
        url "https://oss.sonatype.org/content/repositories/snapshots/"
    }
}

Next, import this library as a dependency, like this:

dependencies {
    ...
    compile group: 'org.interledger', name: 'java-ilp-core', version: '0.7.0-SNAPSHOT'
    ...
}

Usage

Interledger Address

Interledger Addresses can be created from a String and then manipulated using utility functions

//Create a new address (short form)
InterledgerAddress address = InterledgerAddress.of("private.bob");

//Create a new address (long form)
InterledgerAddress destinationAddress = InterledgerAddress.builder()
  .value("private.bob")
  .build();

//Check if an address starts with a specific prefix
if( address.startsWith("test") ) {
  //Testnet address...
}

Conditions and Fulfillments

Conditions can be derived from a fullfillment or directly from the underlying hash

//Create a fulfillment from a pre-image of 32-bytes (short form)
Fulfillment fulfillment = Fulfillment.of(preimage);

//Create a fulfillment from a pre-image of 32-bytes (long form)
Fulfillment fulfillment = Fulfillment.builder()
  .preimage(preimage)
  .build();

//Get Condition from Fulfillment
Condition condition = fulfillment.getCondition();

//Create Condition (short form)
Condition condition1 = Condition.of(hash);

//Create Condition (long form)
Condition condition1 = Condition.builder()
  .hash(hash)
  .build();

Interledger Payment packet

// Build ILP Payment Packet
InterledgerPayment payment = InterledgerPayment.builder()
  .destinationAccount(address)
  .destinationAmount(destinationAmount)
  .data(data)
  .build();

Interledger Payment Request

InterledgerPaymentRequest ipr = InterledgerPaymentRequest.builder()
  .payment(payment)
  .condition(condition)
  .build();

Pre-Shared Key protocol

The PSK protocol defines an envelope format for the data in an ILP Payment packet but also a number of algorithms for deriving various keys and secrets based on a single receiver secret.

The PSK Context is created using the receiver secret (on the receiver side) or just the shared key on the sender side. A sender side context cannot be used to derive a receiverId and has no random token so calling either getToken() or getReceiverId() will throw.

See ILP-RFC 16 for more details of PSK

// Create a new context at the receiver and seed with a new random token
PskContext context = PskContext.seed(SECRET);

//Load a context from an incoming payment using the token extracted from the destination address
in the payment
PskContext receiverContext =
    PskContext.fromReceiverAddress(SECRET, incomingPayment.getDestinationAccount());

//Load a context from the shared key provided to the sender during the SPSP exchange
PskContext senderPskContext = PskContext.fromPreSharedKey(psk);

//Create a PSK Message
PskMessage pskMessage = PskMessage.builder()
  .paymentId(paymentId)
  .expiry(expiry)
  .addPrivateHeader("Secret", secretStuff)
  .data(data)
  .build();

// Encrypt message
PskMessage encryptedPskMessage = context.encryptMessage(pskMessage);

// Decrypt message
PskMessage decryptedPskMessage = context.decryptMessage(encryptedPskMessage);

For a full end-to-end test demonstrating all of these functions see: org.interledger.ipr.InterledgerPaymentRequestEndToEndTest

Crypto Conditions

TODO

Development

We welcome any and all submissions, whether it's a typo, bug fix, or new feature.

Requirements

This project uses Maven to manage dependencies and other aspects of the build. To install Maven, follow the instructions at https://maven.apache.org/install.html.

Get the Code

$ git clone https://github.com/interledger/java-ilp-core.git

Build the Project

To build the project, execute the following command from the top-level folder that you cloned the above two projects to. For example:

$ mvn install

Code Style

The project uses checkstyle to keep code style consistent. To run the style checks:

$ mvn checkstyle:check

Contributing

This project utilizes a Pull Request submission model. Before submitting a pull request, ensure that your build passes with no test failures nor Checkstyle errors.

FAQ

1. What Is Interledger?
2. What Is Interledger For?
3. What Problem Does Interledger Solve?
4. What Design Principles Underlie Interledger Java?

TODO