@bze/bze-ui-kit

Shared hooks, utilities, query clients, services, UI components, and types for BZE ecosystem frontend apps.

Installation

npm install @bze/bze-ui-kit

Peer dependencies

The consuming app must have these installed (they are not bundled):

npm install @bze/bzejs @chakra-ui/react bignumber.js chain-registry \
  @chain-registry/types @chain-registry/utils \
  @interchain-kit/core @interchain-kit/react \
  @interchainjs/cosmos @interchainjs/encoding \
  next-themes react react-dom react-icons

Usage

import {
  // Configuration — call these early in your app (both optional)
  setStorageKeyVersion,
  setDefaultTxMemo,

  // Utils
  toBigNumber, prettyAmount, createMarketId, formatUsdAmount,

  // Query clients
  getMarkets, getLiquidityPools, getAddressBalances, getBZEUSDPrice,

  // Hooks
  useAssets, useBalances, useMarkets, useLiquidityPools,
  useWalletHealthCheck,

  // Context (provide your own AssetsProvider)
  AssetsContext,

  // Types
  type Asset, type Market, type Balance,
} from '@bze/bze-ui-kit';

App initialization

Each app must configure the library at startup:

// In your app's entry point (e.g., layout.tsx)
import { setStorageKeyVersion, setDefaultTxMemo } from '@bze/bze-ui-kit';

// Set a unique storage prefix to avoid localStorage collisions between apps
setStorageKeyVersion('3');  // dex uses '3', burner uses '2'

// Optional — transaction memo defaults to NEXT_PUBLIC_APP_NAME if set.
// Only needed if you want a value different from the app name env var.
setDefaultTxMemo('dex.getbze.com');

AssetsProvider

The library exports AssetsContext and AssetsContextType but each app implements its own AssetsProvider. This is because dex and burner have different app-specific state on top of the shared base.

Wallet health check

Call useWalletHealthCheck() in a top-level always-mounted component (e.g. BlockchainListenerWrapper) to proactively detect and clear stale wallet state restored from localStorage (e.g. extension locked after leaving the page for hours):

import { useWalletHealthCheck } from '@bze/bze-ui-kit';

export function BlockchainListenerWrapper() {
  useWalletHealthCheck();
  // ...
}

Blockchain event subscriptions

Use subscribeToBlockchainEvents to subscribe to CometBFT events via a shared WebSocket singleton (one persistent connection reused across the whole app):

import { subscribeToBlockchainEvents, getSettings } from '@bze/bze-ui-kit';

const unsubscribe = await subscribeToBlockchainEvents(
  getSettings().endpoints.rpcEndpoint,
  "tm.event='NewBlock'",
  (result) => { /* handle result.data.value */ }
);

// Later:
unsubscribe();

The singleton handles reconnection with exponential backoff and automatically resubscribes active subscriptions after reconnect.

Event helper functions

Use these to filter CometBFT events in your blockchain listener:

import {
  isAddressTransfer, isBurnEvent, isCoinbaseEvent, isEpochStartEvent,
  isOrderBookEvent, isOrderExecutedEvent, isSwapEvent,
  getMintedAmount, getEventMarketId, getEventKeyValue,
} from '@bze/bze-ui-kit';

What's included

| Module | Description | |--------|-------------| | types/ | TypeScript interfaces for assets, balances, markets, pools, staking, IBC, events, settings, burn, block | | utils/ | Pure functions: amount math, denom helpers, formatting, address validation, staking APR, chart periods, event filters | | constants/ | Chain config, RPC/REST endpoints, asset lists, keplr fallbacks, testnet, ecosystem navigation | | storage/ | localStorage wrapper with TTL + app settings persistence | | service/ | AmmRouter (Dijkstra swap routing), BlockchainEventManager (pub-sub), assets_factory, keplr suggest chain | | query/ | REST clients for bank, staking, markets, liquidity pools, epochs, IBC, burner, raffle, block, module, rewards, aggregator, prices | | hooks/ | React hooks: useAssets, useBalances, useMarkets, useLiquidityPools, useLiquidityPool, usePrices, useEpochs, useSigningClient, useWalletHealthCheck, useSettings, useFeeTokens, useAssetsValue, useConnectionType, useToast, useSDKTx/useBZETx/useIBCTx | | contexts/ | Base AssetsContextType interface + AssetsContext React context | | components/ | Sidebar, WalletSidebarContent, SettingsSidebarContent, SettingsToggle, Toaster, HighlightText |

Required environment variables

The library reads these NEXT_PUBLIC_* env vars at build time (inlined by Next.js). The consuming app must define them in its .env file.

Chain configuration

| Env var | Default | Description | |---------|---------|-------------| | NEXT_PUBLIC_CHAIN_ID | beezee-1 | Chain ID | | NEXT_PUBLIC_CHAIN_NAME | beezee | Chain name (must match chain-registry) | | NEXT_PUBLIC_CHAIN_IS_TESTNET | false | Set to true or 1 for testnet | | NEXT_PUBLIC_CHAIN_ADDRESS_PREFIX | bze | Bech32 address prefix | | NEXT_PUBLIC_CHAIN_NATIVE_ASSET_DENOM | ubze | Native staking/fee denom | | NEXT_PUBLIC_USDC_IBC_DENOM | (empty) | IBC denom for USDC on BZE chain | | NEXT_PUBLIC_EXPLORER_URL | https://explorer.chaintools.tech | Block explorer base URL | | NEXT_PUBLIC_WALLET_CHAINS_NAMES | (auto) | Comma-separated chain names for wallet connection | | NEXT_PUBLIC_LOCKER_ADDRESS | bze1pc5zjcvhx3e8l305zjl72grytfa30r5mdypmw4 | Locker module address | | NEXT_PUBLIC_APP_NAME | BZE | Display name and default transaction memo | | NEXT_PUBLIC_GAS_MULTIPLIER | 1.5 | Multiplier applied to simulated gas estimates |

BZE endpoints

| Env var | Default | Description | |---------|---------|-------------| | NEXT_PUBLIC_REST_URL | (empty) | Default BZE REST endpoint | | NEXT_PUBLIC_RPC_URL | (empty) | Default BZE RPC endpoint | | NEXT_PUBLIC_REST_ENDPOINT | (empty) | User-configurable REST endpoint (settings default) | | NEXT_PUBLIC_RPC_ENDPOINT | (empty) | User-configurable RPC/WebSocket endpoint (settings default) | | NEXT_PUBLIC_AGG_API_HOST | https://getbze.com | Aggregator API host for prices/tickers |

IBC chain endpoints

| Env var | Description | |---------|-------------| | NEXT_PUBLIC_RPC_URL_ARCHWAY | Archway RPC | | NEXT_PUBLIC_RPC_URL_OSMOSIS | Osmosis RPC | | NEXT_PUBLIC_RPC_URL_NOBLE | Noble RPC | | NEXT_PUBLIC_RPC_URL_JACKAL | Jackal RPC | | NEXT_PUBLIC_RPC_URL_FLIX | OmniFlix RPC | | NEXT_PUBLIC_RPC_URL_ATOMONE | AtomOne RPC | | NEXT_PUBLIC_REST_URL_ARCHWAY | Archway REST | | NEXT_PUBLIC_REST_URL_OSMOSIS | Osmosis REST | | NEXT_PUBLIC_REST_URL_NOBLE | Noble REST | | NEXT_PUBLIC_REST_URL_JACKAL | Jackal REST | | NEXT_PUBLIC_REST_URL_FLIX | OmniFlix REST | | NEXT_PUBLIC_REST_URL_ATOMONE | AtomOne REST |

Ecosystem navigation

| Env var | Default | Description | |---------|---------|-------------| | NEXT_PUBLIC_ECOSYSTEM_EXCLUDED | (empty) | Comma-separated keys to hide (e.g. staking,factory). Valid: website, staking, dex, burner, factory | | NEXT_PUBLIC_ECOSYSTEM_LINK_{KEY} | (per app) | Override URL for an app (e.g. NEXT_PUBLIC_ECOSYSTEM_LINK_WEBSITE) | | NEXT_PUBLIC_ECOSYSTEM_LABEL_{KEY} | (per app) | Override display label (e.g. NEXT_PUBLIC_ECOSYSTEM_LABEL_DEX) |

AtomOne validator (dex-only)

| Env var | Default | Description | |---------|---------|-------------| | NEXT_PUBLIC_ATONE_VALIDATOR_SUPPORTED_DENOMS | (empty) | Comma-separated denoms supported by BZE validator | | NEXT_PUBLIC_ATONE_VALIDATOR_PAGE_URL | (empty) | URL to the validator page |

What stays app-specific

These are not in the library — each app keeps its own:

• useBlockchainListener — different WebSocket event subscriptions per app; built on top of subscribeToBlockchainEvents from the lib
• useNavigation — completely different route structures
• AssetsProvider (contexts/assets_context.tsx) — each app extends the shared base AssetsContextType with app-specific state
• Burner-only: useBurnerContext, useBurningHistory, useNextBurning, useRaffles
• Dex-only: useLockedLiquidity, useNativeStakingData, useRewardsStakingData

Development

# Install dependencies
npm install

# Build (CJS + ESM + type declarations)
npm run build

# Watch mode for development
npm run dev

# Type-check without emitting
npm run lint

Build & Publish to npm

Prerequisites

Add a publish token to ~/.npmrc so npm publish never prompts for login:

echo "//registry.npmjs.org/:_authToken=YOUR_TOKEN" >> ~/.npmrc

Generate the token at npmjs.com → your avatar → Access Tokens → Generate New Token → Classic → Publish.

Steps

# 1. Bump the version in package.json, then:
npm run build && npm publish

License

MIT