# Go SDK

{% hint style="warning" %}
**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](https://discord.gg/tSrXGqDy).
{% endhint %}

## **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.

{% embed url="<https://github.com/0chain/gosdk/blob/staging/zboxcore/sdk/allocation.go>" %}

### **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](https://golang.org/doc/install)
* **Go Modules enabled**: Run `export GO111MODULE=on` in your terminal

#### **Setup Instructions**

**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.

{% hint style="info" %}
You'll use this file to track dependencies like the Züs SDK.
{% endhint %}

If you are using VS code, you can use `code` CLI installed 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:

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

```
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 also build the sample application:

```sh
go build -o main main.go
```

Run the executable:

```sh
./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:

```bash
xcode-select -p
```

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

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

   ```sh
   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**:

     ```sh
     make build-ios
     ```
   * For **Android**:

     ```sh
     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`):**

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

3. **Compile the WebAssembly binary:**

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

4. **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**

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

#### **Running Specific Tests**

* **Run all unit tests in `bls0chain_test.go`**:

  ```sh
  go test github.com/0chain/gosdk/core/zcncrypto -v
  ```
* **Run a single test (e.g., `TestSignatureScheme`)**:

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

#### **Running Coverage Tests**

```sh
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:**

   ```sh
   export PATH=$PATH:/usr/local/go/misc/wasm/
   ```
3. **Run the WASM test suite:**

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

### **Other Dependencies**

#### **Installing FFmpeg (for media processing)**

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

***