KOTLIN CORE SDK

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.

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

1. Clone from github

   git clone git@github.com:XYOracleNetwork/sdk-core-kotlin.git

2. Add project to settings.gradle

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

3. Include in project

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

Using JitPack

With Gradle

1. Point maven to https://jitpack.io

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

2. Include sdk-core-kotlin in dependencies

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

With Maven

1. Point maven to https://jitpack.io

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

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

Sample Project

A sample project demonstrating integration can be found on GitHub