@berachain/berajs 0.2.2 → 0.2.4

package/.claude/skills/berajs/references/staking.md

@@ -0,0 +1,198 @@
+# BeraJS — Liquid Staking (swBERA) Reference
+
+swBERA is Berachain's native liquid staking token. Users stake BERA (or WBERA) to receive swBERA, which accrues staking yield. LST (Liquid Staking Token) vaults follow the same pattern but for third-party protocols.
+
+## APR
+
+### `getStakedBeraAPR`
+
+Server-side action. Returns the current APR as a plain `number` (e.g. `0.12` = 12%).
+
+```ts
+import { getStakedBeraAPR } from "@berachain/berajs/actions";
+
+const apr = await getStakedBeraAPR({ window: "DAY" });
+// or window: "WEEK" for 7-day annualised APR
+```
+
+This is typically cached server-side and passed down as a prop, since APR only updates every ~12 hours on the backend.
+
+## Vault Metadata
+
+### `useSWBeraVaultMetadata` / `getSWBeraVaultMetadata`
+
+On-chain vault stats for a given receipt token address (e.g. swBERA contract address).
+
+```tsx
+import { useSWBeraVaultMetadata } from "@berachain/berajs/hooks";
+import { config } from "@berachain/config/internal";
+
+const { data } = useSWBeraVaultMetadata(config.tokens.swbera);
+
+// data: VaultMetadata | undefined
+// {
+//   current: {
+//     exchangeRate: string,  // how much BERA 1 swBERA redeems for (in wei, as string)
+//     totalSupply: string,   // total swBERA supply (formatted, not wei)
+//     totalAssets: string,   // total BERA staked (formatted)
+//     tvl: string,           // total WBERA in vault (formatted)
+//   },
+//   previous: { ... },      // same shape, from ~26 hours ago
+//   totalWBeraIssued: string,
+//   lockPeriod?: number,     // unstake cooldown in seconds (undefined if no lock)
+//   totalBuyBacks: number,
+//   totalBuyBacksInLast24Hours: number,
+// }
+```
+
+> Note: `useSWBeraVaultMetadata` requires `BlockTimeProvider` in the tree (provided by `BeraFlagsProvider`).
+
+## Staking Configs
+
+### `getLSTStakeConfig`
+
+Server-side action. Resolves a list of LST vault addresses into `StakingConfig[]` by reading each vault's `asset()` on-chain.
+
+```ts
+import { getLSTStakeConfig } from "@berachain/berajs/actions";
+import { getServerSidePublicClient } from "@berachain/berajs/utils";
+
+const publicClient = await getServerSidePublicClient();
+
+// lstStakingVaults: Address[] from your config/edge config
+const lstConfigs = await getLSTStakeConfig({
+  tokenList,        // TokenWithMetadata[] — full token list to resolve symbols/metadata
+  publicClient,
+  lstStakingVaults, // vault contract addresses to resolve
+});
+
+// lstConfigs: StakingConfig[]
+```
+
+**`StakingConfig` type:**
+```ts
+type StakingConfig = {
+  id: string;                        // vault address
+  receiptToken: TokenWithMetadata;   // e.g. swBERA token
+  inputTokens: TokenWithMetadata[];  // e.g. [BERA, WBERA]
+};
+```
+
+The native swBERA config is built manually (not via `getLSTStakeConfig`):
+
+```ts
+const nativeStakingConfig: StakingConfig = {
+  id: swberaToken.address,
+  receiptToken: swberaToken,
+  inputTokens: [beraToken, wBeraToken],
+};
+
+const allConfigs = [nativeStakingConfig, ...lstConfigs];
+```
+
+## User Staked Positions & Earnings
+
+### `useStakedData`
+
+The primary hook for user staking data. Loads in two phases for progressive rendering:
+
+- **`balances`** (fast): staked amounts and USD values, earnings are `0`
+- **`data`** (slow): full picture including earnings from the vault
+
+```tsx
+import { useStakedData } from "@berachain/berajs/hooks";
+
+const {
+  balances,           // StakedBeraAsset[] | undefined — fast path, no earnings
+  data,               // StakedBeraAsset[] | undefined — slow path, full earnings
+  isLoadingBalances,  // true while fast path is pending
+  isLoadingPositions, // true while slow path is pending
+} = useStakedData(stakingConfigs); // StakingConfig[]
+
+// Show balances immediately, swap in data when available
+const positions = data ?? balances ?? [];
+const activePositions = positions.filter((p) => p.stakedAmount > 0);
+```
+
+**`StakedBeraAsset` type:**
+```ts
+type StakedBeraAsset = {
+  token: TokenWithMetadata;    // the input token (e.g. BERA)
+  apr: number;                 // current APR as decimal (e.g. 0.12 = 12%)
+  stakedAmount: number;        // staked amount in token units
+  stakedAmountUsd: number;     // USD value of staked amount
+  earnedAmount: number;        // unrealised earnings in token units (0 on fast path)
+  earnedAmountUsd: number;     // USD value of earnings (0 on fast path)
+  isLoadingEarnings?: boolean; // true on fast path while earnings are still loading
+};
+```
+
+## Queued Withdrawals
+
+### `useQueuedBeraUnlock`
+
+Fetches pending (queued but not yet claimable) withdrawals for a user.
+
+```tsx
+import { useQueuedBeraUnlock } from "@berachain/berajs/hooks";
+
+const { data: queuedWithdrawals } = useQueuedBeraUnlock({
+  receiptTokenAddresses: stakingConfigs.map((c) => c.receiptToken.address),
+  account,
+  version: "V2", // always "V2" for new deployments
+});
+
+const totalQueued = queuedWithdrawals?.reduce(
+  (sum, q) => sum + Number(q.withdrawalAmount),
+  0,
+) ?? 0;
+const hasQueuedWithdrawal = totalQueued > 0;
+```
+
+## Key Types
+
+```ts
+import type { StakingConfig, StakedBeraAsset } from "@berachain/berajs/types";
+import type { VaultMetadata } from "@berachain/berajs/actions";
+```
+
+## Complete Example: Staked Balance Display
+
+```tsx
+"use client";
+import { useStakedData } from "@berachain/berajs/hooks";
+import type { StakingConfig } from "@berachain/berajs/types";
+
+export function StakedBalance({ configs }: { configs: StakingConfig[] }) {
+  const { balances, data: positions, isLoadingBalances } = useStakedData(configs);
+
+  // Use full positions when available, otherwise show balances immediately
+  const source = positions ?? balances ?? [];
+  const active = source.filter((p) => p.stakedAmount > 0);
+
+  const totalStaked = active.reduce((sum, p) => sum + p.stakedAmountUsd, 0);
+  const totalEarned = active.reduce((sum, p) => sum + p.earnedAmountUsd, 0);
+  const hasPositions = !!positions;
+
+  if (!isLoadingBalances && active.length === 0) {
+    return <p>No staked assets.</p>;
+  }
+
+  return (
+    <div>
+      <p>Total Staked: ${totalStaked.toFixed(2)}</p>
+      <p>Total Earnings: {hasPositions ? `$${totalEarned.toFixed(2)}` : "..."}</p>
+      {active.map((asset) => (
+        <div key={asset.token.address}>
+          <span>{asset.token.symbol}</span>
+          <span>{asset.stakedAmount.toFixed(4)} staked</span>
+          <span>
+            {asset.isLoadingEarnings ? "..." : `${asset.earnedAmount.toFixed(4)} earned`}
+          </span>
+          <span>APR: {(asset.apr * 100).toFixed(2)}%</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+```

package/.claude/skills/berajs/references/tokens.md

@@ -0,0 +1,170 @@
+# BeraJS — Tokens Reference
+
+## Wallet Balances
+
+### `usePollWalletBalances` / `getWalletBalances`
+
+Fetch all ERC-20 token balances for a wallet address.
+
+```tsx
+import { usePollWalletBalances } from "@berachain/berajs/hooks";
+
+const { data: balances, isLoading } = usePollWalletBalances({
+  account: "0x...",
+});
+
+// balances: BalanceToken[]
+balances?.map((token) => (
+  <div key={token.address}>
+    {token.symbol}: {token.balance.formatted} (${token.usdValue?.toFixed(2)})
+  </div>
+));
+```
+
+```ts
+// Server-side:
+import { getWalletBalances } from "@berachain/berajs/actions";
+const balances = await getWalletBalances({ account: "0x..." });
+```
+
+**`BalanceToken` type:**
+```ts
+type BalanceToken = Token & {
+  balance: {
+    raw: string;       // wei as string — safe to pass to BigInt()
+    formatted: string; // human-readable e.g. "1.5"
+  };
+  price?: number;    // USD price per token
+  usdValue?: number; // balance * price
+};
+```
+
+## Allowances
+
+### `usePollAllowances` / `getAllowances`
+
+Check ERC-20 spending approvals. Returns whether each token needs approval before a transaction.
+
+```tsx
+import { usePollAllowances } from "@berachain/berajs/hooks";
+import type { AllowanceQueryItem } from "@berachain/berajs/types";
+
+const items: AllowanceQueryItem[] = [{
+  token: {
+    address: "0xHONEY",
+    decimals: 18,
+    symbol: "HONEY",
+    name: "Honey",
+    chainId: 80094,
+  },
+  amount: { raw: "1000000000000000000", formatted: "1.0" },
+  spender: "0xVaultAddress",
+}];
+
+const { data: allowances } = usePollAllowances({
+  account: "0x...",
+  allowanceQueryList: items,
+});
+
+// allowances[0].needsApproval → true if approval required before tx
+// allowances[0].allowance.formatted → current approved amount
+```
+
+## Token Metadata
+
+### `useTokenInformation` / `getTokenInformation`
+
+Resolve a token address to its metadata.
+
+```ts
+import { useTokenInformation } from "@berachain/berajs/hooks";
+
+const { data: token } = useTokenInformation({ address: "0x..." });
+// token: TokenWithMetadata | undefined
+// { address, decimals, symbol, name, chainId, logoURI?, tags? }
+```
+
+## Prices
+
+### `useTokenCurrentPrices` / `getTokenCurrentPrices`
+
+USD prices for multiple tokens at once.
+
+```tsx
+import { useTokenCurrentPrices } from "@berachain/berajs/hooks";
+
+const { data: priceMap } = useTokenCurrentPrices({
+  tokenAddresses: ["0xHONEY", "0xWBERA"],
+});
+
+// priceMap: TokenCurrentPriceMap
+// priceMap["0xhoney"]?.price → 1.0
+// Keys are lowercased addresses
+```
+
+## Key Types
+
+```ts
+// Base for all tokens
+type MinimalERC20 = {
+  address: Address;
+  decimals: number;
+  symbol: string;
+  name: string;
+  chainId: number;
+};
+
+// Full token with optional display metadata
+type Token = MinimalERC20 & {
+  tags?: string[];
+  logoURI?: string;
+  totalSupply?: string;
+  weight?: number | string | null;
+};
+
+// For allowance checking
+type AllowanceQueryItem = {
+  token: MinimalERC20;
+  amount: { raw: string; formatted: string };
+  spender: Address;
+};
+
+type AllowanceToken = AllowanceQueryItem & {
+  allowance: { raw: string; formatted: string };
+  needsApproval: boolean;
+};
+```
+
+## Complete Example: Token Balance List
+
+```tsx
+"use client";
+import { usePollWalletBalances } from "@berachain/berajs/hooks";
+import { useAccount } from "wagmi";
+
+export function TokenBalanceList() {
+  const { address } = useAccount();
+  const { data: balances, isLoading } = usePollWalletBalances(
+    { account: address },
+    { opts: { isEnabled: !!address } }
+  );
+
+  if (!address) return <div>Connect wallet</div>;
+  if (isLoading) return <div>Loading...</div>;
+  if (!balances?.length) return <div>No tokens found</div>;
+
+  return (
+    <ul>
+      {balances.map((token) => (
+        <li key={token.address}>
+          <span>{token.symbol}</span>
+          <span>{token.balance.formatted}</span>
+          {token.usdValue !== undefined && (
+            <span>${token.usdValue.toFixed(2)}</span>
+          )}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```

package/dist/{BexStatusProvider-nS3NcdxI.d.cts → BexStatusProvider-DRymVlQf.d.cts}

@@ -67,4 +67,4 @@ declare function useBexStatus(): {
 };
 declare function BexStatusProvider({ children, isVaultPaused, labels, factories, }: PropsWithChildren<BexStatusProviderProps>): react_jsx_runtime.JSX.Element;
 
-export { type BexStatusProviderProps as B, BexStateContext as a, BexStatusProvider as b, useBexStatus as u };
+export { BexStateContext as B, BexStatusProvider as a, type BexStatusProviderProps as b, useBexStatus as u };

package/dist/{BexStatusProvider-nS3NcdxI.d.ts → BexStatusProvider-DRymVlQf.d.ts}

@@ -67,4 +67,4 @@ declare function useBexStatus(): {
 };
 declare function BexStatusProvider({ children, isVaultPaused, labels, factories, }: PropsWithChildren<BexStatusProviderProps>): react_jsx_runtime.JSX.Element;
 
-export { type BexStatusProviderProps as B, BexStateContext as a, BexStatusProvider as b, useBexStatus as u };
+export { BexStateContext as B, BexStatusProvider as a, type BexStatusProviderProps as b, useBexStatus as u };

package/dist/{HoneyConfigProvider-CK6mOKFH.d.ts → HoneyConfigProvider-DVP_9KZn.d.ts}

@@ -387,4 +387,4 @@ interface HoneyConfigProviderProps extends HoneyConfigContextReturn {
 declare function HoneyConfigProvider({ children, ...props }: HoneyConfigProviderProps): react_jsx_runtime.JSX.Element;
 declare function useHoneyConfig(): HoneyConfigContextReturn;
 
-export { type AllowanceQueryItem as A, type BalanceToken as B, type CollateralRates as C, type IAggregatorQuote as D, type HoneySwapActions as H, type IAggregatorArgs as I, type MinimalERC20 as M, type PythLatestUpdates as P, type SwapRequest as S, type TokenWithOrder as T, type TokenWithMetadata as a, type Token as b, HoneyConfigContext as c, type HoneyConfigContextReturn as d, type HoneyConfigProviderProps as e, HoneyConfigProvider as f, type IRawAggregatorQuote as g, type PythPriceFeedMap as h, type TokenCurrentPriceMap as i, type AllowanceToken as j, type HoneyFeeMap as k, type CollateralRatesArgs as l, getHoneyFees as m, HoneyPreviewMethod as n, type HoneyPreviewArgs as o, type HoneyPreviewResult as p, type HoneyPreviewReadResult as q, getHoneyPreview as r, getPythLatestPrices as s, type TokenWithAmount as t, useHoneyConfig as u, type IUserPosition as v, type Calldata as w, type TokenPriceInfo as x, type TokenWithPrice as y, type BexStatus as z };
+export { type AllowanceQueryItem as A, type BalanceToken as B, type CollateralRates as C, type TokenWithPrice as D, type HoneySwapActions as H, type IAggregatorArgs as I, type MinimalERC20 as M, type PythLatestUpdates as P, type SwapRequest as S, type TokenWithOrder as T, type TokenWithMetadata as a, type Token as b, HoneyConfigContext as c, type HoneyConfigContextReturn as d, HoneyConfigProvider as e, type HoneyConfigProviderProps as f, type IRawAggregatorQuote as g, type PythPriceFeedMap as h, type TokenCurrentPriceMap as i, type AllowanceToken as j, type CollateralRatesArgs as k, type HoneyFeeMap as l, type HoneyPreviewArgs as m, HoneyPreviewMethod as n, type HoneyPreviewReadResult as o, type HoneyPreviewResult as p, getHoneyFees as q, getHoneyPreview as r, getPythLatestPrices as s, type TokenWithAmount as t, useHoneyConfig as u, type IUserPosition as v, type Calldata as w, type TokenPriceInfo as x, type BexStatus as y, type IAggregatorQuote as z };

package/dist/{HoneyConfigProvider-Ca3ouozs.d.cts → HoneyConfigProvider-DfkjmzEf.d.cts}

@@ -387,4 +387,4 @@ interface HoneyConfigProviderProps extends HoneyConfigContextReturn {
 declare function HoneyConfigProvider({ children, ...props }: HoneyConfigProviderProps): react_jsx_runtime.JSX.Element;
 declare function useHoneyConfig(): HoneyConfigContextReturn;
 
-export { type AllowanceQueryItem as A, type BalanceToken as B, type CollateralRates as C, type IAggregatorQuote as D, type HoneySwapActions as H, type IAggregatorArgs as I, type MinimalERC20 as M, type PythLatestUpdates as P, type SwapRequest as S, type TokenWithOrder as T, type TokenWithMetadata as a, type Token as b, HoneyConfigContext as c, type HoneyConfigContextReturn as d, type HoneyConfigProviderProps as e, HoneyConfigProvider as f, type IRawAggregatorQuote as g, type PythPriceFeedMap as h, type TokenCurrentPriceMap as i, type AllowanceToken as j, type HoneyFeeMap as k, type CollateralRatesArgs as l, getHoneyFees as m, HoneyPreviewMethod as n, type HoneyPreviewArgs as o, type HoneyPreviewResult as p, type HoneyPreviewReadResult as q, getHoneyPreview as r, getPythLatestPrices as s, type TokenWithAmount as t, useHoneyConfig as u, type IUserPosition as v, type Calldata as w, type TokenPriceInfo as x, type TokenWithPrice as y, type BexStatus as z };
+export { type AllowanceQueryItem as A, type BalanceToken as B, type CollateralRates as C, type TokenWithPrice as D, type HoneySwapActions as H, type IAggregatorArgs as I, type MinimalERC20 as M, type PythLatestUpdates as P, type SwapRequest as S, type TokenWithOrder as T, type TokenWithMetadata as a, type Token as b, HoneyConfigContext as c, type HoneyConfigContextReturn as d, HoneyConfigProvider as e, type HoneyConfigProviderProps as f, type IRawAggregatorQuote as g, type PythPriceFeedMap as h, type TokenCurrentPriceMap as i, type AllowanceToken as j, type CollateralRatesArgs as k, type HoneyFeeMap as l, type HoneyPreviewArgs as m, HoneyPreviewMethod as n, type HoneyPreviewReadResult as o, type HoneyPreviewResult as p, getHoneyFees as q, getHoneyPreview as r, getPythLatestPrices as s, type TokenWithAmount as t, useHoneyConfig as u, type IUserPosition as v, type Calldata as w, type TokenPriceInfo as x, type BexStatus as y, type IAggregatorQuote as z };