Zilliqa Developer Tools & Documentation

zilliqa-developer is a Bazel based monorepo that contains SDKs, documentations and products used to develop solutions based on the Zilliqa ecosystem.

This repository is organised as follows:

• docs/: Pure documentation in md or mdx format.
• examples/: Reference material.
• zilliqa/: APIs and libraries (JS SDK, Python SDK, etc/)
• products/: Software products(ceres, devex, neosavant, oil etc.)

Detailed documentation of the Zilliqa ecosystem is found in docs/.

Product targets contained in this repository are released as follows: TODO(tfr): following table is a place holder:

Target	Release page	Notes
//products/developer-portal	portal.zilliqa.com	Contains //docs
//products/dev-wallet	wallet.zilliqa.com
//products/devex	devex.zilliqa.com
//products/ceres	zilliqa.com/apps
//products/neo-savant	ide.zilliqa.com

Building

To disable our git queries on build, set the DISABLE_WORKSPACE_STATUS environment variable. This loses version information, but speeds builds and stops you having to touch your security key on every bazel run.

Prerequisites

This repository is based on the Bazel build tool. Bazel builds are mostly self-contained because Bazel downloads dependencies and arrange them in your workspace. The only external tools we rely on is

• Bazelisk, ibazel or Bazel 5.2
• Pnpm / Npm / Yarn
• Python 3.6 or newer
• Trunk 1.0 or newer

While the repository can be built directly with Bazel, we recommend that you either use Bazelisk or ibazel as these will manage the Bazel version used. The following guide assumes you will be using Bazelisk.

On most platforms you can install Bazelisk using NPM:

npm install -g @bazel/bazelisk

On macOS, Bazelisk is also available using brew:

brew install bazelisk

Likewise on Windows, it can be installed using choco:

choco install bazelisk

Once installed, verify that Bazelisk is correctly installed by running

bazelisk --help

In case of issues, please refer to the official documentation.

Building

To build a target, run

bazelisk build [target_name]

where target_name is the target you want to build. Targets can be found in the respective BUILD files and we will also briefly cover how to find them from the commandline in the Listing targets section.

As a concrete example, you can build the all the Zilliqa Javascript SDK targets as:

bazelisk build //zilliqa/js/...

or you can pick out a specific target as

bazelisk build //zilliqa/js/util:pkg

Building documentation

To build and run the docker image for the documentation locally, run

ibazel run //products/developer-portal:dev-image

This will start a server on port 8000. If ibazel is used, the Docker image will recompile everytime you make a file change to anything in the dependency list.

You can also run the main server on as

ibazel run //products/developer-portal:image

which is served on port 80.

Building libraries

Building and publishing zilliqa-js

Checkout out the repository. First ensure that tests are passing:

bazelisk test //zilliqa/js/...

Next navigate to the zilliqa/js folder. If you have not done so, install all dependencies:

pnpm i

Then build all libraries:

pnpm -r build

Finally, publish:

pnpm -r publish

Add --dry-run in the event you want to test publish without publishing anything.

Building and running Docker images

For the purpose of building Docker images, you do not need Docker installed whereas if you wish to run the generated image, you do need Docker.

To build the image execute:

bazelisk build //products/isolated-server:latest

To populate the image to the local Docker registry:

bazelisk run //products/isolated-server:latest

You can now verify that the image is in your local registry by running:

docker images | grep products/isolated-server:latest

To run the image, you need Docker installed

docker run -it bazel/products/isolated-server:latest

Running executable targets

Bazel can run an executable target directly from the build tool. This is done as

bazelisk run [target_name]

This can be used while developing products.

Testing

Testing follows the same pattern as described above, but using the test command instead:

bazelisk test [target_name]

Similar to when building, you can request to run multiple tests:

bazelisk test //zilliqa/js/...

The above command would run all tests related to the Zilliqa Javascript SDK. TODO(tfr): No tests enabled yet.

Code formatting and style checking

To maintain a consistent style accross the repository we use trunk.io to manage various linters and code formatters.

To check your code:

trunk check

To format your code where possible:

trunk fmt

This step is enforced by CI.

Listing targets

Often it is useful to list targets and/or dependencies of targets. Here we provide a few To list all targets:

bazelisk query "//..."

To list targets in a subfolder:

bazelisk query "//zilliqa/..."

To find the dependencies of at target

bazelisk query "deps(//zilliqa/js/util:pkg)"

Useful notes on Bazel

To get verbose error messages add --verbose_failures.

If you experience issues with Bazel determining relevant toolchain for C++, try adding the argument --toolchain_resolution_debug=@bazel_tools//tools/cpp:toolchain_type to help debug.

If you experience that it is difficult to understand what folder structure Bazel builds, add --sandbox_debug

To get all output from tests, use --test_output=all

Sometimes while debugging it is helpful to clean all to aviod artefacts from previous builds: bazel clean --expunge

To get information about your current Bazel setup run bazelisk info.

If you get bored with bazel constantly asking you for your password/to authenticate via your key, add --workspace_status_command=echo to your command line. Use DISABLE_WORKSPACE_STATUS with ibazel (since ibazel doesn't pass command line options on to bazel).

Reasoning Behind Repository Organisation

This repository is organised as follows:

• docs/: Pure documentation in md or mdx format.
• exmaples/: Reference material.
• zilliqa/: APIs and libraries (JS API, GO API, etc/)
• products/: Software products(ceres, devex, neosavant, oil etc.)

The idea with keeping it all in one repository is as follows:

1. When someone would make a breaking change to the JS Api which would break ceres, devex and two API examples this would be caught before the change makes it into main, and whoever responsbile for the change would also be responsible for updating all broken products as part of that update.

2. The documentation and examples are kept closer to the source code hence making it possible to request an update of docs during the review of a new code piece (as opposed to create a ticket on the backlog, which is under the danger of never being addressed)

3. For our different components, it would be substantially easier to make sure that all are using the same version of a given library. For instance, if the JS API is depending on BN.js version 4.11.8 but the devex product uses version 5.2.1, this possibly leads to incompatibility between devex and the API component. By keeping the two together, we can ensure that releases are done simultaneously and that they rely on the same library version to avoid tedious bugs that are hard to find..