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-signingPackage Overview
| Package | Purpose |
|---|---|
@cosmjs/stargate | Main client for Cosmos SDK chains |
@cosmjs/proto-signing | Protobuf signing utilities |
@cosmjs/cosmwasm-stargate | CosmWasm smart contract support |
@cosmjs/amino | Amino 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 signingSigning 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.