Skip to main content

Quick Start

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​

The SDK must be initialized before use. This process includes fetching the appropriate WASM file and then initializing the WASM.

Fetching the WASM​

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

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

  2. Upload your WASM file for wasmBaseUrl config:

    • You can place it in your website’s static assets folder.

      • Example Folder Structure for Static Assets
          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

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

    • Place it in your website’s static assets folder:

      Example Folder Structure for Static Assets
      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.

App.jsx
import { useWasmLoader } from '@zerochain/sdk/dist/react'

export const App = () => {
  const [isWasmLoaded, setIsWasmLoaded] = useState(false)

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

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

  // ...
}

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({
  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'
  },

  // 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.
SwitchWasmMode.tsx
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 */})
  }

  // ...
}

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)
}