gosdk

README

0chain/gosdk

The Züs client SDK written in Go programming language.

• GoSDK - a Go based SDK for Züs dStorage
  • Züs Overview
  • Installation
  • Mobile Builds(iOS and Android)
  • Exposing a gosdk function to mobilesdk
  • Export a gosdk function to WebAssembly
  • Running Unit Tests
  • FAQ

Overview

Züs is a high-performance cloud on a fast blockchain offering privacy and configurable uptime. It is an alternative to traditional cloud S3 and has shown better performance on a test network due to its parallel data architecture. The technology uses erasure code to distribute the data between data and parity servers. Züs storage is configurable to provide flexibility for IT managers to design for desired security and uptime, and can design a hybrid or a multi-cloud architecture with a few clicks using Blimp's workflow, and can change redundancy and providers on the fly.

For instance, the user can start with 10 data and 5 parity providers and select where they are located globally, and later decide to add a provider on-the-fly to increase resilience, performance, or switch to a lower cost provider.

Users can also add their own servers to the network to operate in a hybrid cloud architecture. Such flexibility allows the user to improve their regulatory, content distribution, and security requirements with a true multi-cloud architecture. Users can also construct a private cloud with all of their own servers rented across the globe to have a better content distribution, highly available network, higher performance, and lower cost.

The QoS protocol is time-based where the blockchain challenges a provider on a file that the provider must respond within a certain time based on its size to pass. This forces the provider to have a good server and data center performance to earn rewards and income.

The privacy protocol from Züs is unique where a user can easily share their encrypted data with their business partners, friends, and family through a proxy key sharing protocol, where the key is given to the providers, and they re-encrypt the data using the proxy key so that only the recipient can decrypt it with their private key.

Züs has ecosystem apps to encourage traditional storage consumption such as Blimp, a S3 server and cloud migration platform, and Vult, a personal cloud app to store encrypted data and share privately with friends and family, and Chalk, a high-performance story-telling storage solution for NFT artists.

Other apps are Bolt, a wallet that is very secure with air-gapped 2FA split-key protocol to prevent hacks from compromising your digital assets, and it enables you to stake and earn from the storage providers; Atlus, a blockchain explorer and Chimney, which allows anyone to join the network and earn using their server or by just renting one, with no prior knowledge required.

Installation

Supported Platforms

This repository currently supports the following platforms:

• Mac OSX Mojave 10.14.5 or Above
• Linux (Ubuntu/bionic): This includes all Ubuntu 18+ platforms, so Ubuntu 19, Linux Mint 19 etc. (apt based package installer)
• Linux (RHEL/CENTOS 7+): All Releases based on RHEL 7+, Centos 7+, Fedora 30 etc. (yum based package installer)

Instructions

• Go is required to build gosdk code. Instructions can be found here

1. Save below code as sdkversion.go

   package main
   
   import (
       "fmt"
   
       "github.com/0chain/gosdk/zcncore"
   )
   
   func main() {
       fmt.Println("gosdk version: ", zcncore.GetVersion())
   }
   

2. Run below command: (if you don't have gosdk already in your GOPATH)

   go get github.com/0chain/gosdk
   

3. Build the sample application sdkversion

   go build -o sdkversion sdkversion.go
   

4. Run the executable

   ./sdkversion
   

5. If it prints the gosdk version installed then setup is complete.

Mobile Builds

• gosdk can be built for iOS and Android using gomobile.
• Xcode Command Line Tools is required to build the SDK for iOS.
• Android studio with NDK is required to build the SDK for Android.
• See FAQ for installing Go, gomobile Xcode or Android Studio.

Steps:

1. Run the command below for the first time to setup the gomobile environment:

   make setup-gomobile
   

2. In case the Go package is not found in golang.org/x/mobile/bind, run: go get golang.org/x/mobile/bind

3. Run below commands in the root folder of the repo to build the Mobile SDK:

   For iOS only:
           make build-ios
   For Android only:
           make build-android
   

Expose a gosdk function to mobilesdk

Examples:

• mobilesdk/sdk/common.go, which exports the functions in core/encryption/hash.go.

Steps:

1. If you are exposing:

   • a new function from an existing file, such as zboxcore/sdk/allocation.go, you should add a function to mobilesdksdk/zbox/allocation.go. This new function should call the gosdk function you intend to expose.
   • a function from a new file, you should create a new <filename>.go file for it. This should follow the same style as mobilesdksdk/zbox/allocation.go. In the new file, call the gosdk function you intend to expose.

2. Build the Mobile SDK as mentioned in the 'Mobile Builds' section of this file to build the aar file used in the mobile application you are developing.

Export a gosdk function to WebAssembly

Examples:

• wasmsdk/ethwallet.go which exports the functions in zcncore/ethwallet.go.
• wasmsdk/wallet.go which exports one function in zcncore/wallet.go.

Steps:

1. If you are exporting:

   • a new function from zcncore/wallet.go, you should add to wasmsdk/wallet.go

   • a function from a new file, you should create a new <filename>.go file for it, in the same style as wasmsdk/wallet.go or wasmsdk/ethwallet.go

2. In func main(), https://github.com/0chain/gosdk/wasmsdk/proxy.go, you need to add this line:

       js.Global().Set("YOURFUNC", js.FuncOf(YOURFUNC))
   

3. Now you need to compile a new <any_name>.wasm (e.g. proxy.wasm). Currently, the right version to compile wasm is with Go version 1.16. So make sure you have it to make the wasm build works properly. In order to compile, run the following command:

   $ GOOS=js CGO_ENABLED=0 GOARCH=wasm go build -o <any_name>.wasm github.com/0chain/gosdk/wasmsdk
   

An important note regarding export of an async function

If your golang function needs to suport asynchronous execution, you need to add more wrapper code where you are returning a Promise object.

See "InitZCNSDK" example:

func InitZCNSDK(this js.Value, p []js.Value) interface{} {
	blockWorker := p[0].String()
	signscheme := p[1].String()

	handler := js.FuncOf(func(this js.Value, args []js.Value) interface{} {
		resolve := args[0]
		// reject := args[1]

		go func() {
			err := zcncore.InitZCNSDK(blockWorker, signscheme)
			if err != nil {
				fmt.Println("error:", err)
			}
			resolve.Invoke()
		}()

		return nil
	})

	// Create and return the Promise object
	promiseConstructor := js.Global().Get("Promise")
	return promiseConstructor.New(handler)
}

Running Unit Tests

BLS unit test

It's advisable to put GOPATH as $TOP/../go, to avoid conflicts with this command: go build ./...

To run all the unit tests in gosdk: go test github.com/0chain/gosdk/zboxcore/sdk -v

$ go test ./...

To run all the unit tests in bls0chain_test.go, run this command from $TOP: go test github.com/0chain/gosdk/core/zcncrypto -v

To run a specific unit test in bls0chain_test.go, such as TestSignatureScheme, run: go test github.com/0chain/gosdk/core/zcncrypto -v -run TestSignatureScheme

To run the coverage test in gosdk:

$ go test <path_to_folder> -coverprofile=coverage.out
$ go tool cover -html=coverage.out

WebAssembly

Using go test

1. You need to install nodejs first, see this page for further instructions

2. Add /path/to/go/misc/wasm to your $PATH environment variable (so that go test can find go_js_wasm_exec). For example in Ubuntu, run $export PATH=$PATH:/usr/local/go/misc/wasm/.

3. You can then run the test by following the BLS unit test above by adding the prefix environment GOOS=js CGO_ENABLED=0 GOARCH=wasm:

   go test -tags test -v github.com/0chain/gosdk/wasmsdk
   

Test in the client

1. After you successfully export the wasm package to proxy.wasm, you can test the exported proxy.wasm.

2. We currently have a test page going at the js-client-sdk repo: https://github.com/0chain/js-client-sdk/blob/gosdk/test/index.html

3. You can replace the proxy.wasm at https://github.com/0chain/js-client-sdk/blob/gosdk/test/proxy.wasm

4. You need to start a special test server in order to stream WASM files. Use the following command from js-client-sdk $TOP: sudo php -S localhost:82 test/server.php

5. See "testethwallet" function in index.html for how the testing for ethwallet.go is done.

6. To test the function you exported, it's probably as simple as calling "HelloWorld()". It should be a 1-liner.

How to install ffmpeg

On Ubuntu Linux

sudo apt-get install ffmpeg
sudo apt-get install v4l-utils

FAQ

• How to install GO on any platform
• How to install different version of GO
• How to use go mod
• What is gomobile
• About XCode
• Android Studio
• Android NDK