gosdk

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 30 Open GitHub ↗

A client SDK in Go to interface the blockchain and storage platform, and other smart contracts

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 0chain/gosdk

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

- [GoSDK - a Go based SDK for Züs dStorage]()
  - [Züs Overview ](#overview)
  - [Installation](#installation)
  - [Mobile Builds(iOS and Android)](#mobile-builds)
  - [Exposing a gosdk function to mobilesdk](#expose-a-gosdk-function-to-mobilesdk)
  - [Export a gosdk function to WebAssembly](#export-a-gosdk-function-to-webassembly)
  - [Running Unit Tests](#running-unit-tests)
  - [FAQ](#faq)

## Overview

[Züs](https://zus.network/) 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](https://blimp.software/) 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](https://medium.com/0chain/qos-protocol-weekly-debrief-april-12-2023-44524924381f) 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](https://zus.network/build) 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](https://blimp.software/), a S3 server and cloud migration platform, and [Vult](https://vult.network/), a personal cloud app to store encrypted data and share privately with friends and family, and [Chalk](https://chalk.software/), a high-performance story-telling storage solution for NFT artists.

Other apps are [Bolt](https://bolt.holdings/), 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](https://atlus.cloud/), a blockchain explorer and [Chimney](https://demo.chimney.software/), which allows anyone to join the network and earn using their server or by just renting one, with no prior knowledge required.

## Installation

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)

### Step 1: Create a New Project Folder
Open your terminal and run:
```bash
mkdir zus-go-demo
cd zus-go-demo
```
This creates and enters a new folder named `zus-go-demo`.

### Step 2: Initialize a Go Module
Run:
```bash
go mod init zus-go-demo
```
This creates a `go.mod` file that declares this folder as a Go module. You'll use this file to track dependencies like the Züs SDK.

If you are using VS Code, you can use the `code` CLI command to open the folder:
```bash
code .
```
If not, open VS Code manually and open the `zus-go-demo` folder from the File menu.

### Step 3: Install Züs SDK from staging Branch
In your terminal:
```bash
go get github.com/0chain/gosdk@staging
```
This tells Go to pull the latest code from the `staging` branch of the SDK repo.

**Expected output:**
```
go: added github.com/0chain/gosdk v1.8.18-0.20230901213317-53d640a9b7f9
```
This is a pseudo-version that references a specific commit on the `staging` branch.

### Step 4: Create Your `main.go` File
In the root of `zus-go-demo`, create a file named `main.go` and paste this:
```go
package main

import (
	"fmt"

"github.com/0chain/gosdk/zcncore"
)

func main() {
	fmt.Println("Züs Go SDK is ready!")
	fmt.Println("SDK Version:", zcncore.GetVersion())
}
```
This imports the SDK and prints its version.

### Step 5: Tidy Up Your Dependencies
Run:
```bash
go mod tidy
```
This cleans up the `go.mod` and `go.sum` files by removing unused and downloading used dependencies.

If you hadn’t imported anything yet, you might see a warning like:
```
go: warning: "all" matched no packages
```
If you see a missing `go.sum` entry error (e.g., after importing packages), and `go mod tidy` does not fetch dependencies, try:
```bash
go mod tidy -e
```
The `-e` flag tells Go to continue downloading even if errors are detected.

### Step 6: Run Your Project
Run the Go file:
```bash
go run main.go
```
This confirms that the SDK is installed, imported, and running.

Alternatively, you can build the sample application:
```bash
go build -o main main.go
```
Run the executable:
```bash
./main
```
If the GoSDK version is printed successfully, the installation 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](#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:

```golang
       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:

```bash
   $ 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:

```golang
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`

```bash
$ 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`:

```bash
$ 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](https://nodejs.org/en/download/) 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](#bls-unit-test) above by adding the prefix environment `GOOS=js CGO_ENABLED=0 GOARCH=wasm`:
   ```bash
   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](#how-to-export-a-gosdk-function-to-webassembly), 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

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

### FAQ

- [How to install GO on any platform](https://golang.org/doc/install)
- [How to install different version of GO](https://golang.org/doc/install#extra_versions)
- [How to use go mod](https://blog.golang.org/using-go-modules)
- [What is gomobile](https://godoc.org/golang.org/x/mobile/cmd/gomobile)
- [About XCode](https://developer.apple.com/xcode/)
- [Android Studio](https://developer.android.com/studio)
- [Android NDK](https://developer.android.com/ndk/)

gosdk

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README