sdk-core-kotlin

Title
Description
Long Description
XYO Origin Block Protocol
Getting Started
Install
Building and Testing with Gradle
Origin Chain
Bound Witness
Node Listener
Testing
Maintainers
Contributing
License
Credits

This README.md document is an overview of the common methods that you may need when integrating the XYO Core SDK into your project.

For an easy to use entry integration guide, take a look at our Sample App Guide

Description

Library to preform all core XYO Network functions which includes

Creating an origin chain
Maintaining an origin chain
Negotiations for talking to other nodes
Other basic functionality

Long Description

A library to preform all core XYO Network functions. This includes creating an origin chain, maintaining an origin chain, negotiations for talking to other nodes, and other basic functionality. The library has heavily abstracted modules so that all operations will work with any crypto, storage, networking, etc.

Read the Yellow Paper

The XYO protocol for creating origin-blocks is specified in the XYO Yellow Paper. In it, it describes the behavior of how a node on the XYO network should create Bound Witnesses. Note, the behavior is not coupled with any particular technology constraints around transport layers, cryptographic algorithms, or hashing algorithms.

Getting Started

Install

You can add sdk-core-kotlin to your existing app by cloning the project and manually adding it to your build.gradle or by using JitPack.

Build From Source

Clone from github

git clone git@github.com:XYOracleNetwork/sdk-core-kotlin.git
Add project to settings.gradle

    include ':sdk-core-kotlin'
    project(':sdk-core-kotlin').projectDir = new File('../sdk-core-kotlin')

Include in project

    implementation project (':sdk-core-kotlin')

Using JitPack

With Gradle

Point maven to https://jitpack.io

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

Include sdk-core-kotlin in dependencies

dependencies {
   implementation 'com.github.XYOracleNetwork:sdk-core-kotlin:v3.0.36'
}

With Maven

Point maven to https://jitpack.io

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

Include sdk-core-kotlin in dependencies

<dependency>
   <groupId>com.github.XYOracleNetwork</groupId>
   <artifactId>sdk-core-kotlin</artifactId>
   <version>Tag</version>
</dependency>

Building and Testing with Gradle

Building Source is located in /src/main/*

gradle build

You should start by setting up an interface to this library through creating an origin chain creator object.

Origin Chain

Through an origin chain creator object one can create and maintain an origin chain.

val originChain = XyoOriginChainCreator(blockRepo, stateRepo, hash)

// a key value store to store persist state and bound witnesses
val storage = XyoInMemoryStorageProvider()

// a hash implementation for the node to hash with
val hasher = XyoBasicHashBase.createHashType(XyoSchemas.SHA_256, "SHA-256")

// a place to store all off the blocks that the node makes
val blockRepo = XyoStorageOriginBlockRepository(storage, hasher)

// a place to store all of the origin state (index, keys, previous hash)
val stateRepo = XyoStorageOriginStateRepository(storage)

// the node object to create origin blocks
val node = XyoOriginChainCreator(blockRepo, stateRepo, hasher)

After creating a node, it is standard to add a signer, and create a genesis block.

// creates a signer with a random private key
val signer = XyoSha256WithSecp256K.newInstance()
    
// adds the signer to the node
node.originState.addSigner(signer: signer)

// creates a origin block with itself (genesis block if this is the first block you make)
node.selfSignOriginChain()

After creating a genesis block, your origin chain has officially started. Remember, all of the state is stored in the state repository (XyoOriginChainStateRepository) and the block repository (XyoOriginBlockRepository) that are constructed with the node.

Both repositories are very high level and can be implemented for one's needs. Out of the box, this library comes with an implementation for key value store databases (XyoStorageOriginBlockRepository) and (XyoStorageOriginChainStateRepository).

The XyoStorageProvider interface defines the methods for a simple key value store. There is a default implementation of an in memory key value store that comes with this library (XyoInMemoryStorage).

Creating Origin Blocks

After a node has been created, it can be used to create origin blocks with other nodes. The process of talking to other nodes has been abstracted through use of a pipe (e.g. tcp, ble, memory) that handles all of the transport logic. This interface is defined as XyoNetworkPipe. This library ships with a and a tcp client and server pipe.

Using a TCP Pipe

Client

// creates a socket with the peer
val socket = Socket("myarchivist.com", 11000)

// creates a pipe so that we can send formatted data through the socket
val pipe = XyoTcpPipe(socket, null)

// create a handler so that we can do the starting handshake with the node
val handler = XyoNetworkHandler(pipe)

// create the bound witness with the node on the socket
val newBoundWitness = node.boundWitness(handler, testProcedureCatalogue).await()

Server

// create a tcp server on port 11000
val server = XyoTcpServer(11000)

// listen from the server for connection events
server.listen { pipe ->
	// put bound witness into new thread (optional)
	GlobalScope.launch {
	
				// create a handler so that we can do the starting handshake with the node
	    	val handler = XyoNetworkHandler(pipe)
		
				// do the bound witness with the node
	    	val newBoundWitness = nodeTwo.boundWitness(handler, XyoBoundWitnessCatalog).await()
	}
}

Further examples of interacting through a socket can be found here.

Bound Witness

Adding Custom Data to a Bound Witness

node.addHeuristic("MyHeuristic", object : XyoHeuristicGetter {
	// will get called right before the bound witness starts
	override fun getHeuristic(): XyoBuff? {
	    if (conditionIsMet()) {
	    	// object will be put into the bound witness
				return getMyHeuristic()
	    }

	    // object will not be put into the bound witness 
	    return null
	}
})

Node Listener

Adding a Listener to a Node

node.addListener("MyListener", object : XyoNodeListener {
	override fun onBoundWitnessDiscovered(boundWitness: XyoBoundWitness) {
		// will get called when a new bound witness if found
	}

	override fun onBoundWitnessEndFailure(error: Exception?) {
		// will get called when a bound witness errors out
	}

	override fun onBoundWitnessEndSuccess(boundWitness: XyoBoundWitness) {
		// will get called when a bound witness is completed
	}

	override fun onBoundWitnessStart() {
		// will get called when a bound witness starts
	} 
})

Testing

All tests can be found in /src/test/*

gradle test

Maintainers

Carter Harrison

License

See the LICENSE.md file for license details.

Credits

Made with 🔥and ❄️ by XYO

renatrazumov / sdk-core-kotlin