@cosmjs/cosmwasm

Client for CosmWasm smart contract chains

Extends @cosmjs/stargate with CosmWasm-specific functionality for interacting with smart contracts on CosmWasm-enabled chains.

npm install @cosmjs/cosmwasm

The previous package name @cosmjs/cosmwasm-stargate is deprecated. Update your imports to use @cosmjs/cosmwasm.

CosmWasmClient

Read-only client for querying blockchain state and smart contracts. Provides common query methods plus contract-specific operations.

Static Methods

Method	Parameters	Returns
connect	endpoint: string | HttpEndpoint, options?: CosmWasmClientOptions	Promise<CosmWasmClient>
create	cometClient: CometClient, options?: CosmWasmClientOptions	CosmWasmClient

Instance Methods — Chain Queries

Method	Parameters	Returns
getChainId	—	Promise<string>
getHeight	—	Promise<number>
getAccount	searchAddress: string	Promise<Account | null>
getSequence	address: string	Promise<SequenceResponse>
getBlock	height?: number	Promise<Block>
getBalance	address: string, searchDenom: string	Promise<Coin>
getTx	id: string	Promise<IndexedTx | null>
searchTx	query: SearchTxQuery	Promise<IndexedTx[]>
broadcastTx	tx: Uint8Array, timeoutMs?: number, pollIntervalMs?: number	Promise<DeliverTxResponse>
broadcastTxSync	tx: Uint8Array	Promise<string>
disconnect	—	void

Instance Methods — Contract Queries

Method	Parameters	Returns
getCodes	—	Promise<readonly Code[]>
getCodeDetails	codeId: number	Promise<CodeDetails>
getContracts	codeId: number	Promise<readonly string[]>
getContractsByCreator	creator: string	Promise<string[]>
getContract	address: string	Promise<Contract>
getContractCodeHistory	address: string	Promise<readonly ContractCodeHistoryEntry[]>
queryContractRaw	address: string, key: Uint8Array	Promise<Uint8Array | null>
queryContractSmart	address: string, queryMsg: JsonObject	Promise<JsonObject>

Usage

import { CosmWasmClient } from "@cosmjs/cosmwasm";

const client = await CosmWasmClient.connect("https://rpc.my-chain.network");

const info = await client.getContract("osmo1contractaddr...");
const state = await client.queryContractSmart("osmo1contractaddr...", {
  get_count: {},
});
const codes = await client.getCodes();
const contracts = await client.getContracts(1);

client.disconnect();

SigningCosmWasmClient

Extends CosmWasmClient with transaction signing and smart contract management. Inherits all read-only methods above.

Static Methods

Method	Parameters	Returns
connectWithSigner	endpoint: string | HttpEndpoint, signer: OfflineSigner, options?: SigningCosmWasmClientOptions	Promise<SigningCosmWasmClient>
createWithSigner	cometClient: CometClient, signer: OfflineSigner, options?: SigningCosmWasmClientOptions	SigningCosmWasmClient
offline	signer: OfflineSigner, options?: SigningCosmWasmClientOptions	Promise<SigningCosmWasmClient>

Instance Methods — Contract Operations

Method	Parameters	Returns
upload	senderAddress: string, wasmCode: Uint8Array, fee: StdFee | "auto" | number, memo?: string, instantiatePermission?: AccessConfig	Promise<UploadResult>
instantiate	senderAddress: string, codeId: number, msg: JsonObject, label: string, fee: StdFee | "auto" | number, options?: InstantiateOptions	Promise<InstantiateResult>
instantiate2	senderAddress: string, codeId: number, salt: Uint8Array, msg: JsonObject, label: string, fee: StdFee | "auto" | number, options?: InstantiateOptions	Promise<InstantiateResult>
execute	senderAddress: string, contractAddress: string, msg: JsonObject, fee: StdFee | "auto" | number, memo?: string, funds?: readonly Coin[]	Promise<ExecuteResult>
executeMultiple	senderAddress: string, instructions: readonly ExecuteInstruction[], fee: StdFee | "auto" | number, memo?: string	Promise<ExecuteResult>
migrate	senderAddress: string, contractAddress: string, codeId: number, migrateMsg: JsonObject, fee: StdFee | "auto" | number, memo?: string	Promise<MigrateResult>
updateAdmin	senderAddress: string, contractAddress: string, newAdmin: string, fee: StdFee | "auto" | number, memo?: string	Promise<ChangeAdminResult>
clearAdmin	senderAddress: string, contractAddress: string, fee: StdFee | "auto" | number, memo?: string	Promise<ChangeAdminResult>

Instance Methods — Token Operations

Method	Parameters	Returns
sendTokens	senderAddress: string, recipientAddress: string, amount: readonly Coin[], fee: StdFee | "auto" | number, memo?: string	Promise<DeliverTxResponse>
delegateTokens	delegatorAddress: string, validatorAddress: string, amount: Coin, fee: StdFee | "auto" | number, memo?: string	Promise<DeliverTxResponse>
undelegateTokens	delegatorAddress: string, validatorAddress: string, amount: Coin, fee: StdFee | "auto" | number, memo?: string	Promise<DeliverTxResponse>
withdrawRewards	delegatorAddress: string, validatorAddress: string, fee: StdFee | "auto" | number, memo?: string	Promise<DeliverTxResponse>

Instance Methods — Signing

Method	Parameters	Returns
simulate	signerAddress: string, messages: readonly EncodeObject[], memo: string | undefined	Promise<number>
signAndBroadcast	signerAddress: string, messages: readonly EncodeObject[], fee: StdFee | "auto" | number, memo?: string, timeoutHeight?: bigint	Promise<DeliverTxResponse>
signAndBroadcastSync	signerAddress: string, messages: readonly EncodeObject[], fee: StdFee | "auto" | number, memo?: string, timeoutHeight?: bigint	Promise<string>
sign	signerAddress: string, messages: readonly EncodeObject[], fee: StdFee, memo: string, explicitSignerData?: SignerData, timeoutHeight?: bigint	Promise<TxRaw>

Usage

import fs from "node:fs";
import { SigningCosmWasmClient } from "@cosmjs/cosmwasm";
import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";
import { GasPrice } from "@cosmjs/stargate";

const wallet = await DirectSecp256k1HdWallet.fromMnemonic("your mnemonic ...", {
  prefix: "osmo",
});
const [{ address }] = await wallet.getAccounts();

const client = await SigningCosmWasmClient.connectWithSigner(
  "https://rpc.my-chain.network",
  wallet,
  { gasPrice: GasPrice.fromString("0.025uosmo") },
);

// Upload
const wasmCode = fs.readFileSync("contract.wasm");
const { codeId } = await client.upload(address, wasmCode, "auto");

// Instantiate
const { contractAddress } = await client.instantiate(
  address, codeId, { count: 0 }, "My Contract", "auto",
);

// Execute
const result = await client.execute(
  address, contractAddress, { increment: {} }, "auto",
);

// Query
const state = await client.queryContractSmart(contractAddress, { get_count: {} });

Key Types

Code

interface Code {
  readonly id: number;
  readonly creator: string;
  readonly checksum: string;
}

CodeDetails

interface CodeDetails extends Code {
  readonly data: Uint8Array;
}

Contract

interface Contract {
  readonly address: string;
  readonly codeId: number;
  readonly creator: string;
  readonly admin: string | undefined;
  readonly label: string;
  readonly ibcPortId: string | undefined;
}

ContractCodeHistoryEntry

interface ContractCodeHistoryEntry {
  readonly operation: "Genesis" | "Init" | "Migrate";
  readonly codeId: number;
  readonly msg: JsonObject;
}

In the interfaces below, logs refers to the namespace re-exported from @cosmjs/stargate (import { logs } from "@cosmjs/stargate"), so logs.Log[] is the type logs.Log array, not a reference to the field of the same name.

UploadResult

interface UploadResult {
  readonly checksum: string;
  readonly originalSize: number;
  readonly compressedSize: number;
  readonly codeId: number;
  readonly height: number;
  readonly transactionHash: string;
  readonly events: readonly Event[];
  /** @deprecated Not filled in Cosmos SDK >= 0.50. Use `events` instead. */
  readonly logs: readonly logs.Log[];
  readonly gasWanted: bigint;
  readonly gasUsed: bigint;
}

InstantiateResult

interface InstantiateResult {
  readonly contractAddress: string;
  readonly height: number;
  readonly transactionHash: string;
  readonly events: readonly Event[];
  /** @deprecated Not filled in Cosmos SDK >= 0.50. Use `events` instead. */
  readonly logs: readonly logs.Log[];
  readonly gasWanted: bigint;
  readonly gasUsed: bigint;
}

InstantiateOptions

interface InstantiateOptions {
  readonly memo?: string;
  readonly funds?: readonly Coin[];
  readonly admin?: string;
}

ExecuteResult

interface ExecuteResult {
  readonly height: number;
  readonly transactionHash: string;
  readonly events: readonly Event[];
  /** @deprecated Not filled in Cosmos SDK >= 0.50. Use `events` instead. */
  readonly logs: readonly logs.Log[];
  readonly gasWanted: bigint;
  readonly gasUsed: bigint;
}

ExecuteInstruction

interface ExecuteInstruction {
  contractAddress: string;
  msg: JsonObject;
  funds?: readonly Coin[];
}

MigrateResult

interface MigrateResult {
  readonly height: number;
  readonly transactionHash: string;
  readonly events: readonly Event[];
  /** @deprecated Not filled in Cosmos SDK >= 0.50. Use `events` instead. */
  readonly logs: readonly logs.Log[];
  readonly gasWanted: bigint;
  readonly gasUsed: bigint;
}

ChangeAdminResult

interface ChangeAdminResult {
  readonly height: number;
  readonly transactionHash: string;
  readonly events: readonly Event[];
  /** @deprecated Not filled in Cosmos SDK >= 0.50. Use `events` instead. */
  readonly logs: readonly logs.Log[];
  readonly gasWanted: bigint;
  readonly gasUsed: bigint;
}

SigningCosmWasmClientOptions

interface SigningCosmWasmClientOptions extends CosmWasmClientOptions {
  readonly registry?: Registry;
  readonly aminoTypes?: AminoTypes;
  readonly broadcastTimeoutMs?: number;
  readonly broadcastPollIntervalMs?: number;
  readonly gasPrice?: GasPrice | DynamicGasPriceConfig;
}

Helper Functions

Function	Parameters	Returns
setupWasmExtension	base: QueryClient	WasmExtension
createWasmAminoConverters	—	AminoConverters
instantiate2Address	checksum: Uint8Array, creator: string, salt: Uint8Array, prefix: string	string
toBinary	obj: any	string
fromBinary	binary: string	any

Encode Objects

Type	typeUrl
MsgStoreCodeEncodeObject	/cosmwasm.wasm.v1.MsgStoreCode
MsgInstantiateContractEncodeObject	/cosmwasm.wasm.v1.MsgInstantiateContract
MsgInstantiateContract2EncodeObject	/cosmwasm.wasm.v1.MsgInstantiateContract2
MsgExecuteContractEncodeObject	/cosmwasm.wasm.v1.MsgExecuteContract
MsgMigrateContractEncodeObject	/cosmwasm.wasm.v1.MsgMigrateContract
MsgUpdateAdminEncodeObject	/cosmwasm.wasm.v1.MsgUpdateAdmin
MsgClearAdminEncodeObject	/cosmwasm.wasm.v1.MsgClearAdmin