Code Generation

Generate TypeScript types from protobuf definitions using Telescope, ts-proto, or protobufjs

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.

1. Install Telescope
2. npm install -g @cosmology/telescope
   

3. Initialize a new package
4. telescope generate
   

5. This creates a new project scaffold. Place your .proto files (or the chain’s proto files) into the ./proto directory.
6. Install existing protobuf definitions
7. For well-known chains, Telescope can pull proto definitions automatically:
8. telescope install
   

9. Generate TypeScript code
10. telescope transpile
    

11. This produces typed message codecs, query clients, Amino converters, and registry helpers — ready to import into your CosmJS project.

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

npm install --save-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

Register your generated types in the CosmJS Registry.

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.