Overledger JavaScript SDK

Welcome to the developer's guide to use the Overledger SDK written in Javascript by Quant Network.

Introduction to the Overledger SDK

Overledger is a blockchain operating system that allows applications to connect to multiple distributed ledger technologies (DLTs) or blockchains, thus becoming Multi-chain Applications (MApps). The Overledger SDK enables developers to create signed transactions and send them simultaneously to all supported DLTs through the Overledger Blockchain Programming Interface (BPI).

Technologies

The Overledger SDK is a collection of node packages written in Typescript. Currently, the supported DLTs are Ethereum and Ripple. Bitcoin support will be re-enabled once the migration to the public testnet is complete.

Prerequisites

  • Register for a free developer account on Quant Developer's Portal
  • You will require a MApp ID and BPI key:
    • Register your application in order to get a free MApp ID.
    • Verify your Quant token, and create a BPI key.
  • Node.js 10

Installation

The Overledger SDK can be installed as a node module. If all supported DLTs are necessary, the bundle package can be installed, which will include all required dependencies.

npm install @quantnetwork/overledger-bundle

Or, if you prefer using yarn:

yarn add @quantnetwork/overledger-bundle

Alternatively, the suite of packages allows developers to chose which blockchains/DLTs they would like to utilise by installing the core package and the individual DLT packages. Such as if you only want to install overledger-core and overledger-ethereum you would enter:

npm install @quantnetwork/overledger-core
npm install @quantnetwork/overledger-dlt-ethereum

Or, if you prefer using yarn:

yarn add @quantnetwork/overledger-core
yarn add @quantnetwork/overledger-dlt-ethereum

Getting started

Initialize the SDK with the available DLTs. Optionally you can name the Overledger network provider to connect to and a timeout period can be specified (by default it is 5000ms).

const OverledgerSDK = require("@quantnetwork/overledger-bundle").default;

const overledger = new OverledgerSDK("mappId", "bpiKey", {
  dlts: [{ dlt: "ethereum" }, { dlt: "ripple" }],
  provider: { network: 'testnet', timeoutout: 1500 }, // Optional
});

API Reference

The SDK packages provide functions for interacting with the Overledger BPI Gateway as well as support for offline account generation and transaction signing. The functions which interact with the Overledger BPI (send, get) return a promise with a standard Axios response which includes the BPI data in the data field.

Please check the examples folder for details on how to sign and send transactions, as well as do account queries. The api reference page can be found here.

Examples

Examples can be found in the examples folder.

Don't forget to setup your mappId and bpiKey, you can get these on the developer portal.

Development

The Overledger JavaScript SDK manages multiple packages through Lerna. To develop the SDK, first install lerna:

npm install -g lerna

To build the project, download the yarn package manager and run:

yarn run build

This will build and link the packages together.

Documentation

Please update the documentation after your changes by editing the JSDoc annotations inside the source files and then run the following command from the root directory:

yarn run docs

License

The Apache 2.0 license can be found here.

License Maven Central

Overledger Java SDK

Developer's guide to use the Overledger SDK written in Java by Quant Network.

Introduction to the Overledger SDK

Overledger is an operating system that allows distributed apps (MApps) to connect to multiple distributed ledger technologies (DLTs) or blockchains. The Overledger SDK allows developers to create signed transactions & send them simultaneously to all supported DLTs.

Technologies

The Overledger SDK is maven compatible dependency written in Java

Overledger SDK Structure

Project Layer

Overledger SDK Working Flow

Project Flow

Prerequisites

  • Register for a free developer account on Quant Developer's Portal
  • You will require MAppId and access key:
    • Enter information regarding your application in order to get a MApp ID.
    • Verfify your Quant token, and create a access key.

Installation

Developers would have to install the Overledger SDK as a maven dependency.

<!-- SDK bundle -->
<dependency>
    <groupId>network.quant</groupId>
    <artifactId>overledger-sdk-bundle</artifactId>
    <version>1.0.0-alpha.3</version>
</dependency>

Tailored installation

When a full implementation of all dependencies is not required, it can be tailored to only implement those services that will be utilised.

overledger-sdk-api

API module defines Overledger SDK interfaces.

overledger-sdk-essential

This module gives a basic implementation of Overledger SDK API.

overledger-sdk-bitcoin

This module contains Bitcoin implementation of Overledger Account API.

overledger-sdk-ethereum

This module contains Ethereum implementation of Overledger Account API.

overledger-sdk-ripple

This module contains Ripple implementation of Overledger Account API.

overledger-sdk-bundle

This module bundles up API, essential, Bitcoin, Ethereum and Ripple modules.

overledger-sdk-example

Includes some examples.

Getting started

  • Follow README from overledger-sdk-api to create context.properties.

  • Then load properties into OverledgerContext

OverledgerContext.loadContext(...);
  • Instance OverledgerSDK Object, add accounts, and call Overledger SDK methods.
public class OverledgerSDKExample {

    private OverledgerSDK overledgerSDK;

    public OverledgerSDKExample(Account... accounts) {
        this.overledgerSDK = DefaultOverledgerSDK.newInstance(NETWORK.MAIN);
        this.overledgerSDK.addAccount(DLT.bitcoin.name(), accounts[0]);
        this.overledgerSDK.addAccount(DLT.ethereum.name(), accounts[1]);
        this.overledgerSDK.addAccount(DLT.ripple.name(), accounts[2]);
    }

    public OverledgerTransaction writeTransaction(OverledgerTransaction ovlTransaction) {
        return this.overledgerSDK.writeTransaction(ovlTransaction);
    }

}

actually working use case: note custom java properties only working and it must be laoded before the OverledgersSDK is instantiated.

            File fprop = new File("/Users/marvas/overledger-sdk-java/overledger-sdk-example/context.properties");
            UUID ovlId=null;
            FileInputStream inputStream = new FileInputStream(fprop);
            Properties properties = new Properties();
            properties.load(inputStream);
            OverledgerContext.loadContext(properties);
            OverledgerSDK h  = DefaultOverledgerSDK.newInstance();

            var ovTrans = h.readTransactions("network.quant.software");
            int cnt=0;

Further information

This SDK acts as library for embedding in an application, and facilitates the execution and access of Quant Network's Overledger.

Refer wiki for more Details.

Stable Release Version JDK Version compatibility BPI Version compatibility Release Date
1.0.0-alpha 11+ 1.0.0-alpha *30/10/2018
1.0.0-alpha.1 11+ 1.0.0-alpha.1 *17/12/2018
1.0.0-alpha.2 11+ 1.0.0-alpha.1 *26/02/2019
1.0.0-alpha.3 11+ 1.0.0-alpha.2 *15/04/2019
1.0.0-alpha.4 11+ 1.0.0-alpha.3 *15/04/2019

Release notes

Release Notes
1.0.0-alpha v1.0.0-alpha release notes
1.0.0-alpha.1 v1.0.0-alpha.1 release notes
1.0.0-alpha.2 v1.0.0-alpha.2 release notes
1.0.0-alpha.3 v1.0.0-alpha.3 release notes
1.0.0-alpha.4 Created simple working examples based on the JavaScript examples

Tutorial - Developing on Overledger

Introduction

An introduction to exploring the blockchain using Quant Network's Overledger SDK.

Quant's Overledger is a platform that facilitates the development of decentralised, multi-chain applications which allows you build on the blockchain more quickly and efficiently.

During this tutorial we will demonstrate how to use the Overledger Javascript SDK to submit transactions and query data on multiple blockchains.

Outcome

We will begin writing a NodeJS project which will allow us to run an Overledger example in JavaScript.

What we will be building: a simple script which automatically signs and sends transactions to multiple blockchains through Overledger.

Requirements

Please note this has been tested on MacOS and Ubuntu, for Windows, you might need to do additional environment configuration

  • NodeJS 10
  • NPM
  • Your favourite IDE/editor

Setting up the environment

First, create a new directory within which all the setup will be done. Then, open a terminal shell inside it and run the following command:

npm init -y

This will create a default package.json file which we can use to set up the dependencies of our project.

Only one dependency is required @quantnetwork/overledger-bundle. To set this up run the following command for npm:

# npm
npm install @quantnetwork/overledger-bundle

The overledger-bundle includes all the sub-packages of the Overledger SDK which are required to read and write on the different blockchains supported.

Link to Quant Overledger SDK JavaScript for some guidance and information.

Application Flow / Outline

The objective is to succesfully send a multi-chain transaction and verify that it took place.

After that, we will explore some further examples on how to query data from the blockchains.

Importing the dependency and setting up the accounts

First, create a JavaScript file, for example overledger-script.js. Inside the file, we will include all our code blocks.

We will now require the 'overledger-bundle' library and set up the initial constants.

const OverledgerSDK = require('@quantnetwork/overledger-bundle').default;

//  ---------------------------------------------------------
//  -------------- BEGIN VARIABLES TO UPDATE ----------------
//  ---------------------------------------------------------
const mappId = '<ENTER YOUR MAPPID>';
const bpiKey = '<ENTER YOUR BPIKEY>';

// Paste in your ethereum and ripple private keys.
// For Ethereum you can generate an account using `OverledgerSDK.dlts.ethereum.createAccount()`, then fund the address at the Ropsten Testnet Faucet. An example can be found in src/create-ethereum-account.js
const partyAEthereumPrivateKey = '';
const partyAEthereumAddress = ''
// For Ripple, you can go to the official Ripple Testnet Faucet to get an account already funded.
const partyARipplePrivateKey = '';
const partyARippleAddress = ''


const partyBEthereumAddress = '0x1a90dbb13861a29bFC2e464549D28bE44846Dbe4';
// Keep in mind that for Ripple, the minimum transfer amount is 20XRP (20,000,000 drops), if the address is not yet funded.
const partyBRippleAddress = 'rHVsZPVPjYJMR3Xa8YH7r7MapS7s5cyqgB';

const transactionMessage = 'Hello world!';
//  ---------------------------------------------------------
//  -------------- END VARIABLES TO UPDATE ------------------
//  ---------------------------------------------------------

Instantiating the Overledger SDK

To instantiate the OverledgerSDK, we need to specify the dlts we would like to use and the network we want to connect to. Optionally, we can set a request timeout period in ms. We will also set up the transactionMessage constant here, which we will send to the blockchains.

const overledger = new OverledgerSDK(mappId, bpiKey, {
  dlts: [{ dlt: 'ethereum' }, { dlt: 'ripple' }],
  provider: {
    network: 'testnet',
    timeout: 10000,
  },
});

Getting our account transaction sequences through Overledger

In order to sign transactions offline, some information about the state of our accounts is required first. The transaction sequence is the number of transactions the respective account has submitted. We can use Overledger to request this information from the blockchains.

; (async () => {
  try {
    // SET partyA accounts for signing;
    overledger.dlts.ethereum.setAccount(partyAEthereumPrivateKey);
    overledger.dlts.ripple.setAccount(partyARipplePrivateKey);

    // Get the address sequences.
    const ethereumSequenceRequest = await overledger.dlts.ethereum.getSequence(partyAEthereumAddress);
    const rippleSequenceRequest = await overledger.dlts.ripple.getSequence(partyARippleAddress);
    const ethereumAccountSequence = ethereumSequenceRequest.data.dltData[0].sequence;
    const rippleAccountSequence = rippleSequenceRequest.data.dltData[0].sequence;

    console.log("The transaction sequence of our Ethereum account is: ", ethereumAccountSequence);
    console.log("The transaction sequence of our Ripple account is: ", rippleAccountSequence);
  } catch (e) {
    console.error('error:', e);
  }
})();

Signing the transactions

To submit our transactions, we need to sign them first. The Overledger SDK uses the respective libraries for the blockchains in order to sign transactions offline, therefore avoiding the exposure of our private keys.

We will now include this block before the } catch (e) { line in the previous block.

    // Sign the transactions.
    const signedTransactions = await overledger.sign([
    {
      // In order to sign an ethereum transaction offline, we have to specify the sequence (nonce), a feePrice (gasPrice) and feeLimit (gasLimit).
      dlt: 'ethereum',
      toAddress: partyBEthereumAddress,
      message: transactionMessage,
      options: {
        amount: '0', // On Ethereum you can send 0 amount transactions. But you still pay network fees
        sequence: ethereumAccountSequence, // Sequence starts at 0 for newly created addresses
        feePrice: '1000', // Price for each individual gas unit this transaction will consume
        feeLimit: '80000', // The maximum fee that this transaction will use
      },
    },
    {
      // In order to sign a ripple transaction offline, we have to specify a fee, sequence and maxLedgerVersion.
      dlt: 'ripple',
      toAddress: partyBRippleAddress,
      message: transactionMessage,
      options: {
        amount: '1', // Minimum allowed amount of drops is 1 for Ripple.
        sequence: rippleAccountSequence, // Sequence increases by 1 with each transaction and starts at 1 right after getting the address from the XRP testnet faucet.
        feePrice: '12', // Minimum feePrice on Ripple is 12 drops.
        maxLedgerVersion: '4294967295', // The maximum ledger version the transaction can be included in.
      },
    },]);

Sending the signed transactions through Overledger

Lastly, we will send our signed transactions to Overledger.

We will include this block right below the block above, but before the } catch (e) { line.

    // Send the transactions to Overledger.
    const result = (await overledger.send(signedTransactions)).data;

    // Log the result.
    console.log(JSON.stringify(result, null, 2));

Running

To run our script, from the terminal, simply execute

node overledger-script.js

You should see the terminal output stating the transactions have been successfuly broadcasted, together with an overledgerTransactionId which can be used to search for both transactions:

{
  "mappId": "network.quant.examples.a-to-b-transaction",
  "overledgerTransactionId": "f0c1f314-7cda-4f67-8a21-3761d09af452",
  "timestamp": "2019-04-29T14:05:40.189878Z",
  "dltData": [
    {
      "dlt": "ethereum",
      "transactionHash": "0x4016406d985f0273d841353c95e88906fc805c700b7a5bf4c79124df1dd53985",
      "status": {
        "status": "broadcasted",
        "code": "0",
        "message": "Successfully broadcasted"
      },
      "links": []
    },
    {
      "dlt": "ripple",
      "transactionHash": "A7606719C83BCE64A43D102FB7D6DDF0B1A8E7014512D395E0756D1D7EBA287F",
      "status": {
        "status": "broadcasted",
        "code": "tesSUCCESS",
        "message": "The transaction was applied. Only final in a validated ledger."
      },
      "links": []
    }
  ]
}

A full example can be found in src/send-transaction.js.

More examples

Further examples can be found in the src folder for: - creating an ethereum account - getting address balances - getting address sequences - reading an Overledger transaction - searching for blocks - searching for transactions