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

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zus.network/zus-docs/sdks/go-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.