Custom Protobuf Types

Register custom message types in the Registry, create type-safe encode objects, and decode transactions

Every transaction message in Cosmos SDK is identified by a type URL (e.g. "/cosmos.bank.v1beta1.MsgSend") and encoded as Protocol Buffers. The Registry in @cosmjs/proto-signing maps type URLs to their codec implementations so CosmJS can encode and decode messages.

Adding Types to the Registry

Start from defaultRegistryTypes, which includes all standard Cosmos SDK message types, and add your own:

import { Registry } from "@cosmjs/proto-signing";
import { defaultRegistryTypes, SigningStargateClient, GasPrice } from "@cosmjs/stargate";

import { MsgCreatePost } from "./generated/blog/v1/tx";

const registry = new Registry(defaultRegistryTypes);
registry.register("/blog.v1.MsgCreatePost", MsgCreatePost);

const client = await SigningStargateClient.connectWithSigner(
  "https://rpc.my-chain.network",
  wallet,
  { registry, gasPrice: GasPrice.fromString("0.025utoken") },
);

Now signAndBroadcast can serialize MsgCreatePost messages:

const result = await client.signAndBroadcast(
  senderAddress,
  [
    {
      typeUrl: "/blog.v1.MsgCreatePost",
      value: MsgCreatePost.fromPartial({
        author: senderAddress,
        title: "Hello Cosmos",
        body: "This is my first post on-chain.",
      }),
    },
  ],
  "auto",
);

Registering Multiple Types

When your module has several message types, define them as an array and spread into the registry:

import { GeneratedType, Registry } from "@cosmjs/proto-signing";
import { defaultRegistryTypes } from "@cosmjs/stargate";

import { MsgCreatePost, MsgEditPost, MsgDeletePost } from "./generated/blog/v1/tx";

const blogTypes: ReadonlyArray<[string, GeneratedType]> = [
  ["/blog.v1.MsgCreatePost", MsgCreatePost],
  ["/blog.v1.MsgEditPost", MsgEditPost],
  ["/blog.v1.MsgDeletePost", MsgDeletePost],
];

const registry = new Registry([...defaultRegistryTypes, ...blogTypes]);

Supported Codec Formats

The Registry accepts types generated by any of these tools:

Generator	Interface	fromPartial	Notes
Telescope 1.x	TelescopeGeneratedType	Yes	Used by OsmoJS, Stargaze, dYdX, and others
ts-proto 1.x	TsProtoGeneratedType	Yes	Used by cosmjs-types (CosmJS’s own types)
ts-proto 2.x	TsProto2GeneratedType	Yes	Uses @bufbuild/protobuf wire format
protobufjs	PbjsGeneratedType	No (uses create)	Runtime-only type definitions, no codegen step required

All four implement encode and decode. Types with fromPartial (Telescope, ts-proto) are preferred because they allow constructing messages from partial objects without specifying every field.

See the Code Generation page for details on each tool.

Type-Safe Encode Objects

For large projects, define typed encode objects that narrow the typeUrl to a string literal. This prevents typos and gives you autocomplete on the value field:

import { EncodeObject } from "@cosmjs/proto-signing";
import { MsgCreatePost } from "./generated/blog/v1/tx";

export interface MsgCreatePostEncodeObject extends EncodeObject {
  readonly typeUrl: "/blog.v1.MsgCreatePost";
  readonly value: Partial<MsgCreatePost>;
}

export function isMsgCreatePostEncodeObject(
  o: EncodeObject,
): o is MsgCreatePostEncodeObject {
  return o.typeUrl === "/blog.v1.MsgCreatePost";
}

Use them when constructing transactions:

const msg: MsgCreatePostEncodeObject = {
  typeUrl: "/blog.v1.MsgCreatePost",
  value: MsgCreatePost.fromPartial({
    author: senderAddress,
    title: "Type-safe message",
    body: "The compiler catches typos in typeUrl.",
  }),
};

const result = await client.signAndBroadcast(senderAddress, [msg], "auto");

Decoding Transactions

The Registry also decodes incoming data. This is useful for parsing transactions from the blockchain or decoding responses:

import { decodeTxRaw } from "@cosmjs/proto-signing";

const tx = await client.getTx(txHash);
if (tx) {
  const decoded = decodeTxRaw(tx.tx);

  for (const msg of decoded.body.messages) {
    const decodedMsg = registry.decode(msg);
    console.info(`${msg.typeUrl}:`, decodedMsg);
  }
}

Without your custom types registered, registry.decode throws Unregistered type url for unknown message types. Register all types you expect to encounter before decoding.

Next Steps

Query Extensions

Build typed query methods for your custom module.

Amino Converters

Add Amino JSON signing support for wallets like Keplr and Leap.

Code Generation

Generate TypeScript codecs from protobuf definitions automatically.