Code Generation

Writing protobuf codec wrappers, query clients, and Amino converters by hand is error-prone and tedious. Code generation tools read your chain’s .proto files and produce TypeScript code that’s directly compatible with CosmJS’s Registry, createProtobufRpcClient, and AminoTypes.

Choosing a Generator

	Telescope	ts-proto	protobufjs
Approach	Full-stack Cosmos codegen	General-purpose protobuf codegen	Runtime type definitions
Output	Message codecs, query clients, Amino converters, registry helpers, LCD clients	Message codecs, query service clients	Encode/decode at runtime (no build step)
CosmJS interface	`TelescopeGeneratedType`	`TsProtoGeneratedType` / `TsProto2GeneratedType`	`PbjsGeneratedType`
`fromPartial`	Yes	Yes	No (uses `create`)
Best for	Full dApp development, chain-specific libraries	Matching CosmJS’s own code style, lightweight projects	Prototyping, runtime-defined types
Used by	OsmoJS, Stargaze, dYdX, Stride	`cosmjs-types` (CosmJS itself)	Quick prototypes, dynamic schemas

Telescope

Telescope is the most popular code generator in the Cosmos ecosystem. It produces complete TypeScript libraries that include everything needed for CosmJS integration — message codecs, query clients, Amino converters, and registry arrays.

Quick Start

Telescope v2 has been published as @hyperweb/telescope with InterchainJS as the default dependency. For CosmJS-based projects, @cosmology/telescope v1.x remains the recommended version. The CLI commands below work with both versions.

Using Telescope Output with CosmJS

Telescope-generated types implement TelescopeGeneratedType, which the CosmJS Registry accepts directly. A typical Telescope output includes:

Message codecs (MsgXxx with encode, decode, fromPartial)
Query clients (QueryClientImpl for gRPC-web queries)
Registry arrays (pre-built [typeUrl, codec] pairs)
Amino converters (ready-made AminoConverter objects)

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

// Telescope-generated imports from OsmoJS
import { osmosis, osmosisProtoRegistry, osmosisAminoConverters } from "osmojs";

// Message composers give you typed helpers
const { joinPool, swapExactAmountIn } = osmosis.gamm.v1beta1.MessageComposer.withTypeUrl;

// Use the top-level registry and amino exports
const registry = new Registry([
  ...defaultRegistryTypes,
  ...osmosisProtoRegistry,
]);

const aminoTypes = new AminoTypes({
  ...createDefaultAminoConverters(),
  ...osmosisAminoConverters,
});

Chain-Specific Libraries

Many popular chains already have Telescope-generated libraries published on npm:

Chain	Package	Install
Osmosis	`osmojs`	`npm install osmojs`
Stargaze	`stargazejs`	`npm install stargazejs`
Juno	`juno-network`	`npm install juno-network`
Stride	`stridejs`	`npm install stridejs`
dYdX	`@dydxprotocol/v4-client-js`	`npm install @dydxprotocol/v4-client-js`
Injective	`@injectivelabs/sdk-ts`	`npm install @injectivelabs/sdk-ts`

Check if a library exists for your chain before generating types from scratch.

ts-proto

CosmJS itself uses ts-proto via the cosmjs-types package. It’s a lightweight, general-purpose protobuf code generator that produces clean TypeScript with no Cosmos-specific abstractions.

Setup

Install ts-proto and protoc (the Protocol Buffer compiler):

npm install --save-dev ts-proto

yarn add --dev ts-proto

You also need protoc installed on your system.

Generating Code

protoc \
  --plugin="./node_modules/.bin/protoc-gen-ts_proto" \
  --ts_proto_out="./src/generated" \
  --proto_path="./proto" \
  --ts_proto_opt="esModuleInterop=true,forceLong=bigint,useOptionals=messages" \
  ./proto/mymodule/v1/tx.proto \
  ./proto/mymodule/v1/query.proto

Key ts_proto_opt options:

Option	Recommended value	Purpose
`esModuleInterop`	`true`	Compatibility with ES module imports
`forceLong`	`bigint`	Use native `bigint` instead of the `Long` library
`useOptionals`	`messages`	Make nested message fields optional

The generated MsgXxx and QueryClientImpl classes work directly with CosmJS’s Registry and createProtobufRpcClient.

Working with Yarn 2+

The binary ./node_modules/.bin/protoc-gen-ts_proto is not easily available in Yarn 2+. Create an executable wrapper script bin/protoc-gen-ts_proto_yarn_2:

#!/usr/bin/env -S yarn node
require('ts-proto/build/plugin')

Then use --ts_proto_yarn_2_opt instead of --ts_proto_opt in your protoc command. See the cosmjs-types repo for a full example.

protobufjs (Runtime Types)

For prototyping or when you don’t have access to .proto files, protobufjs lets you define types at runtime in pure JavaScript — no build step required:

import * as protobuf from "protobufjs";
import { Registry } from "@cosmjs/proto-signing";
import { defaultRegistryTypes } from "@cosmjs/stargate";

const root = protobuf.Root.fromJSON({
  nested: {
    blog: {
      nested: {
        v1: {
          nested: {
            MsgCreatePost: {
              fields: {
                author: { type: "string", id: 1 },
                title: { type: "string", id: 2 },
                body: { type: "string", id: 3 },
              },
            },
          },
        },
      },
    },
  },
});

const MsgCreatePost = root.lookupType("blog.v1.MsgCreatePost");

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

Runtime types from protobufjs use create instead of fromPartial. The Registry handles both automatically.

When to Use protobufjs

Prototyping: Quickly test a message type without setting up a codegen pipeline
Dynamic schemas: When the proto definitions aren’t known at build time
Plain JavaScript: When you don’t want a TypeScript build step

For production applications, Telescope or ts-proto are preferred because they provide compile-time type safety.

Next Steps

Custom Protobuf Types

Custom Modules

Wire generated types into a complete module integration.

Supporting New Chains

Configure CosmJS for your chain’s address prefix, gas token, and account type.

CosmJS

Concepts

Guides

API Reference

Choosing a Generator

Telescope

Quick Start

Using Telescope Output with CosmJS

Chain-Specific Libraries

ts-proto

Setup

Generating Code

Working with Yarn 2+

protobufjs (Runtime Types)

When to Use protobufjs

Next Steps

Custom Protobuf Types

Custom Modules

Supporting New Chains

​Choosing a Generator

​Telescope

​Quick Start

​Using Telescope Output with CosmJS

​Chain-Specific Libraries

​ts-proto

​Setup

​Generating Code

​Working with Yarn 2+

​protobufjs (Runtime Types)

​When to Use protobufjs

​Next Steps

Custom Protobuf Types

Custom Modules

Supporting New Chains

Choosing a Generator

Telescope

Quick Start

Using Telescope Output with CosmJS

Chain-Specific Libraries

ts-proto

Setup

Generating Code

Working with Yarn 2+

protobufjs (Runtime Types)

When to Use protobufjs

Next Steps