txwrapper-core

Tools for FRAME chain builders to publish chain specific offline transaction generation libraries.

Table of contents

• Overview
• End user examples
• Chain builder guide
• Develop, contribute, and maintain

Overview

The polkadot.js based txwrapper suite of packages provides chain builders with the tools to quickly create, test, and maintain a library of helper functions for offline transaction generation with their chain. End users can then use these chain specific packages to create an offline transaction workflow. (We sometimes refer to chain specific libs as txwrappers.)

For example, those looking to construct a transaction offline on Polkadot would require @substrate/txwrapper-polkadot. @substrate/txwrapper-polkadot is built by requiring @substrate/txwrapper-core, @substrate/txwrapper-registry, @substrate/txwrapper-substrate and re-exporting utilities and dispatchables relevant to Polkadot.

Packages

Published

• @substrate/txwrapper-polkadot Helper functions for offline transaction generation for polkadot relay and system chains; specifically the following chains: Polkadot, Kusama, Rococo, Westend, Statemint and Statemine.
• @substrate/txwrapper-core The essentials for creating a chain specific txwrapper lib.
• @substrate/txwrapper-registry Registry creation support, catering to chains with types in @polkadot/apps-config.
• @substrate/txwrapper-substrate Selected dispatchables of Substrate pallets, to be re-exported by txwrappers (e.g. @substrate/txwrapper-polkadot).
• @substrate/txwrapper-orml Selected dispatchables of ORML pallets, to be re-exported by txwrappers (e.g. txwrapper-acala).

Non-published

• @substrate/txwrapper-example Usage examples including how to construct, sign, and decode an extrinsic with @substrate/txwrapper-polkadot.
• @substrate/txwrapper-template Template package for chain builders.
• txwrapper-acala PoC of how a FRAME-based chain can leverage txwrapper packages to create a txwrapper. N.B. This is only for PoC usage and not intended to be published by txwrapper-core repo maintainers.

End user examples

Click here for examples on how to use txwrappers for constructing, signing, and decoding transactions.

Chain builder guide

Click here to find our guide for chain builders. The guide explains how to make a chain specific txwrapper.

Develop, contribute, and maintain

Develop

Install dependencies:

yarn install

Build all packages:

yarn run build

Contribute

We welcome contributions!

Before submitting your PR, make sure to run the following commands

Run all tests:

yarn run test

Run the linter:

yarn run lint

# or to automatically fix warnings:

yarn run lint --fix

Release & Publishing

Preparation

1. Checkout a branch name-update-deps, and ensure we have the latest polkadot-js dependencies by running the command below. If all packages are already up to date you may skip to the "Publishing" section below. Note: what follows assumes yarn at version 2.4.2 or above.

yarn up "@polkadot/*"

2. Ensure there are no issues by running the following commands. If any type errors occur due to the updated dependencies, you may file an issue here.

yarn run build
yarn run test
yarn run lint

3. If all tests pass and all packages build successfully, commit your changes with the following format fix(types): Update polkadot-js deps to get the latest types. Then push your branch up to Github for review, then merge. The release tooling takes care of bumping the version so no need for a manual update (see below).

Publishing

This libraries release process uses Lerna, and the following below is required to have a successful release.

• N.B. Ensure you have GH_TOKEN env variable set to a GitHub personal access token (PAT) so lerna can publish the release on github.

• The publisher will need publishing permissions to the @substrate npm org.

1. Make sure to be in the main branch, and git pull origin main.

2. Before deploying a new release run the following sanity checks.

yarn run build
yarn run test

3. Deploy the new release.

yarn run deploy

NOTE (Yubikey Warning): This repo requires signed and verified commits, so when using a yubikey there is a step where you are required to sign a commit while Lerna sets up the github release. The output from Lerna won't warn you that you have to sign it so the release will error, and you will have to git reset --hard <last-commit-hash> and rm -rf lerna-debug.log. When you see the following message, sign your underlying Lerna commit with your Yubikey to avoid the error.

? Are you sure you want to create these versions? Yes
lerna info execute Creating releases...