External App Tutorial

This tutorial will focus on how to create an app on top of OneLedger blockchain protocol. This app will be referred as "external app" in this tutorial.

Introduction

Blockchain is a Distributed Ledger Technology (DLT), that abstracts away trust among 2 or more parties by introducing a technology that is unhackable, immutable and trusted. Any use case that involves trust between 2 or more parties, is where blockchain can be applied, and so it’s thought of regularly in Supply Chain and Logistics, Finance, Insurance, Litigation, Health Care and many others.

Unlike Bitcoin with Proof of Work (PoW), OneLedger blockchain network is based on Proof of Stake (PoS), which will increase transactions per second (TPS) and create sidechains for higher throughput.

An external app will contains 4 layers in total to utilize the OneLedger blockchain network.

• Data Layer: store varies data that will be used in the app
• Transaction Layer: any actions in the blockchain system will be executed as a transaction, and this transaction will be processed multiple times in the blockchain network to let all the blockchain node reach a consensus state.
• RPC Layer: in order to interact with blockchain network, for example, trigger the transactions in transaction layer, or query data from data layer, we need RPC layer to be able to make RPC request to block chain network.
• Block Function Layer: block function provides the ability to run transactions without manually triggering it by RPC request, it will allow automatic or routine based transaction to be executed.

0. Pre-Start

System Requirements

Ensure your system meets the following requirements:

Operating System must be one of the following:

• macOS
  • Ensure Xcode Developer Tools is installed(only command line version is needed)
• A Debian-based Linux distribution
  • Ubuntu is recommended for the smoothest install, otherwise you will have to set up your distribution for installing PPAs
• Go version 1.11 or higher
• git

Configurations

Setup Environment Variables

Use which go to check were Golang is installed

In your .bashrc or .zshrc file, set up environment variables as below:

export GOPATH="folder for all your Golang project"
export PATH=$PATH:$GOPATH/bin
export GO111MODULE=auto
export GOROOT="folder where Golang is installed"
export OLROOT="$GOPATH/src/github.com/Oneledger"
export OLTEST="$OLROOT/protocol/node/scripts"
export OLSCRIPT="$OLROOT/protocol/node/scripts"
export OLSETUP="$OLROOT/protocol/node/setup"
export OLDATA="$GOPATH/test"

and source it(choose .bashrc or .zshrc that you are using)

source ~/.bashrc

Install ClevelDB

For Ubuntu:

sudo apt-get update
sudo apt install build-essential

sudo apt-get install libsnappy-dev

wget https://github.com/google/leveldb/archive/v1.20.tar.gz && \
  tar -zxvf v1.20.tar.gz && \
  cd leveldb-1.20/ && \
  make && \
  sudo cp -r out-static/lib* out-shared/lib* /usr/local/lib/ && \
  cd include/ && \
  sudo cp -r leveldb /usr/local/include/ && \
  sudo ldconfig && \
  rm -f v1.20.tar.gz

For MacOS:

brew install leveldb

Clone the repo

cd $OLROOT
git clone github.com/Oneledger/protocol

Install the required dependencies

cd ./protocol
git checkout develop
git checkout -b name-of-your-branch
make update
make install_c

If no error occurs, you are good to go.

Choose your IDE

You can use Goland or VScode. For Goland, it comes with a 30-day trial.

Steps to create an external app

It takes 8 major steps to create an external app:

• Create your external app folder
• Create error codes package
• Create data package
• Create action(transaction) package
• Create block function package
• Create RPC package
• Register the app into OneLedger Blockchain
• Create integration test using python or any script you like

This tutorial will use an example app called "bid" to show the steps you need to take to build an external app.

This example app will provide the functionality of bidding on OneLedger Naming Service.

OneLedger Naming Service: The Domains created on the OneLedger Network can be tied directly to an Account (OneLedger Address) and can be associated to a website URLs, so that Businesses can connect their web properties to a OneLedger Account and send crypto-payments to any online business.

1. Create your external app folder

Inside protocol folder, there is a folder named external_apps, everything need to be done will be in this folder.

The structure inside external_apps is shown in the below, which includes a common utility folder, an example project folder and an initialization file.

.
├── bid(example project folder)  
├── common(common utility folder)
└── init.go

The first step for external app is to create your own external app folder, just like bid as the example.

2. Create error codes package

Create error package and error codes file to define all the error codes used in your external app, you will be provided a range of error codes that are pre-allocated to this external app to avoid conflict.

All external app error codes will be a six digit number starts with 99, and for each external app, there are 100 error codes available. For example, 990100 to 990199.

All packages inside your app folder should follow the naming convention of app name + underscore + package name, such as bid_error.

.
├── bid(example project folder)  
│   └── bid_error
│       └── codes.go
├── common(common utility folder)
└── init.go

Later on you will be adding error codes into this file as below. (with your dedicated error codes)

const (
	BidErrInvalidBidConvId = 990001
	BidErrInvalidAsset = 990002
)

3. Create data package

Data package takes care of the functionality to store, set, get and iterate data related to your external app. There will be data structs to represent single entry of data object, and there will be data stores to hold the data. You can use multiple data structs or stores if needed.

Data in all stores is saved in a non-relational key-value database, with different prefix in the key we can differentiate data from different stores.

Create data folder as below

.
├── bid(example project folder)  
│   └── bid_data
├── common(common utility folder)
└── init.go

Create basic data types that will be used in the external app

Create a new file called types.go in your data package.

.
├── bid(example project folder)  
│   └── bid_data
│       └── types.go
├── common(common utility folder)
└── init.go

This file will store all the basic types you will need in the app. This way they can be easily maintained in the future.

type (
	BidConvId            string
	BidConvState         int
	BidAssetType         int
	BidConvStatus        bool
	BidOfferStatus       int
	BidOfferType         int
	BidOfferAmountStatus int
	BidDecision          bool
)

Define structs that will be used in the external app

This is the structs that you want to utilize to represent single entry of data object in the external app.

For example, this is a note if your app is a notebook, a product if your app is a product management system.

.
├── bid(example project folder)  
│   └── bid_data
│       ├── bid_conversation.go
│       └── types.go
├── common(common utility folder)
└── init.go

In bid example app, we have two different data structs, bid conversation and bid offer. Let's use bid conversation as an example.

This bid_conversation.go will at least contains a type definition and a constructor as below

⚠️ Remember to use proper json tag so that it can be successfully serialized and deserialized.

type BidConv struct {
	BidConvId   BidConvId    `json:"bidId"`
	AssetOwner  keys.Address `json:"assetOwner"`
	AssetName   string       `json:"assetName"`
	AssetType   BidAssetType `json:"assetType"`
	Bidder      keys.Address `json:"bidder"`
	DeadlineUTC int64        `json:"deadlineUtc"`
}

func NewBidConv(owner keys.Address, assetName string, assetType BidAssetType, bidder keys.Address, deadline int64, height int64) *BidConv {
	return &BidConv{
		BidConvId:   generateBidConvID(owner.String()+assetName+bidder.String(), height),
		AssetOwner:  owner,
		AssetName:   assetName,
		AssetType:   assetType,
		Bidder:      bidder,
		DeadlineUTC: deadline,
	}
}

In the bid conversation, we have the bid conversation id to make each conversation unique.

Since this app is to let people bidding on an asset that belongs to an owner, we have owner and bidder here. The data type is OneLedger address.

🛠If your data object is an entity that designed to be owned by or traded/exchanged among users, you can use keys.Address as data type for that field. This represents an address on the OneLedger blockchain network.

We also have bid asset name and type that will be used in the validation and exchange process. For example, this asset needs to be under owner's address, and it needs to be valid in the period of bidding.

4. Create action(transaction) package

5. Create block function package

6. Create RPC package

7. Register the app into OneLedger Blockchain

8. Create integration test using python or any script you like