Skip to content

Typed Codecs

Overview

In advanced use cases -mainly for library authors or developer tool creators- it’s often necessary to tap into the codecs used in different chain interactions. This is exactly what the getTypedCodecs API offers: a strongly-typed interface that grants access to all relevant codecs as defined in a chain’s metadata.

This API is particularly helpful when you need to manually encode or decode values for runtime storage, calls, constants, or events, without relying on runtime type guessing.

Let’s take a look at how this works in practice.

Example: Manual Storage Entry Encoding

Suppose you're in a development environment and want to manually set a storage entry for XcmPallet.Queries. Here’s how getTypedCodecs helps:

import { getTypedCodecs } from "polkadot-api"
import {
  dot,
  XcmPalletQueryStatus,
  XcmV4Response,
  XcmVersionedResponse,
} from "@polkadot-api/descriptors"
 
const codecs = await getTypedCodecs(dot)
const xcmQueriesCodecs = codecs.query.XcmPallet.Queries
 
export const encodedValue = xcmQueriesCodecs.value.enc(
  XcmPalletQueryStatus.Ready({
    at: 100000,
    response: XcmVersionedResponse.V4(XcmV4Response.Null()),
  }),
)
 
export const encodedKey = xcmQueriesCodecs.args.enc([100n])

You get fully typed access to both key and value encoders for any storage item, safely and with full IDE support.

Example: Inner Enum Variant Codec

Need to access the codec for a specific enum variant, like XcmPalletQueryStatus.Ready? You can go even deeper:

import { getTypedCodecs } from "polkadot-api"
import {
  dot,
  XcmV4Response,
  XcmVersionedResponse,
} from "@polkadot-api/descriptors"
 
const codecs = await getTypedCodecs(dot)
 
codecs.query.XcmPallet.Queries.value.inner.Ready.enc({
  at: 100,
  response: XcmVersionedResponse.V4(XcmV4Response.Null()),
})

You can directly encode the structure required by the Ready variant of the enum. And again, the entire structure is strongly typed.

🎥 Want to see this in action? Check out this short video to experience the powerful DX this API offers:

Deep Dive: The Codec System

To fully understand getTypedCodecs, it's important to grasp the underlying building blocks: Codec, Encoder, Decoder, and ShapedCodec.

What Is a Codec?

In polkadot-api, a Codec is an interface that groups together a SCALE Encoder and a Decoder.

Encoder

An encoder is simply:

type Encoder<T> = (value: T) => Uint8Array

It outputs a SCALE-encoded byte array from a typed value.

Decoder

A decoder has this signature:

type Decoder<T> = (value: Uint8Array | ArrayBuffer | HexString) => T

It accepts a SCALE-encoded value and returns the corresponding decoded structure.

The Codec Interface

A Codec<T> bundles both encoder and decoder, and also exposes them in two ways:

  1. As a tuple:

    const [encoder, decoder] = Vector(u16)

  2. As properties:

    const codec = Vector(u16)
 
const encoded = codec.enc([1, 2, 3])
const decoded = codec.dec(encoded)

Here’s the full type:

type Codec<T> = [Encoder<T>, Decoder<T>] & {
  enc: Encoder<T>
  dec: Decoder<T>
}

The ShapedCodec Interface

Some codecs are primitive (e.g., u8, bool, str) while others are complex (e.g., Struct, Enum, Tuple, Vector).

Complex codecs are represented by a ShapedCodec<T>, which extends the Codec<T> interface with an inner property that exposes its components—with full type safety.

type ShapedCodec<T> = Codec<T> & {
  inner: SomeMagicTsToInferTheInnerShapeOfThisType<T>
}

📘 Curious how the inner shape is inferred? Take a look at the implementation

What matters here is: complex structures like Enums or Structs let you navigate their internal parts, each fully typed and codec-enabled.

Wrapping Up

The getTypedCodecs API provides powerful introspection and manipulation tools for any type defined in your chain’s metadata—without sacrificing type safety or developer ergonomics.

It’s ideal for:

  • Devtools that need precise encoding/decoding logic
  • Test tooling that interacts with low-level storage or runtime APIs
  • Manual transaction crafting
  • Chain simulation and debugging tools

You can use it in combination with descriptors generated by the CLI, and the codecs align 1:1 with the types exposed by the TypedApi.