[![](https://user-images.githubusercontent.com/39338561/122415864-8d6a7c00-cf88-11eb-846f-a98a936f88da.png)
](https://kilt.io)

# 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](https://github.com/KILTprotocol/types-augment/blob/main/packages/type-definitions/README.md).

To install, run:

```bash
yarn add --dev @kiltprotocol/augment-api
```

### Basic Integration

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

```typescript
// 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](https://github.com/KILTprotocol/kilt-node/releases).

### Mainnet and Testnet Types

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

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

For the Peregrine testnet, append `-peregrine`:

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

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

```bash
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:

```bash
yarn run kilt_reaugment
```

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

```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:

```bash
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.