@evefrontier/dapp-kit 0.1.0

package/utils/datahub.ts

@@ -0,0 +1,76 @@
+/**
+ * Game item/type information from the EVE Frontier Datahub API.
+ *
+ * Contains metadata about items, assemblies, and other game objects
+ * including display names, descriptions, icons, and physical properties.
+ *
+ * @category Types
+ */
+export interface DatahubGameInfo {
+  /** The type ID (matches on-chain type_id) */
+  id: number;
+  /** Display name of the item/type */
+  name: string;
+  /** Description text */
+  description: string;
+  /** Mass in kg */
+  mass: number;
+  /** Radius in meters */
+  radius: number;
+  /** Volume in cubic meters */
+  volume: number;
+  /** Portion size for stacking */
+  portionSize: number;
+  /** Category group name (e.g., "Structures") */
+  groupName: string;
+  /** Category group ID */
+  groupId: number;
+  /** Top-level category name */
+  categoryName: string;
+  /** Top-level category ID */
+  categoryId: number;
+  /** URL to the item's icon image */
+  iconUrl: string;
+  /** Additional type-specific attributes */
+  attributes?: {
+    energyConstant?: number;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Fetch game type information from the EVE Frontier Datahub API.
+ *
+ * Retrieves metadata about a game type by its ID, including display name,
+ * description, icon URL, and physical properties. This data is used to
+ * enrich on-chain objects with human-readable information.
+ *
+ * @category Utilities
+ * @param typeId - The numeric type ID (from on-chain type_id field)
+ * @returns Promise resolving to the type's game info
+ *
+ * @example Fetch assembly type info
+ * ```typescript
+ * const typeInfo = await getDatahubGameInfo(83463);
+ * console.log(typeInfo.name);        // "Smart Storage Unit"
+ * console.log(typeInfo.iconUrl);     // URL to icon
+ * console.log(typeInfo.description); // Description text
+ * ```
+ *
+ * @example Enrich inventory items
+ * ```typescript
+ * const inventoryItem = { type_id: 12345, quantity: 100 };
+ * const info = await getDatahubGameInfo(inventoryItem.type_id);
+ * console.log(`${info.name} x${inventoryItem.quantity}`);
+ * ```
+ */
+export async function getDatahubGameInfo(
+  typeId: number
+): Promise<DatahubGameInfo> {
+  const response = await fetch(
+    `https://world-api-stillness.live.tech.evefrontier.com/v2/types/${typeId}`
+  );
+  const data = await response.json();
+
+  return data;
+}

package/utils/errors.ts

@@ -0,0 +1,171 @@
+/** @category Types */
+export type ErrorType = {
+  code: number;
+  name: string;
+  patterns: string[];
+  message: string;
+};
+
+/** @category Utilities */
+export const ERRORS: Record<number | string, ErrorType> = {
+  1001: {
+    code: 1001,
+    name: "Unknown Error",
+    patterns: ["unknown error"],
+    message: "An unknown error occurred.",
+  },
+  1002: {
+    code: 1002,
+    name: "Network Error",
+    patterns: ["network error", "connection failed", "failed to fetch"],
+    message: "",
+  },
+  1003: {
+    code: 1003,
+    name: "Invalid Input Error",
+    patterns: ["invalid input", "bad request", "malformed"],
+    message: "",
+  },
+  2001: {
+    code: 2001,
+    name: "Contract Call Error",
+    patterns: ["contract call error", "execution reverted", "out of gas"],
+    message: "Error calling the smart contract.",
+  },
+  2002: {
+    code: 2002,
+    name: "Contract Deployment Error",
+    patterns: ["contract deployment error", "contract creation failed"],
+    message: "",
+  },
+  2003: {
+    code: 2003,
+    name: "World Resource Not Found Error",
+    patterns: ["Error: World_ResourceNotFound"],
+    message: "World resource not found.",
+  },
+  2004: {
+    code: 2004,
+    name: "ABI Function Not Found Error",
+    patterns: ["AbiErrorSignatureNotFoundError"],
+    message: "Function not found in ABI",
+  },
+  2005: {
+    code: 2005,
+    name: "ERC2771 Forwarder contract Not Found Error",
+    patterns: ["Forwarder contract"],
+    message: "ERC2771 forwarder contract could not be found",
+  },
+  2006: {
+    code: 2006,
+    name: "callFrom Function Not Found Error",
+    patterns: ["callFrom Function"],
+    message: "callFrom Function not found in ABI",
+  },
+  2007: {
+    code: 2007,
+    name: "Abi Encoding Bytes Size Mismatch Error",
+    patterns: ["does not match expected size"],
+    message: "Size of bytes does not match expected size.",
+  },
+  2008: {
+    code: 2008,
+    name: "Contract Revert Error",
+    patterns: ["contract revert", "reverted"],
+    message: "Function simulation reverted",
+  },
+  3001: {
+    code: 3001,
+    name: "Insufficient Gas",
+    patterns: ["insufficient gas", "not enough gas", "balance too low"],
+    message: "Insufficient funds for GAS.",
+  },
+  3002: {
+    code: 3002,
+    name: "Insufficient Eve",
+    patterns: ["insufficient EVE", "not enough EVE"],
+    message: "Insufficient EVE.",
+  },
+  3003: {
+    code: 3003,
+    name: "User Denied Transaction",
+    patterns: [
+      "User denied transaction signature.",
+      "transaction rejected",
+      "User rejected the request",
+    ],
+    message: "User rejected the transaction.",
+  },
+  3004: {
+    code: 3004,
+    name: "Transaction Timeout",
+    patterns: ["transaction timeout", "timeout exceeded"],
+    message: "",
+  },
+  4001: {
+    code: 4001,
+    name: "Unauthorized Access",
+    patterns: ["unauthorized access", "permission denied"],
+    message: "",
+  },
+  4002: {
+    code: 4002,
+    name: "User Not Logged In",
+    patterns: ["user not logged in", "authentication required"],
+    message: "",
+  },
+  4003: {
+    code: 4003,
+    name: "Chain Mismatch",
+    patterns: ["does not match the target chain"],
+    message: "Please check the chain your wallet is connected to.",
+  },
+  5001: {
+    code: 5001,
+    name: "Lens Unavailable",
+    patterns: ["no lens"],
+    message: "There are no lenses available here",
+  },
+};
+
+/* Manually assign additional aliases for the ERRORS object */
+ERRORS.UNKNOWN_ERROR = ERRORS[1001];
+ERRORS.CONTRACT_CALL = ERRORS[2001];
+ERRORS.ABI_FUNCTION_NOT_FOUND = ERRORS[2004];
+ERRORS.FORWARDER_NOT_FOUND = ERRORS[2005];
+ERRORS.CALLFROM_NOT_FOUND = ERRORS[2006];
+ERRORS.INSUFFICIENT_EVE = ERRORS[3002];
+ERRORS.LENS_UNAVAILABLE = ERRORS[5001];
+
+/** @category Utilities */
+export const ERROR_MESSAGES: Record<number, string> = Object.fromEntries(
+  Object.entries(ERRORS)
+    .filter(([key]) => /^\d+$/.test(key))
+    .map(([key, value]) => [Number(key), value.message]),
+);
+
+/** @category Utilities */
+export const parseErrorFromMessage = (
+  errorMessage: string,
+): {
+  code: number;
+  name: string;
+  patterns: string[];
+} => {
+  for (const error of Object.values(ERRORS)) {
+    for (const pattern of error.patterns) {
+      if (new RegExp(pattern, "i").test(errorMessage)) {
+        return {
+          code: +error.code,
+          name: error.name,
+          patterns: error.patterns,
+        };
+      }
+    }
+  }
+  return {
+    code: 1001,
+    name: "Unknown Error",
+    patterns: ["unknown error"],
+  };
+};

package/utils/index.ts

@@ -0,0 +1,38 @@
+// Transform utilities
+export {
+  parseStatus,
+  getAssemblyType,
+  getObjectId,
+  getRegistryAddress,
+} from "./mapping";
+export { transformToAssembly, transformToCharacter } from "./transforms";
+export type { TransformOptions } from "./transforms";
+
+// Datahub utilities
+export { getDatahubGameInfo } from "./datahub";
+export type { DatahubGameInfo } from "./datahub";
+
+// General utilities
+export {
+  assertAssemblyType,
+  abbreviateAddress,
+  clickToCopy,
+  findOwnerByAddress,
+  formatM3,
+  formatDuration,
+  getCommonItems,
+  getDappUrl,
+  getEnv,
+  getTxUrl,
+  getVolumeM3,
+  isOwner,
+  parseURL,
+  removeTrailingZeros,
+} from "./utils";
+
+// Constants
+export * from "./constants";
+
+// Error handling
+export { ERRORS, ERROR_MESSAGES, parseErrorFromMessage } from "./errors";
+export type { ErrorType } from "./errors";

package/utils/mapping.ts

@@ -0,0 +1,115 @@
+import { bcs } from "@mysten/sui/bcs";
+import { Assemblies, State } from "../types";
+import { deriveObjectID } from "@mysten/sui/utils";
+import { getEveWorldPackageId, getObjectRegistryType } from "./constants";
+import { getSingletonObjectByType } from "../graphql/client";
+
+/**
+ * Convert raw status variant string to State enum
+ *
+ * @category Utilities
+ */
+export function parseStatus(statusVariant: string | undefined): State {
+  if (!statusVariant) return State.NULL;
+
+  switch (statusVariant.toUpperCase()) {
+    case "ONLINE":
+      return State.ONLINE;
+    case "OFFLINE":
+      return State.ANCHORED;
+    case "ANCHORED":
+      return State.ANCHORED;
+    case "UNANCHORED":
+      return State.UNANCHORED;
+    case "DESTROYED":
+      return State.DESTROYED;
+    default:
+      return State.NULL;
+  }
+}
+
+/**
+ * Get assembly type from Move object type tag
+ * @param typeRepr - The Move object type tag
+ * @returns The assembly type as an enum
+ *
+ * @category Utilities
+ */
+export function getAssemblyType(typeRepr: string): Assemblies {
+  if (typeRepr.includes("::storage_unit::StorageUnit")) {
+    return Assemblies.SmartStorageUnit;
+  }
+  if (typeRepr.includes("::turret::Turret")) {
+    return Assemblies.SmartTurret;
+  }
+  if (typeRepr.includes("::gate::Gate")) {
+    return Assemblies.SmartGate;
+  }
+  if (typeRepr.includes("::network_node::NetworkNode")) {
+    return Assemblies.NetworkNode;
+  }
+  if (typeRepr.includes("::manufacturing::Manufacturing")) {
+    return Assemblies.Manufacturing;
+  }
+  if (typeRepr.includes("::refinery::Refinery")) {
+    return Assemblies.Refinery;
+  }
+
+  // Assembly type not found, return default SmartStorageUnit
+  return Assemblies.SmartStorageUnit;
+}
+
+// Cache for the Registry address
+let objectRegistryAddress: string | null = null;
+/**
+ * Fetches the AssemblyRegistry singleton address from the chain
+ * Caches the result to avoid repeated queries
+ *
+ * @category Utilities
+ */
+export async function getRegistryAddress(): Promise<string> {
+  if (objectRegistryAddress) {
+    return objectRegistryAddress;
+  }
+
+  const registryType = getObjectRegistryType();
+  const result = await getSingletonObjectByType(registryType);
+
+  const address = result.data?.objects?.nodes?.[0]?.address;
+  if (!address) {
+    throw new Error(`ObjectRegistry not found for type: ${registryType}`);
+  }
+
+  objectRegistryAddress = address;
+  return address;
+}
+
+/**
+ * Derives an object ID from an in-game item ID using the AssemblyRegistry
+ * @param itemId - The in-game item ID
+ * @returns The derived Sui object ID
+ *
+ * @category Utilities
+ */
+export async function getObjectId(
+  itemId: string,
+  selectedTenant: string,
+): Promise<string> {
+  const registryAddress = await getRegistryAddress();
+
+  const bcsType = bcs.struct("TenantItemId", {
+    id: bcs.u64(),
+    tenant: bcs.string(),
+  });
+  const key = bcsType
+    .serialize({ id: BigInt(itemId), tenant: selectedTenant })
+    .toBytes();
+
+  const objectId = deriveObjectID(
+    registryAddress,
+    `${getEveWorldPackageId()}::in_game_id::TenantItemId`,
+    key,
+  );
+
+  return objectId;
+}

package/utils/transforms.ts

@@ -0,0 +1,258 @@
+import {
+  Assemblies,
+  AssemblyType,
+  State,
+  DetailedSmartCharacterResponse,
+  SmartAssemblyResponse,
+  InventoryItem,
+} from "../types";
+import type {
+  MoveObjectData,
+  RawSuiObjectData,
+  CharacterInfo,
+} from "../graphql/types";
+import { getAssemblyType, parseStatus } from "./mapping";
+import { getDatahubGameInfo, type DatahubGameInfo } from "./datahub";
+import { getObjectWithJson } from "../graphql";
+
+/**
+ * Transform CharacterInfo to DetailedSmartCharacterResponse
+ *
+ * @category Utilities
+ */
+export function transformToCharacter(
+  characterInfo: CharacterInfo,
+): DetailedSmartCharacterResponse {
+  return {
+    id: characterInfo.id,
+    address: characterInfo.address,
+    name: characterInfo.name,
+    tribeId: characterInfo.tribeId,
+    smartAssemblies: [],
+    portrait: "",
+  };
+}
+
+/**
+ * Additional options for transformToAssembly
+ */
+export interface TransformOptions {
+  /** Character/owner information */
+  character?: CharacterInfo | null;
+  /** Pre-fetched datahub game info (name, description, image) */
+  datahubInfo?: DatahubGameInfo | null;
+}
+
+/**
+ * Transform raw Sui Move object data to AssemblyType
+ *
+ * @param objectId - The Sui object address
+ * @param moveObject - The Move object data from GraphQL
+ * @param options - Optional transform options including character info
+ *
+ * @category Utilities
+ */
+export async function transformToAssembly(
+  objectId: string,
+  moveObject: MoveObjectData,
+  options?: TransformOptions,
+): Promise<AssemblyType<Assemblies> | null> {
+  const rawData = moveObject.contents?.json as unknown as RawSuiObjectData;
+
+  if (!rawData) {
+    console.warn("[DappKit] transformToAssembly: No raw data found");
+    return null;
+  }
+
+  // Determine assembly type from Move object
+  const typeId = rawData.type_id || rawData.status?.type_id || "0";
+  const assemblyType = getAssemblyType(moveObject.contents.type?.repr || ""); // This is the Move object type tag, not the typeId
+
+  // Parse dynamic fields for additional data (such as inventory)
+  const dynamicFields: Record<string, unknown> = {};
+  if (moveObject.dynamicFields?.nodes) {
+    for (const field of moveObject.dynamicFields.nodes) {
+      const fieldName =
+        typeof field.name.json === "string"
+          ? field.name.json
+          : JSON.stringify(field.name.json);
+
+      dynamicFields[fieldName] = field.contents.json;
+    }
+  }
+
+  // Build base assembly properties
+  const state = parseStatus(rawData.status?.status?.["@variant"]);
+
+  // Use pre-fetched datahub info for defaults
+  const datahubInfo = options?.datahubInfo;
+
+  const baseAssembly = {
+    id: rawData.id || objectId,
+    item_id: parseInt(rawData.key?.item_id || "0", 10) || 0,
+    type: assemblyType,
+    name: rawData.metadata?.name || "",
+    description: rawData.metadata?.description || "",
+    dappURL: rawData.metadata?.url || "",
+    state,
+    typeId: parseInt(typeId, 10) || 0,
+    energyUsage: 0,
+    location: {
+      x: 0,
+      y: 0,
+      z: 0,
+    },
+    typeDetails: datahubInfo,
+    // Owner information
+    character: options?.character || undefined,
+    // Include raw data for debugging/extension
+    _raw: moveObject,
+  };
+
+  // Add module-specific data based on assembly type
+  switch (assemblyType) {
+    case Assemblies.SmartStorageUnit:
+      const inventoryKey = rawData.inventory_keys?.[0];
+      const inventoryData = dynamicFields[inventoryKey || ""] as
+        | {
+            key: string;
+            value?: {
+              max_capacity: string;
+              used_capacity: string;
+              items?: {
+                contents?: Array<{ key: string; value: unknown }>;
+              };
+            };
+          }
+        | undefined;
+
+      const inventoryItems = inventoryData?.value?.items?.contents?.map(
+        (item) => {
+          return item.value as InventoryItem;
+        },
+      );
+
+      return {
+        ...baseAssembly,
+        storage: {
+          mainInventory: {
+            capacity: inventoryData?.value?.max_capacity,
+            usedCapacity: inventoryData?.value?.used_capacity,
+            items: inventoryItems,
+          },
+          ephemeralInventories: [],
+          isParentNodeOnline: state === State.ONLINE,
+        },
+      } as AssemblyType<Assemblies.SmartStorageUnit>;
+
+    case Assemblies.SmartTurret:
+      return {
+        ...baseAssembly,
+        turret: {
+          isParentNodeOnline: state === State.ONLINE,
+        },
+      } as AssemblyType<Assemblies.SmartTurret>;
+
+    case Assemblies.SmartGate:
+      return {
+        ...baseAssembly,
+        gate: {
+          linked: false,
+          destinationId: undefined,
+          inRange: [],
+          isParentNodeOnline: state === State.ONLINE,
+        },
+      } as AssemblyType<Assemblies.SmartGate>;
+
+    case Assemblies.NetworkNode:
+      // TODO: Batch this call so that it can fetch all assemblies at once
+      const linkedAssemblies: SmartAssemblyResponse[] = await Promise.all(
+        (rawData.connected_assembly_ids || []).map(async (id) => {
+          const assemblyResult = await getObjectWithJson(id);
+          const assemblyJson = assemblyResult.data?.object?.asMoveObject
+            ?.contents?.json as RawSuiObjectData | undefined;
+
+          // TODO: Change this so that it doesn't need to be fetched for each assembly
+          const typeDetails = await getDatahubGameInfo(
+            parseInt(assemblyJson?.type_id || "0", 10),
+          );
+
+          return {
+            id,
+            item_id: parseInt(assemblyJson?.key?.item_id || "0", 10),
+            state: parseStatus(assemblyJson?.status?.status?.["@variant"]),
+            energyUsage: 0,
+            typeId: parseInt(assemblyJson?.type_id || "0", 10),
+            name: assemblyJson?.metadata?.name || "",
+            type: getAssemblyType(assemblyJson?.type_id || ""),
+            typeDetails: typeDetails,
+          };
+        }),
+      );
+
+      return {
+        ...baseAssembly,
+        networkNode: {
+          fuel: {
+            amount: parseInt(rawData.fuel?.quantity || "0", 10),
+            burnRateInMs: parseInt(rawData.fuel?.burn_rate_in_ms || "0", 10),
+            efficiency: 0,
+            unitVolume: parseInt(rawData.fuel?.unit_volume || "0", 10),
+            typeId: parseInt(rawData.fuel?.type_id || "0", 10),
+          },
+          burn: {
+            isBurning: rawData.fuel?.is_burning || false,
+            startTime: rawData.fuel?.burn_start_time || "",
+            previousCycleElapsedTimeInSec: parseInt(
+              rawData.fuel?.previous_cycle_elapsed_time || "0",
+              10,
+            ),
+          },
+          energyProduction: parseInt(
+            rawData.energy_source?.current_energy_production || "0",
+            10,
+          ),
+          energyMaxCapacity: parseInt(
+            rawData.energy_source?.max_energy_production || "0",
+            10,
+          ),
+          totalReservedEnergy: parseInt(
+            rawData.energy_source?.total_reserved_energy || "0",
+            10,
+          ),
+          linkedAssemblies: linkedAssemblies || [],
+        },
+      } as AssemblyType<Assemblies.NetworkNode>;
+
+    case Assemblies.Manufacturing:
+      return {
+        ...baseAssembly,
+        manufacturing: {
+          isParentNodeOnline: state === State.ONLINE,
+        },
+      } as AssemblyType<Assemblies.Manufacturing>;
+
+    case Assemblies.Refinery:
+      return {
+        ...baseAssembly,
+        refinery: {
+          isParentNodeOnline: state === State.ONLINE,
+        },
+      } as AssemblyType<Assemblies.Refinery>;
+
+    default:
+      // Default to SmartStorageUnit
+      return {
+        ...baseAssembly,
+        storage: {
+          mainInventory: {
+            capacity: "0",
+            usedCapacity: "0",
+            items: [],
+          },
+          ephemeralInventories: [],
+          isParentNodeOnline: state === State.ONLINE,
+        },
+      } as AssemblyType<Assemblies.SmartStorageUnit>;
+  }
+}