@berachain/berajs 0.2.4 → 0.2.6-patch.1

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

@@ -1,235 +0,0 @@
-# BeraJS — DEX (BEX) Reference
-
-BEX is Berachain's native DEX. `@berachain/berajs` provides pool data, swap quotes via multiple aggregators, and protocol pause status.
-
-## Pool List
-
-### `usePools` / `getAllPools`
-
-Paginated pool list with search and sorting.
-
-```tsx
-import { usePools } from "@berachain/berajs/hooks";
-import { GqlPoolOrderBy, GqlPoolOrderDirection } from "@berachain/graphql/pol/api";
-
-const { data, isLoading } = usePools({
-  first: 20,
-  skip: 0,
-  orderBy: GqlPoolOrderBy.TotalLiquidity,
-  orderDirection: GqlPoolOrderDirection.Desc,
-  textSearch: "HONEY", // optional
-});
-
-// data: { pools: GqlPoolFragment[], count: number }
-```
-
-## Single Pool
-
-### `usePool` / `getApiPool`
-
-Fetch one pool by its contract address.
-
-```tsx
-import { usePool } from "@berachain/berajs/hooks";
-
-const { data: pool } = usePool({ id: "0xPoolAddress" });
-```
-
-## Swap Quotes
-
-### `useAggregatorsQuotes`
-
-Get quotes from **all enabled aggregators** simultaneously, ranked best to worst.
-
-```tsx
-import { useAggregatorsQuotes } from "@berachain/berajs/hooks";
-import { SwapKind } from "@berachain-foundation/berancer-sdk";
-import type { IAggregatorArgs } from "@berachain/berajs/types";
-
-const swapArgs: IAggregatorArgs = {
-  tokenIn: {
-    address: "0xWBERA",
-    decimals: 18,
-    symbol: "WBERA",
-    name: "Wrapped BERA",
-    chainId: 80094,
-  },
-  tokenOut: {
-    address: "0xHONEY",
-    decimals: 18,
-    symbol: "HONEY",
-    name: "Honey",
-    chainId: 80094,
-  },
-  amount: "1000000000000000000", // 1 WBERA in wei
-  slippage: 0.5,                  // 0.5%
-  account: "0x...",
-  swapKind: SwapKind.GivenIn,
-};
-
-const { data: quotes, isLoading } = useAggregatorsQuotes(swapArgs);
-
-// quotes: IAggregatorQuote[] | undefined — sorted best to worst
-// quotes[0].isBest === true
-// quotes[0].amountOut        — output amount as string
-// quotes[0].amountOutUsd     — USD value as string
-// quotes[0].priceImpactPercentage
-// quotes[0].getCalldata?.({ account }) → { address, data, value, abi?, functionName? }
-```
-
-### `useSingleAggregatorQuote`
-
-Quote from one specific aggregator. Useful for dedicated aggregator UIs.
-
-```tsx
-import { useSingleAggregatorQuote } from "@berachain/berajs/hooks";
-// Same args as useAggregatorsQuotes, plus aggregator name
-```
-
-## Protocol/Pool Pause Status
-
-### `useBexStatus`
-
-**Always check before allowing swaps or deposits.**
-
-```tsx
-import { useBexStatus } from "@berachain/berajs/hooks";
-
-const { protocol, pool } = useBexStatus();
-
-// Disable all swaps when protocol is paused:
-if (protocol.isPaused) return <div>Protocol paused</div>;
-
-// Pool-level flags (set BexStatusProvider's onPoolChange first):
-pool?.isPaused           // pool is paused
-pool?.isInRecoveryMode   // proportional exit only
-pool?.disablePoolDeposits
-pool?.disablePoolWithdrawals
-```
-
-To track a specific pool, call `onPoolChange` from the context:
-
-```tsx
-import { useContext } from "react";
-import { BexStateContext } from "@berachain/berajs/contexts";
-
-const { onPoolChange } = useContext(BexStateContext);
-
-// When user navigates to a pool page:
-useEffect(() => {
-  onPoolChange({ id: poolId, isInRecoveryMode, isPaused });
-}, [poolId]);
-```
-
-## Key Types
-
-```ts
-type IAggregatorArgs = {
-  tokenIn: MinimalERC20;
-  tokenOut: MinimalERC20;
-  amount: string;       // wei string
-  slippage: number;     // e.g. 0.5 for 0.5%
-  account?: Address;
-  swapKind: SwapKind;   // from @berachain-foundation/berancer-sdk
-  publicClient?: PublicClient;
-  aggregatorsFeeBps?: number;
-  rewardVault?: Address; // stake output into this vault after swap
-};
-
-type IAggregatorQuote = {
-  name: string;
-  amountOut: string;
-  amountOutUsd: string;
-  amountIn: string;
-  amountInUsd: string;
-  priceImpactPercentage: number;
-  exchangeRate: number;
-  relativeLossPercentage: number;
-  isBest?: boolean;
-  allowanceRequirements: AllowanceQueryItem[];
-  swapFeeBps: number;
-  getCalldata?: ({ account }: { account: Address }) => Calldata;
-};
-```
-
-## Complete Example: Swap UI
-
-```tsx
-"use client";
-import { useAggregatorsQuotes, useBeraContractWrite } from "@berachain/berajs/hooks";
-import { useBexStatus } from "@berachain/berajs/hooks";
-import { TransactionActionType } from "@berachain/berajs/enum";
-import { SwapKind } from "@berachain-foundation/berancer-sdk";
-import { useAccount } from "wagmi";
-import type { Address } from "viem";
-
-const WBERA = {
-  address: "0x6969696969696969696969696969696969696969" as Address,
-  decimals: 18,
-  symbol: "WBERA",
-  name: "Wrapped BERA",
-  chainId: 80094,
-};
-const HONEY = {
-  address: "0xFCBD14DC51f0A4d49d5E53C2E0950e0bC26d0Dce" as Address,
-  decimals: 18,
-  symbol: "HONEY",
-  name: "Honey",
-  chainId: 80094,
-};
-
-export function SwapUI({ amountIn }: { amountIn: string }) {
-  const { address } = useAccount();
-  const { protocol } = useBexStatus();
-
-  const { data: quotes, isLoading: isQuoting } = useAggregatorsQuotes(
-    {
-      tokenIn: WBERA,
-      tokenOut: HONEY,
-      amount: amountIn,
-      slippage: 0.5,
-      account: address,
-      swapKind: SwapKind.GivenIn,
-    },
-    { opts: { isEnabled: !!amountIn && amountIn !== "0" && !protocol.isPaused } }
-  );
-
-  const { write, isLoading: isSwapping } = useBeraContractWrite();
-
-  const bestQuote = quotes?.[0];
-
-  const handleSwap = () => {
-    if (!bestQuote?.getCalldata || !address) return;
-    const calldata = bestQuote.getCalldata({ account: address });
-
-    write({
-      address: calldata.address,
-      data: calldata.data,
-      value: calldata.value,
-      message: "Swapping WBERA for HONEY...",
-      actionType: TransactionActionType.SWAP,
-      contractName: "bex.router",
-      onSuccess: (receipt) => console.log("Swapped!", receipt.transactionHash),
-      onError: (err) => console.error(err.displayMessage),
-    });
-  };
-
-  if (protocol.isPaused) return <div>Protocol is paused</div>;
-
-  return (
-    <div>
-      {isQuoting && <p>Getting quotes...</p>}
-      {bestQuote && !isQuoting && (
-        <div>
-          <p>Best route: {bestQuote.name}</p>
-          <p>You receive: {bestQuote.amountOut} HONEY (${bestQuote.amountOutUsd})</p>
-          <p>Price impact: {bestQuote.priceImpactPercentage.toFixed(2)}%</p>
-          <button onClick={handleSwap} disabled={isSwapping || !address}>
-            {isSwapping ? "Swapping..." : "Swap"}
-          </button>
-        </div>
-      )}
-    </div>
-  );
-}
-```

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

@@ -1,194 +0,0 @@
-# BeraJS — POL Reference
-
-POL (Proof of Liquidity) is Berachain's validator incentive system. Protocols deploy **reward vaults** that emit **BGT** (non-transferable governance token) to stakers. Validators direct BGT emissions to vaults via their cutting board weights.
-
-## Reward Vault List
-
-### `useRewardVaults` / `getRewardVaults`
-
-Paginated list of reward vaults with optional filtering.
-
-```tsx
-import { useRewardVaults } from "@berachain/berajs/hooks";
-
-const { data, isLoading, refresh } = useRewardVaults({
-  filter: {
-    first: 20,
-    // where: { search: "kodiak" }
-  },
-});
-
-// data: ApiVaultFragment[] | undefined
-// Each vault has: address, name, stakingToken, apr, tvl, etc.
-```
-
-```ts
-// Server-side:
-import { getRewardVaults } from "@berachain/berajs/actions";
-const vaults = await getRewardVaults({ filter: { first: 20 } });
-```
-
-### `useRewardVaultsQueryKey`
-
-Get the SWR cache key for SSR prefetching:
-
-```ts
-import { useRewardVaultsQueryKey } from "@berachain/berajs/hooks";
-const key = useRewardVaultsQueryKey(filter, onChainIncentives);
-```
-
-## Single Vault
-
-### `useRewardVault` / `getRewardVault`
-
-Fetch a single vault by its contract address.
-
-```tsx
-import { useRewardVault } from "@berachain/berajs/hooks";
-
-const { data: vault } = useRewardVault({ address: "0xVaultAddress" });
-```
-
-Throws `NotFoundError` if the vault does not exist.
-
-## User Vault Position
-
-### `useUserVaultInfo` / `getUserVaultInfo`
-
-Connected user's staked balance and earned BGT for a vault.
-
-```tsx
-import { useUserVaultInfo } from "@berachain/berajs/hooks";
-import { useAccount } from "wagmi";
-
-const { address } = useAccount();
-const { data: vaultInfo } = useUserVaultInfo(
-  { vaultAddress: "0xVault", account: address },
-  { opts: { isEnabled: !!address } }
-);
-
-// vaultInfo: UserVaultInfo | undefined
-// {
-//   balance: bigint,             // staked amount in wei
-//   delegatedBalance: bigint,
-//   withdrawableBalance: bigint,
-//   rewards: string,             // earned BGT (formatted string)
-//   percentage: string           // user's % share of vault
-// }
-```
-
-### `useUserVaults` / `getUserVaults`
-
-All vaults where the user has an active staked position.
-
-```tsx
-import { useUserVaults } from "@berachain/berajs/hooks";
-
-const { data: userVaults } = useUserVaults({ account: "0x..." });
-```
-
-## Vault Incentives
-
-### `useRewardVaultIncentives` / `getRewardVaultIncentives`
-
-Incentive tokens offered by protocols to attract BGT emissions to their vault.
-
-```tsx
-import { useRewardVaultIncentives } from "@berachain/berajs/hooks";
-
-const { data: incentives } = useRewardVaultIncentives({
-  vaultAddress: "0xVault",
-});
-```
-
-## BGT APR
-
-### `useBgtAprSimulation` / `getBgtAprSimulation`
-
-Estimate APR for a vault given a hypothetical BGT emission weight.
-
-```tsx
-import { useBgtAprSimulation } from "@berachain/berajs/hooks";
-
-const { data: simulation } = useBgtAprSimulation({
-  vaultAddress: "0xVault",
-  proposedWeight: 0.1, // 10% of total BGT emissions
-});
-```
-
-## Transaction Action Types (POL)
-
-```ts
-import { TransactionActionType } from "@berachain/berajs/enum";
-
-TransactionActionType.STAKE              // "Stake"
-TransactionActionType.UNSTAKE            // "Unstake"
-TransactionActionType.CLAIMING_REWARDS   // "Claiming BGT"
-TransactionActionType.CREATE_BRIBE       // "Add Incentives"
-TransactionActionType.CLAIMING_BRIBES    // "Claiming Incentives"
-TransactionActionType.BONDING_BERA       // "Stake BERA"
-TransactionActionType.UNBONDING_BERA     // "Unstake BERA"
-TransactionActionType.QUEUE_UNBONDING_BERA // "Queue Unstake BERA"
-TransactionActionType.REDEEM_BGT         // "Redeem BGT"
-```
-
-## Complete Example: Vault Card with Claim Button
-
-```tsx
-"use client";
-import { useUserVaultInfo, useRewardVault } from "@berachain/berajs/hooks";
-import { useBeraContractWrite } from "@berachain/berajs/hooks";
-import { TransactionActionType } from "@berachain/berajs/enum";
-import { useAccount } from "wagmi";
-import type { Address } from "viem";
-
-// Minimal ABI for the getReward function on reward vaults
-const REWARD_VAULT_ABI = [{
-  name: "getReward",
-  type: "function",
-  stateMutability: "nonpayable",
-  inputs: [{ name: "account", type: "address" }],
-  outputs: [{ name: "reward", type: "uint256" }],
-}] as const;
-
-export function VaultCard({ vaultAddress }: { vaultAddress: Address }) {
-  const { address } = useAccount();
-  const { data: vault } = useRewardVault({ address: vaultAddress });
-  const { data: userInfo, refresh } = useUserVaultInfo(
-    { vaultAddress, account: address },
-    { opts: { isEnabled: !!address } }
-  );
-  const { write, isLoading } = useBeraContractWrite();
-
-  const handleClaim = () => {
-    if (!address) return;
-    write({
-      address: vaultAddress,
-      abi: REWARD_VAULT_ABI,
-      functionName: "getReward",
-      params: [address],
-      message: "Claiming BGT rewards...",
-      actionType: TransactionActionType.CLAIMING_REWARDS,
-      contractName: "pol.rewardVault",
-      onSuccess: () => refresh(),
-    });
-  };
-
-  if (!vault) return null;
-
-  return (
-    <div>
-      <h3>{vault.name}</h3>
-      {userInfo && (
-        <>
-          <p>Earned BGT: {userInfo.rewards}</p>
-          <p>Your share: {userInfo.percentage}%</p>
-        </>
-      )}
-      <button onClick={handleClaim} disabled={isLoading || !address}>
-        {isLoading ? "Claiming..." : "Claim BGT"}
-      </button>
-    </div>
-  );
-}
-```

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

@@ -1,198 +0,0 @@
-# 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>
-  );
-}
-```