JS SDK

This page will specifically guide you through setting up a project using the Züs JS SDK. For detailed API documentation, please refer to the API Reference.

Install Züs JS SDK

The Züs JS SDK is available as a package on NPM for use with a module bundler:

npm install @zerochain/sdk

Initialize the SDK

Before using the SDK, it must be initialized. This process involves loading the required scripts, fetching the appropriate WASM file, and then initializing the WASM.

Adding Required Scripts

Include the following scripts in the <head> of your HTML:

<script
  defer
  src="https://cdn.jsdelivr.net/gh/herumi/[email protected]/browser/bls.js"
/>
<script
  defer
  src="https://cdn.jsdelivr.net/gh/golang/[email protected]/misc/wasm/wasm_exec.js"
/>

The WASM relies on the scripts above and requires specific versions to function correctly. Make sure to use the exact versions listed. These may be updated periodically based on the latest WASM v1.x.x release requirements.

Fetching the WASM

There are two WASM file types available, standard and enterprise.

Download the appropriate WASM file(s):
- Standard WASM is for interacting with a Standard Allocation:
  - Download zcn.wasm from the "Assets" section of any GoSDK Release here
- Enterprise WASM is for interacting with an Enterprise Allocation:
  - Download enterprise-zcn.wasm from the "Assets" section of any eGoSDK Release here
Upload your WASM file for wasmBaseUrl config:
- You can place it in your website’s static assets folder.
  - public/ |--wasm/ | |--zcn.wasm | |--enterprise-zcn.wasm
  - In this case, set the wasmBaseUrl config to /wasm.
- Alternatively, you can upload it to a web server or CDN.
  - For example, if wasmBaseUrl is set to https://example.com/wasm, the WASM files should be located at:
    https://example.com/wasm/enterprise-zcn.wasm for the Enterprise WASM
    https://example.com/wasm/zcn.wasm for the Standard WASM
Upload the md5worker.js file for the md5WorkerUrl config:
- This is optional if you are not using upload features of the SDK. This includes using SDK methods like multiUpload and bulkUpload. {/* DOTODO: update link to multiUpload and bulkUpload */}
- Place it in your website’s static assets folder:
  public/ |--md5worker.js
  - In this case, set the md5WorkerUrl config to md5worker.js.
- Alternatively, use the CDN URL for the md5WorkerUrl config. :::warning

This is strongly not recommended as it is used only in Zus apps like Vult, Blimp & Chalk and may change in the future, potentially breaking your app.

import { useWasmLoader } from '@zerochain/sdk/dist/react'
export const App = () => {
  const [isWasmLoaded, setIsWasmLoaded] = useState(false)

   // highlight-start
  const loadWasm = useWasmLoader({
    onLog: (type, log) => console[type]('WASM LOG:', log.message),
    setIsWasmLoaded,
  })
  // highlight-end

  // Using useEffect to ensure the `window` object is accessible
  useEffect(() => {
    // highlight-start
    loadWasm({
      md5WorkerUrl: 'md5worker.js',
      wasmBaseUrl: '/wasm', // Or, 'https://example.com/wasm'
    })
    // highlight-end
  }, [loadWasm])

  // ...
}
```

import { wasmLoader } from '@zerochain/sdk'

const loadWasm = wasmLoader({
  onLog: (type, log) => console[type]('WASM LOG:', log.message),
  setIsWasmLoaded: isWasmLoaded => updateMyUI(isWasmLoaded),
})

loadWasm({
  md5WorkerUrl: 'md5worker.js',
  wasmBaseUrl: '/wasm', // Or, 'https://example.com/wasm'
})

Fetching WASM with Caching Support

The SDK supports caching the WASM file for faster access. This is not enabled by default, but you can modify the loadWasm config to enable it.

Set useCachedWasm to true.
Configure cacheConfig based on your WASM file type:
- For Enterprise WASM, set enterpriseGosdkVersion and enterpriseWasmUrl.
- For Standard WASM, set standardGosdkVersion and standardWasmUrl.
Optionally, set wasmBaseUrl as a fallback. (Reference)

loadWasm({
  // highlight-start
  useCachedWasm: true,
  cacheConfig: {
    enterpriseGosdkVersion: process.env.EGOSDK_VERSION, // Example: '1.18.5'
    enterpriseWasmUrl: process.env.EGOSDK_WASM_URL, // Example: 'https://example.com/wasm/enterprise-zcn.wasm'
    standardGosdkVersion: process.env.GOSDK_VERSION, // Example: '1.18.17'
    standardWasmUrl: process.env.GOSDK_WASM_URL, // Example: 'https://example.com/wasm/zcn.wasm'
  },
  // highlight-end

  // Set other options as needed
  md5WorkerUrl: 'md5worker.js',
  wasmBaseUrl: '/wasm', // Or, 'https://example.com/wasm'
});

Switching between WASM modes

The SDK provides updateWasmMode for switching between WASM modes.

First call updateWasmMode with the desired WASM mode.
Then call loadWasm with the proper config.

import { useWasmLoader } from '@zerochain/sdk/dist/react'
import { updateWasmMode } from '@zerochain/sdk'

export const SwitchWasmMode = () => {
  const loadWasm = useWasmLoader({ /** ... */})

  const switchWasmMode = (newWasmMode: "normal" | "enterprise") => {
    updateWasmMode(newWasmMode)
    loadWasm({ /** Your loadWasm config */})
  }

  // ...
}

import { wasmLoader } from '@zerochain/sdk'
import { updateWasmMode } from '@zerochain/sdk'

const loadWasm = wasmLoader({ /** ... */})

const switchWasmMode = (newWasmMode: "normal" | "enterprise") => {
  updateWasmMode(newWasmMode)
  loadWasm({ /** Your loadWasm config */})
}

Next Steps

Now that the SDK is initialized, you can start using its methods in your application. Check out the API Reference.

Example: Logging the WASM version

import sdk from '@zerochain/sdk'

async function logWasmVersion() {
  const version = await sdk.getGosdkVersion(domain)
  console.log('WASM Version:', version)
}

Last updated 7 months ago