@evefrontier/dapp-kit 0.1.0

package/hooks/useSponsoredTransaction.ts

@@ -0,0 +1,323 @@
+import { getWallets } from "@mysten/wallet-standard";
+import {
+  useCurrentAccount,
+  useWallets,
+  useDAppKit,
+} from "@mysten/dapp-kit-react";
+import {
+  useMutation,
+  UseMutationResult,
+  type UseMutationOptions,
+} from "@tanstack/react-query";
+import {
+  getAssemblyTypeApiString,
+  supportsSponsoredTransaction,
+  getSponsoredTransactionMethod,
+  type SponsoredTransactionInput,
+  type SponsoredTransactionOutput,
+  SponsoredTransactionArgs,
+} from "../wallet";
+import { SponsoredTransactionActions } from "../types";
+
+/** Wallet-like shape from dApp Kit (UiWallet or connection store). */
+type ResolvableWallet = {
+  features: unknown;
+  name?: string;
+  version?: string;
+  [key: string]: unknown;
+};
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * Error thrown when the connected wallet doesn't support EVE Frontier sponsored transactions.
+ *
+ * This occurs when the wallet doesn't implement the `evefrontier:sponsoredTransaction` feature.
+ * Currently, only EVE Vault wallet supports this feature.
+ *
+ * @category Errors
+ */
+export class WalletSponsoredTransactionNotSupportedError extends Error {
+  constructor(walletName?: string) {
+    super(
+      walletName
+        ? `Wallet "${walletName}" does not support sponsored transactions`
+        : "Connected wallet does not support sponsored transactions",
+    );
+    this.name = "WalletSponsoredTransactionNotSupportedError";
+  }
+}
+
+/**
+ * Error thrown when attempting a sponsored transaction without a connected wallet.
+ *
+ * @category Errors
+ */
+export class WalletNotConnectedError extends Error {
+  constructor() {
+    super("No wallet connected");
+    this.name = "WalletNotConnectedError";
+  }
+}
+
+/**
+ * Error thrown when no account is selected in the connected wallet.
+ *
+ * @category Errors
+ */
+export class WalletNoAccountSelectedError extends Error {
+  constructor() {
+    super("No account selected in wallet");
+    this.name = "WalletNoAccountSelectedError";
+  }
+}
+
+// ============================================================================
+// Hook Types
+// ============================================================================
+
+/**
+ * Error union type for {@link useSponsoredTransaction} mutation failures.
+ *
+ * @category Hooks
+ */
+export type UseSponsoredTransactionError =
+  | WalletSponsoredTransactionNotSupportedError
+  | WalletNotConnectedError
+  | WalletNoAccountSelectedError
+  | Error;
+
+/**
+ * Arguments passed to {@link useSponsoredTransaction} mutate/mutateAsync.
+ * With assembly object (id and type derived).
+ *
+ * @category Hooks
+ */
+export type UseSponsoredTransactionArgs = SponsoredTransactionArgs;
+
+/**
+ * React Query mutation options for {@link useSponsoredTransaction}.
+ *
+ * @category Hooks
+ */
+export type UseSponsoredTransactionMutationOptions = Omit<
+  UseMutationOptions<
+    SponsoredTransactionOutput,
+    UseSponsoredTransactionError,
+    UseSponsoredTransactionArgs
+  >,
+  "mutationFn"
+>;
+
+// ============================================================================
+// Hook Implementation
+// ============================================================================
+
+/**
+ * Hook for executing gas-sponsored transactions via EVE Frontier.
+ *
+ * This mutation hook enables dApps to send transactions where gas fees are paid
+ * by the EVE Frontier backend service, eliminating the need for users to have SUI
+ * tokens for gas. The wallet must support the `evefrontier:sponsoredTransaction` feature
+ * (currently only EVE Vault).
+ *
+ * The hook automatically uses the currently connected wallet and account (unless overridden)
+ * and handles wallet feature detection and validation.
+ *
+ * **Input** (passed to `mutate` / `mutateAsync`):
+ * - `txAction` (required) – The sponsored action to run (e.g. BRING_ONLINE, BRING_OFFLINE).
+ * - `chain` (required) – Sui chain id, e.g. `"sui:testnet"` or `"sui:mainnet"`.
+ * - `ownerId` (required) – Assembly owner ID.
+ * - `assembly` (optional) – Assembly ID; omit to use context-specific default.
+ * - `destination` (optional) – Destination for gate linking (LINK_SMART_GATE / UNLINK_SMART_GATE).
+ * - `account` (optional) – Signer account override; defaults to current connected account.
+ *
+ * **Output** (on success, in `data` or resolved from `mutateAsync`):
+ * - `digest` (required) – Transaction digest.
+ * - `effects` (optional) – Transaction effects, BCS encoded.
+ * - `rawEffects` (optional) – Raw effects bytes.
+ *
+ * @category Hooks
+ * @param options - React Query mutation options (optional)
+ * @returns React Query mutation result with:
+ *   - `mutate(args, options?)` - Trigger transaction (fire-and-forget)
+ *   - `mutateAsync(args)` - Trigger transaction (returns Promise<SponsoredTransactionOutput>)
+ *   - `isPending` - True while the transaction is in progress
+ *   - `isError` - True if the last mutation failed
+ *   - `error` - Error from the last failed mutation
+ *   - `data` - Last successful result (`SponsoredTransactionOutput`)
+ *
+ * @throws {WalletNotConnectedError} If no wallet is connected
+ * @throws {WalletNoAccountSelectedError} If no account is selected
+ * @throws {WalletSponsoredTransactionNotSupportedError} If wallet doesn't support sponsored transactions
+ *
+ * @example Basic bring online transaction
+ * ```tsx
+ * import { useSponsoredTransaction, SponsoredTransactionActions } from "@evefrontier/dapp-kit";
+ *
+ * const BringOnlineButton = () => {
+ *   const { mutateAsync: sendTx, isPending } = useSponsoredTransaction();
+ *
+ *   const handleBringOnline = async () => {
+ *     try {
+ *       const result = await sendTx({
+ *         txAction: SponsoredTransactionActions.BRING_ONLINE,
+ *         assembly: "0x123...",
+ *         chain: "sui:testnet",
+ *         ownerId: "0x...",
+ *       });
+ *       console.log("Transaction digest:", result.digest);
+ *     } catch (error) {
+ *       console.error("Transaction failed:", error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <button onClick={handleBringOnline} disabled={isPending}>
+ *       {isPending ? "Processing..." : "Bring Online"}
+ *     </button>
+ *   );
+ * };
+ * ```
+ *
+ * @example With callbacks
+ * ```tsx
+ * const { mutate: sendTx } = useSponsoredTransaction();
+ *
+ * sendTx(
+ *   {
+ *     txAction: SponsoredTransactionActions.BRING_ONLINE,
+ *     assembly: "0x123...",
+ *     ownerId: "0x...",
+ *     chain: "sui:testnet",
+ *   },
+ *   {
+ *     onSuccess: (result) => {
+ *       notify({ type: Severity.Success, txHash: result.digest });
+ *     },
+ *     onError: (error) => {
+ *       notify({ type: Severity.Error, message: error.message });
+ *     },
+ *   }
+ * );
+ * ```
+ *
+ * @example With assembly
+ * ```tsx
+ * const result = await sendTx({
+ *   txAction: SponsoredTransactionActions.BRING_ONLINE,
+ *   chain: "sui:testnet",
+ *   ownerId: "0x...",
+ *   assembly: "0x123...",
+ * });
+ * ```
+ *
+ * @see {@link SponsoredTransactionActions} for available transaction actions
+ * @see {@link SponsoredTransactionInput} for full input type
+ * @see {@link SponsoredTransactionOutput} for full output type
+ */
+export function useSponsoredTransaction({
+  mutationKey,
+  ...mutationOptions
+}: UseSponsoredTransactionMutationOptions = {}): UseMutationResult<
+  SponsoredTransactionOutput,
+  UseSponsoredTransactionError,
+  UseSponsoredTransactionArgs
+> {
+  const dAppKit = useDAppKit();
+  const wallets = useWallets();
+  const currentAccount = useCurrentAccount();
+
+  return useMutation({
+    mutationKey: [
+      "evefrontier",
+      "sponsored-transaction",
+      ...(mutationKey ?? []),
+    ],
+    mutationFn: async (args): Promise<SponsoredTransactionOutput> => {
+      // Resolve wallet at call time
+      const connection =
+        typeof dAppKit.stores?.$connection?.get === "function"
+          ? (dAppKit.stores.$connection.get() as { wallet?: ResolvableWallet })
+          : null;
+      const walletFromStore = connection?.wallet;
+      const wallet = walletFromStore ?? null;
+
+      if (!wallet) {
+        throw new WalletNotConnectedError();
+      }
+
+      const signerAccount = args.account ?? currentAccount?.address;
+      if (!signerAccount) {
+        throw new WalletNoAccountSelectedError();
+      }
+
+      if (!supportsSponsoredTransaction(wallet.features)) {
+        throw new WalletSponsoredTransactionNotSupportedError(
+          (wallet as ResolvableWallet).name,
+        );
+      }
+
+      // Resolve method: prefer raw Wallet Standard wallets (object-shaped features), then store/current/list
+      const walletName = (wallet as ResolvableWallet).name;
+      const walletVersion = (wallet as ResolvableWallet).version;
+      const rawWallets =
+        typeof getWallets === "function" ? getWallets().get() : [];
+      const rawWallet = rawWallets.find(
+        (w) =>
+          w.name === walletName &&
+          (walletVersion == null || w.version === walletVersion),
+      );
+      let signSponsoredTransaction =
+        (rawWallet != null
+          ? getSponsoredTransactionMethod(
+              rawWallet as Parameters<typeof getSponsoredTransactionMethod>[0],
+            )
+          : undefined) ??
+        (walletFromStore != null
+          ? getSponsoredTransactionMethod(
+              walletFromStore as Parameters<
+                typeof getSponsoredTransactionMethod
+              >[0],
+            )
+          : undefined) ??
+        getSponsoredTransactionMethod(
+          wallet as Parameters<typeof getSponsoredTransactionMethod>[0],
+        );
+      if (!signSponsoredTransaction) {
+        const walletFromList = wallets.find(
+          (w) =>
+            w.name === (wallet as ResolvableWallet).name &&
+            ((wallet as ResolvableWallet).version == null ||
+              w.version === (wallet as ResolvableWallet).version),
+        );
+        signSponsoredTransaction =
+          walletFromList != null
+            ? getSponsoredTransactionMethod(
+                walletFromList as Parameters<
+                  typeof getSponsoredTransactionMethod
+                >[0],
+              )
+            : undefined;
+      }
+      if (!signSponsoredTransaction) {
+        throw new WalletSponsoredTransactionNotSupportedError(
+          (wallet as ResolvableWallet).name,
+        );
+      }
+
+      const payload: SponsoredTransactionInput = {
+        txAction: args.txAction,
+        assembly: args.assembly.item_id,
+        assemblyType: getAssemblyTypeApiString(args.assembly.type),
+        chain: args.chain,
+        ...(args.destination != null ? { destination: args.destination } : {}),
+      };
+
+      return await signSponsoredTransaction(payload);
+    },
+    ...mutationOptions,
+  });
+}

package/index.ts

@@ -0,0 +1,162 @@
+// Main provider
+export { EveFrontierProvider } from "./providers";
+
+// Hooks
+export {
+  useConnection,
+  useSmartObject,
+  useNotification,
+  useSponsoredTransaction,
+} from "./hooks";
+
+// Hook error types and sponsored transaction types
+export {
+  WalletSponsoredTransactionNotSupportedError,
+  WalletNotConnectedError,
+  WalletNoAccountSelectedError,
+} from "./hooks";
+export type {
+  UseSponsoredTransactionError,
+  UseSponsoredTransactionArgs,
+  UseSponsoredTransactionMutationOptions,
+} from "./hooks";
+
+// Providers (for advanced usage)
+export {
+  VaultProvider,
+  VaultContext,
+  SmartObjectProvider,
+  SmartObjectContext,
+  NotificationProvider,
+  NotificationContext,
+} from "./providers";
+
+// Types from providers
+export type {
+  VaultContextType,
+  SmartObjectContextType,
+  NotificationContextType,
+  NotificationState,
+} from "./providers";
+
+// =========================================
+// Types (re-exported from ./types)
+// =========================================
+export * from "./types";
+
+// =========================================
+// Utils (re-exported from ./utils)
+// =========================================
+export * from "./utils";
+
+// =========================================
+// GraphQL - Query execution & helper functions
+// =========================================
+export {
+  executeGraphQLQuery,
+  getObjectByAddress,
+  getObjectWithDynamicFields,
+  getObjectWithJson,
+  getObjectOwnerAndOwnedObjectsByType,
+  getObjectAndCharacterOwner,
+  getOwnedObjectsByType,
+  getOwnedObjectsByPackage,
+  getSingletonObjectByType,
+  getObjectsByType,
+  // Character/owner resolution
+  getAssemblyWithOwner,
+} from "./graphql";
+
+// GraphQL - Query strings
+export {
+  // Core object queries
+  GET_OBJECT_BY_ADDRESS,
+  GET_OBJECT_WITH_DYNAMIC_FIELDS,
+  GET_OBJECT_WITH_JSON,
+  // Owner & ownership queries
+  GET_OBJECT_OWNER_AND_OWNED_OBJECTS_BY_TYPE,
+  GET_OBJECT_OWNER_AND_OWNED_OBJECTS_WITH_JSON,
+  GET_OWNED_OBJECTS_BY_TYPE,
+  GET_OWNED_OBJECTS_BY_PACKAGE,
+  // Singleton & type-based queries
+  GET_SINGLETON_OBJECT_BY_TYPE,
+  GET_OBJECTS_BY_TYPE,
+} from "./graphql";
+
+// GraphQL - Types
+export type {
+  // Base types
+  GraphQLResponse,
+  PageInfo,
+  // Move object types
+  MoveObjectContents,
+  DynamicFieldNode,
+  MoveObjectData,
+  // Object response types
+  SuiObjectResponse,
+  GetObjectResponse,
+  // GetObjectByAddress types
+  GetObjectByAddressResponse,
+  // GetObjectWithJson types
+  GetObjectWithJsonResponse,
+  // Owner & owned objects types
+  OwnedObjectNode,
+  AddressOwner,
+  GetObjectOwnerAndOwnedObjectsResponse,
+  // Owner & owned objects with JSON types
+  OwnedObjectNodeWithJson,
+  AddressOwnerWithJson,
+  GetObjectOwnerAndOwnedObjectsWithJsonResponse,
+  // GetOwnedObjectsByType types
+  OwnedObjectAddressNode,
+  GetOwnedObjectsByTypeResponse,
+  // GetOwnedObjectsByPackage types
+  OwnedObjectFullNode,
+  GetOwnedObjectsByPackageResponse,
+  // Singleton & type-based types
+  GetSingletonObjectByTypeResponse,
+  ObjectWithContentsNode,
+  GetObjectsByTypeResponse,
+  // EVE Frontier specific types
+  RawSuiObjectData,
+  OwnerCapData,
+  RawCharacterData,
+  CharacterInfo,
+} from "./graphql";
+
+// =========================================
+// Config
+// =========================================
+export { dAppKit } from "./config/dapp-kit";
+
+// =========================================
+// Constants & Configuration
+// =========================================
+export {
+  getSuiGraphqlEndpoint,
+  getEveWorldPackageId,
+  getCharacterOwnerCapType,
+  getObjectRegistryType,
+  POLLING_INTERVAL,
+  STORAGE_KEYS,
+} from "./utils/constants";
+
+// =========================================
+// Wallet Standard Extensions
+// =========================================
+export {
+  EVEFRONTIER_SPONSORED_TRANSACTION,
+  getAssemblyTypeApiString,
+  hasSponsoredTransactionFeature,
+  walletSupportsSponsoredTransaction,
+  getSponsoredTransactionFeature,
+} from "./wallet";
+
+export type {
+  EveFrontierSponsoredTransactionFeature,
+  SponsoredTransactionArgs,
+  SponsoredTransactionAssemblyType,
+  SponsoredTransactionInput,
+  SponsoredTransactionOutput,
+  SponsoredTransactionMethod,
+} from "./wallet";

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@evefrontier/dapp-kit",
+  "version": "0.1.0",
+  "description": "React SDK for EVE Frontier dApps on Sui",
+  "main": "index.ts",
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts",
+    "./types": "./types/index.ts",
+    "./utils": "./utils/index.ts",
+    "./graphql": "./graphql/index.ts",
+    "./providers": "./providers/index.ts",
+    "./hooks": "./hooks/index.ts",
+    "./config": "./config/index.ts"
+  },
+  "dependencies": {
+    "@mysten/dapp-kit-core": "^1.0.4",
+    "@mysten/dapp-kit-react": "^1.0.2",
+    "@mysten/sui": "^2.4.0",
+    "@mysten/wallet-standard": "^0.19.9",
+    "@tanstack/react-query": "^5.90.16",
+    "react": "^19.2.4"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@vitejs/plugin-react-swc": "3.4.0",
+    "typedoc": "^0.28.17",
+    "typedoc-plugin-markdown": "^4.4.0",
+    "typescript": "^5.5.3",
+    "vite": "^5.4.6",
+    "vite-plugin-svgr": "^3.3.0",
+    "vitest": "^4.0.14"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "ts:clean": "tsc --build --clean",
+    "docs": "typedoc",
+    "docs:md": "typedoc --plugin typedoc-plugin-markdown --out docs/markdown",
+    "docs:serve": "typedoc && npx serve docs/api",
+    "lint": "prettier . --check && eslint --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "prettier . --write && eslint --fix --report-unused-disable-directives --max-warnings 0",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run"
+  }
+}

package/providers/EveFrontierProvider.tsx

@@ -0,0 +1,41 @@
+import { ReactNode } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { DAppKitProvider } from "@mysten/dapp-kit-react";
+import { dAppKit } from "../config/dapp-kit";
+
+import NotificationProvider from "./NotificationProvider";
+import SmartObjectProvider from "./SmartObjectProvider";
+import VaultProvider from "./VaultProvider";
+/**
+ * EveFrontierProvider wraps the application with all necessary providers
+ * for the EVE Frontier dApp kit.
+ *
+ * Provider hierarchy:
+ * 1. QueryClientProvider - React Query for async state management
+ * 2. DAppKitProvider - Sui blockchain client
+ * 3. VaultProvider - Eve-specific wallet configuration  (from @evefrontier/dapp-kit)
+ * 4. SmartObjectProvider - Smart object data via GraphQL
+ * 5. NotificationProvider - User notifications
+ * @category Providers
+ */
+const EveFrontierProvider = ({
+  children,
+  queryClient,
+}: {
+  children: ReactNode;
+  queryClient: QueryClient;
+}) => {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <DAppKitProvider dAppKit={dAppKit}>
+        <VaultProvider>
+          <SmartObjectProvider>
+            <NotificationProvider>{children}</NotificationProvider>
+          </SmartObjectProvider>
+        </VaultProvider>
+      </DAppKitProvider>
+    </QueryClientProvider>
+  );
+};
+
+export default EveFrontierProvider;

package/providers/NotificationProvider.tsx

@@ -0,0 +1,115 @@
+import { ReactNode, createContext, useCallback, useState } from "react";
+
+import { Severity } from "../types";
+
+/** @category Types */
+export interface NotificationState {
+  message: string;
+  txHash: string;
+  severity: Severity;
+  handleClose: () => void;
+  isOpen: boolean;
+}
+
+/** @category Types */
+export interface NotificationContextType {
+  notify: (notification: {
+    type: Severity;
+    txHash?: string;
+    message?: string;
+  }) => void;
+  notification: NotificationState;
+  handleClose: () => void;
+}
+
+/** @category Providers */
+export const NotificationContext = createContext<NotificationContextType>({
+  notify: () => {},
+  notification: {
+    message: "",
+    txHash: "",
+    severity: Severity.Success,
+    handleClose: () => {},
+    isOpen: false,
+  },
+  handleClose: () => {},
+});
+
+/**
+ * NotificationProvider manages notifications for transactions and messages.
+ *
+ * @category Providers
+ */
+const NotificationProvider = ({ children }: { children: ReactNode }) => {
+  const [isOpen, setIsOpen] = useState<boolean>(false);
+  const [message, setMessage] = useState<string>("");
+  const [severity, setSeverity] = useState<Severity>(Severity.Info);
+  const [txHash, setTxHash] = useState<string>("");
+
+  const handleClose = useCallback(() => {
+    setIsOpen(false);
+  }, []);
+
+  const notify = useCallback(
+    ({
+      type,
+      message,
+      txHash,
+    }: {
+      type: Severity;
+      message?: string;
+      txHash?: string;
+    }) => {
+      setSeverity(type);
+      setIsOpen(true);
+
+      // If success with txHash, show success message with transaction hash
+      if (type === Severity.Success && txHash) {
+        setMessage(
+          `Transaction was successful. ${message ?? ""} Transaction hash: ${txHash}`,
+        );
+        setTxHash(txHash);
+        return;
+      }
+
+      // Otherwise, show the passed message or a default based on severity
+      if (message) {
+        setMessage(message);
+      } else {
+        switch (type) {
+          case Severity.Success:
+            setMessage("Operation completed successfully.");
+            break;
+          case Severity.Error:
+            setMessage("An error occurred.");
+            break;
+          case Severity.Warning:
+            setMessage("Warning.");
+            break;
+          case Severity.Info:
+          default:
+            setMessage("Processing...");
+            break;
+        }
+      }
+      setTxHash(txHash ?? "");
+    },
+    [],
+  );
+
+  const notification: NotificationState = {
+    message,
+    txHash,
+    severity,
+    handleClose,
+    isOpen,
+  };
+
+  return (
+    <NotificationContext.Provider value={{ notify, handleClose, notification }}>
+      {children}
+    </NotificationContext.Provider>
+  );
+};
+
+export default NotificationProvider;