| name | indexer-staking |
| description | Use when the user asks about the Nibiru indexer (Heart Monitor), staking GraphQL schema, GQLValidator, GQLDelegation, HeartMonitor, or querying staking data via GraphQL. Explains that staking is under query.staking, not root-level deprecated fields; rewards come from the chain (distribution), not the indexer; amounts are Int in base units (e.g. unibi). |
Nibiru Indexer (Heart Monitor) — Staking
Use this skill when working with the Nibiru indexer / Heart Monitor GraphQL API or the staking part of the schema (validators, delegations, redelegations, unbondings, history).
Quick Facts
- Indexer = Heart Monitor = GraphQL API. Endpoints (path
/query): Mainnet https://hm-graphql.nibiru.fi/query; testnet https://hm-graphql.itn-2.nibiru.fi/query. Env is the hostname segment for the network: mainnet has no env (host hm-graphql.nibiru.fi); testnet uses env itn-2 (host hm-graphql.itn-2.nibiru.fi). The playground uses the same host with path /graphql.
- Canonical Path: Always use
query { staking { ... } }. Root-level fields are deprecated.
- Bond denom: The staking token denomination is unibi — shorthand for micro NIBI (μ NIBI), where "u" comes from "μ" (mu).
- Amounts: Stored as Int in base units (unibi). Divide by 10^6 for
NIBI.
- Shares: A delegator's proportional claim on a validator's pool; the shares-to-tokens rate changes with slashing (see Shares vs. Amount below).
- Valoper: Validator operator address (
nibivaloper1...). Validators have three Bech32 identities: account nibi1..., operator (valoper), and consensus nibivalcons1...; use nibid debug addr to convert. Indexer/CLI staking use valoper.
- Rewards: Not in the indexer. Use the chain’s distribution module via the Nibiru CLI:
nibid query distribution (e.g. rewards) and nibid tx distribution.
- TS SDK: Use
HeartMonitor from @nibiruchain/nibijs.
Dependency Flow & Lineage
Data flows from the chain to the client in a specific pipeline. Understanding this prevents schema confusion:
- Chain State (Go): Source of truth. Staking module (
internal/cosmos-sdk) stores Shares for delegations.
- Indexer Sync: The
nibi-go-hm server queries the chain, calculates the token Balance, and persists it to the indexer DB.
- GraphQL API: The API (
staking.graphqls) exposes these DB fields. This is why you see amount (tokens) but usually not shares in indexer delegations.
- TS SDK: The client (
nibi-ts-sdk) generates types and query builders from the GraphQL schema.
Shares vs. Amount (Critical)
Shares are a delegator's proportional claim on a validator's pool; the shares-to-tokens rate changes with slashing.
- Indexer
Delegation.amount is a balance snapshot in tokens. It does not track shares.
- Slashing/Compensation: Here compensation means reimbursing delegators after slashing or validator misbehavior (distinct from commission, the validator's share of rewards). You cannot derive shares from the indexer amount after a slash. For reproducible compensation math, you MUST query the chain directly (e.g.,
nibid q staking delegations-to) using a specific --height.
Rule of Thumb: Where to Query?
| Requirement | Preferred Source | Reason |
|---|
| Current delegator balances | Indexer | Fast, indexed, GraphQL support. |
| Historical staking actions | Indexer | staking { history } tracks events over time. |
| Rewards | Chain | Indexer does not track distribution module data. |
| Compensation / Slashing | Chain | Requires shares and height-specific snapshots. |
| Validator uptime/jailed status | Either | Indexer is fine unless absolute real-time is needed. |
Additional Resources
