Using CosmJS

Overview

CosmJS is the official JavaScript/TypeScript library for interacting with Cosmos SDK blockchains. Aria Wallet integrates seamlessly with CosmJS through its offline signer interface.

This guide covers how to use CosmJS with Aria Wallet to send transactions, query chain data, and interact with smart contracts.

Installation

Install the CosmJS packages you need for your project:

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

Package Overview

PackagePurpose
@cosmjs/stargateMain client for Cosmos SDK chains
@cosmjs/proto-signingProtobuf signing utilities
@cosmjs/cosmwasm-stargateCosmWasm smart contract support
@cosmjs/aminoAmino encoding (legacy)

Setup with Aria

Connect CosmJS to Aria Wallet using the offline signer interface. This allows CosmJS to request signatures from the wallet without exposing private keys.

import { SigningStargateClient } from "@cosmjs/stargate"; async function connectWithCosmJS() { // 1. Check if Aria is installed if (!window.aria) { throw new Error("Please install Aria Wallet"); } // 2. Enable the chain const chainId = "cosmoshub-4"; await window.aria.enable(chainId); // 3. Get the offline signer from Aria const offlineSigner = window.aria.getOfflineSigner(chainId); // 4. Get the user's account const accounts = await offlineSigner.getAccounts(); const userAddress = accounts[0].address; // 5. Connect to the chain with CosmJS const rpcEndpoint = "https://rpc.cosmos.network"; const client = await SigningStargateClient.connectWithSigner( rpcEndpoint, offlineSigner ); return { client, userAddress }; }

Signer Types

Aria provides different signer types for various use cases:

// Aria provides three types of offline signers: // 1. Combined signer (supports both Amino and Direct) const signer = window.aria.getOfflineSigner(chainId); // 2. Amino-only signer (for legacy compatibility) const aminoSigner = window.aria.getOfflineSignerOnlyAmino(chainId); // 3. Auto-detect signer (returns appropriate type based on chain) const autoSigner = await window.aria.getOfflineSignerAuto(chainId); // For most use cases, getOfflineSigner() is recommended // Use getOfflineSignerOnlyAmino() only for chains that don't support Direct signing

Signing Client

The SigningStargateClient is the main interface for sending transactions. It connects to an RPC endpoint and uses Aria's offline signer for signing.

Note: The RPC endpoint should match the chain you enabled in Aria. Using a mismatched endpoint will cause transaction failures.

Sending Transactions

Use the signing client to send various transaction types.

Send Tokens

import { SigningStargateClient, coins } from "@cosmjs/stargate"; async function sendTokens() { const chainId = "cosmoshub-4"; await window.aria.enable(chainId); const offlineSigner = window.aria.getOfflineSigner(chainId); const [account] = await offlineSigner.getAccounts(); const client = await SigningStargateClient.connectWithSigner( "https://rpc.cosmos.network", offlineSigner ); // Send 1 ATOM to recipient const recipient = "cosmos1recipient..."; const amount = coins(1000000, "uatom"); // 1 ATOM = 1,000,000 uatom const result = await client.sendTokens( account.address, recipient, amount, { amount: coins(5000, "uatom"), gas: "200000", }, "Sent via Aria Wallet" // memo ); console.log("Transaction hash:", result.transactionHash); return result; }

Delegate to Validator

import { SigningStargateClient, coins } from "@cosmjs/stargate"; async function delegateTokens() { const chainId = "cosmoshub-4"; await window.aria.enable(chainId); const offlineSigner = window.aria.getOfflineSigner(chainId); const [account] = await offlineSigner.getAccounts(); const client = await SigningStargateClient.connectWithSigner( "https://rpc.cosmos.network", offlineSigner ); const validatorAddress = "cosmosvaloper1..."; const amount = coins(1000000, "uatom"); const result = await client.delegateTokens( account.address, validatorAddress, amount[0], { amount: coins(5000, "uatom"), gas: "250000", } ); console.log("Delegation tx:", result.transactionHash); return result; }

IBC Transfer

import { SigningStargateClient, coins } from "@cosmjs/stargate"; async function ibcTransfer() { const chainId = "cosmoshub-4"; await window.aria.enable(chainId); const offlineSigner = window.aria.getOfflineSigner(chainId); const [account] = await offlineSigner.getAccounts(); const client = await SigningStargateClient.connectWithSigner( "https://rpc.cosmos.network", offlineSigner ); // IBC transfer from Cosmos Hub to Osmosis const result = await client.sendIbcTokens( account.address, // sender "osmo1recipient...", // receiver on destination chain coins(1000000, "uatom")[0], // amount "transfer", // source port "channel-141", // source channel (Cosmos Hub -> Osmosis) undefined, // timeout height (use timestamp instead) Math.floor(Date.now() / 1000) + 600, // timeout timestamp (10 minutes) { amount: coins(5000, "uatom"), gas: "250000", } ); console.log("IBC transfer tx:", result.transactionHash); return result; }

Querying Data

For read-only queries, you can use StargateClient without a signer. This is useful for displaying balances, transaction history, and other chain data.

import { StargateClient } from "@cosmjs/stargate"; async function queryChain() { // For queries, you don't need a signer const client = await StargateClient.connect("https://rpc.cosmos.network"); // Get account balance const address = "cosmos1..."; const balance = await client.getBalance(address, "uatom"); console.log("Balance:", balance.amount, balance.denom); // Get all balances const allBalances = await client.getAllBalances(address); console.log("All balances:", allBalances); // Get account info const account = await client.getAccount(address); console.log("Account number:", account?.accountNumber); console.log("Sequence:", account?.sequence); // Get chain height const height = await client.getHeight(); console.log("Current block height:", height); // Get transaction by hash const tx = await client.getTx("TRANSACTION_HASH"); console.log("Transaction:", tx); return { balance, allBalances, account, height }; }

Custom Messages

For CosmWasm contracts or custom message types, you'll need to register them with the client's registry.

import { SigningStargateClient, Registry } from "@cosmjs/stargate"; import { MsgExecuteContract } from "cosmwasm"; async function executeContract() { const chainId = "juno-1"; // Example CosmWasm chain await window.aria.enable(chainId); const offlineSigner = window.aria.getOfflineSigner(chainId); const [account] = await offlineSigner.getAccounts(); // Create a custom registry with CosmWasm messages const registry = new Registry(); registry.register("/cosmwasm.wasm.v1.MsgExecuteContract", MsgExecuteContract); const client = await SigningStargateClient.connectWithSigner( "https://rpc.juno.network", offlineSigner, { registry } ); // Execute a smart contract const contractAddress = "juno1contract..."; const executeMsg = { transfer: { recipient: "juno1recipient...", amount: "1000000", }, }; const result = await client.execute( account.address, contractAddress, executeMsg, { amount: coins(5000, "ujuno"), gas: "300000", } ); return result; }

Tip: For CosmWasm chains, consider using @cosmjs/cosmwasm-stargate which includes pre-registered CosmWasm message types.