@kiltprotocol/augment-api

TypeScript Interfaces for the KILT Network

This package provides TypeScript interfaces for data structures and transaction types used on the KILT blockchain. It improves the developer experience when using @polkadot/api to interact with the KILT blockchain and is required for the use of @kiltprotocol/sdk-js in a TypeScript development environment.

Getting Started

Installation

1. Ensure you have the latest versions of @polkadot/api and (optionally) @kiltprotocol/sdk-js.
2. If using @polkadot/api alone, also include @kiltprotocol/type-definitions in your project. These definitions must be passed to the API constructor. For detailed guidance, refer to its package documentation.

To install, run:

yarn add --dev @kiltprotocol/augment-api

Basic Integration

Add the following import at the beginning of your application's entry point:

// this import should be made at the earliest point possible
import '@kiltprotocol/augment-api'
// imports of other KILT or Polkadot packages should follow
import { connect } from '@kiltprotocol/sdk-js'

const api = await connect('wss://…')
// api is now augmented with types for the latest Spiritnet runtime
api.tx.did.dispatchAs()

Specific Runtime Augmentation

We release types corresponding to each runtime version of our mainnet and testnet, aligned with the blockchain client releases.

Mainnet and Testnet Types

To use types for a specific runtime version, simply pin their corresponding client release version:

yarn add --dev @kiltprotocol/augment-api@1.11300.0

For the Peregrine testnet, append -peregrine:

yarn add --dev @kiltprotocol/augment-api@1.11300.0-peregrine

To always use the latest Peregrine testnet types, use the peregrine distribution tag:

yarn add --dev @kiltprotocol/augment-api@peregrine

Advanced Features

Regenerating Types

Each version of the package indicates, via peer dependencies on @polkadot/api & @polkadot/typegen, which versions of these packages were used to generate types.

Sometimes definitions of Polkadot built-in runtime components change between releases of these libraries, resulting in type conflicts when trying to use the generated types with a different release. If you need to use divergent @polkadot/api versions in your project, you can run the generator scripts to regenerate type definitions based on your local configuration.

Requirements

• Add @polkadot/typegen to your package dependencies, matching your version of @polkadot/api.
• Ensure you have typescript and @kiltprotocol/type-definitions installed.

Regenerate types using:

yarn run kilt_reaugment

For persistency across installations, we recommend adding a postinstall script to your package.json:

{
  "scripts": {
    "postinstall": "yarn run kilt_reaugment"
  }
}

Generating Types for Alternative Runtimes

The kilt_reaugment script can also generate types for other KILT runtimes, such as for our staging or standalone chains. Run yarn kilt_reaugment --help to learn more about its command line arguments.

This functionality is best used in combination with the kilt_updateMetadata package script, which fetches runtime metadata and version information from a blockchain client:

yarn run kilt_updateMetadata -e wss://peregrine.kilt.io

This creates a file with the chain's metadata, along with a .env.kilt file that changes the default behavior of kilt_reaugment to perform type generation based on this metadata file.

Commit these files to your project and include kilt_reaugment in your postinstall script (see above) to ensure types are always up-to-date with your project metadata.