Webb Tools API 🕸️

🚀 Webb Tools API 🚀
_{⚠️ Beta Software ⚠️}

📖 Table of Contents

Table of Contents

• Getting Started
• Usage
• Testing
• Contributing
• License

Getting Started 🎉

This library provides additional typing information for user to access Webb's modules by using polkadot.js.

For additional information, please refer to the Webb Tools API reference docs or Webb Tools Official Documentation 📝. Have feedback on how to improve webb.js? Or have a specific question to ask? Checkout the Webb Dapp Feedback Discussion 💬.

Package layout

packages/
  |____api/                 # Contains necessary options to create a polkadot.js API instance.
  |____api-derive/          # Routines and helper functions utilizing webb's api package.
  |____app-util/            # Utilities to work with Webb Network.
  |____sdk-core/            # The package provides a cleaner API to the underlying `wasm-utils`.
  |____test-utils/          # Common testing setup and helper functions.
  |____wasm-utils/          # Wasm utils for generating zero-knowledge proof and deposit notes. Consumed by `sdk-core`.

Prerequisites

This repository makes use of node.js, yarn, Rust, and requires version 16. To install node.js binaries, installers, and source tarballs, please visit https://nodejs.org/en/download/. Once node.js is installed you may proceed to install yarn:

npm install --global yarn

Great! Now your Node environment is ready! 🚀🚀

To install Rust, we will make use of https://rustup.rs installer and the rustup tool to manage the Rust toolchain.

First install and configure rustup:

# Install
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Configure
source ~/.cargo/env

Configure the Rust toolchain to default to the nightly version, add nightly and the nightly wasm target:

rustup default nightly
rustup update
rustup update nightly

This repository makes use of wasm-pack for bindings between javascript and webassembly generated from rust. Install it with:

curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

Great! Now your Rust environment is ready! 🦀 🦀

Lastly, install

• DVC is used for fetching large ZK files and managing them alongside git
• substrate.io may require additional dependencies

🚀🚀 Your environment is complete! 🚀🚀

Installation 💻

Once the development environment is set up, you may proceed install the required dependencies.

yarn install

To build:

yarn build

To fetch fixtures:

dvc pull

Usage

Quick Start ⚡

In order to make use of @webb-tools/api you will need to have a node available and running. Below we assume you have started a node locally, but you may also make use of our deployed Tangle Network Minerva Parachain Testnet.

Install package dependencies

yarn add @polkadot/api @webb-tools/api@beta

Create API instance

import { ApiPromise } from '@polkadot/api';
import { WsProvider } from '@polkadot/rpc-provider';
import { options } from '@webb-tools/api';

async function main() {
    // the node endpoint
    const provider = new WsProvider('ws://localhost:9944');
    const api = new ApiPromise(options({ provider }));
    await api.isReady;

    // use the api
    //..
}

main()

Use api to interact with node

// query and display account data
const data = await api.query.system.account('5Dqf9U5dgQ9GLqdfaxXGjpZf9af1sCV8UrnpRgqJPbe3wCwX');
console.log(data.toHuman());

Usage examples

We have included implementation examples for using this API to interact with an Anchor and Mixer.

To run the above mentioned usage examples you will need to use the experimental module loader and start a local substrate chain. In addition please ensure you have updated the fixtures by running:

dvc pull

Once started you may run the following command from root:

# Runs the Anchor usage example script
NODE_OPTIONS="--loader ./loader.js" node ./examples/node/substrate/anchor.ts

# Runs the Mixer usage example script
NODE_OPTIONS="--loader ./loader.js" node ./examples/node/substrate/mixer.ts

Testing 🧪

The following instructions outlines how to run webb.js API unit test suite and integration test suite.

Note: You will need to run yarn build prior to running test suite. For integration tests, a Docker daemon must also be available.

To run all tests - unit, integration, wasm, providers

yarn test

To run unit tests

yarn test:unit

To run integration tests

yarn test:integration

To run wasm tests

yarn test:wasm

To run providers test

yarn test:providers

Contributing

Interested in contributing to Webb.js? Thank you so much for your interest! We are always appreciative for contributions from the open-source community!

If you have a contribution in mind, please check out our Contribution Guide for information on how to do so. We are excited for your first contribution!

Lint before you push! 🪥

Please ensure you lint and format your changes prior to opening a PR.

To lint:

yarn lint

To format:

yarn format

License

Licensed under Apache 2.0 license.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache 2.0 license, shall be licensed as above, without any additional terms or conditions.

Supported by