CosmJS + Stargate – A guided tour

header.png

TOUR_COMSJS_STARGATE.md

Support for Cosmos SDK Stargate in CosmJS has been ongoing work for several months now. Stargate is released and CosmJS is here to connect to it.

Starting points

Let's explore what is new for Stargate support:

• @cosmjs/proto-signing, which implements the new SIGN_MODE_DIRECT based on protobuf serializations
• @cosmjs/stargate, which provides a high level client for querying, signing and broadcasting
• @cosmjs/cosmwasm-stargate for interacting with CosmWasm smart contracts on Stargate chains

Install CosmJS ^0.24.0

npm install @cosmjs/proto-signing @cosmjs/stargate
# or
yarn add @cosmjs/proto-signing @cosmjs/stargate

Send your first Stargate transaction from JavaScript:

import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
import { assertIsBroadcastTxSuccess, SigningStargateClient, StargateClient } from "@cosmjs/stargate";

const mnemonic = "surround miss nominee dream gap cross assault thank captain prosper drop duty group candy wealth weather scale put";
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic);
const [firstAccount] = await wallet.getAccounts();

const rpcEndpoint = "https://rpc.my_tendermint_rpc_node";
const client = await SigningStargateClient.connectWithSigner(rpcEndpoint, wallet);

const recipient = "cosmos1xv9tklw7d82sezh9haa573wufgy59vmwe6xxe5";
const amount = {
  denom: "ucosm",
  amount: "1234567",
};
const result = await client.sendTokens(firstAccount.address, recipient, [amount], "Have fun with your star coins");
assertIsBroadcastTxSuccess(result);

Easy, right? Maybe too easy to be actually useful for anyone except exchanges. Here is how you send your custom message types:

import { DirectSecp256k1HdWallet, Registry } from "@cosmjs/proto-signing";
import {
  assertIsBroadcastTxSuccess,
  SigningStargateClient,
  StargateClient,
} from "@cosmjs/stargate";

// A message type auto-generated from .proto files using ts-proto. @cosmjs/stargate ships some
// common types but don't rely on those being available. You need to set up your own code generator
// for the types you care about. How this is done should be documented, but is not yet:
// https://github.com/cosmos/cosmjs/issues/640
import { MsgDelegate } from "@cosmjs/stargate/build/codec/cosmos/staking/v1beta1/tx"; 

const mnemonic =
  "surround miss nominee dream gap cross assault thank captain prosper drop duty group candy wealth weather scale put";
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic);
const [firstAccount] = await wallet.getAccounts();

const rpcEndpoint = "https://rpc.my_tendermint_rpc_node";
const client = await SigningStargateClient.connectWithSigner(
  rpcEndpoint,
  wallet,
  { registry: registry }
);

const msg = MsgDelegate.create({
  delegatorAddress: alice.address0,
  validatorAddress: validator.validatorAddress,
  amount: {
    denom: "uatom",
    amount: "1234567",
  },
});
const msgAny = {
  typeUrl: msgDelegateTypeUrl,
  value: msg,
};
const fee = {
  amount: [
    {
      denom: "uatom",
      amount: "2000",
    },
  ],
  gas: "180000", // 180k
};
const memo = "Use your power wisely";
const result = await client.signAndBroadcast(
  firstAccount.address,
  [msgAny],
  fee,
  memo
);
assertIsBroadcastTxSuccess(result);

If you're not on the Cosmos Hub, you probably want to configure your address prefix and your HD derivation path:

import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
import { stringToPath } from "@cosmjs/crypto";

const mnemonic =
  "surround miss nominee dream gap cross assault thank captain prosper drop duty group candy wealth weather scale put";
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(
  mnemonic,
  stringToPath("m/0'/1/2'/2/1000000000"),
  "blub"
);
const [firstAccount] = await wallet.getAccounts();
// firstAccount.address now starts with blub1

Things we built with CosmJS

The above examples focus on signing, but there are plenty of things you can build with CosmJS and only some of them require signing.

• Wallets (hot and cold; with and without a UI)
• Explorers
• Scrapers
• Key/Address generators
• dApps
• IBC relayers

Used CosmJS before

If you have experience working with CosmJS from Cosmos SDK 0.37–0.39 (Launchpad) times, please note the following significant changes in the Stargate client library:

• The Stargate client always connects to a Tendermint RPC endpoint (HTTP or WebSockets). The LCD API is not used anymore.
• We can now encode/decode binary transactions locally, as the client has a full protobuf implementation. This was not possible before due to the lack of an Amino encoder/decoder.
• Ledger signing support should work via SIGN_MODE_LEGACY_AMINO_JSON. Please see #594

Get in touch

The CosmJS development team is happy to get in touch with you for all questions and suggestions.

• GitHub issues for bugs and feature requests
• The #cosmjs channel on the "Cosmos Community" Discord server for questions and open discussions
• #CosmJS on Twitter to spread the word

Further reading

• The 0.23 -> 0.24 CHANGELOG
• The 0.24.0 development milestone, tracking what is missing for a final 0.24.0