oak.js OAK Network JavaScript SDK

The oak.js library is a JavaScript extension of polkadot.js.

It provides type decorations for OAK Network functions. It requires the installation of the following packages:

• @oak-network/api-augment, available at npmjs.com/@oak-network/api-augment
• @oak-network/types, available at npmjs.com/@oak-network/types

JavaScript and TypeScript developers can leverage this library to make OAK-specific API calls, such as timeAutomation.scheduleXcmpTask. For more information on OAK's unique API, refer to the Time Automation Explained in Documentation guide.

In addition, it provides an SDK to help developers simplify the use of automation. It includes the following packages:

• @oak-network/config, available at npmjs.com/@oak-network/config
• @oak-network/adapter, available at npmjs.com/@oak-network/adapter
• @oak-network/sdk, available at npmjs.com/@oak-network/sdk

Usage for the Foundational library

Installation

Run the following commands to install the latest packages:

npm i @oak-network/api-augment
npm i @oak-network/types

Including the Library in Your Code

To include the library in your code, refer to the code snippet provided in ./demo/src for Time Automation code. In summary, the following lines will add type checking of OAK extrinsics to the existing polkadot.js library:

require('@oak-network/api-augment');
const { rpc, types } = require('@oak-network/types');
const { ApiPromise, WsProvider, Keyring } = require('@polkadot/api');

Usage of the SDK Library

Installation

Run the following commands to install the required packages:

npm i @oak-network/config@latest
npm i @oak-network/adapter@latest
npm i @oak-network/sdk@latest

Developing Applications with the SDK

To develop applications using the SDK, you can refer to the test code as an example. Here's a step-by-step guide:

• Start by exporting configurations from @oak-network/config.

• Construct a Polkadot API.

• Build and initialize an adapter. Utilize the methods provided by the adapter for standard operations.

• For more complex operations that involve data exchange between multiple adapters, such as scheduleXcmpTaskWithPayThroughRemoteDerivativeAccountFlow, you can leverage the functions provided by the SDK package.

For example:

// Create keyringPair
keyringPair = await getKeyringPair();

// Get configs
const turingConfig = getOakConfig();
const mangataConfig = getMangataConfig();

// Initialize adapters
turingApi = await ApiPromise.create({ provider: new WsProvider(turingConfig.endpoint), rpc, types, runtime });
turingAdapter = new OakAdapter(turingApi, turingConfig);
await turingAdapter.initialize();

mangataSdk = Mangata.getInstance([mangataConfig.endpoint]);
mangataApi = await mangataSdk.getApi();
mangataAdapter = new MangataAdapter(mangataApi, mangataConfig);
await mangataAdapter.initialize();

// Make task payload extrinsic
const taskPayloadExtrinsic = mangataApi.tx.system.remarkWithEvent('hello!');

// Schedule task with sdk
const executionTimes = [getHourlyTimestamp(1)/1000];
await Sdk().scheduleXcmpTaskWithPayThroughSoverignAccountFlow({
	oakAdapter: turingAdapter,
	destinationChainAdapter: mangataAdapter,
	taskPayloadExtrinsic,
	schedule: { Fixed: { executionTimes } },
	keyringPair,
});

Development

If you would like to develop or test the code in this repository, please follow the guidelines below.

Pre-requisites

Yarn version needs to be equal to or higher than 2 to use Yarn Workspace feature of this monorepo. First run the following command to check the version of Yarn:

yarn --version

Then if yarn version is lower than 2, run the following command to upgrade:

yarn set version berry

Installation

Run the following command to install the necessary dependencies:

yarn # Please use yarn to install dependencies due to the use of Yarn Workspace

Maintaining dependencies across packages

The packages are referring each other by source code, so when one is updated, the new version will be used by other packages. For example, ./packages/sdk/package.json has the following dependency:

"@oak-network/adapter": "../adapter",
"@oak-network/config": "../config"

Running Functional Tests

By default, the tests are configured to target your local development environment. Before running any commands, please follow the steps in the Quickstart: run Local Network with Zombienet guide to build and run a local relay chain and parachain.

Once the Turing Dev network is running, you should be able to see it on polkadot.js.org/apps.

The default WebSocket endpoint is ws://127.0.0.1:9946 and the default test wallet is Alice (6AwtFW6sYcQ8RcuAJeXdDKuFtUVXj4xW57ghjYQ5xyciT1yd).

You can start the tests by running the following command:

yarn run test

Please note that the tests are not meant to be repeatedly run against live networks. However, you can run them against the Turing Staging environment using the following command:

ENV="Turing Staging" MNEMONIC="<MNEMONIC>" yarn run test

You can also specify the endpoint in the Turing Dev environment:

MNEMONIC="<MNEMONIC>" ENDPOINT="ws://127.0.0.1:9944" yarn run test

SDK Tests

You can start the tests by running the following command:

MNEMONIC="<MNEMONIC>" ENV="Turing Staging" yarn run test:sdk

If you wish to perform local testing, you'll need to launch the parachain test network yourself using the following command:

zombienet spawn zombienets/turing/moonbase.toml

This command will initiate the test network for parachains.

Then, you'll need to specify a test suite since each suite executes tests for a single parachains.

yarn run test:sdk -- -t test-mangata

Compound Tests

If you wish to perform local testing, you'll need to launch the parachain test network yourself using the following command:

zombienet spawn zombienets/turing/single-chain.toml

If the account hasn't been delegated on-chain yet, you can execute the following command to test the delegateWithAutoCompound interface.

MNEMONIC="<MNEMONIC>" ENV="Turing Dev" yarn run test:delegate

If the account has already been delegated on-chain, or if you've previously tested the delegateWithAutoCompound interface, you can execute the following command to test the delegatorBondMore, setAutoCompound, getDelegation, and getAutoCompoundingDelegationPercentage interfaces.

MNEMONIC="<MNEMONIC>" ENV="Turing Dev" yarn test:compound

File structure

.
├── LICENSE
├── README.md
├── babel.config.js
├── demo
├── jest.config.js
├── media
├── package.json
├── packages
│   ├── adapter
│   ├── api-augment
│   ├── config
│   ├── sdk
│   └── types
├── scripts
│   └── package-setup
├── templates
│   └── index.cjs
├── test
│   ├── functional
│   ├── sdk
│   └── utils
├── tsconfig.build.json
├── tsconfig.json

• packages: It store individual code libraries for various parts of the project.
• scripts/package-setup: It is a script used for building packages. It utilizes templates/index.cjs as a script.
• test: The test folder contains test programs. test/functional is used for testing the Foundational library, while test/sdk is used for testing the SDK library.
• demo: It contains example code for developers to learn from.

Updating the packages

To update the code of both packages in this repository, you will first need to run a local version of the Turing Network. Then, using a script and leveraging the chain's API, you can automatically update the TypeScript code in the packages.

1. Run Turing Network Locally

Follow the instructions in the OAK-blockchain GitHub repository to clone the source code and set up the Rust version. Build and run the project. Additionally, set up zombienet to spawn a local network. Assuming zombienet is installed and you are in the OAK-blockchain directory, run the following command:

zombienet spawn zombienets/turing/single-chain.toml

2. Update Packages

You are now ready to update the packages' code in this oak.js project. From the root of this project, run the following commands:

yarn
cd packages/api-augment
yarn run clean:defs
yarn run generate

3. Rebuilding packages

The last step is to build the packages' source code in preparation for publishing. Navigate back to the root of the oak.js directory and run the following commands:

yarn run clean
yarn run build

The build command will generate distribution files under packages/*/build.

Publishing the Packages

The release creation and publishing process is managed by GitHub Actions. It's important to note that package versions don't need to be consistent across all packages. For example, if changes are made to the api-augment library, there's no requirement to bump the version of the types library as well.

To publish packages, please follow the steps outlined below:

1. Generate Changeset Marking File: To initiate a version update, start by running the command yarn run changeset locally. This action will create a marking file in the ./changeset directory. An example of such a change can be found in this PR: example PR link.

2. Automated Package Version Update: After the aforementioned PR is merged into the main branch, a GitHub Action will be triggered by the created marking file. This action will automatically generate a new PR, updating the versions of all packages simultaneously. You can observe this process in action with this PR: example PR link. Should you need to add additional changes to the same version, simply repeat step 1 to create another marking file and merge it into the main branch. The original PR associated with the main branch will be updated automatically. Furthermore, a corresponding git tag will be generated for each package as part of this process.

3. Testing with Dev Version: If everything appears satisfactory, proceed to merge the above-mentioned PR. Following the successful merge, manually trigger the Publish dev version workflow. This will lead to the publishing of an NPM package version with the dev tag, facilitating thorough testing.

4. Updating to Latest Tag: Once confident with the outcome of the dev testing phase, manually initiate the Update dev tag to latest workflow. This workflow will update the npm tag from dev to latest, signifying the readiness of the package for broader use.

You should receive an email from [email protected] if the package is successfully published.