@berachain/berajs 0.2.8-beta.0 → 0.2.8-beta.10

package/src/actions/governance/checkProposalField.ts

@@ -10,43 +10,74 @@ type CheckProposalFieldResult =
   | CheckProposalFieldResultMinimal[]
   | Record<string, CheckProposalFieldResultMinimal>;
 
-interface CheckProposalField {
-  (arg: {
-    fieldOrType:
-      | "address"
-      | "hex"
-      | "abi"
-      | "string"
-      | "bool"
-      | `uint${string}`
-      | `int${string}`
-      | "action"
-      | "title"
-      | "forumLink"
-      | "description"
-      | "logoURI"
-      | "url";
-    value: any;
-    required?: boolean;
-    baseUrl?: string;
-    components?: readonly (AbiParameter | readonly AbiParameter[])[];
-  }): CheckProposalFieldResultMinimal;
-  (arg: {
-    fieldOrType: "tuple[]" | "tuple";
-    value: any;
-    required?: boolean;
-    baseUrl?: string;
-    components?: readonly (AbiParameter | readonly AbiParameter[])[];
-  }): CheckProposalFieldResult;
+/**
+ * Internal implementation arg covering the full union of all valid fieldOrType
+ * values. The public overloads below provide the narrowed return types.
+ */
+interface CheckProposalFieldImplArg {
+  fieldOrType:
+    | "address"
+    | "hex"
+    | "abi"
+    | "string"
+    | "bool"
+    | `uint${string}`
+    | `int${string}`
+    | "action"
+    | "title"
+    | "forumLink"
+    | "description"
+    | "logoURI"
+    | "url"
+    | "tuple[]"
+    | "tuple";
+  value: unknown;
+  required?: boolean;
+  baseUrl?: string;
+  components?: readonly (AbiParameter | readonly AbiParameter[])[];
 }
-// @ts-expect-error TODO: this is not typed, will throw if not valid
-export const checkProposalField: CheckProposalField = ({
+
+/**
+ * Validates a single proposal field or ABI-typed value.
+ * Returns `null` if valid, or a `ProposalErrorCodes` value describing the problem.
+ */
+export function checkProposalField(arg: {
+  fieldOrType:
+    | "address"
+    | "hex"
+    | "abi"
+    | "string"
+    | "bool"
+    | `uint${string}`
+    | `int${string}`
+    | "action"
+    | "title"
+    | "forumLink"
+    | "description"
+    | "logoURI"
+    | "url";
+  value: unknown;
+  required?: boolean;
+  baseUrl?: string;
+  components?: readonly (AbiParameter | readonly AbiParameter[])[];
+}): CheckProposalFieldResultMinimal;
+/**
+ * For tuple/tuple[] types, may return nested error structures.
+ */
+export function checkProposalField(arg: {
+  fieldOrType: "tuple[]" | "tuple";
+  value: unknown;
+  required?: boolean;
+  baseUrl?: string;
+  components?: readonly (AbiParameter | readonly AbiParameter[])[];
+}): CheckProposalFieldResult;
+export function checkProposalField({
   fieldOrType,
   value,
   required = true,
   baseUrl,
   components,
-}) => {
+}: CheckProposalFieldImplArg): CheckProposalFieldResult {
   const notRequiredAbiTypes = ["bool", "string"];
 
   if (
@@ -89,19 +120,19 @@ export const checkProposalField: CheckProposalField = ({
       return null;
 
     case "title":
-      if (value.length === 0) {
+      if (typeof value !== "string" || value.length === 0) {
         return ProposalErrorCodes.REQUIRED;
       }
       return null;
 
     case "description":
-      if (value.length === 0) {
+      if (typeof value !== "string" || value.length === 0) {
         return ProposalErrorCodes.REQUIRED;
       }
       return null;
 
-    case "forumLink":
-      if (value.length === 0) {
+    case "forumLink": {
+      if (typeof value !== "string" || value.length === 0) {
         return ProposalErrorCodes.REQUIRED;
       }
 
@@ -109,8 +140,7 @@ export const checkProposalField: CheckProposalField = ({
         return ProposalErrorCodes.INVALID_ADDRESS;
       }
 
-      // biome-ignore lint/correctness/noSwitchDeclarations: <explanation>
-      const base = new URL(baseUrl as string);
+      const base = new URL(baseUrl!);
 
       // base.pathname = "/c/";
 
@@ -119,21 +149,25 @@ export const checkProposalField: CheckProposalField = ({
       }
 
       return null;
+    }
 
     case "address":
-      if (!isAddress(value, { strict: true })) {
+      if (typeof value !== "string" || !isAddress(value, { strict: true })) {
         return ProposalErrorCodes.INVALID_ADDRESS;
       }
 
       return null;
 
     case "hex":
-      if (!isHex(value, { strict: true })) {
+      if (typeof value !== "string" || !isHex(value, { strict: true })) {
         return ProposalErrorCodes.INVALID_ADDRESS;
       }
       return null;
 
     case "abi":
+      if (typeof value !== "string") {
+        return ProposalErrorCodes.INVALID_ABI;
+      }
       try {
         JSON.parse(value);
       } catch {
@@ -142,20 +176,29 @@ export const checkProposalField: CheckProposalField = ({
       return null;
 
     case "action":
-      if (!isAddress(value, { strict: true })) {
+      if (typeof value !== "string" || !isAddress(value, { strict: true })) {
         return ProposalErrorCodes.INVALID_ADDRESS;
       }
       return null;
 
     case "tuple":
       if (typeof value === "object" && Array.isArray(components)) {
-        const errors: Record<string, ProposalErrorCodes | null> = {};
+        const errors: Record<string, CheckProposalFieldResult> = {};
 
         for (const component of components) {
-          errors[component.name!] = checkProposalField({
-            fieldOrType: component.type,
-            value: value[component.name!],
-            components: component.components,
+          // Intersect with components? to access the field safely;
+          // it only exists on tuple AbiParameter variants
+          const abiParam = component as AbiParameter & {
+            components?: readonly AbiParameter[];
+          };
+          const name = abiParam.name!;
+          // fieldOrType is cast to "tuple" | "tuple[]" to satisfy overload 2
+          // (returns CheckProposalFieldResult). The actual runtime type dispatches
+          // to the correct branch.
+          errors[name] = checkProposalField({
+            fieldOrType: abiParam.type as "tuple" | "tuple[]",
+            value: (value as Record<string, unknown>)[name],
+            components: abiParam.components,
           });
         }
 
@@ -163,7 +206,7 @@ export const checkProposalField: CheckProposalField = ({
           return null;
         }
 
-        return errors;
+        return errors as Record<string, CheckProposalFieldResultMinimal>;
       }
 
       return null;
@@ -182,30 +225,41 @@ export const checkProposalField: CheckProposalField = ({
           return null;
         }
 
-        return errors;
+        // errors contains tuple results (null | Record<string, ...>);
+        // cast is intentional — the type definition predates nested support
+        return errors as unknown as CheckProposalFieldResultMinimal[];
       }
 
       return null;
+
     case "logoURI": {
       if (value === undefined || value === "") {
         return null;
       }
-      if (URL.canParse(value) && new URL(value).protocol === "https:") {
-        return null;
+      if (
+        typeof value !== "string" ||
+        !URL.canParse(value) ||
+        new URL(value).protocol !== "https:"
+      ) {
+        return ProposalErrorCodes.MUST_BE_HTTPS_OR_IPFS;
       }
-      return ProposalErrorCodes.MUST_BE_HTTPS_OR_IPFS;
+      return null;
     }
     case "url": {
       if (value === undefined || value === "") {
         return null;
       }
-      if (URL.canParse(value) && new URL(value).protocol === "https:") {
-        return null;
+      if (
+        typeof value !== "string" ||
+        !URL.canParse(value) ||
+        new URL(value).protocol !== "https:"
+      ) {
+        return ProposalErrorCodes.MUST_BE_HTTPS;
       }
-      return ProposalErrorCodes.MUST_BE_HTTPS;
+      return null;
     }
     default:
       console.error(`Invalid field or type: ${fieldOrType}`);
       return null;
   }
-};
+}

package/src/actions/governance/computeActualStatus.ts

@@ -15,11 +15,15 @@ export const MOCKED_PROPOSAL_STATUSES: readonly ProposalStatus[] = [
   ProposalStatus.QuorumNotReached,
 ];
 
+/**
+ * Derives the effective `ProposalStatus` by reconciling subgraph data with the
+ * on-chain contract state. Falls back to subgraph timestamps when the on-chain
+ * state is unavailable.
+ */
 export function computeActualStatus(
+  /** Subgraph proposal data */
   proposal: ProposalSelectionFragment,
-  /**
-   * Value returned by the `state` function of the governance contract.
-   */
+  /** Value returned by the `state` function of the governance contract */
   proposalOnChainState?: ProposalState,
 ): ProposalStatus {
   /**

package/src/actions/governance/exports.ts

@@ -0,0 +1,9 @@
+export * from "./checkProposalField";
+export * from "./computeActualStatus";
+export * from "./getAllProposals";
+export * from "./getBodyErrors";
+export * from "./getDecodedFunctionData";
+export * from "./getProposalDetails";
+export * from "./getProposalFromTx";
+export * from "./getProposalVotes";
+export * from "./parseProposalBody";

package/src/actions/governance/getAllProposals.ts

@@ -14,6 +14,20 @@ import {
 import { getApolloClient } from "../clients/getApolloClient";
 import { computeActualStatus } from "./computeActualStatus";
 
+export type GetAllProposalsArgs = BeraJS.BaseFunctionArgs & {
+  /** Subgraph filter applied to the proposals query */
+  where: Proposal_Filter;
+  /** Number of proposals to skip (for pagination) */
+  offset?: number;
+  /** Maximum proposals per page; must be ≤ 1000 */
+  perPage?: number;
+  orderBy?: Proposal_OrderBy;
+  orderDirection?: OrderDirection;
+  /** Full-text search query; switches to the search endpoint when provided */
+  text?: string;
+};
+
+/** Fetches a paginated list of governance proposals from the subgraph */
 export async function getAllProposals({
   where,
   orderBy,
@@ -22,14 +36,7 @@ export async function getAllProposals({
   perPage = 20,
   text,
   ...args
-}: BeraJS.BaseFunctionArgs & {
-  offset?: number;
-  where: Proposal_Filter;
-  perPage?: number;
-  orderBy?: Proposal_OrderBy;
-  orderDirection?: OrderDirection;
-  text?: string;
-}): Promise<ProposalSelectionFragment[] | undefined> {
+}: GetAllProposalsArgs): Promise<ProposalSelectionFragment[] | undefined> {
   try {
     if (perPage > 1000) {
       throw new Error("perPage must be less than 1000");

package/src/actions/governance/getBodyErrors.ts

@@ -5,10 +5,18 @@ import type {
 } from "../../types/governance";
 import { checkProposalField } from "./checkProposalField";
 
-export const getBodyErrors = (
-  proposal: CustomProposal,
-  currentTopic: GovernanceTopic,
-) => {
+export interface GetBodyErrorsArgs {
+  /** The proposal to validate */
+  proposal: CustomProposal;
+  /** The current governance topic, used for forum link base URL validation */
+  currentTopic: GovernanceTopic;
+}
+
+/** Validates the body fields (title, description, forum link) of a proposal */
+export function getBodyErrors({
+  proposal,
+  currentTopic,
+}: GetBodyErrorsArgs): CustomProposalErrors {
   const e: CustomProposalErrors = {};
   e.title = checkProposalField({
     fieldOrType: "title",
@@ -25,4 +33,4 @@ export const getBodyErrors = (
   });
 
   return e;
-};
+}

package/src/actions/governance/getDecodedFunctionData.ts

@@ -17,14 +17,19 @@ import { beraChefAbi } from "@berachain/abis/pol/rewards/beraChef";
 import { rewardVaultAbi } from "@berachain/abis/pol/rewards/rewardVault";
 
 // Function to check if ABI contains proxy-related functions
-function isProxyABI(abi: Abi[]): boolean {
-  return abi.some(
-    (item: any) =>
-      item.name === "implementation" ||
-      item.name === "proxyType" ||
-      (item.type === "constructor" &&
-        item.inputs?.[0]?.name === "implementation"),
-  );
+function isProxyABI(abi: Abi): boolean {
+  return abi.some((item: AbiItem) => {
+    const i = item as {
+      name?: string;
+      type: string;
+      inputs?: readonly { name?: string }[];
+    };
+    return (
+      i.name === "implementation" ||
+      i.name === "proxyType" ||
+      (i.type === "constructor" && i.inputs?.[0]?.name === "implementation")
+    );
+  });
 }
 
 /**
@@ -89,9 +94,10 @@ async function _getAbiForCallData({
       return knownAbi;
     }
   } catch {}
-  try {
-    return await _getAbi({ contractAddress: address, chainId, publicClient });
-  } catch {}
+
+  return _getAbi({ contractAddress: address, chainId, publicClient }).catch(
+    () => undefined,
+  );
 }
 
 function _decodeCallData(callData: `0x${string}`, abi: AbiItem[]) {
@@ -117,27 +123,30 @@ function _getFunctionSignature(abiItem: AbiFunction | undefined) {
   }
 }
 
+export interface GetDecodedFunctionDataArgs {
+  /** Contract address that emitted the calldata */
+  address: Address;
+  /** Raw calldata to decode */
+  callData: `0x${string}`;
+  /** @default defaultChainId */
+  chainId?: number;
+  publicClient: PublicClient;
+}
+
 /**
  * Decodes the function data from a given contract address and calldata.
  *
- * This function attempts to decode the provided calldata using a known set of ABIs.
- * If the call data cannot be decoded with the known ABIs, it fetches the ABI from the blockexplorer API.
+ * Attempts to decode using a known set of ABIs first, then falls back to
+ * fetching the ABI from the block-explorer API.
  *
- * @param address - The contract address.
- * @param callData - The calldata to decode, in hexadecimal format.
- * @returns An object containing the decoded ABI item, function signature, function name, and arguments.
+ * @returns An object with the decoded ABI item, function signature, function name, and arguments.
  */
 export async function getDecodedFunctionData({
   address,
   callData,
   chainId = defaultChainId,
   publicClient,
-}: {
-  address: Address;
-  callData: `0x${string}`;
-  chainId?: number;
-  publicClient: PublicClient;
-}) {
+}: GetDecodedFunctionDataArgs) {
   const knownAbi = [...beraChefAbi, ...rewardVaultAbi, ...erc20Abi];
 
   const abi = await _getAbiForCallData({

package/src/actions/governance/getProposalDetails.ts

@@ -10,13 +10,17 @@ import {
 import { getApolloClient } from "../clients/getApolloClient";
 import { computeActualStatus } from "./computeActualStatus";
 
+export type GetProposalDetailsArgs = BeraJS.BaseFunctionArgs & {
+  /** On-chain proposal ID */
+  proposalId: string;
+  client?: PublicClient;
+};
+
+/** Fetches a single proposal with its vote data from the subgraph */
 export async function getProposalDetails({
   proposalId,
   ...args
-}: BeraJS.BaseFunctionArgs & {
-  proposalId: string;
-  client?: PublicClient;
-}): Promise<ProposalWithVotesFragment | undefined> {
+}: GetProposalDetailsArgs): Promise<ProposalWithVotesFragment | undefined> {
   const governanceClient = getApolloClient("governance.subgraph", args);
 
   const res = await governanceClient.query<

package/src/actions/governance/getProposalFromTx.ts

@@ -16,17 +16,26 @@ import {
 import { assertPublicClient } from "../../errors/assert";
 import { parseProposalBody } from "./parseProposalBody";
 
+export type GetProposalFromTxArgs = {
+  /** Viem public client used to fetch block and receipt data */
+  publicClient: PublicClient | undefined;
+} & (
+  | {
+      /** Pre-fetched transaction receipt */
+      tx: TransactionReceipt;
+    }
+  | {
+      /** Transaction hash to look up */
+      txHash: Address;
+    }
+);
+
+/**
+ * Reconstructs a `ProposalWithVotesFragment` from the `ProposalCreated` event
+ * emitted in a given transaction. Returns `null` if the event is not found.
+ */
 export async function getProposalFromTx(
-  args: {
-    publicClient: PublicClient | undefined;
-  } & (
-    | {
-        tx: TransactionReceipt;
-      }
-    | {
-        txHash: Address;
-      }
-  ),
+  args: GetProposalFromTxArgs,
 ): Promise<ProposalWithVotesFragment | null> {
   assertPublicClient(args.publicClient);
 

package/src/actions/governance/getProposalParams.ts

@@ -21,25 +21,25 @@ import { hasAnyTruthyValues } from "../../utils/hasAnyTruthyValues";
 import { checkProposalField } from "./checkProposalField";
 import { getBodyErrors } from "./getBodyErrors";
 
-export const getProposalParams = ({
-  proposal,
-  currentTopic,
-  onError,
-}: {
-  /**
-   * The proposal to get the parameters for
-   */
+export interface GetProposalParamsArgs {
+  /** The proposal to encode and validate */
   proposal: CustomProposal;
-  /**
-   * The current topic
-   */
+  /** The current governance topic */
   currentTopic: GovernanceTopic;
-  /**
-   * Callback to handle errors
-   */
+  /** Called with validation errors if the proposal is invalid */
   onError?: (e: CustomProposalErrors) => void;
-}) => {
-  const e: CustomProposalErrors = getBodyErrors(proposal, currentTopic);
+}
+
+/**
+ * Validates a governance proposal and encodes its on-chain call parameters.
+ * Returns the encoded targets, values, calldatas, and description, or `undefined` if validation fails.
+ */
+export function getProposalParams({
+  proposal,
+  currentTopic,
+  onError,
+}: GetProposalParamsArgs) {
+  const e: CustomProposalErrors = getBodyErrors({ proposal, currentTopic });
 
   const actions: Address[] = [];
 
@@ -244,4 +244,4 @@ export const getProposalParams = ({
     actions,
     description,
   ] as const;
-};
+}

package/src/actions/governance/getProposalVotes.ts

@@ -6,12 +6,16 @@ import {
 
 import { getApolloClient } from "../clients/getApolloClient";
 
+export type GetProposalVotesArgs = BeraJS.BaseFunctionArgs & {
+  /** GraphQL variables forwarded to the GetProposalVotes query */
+  variables: GetProposalVotesQueryVariables;
+};
+
+/** Fetches the votes for a proposal from the subgraph */
 export async function getProposalVotes({
   variables,
   ...args
-}: BeraJS.BaseFunctionArgs & {
-  variables: GetProposalVotesQueryVariables;
-}) {
+}: GetProposalVotesArgs) {
   const governanceClient = getApolloClient("governance.subgraph", args);
   return governanceClient.query<GetProposalVotesQuery>({
     query: GetProposalVotes,

package/src/actions/governance/getQuorum.ts

@@ -5,6 +5,12 @@ import { berachainGovernanceAbi as governanceAbi } from "@berachain/abis/gov/ber
 import { assertPublicClient } from "../../errors/assert";
 import { parseBaseArgs } from "../../utils/parseBaseArgs";
 
+export type GetQuorumArgs = BeraJS.BaseFunctionArgs & {
+  /** Timestamp in seconds; defaults to now. Returns the current quorum when in the future. */
+  at?: number | string;
+  publicClient: PublicClient | undefined;
+};
+
 /**
  * Queries the quorum for a given timestamp.
  *
@@ -14,13 +20,7 @@ export async function getQuorum({
   at,
   publicClient,
   ...args
-}: {
-  /**
-   * Timestamp in seconds
-   */
-  at?: number | string;
-  publicClient: PublicClient | undefined;
-} & BeraJS.BaseFunctionArgs): Promise<string> {
+}: GetQuorumArgs): Promise<string> {
   const { config } = parseBaseArgs(args);
   assertPublicClient(publicClient);
 

package/src/actions/governance/parseProposalBody.ts

@@ -2,9 +2,16 @@ import graymatter from "gray-matter";
 
 import type { ProposalSelectionFragment } from "@berachain/graphql/governance";
 
-const parseLegacyBody = (
-  s: string,
-): { type: string | null; title: string; content: string } => {
+export type ParseProposalBodyResult = graymatter.GrayMatterFile<string> & {
+  /** Whether the body uses YAML front-matter (true) or legacy heading format (false) */
+  isFrontMatter: boolean;
+};
+
+function parseLegacyBody(s: string): {
+  type: string | null;
+  title: string;
+  content: string;
+} {
   const pattern = /#(?:([\w-]+)# )?(.+)\n([\s\S]*)/;
   const match = s.match(pattern);
 
@@ -20,13 +27,16 @@ const parseLegacyBody = (
   }
 
   throw new Error("Invalid proposal body");
-};
+}
 
-export const parseProposalBody = (
+/**
+ * Parses the body of a governance proposal into structured front-matter and content.
+ * Supports YAML front-matter format and a legacy heading-based format.
+ * Falls back to raw description on parse failure.
+ */
+export function parseProposalBody(
   proposal?: Pick<ProposalSelectionFragment, "description">,
-): graymatter.GrayMatterFile<string> & {
-  isFrontMatter: boolean;
-} => {
+): ParseProposalBodyResult {
   if (!proposal) {
     return {
       isFrontMatter: false,
@@ -70,4 +80,4 @@ export const parseProposalBody = (
       stringify: () => body,
     };
   }
-};
+}

package/src/actions/honey/getChartData.ts

@@ -1,8 +1,8 @@
 import {
   Aggregation_Interval,
-  GetChartData,
-  type GetChartDataQuery,
-  type GetChartDataQueryVariables,
+  GetSnapshots,
+  type GetSnapshotsQuery,
+  type GetSnapshotsQueryVariables,
 } from "@berachain/graphql/honey";
 
 import { getApolloClient } from "../clients/getApolloClient";
@@ -14,9 +14,9 @@ export async function getChartData({
 }) {
   const client = getApolloClient("honey.subgraph", args);
 
-  const res = await client.query<GetChartDataQuery, GetChartDataQueryVariables>(
+  const res = await client.query<GetSnapshotsQuery, GetSnapshotsQueryVariables>(
     {
-      query: GetChartData,
+      query: GetSnapshots,
       variables: {
         interval: Aggregation_Interval.Day,
         first: days,