@berachain/berajs 0.2.3 → 0.2.4

package/.claude/skills/berajs/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: berajs
+description: Use when the user asks about "@berachain/berajs", "berajs SDK", "useRewardVaults", "useBeraContractWrite", "beraWriteContract", "BeraFlagsProvider", "BGT", "reward vault", "BEX pools", "Berachain DEX", "berachain token balances", "usePollWalletBalances", "getAllPools", or any question about integrating the berajs SDK into a React or Next.js application.
+version: 1.0.0
+---
+
+# BeraJS SDK — Developer Reference
+
+`@berachain/berajs` is a TypeScript SDK for Berachain's DeFi ecosystem. Built on wagmi v2, viem, and SWR.
+
+## Installation
+
+```bash
+pnpm add @berachain/berajs
+```
+
+Peer dependencies:
+```bash
+pnpm add viem react react-dom @berachain/wagmi
+```
+
+## Import Paths
+
+The package uses **sub-path exports** — never import from the root:
+
+| What you need | Import from |
+|---|---|
+| Actions (async functions) | `@berachain/berajs/actions` |
+| React hooks | `@berachain/berajs/hooks` |
+| Context providers | `@berachain/berajs/contexts` |
+| Utility functions | `@berachain/berajs/utils` |
+| TypeScript types | `@berachain/berajs/types` |
+| Enums | `@berachain/berajs/enum` |
+| ABIs | `@berachain/berajs/abi` |
+
+## Required Provider Setup
+
+Wrap your app with providers **in this order**. Only include providers for features you use:
+
+```tsx
+"use client";
+import {
+  BeraFlagsProvider,
+  TokensProvider,
+  BexStatusProvider,
+} from "@berachain/berajs/contexts";
+import { defaultBeraFlags } from "@berachain/berajs/utils";
+
+function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <BeraFlagsProvider flags={defaultBeraFlags}>
+      <TokensProvider
+        defaultTokens={[]}
+        edgeConfigTokenList={[]}
+        userTokens={[]}
+        onAddToken={() => {}}
+        onRemoveToken={() => {}}
+      >
+        <BexStatusProvider
+          isVaultPaused={false}
+          factories={{ composableStable: "enabled", weighted: "enabled" }}
+        >
+          {children}
+        </BexStatusProvider>
+      </TokensProvider>
+    </BeraFlagsProvider>
+  );
+}
+```
+
+**Provider responsibilities:**
+- `BeraFlagsProvider` — feature flags used throughout the SDK (required for all berajs hooks)
+- `TokensProvider` — token list management; required for token hooks
+- `BexStatusProvider` — vault/pool pause state; required for `useBexStatus`
+- `HoneyConfigProvider` — only needed for Honey mint/redeem features (not covered here)
+
+### SSR prefetching (Next.js)
+
+Use `SWRFallback` to pass server-fetched data to SWR hooks:
+
+```tsx
+import { SWRFallback } from "@berachain/berajs/contexts";
+import { useRewardVaultsQueryKey } from "@berachain/berajs/hooks";
+import { getRewardVaults } from "@berachain/berajs/actions";
+
+// server component
+const queryKey = useRewardVaultsQueryKey();
+const vaults = await getRewardVaults({ filter: {} });
+
+<SWRFallback fallback={{ [JSON.stringify(queryKey)]: vaults }}>
+  {children}
+</SWRFallback>
+```
+
+## Core Patterns
+
+### Actions vs Hooks
+
+**Actions** — plain async functions. Use server-side or imperatively:
+
+```ts
+import { getRewardVaults } from "@berachain/berajs/actions";
+const vaults = await getRewardVaults({ filter: {} });
+```
+
+**Hooks** — SWR-powered React hooks. Use in client components:
+
+```ts
+import { useRewardVaults } from "@berachain/berajs/hooks";
+const { data: vaults, isLoading, refresh } = useRewardVaults({ filter: {} });
+```
+
+**Rule:** In a React component → use the hook. On the server or imperatively → use the action.
+
+### BaseFunctionArgs
+
+Every action accepts `BeraJS.BaseFunctionArgs` as a spread:
+
+```ts
+// Defaults to mainnet (chainId 80094)
+await getRewardVaults({ filter: {} });
+
+// Override for testnet:
+import { ChainId } from "@berachain/config";
+await getRewardVaults({ filter: {}, chainId: ChainId.BEPOLIA });
+```
+
+### DefaultHookOptions
+
+Every hook accepts an optional second argument:
+
+```ts
+// Conditionally fetch (wait for wallet connection):
+const { data } = useRewardVaults(
+  { filter: {} },
+  { opts: { isEnabled: !!account } }
+);
+
+// Custom refresh interval (ms):
+const { data } = usePollWalletBalances(
+  { account },
+  { opts: { refreshInterval: 5000 } }
+);
+```
+
+### DefaultHookReturnType
+
+All hooks return:
+
+```ts
+{
+  data: T | undefined;
+  isLoading: boolean;    // true on first fetch
+  isValidating: boolean; // true on any fetch including refetch
+  error: any;
+  refresh: () => void;   // triggers revalidation (replaces SWR mutate)
+}
+```
+
+### Sending Transactions
+
+```tsx
+import { useBeraContractWrite } from "@berachain/berajs/hooks";
+import { TransactionActionType } from "@berachain/berajs/enum";
+
+const { write, isLoading, isSuccess, isError, reset } = useBeraContractWrite({
+  onSuccess: (receipt) => console.log("Done", receipt.transactionHash),
+  onError: (error) => console.error(error.displayMessage),
+});
+
+write({
+  address: "0xContract",
+  abi: myAbi,
+  functionName: "myFunction",
+  params: [arg1, arg2],
+  message: "Doing the thing...",
+  actionType: TransactionActionType.STAKE,
+  contractName: "pol.rewardVault", // required in dev; see ContractName enum
+});
+```
+
+**Batch calls (EIP-5792):**
+
+```ts
+write({
+  message: "Approve and stake",
+  actionType: TransactionActionType.STAKE,
+  calls: [
+    { address: tokenAddress, abi: erc20Abi, functionName: "approve", params: [spender, amount] },
+    { address: vaultAddress, abi: vaultAbi, functionName: "stake", params: [amount] },
+  ],
+});
+```
+
+**Key `IContractWrite` fields:**
+- `message` — shown to user while pending
+- `actionType` — from `TransactionActionType` enum
+- `contractName` — required in dev mode; values from `ContractName` enum
+- `permissionless: true` — set if `msg.sender` does not matter
+- `onSuccess(receipt, writeArgs)` — after confirmation
+- `onError(error, writeArgs)` — `error.displayMessage` is user-safe
+- `onSubmission({ txHash }, writeArgs)` — when tx hash is available
+- `onWarning(error, writeArgs)` — non-fatal warning (tx still submitted)
+
+### Error Types
+
+Import from `@berachain/berajs/errors`:
+
+| Type | When it appears |
+|---|---|
+| `BeraError` | Base class for all berajs errors |
+| `TransactionFailedError` | Tx reverted or simulation failed |
+| `NotFoundError` | Resource does not exist (e.g. unknown vault address) |
+| `InvalidArgumentError` | Wrong or missing argument |
+| `RequestError` | Network/RPC request failed |
+
+## Domain References
+
+- **Tokens** — `./references/tokens.md`
+- **POL (Reward Vaults, BGT)** — `./references/pol.md`
+- **DEX (Pools, Swaps)** — `./references/dex.md`
+- **Liquid Staking (swBERA)** — `./references/staking.md`

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

@@ -0,0 +1,235 @@
+# 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

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