-
Notifications
You must be signed in to change notification settings - Fork 30
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1631 from 0chain/hotfix/update-readme
Revert readme changes
- Loading branch information
Showing
1 changed file
with
220 additions
and
18 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,33 +1,235 @@ | ||
| <!-- Code generated by gomarkdoc. DO NOT EDIT --> | ||
| # 0chain/gosdk | ||
|
|
||
| # gosdk | ||
| The Züs client SDK written in Go programming language. | ||
|
|
||
| ```go | ||
| import "github.com/0chain/gosdk" | ||
| - [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 | ||
|
|
||
| ### 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](https://go.dev/doc/install) | ||
|
|
||
| 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](#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) | ||
| } | ||
| ``` | ||
|
|
||
| ## Index | ||
| ## 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` | ||
| - [type Timestamp](<#Timestamp>) | ||
| - [func Now\(\) Timestamp](<#Now>) | ||
| ```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` | ||
| <a name="Timestamp"></a> | ||
| ## type [Timestamp](<https://github.com/0chain/gosdk/blob/doc/initial/play.go#L13>) | ||
| 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` | ||
| Timestamp represents Unix time \(e.g. in seconds\) | ||
| To run the coverage test in `gosdk`: | ||
| ```go | ||
| type Timestamp int64 | ||
| ```bash | ||
| $ go test <path_to_folder> -coverprofile=coverage.out | ||
| $ go tool cover -html=coverage.out | ||
| ``` | ||
| <a name="Now"></a> | ||
| ### func [Now](<https://github.com/0chain/gosdk/blob/doc/initial/play.go#L16>) | ||
| ### 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 | ||
|
|
||
| ```go | ||
| func Now() Timestamp | ||
| ```bash | ||
| sudo apt-get install ffmpeg | ||
| sudo apt-get install v4l-utils | ||
| ``` | ||
|
|
||
| Now \- current datetime | ||
| ### FAQ | ||
|
|
||
| Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>) | ||
| - [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/) |