# @cosmjs/cosmwasm Agent Guide

> **Package**: `@cosmjs/cosmwasm` v0.38.0 **Purpose**: Client for CosmWasm smart
> contract chains **Layer**: Client Layer (extends @cosmjs/stargate)

## Package Overview

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

### Key Features

- **CosmWasmClient**: Read-only contract queries
- **SigningCosmWasmClient**: Upload, instantiate, execute contracts
- **Contract Queries**: Query contract state
- **Contract Execution**: Execute contract messages
- **Code Upload**: Deploy WASM binaries

## Key Exports

| Export                  | Purpose             |
| ----------------------- | ------------------- |
| `CosmWasmClient`        | Read-only client    |
| `SigningCosmWasmClient` | Signing client      |
| `setupWasmExtension()`  | Wasm module queries |

## Common Usage

### Read-Only Client

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

const client = await CosmWasmClient.connect("https://rpc.osmosis.zone");

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

// Get contract info
const info = await client.getContract(contractAddress);

// Get code info
const codeInfo = await client.getCodeDetails(codeId);

// List contracts by code
const contracts = await client.getContracts(codeId);
```

### Signing Client

```typescript
import { SigningCosmWasmClient } from "@cosmjs/cosmwasm";
import { DirectSecp256k1HdWallet } from "@cosmjs/proto-signing";

const wallet = await DirectSecp256k1HdWallet.fromMnemonic(mnemonic);
const client = await SigningCosmWasmClient.connectWithSigner(
  "https://rpc.osmosis.zone",
  wallet,
);

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

// Instantiate contract
const instantiateResult = await client.instantiate(
  senderAddress,
  codeId,
  { count: 0 }, // Init message
  "My Contract",
  "auto",
);
const contractAddress = instantiateResult.contractAddress;

// Execute contract
const executeResult = await client.execute(
  senderAddress,
  contractAddress,
  { increment: {} },
  "auto",
);

// Execute with funds
await client.execute(
  senderAddress,
  contractAddress,
  { deposit: {} },
  "auto",
  "memo",
  [{ denom: "uosmo", amount: "1000000" }],
);
```

## Common Patterns

### Pattern: Contract Interaction Flow

```typescript
// 1. Upload code
const { codeId } = await client.upload(sender, wasmCode, "auto");

// 2. Instantiate
const { contractAddress } = await client.instantiate(
  sender,
  codeId,
  initMsg,
  label,
  "auto",
);

// 3. Execute
await client.execute(sender, contractAddress, executeMsg, "auto");

// 4. Query
const state = await client.queryContractSmart(contractAddress, queryMsg);
```

### Pattern: Batch Execution

```typescript
const messages = [
  {
    typeUrl: "/cosmwasm.wasm.v1.MsgExecuteContract",
    value: {
      sender,
      contract: contractAddress1,
      msg: toUtf8(JSON.stringify({ execute_msg_1: {} })),
      funds: [],
    },
  },
  {
    typeUrl: "/cosmwasm.wasm.v1.MsgExecuteContract",
    value: {
      sender,
      contract: contractAddress2,
      msg: toUtf8(JSON.stringify({ execute_msg_2: {} })),
      funds: [],
    },
  },
];

await client.signAndBroadcast(sender, messages, "auto");
```

### Pattern: Contract Migration

```typescript
// Upload new code
const { codeId: newCodeId } = await client.upload(sender, newWasmCode, "auto");

// Migrate contract
await client.migrate(
  sender,
  contractAddress,
  newCodeId,
  { migrate_msg: {} },
  "auto",
);
```

## Query Messages

```typescript
// Simple query
const count = await client.queryContractSmart(contractAddress, {
  get_count: {},
});

// Query with parameters
const balance = await client.queryContractSmart(contractAddress, {
  balance: { address: userAddress },
});

// Raw query (returns base64)
const rawData = await client.queryContractRaw(
  contractAddress,
  toAscii("config"),
);
```

---

**Last Updated**: January 6, 2026 **Package Version**: 0.38.0