or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

amino-types.mdclient.mdindex.mdmessages.mdquery-extensions.mdutilities.md
tile.json

tessl/npm-cosmjs--stargate

Utilities for Cosmos SDK 0.40

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@cosmjs/stargate@0.36.x

To install, run

npx @tessl/cli install tessl/npm-cosmjs--stargate@0.36.0

index.mddocs/

@cosmjs/stargate

@cosmjs/stargate provides comprehensive utilities and client libraries for interacting with Cosmos SDK 0.40+ blockchains. It enables developers to build applications that can query blockchain state, submit transactions, and integrate with Cosmos-based networks with full TypeScript support.

Package Information

  • Package Name: @cosmjs/stargate
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @cosmjs/stargate

Core Imports

import { 
  StargateClient, 
  SigningStargateClient,
  QueryClient,
  calculateFee,
  GasPrice,
  coin,
  coins,
  parseCoins,
  makeCosmoshubPath 
} from "@cosmjs/stargate";

For CommonJS:

const { 
  StargateClient, 
  SigningStargateClient,
  QueryClient,
  calculateFee,
  GasPrice 
} = require("@cosmjs/stargate");

Basic Usage

Read-only Client

import { StargateClient } from "@cosmjs/stargate";

// Connect to a Cosmos SDK chain
const client = await StargateClient.connect("https://rpc.cosmos.network:443");

// Query account balance
const balance = await client.getBalance("cosmos1abc...", "uatom");
console.log(balance); // { denom: "uatom", amount: "1000000" }

// Get transaction
const tx = await client.getTx("ABC123...");

Signing Client

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

// Create wallet from mnemonic
const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic);

// Connect with signer
const client = await SigningStargateClient.connectWithSigner(
  "https://rpc.cosmos.network:443",
  wallet,
  { gasPrice: GasPrice.fromString("0.025uatom") }
);

// Send tokens
const result = await client.sendTokens(
  "cosmos1sender...",
  "cosmos1recipient...",
  [{ denom: "uatom", amount: "1000000" }],
  "auto",
  "Transfer memo"
);

Architecture

@cosmjs/stargate is built around several key components:

  • Client Layer: StargateClient for read-only operations, SigningStargateClient for transaction signing
  • Query System: QueryClient with modular extensions for different Cosmos SDK modules
  • Message System: Protocol buffer message encoding with EncodeObject types
  • Amino System: Legacy amino acid encoding support with AminoTypes converters
  • Utility Layer: Fee calculation, transaction utilities, and error handling

Capabilities

Blockchain Clients

Core client classes for connecting to and interacting with Cosmos SDK blockchains. Includes read-only querying and transaction signing capabilities.

class StargateClient {
  static async connect(endpoint: string | HttpEndpoint, options?: StargateClientOptions): Promise<StargateClient>;
  async getBalance(address: string, searchDenom: string): Promise<Coin>;
  async broadcastTx(tx: Uint8Array, timeoutMs?: number, pollIntervalMs?: number): Promise<DeliverTxResponse>;
}

class SigningStargateClient extends StargateClient {
  static async connectWithSigner(endpoint: string | HttpEndpoint, signer: OfflineSigner, options?: SigningStargateClientOptions): Promise<SigningStargateClient>;
  async sendTokens(senderAddress: string, recipientAddress: string, amount: readonly Coin[], fee: StdFee | "auto" | number, memo?: string): Promise<DeliverTxResponse>;
  async signAndBroadcast(signerAddress: string, messages: readonly EncodeObject[], fee: StdFee | "auto" | number, memo?: string): Promise<DeliverTxResponse>;
}

Blockchain Clients

Query Extensions

Modular query system with extensions for each Cosmos SDK module. Enables strongly-typed queries for chain state including accounts, balances, staking, governance, and more.

class QueryClient {
  static withExtensions<T extends Record<string, any>[]>(
    cometClient: CometClient,
    ...extensionSetups: QueryExtensionSetup<T>[]
  ): QueryClient & UnionToIntersection<T[number]>;
}

interface BankExtension {
  readonly bank: {
    readonly balance: (address: string, denom: string) => Promise<Coin>;
    readonly allBalances: (address: string) => Promise<Coin[]>;
  };
}

interface StakingExtension {
  readonly staking: {
    readonly validator: (validatorAddress: string) => Promise<QueryValidatorResponse>;
    readonly validators: (status: BondStatusString, paginationKey?: Uint8Array) => Promise<QueryValidatorsResponse>;
  };
}

Query Extensions

Message Types and Encoding

Protocol buffer message types and encoding utilities for creating and signing transactions. Includes type-safe message builders for all Cosmos SDK modules.

interface MsgSendEncodeObject extends EncodeObject {
  readonly typeUrl: "/cosmos.bank.v1beta1.MsgSend";
  readonly value: Partial<MsgSend>;
}

interface MsgDelegateEncodeObject extends EncodeObject {
  readonly typeUrl: "/cosmos.staking.v1beta1.MsgDelegate";
  readonly value: Partial<MsgDelegate>;
}

function isMsgSendEncodeObject(encodeObject: EncodeObject): encodeObject is MsgSendEncodeObject;

Message Types

Amino Type System

Legacy amino acid encoding system for backward compatibility with older Cosmos SDK chains and wallets.

class AminoTypes {
  constructor(types: AminoConverters);
  toAmino({ typeUrl, value }: EncodeObject): AminoMsg;
  fromAmino({ type, value }: AminoMsg): EncodeObject;
}

interface AminoConverter {
  readonly aminoType: string;
  readonly toAmino: (value: any) => any;
  readonly fromAmino: (value: any) => any;
}

function createDefaultAminoConverters(): AminoConverters;

Amino Types

Utilities and Error Handling

Fee calculation, transaction utilities, multisignature support, and comprehensive error handling for robust blockchain applications.

class GasPrice {
  constructor(amount: Decimal, denom: string);
  static fromString(gasPrice: string): GasPrice;
}

function calculateFee(gasLimit: number, gasPrice: GasPrice | string): StdFee;

class TimeoutError extends Error {
  public readonly txId: string;
}

function isDeliverTxSuccess(result: DeliverTxResponse): boolean;
function assertIsDeliverTxSuccess(result: DeliverTxResponse): void;

Utilities

Core Types

interface Coin {
  readonly denom: string;
  readonly amount: string;
}

interface StdFee {
  readonly amount: readonly Coin[];
  readonly gas: string;
}

interface DeliverTxResponse {
  readonly height: number;
  readonly code: number;
  readonly transactionHash: string;
  readonly events: readonly Event[];
  readonly gasUsed: bigint;
  readonly gasWanted: bigint;
}

interface Account {
  readonly address: string;
  readonly pubkey: Pubkey | null;
  readonly accountNumber: number;
  readonly sequence: number;
}

interface Event {
  readonly type: string;
  readonly attributes: readonly Attribute[];
}

interface Attribute {
  readonly key: string;
  readonly value: string;
}

type HttpEndpoint = string | {
  readonly url: string;
  readonly headers?: Record<string, string>;
};

interface SearchPair {
  readonly key: string;
  readonly value: string | number | bigint;
}

type SearchTxQuery = string | readonly SearchPair[];

function isSearchTxQueryArray(query: SearchTxQuery): query is readonly SearchPair[];

function coin(amount: string, denom: string): Coin;
function coins(amount: string, denom: string): Coin[];
function makeCosmoshubPath(a: number): HdPath;
function parseCoins(input: string): Coin[];

type HdPath = readonly number[];