@berachain/berajs 0.1.2 → 0.2.0

package/src/errors/getRevertReason.ts

@@ -35,9 +35,34 @@ export type GetRevertReasonArgs = {
     ))
 );
 /**
- * Get the revert reason for a transaction submitted to the blockchain and failed.
+ * Recovers the revert reason for a transaction that failed **on-chain**.
  *
- * @returns {string}
+ * When a transaction is mined but reverts, the revert reason is no longer available in the
+ * original viem error (we only get `status: "reverted"` in the receipt). This function
+ * recovers the reason by **replaying the transaction** at the same block number.
+ *
+ * ## How it works
+ *
+ * 1. **Reconstruct the call:** Either from a `txHash` (fetches tx data from chain) or from
+ *    explicit `blockNumber + to + account + data/functionName+args`.
+ * 2. **Replay via simulateContract:** Calls `publicClient.simulateContract` at the original
+ *    `blockNumber`, which reproduces the exact revert that happened on-chain.
+ * 3. **Parse the revert:** The simulated revert throws a viem error, which is caught and
+ *    parsed by `parseViemError` to extract the reason.
+ *
+ * ## Usage context
+ *
+ * This function is called internally by `beraWriteContract` when a transaction receipt has
+ * `status: "reverted"`. The recovered reason is passed into `TransactionFailedError`, which
+ * then feeds into the standard pipeline (errorMap → displayMessage → Sentry).
+ *
+ * ## ABI importance
+ *
+ * Passing the correct ABI is critical here. Without it, custom error names cannot be decoded
+ * and the reason falls back to a hex selector. The ABI is merged with `commonAbiErrors`
+ * (which includes `Error(string)` and `Panic(uint256)`) to handle standard reverts.
+ *
+ * @returns Same shape as parseViemError: `{ reason, rootCause }`
  */
 export async function getRevertReason({
   publicClient,
@@ -54,7 +79,9 @@ export async function getRevertReason({
   let functionName: string | undefined;
   let args: readonly unknown[] | undefined;
 
+  // ── Step 1: Reconstruct the original call parameters ──────────────────
   if ("txHash" in params) {
+    // Fetch the original transaction from the chain to get its input data, recipient, etc.
     const tx = await publicClient.getTransaction({
       hash: params.txHash,
     });
@@ -91,8 +118,12 @@ export async function getRevertReason({
     }
   }
 
+  // ── Step 2: Replay the transaction to reproduce the revert ────────────
+  // We intentionally call simulateContract/call expecting it to revert.
+  // The revert error is then caught and parsed by parseViemError.
   try {
     if (!abi) {
+      // No ABI available — use raw call which will revert with raw data
       if (data) {
         await publicClient.call({
           data,
@@ -106,6 +137,7 @@ export async function getRevertReason({
       }
     }
 
+    // Resolve functionName and args from the raw data if not provided
     if ("functionName" in params && "args" in params && params.functionName) {
       functionName = params.functionName;
       args = params.args;
@@ -125,6 +157,7 @@ export async function getRevertReason({
         );
       }
       try {
+        // Decode the raw calldata into function name + args using the ABI
         const decoded = decodeFunctionData({
           abi,
           data,
@@ -134,6 +167,7 @@ export async function getRevertReason({
         args = decoded.args;
       } catch (e) {
         if (e instanceof AbiFunctionSignatureNotFoundError) {
+          // Function signature not in ABI — fall back to raw call
           await publicClient.call({
             data,
             to,
@@ -150,6 +184,8 @@ export async function getRevertReason({
     }
 
     if (abi && functionName) {
+      // Replay with simulateContract — this should revert and throw a viem error
+      // containing the decoded revert reason.
       await publicClient.simulateContract({
         functionName,
         args,
@@ -159,6 +195,7 @@ export async function getRevertReason({
         blockNumber,
       });
 
+      // If we get here, the simulation succeeded (shouldn't happen for a reverted tx)
       throw new TransactionFailedError({
         message: `Getting revert reason for successful simulation`,
         functionName,
@@ -170,6 +207,8 @@ export async function getRevertReason({
 
     throw new Error("No data or function name and args provided");
   } catch (error) {
+    // ── Step 3: Parse the revert error to extract the reason ──────────
+    // The simulated revert throws a viem error chain which parseViemError unwraps.
     if (error instanceof Error) {
       return parseViemError({ error, abi, revertIfUnknown: true });
     }

package/src/errors/initBeraError.ts

@@ -3,14 +3,55 @@ import { BaseError } from "viem";
 import { BeraError } from "./BeraError";
 import { parseViemError } from "./parseViemError";
 import { RequestError } from "./RequestError";
+import type { SeverityLevel } from "./severity";
 
 /**
- * Initialize a BeraError from an error.
+ * The preferred way to normalize any unknown error into a BeraError.
  *
- * If the error is already a BeraError, it will be returned as is.
- * Otherwise, a new BeraError will be created with the error as the cause.
+ * This function acts as a smart factory that picks the correct BeraError subclass:
+ *
+ * 1. If `cause` is already a `BeraError`, returns it as-is (no double-wrapping).
+ * 2. If `cause` is a viem `BaseError`, runs `parseViemError` to classify it:
+ *    - If the root cause is an `HttpRequestError` (RPC transport failure), wraps it
+ *      in a `RequestError` with the endpoint URL extracted from the error.
+ * 3. Otherwise, wraps in a new `BeraError` — which triggers the automatic reason
+ *    detection pipeline in the BeraError constructor (parseViemError → errorMap → displayMessage).
+ *
+ * **Use this instead of `new BeraError({ cause })` when you don't know the error type.**
+ * It ensures RequestErrors are correctly classified (important for Sentry filtering
+ * and fingerprinting — RequestErrors are skipped from transaction error grouping).
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await someOperation();
+ * } catch (error) {
+ *   // Normalizes to the right subclass, reason auto-detected
+ *   throw initBeraError({ cause: error });
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Reporting to Sentry without rethrowing
+ * catch (error) {
+ *   captureException(initBeraError({ cause: error }));
+ * }
+ * ```
  */
-export function initBeraError({ cause: error }: { cause: unknown }): BeraError {
+export function initBeraError({
+  cause: error,
+  level,
+}: {
+  cause: unknown;
+  /**
+   * The severity level of the error, only used if the error is not a BeraError.
+   */
+  level?: SeverityLevel;
+}): BeraError {
+  // ── Step 1: Check if it's a viem BaseError that wraps an RPC transport failure ──
+  // parseViemError with revertIfUnknown=false won't throw — it returns { reason: undefined }
+  // if the error chain doesn't match any known type.
   if (error instanceof BaseError) {
     const parsed = parseViemError({
       error,
@@ -22,9 +63,8 @@ export function initBeraError({ cause: error }: { cause: unknown }): BeraError {
       "url" in parsed.rootCause &&
       typeof parsed.rootCause.url === "string"
     ) {
-      // the best way would be to return the RequestError
-      // but that pattern is not recommended by biome (seems legit)
-      // this is mostly supported by `initBeraError()`
+      // RPC transport failure (e.g. HTTP 502 from the RPC endpoint).
+      // Wrapping in RequestError gives it proper endpoint tagging and level="warning".
       return new RequestError({
         cause: parsed.rootCause,
         response: undefined,
@@ -32,14 +72,19 @@ export function initBeraError({ cause: error }: { cause: unknown }): BeraError {
           url: parsed.rootCause.url as string,
           type: "rpc",
         },
+        level,
       });
     }
   }
+
+  // ── Step 2: Return as-is if already a BeraError, otherwise wrap ──────────
+  // The BeraError constructor will run automatic reason detection on the cause.
   const err =
     error instanceof BeraError
       ? error
       : new BeraError({
           cause: error,
+          level,
         });
 
   return err;

package/src/errors/parseViemError.ts

@@ -15,6 +15,14 @@ import {
 
 import { commonAbiErrors } from "~/abi/utils/commonAbiErrors";
 
+/**
+ * Duck-type check for viem's BaseError.
+ *
+ * We can't always rely on `instanceof BaseError` because viem errors may originate
+ * from a different version of the `viem` package (e.g. in dependency tree mismatches).
+ * The duck-type fallback checks for the structural shape that all viem errors share:
+ * `shortMessage`, `message`, and `details`.
+ */
 function isBaseError(error: unknown): error is BaseError {
   if (error instanceof BaseError) {
     return true;
@@ -32,6 +40,12 @@ function isBaseError(error: unknown): error is BaseError {
   return false;
 }
 
+/**
+ * Type-guard for specific viem error types.
+ *
+ * Uses both `instanceof` and `error.name` to handle cases where the error
+ * was created by a different viem version (name-based fallback).
+ */
 function isViemError<T extends Error>(
   error: Error,
   name: T["name"],
@@ -48,6 +62,18 @@ function isViemError<T extends Error>(
   return false;
 }
 
+/**
+ * Extracts a human-readable reason string from a decoded Solidity error.
+ *
+ * Solidity has two kinds of revert errors:
+ * - `revert("some message")` → decoded as `Error(string)` where the message is in `args[0]`.
+ *   In this case we return the string argument (e.g. `"BAL#508"`).
+ * - `revert CustomError(...)` → decoded as `CustomError(...)` where `errorName` is the
+ *   custom error name. In this case we return `errorName` (e.g. `"NotEnoughBalance"`).
+ *
+ * The returned string is used as the `reason` field in BeraError and is matched against
+ * `errorMap.ts` to resolve a user-friendly `displayMessage`.
+ */
 export function parseDecodedError<const abi extends Abi | readonly unknown[]>(
   error: DecodeErrorResultReturnType<abi>,
 ): string | undefined {
@@ -56,25 +82,73 @@ export function parseDecodedError<const abi extends Abi | readonly unknown[]>(
     Array.isArray(error.args) &&
     error.args?.at(0)
   ) {
-    // this is a solidity error thrown by `revert` and the message is the first argument
-    // for other errors, we return the error name
+    // Solidity `revert("message")` — the message string is the reason
     return error.args?.at(0) as string;
   }
 
+  // Custom error `revert CustomError(...)` — the error name is the reason
   return error.errorName;
 }
 
 /**
- * Parses errors thrown by `publicClient.simulateContract` or `publicClient.call`.
+ * The reason extraction engine — recursively unwraps viem error chains to extract
+ * a machine-readable `reason` string.
+ *
+ * This function is the core of the automatic reason detection system. It is called by:
+ * - `BeraError` constructor (when `reason` is not manually provided)
+ * - `initBeraError` (to detect if the error is a RequestError)
+ * - `getRevertReason` (after replaying a failed on-chain transaction)
  *
- * @returns error code if available, otherwise signature or a message from the error.
+ * ## Viem error chain structure
+ *
+ * Viem errors are deeply nested. The typical chains look like:
+ *
+ * **From `simulateContract`:**
+ * ```
+ * ContractFunctionExecutionError          ← wrapper, skipped
+ *   └── ContractFunctionRevertedError     ← reason extracted here (cause.reason / cause.signature)
+ * ```
+ *
+ * **From `publicClient.call` (raw call):**
+ * ```
+ * CallExecutionError                      ← wrapper, skipped
+ *   └── ExecutionRevertedError            ← wrapper, skipped
+ *         └── RpcRequestError             ← reason decoded from cause.data using ABI
+ * ```
+ *
+ * **From `writeContract` / `sendTransaction`:**
+ * ```
+ * TransactionExecutionError               ← checked for special wallet errors
+ *   └── UserRejectedRequestError          ← "UserRejectedRequestError"
+ *   └── AtomicReadyWalletRejectedUpgradeError ← "AtomicReadyWalletRejectedUpgradeError"
+ * ```
+ *
+ * **From RPC transport failures:**
+ * ```
+ * ContractFunctionExecutionError          ← wrapper, skipped
+ *   └── HttpRequestError                  ← "HttpRequestError(status:<code>)", isRequestError=true
+ * ```
+ *
+ * The function walks `cause.cause` in a while loop until it finds an error type it can
+ * extract a reason from, or runs out of nested causes.
+ *
+ * ## Parameters
+ *
+ * @param error - Any Error instance (typically a viem BaseError).
+ * @param abi - Optional contract ABI. Merged with `commonAbiErrors` to decode revert data.
+ *              Passing the correct ABI enables decoding custom error names (e.g. "SlippageExceeded")
+ *              instead of falling back to hex selectors (e.g. "0xa3b1e29f").
+ * @param revertIfUnknown - If true, throws when the error doesn't match any known pattern.
+ *                          The BeraError constructor calls with `true`; `initBeraError` calls with `false`.
+ *
+ * @returns `{ reason, rootCause, isRequestError? }` where:
+ *   - `reason` is the extracted error code/name (matched against errorMap.ts for displayMessage)
+ *   - `rootCause` is the deepest error in the chain that was identified
+ *   - `isRequestError` is true if the error is an HTTP/RPC transport failure
  */
 export function parseViemError({
   error,
   abi,
-  /**
-   * If true, error is thrown if the revert reason is not a CallExecutionError or ContractFunctionExecutionError
-   */
   revertIfUnknown = true,
 }: {
   error: Error;
@@ -83,11 +157,9 @@ export function parseViemError({
 }): {
   reason: string | undefined;
   rootCause: unknown;
-  /**
-   * If true, the error is a request error.
-   */
   isRequestError?: boolean;
 } {
+  // If it's not a viem-shaped error, either rethrow or return the message as-is
   if (!isBaseError(error)) {
     if (revertIfUnknown) {
       throw error;
@@ -100,9 +172,16 @@ export function parseViemError({
     return { reason: error.message, rootCause: error };
   }
 
+  // Begin unwrapping the nested error chain
   let cause: unknown = error;
 
+  // Walk the nested viem error chain from outermost to innermost.
+  // Each iteration checks for known error types and either extracts the reason or
+  // skips the wrapper to go deeper into `cause.cause`.
   while (isBaseError(cause)) {
+    // ── Step 1: Skip wrapper errors that don't carry reason data ────────────
+    // ContractFunctionExecutionError is a top-level wrapper from simulateContract/writeContract.
+    // The actual revert info is in its nested cause.
     if (
       isViemError(
         cause,
@@ -110,12 +189,13 @@ export function parseViemError({
         ContractFunctionExecutionError,
       )
     ) {
-      // let's skip to the deeper cause
       cause = cause.cause;
-
       continue;
     }
 
+    // ── Step 2: Check for wallet-level errors ──────────────────────────────
+    // TransactionExecutionError wraps errors from wallet interactions (sendTransaction).
+    // Check for EIP-7702 smart wallet upgrade rejection specifically.
     if (
       isViemError(cause, "TransactionExecutionError", TransactionExecutionError)
     ) {
@@ -126,27 +206,29 @@ export function parseViemError({
         };
       }
     }
-    /**
-     * This error is likely to be thrown by publicClient.call. In this case no args are provided when sending tx
-     * but if ABI was provided, we can decode the error from the data
-     *
-     * In theory, we get here from CallExecutionError -> ExecutionRevertedError -> RpcRequestError
-     */
+
+    // ── Step 3: RpcRequestError — from raw `publicClient.call` ─────────────
+    // Error chain: CallExecutionError → ExecutionRevertedError → RpcRequestError
+    // The revert data is in `cause.data` as raw hex bytes.
+    // We decode it using the provided ABI + commonAbiErrors to get the error name.
     if (isViemError(cause, "RpcRequestError", RpcRequestError)) {
       if (!cause.data) {
+        // No revert data available — check if there's a nested message (special RPC cases)
         if (
           typeof cause.cause === "object" &&
           cause.cause &&
           "message" in cause.cause &&
           typeof cause.cause.message === "string"
         ) {
-          // this covers special cases
           return { reason: cause.cause.message, rootCause: cause.cause };
         }
 
         throw new Error("No data", { cause });
       }
 
+      // Decode the raw revert bytes into a structured error using ABI.
+      // commonAbiErrors includes Error(string) and Panic(uint256) so standard reverts
+      // are always decodable even without a user-provided ABI.
       const decodedError = decodeErrorResult({
         data: cause.data as `0x${string}`,
         abi: [...commonAbiErrors, ...(abi ?? [])],
@@ -158,12 +240,12 @@ export function parseViemError({
       };
     }
 
-    /**
-     * This error is likely to be thrown by publicClient.simulateContract.
-     * In this case, we can decode the error from the data
-     *
-     * In theory, we get here from ContractFunctionExecutionError -> ContractFunctionRevertedError
-     */
+    // ── Step 4: ContractFunctionRevertedError — from `simulateContract` ────
+    // Error chain: ContractFunctionExecutionError → ContractFunctionRevertedError
+    // Viem already decoded the revert using the ABI passed to simulateContract.
+    // `cause.reason` is the decoded error name (e.g. "NotEnoughBalance").
+    // `cause.signature` is the 4-byte selector fallback (e.g. "0x13be252b").
+    // `cause.data?.errorName` is another fallback from the decoded data.
     if (
       isViemError(
         cause,
@@ -171,8 +253,6 @@ export function parseViemError({
         ContractFunctionRevertedError,
       )
     ) {
-      // If error is not found in the abi, reason is undefined
-      // In this case, we return the signature
       return {
         reason:
           cause.reason ??
@@ -183,12 +263,17 @@ export function parseViemError({
       };
     }
 
+    // ── Step 5: UserRejectedRequestError — wallet popup dismissed ──────────
+    // The user clicked "Reject" in their wallet. Level is set to "info" by BeraError constructor.
     if (
       isViemError(cause, "UserRejectedRequestError", UserRejectedRequestError)
     ) {
       return { reason: "UserRejectedRequestError", rootCause: cause };
     }
 
+    // ── Step 6: HttpRequestError — RPC transport failure ───────────────────
+    // The RPC endpoint returned an HTTP error (e.g. 502, 503).
+    // Flagged as isRequestError so initBeraError can wrap it in a RequestError.
     if (isViemError(cause, "HttpRequestError", HttpRequestError)) {
       return {
         reason: `HttpRequestError(status:${cause.status})`,
@@ -197,10 +282,12 @@ export function parseViemError({
       };
     }
 
+    // ── Step 7: End of chain — no deeper cause to unwrap ───────────────────
     if (!cause.cause) {
       return { reason: cause.name, rootCause: cause };
     }
 
+    // Keep unwrapping
     cause = cause.cause;
   }
 

package/src/errors/severity.ts

@@ -0,0 +1,12 @@
+/**
+ * Severity levels for error reporting.
+ * Mirrors Sentry's SeverityLevel for compatibility, but owned by berajs
+ * so we don't depend on @sentry/nextjs.
+ */
+export type SeverityLevel =
+  | "fatal"
+  | "error"
+  | "warning"
+  | "log"
+  | "info"
+  | "debug";

package/src/hooks/bend/useGetConvertToAssets.ts

@@ -2,9 +2,10 @@ import useSWR from "swr";
 
 import { usePublicClient } from "@berachain/wagmi/hooks";
 
-import { type GetConvertToAssetsProps, getConvertToAssets } from "~/actions";
+import type { GetConvertToAssetsProps } from "~/actions/bend/getConvertToAssets";
+import { getConvertToAssets } from "~/actions/bend/getConvertToAssets";
 import { assertPublicClient } from "~/errors/assert";
-import type { DefaultHookOptions } from "~/types";
+import type { DefaultHookOptions } from "~/types/global";
 
 export const useGetConvertToAssets = (
   {