# What is CosmJS?

Build applications that interact with Cosmos blockchains with CosmJS.

In this section, you will learn:

  • What CosmJS is.
  • What you can use it for.
  • More details regarding the modular design of CosmJS.

Distributed applications (dApps) are software applications that run on distributed networks. Blockchains provide persistent data, or the state, as well as persistent processes and logic. The Cosmos SDK helps developers create such applications. A user interface is important in most cases, and server interactions are important in many cases. This is where CosmJS (opens new window) comes in handy.

As the name suggests, CosmJS is a TypeScript/JavaScript library. It helps developers integrate frontend user interfaces and backend servers with Cosmos blockchains that implement distributed applications. To many users, the "dApp" is the user interface, even though it is often delivered to the browser in a centralized, traditional way - relying on the DNS infrastructure and centralized web servers.

This re-introduction of a degree of centralization is usually considered acceptable by most teams, provided that the important business logic of the system is enforced by a blockchain and provided it is not strictly necessary to use the provided user interface in order to use the dApp. As a general heuristic, offer a user interface as a convenience rather than a necessity.

In general, user interfaces help users interpret the blockchain state, compose and sign transactions, and send them - all things that are potentially accomplished by other less convenient methods. A user interface is supported by servers or micro-services that also interact with the blockchain.

Here you can find the recording of a live session with Noam Cohen of the Interchain Foundation, providing an Introduction to CosmJS:

# Some examples

Developers who are engaged in developing intuitive and coherent user interfaces need to accomplish certain things at the browser level:

  • Help the user create unsigned Cosmos SDK transactions with one or multiple messages.
  • Let the user sign an unsigned transaction with their wallet.
  • Help the user submit a signed transaction to a Cosmos SDK endpoint.
  • Query the state from the Cosmos Hub or a custom module using the legacy REST endpoint.
  • Query the state from the Cosmos Hub or a custom module using the gRPC endpoint.

Backend systems are often useful components of the overall design:

  • Cache a complex state for performance reasons.
  • Minimize client requirements for basic, anonymous browsing.
  • Monitor the blockchain for changes and inform clients.
  • Present API endpoints and WebSockets.

Developers need a tool-kit to accomplish things that address these foundational concerns:

  • Signing a transaction when a mnemonic phrase is known.
  • Signing a transaction when a private key is known.
  • Grouping multiple messages into a single transaction.
  • Requesting a user signature with help from a wallet like Keplr.
  • Querying the blockchain state.
  • Listening for events emitted by Cosmos SDK modules.

CosmJS assists with these tasks and more.

The modular structure of CosmJS lets developers import only the parts that are needed, which helps reduce download payloads. Since the library is unopinionated, it is compatible with popular JavaScript frameworks such as Vue, React, and Express.

# Packages

CosmJS is a library that consists of many smaller npm packages within the @cosmjs namespace (opens new window), a so-called "monorepo".

Generally people only need the stargate and encoding packages as they contain the main functionality to interact with Cosmos SDK chains version 0.40 and higher.

Among many more, here are some example packages:

Package Description Latest
@cosmjs/stargate (opens new window) A client library for the Cosmos SDK 0.40+ (Stargate) (opens new window)
@cosmjs/faucet (opens new window) A faucet application for Node.js (opens new window)
@cosmjs/cosmwasm-stargate (opens new window) Client for Stargate chains with the CosmWasm module enabled (opens new window)
@cosmjs/crypto (opens new window) Cryptography for blockchain projects, e.g. hashing (SHA-2, Keccak256, Ripemd160), signing (secp256k1, ed25519), HD key derivation (BIP-39, SLIP-0010), KDFs and symmetric encryption for key storage (PBKDF2, Argon2, XChaCha20Poly1305) (opens new window)
@cosmjs/encoding (opens new window) Encoding helpers for blockchain projects (opens new window)
@cosmjs/math (opens new window) Safe integers; decimals for handling financial amounts (opens new window)

# Modularity

The repository is nicely modular and keeps clean dependencies. This ensures software quality and lets users pick exactly what they need and only what they need. The following diagram shows how everything fits together (every item is a npm package; right depends on left):

Continue reading for a hands-on developer exercise. The tutorial starts with downloading dependencies and proceeds through the steps of creating a simple user interface.


To summarize, this section has explored:

  • CosmJS, a TypeScript/JavaScript library supplied with the Cosmos SDK providing many small npm packages that help developers integrate frontend user interfaces and backend servers with Cosmos blockchains that implement distributed applications (dApps).
  • How to think about the objectives a coherent and intuitive user interface needs to accomplish, how backend systems can be useful components of the overall design, and the foundational concerns that need to be addressed through the developer's tool-kit.
  • How the modularity of CosmJS delivers clean paths of software design, allowing developers to pick exactly (and only) what they need to achieve their project goals.