Skip to content

Unique-Divine/jiyuu / ai-skills/nibiru-cli

nibiru-cli

Verified

Query Nibiru chain state and submit transactions with the `nibiru` CLI, including setup via `ud`, config inspection, key discovery with `nibiru keys list`, bank transfers, bank balance queries, EVM multi-VM balance checks such as `nibiru q evm balance` for Sai USDC, wasm contract queries, wasm execute/instantiate flows, transaction lookups by hash, and governance proposal queries such as tallies, quorum, validator votes, and software-upgrade plans. Use when the user mentions `nibiru`, Nibiru CLI, `nibiru keys list`, `--from`, `nibiru tx bank`, `nibiru tx wasm`, `nibiru q bank`, `nibiru q evm balance`, `nibiru q wasm`, `nibiru q tx`, balances, contract-state smart, tx hashes, `nibiru q gov`, `nibiru tx gov vote`, governance proposals, votes, deposits, tally, quorum, or upgrade plans.

FileKindSize
SKILL.mdskill md15.8 KB
examples.mdmarkdown1.0 KB
governance.mdmarkdown10.1 KB
reference.mdmarkdown6.0 KB

reference.md

View on GitHub
# `nibiru` Reference Notes

## EVM via `nibiru`

Use these commands when the user wants EVM-related state through the Nibiru CLI
rather than Ethereum JSON-RPC.

Start on the intended network first:

```bash
ud nibi cfg prod
nibiru config
```

This selects the default, non-archive mainnet RPC and JSON output. The commands
in this reference read current EVM state, so do not add `--archive`. Assume the
active CLI config is already set to JSON output unless the user says otherwise.

### `nibiru q evm account`

This is the fastest CLI check for an EVM account's native gas balance on Nibiru.
It accepts either a hex `0x...` address or a Bech32 `nibi1...` address and
returns both forms in the response.

```bash
ADDR_HEX="0x7027d536380F0474B7Ec119c2c5250821902e6dC"
ADDR_BECH32="nibi1wqna2d3cpuz8fdlvzxwzc5jssgvs9ekufm3uj2"
nibiru q evm account "$ADDR_HEX"
nibiru q evm account "$ADDR_BECH32"
```

Returned fields:

- `balance_wei`: native EVM balance in wei
- `nonce`: account nonce
- `code_hash`: code hash at the address
- `eth_address`: normalized hex form
- `bech32_address`: normalized Bech32 form

Reminder:

- The empty-account code hash appears as `0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470`; seeing that value is a quick hint that the address is not holding deployed EVM bytecode.

Offline normalization only:

```bash
ADDR="0x7027d536380F0474B7Ec119c2c5250821902e6dC"
nibiru q evm account "$ADDR" --offline
```

With `--offline`, the CLI only normalizes the address forms. It does not query
live chain state, so `balance_wei` and `code_hash` come back empty and `nonce`
defaults to `0`.

### `nibiru q evm balance`

This is the workhorse command for checking USDC balances on Nibiru, especially
for Sai operations where USDC is the primary currency. It queries token balances
in Nibiru's multi-VM context and returns both ERC20 and Bank representations
when available.

It accepts either address format for the account argument:

- EVM hex address, e.g. `0x8fB11A655B6cb989085c8B21AB044Ec19685942D`
- Bech32 address, e.g. `nibi137c35e2mdjucjzzu3vs6kpzwcxtgt9pdnvj5ll`

It accepts either token format for the token argument:

- ERC20 address, e.g. mainnet USDC `0x357c97796aA8e2A6b5A64b1Fc19d5baB9668E190`
- Bank denom, e.g. `erc20/0x357c97796aA8e2A6b5A64b1Fc19d5baB9668E190`
- Native bank denom, e.g. `unibi`

Mainnet Sai USDC reference, distinct from legacy Stargate USDC.e:

```bash
USDC_ERC20="0x357c97796aA8e2A6b5A64b1Fc19d5baB9668E190"
USDC_BANK="erc20/0x357c97796aA8e2A6b5A64b1Fc19d5baB9668E190"
```

The examples from `nibiru q evm balance --help` are the canonical quick-start:

```bash
# USDC on Nibiru mainnet
addr="0xYourAddr" token="0x357c97796aA8e2A6b5A64b1Fc19d5baB9668E190"
nibiru query evm balance "$addr" "$token"

# NIBI via bank denom
addr="0xYourAddr" token="unibi"  # Bank coin denom works
nibiru query evm balance "$addr" "$token"

# NIBI via canonical WNIBI ERC20
addr="0xYourAddr" token="0x0CaCF669f8446BeCA826913a3c6B96aCD4b02a97" # ERC20 addr works
nibiru query evm balance "$addr" "$token"
```

For a Bech32 keyring address, use the key address directly:

```bash
ADDR="$(nibiru keys show sai-perp-admin -a)"
TOKEN="0x357c97796aA8e2A6b5A64b1Fc19d5baB9668E190"
nibiru q evm balance "$ADDR" "$TOKEN" | jq .
```

Useful output fields:

- `addr_evm` and `addr_bech32`: normalized account address forms.
- `erc20_balance_human` / `erc20_balance_base`: ERC20 balance.
- `bank_balance_human` / `bank_balance_base`: Bank coin balance for the mapped
  denom.
- `bank_coin_denom`: bank denom corresponding to the ERC20 token.
- `erc20_decimals` / `bank_decimals`: decimal metadata for display conversion.

Rule of thumb:

- Prefer `nibiru q evm balance "$ADDR" "$USDC_ERC20"` for Sai USDC balance
  checks because it shows both EVM/ERC20 and Bank-side holdings in one response.
- Use `nibiru q bank balances "$ADDR" --denom "$USDC_BANK"` only when you
  specifically need the Bank module view.

Legacy USDC.e uses `0x0829F361A05D993d5CEb035cA6DF3446b060970b`, not the
Sai USDC address above. Both tokens have six decimals. The planned v2.23.1
CLI patch resolves `USDC` and `USDC.e` locally to explicit Sai and legacy
addresses on the compatible `release/v2.23` line. It does not change direct
node or Wasm Stargate query semantics: `USDC` still selects legacy USDC there.
The separate native alias change on `main` requires a coordinated upgrade.
Use explicit addresses with installed CLIs and direct queries to existing nodes.

A zero result applies only to the selected token. Use `nibiru q bank balances "$ADDR"` to inspect other bank holdings before describing an account as empty.

### `balance_wei` and bank `unibi`

`balance_wei` from `nibiru q evm account` and bank `unibi` from `nibiru q bank balances`
represent the same native NIBI balance, just at different granularities.

- `unibi` means micro NIBI (`μ NIBI`)
- `1 NIBI = 1_000_000 unibi`
- `1 NIBI = 10^18 wei`
- Therefore `1 unibi = 10^12 wei`

Examples:

```bash
ADDR="nibi1wqna2d3cpuz8fdlvzxwzc5jssgvs9ekufm3uj2"
DENOM="unibi"
nibiru q evm account "$ADDR"
nibiru q bank balances "$ADDR" --denom "$DENOM"
```

Rule of thumb:

- Use `q evm account` when the user thinks in EVM/native-gas terms or has a `0x...` address.
- Use `q bank balances --denom unibi` when the user wants the Cosmos bank representation.

### `nibiru q evm funtoken`

Use this to query the mapping between a bank denom and its ERC20 representation.

```bash
COIN_OR_ERC20="unibi"
nibiru q evm funtoken "$COIN_OR_ERC20"

COIN_OR_ERC20="0x7D4B7B8CA7E1a24928Bb96D59249c7a5bd1DfBe6"
nibiru q evm funtoken "$COIN_OR_ERC20"
```

## `nibiru tx evm` scope

On this CLI build, `nibiru tx evm` is for FunToken and bank/ERC20 conversion
flows, not generic Ethereum wallet-like transactions.

Available commands:

- `nibiru tx evm convert-coin-to-evm`
- `nibiru tx evm convert-evm-to-coin`
- `nibiru tx evm create-funtoken`

Use other surfaces when appropriate:

- `nibiru tx bank` for native bank sends
- `nibiru tx wasm` for CosmWasm contract execution and instantiation
- `evm-rpc` for receipts, traces, and `eth_*` / `debug_*` RPC workflows
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall