@bze/bze-ui-kit 1.0.10 → 1.0.11

package/README.md

@@ -13,17 +13,18 @@ npm install @bze/bze-ui-kit
 The consuming app must have these installed (they are **not** bundled):
 
 ```sh
-npm install @bze/bzejs @chakra-ui/react @cosmjs/stargate bignumber.js chain-registry \
+npm install @bze/bzejs @chakra-ui/react bignumber.js chain-registry \
   @chain-registry/types @chain-registry/utils \
-  @interchain-kit/core @interchain-kit/react @interchainjs/encoding \
-  interchainjs next-themes react react-dom react-icons
+  @interchain-kit/core @interchain-kit/react \
+  @interchainjs/cosmos @interchainjs/encoding \
+  next-themes react react-dom react-icons
 ```
 
 ## Usage
 
 ```ts
 import {
-  // Configuration — call these early in your app
+  // Configuration — call these early in your app (both optional)
   setStorageKeyVersion,
   setDefaultTxMemo,
 
@@ -35,6 +36,7 @@ import {
 
   // Hooks
   useAssets, useBalances, useMarkets, useLiquidityPools,
+  useWalletHealthCheck,
 
   // Context (provide your own AssetsProvider)
   AssetsContext,
@@ -49,31 +51,76 @@ import {
 Each app must configure the library at startup:
 
 ```ts
-// In your app's entry point (e.g., layout.tsx or _app.tsx)
+// 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'
 
-// Set the default transaction memo
+// 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 the `AssetsContext` and `AssetsContextType` but each app must implement its own `AssetsProvider`. This is because the dex and burner have different app-specific state on top of the shared base.
+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):
+
+```ts
+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):
+
+```ts
+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:
+
+```ts
+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 |
+| `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, useSettings, useFeeTokens, useAssetsValue, useConnectionType, useToast, useSDKTx/useBZETx/useIBCTx |
+| `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 |
 
@@ -93,8 +140,9 @@ The library reads these `NEXT_PUBLIC_*` env vars at build time (inlined by Next.
 | `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 (used by dex for locked balances) |
-| `NEXT_PUBLIC_APP_NAME` | `BZE` | Display name shown in settings UI |
+| `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
 
@@ -103,7 +151,7 @@ The library reads these `NEXT_PUBLIC_*` env vars at build time (inlined by Next.
 | `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 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
@@ -125,15 +173,11 @@ The library reads these `NEXT_PUBLIC_*` env vars at build time (inlined by Next.
 
 ### Ecosystem navigation
 
-Override links and labels for the "Other" dropdown in the navbar, or exclude apps entirely. Useful for testnet deployments.
-
 | Env var | Default | Description |
 |---------|---------|-------------|
-| `NEXT_PUBLIC_ECOSYSTEM_EXCLUDED` | _(empty)_ | Comma-separated keys to hide from the dropdown (e.g. `staking,factory`). Valid keys: `website`, `staking`, `dex`, `burner`, `factory` |
-| `NEXT_PUBLIC_ECOSYSTEM_LINK_{KEY}` | _(per app)_ | Override the URL for an app. Key is uppercased (e.g. `NEXT_PUBLIC_ECOSYSTEM_LINK_WEBSITE=https://testnet.getbze.com`) |
-| `NEXT_PUBLIC_ECOSYSTEM_LABEL_{KEY}` | _(per app)_ | Override the display label (e.g. `NEXT_PUBLIC_ECOSYSTEM_LABEL_DEX=TestDEX`) |
-
-Call `getEcosystemApps()` to get the filtered and overridden list. Each app should exclude itself via `NEXT_PUBLIC_ECOSYSTEM_EXCLUDED`.
+| `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)
 
@@ -146,10 +190,10 @@ Call `getEcosystemApps()` to get the filtered and overridden list. Each app shou
 
 These are **not** in the library — each app keeps its own:
 
-- **useBlockchainListener** — different WebSocket event subscriptions per app
+- **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 composes the shared base `AssetsContextType` with app-specific state
-- **Burner-only**: `useBurnerContext` (typed wrapper for extended context), `useBurningHistory`, `useNextBurning`, `useRaffles`
+- **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
@@ -172,51 +216,19 @@ npm run lint
 
 ### Prerequisites
 
-1. Make sure you are logged in to npm:
-   ```sh
-   npm login
-   ```
-
-2. Verify you have publish access to the `@bze` scope:
-   ```sh
-   npm access list packages @bze
-   ```
-
-### Steps
+Add a publish token to `~/.npmrc` so `npm publish` never prompts for login:
 
 ```sh
-# 1. Make sure you're on a clean state
-git status
-
-# 2. Update the version in package.json
-#    For a patch release:
-npm version patch
-#    For a minor release:
-npm version minor
-#    For a major release:
-npm version major
-
-# 3. Build the library
-npm run build
-
-# 4. Verify the build output looks correct
-ls -la dist/
-# Should contain: index.js, index.mjs, index.d.ts, index.d.mts, and source maps
-
-# 5. Do a dry run to see what would be published
-npm publish --dry-run
-
-# 6. Publish to npm
-npm publish
-
-# 7. Verify the published package
-npm view @bze/bze-ui-kit
+echo "//registry.npmjs.org/:_authToken=YOUR_TOKEN" >> ~/.npmrc
 ```
 
-### Quick one-liner
+Generate the token at npmjs.com → your avatar → Access Tokens → Generate New Token → Classic → Publish.
+
+### Steps
 
 ```sh
-npm version patch && npm run build && npm publish
+# 1. Bump the version in package.json, then:
+npm run build && npm publish
 ```
 
 ## License

package/dist/index.js

@@ -3619,21 +3619,27 @@ var useSigningClient = ({ chainName }) => {
   const { getSigningClient, signingClientError, wallet, chain } = (0, import_react4.useChain)(chainName != null ? chainName : getChainName());
   const [signingClient, setSigningClient] = (0, import_react3.useState)(null);
   const [isSigningClientReady, setIsSigningClientReady] = (0, import_react3.useState)(false);
-  const hasInitialized = (0, import_react3.useRef)(false);
+  const initializedForWallet = (0, import_react3.useRef)(null);
   const createSigningClient = (0, import_react3.useCallback)(async () => {
     return getSigningClient();
   }, [getSigningClient]);
   (0, import_react3.useEffect)(() => {
-    if (!wallet || !chain || hasInitialized.current) {
+    if (!wallet || !chain) {
+      if (initializedForWallet.current !== null) {
+        setSigningClient(null);
+        setIsSigningClientReady(false);
+        initializedForWallet.current = null;
+      }
       return;
     }
+    if (initializedForWallet.current === wallet) return;
     const load = async () => {
       const client = await createSigningClient();
       if (client) {
         registerBzeEncoders(client);
         setSigningClient(client);
         setIsSigningClientReady(true);
-        hasInitialized.current = true;
+        initializedForWallet.current = wallet;
       }
     };
     load();