Chronicle-Decentred

Chronicle Decentred is a framework for building a peer to peer Secure Scalable Microservices on Distributed Ledger Technology.

The purpose of this library is to make it easy to create many high throughput microservices which can be run in a decentralised manner.

Versions supported

Currently only Java 8, OpenJDK or Oracle JVMs are supported.

What features will be supported in the open source version

The open source version will

• peer to peer chains running concurrently

• a near unlimited number of chains. The theoretical limit is one bllion chains for every person in the world.

• 25K - 500K transactions per second per chain depending on hardware.

• latencies down to single digit milli-seconds (depending on network connectivity)

• testing tools for creating new transaction types

• simple decentralised consensus strategy (PoIP - Proof Of IP)

• simple exchange of value

• supports digital and fiat currencies including XCL (Chronicle Accelerate’s token)

What features will the Enterprise version have

The Enterprise version is designed to add features a commercial operator would like

• supports bursts of millions of messages per second.

• tighter latencies (sub-milli-second for Proof of Receipt)

• more options for exchange of value including continuous auctions.

• more pluggable consensus strategies

• doesn’t require a digital currency to run.

Lifecycle of a chain

There is one registry chain for finding the nodes providing any individual chain. This is required for peer chains to find each other but not to run.

• A private/public key pair for an address is created. The address includes the IPv4 address and port of the first node and is the last 6 bytes of the public key.

• This address must be verified by a majority of nodes running the registry chain.

• Once verified, the address can delegate authorirty to run the chain the initial nodes. After that a majority of nodes need to agree a transaction occurred for them to be considered to have happened.

• This chain can create any number of tokens for use in transactions on this chain. Each token has a home chain which created it.

• Peer chains can also hold value and perform transaction on these tokens.

• A chain can set the costs, comsumption rate and reward rate for any token.

Single pass transaction lifecycle

A transaction which only needs the authority of one address can be confirmed in a single pass of the blockchain.

• The holder of a private key creates a Request with an always increasing micro-second timestamp and signs the message using it’s private key.

• The Request is passed to one or more nodes in the cluster running the chain.

• Any transaction which has the same (or earlier timestamp) is ignored.

• The Request is validated by the gateway of the nodes receiving the request, and possibly rejected with a Response to the sender.

• If valid, the Request is passed to the chainer to be added to the block created by that node.

• The blocks created by each node are socialised throughout the cluster and through a consensus model agreed as to the order of those blocks.

• Once the order of blocks has been agreed by a majority of nodes, every node processes those blocks in the same order and publishes any results.

Double pass transaction lifecycle

A transaction which requires the authority of the majority of nodes running in the cluster requires two passes.

• A Request is created which follows the single pass lifecycle above, however

• The results of the transactions on each node are socialised to every other node.

• The outcome is only confirmed by a majority of nodes chosing the same result, this is published as another event with the events from each node attached as proof.

Examples of single and multi-pass transactions

Transaction	Passes
Transfer within a chain using a single address	Single pass
Transfer between a peer chain and the home chain of a token	Two passes on the peer chain and a single pass on the home chain
Transfer between a peer chain and another peer chain for a token which is homed by a third chain	Two passes on the source peer chain, two passes on the home chain and one pass on the destination chain

How does the chaining work?

Figure 1. Workflow for transactions on the blockchain

• A client connects to a server over TCP.

• The gateway receives the transaction and verifies its signature

• The gateway can process the request or query and send a reply, or it can pass the request onto the blockchain.

• Transactions passed to the blockchain are batched into blocks. Each node creates a block concurrently (as needed)

• Blocks are replicated across nodes via TCP.

• Each node gossips about the blocks it has.

• Each node votes on which blocks to include in the next round.

• Once a majority of node vote the same way, those blocks are included in the next round.

• Transaction in the next round are processed in order.

• The results of those transactions are published on all nodes.

• Events to pass back to the client are returned over TCP.

Getting started

Under examples/appreciation there is a module containing tests for transaction.

A more complex example is examples/exchange for transfer and exchange of value.

In detail

There are a number of key concepts need to understand how this works.

Addresses

Information is associated with an address. You need the private key for the public key registered to an address to alter that data.

Addresses are registered allowing them to be limited in size. Decentred uses 64-bit addresses. Addresses can be

• Base32 encoded string (top 3 bits are all set)

• IPv4:port:id (top 3 bits are not all set)

The IPv4:port:id is shorten to IPv4:port if the id is 0.

See DecentredUtils for more details.

Java Server Components and Messages

Chronicle Decentred Java Server Components and Messages are typically handled as described hereunder:

Server Components

Gateway

Receives SignedMessage application messages, validates signatures, responds to query messages that do not change any perceived state of the chain members and sends potentially state altering SignedMessage application messages to a BlockEngine.

BlockEngine

Contains and manages the following sub-components:

Chainer

Receives SignedMessage application messages from Gateway instances and produces TransactionBlockEvent messages.

Gossiper

Receives TransactionBlockEvent messages and sends TransactionBlockGossipEvent messages to Voter instances.

Voter

Receives TransactionBlockGossipEvent from Gossiper instances and sends TransactionBlockVoteEvent messages to VoteTaker instances.

VoteTaker

Receives TransactionBlockVoteEvent from Voter instances and sends EndOfRoundBlockEvent messages to BlockReplayer instances.

BlockReplayer

Replays SignedMessage application messages on participating nodes, altering the perceived state of the chain to reflect the evetns agreed upon by the voting steps above.

Messages

SignedMessage application messages

For example the messages in examples/appreciation: OpeningBalance, Give, Topup.

TransactionBlockEvent

Contains one or several SignedMessage application messages proposed to be included in the next block.

TransactionBlockGossipEvent

Constitutes a new chain state and consists of one cursor for each event producing node. The cursor determines the highest numbered event from that particular node that is included in the block.

TransactionBlockVoteEvent

Consists of a block gossip event that is proposed as next block of the chain.

EndOfRoundBlockEvent

Contains the consensus of events in the block, the outcome of a voting round.

Creating a chain

Create a private/public key pair.

The KeyPair class can help.

Send a create address request

# create a new unique id/address for the chain
createAddressRequest: {
  timestampUS: 2019-02-04T14:31:56.013465,
  address: phccofmpy6ci,
  publicKey: !!binary 9M9t8hyt2kEJmL46Fs+si0VigLTMQt9OafgMm3ljIOg=
}

# create a chain for this address
createChainRequest: {
  timestampUS: 2019-02-04T14:31:56.101034,
  address: phccofmpy6ci,
  cycleOffset: -02:00,
  roundsPerDay: 1000
}

This allows you to run a private chain for yourself, however to run it on multiple node, you have to delegate to one or more IPv4:port addresses. To do this generate an IPV4:port for each of your nodes using brute force. These can be done in parallel.

# assign five delegates to run this chain.
# 165.225.124.237:25956:3b17, 101.255.243.30:17634:9989, 143.245.75.233:729:2a88, 91.102.70.210:2096:2257, 133.194.48.160:27831:945e
assignDelegatesRequest: {
  timestampUS: 2019-02-04T15:09:06.356534,
  address: phccofmpy6ci,
  delegates: [
    !!binary 9M9t8hyt2kEJmL46Fs+si0VigLTMQt9OafgMm3ljIOg=,
    !!binary Ddk/qZ8BB63XgUsBsKCOub6IWoL9+VvvK8kaea/oJfA=,
    !!binary TsXED8x8VoxtLgRu7iPaz4aAhfQUtmvee9KRyhDKk+o=,
    !!binary WClTgi5nnngj3bIkiofts5sFv8CwMPeUEL5Y5MxKwPw=,
    !!binary B/WVrcp+P2Dv7aX5tm5YXvUDk5PKuAyk6ppDoXfIiPk=
  ]
}

Finally, Start the nodes on the IPv4:port as above