Repository files navigation

Theoak.js library is a JavaScript extension ofpolkadot.js.

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

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

JavaScript and TypeScript developers can leverage this library to make OAK-specific API calls, such astimeAutomation.scheduleXcmpTask. For more information on OAK's unique API, refer to theTime 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 atnpmjs.com/@oak-network/config
• @oak-network/adapter, available atnpmjs.com/@oak-network/adapter
• @oak-network/sdk, available atnpmjs.com/@oak-network/sdk

Run the following commands to install the latest packages:

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

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 existingpolkadot.js library:

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

Run the following commands to install the required packages:

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

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 asscheduleXcmpTaskWithPayThroughRemoteDerivativeAccountFlow, you can leverage the functions provided by the SDK package.

For example:

// Create keyringPairkeyringPair = await getKeyringPair();// Get configsconst turingConfig = getOakConfig();const mangataConfig = getMangataConfig();// Initialize adaptersturingApi = 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 extrinsicconst taskPayloadExtrinsic = mangataApi.tx.system.remarkWithEvent('hello!');// Schedule task with sdkconst executionTimes = [getHourlyTimestamp(1)/1000];await Sdk().scheduleXcmpTaskWithPayThroughSoverignAccountFlow({oakAdapter: turingAdapter,destinationChainAdapter: mangataAdapter,taskPayloadExtrinsic,schedule: { Fixed: { executionTimes } },keyringPair,});

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

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

Run the following command to install the necessary dependencies:

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

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"

By default, the tests are configured to target your local development environment. Before running any commands, please follow the steps in theQuickstart: 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 onpolkadot.js.org/apps.

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

You can start the tests by running the following command:

yarn runtest

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 runtest

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

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

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

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 thedelegateWithAutoCompound 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 thedelegateWithAutoCompound interface, you can execute the following command to test thedelegatorBondMore,setAutoCompound,getDelegation, andgetAutoCompoundingDelegationPercentage interfaces.

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

.├── 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: Thetest folder contains test programs.test/functional is used for testing the Foundational library, whiletest/sdk is used for testing the SDK library.
• demo: It contains example code for developers to learn from.

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.

Follow the instructions in theOAK-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 theOAK-blockchain directory, run the following command:

zombienet spawn zombienets/turing/single-chain.toml

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

yarncd packages/api-augmentyarn run clean:defsyarn run generate

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 cleanyarn run build

The build command will generate distribution files underpackages/*/build.

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 theapi-augment library, there's no requirement to bump the version of thetypes 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 commandyarn 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 themain 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 themain branch. The original PR associated with themain branch will be updated automatically. Furthermore, a correspondinggit 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 thePublish dev version workflow. This will lead to the publishing of an NPM package version with thedev tag, facilitating thorough testing.

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

You should receive an email fromsupport@npmjs.com if the package is successfully published.