Go SDK

Functions to manage your allocations

Please Note: This SDK is subject to tremendous changes in the next releases that can be backward incompatible. Please pay close attention to our announcements on Discord.

GoSDK - Züs Client SDK for Go

GoSDK is the official Go-based Software Development Kit (SDK) for the Züs decentralized storage network. It enables developers to integrate Züs storage functionalities into their applications while providing tools for wallet management, file operations, staking, and smart contract interactions.

The SDK supports various platforms, including Linux, macOS, and Windows. Additionally, GoSDK can be built for mobile (iOS/Android) and WebAssembly (WASM) to provide broader compatibility across different environments.

gosdk/zboxcore/sdk/allocation.go at staging · 0chain/gosdkGitHub

Installation

Supported Platforms

GoSDK is compatible with the following operating systems:

• MacOS (10.14.5 or later)

• Linux (Ubuntu 18+, CentOS 7+, Fedora 30+)

• Windows (via WSL or native support)

Prerequisites

Before installing GoSDK, ensure you have:

• Go (Golang) installed: Install Go

• Go Modules enabled: Run export GO111MODULE=on in your terminal

Setup Instructions

Step 1: Create a New Project Folder

Open your terminal and run:

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:

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 code CLI installed command to open the folder.

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:

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:

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:

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:

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:

go run main.go

This confirms that the SDK is installed, imported, and running.

Alternatively you can also build the sample application:

go build -o main main.go

Run the executable:

./main

If the GoSDK version is printed successfully, the installation is complete.

Mobile SDK (iOS & Android)

Building GoSDK for Mobile

GoSDK supports mobile app development through gomobile, allowing integration with iOS and Android apps.

Prerequisites

• iOS: Requires Xcode Command Line Tools

• Android: Requires Android Studio with NDK

Verify Xcode Setup (macOS users)

To ensure Xcode is correctly referenced:

xcode-select -p

If it shows /Library/Developer/CommandLineTools, run:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

This ensures full Xcode paths are used.

Steps to Build for Mobile

1. Setup the Go Mobile environment:

   make setup-gomobile

   (If golang.org/x/mobile/bind is missing, install it using go get golang.org/x/mobile/bind)

2. Build the SDK:

   • For iOS:

     make build-ios

   • For Android:

     make build-android

Exporting GoSDK Functions

Expose a GoSDK Function to Mobile SDK

To expose GoSDK functions in Mobile SDK, follow these steps:

1. For an existing file function (e.g., zboxcore/sdk/allocation.go):

   • Add a wrapper function inside mobilesdk/sdk/zbox/allocation.go

2. For a new function:

   • Create a new Go file in mobilesdk/sdk/zbox/

   • Implement the function to call the respective GoSDK method.

3. Build the SDK again (make build-ios or make build-android).

Exporting GoSDK Functions to WebAssembly (WASM)

GoSDK can be compiled into WASM for web applications. Example functions that have been exported include:

• wasmsdk/ethwallet.go (exports Ethereum wallet functions)

• wasmsdk/wallet.go (exports core wallet functionalities)

Steps to Export a GoSDK Function to WASM

1. Modify wasmsdk/wallet.go or create a new file.

2. Register the function in WebAssembly (proxy.go):

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

1. Compile the WebAssembly binary:

GOOS=js CGO_ENABLED=0 GOARCH=wasm go build -o proxy.wasm github.com/0chain/gosdk/wasmsdk

1. Test the WASM function:

   1. Replace proxy.wasm in the test client.

   2. Run a local server (php -S localhost:82 test/server.php).

   3. Execute the exported function via JavaScript.

Running Unit Tests

GoSDK includes a test suite to validate functionality.

Running General Unit Tests

go test github.com/0chain/gosdk/zboxcore/sdk -v

Running Specific Tests

• Run all unit tests in bls0chain_test.go:

  go test github.com/0chain/gosdk/core/zcncrypto -v

• Run a single test (e.g., TestSignatureScheme):

  go test github.com/0chain/gosdk/core/zcncrypto -v -run TestSignatureScheme

Running Coverage Tests

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

WebAssembly Testing

Using go test for WASM

1. Install Node.js (Required for testing)

2. Set environment variables for WASM testing:

   export PATH=$PATH:/usr/local/go/misc/wasm/

3. Run the WASM test suite:

   GOOS=js CGO_ENABLED=0 GOARCH=wasm go test -tags test -v github.com/0chain/gosdk/wasmsdk

Other Dependencies

Installing FFmpeg (for media processing)

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

---