@evefrontier/dapp-kit 0.1.0

package/utils/utils.ts

@@ -0,0 +1,270 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { SuiChain } from "@mysten/wallet-standard";
+import {
+  Assemblies,
+  DetailedAssemblyResponse,
+  SmartAssemblyResponse,
+  AssemblyType,
+} from "../types";
+
+import { ONE_M3 } from "./constants";
+
+/**
+ * Abbreviate a Sui address or hex string for display.
+ *
+ * Shortens long addresses to show only the beginning and end characters
+ * with ellipsis in the middle.
+ *
+ * @category Utilities
+ * @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
+ * @returns The abbreviated string (e.g., "0x123...abc")
+ *
+ * @example
+ * ```typescript
+ * abbreviateAddress("0x1234567890abcdef1234567890abcdef"); // "0x123...cdef"
+ * abbreviateAddress("0x1234567890abcdef", 3);              // "0x1...def"
+ * abbreviateAddress("0x1234567890abcdef", 5, true);        // Full address
+ * ```
+ */
+export const abbreviateAddress = (
+  string?: `0x${string}` | string,
+  precision = 5,
+  expanded = false,
+): string => {
+  if (!string) return "";
+  if (expanded) return string;
+  if (string.length <= precision * 2) return string;
+  return `${string.slice(0, precision)}...${string.slice(-precision)}`;
+};
+
+/**
+ * Check if an account is the owner of a smart assembly.
+ *
+ * Compares the assembly's owner address with the provided account address
+ * to determine ownership.
+ *
+ * @category Utilities
+ * @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
+ *
+ * @example
+ * ```typescript
+ * const { assembly } = useSmartObject();
+ * const { currentAccount } = useConnection();
+ *
+ * if (isOwner(assembly, currentAccount?.address)) {
+ *   // Show owner-only actions
+ * }
+ * ```
+ */
+export const isOwner = (
+  assembly: DetailedAssemblyResponse | SmartAssemblyResponse | null,
+  account?: `0x${string}` | string,
+): boolean => {
+  if (!assembly?.character?.address || account == "0x") return false;
+  return assembly.character.address === (account ?? "");
+};
+
+/**
+ * Generate a Suiscan transaction URL for a given transaction hash.
+ *
+ * @category Utilities
+ * @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
+ *
+ * @example
+ * ```typescript
+ * const url = getTxUrl("sui:testnet", "ABC123...");
+ * // Returns: "https://suiscan.xyz/testnet/tx/ABC123..."
+ * ```
+ */
+export const getTxUrl = (suiChain: SuiChain, txHash: string): string => {
+  const network = suiChain.split(":")[1];
+
+  return `https://suiscan.xyz/${network}/tx/${txHash}`;
+};
+
+export const parseURL = (string: string): string => {
+  if (string.includes("://")) {
+    // Remove 'http' or 'https'
+    return string.split("://")[1];
+  } else {
+    return string;
+  }
+};
+
+export const clickToCopy = (string: string) => {
+  return navigator.clipboard.writeText(string);
+};
+
+export const getCommonItems = (array1: any[], array2: any[]) => {
+  const commonItems: any[] = [];
+  const set: Set<any> = new Set([]);
+
+  for (let i = 0; i < array1.length; i++) {
+    const value = array1[i];
+    if (!set.has(value)) set.add(value);
+  }
+  for (let i = 0; i < array2.length; i++) {
+    const value = array2[i];
+    if (set.has(value)) commonItems.push(value);
+  }
+  return commonItems;
+};
+
+export const removeTrailingZeros = (number: string) => {
+  return number.replace(/(\.\d*?[1-9])0+$|\.0*$/, "$1");
+};
+
+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
+ * @param volume - Volume per unit in wei (10^18)
+ * @returns volume in m3 */
+export const getVolumeM3 = (quantity: bigint, volume: bigint): number => {
+  const totalVolume = Number(quantity) * Number(volume);
+  return totalVolume;
+};
+
+/**
+ * Format a raw volume value to cubic meters (m³).
+ *
+ * Converts from the on-chain representation (wei-like, 10^18) to m³.
+ *
+ * @category Utilities
+ * @param quantity - The raw volume value as string or bigint
+ * @returns Volume in cubic meters
+ *
+ * @example
+ * ```typescript
+ * const m3 = formatM3(BigInt("1000000000000000000")); // 1.0 m³
+ * ```
+ */
+export const formatM3 = (quantity: string | bigint): number => {
+  return Number(quantity) / ONE_M3;
+};
+
+/**
+ * Get the dApp URL for an assembly, ensuring it has a protocol prefix.
+ *
+ * @category Utilities
+ * @param assembly - The assembly object
+ * @returns The full dApp URL with https:// prefix if needed
+ *
+ * @example
+ * ```typescript
+ * const { assembly } = useSmartObject();
+ * const dappUrl = getDappUrl(assembly);
+ * if (dappUrl) {
+ *   window.open(dappUrl, '_blank');
+ * }
+ * ```
+ */
+export const getDappUrl = (assembly: AssemblyType<Assemblies>): string => {
+  if (!assembly?.dappURL) return "";
+
+  const pattern = /^((http|https|ftp):\/\/)/;
+
+  let url = assembly.dappURL;
+  if (!pattern.test(url)) {
+    url = "https://" + url;
+  }
+
+  return url;
+};
+
+/**
+ * Check if two addresses match.
+ *
+ * @category Utilities
+ * @param address1 - First address to compare
+ * @param address2 - Second address to compare
+ * @returns True if addresses match, false otherwise
+ */
+export const findOwnerByAddress = (
+  address1: string | undefined,
+  address2: string | undefined,
+): boolean => {
+  if (!address2 || !address1 || address1 == "" || address2 == "") return false;
+  return address1 === address2;
+};
+
+/**
+ * Type guard to check if an assembly is of a specific type.
+ *
+ * Use this to narrow the type of an assembly for type-safe property access.
+ *
+ * @category Utilities
+ * @param assembly - The assembly to check
+ * @param assemblyType - The expected assembly type
+ * @returns True if assembly matches the specified type
+ *
+ * @example
+ * ```typescript
+ * const { assembly } = useSmartObject();
+ *
+ * if (assertAssemblyType(assembly, Assemblies.SmartStorageUnit)) {
+ *   // TypeScript knows assembly is SmartStorageUnit here
+ *   console.log(assembly.storage.mainInventory);
+ * }
+ * ```
+ */
+export const assertAssemblyType = (
+  assembly: AssemblyType<Assemblies> | null,
+  assemblyType: Assemblies,
+): assembly is AssemblyType<Assemblies> => {
+  if (typeof assembly?.type === "string") {
+    return assembly.type === assemblyType;
+  }
+  return false;
+};
+
+/**
+ * Format a duration in seconds to a human-readable string.
+ *
+ * Displays the duration in days, hours, minutes, and seconds as appropriate.
+ *
+ * @category Utilities
+ * @param seconds - Duration in seconds
+ * @returns Formatted duration string (e.g., "02d 05h 30m 15s")
+ *
+ * @example
+ * ```typescript
+ * formatDuration(3665);   // "01h 01m 05s"
+ * formatDuration(90061);  // "01d 01h 01m 01s"
+ * formatDuration(45);     // "45s"
+ * ```
+ */
+export const formatDuration = (seconds: number): string => {
+  if (seconds === 0) return "0m 0s";
+
+  const days = Math.floor(seconds / (24 * 3600));
+  seconds %= 24 * 3600;
+  const hours = Math.floor(seconds / 3600);
+  seconds %= 3600;
+  const minutes = Math.floor(seconds / 60);
+  const remainingSeconds = seconds % 60;
+
+  const formattedDays = String(days).padStart(2, "0");
+  const formattedHours = String(hours).padStart(2, "0");
+  const formattedMinutes = String(minutes).padStart(2, "0");
+  const formattedSeconds = String(remainingSeconds).padStart(2, "0");
+
+  if (days > 0) {
+    return `${formattedDays}d ${formattedHours}h ${formattedMinutes}m ${formattedSeconds}s`;
+  } else if (hours > 0) {
+    return `${formattedHours}h ${formattedMinutes}m ${formattedSeconds}s`;
+  } else if (minutes > 0) {
+    return `${formattedMinutes}m ${formattedSeconds}s`;
+  } else {
+    return `${formattedSeconds}s`;
+  }
+};

package/vite-env.d.ts

@@ -0,0 +1,16 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  /** Sui GraphQL endpoint URL (required) */
+  readonly VITE_SUI_GRAPHQL_ENDPOINT: string;
+  /** EVE World package ID on Sui (required) */
+  readonly VITE_EVE_WORLD_PACKAGE_ID: string;
+  /** Optional smart assembly item ID override */
+  readonly VITE_ITEM_ID?: string;
+  /** Tenant identifier (required when VITE_ITEM_ID is set) */
+  readonly VITE_EVE_WORLD_TENANT?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/wallet/features.ts

@@ -0,0 +1,165 @@
+/**
+ * EVE Frontier Wallet Standard Feature Extensions
+ *
+ * Custom wallet features for EVE Frontier dApps that extend the
+ * standard Sui wallet capabilities.
+ */
+
+import {
+  Assemblies,
+  AssemblyType,
+  SponsoredTransactionActions,
+} from "../types";
+
+// ============================================================================
+// Feature Identifiers
+// ============================================================================
+
+/**
+ * Feature identifier for sponsored transactions.
+ * Wallets implementing this feature can request gas sponsorship from
+ * the EVE Frontier sponsored-transaction backend service.
+ *
+ * @category Wallet
+ */
+export const EVEFRONTIER_SPONSORED_TRANSACTION =
+  "evefrontier:sponsoredTransaction" as const;
+
+// ============================================================================
+// Sponsored Transaction Types
+// ============================================================================
+
+/**
+ * Map assembly types to API strings
+ */
+const ASSEMBLY_TYPE_API_STRING: Record<Assemblies, string> = {
+  [Assemblies.SmartStorageUnit]: "storage-units",
+  [Assemblies.SmartTurret]: "turrets",
+  [Assemblies.SmartGate]: "gates",
+  [Assemblies.NetworkNode]: "network-nodes",
+  [Assemblies.Manufacturing]: "manufacturing",
+  [Assemblies.Refinery]: "refineries",
+} as const;
+
+/** API slug for assembly type in sponsored transaction payloads (e.g. "storage-units"). */
+export type SponsoredTransactionAssemblyType =
+  (typeof ASSEMBLY_TYPE_API_STRING)[Assemblies];
+
+/**
+ * Maps an assembly type enum to the API string expected by the sponsored transaction backend.
+ *
+ * @category Wallet
+ */
+export function getAssemblyTypeApiString(
+  type: Assemblies,
+): SponsoredTransactionAssemblyType {
+  return ASSEMBLY_TYPE_API_STRING[type];
+}
+
+/**
+ * Input for a sponsored transaction request
+ * Takes the transformed item_id and assembly type values of the assembly object
+ * Normalization from assembly object to this flat shape is done in the hook by design;
+ * callers may pass either the full assembly or pre-flattened values.
+ * @category Wallet
+ */
+export interface SponsoredTransactionInput {
+  /** The transaction to be sponsored and executed */
+  txAction: SponsoredTransactionActions;
+  /** Assembly ID */
+  assembly: AssemblyType<Assemblies>["item_id"];
+  /** The assembly type to be sponsored and executed */
+  assemblyType: SponsoredTransactionAssemblyType;
+  /** The Sui chain to execute on (e.g., "sui:testnet", "sui:mainnet") */
+  chain: `sui:${string}`;
+  /** Optional destination for gate linking */
+  destination?: AssemblyType<Assemblies>["item_id"];
+}
+
+/** Sponsored tx args with assembly object; id and assemblyType are derived. */
+export type SponsoredTransactionArgs = Omit<
+  SponsoredTransactionInput,
+  "assembly" | "assemblyType" | "account"
+> & {
+  assembly: AssemblyType<Assemblies>;
+  account?: string;
+};
+
+/**
+ * Output from a successful sponsored transaction
+ *
+ * @category Wallet
+ */
+export interface SponsoredTransactionOutput {
+  /** The transaction digest */
+  digest: string;
+  /** The transaction effects (BCS encoded) */
+  effects?: string;
+  /** Raw effects bytes (if available) */
+  rawEffects?: number[];
+}
+
+/**
+ * The sponsored transaction method signature
+ *
+ * @category Wallet
+ */
+export type SponsoredTransactionMethod = (
+  input: SponsoredTransactionInput,
+) => Promise<SponsoredTransactionOutput>;
+
+/**
+ * Feature interface for sponsored transactions.
+ * Wallets that support this feature should implement this interface
+ * in their `features` object.
+ *
+ * @category Wallet
+ */
+export interface EveFrontierSponsoredTransactionFeature {
+  readonly [EVEFRONTIER_SPONSORED_TRANSACTION]: {
+    /** Feature version for compatibility checking */
+    readonly version: "1.0.0";
+    /** Execute a gas-sponsored transaction */
+    signSponsoredTransaction: SponsoredTransactionMethod;
+  };
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Type guard to check if an object has the sponsored transaction feature
+ * (object form with implementation).
+ *
+ * @category Wallet
+ */
+export function hasSponsoredTransactionFeature(
+  features: Record<string, unknown>,
+): features is Record<string, unknown> &
+  EveFrontierSponsoredTransactionFeature {
+  const featureValue = features[EVEFRONTIER_SPONSORED_TRANSACTION];
+  return (
+    EVEFRONTIER_SPONSORED_TRANSACTION in features &&
+    typeof featureValue === "object" &&
+    featureValue !== null &&
+    "signSponsoredTransaction" in (featureValue as object)
+  );
+}
+
+/**
+ * Check if a wallet supports the sponsored transaction feature.
+ * Supports both legacy object-shaped features and v2 array-shaped features
+ * (list of feature names).
+ *
+ * @category Wallet
+ */
+export function supportsSponsoredTransaction(features: unknown): boolean {
+  if (Array.isArray(features)) {
+    return (features as string[]).includes(EVEFRONTIER_SPONSORED_TRANSACTION);
+  }
+  if (typeof features === "object" && features !== null) {
+    return hasSponsoredTransactionFeature(features as Record<string, unknown>);
+  }
+  return false;
+}

package/wallet/index.ts

@@ -0,0 +1,28 @@
+/**
+ * EVE Frontier Wallet Standard Extensions
+ *
+ * Provides custom wallet sponsored transaction features.
+ */
+
+// Feature definitions and types
+export {
+  EVEFRONTIER_SPONSORED_TRANSACTION,
+  getAssemblyTypeApiString,
+  hasSponsoredTransactionFeature,
+  supportsSponsoredTransaction,
+} from "./features";
+export type {
+  EveFrontierSponsoredTransactionFeature,
+  SponsoredTransactionArgs,
+  SponsoredTransactionAssemblyType,
+  SponsoredTransactionInput,
+  SponsoredTransactionMethod,
+  SponsoredTransactionOutput,
+} from "./features";
+
+// Utility functions
+export {
+  walletSupportsSponsoredTransaction,
+  getSponsoredTransactionFeature,
+  getSponsoredTransactionMethod,
+} from "./utils";

package/wallet/utils.ts

@@ -0,0 +1,117 @@
+import type { Wallet } from "@mysten/wallet-standard";
+import {
+  EVEFRONTIER_SPONSORED_TRANSACTION,
+  hasSponsoredTransactionFeature,
+  supportsSponsoredTransaction,
+  type EveFrontierSponsoredTransactionFeature,
+  type SponsoredTransactionMethod,
+} from "./features";
+
+/**
+ * Check if a wallet supports the EVE Frontier sponsored transaction feature.
+ *
+ * Use this to filter available wallets to only those that can execute
+ * sponsored (gasless) transactions. Currently, only EVE Vault implements
+ * this feature.
+ *
+ * @category Wallet
+ * @param wallet - The wallet object from wallet-standard
+ * @returns True if the wallet implements the `evefrontier:sponsoredTransaction` feature
+ *
+ * @example Filter supported wallets
+ * ```tsx
+ * import { useWallets } from "@mysten/dapp-kit-react";
+ * import { walletSupportsSponsoredTransaction } from "@evefrontier/dapp-kit";
+ *
+ * const wallets = useWallets();
+ * const supportedWallets = wallets.filter(walletSupportsSponsoredTransaction);
+ *
+ * console.log(`${supportedWallets.length} wallets support sponsored transactions`);
+ * ```
+ *
+ * @example Check single wallet
+ * ```tsx
+ * const { currentWallet } = useCurrentWallet();
+ *
+ * if (currentWallet && walletSupportsSponsoredTransaction(currentWallet)) {
+ *   // Wallet supports gasless transactions
+ * }
+ * ```
+ */
+export function walletSupportsSponsoredTransaction(wallet: Wallet): boolean {
+  return supportsSponsoredTransaction(wallet.features);
+}
+
+/**
+ * Get the sponsored transaction method from a wallet if supported.
+ *
+ * Returns the raw `signSponsoredTransaction` method from the wallet's features.
+ * For most use cases, prefer using the {@link useSponsoredTransaction} hook instead,
+ * which provides React Query integration and automatic error handling.
+ *
+ * @category Wallet
+ * @param wallet - The wallet object from wallet-standard
+ * @returns The sponsored transaction method, or undefined if not supported
+ *
+ * @example Direct wallet feature access
+ * ```tsx
+ * const { currentWallet } = useCurrentWallet();
+ *
+ * if (currentWallet) {
+ *   const sponsoredTx = getSponsoredTransactionFeature(currentWallet);
+ *   if (sponsoredTx) {
+ *     const result = await sponsoredTx({
+ *       txAction: "online",
+ *       chain: "sui:testnet",
+ *       assembly: "0x123..."
+ *     });
+ *     console.log("Transaction digest:", result.digest);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link useSponsoredTransaction} for the recommended React hook approach
+ */
+export function getSponsoredTransactionFeature(
+  wallet: Wallet,
+): SponsoredTransactionMethod | undefined {
+  if (
+    !hasSponsoredTransactionFeature(wallet.features as Record<string, unknown>)
+  ) {
+    return undefined;
+  }
+
+  const feature = (wallet.features as Record<string, unknown>)[
+    EVEFRONTIER_SPONSORED_TRANSACTION
+  ] as EveFrontierSponsoredTransactionFeature[typeof EVEFRONTIER_SPONSORED_TRANSACTION];
+
+  return feature.signSponsoredTransaction;
+}
+
+/**
+ * Get the sponsored transaction method from a wallet, supporting both
+ * object-shaped features (legacy) and array-shaped features (v2).
+ * When features is an array, tries the wallet object for a top-level
+ * feature implementation (e.g. wallet['evefrontier:sponsoredTransaction']).
+ */
+export function getSponsoredTransactionMethod(
+  wallet: Wallet | { features: unknown; name?: string; version?: string },
+): SponsoredTransactionMethod | undefined {
+  const fromFeatures = getSponsoredTransactionFeature(wallet as Wallet);
+  if (fromFeatures) return fromFeatures;
+
+  if (!supportsSponsoredTransaction(wallet.features)) return undefined;
+
+  const w = wallet as Record<string, unknown>;
+  const feature = w[EVEFRONTIER_SPONSORED_TRANSACTION];
+  if (
+    feature !== null &&
+    typeof feature === "object" &&
+    typeof (feature as { signSponsoredTransaction?: unknown })
+      .signSponsoredTransaction === "function"
+  ) {
+    return (feature as { signSponsoredTransaction: SponsoredTransactionMethod })
+      .signSponsoredTransaction;
+  }
+  return undefined;
+}