Module: Protocols - ninazeina/SXP GitHub Wiki

Before using our Establisher protocol, it is highly recommended to familiarize yourself with the Blockchain technology, SmartContracts, and mostly with Ethereum, a decentralized application that runs smart contracts on its blockchain. Our whole deploying contract protocol relies on two modules: Establisher (itself composed of a sub-module Network) and EthereumJ, which is implemented by Establisher. The main goal of our protocol is to deploy a contract on a blockchain based on the wishes and the terms defined by two SXP users.

• Establisher and EstablisherListener.
• EthereumJ a pure Java implementation of the Ethereum Protocol, an Ethereum client.
• EthereumSXP Interface that use EthereumJ.

• EthereumImpl implements synchronization of the blockchain, deploy a contract and call its functions.
• BlockChainEstablisher implements Establisher protocol.

Establisher is a protocol which connect two peers and allow them to communicate through jxta service, and that implements the Java implementation protocol of Ethereum, EthereumJ. jxta is a service we implemented by ourselves.
Usage is the following : connecting two peers and allowing them to exchange about whether they want to make a deal or not on the SXP free market. If they will to do so, Establisher creates a contract written in Solidity (high-level language similar to JavaScript, used to write SmartContracts), based on the terms defined by the user who firstly wanted to make a trade, then launch the EthereumJ client that will compile the corresponding contract and deploy it on the Ethereum blockchain, so it could be signed.
As said above in the intro, Establisher is composed of a module named Network, we describe his functionalities below.

Establisher is a service which is added to every peer the moment of its creation (when SXP is launched for exemple : you can use them to start synchronizing a blockchain in order to deploy a contract).
Once User1 (let's call it Owner now) has defined the items he wants to trade, and more globally the terms of the contract, he needs to send the contract to User2 (let's call it Client now). In order to do so :

• Retrieve the Establishers :

(BlockChainEstablisher) peer1.getService("establisher");
(BlockChainEstablisher) peer2.getService("establisher");

• Add connected listeners (optional)

establisher1 = addListener(NewContractListener(), peer2.getUni());  
establisher2 = addListener(NewContractListener(), peer1.getUni());  

• Initialize Owner Establisher

establisher1.initialize(true, "Owner") /* true defines Owner as the.. owner of the contract */

• Sending ContractMessage

establisher1.sendContract("Contract1", peer1.getUni(), itemVoulu.getId(), itemAEchanger.getId(), getPeer2().getUni());

From now on, Client receive a message that indicates an exchange request, and have to give his Wish :

establisher2.sendWish($WISH, peer2.getUni(), peer1.getUni());  

Where $WISH is of the form 'wish.ACCEPT/REFUSE/NEUTRAL'.

This module is the part of the protocol that allows two peers to communicate via services like jxta. In order to create a service for P2P communication with SXP project, one must go trough the following steps :

• Create a Class MessageSample extends MessagesImpl in network/impl/messages with the elements of your message in a String format (see messages samples in the package).
• Create an Interface ServiceSample extends Service in network/api . Implement this Interface with a Name that will allow you to identify the service in use, and with some writing-messages methods (see ContractService in the same package).
• Create a class JxtaServiceSample extends JxtaService implements ServiceSample in network/impl/jxta that implements some sending-messages methods, and a pipe MsgEvent that stores an Event whenever a user sends a MessageSample (see JxtaContractService).

Note that it is not an absolute necessity to use listeners. You'll however need to add a new service in PeerFactory

git clone https://github.com/ninazeina/SXP.git /* in the repository of your choice */

Establisher is used by SXP, but you don't need to "call it". see EthereumJ Usage below.
For testing purposes :

gradle test --tests controller*

• Benjamin Soriano, Nina Thiongane

EthereumJ is an Ethereum client. It is a pure Java implementation of the Ethereum protocol.
This client allows us to create or retrieve a SmartContract, compile it into bytecode, deploy it on the Ethereum blockchain, and call its inherent functions later. EthereumJ gets the contract from Establisher, then call the Solc compilator, which compiles contacts written in Solidity into bytecode. Once our contract is compiled, EthereumJ synchronizes with the Ethereum blockchain and deploy our contract on it via a specific transaction. Then we are able to call the functions inherent to our SmartContract, and "modify" its state, like signing a transaction, for exemple. We made our protocol in a way that future developers of our project won't have to code or manipulate EthereumJ, but only using it via SXP. In order to do so, we made a jar with our pre-configured Ethereumj package, which we added in the libs directory of our SXP project. Of course we will detail how to install EthereumJ as a independant module, so that you could configure it as you will.

Note that each transaction on the blockchain will cost you a small amount of ether, you can use this address for testing purposes only :

• Address : 0f3bce1d0d5bf08310c53965260b6d0ae3e5b06f
• Private Key : 287fc6941394e06872850966e20fe190ad43b3d0a3caa82e42cd077a6aaeb8b5

Of course we insist that this is for testing purposes only, NEVER give your private key to anyone. It is possible to mine ether to your address, you can contact us if there is no more ether stored at this address, we'll mine some for you !

• Alexis Mestrallet, Philippe Risch

As an independent module :

From command line (Linux users only) :

> git clone https://github.com/ethereum/ethereumj     /*In the repository of your choice*/
> cd your_path/ethereumj
> ./gradlew build 

You can also change the configuration of ethereumj by editing the ethereumj.conf file (in ethereumj-core/src/main/resources/). It allows you to choose the blockchain you want to use for example (line 145), or the range of peers you want to connect to.. everything is customizable here to your needs. for full installation options, see the official repository here : EthereumJ

• Launch a sample :

./gradlew run [-PmainClass=<sample class>]

• Launch a synch with a specific blockchain (Ropsten for example):

./gradlew runRopsten (lauching run instead of runRopsten run the Homestead Blockchain)

See ethereumj-core/build.gradle for all tasks.

• Add https://oss.jfrog.org/libs-snapshot/ as a repository to your build script
• Add a dependency on org.ethereum:ethereumj-core:${VERSION}, where ${VERSION} is of the form 1.3.9-RELEASE.

As an exemple, insert this bloc into your build.gradle file, above others dependencies or repositories.

repositories {
    maven {
    	url 'https://oss.jfrog.org/libs-snapshot/'
    }
}

dependencies {
	compile 'org.ethereum:ethereumj-core:1.3.9-RELEASE'
}

> cd ethereumj
> cp ethereumj-core/src/main/resources/ethereumj.conf ethereumj-core/src/main/resources/user.conf
> vim ethereumj-core/src/main/resources/user.conf # adjust user.conf to your needs
> ./gradlew clean shadowJar

We adjusted user.conf to our needs, by adding these lines :

# List of the peers to start
# the search of the online peers
# values: [ip:port, ip:port, ip:port ...]
    peer.discovery.ip.list = [
        "94.242.229.4:40404",
        "94.242.229.203:30303"
    ]

# Network id
    peer.networkId = 3

# the folder resources/genesis
# contains several versions of
# genesis configuration according
# to the network the peer will run on
    genesis = ropsten.json

# Blockchain settings (constants and algorithms) which are
# not described in the genesis file (like MINIMUM_DIFFICULTY or Mining algorithm)
# The possible named presets are:
# - main : the main network (Frontier-Homestead-...)
# - morden: Morden test network
# - testnet: Ethercamp test network
# - olympic: pre-Frontier Olympic network
# For custom network settings please refer to 'blockchain.config.class'
    blockchain.config.name = "ropsten"


# place to save physical storage files
# can be either absolute or relative path
    database.dir = database-ropsten

Just copy/past you JAR file in the libs folder of your SXP project :

cp your_path/ethereumj/ethereumj-core/build/libs/your_jar.jar your_path/SXP/libs/

In order to deploy a contract, a solid comprehension of what a blockchain is and how it works is essential. Contracts are written in a high level programming-language similar to JavaScript. Usage of Solidity is recommended, as it is the most common way to write a contract for deployment purpose.
We created a Java class which fully implements the org.ethereum package. By doing so, we abstracted the Ethereumj module so that we don't need to modify it to use it. We implemented all our methods in that class : EthereumjImpl.java. It is essential to synchronized a blockchain before attempting anything. That's why we are using an EthereumListener in order to check it, before going through the followings steps.
All the methods described below are commented in our code, for full understanding check EthereumImpl.java

Learn more about contracts ! Now that you've mastered the basics of Ethereum blockchain and its related contracts, let's begin with your first typical contract, a (very) simple calculator :

contract Sample {  
           int i;  
            function inc(int n) {  
               i = i + n;
            }
            function get() returns (int) {
              return i;
            }
};

This contract is really basic, composed of two functions which respectively increase the value of a given integer and then returns it.
Now before being able to deploy it though, we need to compile that contract. Contracts live on the blockchain in an Ethereum-specific binary format (Ethereum Virtual Machine (EVM) byte-code). Contracts are typically written in some high level language and then compiled into byte code to be uploaded on the blockchain.

Note that other languages than solidity also exist, notably Serpent and LLL. Legacy Mutan (an early c-like language) is no longer officially maintained. Note that a powerful online real-time Solidity-compilator allows you to write corrects contracts directly in your web-navigator here, so that you know your contract can be compiled before integrating it in your code.

So, at this stage, you'll need two things: the compiled code, and the Application Binary Interface, which is a JavaScript Object that defines how to interact with the contract. We are using EthereumJ client since it fits our needs perfectly, however you can start by using geth which is the official Ethereum client in order to apprehend the concepts of compiling, deploying and mining. And more importantly, managing your Ethereum accounts. Note that you need to reformat your contract by removing line-breaks so it fits into a string variable, before being able to call your compilation methods on it. You can use these tools.

Once again, we made a method which manage to create a new transaction with the compiled contract in it, and then deploy it on the chosen blockchain. Our method success only if the contract is effectively stored in the blockchain. For instance, in SXP, users will be able to sign each side separately. EthereumJ displays a lot of useful informations, such as a summary of the deploying state of the contract (hash, receive address, sender address, signature...). To check whether your transaction successfully made it to the blockchain or not, it is wise to use the Ethereum Scanner by placing the hash of your transaction in the search bar. So we do now have the address of our deployed contract, which will be useful to call the inherent functions of our contract.

Now that your contract is (at least !) successfully deployed on the blockchain, all of the contracts functions are operational and ready to be called. However calling a function from a contract is far from easy with EthereumJ, so we simplified it by adding methods that abstract the complexity of the process in our code. Calling the function of a contract means to create a new transaction, deploy it and modifying the state of the contract.
Just know that you need to call the functions you defined in your contract to execute them, for example calling get() in our Sample contract returns the value of the variable i.

Now that you have all the elements in hands, you will be able to create your own protocol using EthereumJ.
Our Establisher protocol connect two peers for an exchange, however we need two users with a valid Ethereum account. So we tested Establisher and EthereumImpl separately. In order to test EthereumImpl, simply launch a ./gradlew run from the SXP folder.

## Improvements

Once solved the peer issue, we'll be able to fully add a valid Ethereum implementation in Establisher.
The SmartContract we are deploying could be improved to, with more specific functions :

• Cancel the SmartContract after a certain amount of time without two valid signatures.
• We made some access-security functions that are not implemented and will be of use once solved the peer issue.
• We could add a test which checks the hash of the SmartContract deployed on the blockchain so we are sure it wasn't modified during the whole process.
• Make it possible to choose a specific blockchain in an easier way than modifying user.conf.