License NPM package version

Overledger Javascript SDK

Developer's guide to use Overledger SDK written in Javascript 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 a node module written in Javascript/ES6.

Prerequisites

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

Installation

The Overledger SDK can be easily installed as an npm module. This will ensure that all required dependencies are automatically included.

npm install @quantnetwork/overledger-sdk

Or if you prefer Yarn as the package manager.

yarn add @quantnetwork/overledger-sdk

Development

To run the SDK in development mode, run the command npm run dev and every change will be automatically built.

Getting started

NodeJS with babel

import OverledgerSDK from "@quantnetwork/overledger-sdk";

NodeJS

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

Initialize the SDK with the 3 available dlts. Optionally, a timeout period can be specified (by default it's 5000ms).

const overledger = new OverledgerSDK("mappId", "bpiKey", {
  dlts: [{ dlt: "bitcoin" }, { dlt: "ethereum" }, { dlt: "ripple" }],
  timeout: 1500, // Optional
});

Usage

The SDK provides the following functions which return a promise with a standard axios response which includes the BPI data in the data field:

configure

Configure DLTs.

Usage: configure(options)

Parameters

This function has DLT Names as parameter.

Name Type Description
options Object Object of the options type

Return Value

This function does not have a return value.

sign

Sign a transaction for a DLT.

Usage: sign(dlts)

Parameters

This function takes an array of DLT transaction data.

Name Type Description
dlts array Array of DLT transaction data (DLT Name, From Address, To Address and Data)

Example of DLT transaction data:

Because the data differs between blockchain, the options object contains all the non-generic variables and can be different in each blockchain.

[
  {
    dlt: "bitcoin",
    toAddress: "2NFj2CVhE5ru7werwXUNCbirUW6KDo2d",
    message: "QNT test",
    options: {
      amount: 1,
      sequence: 2, // VOUT
      previousTransactionHash: '77b04805f40a7cba6ed49be10d200f41462bfa266f24db91114798178c802058',
      feePrice: 1e5,
      value: 1
    }
  },
  {
    dlt: "ethereum",
    toAddress: "0x0000000000000000000000000000000000000000",
    message: "QNT test",
    options: {
      amount: '1', // Amount in wei (1 ETH = 10^18 wei)
      sequence: 2, // nonce
      feeLimit: '10',
      feePrice: '10',
    }
  },
  {
    dlt: "ripple",
    toAddress: "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh",
    message: "QNT test",
    options: {
      amount: '1', // Amount in drops (1 XRP = 1,000,000 drops)
      feePrice: '0.000012', // Standard fee price on the XRP network
      sequence: 1, // Transaction index number for this account (e.g if it's the first transaction after funding the address, sequence is 1)
      maxLedgerVersion: 4294967295, // This is the maximum value that this option field can take
    }
  }
];

Return Value

This function returns a Promise which resolves with a signedTransaction string.

send

Send the signed transaction to the blockchain.

Usage: send(signedTransactions)

Parameters

This function takes Signed Transaction Hash as parameter.

Name Type Description
signedTransactions[object] object Object of signed transaction
signedTransactions = [
  {
    dlt: 'bitcoin',
    signedTransaction: 'SIGNEDTRANSACTIONHASH',
  },
  {
    dlt: 'ethereum',
    signedTransaction: 'SIGNEDTRANSACTIONHASH',
  },
]

Return Value

This function returns Transaction Hash

readTransactionsByMappId

Read all transactions submitted by the mapp connected to the current API session.

Parameters

This function has no parameters.

Return value

This function returns a promise that resolves with an array of Overledger transaction objects with the following fields:

Name Type Description
mappId string Identifier of a multi-chain application
overledgerTransactionId string A transaction hash used to identify it, represented in hexadecimal
timestamp string The timestamp when the transaction was received by Overledger
dltData array Array of dltData type objects

readByTransactionId

Read an Overledger transaction by its ID.

Parameters

Name Type Description
id String A transaction hash used to identify it, represented in hexadecimal

Return value

This function returns a promise that resolves with an Overledger transaction containing the following fields:

Name Type Description
mappId string Identifier of a multi-chain application
overledgerTransactionId string A transaction hash used to identify it, represented in hexadecimal
timestamp string The timestamp when the transaction was received by Overledger
dltData array Array of objects of the dltData type

setMappId

Set the multi-chain application ID. Usage: setMappId('network.quant.helloworld');

Parameters

Name Type Description
id String String representation of a multichain application id

Return value

This functionns has no return value

getMappId

Get the multi-chain application identifier. Usage: const mappId = getMappId();

Parameters

This function has no parameters.

Return value

This function returns a string representing the multi-chain application identifier.

Name Type Description
id string String representation of a multichain application id

setBpiKey

Set the Blockchain Programming Interface key. Usage: setBpiKey('bpiKey');

Parameters

Name Type Description
bpiKey string String representation of a BPI key.

Return value

This functions has no return value

getBpiKey

Get the currently set Blockchain Programming Interface key. Usage: const bpiKey = getBpiKey();

Parameters

This function has no parameters

Return value

This function returns a string representing the bpi key that is currently used.

Name Type Description
bpiKey string String representation of the BPI key.

getBalances

Get the balances of multiple addresses Usage:

const request = [
    {
        "dlt": "ethereum",
        "address": "0x0000000000000000000000000000000000000000"
    },
    {
        "dlt": "ripple",
        "address": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"
    }
]

overledger.getBalances(request);

Parameters

This function accepts an array of objects with the following fields:

Name Type Description
dlt string The dlt where this address should be searched on
address string The address for the balance query

Return value

This function returns an array of objects with the following fields.

Name Type Description
dlt string The DLT which the request has been submitted to
address string The address holding the balance
unit string The unit; satoshi for bitcoin, wei for ethereum, drops for ripple
value string The amount of units this address holds

getSequences

Get the sequences of multiple addresses Usage:

const request = [
    {
        "dlt": "ethereum",
        "fromAddress": "0x0000000000000000000000000000000000000000"
    },
    {
        "dlt": "ripple",
        "fromAddress": "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"
    }
]

overledger.getSequences(request);

Parameters

This function accepts an array of objects with the following fields:

Name Type Description
dlt string The dlt where this address should be searched on
fromAddress string The address for the sequence query

Return value

This function returns an array of objects with the following fields.

Name Type Description
dlt string The DLT which the request has been submitted to
sequence string The sequence number of this address

Faucet

As per default it would take the configured address. From the DLT level overledger.dlts.[dlt] Fund an account on our testnet.

Usage: fundAccount(amount?, address?)

Parameters

Name Type Description
amount string Optional The amount of tokens to fund, in the smallest unit (satoshi for Bitcoin, wei for Ethereum or drops for Ripple)
address string Optional The address to fund

Return Value

This function returns a Promise

Types

In this section we will provide a description of the common object types.

overledgerTransaction

Name Type Description
mappId string Identifier of a multi-chain application
overledgerTransactionId string A transaction hash used to identify it, represented in hexadecimal
timestamp string The timestamp when the transaction was received by Overledger
dltData array Array of objects of the dltData type

dltData

Name Type Description
dlt string String representation of the BPI key.
message string Data to be sent to the DLT
fromAddres string Sender address
toAddress string Destination address
changeAddress string Address for the change to be submitted to
fee string Fee to pay for the transaction, represented in the lowest unit on the network (e.g.: satoshi, wei, drop etc)
feeLimit string Maximum fee to pay for the transaction to be submitted on the DLT
callbackUrl string Endpoint provided by the Mapp for the BPI layer to call back
signedTransaction string Hexadecimal string representation of a signed transaction

Account

From the DLT level overledger.dlts.[dlt]

Set Account

This function sets the default account for the specified blockchain into the SDK, every transaction will be signed by this account Usage: setAccount(privateKey) Must be a WIF key for bitcoin

Parameters

This function takes: - privateKey: the privateKey belonging to the specified blockchain

Return Value

This function has no return value.

Get Account

This function gets the default account for the specified blockchain from the SDK Usage: overledger.dlts.[dlt].account

Return Value

This function returns

{
  privateKey: 'string' // The privateKey belonging to the specified blockchain
  address: 'string' // The address belonging to this privateKey
}

For bitcoin, the privateKey is in the WIF format

Create Account

This function creates an account for the specified blockchain from the SDK Usage: overledger.dlts.[dlt].createAccount()

Return Value

This function returns

{
  privateKey: 'string' // The privateKey belonging to the specified blockchain
  address: 'string' // The address belonging to this privateKey
}

For bitcoin, the privateKey is in the WIF format

getBalance

Get the balance of an address or, by default, the account that is currently set.

Usage: overledger.dlts.{dltName}.getBalance(address);

Parameters

Name Type Description
address string Optional address.

Return value

This function returns an object with the following fields.

Name Type Description
dlt string The DLT which the request has been submitted to
address string The address holding the balance
unit string The unit; satoshi for bitcoin, wei for ethereum, drops for ripple
value string The amount of units this address holds

getSequence

Get the sequence of an address Usage: overledger.dlts.{dltName}.getSequence('0x0000000000000000000000000000000000000000');

Parameters

Name Type Description
fromAddress string The address for the sequence query

Return value

This function returns an array of objects with the following fields.

Name Type Description
dlt string The DLT which the request has been submitted to
sequence string The sequence number of this address

Usage Example

In this simple usage example we will call the getBalance method to request the balance of the genesis address on Ripple (created by the blockchain on startup).

npm install @quantnetwork/overledger-sdk
// Boilerplate
const OverledgerSDK = require("@quantnetwork/overledger-sdk").default;
// Replace mappId and bipKey with your own credentials.
const overledger = new OverledgerSDK("mappId", "bpiKey", {
  dlts: [{ dlt: "bitcoin" }, { dlt: "ethereum" }, { dlt: "ripple" }]
});

// Method call
;(async () => {

  const rippleAddress = "rHb9CJAWyB4rj91VRWn96DkukG4bwdtyTh"

  const response = await overledger.dlts.ripple.getBalance(rippleAddress);

  var rippleGenesisBalance = response.data
  // The lowest unit in XRP is called 'drop'
  console.log("The balance of the genesis address on the Quant Ripple Testnet is", rippleGenesisBalance.value, rippleGenesisBalance.unit);

})();

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.2</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.

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);
    }

}

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

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

IWOMM Developing on the Blockchain

Wednesday, 13th February 2019, 18:30 to 21:30, Lexis House, 30 Farringdon St, London

Introduction

An introduction to exploring the blockchain using Quant Network's Overledger SDK. Kindly sponsored by 101Ways and LexisNexis.

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 the next 101 minutes we will build the skeleton of a multi-chain application backend for a distributed commerce application: 101 Dream Cars.

Running order

  1. Short presentation about Overledger
  2. What you will be building 101 Dream Cars
  3. Setting up the environment
  4. Application flow / outline

101 Dream Cars

101 Dream Cars is a one stop shop for dCommerce of unique motor vehicles. It prides itself on facilitating a single transaction where a buyer can:

  • Purchase a car with 101 Cars using Bitcoin
  • Register a car with the Vehicle Licencing Agency using Ripple
  • Insure a car with Specialist Insurers using Ethereum

In order to do this it utilises an online shop where it transacts with the buyer, and integrates with third party services. The transactions are recorded immutable on the respective blockchains as used by each of the services.

In order to keep this demonstration practical we will focus on the integration with the blockchain opposed to building a nice front-end.

Setting up the environment

This session will focus on a JavaScript application.

Only one dependency is required @quantnetwork/overledger-sdk:

# npm
npm install @quantnetwork/overledger-sdk

# yarn
yarn add @quantnetwork/overledger-sdk

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

Additional environment setup

Please note that the package expect certain build tools already present. MacOS and Linux normally has these preinstalled like the xcode-select gcc compiler etc.

For windows it is important to add the following steps if that is not already configured for your environment.

PLEASE NOTE: If you already have Python and Windows Build Tools installed this may not work for you. The steps below are dependent on a clean machine. They are tested with node 10.15.1 LTS

# From an administrative privileged command prompt
npm install --global --production windows-build-tools
npm install -g node-gyp

Quant Developer Portal registration

PLEASE NOTE To make best use of the time for this event we've disabled the checking for a MappId & BpiKey. As such you can choose your own version for those keys.

attribute suggestion
MappId Unique identifier for the application, in this case the 101 Dream Cars shop. Suggest you use your email in reverse dot notation; i.e. network.quant.dejong.jean-paul
BpiKey Specific key that can be updated an revoked by environment. You can use anything; i.e. mybpikey

Optional at today's event

Sign up at the Quant Developer Portal is free, and it will provide ongoing access to our testnet. Deployment into a production environment will require a holding of our utility token QNT. Some of the key benefits of our testnet are;

  • Instant access environment with all supported Distributed Ledger Technologies.
  • Faucets to supply test value as required by your chosen DLTs.
  • Requires only a single end-point to be made available through any corporate firewalls.

Application Flow / Outline

The objective of the next 101 minutes is to get to a stage where through a single transaction your shops 101 Dream Cars can not only take payment for the vehicle sold, but also performs the registration with the Vehicle Licensing Agency and pays for the insurance with Specialists Insurers

Key Information

Organisation DLT Public address
Vehicle Licensing Agency ripple rhSktMK7XTQUpaFRUQEwyXkUr3PbdhtY84
Specialist Insurers ethereum 0x09085e217f06199d5Aa5370A88e9Bbf822CaE84F

Setup the shop methods

  • Create and store for the shop
    • Bitcoin account
    • Ripple account
    • Ethereum account
  • Fund all addresses in the accounts through a faucet with some initial values
  • Check balances on all three addresses

Create the car buyer methods

  • Create and store bitcoin account
  • Fund bitcoin account
  • Check balance of bitcoin account
  • Buy a car 🙂 Create/Sign/Send transaction
    • Transaction for X BTC to Shop BTC address with message "Car Make / Model"

Continue shop methods

  • Get transactions by Transaction ID
  • Register and Insure Vehicle
  • Create/Sign/Send multi-chain transaction
    • Vehicle License Agency (ripple) with message TransactionId & Vehicle Registration Number (VRN)
    • Specialist Insurers (ethereum) with message TransactionId & Car / Make / Model
  • Check balances
  • Get transactions by MappId