wagmi-cosmos

wagmi React hooks for the Cosmos EVM precompiles, built on viem-cosmos.

The hooks are thin @tanstack/react-query wrappers over the viem-cosmos formatted decorators — the same pattern the wagmi team uses for its own contract-heavy chain extension (tempo). The decorator owns the formatting, so a hook returns the Cosmos-native representation by default (bech32 addresses, typed BondStatus/ProposalStatus/VoteOption, parsed LegacyDec/DecCoin); query.select is left to you for any extra projection.

Install

pnpm add wagmi-cosmos viem-cosmos wagmi viem @tanstack/react-query
# viem-cosmos, wagmi, viem, @tanstack/react-query, react are peer dependencies

Your wagmi config's chains must be defineCosmosChain(...) results (they carry the bech32Prefix the formatted decorators read). A plain viem chain throws ChainMissingBech32PrefixError at runtime.

Quick start

import { createConfig, http, WagmiProvider } from "wagmi"
// wagmi-cosmos re-exports the viem-cosmos surface you need (chain helper, enum
// codecs, page builder, Formatted* types), so a single import is enough.
import {
  defineCosmosChain,
  useValidators, useDelegate, bondStatusToWireString, pageRequest,
} from "wagmi-cosmos"

const cosmosEvm = defineCosmosChain({
  id: 262144,
  name: "Cosmos EVM",
  nativeCurrency: { name: "ATOM", symbol: "ATOM", decimals: 18 },
  rpcUrls: { default: { http: ["https://rpc.example.com"] } },
  bech32Prefix: "cosmos",
})

export const config = createConfig({
  chains: [cosmosEvm],
  transports: { [cosmosEvm.id]: http() },
})
// wrap your app in <WagmiProvider config={config}> + <QueryClientProvider>

function Validators() {
  // read — data is the FORMATTED shape (no manual transform)
  const { data, isLoading } = useValidators({
    args: [bondStatusToWireString("BONDED"), pageRequest({ limit: 10n })],
  })
  // data?.validators[0].operatorAddress === "cosmosvaloper1…"  (bech32, bridged)
  // data?.validators[0].status          === "BONDED"            (typed union)

  // write — the decorator's bech32 guard runs inside the mutation
  const { mutate: delegate } = useDelegate()
  // delegate({ args: [account, "cosmosvaloper1…", amount] })
}

Pattern

• Reads = useQuery(action.queryOptions(...)) over the viem-cosmos decorator. Each read hook also exposes its queryOptions builder (e.g. useValidators.queryOptions(config, params)) for SSR prefetch, a custom QueryClient, or useQueries.
• Writes = useMutation over the formatted write decorator (keeps the funds-path bech32 validation; returns the tx hash).
• Generic factories makeReadHook / makeWriteHook are exported for building hooks over precompiles not yet shipped as named hooks (pair with viem-cosmos's precompileActions).
• Re-exports — the consumer surface from viem-cosmos (defineCosmosChain, enum wire codecs like bondStatusToWireString, pageRequest, the Formatted* types) is re-exported here so apps import from wagmi-cosmos alone. The viem layer proper — decorators, precompileActions, ABIs, pagination iterators — stays in viem-cosmos.

Multicall batching

Batching is a viem client-level feature (wagmi enables batch.multicall by default), independent of these hooks: the decorator reads go through viem readContract, so they coalesce into Multicall3 exactly like useReadContract. viem is config-gated with auto-fallback — if your chain config has no contracts.multicall3, viem silently issues individual eth_calls (works out of the box). To enable batching, add contracts: { multicall3: { address, blockCreated } } to the chain only after verifying Multicall3 is deployed and the precompiles are callable through its internal STATICCALL.

Hooks

| Precompile | Reads | Writes | | --- | --- | --- | | bank | useBalances, useSupplyOf, useTotalSupply | — | | staking | useValidators, useValidator, useDelegation, useUnbondingDelegation, useRedelegation, useRedelegations | useDelegate, useUndelegate, useRedelegate, useCancelUnbondingDelegation, useCreateValidator, useEditValidator | | distribution | useCommunityPool, useDelegationRewards, useDelegationTotalRewards, useValidatorOutstandingRewards, useValidatorCommission, useDelegatorWithdrawAddress, useDelegatorValidators, useValidatorDistributionInfo, useValidatorSlashes | useWithdrawDelegatorRewards, useWithdrawValidatorCommission, useSetWithdrawAddress, useDepositValidatorRewardsPool, useFundCommunityPool, useClaimRewards | | gov | useGetProposal, useGetProposals, useGetTallyResult, useGetVote, useGetVotes, useGetDeposit, useGetDeposits, useGetConstitution, useGetGovParams | useVote, useVoteWeighted, useDeposit, useSubmitProposal, useCancelProposal | | slashing (standalone) | useGetSigningInfo, useGetSigningInfos, useGetSlashingParams | useUnjail |

gov's and slashing's getParams are exported as useGetGovParams / useGetSlashingParams to avoid a name collision (same reason slashing is not in viem-cosmos's combined cosmosActions()).

Testing

pnpm --filter wagmi-cosmos typecheck   # tsc --noEmit (incl. *.test-d.ts type tests)
pnpm --filter wagmi-cosmos test        # smoke + type-level + RTL (mock transport)
pnpm --filter wagmi-cosmos build       # tsdown → dist (ESM + CJS + d.ts)

The render tests drive the hooks against a wagmi config with a custom() mock transport (no chain), asserting the formatted shape end-to-end.

Status

v0.x — API is not yet stable. Hooks cover the validator-economy precompiles (bank, staking, distribution, gov, slashing). useSimulate* write hooks and a multicall convenience helper are follow-ups.

License

MIT © Wonhee Lee