@evefrontier/dapp-kit 0.1.5 → 0.1.6

package/graphql/client.ts

@@ -45,7 +45,7 @@ import {
  * This is the low-level function used by all other GraphQL helper functions.
  * Use this when you need to execute custom queries not covered by the helper functions.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @typeParam T - The expected response data type
  * @param query - The GraphQL query string
  * @param variables - Variables to pass to the query
@@ -97,7 +97,7 @@ export async function executeGraphQLQuery<T = unknown>(
  * Use this for low-level object access when you need raw BCS data.
  * For JSON-decoded data, use {@link getObjectWithJson} instead.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param address - The Sui object address (0x...)
  * @returns Promise resolving to object with BCS contents
  *
@@ -121,7 +121,7 @@ export async function getObjectByAddress(address: string) {
  * which is useful for assemblies that store data in dynamic fields
  * (e.g., inventory items, configuration).
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param objectId - The Sui object ID
  * @returns Promise resolving to object with dynamic fields
  *
@@ -147,7 +147,7 @@ export async function getObjectWithDynamicFields(objectId: string) {
  * This is the most common way to fetch object data when you need
  * to read the object's fields as JavaScript objects.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param address - The Sui object address
  * @returns Promise resolving to object with JSON contents
  *
@@ -170,7 +170,7 @@ export async function getObjectWithJson(address: string) {
  * Useful for traversing ownership chains, e.g., finding all assemblies
  * owned by a specific character.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param objectAddress - The Sui object address to query owner of
  * @param ownedObjectType - Optional type filter for owned objects
  * @returns Promise resolving to owner info and owned objects (BCS format)
@@ -203,7 +203,7 @@ export async function getObjectOwnerAndOwnedObjectsByType(
  * Similar to {@link getObjectOwnerAndOwnedObjectsByType} but returns
  * JSON-decoded contents for easier consumption.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param objectAddress - The Sui object address
  * @param ownedObjectType - Optional type filter for owned objects
  * @returns Promise resolving to owner info and owned objects (JSON format)
@@ -227,7 +227,7 @@ export async function getObjectOwnerAndOwnedObjectsWithJson(
  * This is a specialized query for EVE Frontier assemblies that
  * follows the owner_cap_id to resolve the owning character.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param objectAddress - The assembly object address
  * @returns Promise resolving to assembly and character data
  * @internal
@@ -248,7 +248,7 @@ export async function getObjectAndCharacterOwner(objectAddress: string) {
  * Returns only object addresses (lightweight). Use this when you need
  * to find objects and will fetch their details separately.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param owner - The owner's Sui address
  * @param objectType - Optional Move type filter (e.g., "0xpkg::module::Type")
  * @returns Promise resolving to list of owned object addresses
@@ -281,7 +281,7 @@ export async function getOwnedObjectsByType(
  * Returns full object data with dynamic fields. Use this when you need
  * all objects from a specific package (e.g., all EVE Frontier objects).
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param owner - The owner's Sui address
  * @param packageId - The Move package ID to filter by
  * @returns Promise resolving to full object data including dynamic fields
@@ -312,7 +312,7 @@ export async function getOwnedObjectsByPackage(
  * Get all characters owned by a wallet
  * Returns the most recent character owned by the wallet
  *
- * @category GraphQL
+ * @category GraphQL Client
  */
 export async function getWalletCharacters(wallet: string) {
   return executeGraphQLQuery<GetWalletCharactersResponse>(
@@ -328,7 +328,7 @@ export async function getWalletCharacters(wallet: string) {
  * Get all characters owned by a wallet
  * Returns the characters owned by the wallet
  *
- * @category GraphQL
+ * @category GraphQL Client
  */
 export async function getCharacterAndOwnedObjects(wallet: string) {
   return executeGraphQLQuery<GetCharacterAndOwnedObjectsResponse>(
@@ -346,7 +346,7 @@ export async function getCharacterAndOwnedObjects(wallet: string) {
  * Useful for global/singleton objects where there's only one instance
  * of a particular type on-chain.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param objectType - The full Move type string
  * @returns Promise resolving to the singleton object address
  *
@@ -372,7 +372,7 @@ export async function getSingletonObjectByType(objectType: string) {
  * a table of key/value entries via dynamic fields. Returns the first object's full
  * response including contents.extract...addressAt.dynamicFields.nodes.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param objectType - The full Move type string (e.g. from getEnergyConfigType())
  * @param tableName - The table path for extract (e.g. "assembly_energy", "fuel_efficiency")
  * @returns Promise resolving to the GraphQL response with objects.nodes[0] and dynamicFields.nodes
@@ -402,7 +402,7 @@ export async function getSingletonConfigObjectByType(
  * Use with caution as this may return many results. Supports cursor-based
  * pagination for iterating through large result sets.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param objectType - The full Move type string
  * @param options - Pagination options
  * @param options.first - Number of results per page (default: 50)
@@ -442,7 +442,7 @@ export async function getObjectsByType(
  * It fetches the assembly's Move object data, dynamic fields, and
  * resolves the owner character through the ownership chain.
  *
- * @category GraphQL
+ * @category GraphQL Client
  * @param assemblyId - The assembly's Sui object ID
  * @returns Promise resolving to:
  *   - `moveObject` - The assembly's Move object data with JSON contents and dynamic fields

package/graphql/queries.ts

@@ -10,7 +10,7 @@
  * Query for fetching a specific object by address with BCS-encoded contents
  * Use this for low-level object access with raw BCS data
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OBJECT_BY_ADDRESS = `
   query GetObjectByAddress($address: SuiAddress!) {
@@ -31,11 +31,9 @@ export const GET_OBJECT_BY_ADDRESS = `
 `;
 
 /**
- * Query for fetching a specific assembly by ID with JSON-decoded contents
- * Retrieves the assembly contents and dynamic fields from the EVE Frontier world package
- * Use this for higher-level object access with parsed JSON data
+ * Object by address with JSON contents and dynamic fields (nodes).
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OBJECT_WITH_DYNAMIC_FIELDS = `
   query GetObjectWithDynamicFields($objectId: SuiAddress!) {
@@ -66,11 +64,9 @@ export const GET_OBJECT_WITH_DYNAMIC_FIELDS = `
 `;
 
 /**
- * Query for fetching a specific assembly by ID with JSON-decoded contents
- * Retrieves the assembly contents and dynamic fields from the EVE Frontier world package
- * Use this for higher-level object access with parsed JSON data
+ * Assembly object with owner/character extract and character-owned objects (e.g. inventory).
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OBJECT_DYNAMICFIELD_CHARACTER_WITH_JSON = `
 query GetObjectOwnerCharacterOwnerAndInventory(
@@ -168,7 +164,7 @@ query GetObjectOwnerCharacterOwnerAndInventory(
  * Useful for finding related objects (e.g., getting a character's assemblies)
  * Returns BCS-encoded data only
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OBJECT_OWNER_AND_OWNED_OBJECTS_BY_TYPE = `
   query GetObjectOwnerAndOwnedObjectByType($object: SuiAddress!, $owned_object_type: String) {
@@ -204,7 +200,7 @@ export const GET_OBJECT_OWNER_AND_OWNED_OBJECTS_BY_TYPE = `
  * Query to get an object's owner and their owned objects of a specific type
  * Returns both BCS and JSON-decoded data for easier consumption
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OBJECT_OWNER_AND_OWNED_OBJECTS_WITH_JSON = `
   query GetObjectOwnerAndOwnedObjectWithJson($object: SuiAddress!, $owned_object_type: String) {
@@ -242,7 +238,7 @@ export const GET_OBJECT_OWNER_AND_OWNED_OBJECTS_WITH_JSON = `
  * Query to get full object details with JSON contents
  * Used to fetch character details after getting the character ID from OwnerCap
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OBJECT_WITH_JSON = `
   query GetObjectWithJson($address: SuiAddress!) {
@@ -267,7 +263,7 @@ export const GET_OBJECT_WITH_JSON = `
  * Query to get all objects of a specific type owned by an address
  * Returns object addresses only (lightweight)
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OWNED_OBJECTS_BY_TYPE = `
   query GetOwnedObjectsByType($owner: SuiAddress!, $object_type: String) {
@@ -289,7 +285,7 @@ export const GET_OWNED_OBJECTS_BY_TYPE = `
  * Query for fetching objects owned by an address filtered by package
  * Returns full object data with dynamic fields
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OWNED_OBJECTS_BY_PACKAGE = `
   query GetOwnedObjectsByPackage($owner: SuiAddress!, $packageId: SuiAddress!) {
@@ -336,7 +332,7 @@ export const GET_OWNED_OBJECTS_BY_PACKAGE = `
  * Query to get all characters owned by a wallet
  * Returns the characters owned by the wallet
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_WALLET_CHARACTERS = `
   query GetWalletCharacters($owner: SuiAddress!, $characterPlayerProfileType: String!) {
@@ -376,7 +372,7 @@ export const GET_WALLET_CHARACTERS = `
  * Query to get character owned by a wallet and objects owned by the character
  * Returns the character and objects owned by the character
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_CHARACTER_AND_OWNED_OBJECTS = `
 query GetCharacterAndOwnedObjects($owner: SuiAddress!, $characterPlayerProfileType: String!) {
@@ -440,7 +436,7 @@ query GetCharacterAndOwnedObjects($owner: SuiAddress!, $characterPlayerProfileTy
  * Query to get a singleton object by its type
  * Returns the first object of the specified type (useful for global/singleton objects)
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_SINGLETON_OBJECT_BY_TYPE = `
   query GetSingletonObjectByType($object_type: String) {
@@ -460,7 +456,7 @@ export const GET_SINGLETON_OBJECT_BY_TYPE = `
 /**
  * Query to get a singleton config object by its type
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_SINGLETON_CONFIG_OBJECT_BY_TYPE = `
   query GetSingletonConfigObjectByType($object_type: String!, $table_name: String!) {
@@ -504,7 +500,7 @@ export const GET_SINGLETON_CONFIG_OBJECT_BY_TYPE = `
  * Query to get all objects of a specific type (global search)
  * Use with caution - may return many results
  *
- * @category GraphQL
+ * @category GraphQL Queries
  */
 export const GET_OBJECTS_BY_TYPE = `
   query GetObjectsByType($object_type: String, $first: Int, $after: String) {

package/graphql/types.ts

@@ -6,13 +6,13 @@
 // Base GraphQL Types
 // ============================================================================
 
-/** @category GraphQL */
+/** Response wrapper for GraphQL with optional `data` and `errors`. @category GraphQL Types */
 export interface GraphQLResponse<T = unknown> {
   data?: T;
   errors?: Array<{ message: string }>;
 }
 
-/** @category GraphQL */
+/** Pagination cursor and has-next flag. @category GraphQL Types */
 export interface PageInfo {
   hasNextPage: boolean;
   endCursor: string | null;
@@ -22,44 +22,44 @@ export interface PageInfo {
 // Shared building blocks (reused across response types)
 // ============================================================================
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface TypeRepr {
   repr: string;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface TypeReprWithLayout extends TypeRepr {
   layout?: string;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface ContentsBcs {
   bcs: string;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface ContentsTypeAndBcs extends ContentsBcs {
   type: TypeRepr;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface ContentsJsonAndBcs extends ContentsBcs {
   json: Record<string, unknown>;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface ContentsTypeJsonAndBcs extends ContentsJsonAndBcs {
   type: TypeRepr;
 }
 
 /** Contents with type + json only (no bcs). Reuses ContentsTypeJsonAndBcs shape.
- *  @category GraphQL
+ *  @category GraphQL Types
  */
 export type ContentsTypeAndJson = Pick<ContentsTypeJsonAndBcs, "type" | "json">;
 
 /** Node shape: contents.extract.asAddress.asObject.asMoveObject.contents.
  *  Reusable for any extract-path node whose inner contents are typed as T.
- *  @category GraphQL
+ *  @category GraphQL Types
  */
 export interface ExtractAsMoveObjectNode<T = ContentsTypeAndJson> {
   contents: {
@@ -75,24 +75,24 @@ export interface ExtractAsMoveObjectNode<T = ContentsTypeAndJson> {
   };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface PreviousTransaction {
   effects?: { timestamp?: string };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface ObjectNodes<T> {
   nodes: T[];
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface AddressWithObjects<T> {
   address: string;
   objects: ObjectNodes<T>;
 }
 
 /** GraphQL asAddress → asObject → asMoveObject ref chain.
- *  @category GraphQL
+ *  @category GraphQL Types
  */
 export interface AsMoveObjectRef<T> {
   asAddress?: {
@@ -103,14 +103,14 @@ export interface AsMoveObjectRef<T> {
 }
 
 /** Contents with only json (optional payload).
- *  @category GraphQL
+ *  @category GraphQL Types
  */
 export interface ContentsJsonOnly {
   json: Record<string, unknown>;
 }
 
 /** Move object ref whose contents have json of type T.
- *  @category GraphQL
+ *  @category GraphQL Types
  */
 export type MoveObjectRefWithJson<T> = AsMoveObjectRef<{
   contents: { json: T };
@@ -120,14 +120,14 @@ export type MoveObjectRefWithJson<T> = AsMoveObjectRef<{
 // Move Object Types
 // ============================================================================
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface MoveObjectContents {
   json?: Record<string, unknown>;
   bcs?: string;
   type?: TypeReprWithLayout;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface DynamicFieldNode {
   contents: {
     json: Record<string, unknown>;
@@ -139,7 +139,7 @@ export interface DynamicFieldNode {
   };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface MoveObjectData {
   contents: MoveObjectContents;
   dynamicFields?: ObjectNodes<DynamicFieldNode>;
@@ -149,7 +149,7 @@ export interface MoveObjectData {
 // Object Response Types
 // ============================================================================
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface SuiObjectResponse {
   address?: string;
   version?: number;
@@ -157,12 +157,12 @@ export interface SuiObjectResponse {
   asMoveObject: MoveObjectData | null;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetObjectResponse {
   object?: SuiObjectResponse;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetObjectByAddressResponse {
   object?: {
     address: string;
@@ -176,41 +176,41 @@ export interface GetObjectByAddressResponse {
 // Owner & Owned Objects Response Types
 // ============================================================================
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface OwnedObjectNode {
   contents: ContentsBcs;
   previousTransaction?: PreviousTransaction;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface AddressOwner {
   address: AddressWithObjects<OwnedObjectNode>;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetObjectOwnerAndOwnedObjectsResponse {
   object?: { owner?: { address?: AddressOwner["address"] } };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface OwnedObjectNodeWithJson {
   address: string;
   contents: ContentsJsonAndBcs;
   previousTransaction?: PreviousTransaction;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface AddressOwnerWithJson {
   address: AddressWithObjects<OwnedObjectNodeWithJson>;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetObjectOwnerAndOwnedObjectsWithJsonResponse {
   object?: { owner?: { address?: AddressOwnerWithJson["address"] } };
 }
 
 /** Node shape for owner's objects in GetObjectAndCharacterOwner (authorizedObj → character).
- *  @category GraphQL
+ *  @category GraphQL Types
  */
 export interface CharacterOwnerNode {
   contents: {
@@ -218,7 +218,7 @@ export interface CharacterOwnerNode {
   };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetObjectAndCharacterOwnerResponse {
   object: {
     asMoveObject: {
@@ -235,7 +235,7 @@ export interface GetObjectAndCharacterOwnerResponse {
   };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetObjectWithJsonResponse {
   object?: {
     address: string;
@@ -249,12 +249,12 @@ export interface GetObjectWithJsonResponse {
 // GetOwnedObjectsByType Response Types
 // ============================================================================
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface OwnedObjectAddressNode {
   address: string;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetOwnedObjectsByTypeResponse {
   address?: { objects: ObjectNodes<OwnedObjectAddressNode> };
 }
@@ -263,24 +263,24 @@ export interface GetOwnedObjectsByTypeResponse {
 // GetOwnedObjectsByPackage Response Types
 // ============================================================================
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface OwnedObjectFullNode {
   address: string;
   version: number;
   asMoveObject: MoveObjectData | null;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetOwnedObjectsByPackageResponse {
   objects: ObjectNodes<OwnedObjectFullNode>;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetWalletCharactersResponse {
   address: AddressWithObjects<ExtractAsMoveObjectNode>;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface CharacterAndOwnedObjectsNode {
   contents: {
     extract: {
@@ -296,7 +296,7 @@ export interface CharacterAndOwnedObjectsNode {
   };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetCharacterAndOwnedObjectsResponse {
   address: AddressWithObjects<CharacterAndOwnedObjectsNode>;
 }
@@ -305,18 +305,18 @@ export interface GetCharacterAndOwnedObjectsResponse {
 // Singleton & Type-based Query Response Types
 // ============================================================================
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetSingletonObjectByTypeResponse {
   objects: ObjectNodes<OwnedObjectAddressNode>;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface ConfigExtractDynamicFieldNode {
   key: { json: string };
   value: { json: string };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetSingletonConfigObjectByTypeResponse {
   objects: {
     nodes: Array<{
@@ -341,7 +341,7 @@ export interface GetSingletonConfigObjectByTypeResponse {
   };
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface ObjectWithContentsNode {
   address: string;
   version: number;
@@ -350,7 +350,7 @@ export interface ObjectWithContentsNode {
   } | null;
 }
 
-/** @category GraphQL */
+/** @category GraphQL Types */
 export interface GetObjectsByTypeResponse {
   objects: ObjectNodes<ObjectWithContentsNode> & { pageInfo: PageInfo };
 }
@@ -362,7 +362,7 @@ export interface GetObjectsByTypeResponse {
 /**
  * Raw Sui object data structure returned from the EVE Frontier package
  *
- * @category GraphQL
+ * @category GraphQL Types
  */
 export interface RawSuiObjectData {
   id: string;
@@ -422,7 +422,7 @@ export interface RawSuiObjectData {
  * OwnerCap JSON structure - returned from Character OwnerCap query
  * Contains the authorized_object_id which is the Character ID
  *
- * @category GraphQL
+ * @category GraphQL Types
  */
 export interface OwnerCapData {
   authorized_object_id: string;
@@ -432,7 +432,7 @@ export interface OwnerCapData {
 /**
  * Raw Character data structure from the EVE Frontier package
  *
- * @category GraphQL
+ * @category GraphQL Types
  */
 export interface RawCharacterData {
   id: `0x${string}`;
@@ -456,7 +456,7 @@ export interface RawCharacterData {
 /**
  * Processed character/owner information
  *
- * @category GraphQL
+ * @category GraphQL Types
  */
 export interface CharacterInfo {
   id: string;

package/hooks/useConnection.ts

@@ -9,7 +9,7 @@ import { VaultContextType } from "../types";
  * and methods to connect/disconnect wallets. Automatically detects EVE Vault
  * wallet availability.
  *
- * @category Hooks
+ * @category Hooks - Connection
  * @returns Object containing wallet state and connection methods:
  *   - `currentAccount` - The currently connected wallet account (or null)
  *   - `walletAddress` - The connected wallet's address string

package/hooks/useNotification.ts

@@ -9,7 +9,7 @@ import { NotificationContextType } from "../types";
  * and info messages to users. Commonly used after transaction completions
  * or to display important status updates.
  *
- * @category Hooks
+ * @category Hooks - Notification
  * @returns Object containing notification state and methods:
  *   - `notify` - Function to trigger a notification
  *   - `notification` - Current notification state object with:

package/hooks/useSmartObject.ts

@@ -10,7 +10,7 @@ import { SmartObjectContextType } from "../types";
  * The assembly ID is determined from URL query parameters (`?itemId=` and `?tenant=`)
  * or environment variables as a Sui object ID (`VITE_OBJECT_ID`).
  *
- * @category Hooks
+ * @category Hooks - Smart Object
  * @returns Object containing assembly state and methods:
  *   - `assembly` - The transformed assembly data (or null if not loaded)
  *   - `character` - The owner character information (or null)

package/hooks/useSponsoredTransaction.ts

@@ -133,7 +133,7 @@ function resolveAssemblyId(
 /**
  * Error union type for {@link useSponsoredTransaction} mutation failures.
  *
- * @category Hooks
+ * @category Hooks - Sponsored Transaction
  */
 export type UseSponsoredTransactionError =
   | WalletSponsoredTransactionNotSupportedError
@@ -146,14 +146,14 @@ export type UseSponsoredTransactionError =
  * Arguments passed to {@link useSponsoredTransaction} mutate/mutateAsync.
  * With assembly object (id and type derived).
  *
- * @category Hooks
+ * @category Hooks - Sponsored Transaction
  */
 export type UseSponsoredTransactionArgs = SponsoredTransactionArgs;
 
 /**
  * React Query mutation options for {@link useSponsoredTransaction}.
  *
- * @category Hooks
+ * @category Hooks - Sponsored Transaction
  */
 export type UseSponsoredTransactionMutationOptions = Omit<
   UseMutationOptions<
@@ -191,7 +191,7 @@ export type UseSponsoredTransactionMutationOptions = Omit<
  * - `effects` (optional) – Transaction effects, BCS encoded.
  * - `rawEffects` (optional) – Raw effects bytes.
  *
- * @category Hooks
+ * @category Hooks - Sponsored Transaction
  * @param options - React Query mutation options (optional)
  * @returns React Query mutation result with:
  *   - `mutate(args, options?)` - Trigger transaction (fire-and-forget)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evefrontier/dapp-kit",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "React SDK for EVE Frontier dApps on Sui",
   "main": "index.ts",
   "author": "",

package/providers/SmartObjectProvider.tsx

@@ -14,7 +14,7 @@ import {
   DetailedSmartCharacterResponse,
 } from "../types";
 
-import { POLLING_INTERVAL } from "../utils/constants";
+import { DEFAULT_TENANT, POLLING_INTERVAL } from "../utils/constants";
 import { getAssemblyWithOwner, MoveObjectData } from "../graphql";
 import {
   getObjectId,
@@ -25,9 +25,6 @@ import { getDatahubGameInfo } from "../utils/datahub";
 import { useConnection } from "../hooks/useConnection";
 import { SmartObjectContextType } from "../types";
 
-/** Tenant when not provided via URL ?tenant= (e.g. dev/default chain). */
-const DEFAULT_TENANT = "testevenet";
-
 /** Input for fetching object data: either itemId + tenant (derive object ID) or a Sui object ID directly.
  * @category Types
  */
@@ -37,6 +34,7 @@ export type FetchObjectDataInput =
 
 /** @category Providers */
 export const SmartObjectContext = createContext<SmartObjectContextType>({
+  tenant: DEFAULT_TENANT,
   assembly: null,
   assemblyOwner: null,
   loading: true,
@@ -269,6 +267,7 @@ const SmartObjectProvider = ({ children }: { children: ReactNode }) => {
   return (
     <SmartObjectContext.Provider
       value={{
+        tenant: selectedTenant,
         assembly,
         assemblyOwner,
         loading,

package/types/contexts.ts

@@ -7,8 +7,9 @@ import {
 } from "./types";
 
 /**
- * Vault Context Type
- * @category Types */
+ * Vault context: account, connection state, and connect/disconnect handlers.
+ * @category Types
+ */
 export interface VaultContextType {
   currentAccount: WalletAccount | null;
   walletAddress: string | undefined;
@@ -24,9 +25,11 @@ export enum SupportedWallets {
 }
 
 /**
- * Smart Object Context Type
- * @category Types */
+ * Smart object context: assembly, owner, loading, error, and refetch.
+ * @category Types
+ */
 export interface SmartObjectContextType {
+  tenant: string;
   assembly: AssemblyType<Assemblies> | null;
   assemblyOwner: DetailedSmartCharacterResponse | null;
   loading: boolean;

package/types/types.ts

@@ -1,3 +1,4 @@
+import { SUI_GRAPHQL_NETWORKS } from "../utils";
 import {
   DetailedAssemblyResponse,
   StorageModule,
@@ -18,6 +19,9 @@ export enum QueryParams {
   TENANT = "tenant",
 }
 
+/** @category Types */
+export type SuiGraphqlNetwork = (typeof SUI_GRAPHQL_NETWORKS)[number];
+
 // =========================================
 // Assembly State and Actions
 // =========================================

package/utils/__tests__/datahub.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { resolveTenantFromSearch, resolveDatahubHost } from "../datahub";
+import { DATAHUB_BY_TENANT, DEFAULT_TENANT } from "../constants";
+import { QueryParams } from "../../types";
+
+const DEFAULT_HOST = DATAHUB_BY_TENANT[DEFAULT_TENANT];
+
+describe("resolveTenantFromSearch (tenant resolution)", () => {
+  it("returns DEFAULT_TENANT when search is empty", () => {
+    expect(resolveTenantFromSearch("")).toBe(DEFAULT_TENANT);
+  });
+
+  it("returns DEFAULT_TENANT when tenant param is missing", () => {
+    expect(resolveTenantFromSearch("?itemId=123")).toBe(DEFAULT_TENANT);
+  });
+
+  it("returns DEFAULT_TENANT when tenant param is blank (?tenant=)", () => {
+    expect(resolveTenantFromSearch("?tenant=")).toBe(DEFAULT_TENANT);
+  });
+
+  it("trims tenant value (surrounding spaces)", () => {
+    expect(resolveTenantFromSearch("?tenant=  stillness  ")).toBe("stillness");
+    expect(resolveTenantFromSearch("?tenant=nebula  ")).toBe("nebula");
+  });
+
+  it("returns trimmed known tenant from param", () => {
+    expect(resolveTenantFromSearch(`?${QueryParams.TENANT}=nebula`)).toBe(
+      "nebula",
+    );
+    expect(resolveTenantFromSearch(`?${QueryParams.TENANT}=utopia`)).toBe(
+      "utopia",
+    );
+  });
+});
+
+describe("resolveDatahubHost (host fallback)", () => {
+  it("returns DEFAULT_TENANT host for unknown tenant", () => {
+    expect(resolveDatahubHost("unknown-tenant")).toBe(DEFAULT_HOST);
+    expect(resolveDatahubHost("")).toBe(DEFAULT_HOST);
+  });
+
+  it("returns known host for valid tenant keys", () => {
+    expect(resolveDatahubHost("stillness")).toBe(DATAHUB_BY_TENANT.stillness);
+    expect(resolveDatahubHost("nebula")).toBe(DATAHUB_BY_TENANT.nebula);
+    expect(resolveDatahubHost("utopia")).toBe(DATAHUB_BY_TENANT.utopia);
+    expect(resolveDatahubHost("testevenet")).toBe(DATAHUB_BY_TENANT.testevenet);
+  });
+});

package/utils/__tests__/mapping.test.ts

@@ -8,7 +8,6 @@ import { getObjectRegistryType } from "../constants";
 // Mock env vars for testing
 const TEST_EVE_WORLD_PACKAGE_ID =
   "0x2ff3e06b96eb830bdcffbc6cae9b8fe43f005c3b94cef05d9ec23057df16f107";
-const TEST_SUI_GRAPHQL_ENDPOINT = "https://graphql.testnet.sui.io/graphql";
 
 // Mock the GraphQL client (only for getObjectId/getRegistryAddress tests)
 vi.mock("../../graphql/client", () => ({
@@ -22,7 +21,6 @@ describe("mapping utilities", () => {
     vi.clearAllMocks();
     // Stub environment variables for tests
     vi.stubEnv("VITE_EVE_WORLD_PACKAGE_ID", TEST_EVE_WORLD_PACKAGE_ID);
-    vi.stubEnv("VITE_SUI_GRAPHQL_ENDPOINT", TEST_SUI_GRAPHQL_ENDPOINT);
   });
 
   afterEach(() => {

package/utils/burnRate.ts

@@ -18,7 +18,7 @@ export interface AdjustedBurnRate {
  * @param rawBurnTimeMs - Milliseconds to burn one unit at 100% efficiency. If non-finite or negative, treated as 0 so both returned fields are finite and consistent.
  * @param efficiencyPercent - Efficiency as percentage on a 0–100 scale (e.g. 90 for 90%). Values outside [0, 100] are treated as invalid; when null/undefined, not finite, ≤0, or >100, raw is used as-is for burn time.
  * @returns { burnTimePerUnitMs, unitsPerHour }
- * @category Utilities
+ * @category Utilities - Formatting
  */
 export function getAdjustedBurnRate(
   rawBurnTimeMs: number,

package/utils/config.ts

@@ -52,7 +52,7 @@ function parseConfig(
  * caches the result, and returns the map of type_id -> energy usage.
  * Subsequent calls return the cached map.
  *
- * @category Utilities
+ * @category Utilities - Config
  */
 export async function getEnergyConfig(): Promise<Record<number, number>> {
   if (energyConfigCache) {
@@ -88,7 +88,7 @@ export async function getEnergyConfig(): Promise<Record<number, number>> {
  * caches the result, and returns the map of type_id -> fuel efficiency.
  * Subsequent calls return the cached map.
  *
- * @category Utilities
+ * @category Utilities - Config
  */
 export async function getFuelEfficiencyConfig(): Promise<
   Record<number, number>
@@ -127,7 +127,7 @@ export async function getFuelEfficiencyConfig(): Promise<
  *
  * @param typeId - In-game type ID (e.g. from rawData.type_id)
  * @returns Energy usage (e.g. energy_constant), or 0 if not found or not yet loaded
- * @category Utilities
+ * @category Utilities - Config
  */
 export async function getEnergyUsageForType(typeId: number): Promise<number> {
   const config = await getEnergyConfig();
@@ -141,7 +141,7 @@ export async function getEnergyUsageForType(typeId: number): Promise<number> {
  *
  * @param typeId - In-game type ID (e.g. from rawData.type_id)
  * @returns Fuel efficiency (e.g. fuel_efficiency), or 0 if not found or not yet loaded
- * @category Utilities
+ * @category Utilities - Config
  */
 export async function getFuelEfficiencyForType(
   typeId: number,

package/utils/constants.ts

@@ -2,6 +2,8 @@
 // Environment Variable Helpers
 // ============================================================================
 
+import { SuiGraphqlNetwork } from "../types";
+
 /**
  * Get a required environment variable, throwing if not set.
  * @param name - The environment variable name (e.g., "VITE_SUI_GRAPHQL_ENDPOINT")
@@ -22,68 +24,85 @@ function getEnvVar(name: string): string {
 // Environment-Based Configuration
 // ============================================================================
 
+function isSuiGraphqlNetwork(value: string): value is SuiGraphqlNetwork {
+  return SUI_GRAPHQL_NETWORKS.includes(value as SuiGraphqlNetwork);
+}
+
 /**
- * Get the Sui GraphQL endpoint URL from environment.
+ * Get the Sui GraphQL endpoint URL for the given network.
+ * Unknown values fall back to testnet to avoid returning undefined.
+ * @param env - Network identifier (testnet, devnet, mainnet). Defaults to testnet.
  * @returns The GraphQL endpoint URL
- * @throws {Error} If VITE_SUI_GRAPHQL_ENDPOINT is not set
- * @category Utilities
+ * @category Utilities - Config
  */
-export const getSuiGraphqlEndpoint = (): string =>
-  getEnvVar("VITE_SUI_GRAPHQL_ENDPOINT");
+export function getSuiGraphqlEndpoint(
+  env: string = DEFAULT_GRAPHQL_NETWORK,
+): string {
+  const network = isSuiGraphqlNetwork(env) ? env : DEFAULT_GRAPHQL_NETWORK;
+  return GRAPHQL_ENDPOINTS[network];
+}
 
 /**
  * Get the EVE World package ID from environment.
  * @returns The package ID (0x-prefixed address)
  * @throws {Error} If VITE_EVE_WORLD_PACKAGE_ID is not set
- * @category Utilities
+ * @category Utilities - Config
  */
 export const getEveWorldPackageId = (): string =>
   getEnvVar("VITE_EVE_WORLD_PACKAGE_ID");
 
-/**
- * Get the Character OwnerCap type string (derived from package ID).
- * @returns The fully qualified type string for Character OwnerCap
- * @category Utilities
- */
+/** Type string for Character OwnerCap from the EVE World package. @category Utilities - Config */
 export const getCharacterOwnerCapType = (): string => {
   const pkg = getEveWorldPackageId();
   return `${pkg}::access::OwnerCap<${pkg}::character::Character>`;
 };
 
-/**
- * Get the Character PlayerProfile type string (derived from package ID).
- * @returns The fully qualified type string for Character PlayerProfile
- * @category Utilities
- */
+/** Type string for Character PlayerProfile from the EVE World package. @category Utilities - Config */
 export const getCharacterPlayerProfileType = (): string => {
   const pkg = getEveWorldPackageId();
   return `${pkg}::character::PlayerProfile`;
 };
 
-/**
- * Get the ObjectRegistry type string (derived from package ID).
- * @returns The fully qualified type string for ObjectRegistry
- * @category Utilities
- */
+/** Type string for ObjectRegistry from the EVE World package. @category Utilities - Config */
 export const getObjectRegistryType = (): string =>
   `${getEveWorldPackageId()}::object_registry::ObjectRegistry`;
 
-/**
- * Get the EnergyConfig type string (derived from package ID).
- * @returns The fully qualified type string for Energy Config
- * @category Utilities
- */
+/** Type string for EnergyConfig from the EVE World package. @category Utilities - Config */
 export const getEnergyConfigType = (): string =>
   `${getEveWorldPackageId()}::energy::EnergyConfig`;
 
-/**
- * Get the Fuel Efficiency Config type string (derived from package ID).
- * @returns The fully qualified type string for Fuel Efficiency Config
- * @category Utilities
- */
+/** Type string for FuelConfig from the EVE World package. @category Utilities - Config */
 export const getFuelEfficiencyConfigType = (): string =>
   `${getEveWorldPackageId()}::fuel::FuelConfig`;
 
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** Default Sui network for GraphQL endpoint selection.
+ *  @category Constants
+ */
+export const DEFAULT_GRAPHQL_NETWORK: SuiGraphqlNetwork = "testnet";
+
+/** Tenant when not provided via URL ?tenant= (e.g. dev/default chain).
+ *  @category Constants
+ */
+export const DEFAULT_TENANT = "stillness";
+
+/** Allowed Sui network identifiers for GraphQL endpoint selection.
+ *  @category Constants
+ */
+export const SUI_GRAPHQL_NETWORKS = ["testnet", "devnet", "mainnet"] as const;
+
+/** GraphQL endpoint URLs for each Sui network.
+ *  @category Constants
+ */
+export const GRAPHQL_ENDPOINTS: Record<SuiGraphqlNetwork, string> = {
+  testnet: "https://graphql.testnet.sui.io/graphql",
+  devnet: "https://graphql.devnet.sui.io/graphql",
+  mainnet: "https://graphql.mainnet.sui.io/graphql",
+};
+
 /** Polling interval in milliseconds (10 seconds).
  *  @category Constants
  */
@@ -128,3 +147,79 @@ export const EXCLUDED_TYPEIDS = [
  *  @category Constants
  */
 export const ONE_M3 = 1000000000000000000;
+
+export type TenantId = "utopia" | "stillness" | "testevenet" | "nebula";
+
+/** Per-tenant config: EVE token package ID (Sui) and Datahub API host. v0.0.18
+ * @category Constants
+ */
+export interface TenantConfig {
+  packageId: string;
+  datahubHost: string;
+}
+
+/** Single source of truth for the four tenants (package ID + datahub host).
+ * @category Constants
+ */
+export const TENANT_CONFIG: Record<TenantId, TenantConfig> = {
+  nebula: {
+    packageId:
+      "0x353988e063b4683580e3603dbe9e91fefd8f6a06263a646d43fd3a2f3ef6b8c1",
+    datahubHost: "world-api-nebula.test.evefrontier.tech",
+  },
+  testevenet: {
+    packageId:
+      "0x353988e063b4683580e3603dbe9e91fefd8f6a06263a646d43fd3a2f3ef6b8c1",
+    datahubHost: "world-api-testevenet.test.evefrontier.tech",
+  },
+  utopia: {
+    packageId:
+      "0xd12a70c74c1e759445d6f209b01d43d860e97fcf2ef72ccbbd00afd828043f75",
+    datahubHost: "world-api-utopia.uat.pub.evefrontier.com",
+  },
+  stillness: {
+    packageId:
+      "0x28b497559d65ab320d9da4613bf2498d5946b2c0ae3597ccfda3072ce127448c",
+    datahubHost: "world-api-stillness.live.tech.evefrontier.com",
+  },
+};
+
+/** EVE token package ID per tenant (derived from TENANT_CONFIG).
+ * @category Constants
+ */
+export const EVE_PACKAGE_ID_BY_TENANT = Object.fromEntries(
+  (Object.entries(TENANT_CONFIG) as [TenantId, TenantConfig][]).map(
+    ([id, config]) => [id, config.packageId],
+  ),
+) as Record<TenantId, string>;
+
+/** Datahub API host per tenant (derived from TENANT_CONFIG).
+ * @category Constants
+ */
+export const DATAHUB_BY_TENANT = Object.fromEntries(
+  (Object.entries(TENANT_CONFIG) as [TenantId, TenantConfig][]).map(
+    ([id, config]) => [id, config.datahubHost],
+  ),
+) as Record<TenantId, string>;
+
+/** @category Constants */
+const EVE_COIN_TYPE_SUFFIX = "::EVE::EVE";
+
+/**
+ * Returns the EVE token coin type for the given tenant.
+ * Format: `{packageId}::EVE::EVE` (Sui Move type used by RPC/GraphQL).
+ * @param tenantId - The tenant identifier (e.g., "utopia", "stillness")
+ * @returns The fully qualified EVE coin type string
+ *
+ * @category Utilities - Config
+ */
+export function getEveCoinType(tenantId: TenantId): string {
+  return `${EVE_PACKAGE_ID_BY_TENANT[tenantId]}${EVE_COIN_TYPE_SUFFIX}`;
+}
+
+/** Known EVE coin types (one per tenant) for strict matching.
+ *  @category Constants
+ */
+export const KNOWN_EVE_COIN_TYPES = new Set(
+  (Object.keys(EVE_PACKAGE_ID_BY_TENANT) as TenantId[]).map(getEveCoinType),
+);

package/utils/datahub.ts

@@ -1,4 +1,28 @@
-import { DatahubGameInfo } from "../types";
+import { DATAHUB_BY_TENANT, DEFAULT_TENANT } from "./constants";
+import { DatahubGameInfo, QueryParams } from "../types";
+
+/**
+ * Resolves tenant from a URL search string (e.g. window.location.search).
+ * Trims the param value and falls back to DEFAULT_TENANT when missing or blank.
+ * @internal
+ */
+export function resolveTenantFromSearch(search: string): string {
+  const tenant =
+    new URLSearchParams(search).get(QueryParams.TENANT)?.trim() ||
+    DEFAULT_TENANT;
+  return tenant;
+}
+
+/**
+ * Resolves the datahub host for a tenant key. Falls back to DEFAULT_TENANT host for unknown tenants.
+ * @internal
+ */
+export function resolveDatahubHost(tenant: string): string {
+  return (
+    DATAHUB_BY_TENANT[tenant as keyof typeof DATAHUB_BY_TENANT] ??
+    DATAHUB_BY_TENANT[DEFAULT_TENANT]
+  );
+}
 
 /**
  * Fetch game type information from the EVE Frontier Datahub API.
@@ -7,7 +31,9 @@ import { DatahubGameInfo } from "../types";
  * description, icon URL, and physical properties. This data is used to
  * enrich on-chain objects with human-readable information.
  *
- * @category Utilities
+ * Resolves tenant from the window.location.search param.
+ *
+ * @category Utilities - Config
  * @param typeId - The numeric type ID (from on-chain type_id field)
  * @returns Promise resolving to the type's game info
  *
@@ -29,9 +55,10 @@ import { DatahubGameInfo } from "../types";
 export async function getDatahubGameInfo(
   typeId: number,
 ): Promise<DatahubGameInfo> {
-  const response = await fetch(
-    `https://world-api-stillness.live.tech.evefrontier.com/v2/types/${typeId}`,
-  );
+  const tenant = resolveTenantFromSearch(window.location.search);
+  const host = resolveDatahubHost(tenant);
+
+  const response = await fetch(`https://${host}/v2/types/${typeId}`);
   const data = await response.json();
 
   return data;

package/utils/errors.ts

@@ -6,7 +6,7 @@ export type ErrorType = {
   message: string;
 };
 
-/** @category Utilities */
+/** @category Utilities - Error helpers */
 export const ERRORS: Record<number | string, ErrorType> = {
   1001: {
     code: 1001,
@@ -144,7 +144,7 @@ export const ERROR_MESSAGES: Record<number, string> = Object.fromEntries(
     .map(([key, value]) => [Number(key), value.message]),
 );
 
-/** @category Utilities */
+/** @category Utilities - Error helpers */
 export const parseErrorFromMessage = (
   errorMessage: string,
 ): {

package/utils/mapping.ts

@@ -7,7 +7,7 @@ import { getSingletonObjectByType } from "../graphql/client";
 /**
  * Convert raw status variant string to State enum
  *
- * @category Utilities
+ * @category Utilities - Mapping
  */
 export function parseStatus(statusVariant: string | undefined): State {
   if (!statusVariant) return State.NULL;
@@ -33,7 +33,7 @@ export function parseStatus(statusVariant: string | undefined): State {
  * @param typeRepr - The Move object type tag
  * @returns The assembly type as an enum
  *
- * @category Utilities
+ * @category Utilities - Mapping
  */
 export function getAssemblyType(typeRepr: string): Assemblies {
   if (typeRepr.includes("::storage_unit::StorageUnit")) {
@@ -68,7 +68,7 @@ let objectRegistryAddress: string | null = null;
  * Fetches the AssemblyRegistry singleton address from the chain
  * Caches the result to avoid repeated queries
  *
- * @category Utilities
+ * @category Utilities - Mapping
  */
 export async function getRegistryAddress(): Promise<string> {
   if (objectRegistryAddress) {
@@ -92,7 +92,7 @@ export async function getRegistryAddress(): Promise<string> {
  * @param itemId - The in-game item ID
  * @returns The derived Sui object ID
  *
- * @category Utilities
+ * @category Utilities - Mapping
  */
 export async function getObjectId(
   itemId: string,

package/utils/transforms.ts

@@ -21,7 +21,7 @@ import { getObjectWithJson } from "../graphql";
 /**
  * Transform CharacterInfo to DetailedSmartCharacterResponse
  *
- * @category Utilities
+ * @category Utilities - Transforms
  */
 export function transformToCharacter(
   characterInfo: CharacterInfo,
@@ -57,7 +57,7 @@ export interface TransformOptions {
  * @param moveObject - The Move object data from GraphQL
  * @param options - Optional transform options including character info
  *
- * @category Utilities
+ * @category Utilities - Transforms
  */
 export async function transformToAssembly(
   objectId: string,

package/utils/utils.ts

@@ -15,7 +15,7 @@ import { ONE_M3 } from "./constants";
  * Shortens long addresses to show only the beginning and end characters
  * with ellipsis in the middle.
  *
- * @category Utilities
+ * @category Utilities - Formatting
  * @param string - The address or hex string to abbreviate
  * @param precision - Number of characters to show on each end (default: 5)
  * @param expanded - If true, returns the full string without abbreviation
@@ -45,7 +45,7 @@ export const abbreviateAddress = (
  * Compares the assembly's owner address with the provided account address
  * to determine ownership.
  *
- * @category Utilities
+ * @category Utilities - Assembly
  * @param assembly - The assembly object to check ownership of
  * @param account - The account address to check against
  * @returns True if the account owns the assembly, false otherwise
@@ -71,7 +71,7 @@ export const isOwner = (
 /**
  * Generate a Suiscan transaction URL for a given transaction hash.
  *
- * @category Utilities
+ * @category Utilities - Assembly
  * @param suiChain - The Sui chain identifier (e.g., "sui:testnet", "sui:mainnet")
  * @param txHash - The transaction digest hash
  * @returns Full Suiscan URL to view the transaction
@@ -88,19 +88,20 @@ export const getTxUrl = (suiChain: SuiChain, txHash: string): string => {
   return `https://suiscan.xyz/${network}/tx/${txHash}`;
 };
 
+/** Strips protocol (e.g. https://) from a URL and returns the rest. @category Utilities - Formatting */
 export const parseURL = (string: string): string => {
   if (string.includes("://")) {
-    // Remove 'http' or 'https'
     return string.split("://")[1];
-  } else {
-    return string;
   }
+  return string;
 };
 
+/** Copies the given string to the clipboard. @category Utilities - Formatting */
 export const clickToCopy = (string: string) => {
   return navigator.clipboard.writeText(string);
 };
 
+/** Returns elements that appear in both arrays. @category Utilities - Formatting */
 export const getCommonItems = (array1: any[], array2: any[]) => {
   const commonItems: any[] = [];
   const set: Set<any> = new Set([]);
@@ -116,19 +117,24 @@ export const getCommonItems = (array1: any[], array2: any[]) => {
   return commonItems;
 };
 
+/** Removes trailing zeros after the last significant decimal. @category Utilities - Formatting */
 export const removeTrailingZeros = (number: string) => {
   return number.replace(/(\.\d*?[1-9])0+$|\.0*$/, "$1");
 };
 
+/** Returns the env value or fallback if empty. @category Utilities - Config */
 export const getEnv = (env: string, fallback: string): string => {
   if (!env) return fallback;
   return env;
 };
 
-/** Calculates the volume in M3
- * @param quantity - The unit quantity of the item
+/**
+ * Volume in m³ from unit quantity and volume per unit (wei, 10^18).
+ * @param quantity - Unit quantity of the item
  * @param volume - Volume per unit in wei (10^18)
- * @returns volume in m3 */
+ * @returns Volume in m³
+ * @category Utilities - Formatting
+ */
 export const getVolumeM3 = (quantity: bigint, volume: bigint): number => {
   const totalVolume = Number(quantity) * Number(volume);
   return totalVolume;
@@ -139,7 +145,7 @@ export const getVolumeM3 = (quantity: bigint, volume: bigint): number => {
  *
  * Converts from the on-chain representation (wei-like, 10^18) to m³.
  *
- * @category Utilities
+ * @category Utilities - Formatting
  * @param quantity - The raw volume value as string or bigint
  * @returns Volume in cubic meters
  *
@@ -155,7 +161,7 @@ export const formatM3 = (quantity: string | bigint): number => {
 /**
  * Get the dApp URL for an assembly, ensuring it has a protocol prefix.
  *
- * @category Utilities
+ * @category Utilities - Assembly
  * @param assembly - The assembly object
  * @returns The full dApp URL with https:// prefix if needed
  *
@@ -184,7 +190,7 @@ export const getDappUrl = (assembly: AssemblyType<Assemblies>): string => {
 /**
  * Check if two addresses match.
  *
- * @category Utilities
+ * @category Utilities - Assembly
  * @param address1 - First address to compare
  * @param address2 - Second address to compare
  * @returns True if addresses match, false otherwise
@@ -202,7 +208,7 @@ export const findOwnerByAddress = (
  *
  * Use this to narrow the type of an assembly for type-safe property access.
  *
- * @category Utilities
+ * @category Utilities - Assembly
  * @param assembly - The assembly to check
  * @param assemblyType - The expected assembly type
  * @returns True if assembly matches the specified type
@@ -232,7 +238,7 @@ export const assertAssemblyType = (
  *
  * Displays the duration in days, hours, minutes, and seconds as appropriate.
  *
- * @category Utilities
+ * @category Utilities - Formatting
  * @param seconds - Duration in seconds
  * @returns Formatted duration string (e.g., "02d 05h 30m 15s")
  *