@hivemindhq/core 0.4.0 → 0.5.0

package/src/utils/multivault-errors.ts

@@ -0,0 +1,581 @@
+/**
+ * MultiVault Contract Error Mappings
+ *
+ * Maps Solidity error names from the MultiVault contract to user-friendly messages.
+ * These errors are thrown by the Intuition Protocol's MultiVault contract.
+ *
+ * @see intuition-contracts-v2/src/protocol/MultiVault.sol
+ * @see intuition-contracts-v2/src/protocol/MultiVaultCore.sol
+ */
+
+export interface MultiVaultErrorInfo {
+  /** The Solidity error name as it appears in the contract */
+  errorName: string
+  /** User-friendly message to display in the UI */
+  userMessage: string
+  /** More detailed explanation for tooltips or error details */
+  description: string
+  /** Category for grouping/filtering errors */
+  category:
+    | 'atom'
+    | 'triple'
+    | 'deposit'
+    | 'redeem'
+    | 'balance'
+    | 'limits'
+    | 'batch'
+    | 'approval'
+    | 'existence'
+    | 'epoch'
+    | 'wallet'
+    | 'internal'
+  /** Whether this error is commonly encountered by users */
+  isCommon: boolean
+}
+
+/**
+ * Result of parsing a MultiVault error
+ */
+export interface ParsedMultiVaultError {
+  /** User-friendly message to display in the UI */
+  userMessage: string
+  /** More detailed explanation for tooltips or error details */
+  description: string
+  /** Whether this error is commonly encountered by users */
+  isCommon: boolean
+  /** The original error name if matched, undefined if fallback */
+  errorName?: string
+  /** The error category if matched */
+  category?: MultiVaultErrorInfo['category']
+  /** Whether this was a known MultiVault error */
+  isMultiVaultError: boolean
+}
+
+/**
+ * Complete mapping of MultiVault contract errors to user-friendly messages.
+ *
+ * @example
+ * ```typescript
+ * const errorInfo = MULTIVAULT_ERRORS['MultiVault_AtomExists']
+ * toast.error(errorInfo.userMessage)
+ * ```
+ */
+export const MULTIVAULT_ERRORS: Record<string, MultiVaultErrorInfo> = {
+  // ============================================
+  // ATOM CREATION ERRORS
+  // ============================================
+
+  MultiVault_AtomExists: {
+    errorName: 'MultiVault_AtomExists',
+    userMessage: 'This entity already exists on-chain',
+    description:
+      'An atom with this exact data has already been created. You can stake on the existing atom instead.',
+    category: 'atom',
+    isCommon: true,
+  },
+
+  MultiVault_AtomDoesNotExist: {
+    errorName: 'MultiVault_AtomDoesNotExist',
+    userMessage: "This entity hasn't been created yet",
+    description:
+      'The atom you are trying to reference does not exist on-chain. It may need to be created first.',
+    category: 'atom',
+    isCommon: true,
+  },
+
+  MultiVault_NoAtomDataProvided: {
+    errorName: 'MultiVault_NoAtomDataProvided',
+    userMessage: 'No data provided for entity creation',
+    description:
+      'Atom creation requires data (URL, IPFS URI, or other identifier) to be provided.',
+    category: 'atom',
+    isCommon: false,
+  },
+
+  MultiVault_AtomDataTooLong: {
+    errorName: 'MultiVault_AtomDataTooLong',
+    userMessage: 'Entity data is too large',
+    description:
+      'The provided atom data exceeds the maximum allowed length. Consider using an IPFS URI instead.',
+    category: 'atom',
+    isCommon: false,
+  },
+
+  // ============================================
+  // TRIPLE CREATION ERRORS
+  // ============================================
+
+  MultiVault_TripleExists: {
+    errorName: 'MultiVault_TripleExists',
+    userMessage: 'This claim already exists',
+    description:
+      'A triple with this exact subject-predicate-object combination has already been created. You can stake on the existing claim instead.',
+    category: 'triple',
+    isCommon: true,
+  },
+
+  MultiVault_TermNotTriple: {
+    errorName: 'MultiVault_TermNotTriple',
+    userMessage: 'This is not a claim',
+    description:
+      'The specified term ID refers to an atom, not a triple. Triple-specific operations cannot be performed on atoms.',
+    category: 'triple',
+    isCommon: false,
+  },
+
+  MultiVault_CannotDirectlyInitializeCounterTriple: {
+    errorName: 'MultiVault_CannotDirectlyInitializeCounterTriple',
+    userMessage: 'Cannot initialize counter position directly',
+    description:
+      'Counter-triple vaults are automatically created when the main triple is created. You cannot deposit directly into a counter vault that has not been initialized.',
+    category: 'triple',
+    isCommon: false,
+  },
+
+  // ============================================
+  // DEPOSIT/STAKING ERRORS
+  // ============================================
+
+  MultiVault_HasCounterStake: {
+    errorName: 'MultiVault_HasCounterStake',
+    userMessage: 'You already have an opposing position. Unstake first.',
+    description:
+      'You cannot stake on both sides of a claim simultaneously. Please remove your existing position before staking on the opposite side.',
+    category: 'deposit',
+    isCommon: true,
+  },
+
+  MultiVault_DepositBelowMinimumDeposit: {
+    errorName: 'MultiVault_DepositBelowMinimumDeposit',
+    userMessage: 'Deposit amount is below minimum',
+    description:
+      'The amount you are trying to deposit is less than the protocol minimum. Please increase your deposit amount.',
+    category: 'deposit',
+    isCommon: true,
+  },
+
+  MultiVault_DepositOrRedeemZeroShares: {
+    errorName: 'MultiVault_DepositOrRedeemZeroShares',
+    userMessage: 'Transaction would result in zero shares',
+    description:
+      'The deposit amount is too small to mint any shares, or you are trying to redeem zero shares.',
+    category: 'deposit',
+    isCommon: false,
+  },
+
+  MultiVault_DepositTooSmallToCoverMinShares: {
+    errorName: 'MultiVault_DepositTooSmallToCoverMinShares',
+    userMessage: 'Deposit too small to initialize vault',
+    description:
+      'When initializing a new vault on a non-default bonding curve, the deposit must cover the minimum share cost.',
+    category: 'deposit',
+    isCommon: false,
+  },
+
+  MultiVault_DefaultCurveMustBeInitializedViaCreatePaths: {
+    errorName: 'MultiVault_DefaultCurveMustBeInitializedViaCreatePaths',
+    userMessage: 'Vault must be created before depositing',
+    description:
+      'Default curve vaults must be initialized through createAtoms or createTriples, not through direct deposits.',
+    category: 'deposit',
+    isCommon: false,
+  },
+
+  MultiVault_SenderNotApproved: {
+    errorName: 'MultiVault_SenderNotApproved',
+    userMessage: 'Not authorized to deposit for this account',
+    description:
+      'You do not have approval to deposit on behalf of the specified receiver address.',
+    category: 'deposit',
+    isCommon: false,
+  },
+
+  MultiVault_SlippageExceeded: {
+    errorName: 'MultiVault_SlippageExceeded',
+    userMessage: 'Price changed. Try again with updated amount.',
+    description:
+      'The share price moved unfavorably between when you submitted and when the transaction executed. The actual shares received would be less than your minimum.',
+    category: 'deposit',
+    isCommon: true,
+  },
+
+  // ============================================
+  // REDEMPTION/UNSTAKING ERRORS
+  // ============================================
+
+  MultiVault_InsufficientSharesInVault: {
+    errorName: 'MultiVault_InsufficientSharesInVault',
+    userMessage: 'Insufficient shares to redeem',
+    description:
+      'You are trying to redeem more shares than you currently own in this vault.',
+    category: 'redeem',
+    isCommon: true,
+  },
+
+  MultiVault_InsufficientRemainingSharesInVault: {
+    errorName: 'MultiVault_InsufficientRemainingSharesInVault',
+    userMessage: 'Cannot redeem: would leave vault below minimum',
+    description:
+      'This redemption would leave the vault with fewer shares than the protocol minimum. You may need to redeem a smaller amount.',
+    category: 'redeem',
+    isCommon: false,
+  },
+
+  MultiVault_RedeemerNotApproved: {
+    errorName: 'MultiVault_RedeemerNotApproved',
+    userMessage: 'Not authorized to redeem for this account',
+    description:
+      'You do not have approval to redeem shares on behalf of the specified receiver address.',
+    category: 'redeem',
+    isCommon: false,
+  },
+
+  // ============================================
+  // BALANCE/ASSET ERRORS
+  // ============================================
+
+  MultiVault_InsufficientBalance: {
+    errorName: 'MultiVault_InsufficientBalance',
+    userMessage: 'Insufficient TRUST balance',
+    description:
+      'You do not have enough TRUST tokens to complete this transaction. Please add more funds to your wallet.',
+    category: 'balance',
+    isCommon: true,
+  },
+
+  MultiVault_InsufficientAssets: {
+    errorName: 'MultiVault_InsufficientAssets',
+    userMessage: 'Not enough funds for this operation',
+    description:
+      'The assets provided are less than the required cost for this operation (atom/triple creation cost + deposit).',
+    category: 'balance',
+    isCommon: true,
+  },
+
+  MultiVault_BurnFromZeroAddress: {
+    errorName: 'MultiVault_BurnFromZeroAddress',
+    userMessage: 'Transaction failed',
+    description:
+      'Internal error: attempted to burn shares from the zero address.',
+    category: 'internal',
+    isCommon: false,
+  },
+
+  MultiVault_BurnInsufficientBalance: {
+    errorName: 'MultiVault_BurnInsufficientBalance',
+    userMessage: 'Transaction failed',
+    description:
+      'Internal error: attempted to burn more shares than the account holds.',
+    category: 'internal',
+    isCommon: false,
+  },
+
+  // ============================================
+  // LIMIT/BOUNDS ERRORS
+  // ============================================
+
+  MultiVault_ActionExceedsMaxAssets: {
+    errorName: 'MultiVault_ActionExceedsMaxAssets',
+    userMessage: 'Vault is at maximum capacity',
+    description:
+      'This deposit would cause the vault to exceed its maximum allowed assets. The vault cannot accept more deposits.',
+    category: 'limits',
+    isCommon: false,
+  },
+
+  MultiVault_ActionExceedsMaxShares: {
+    errorName: 'MultiVault_ActionExceedsMaxShares',
+    userMessage: 'Vault is at maximum capacity',
+    description:
+      'This deposit would cause the vault to exceed its maximum allowed shares. The vault cannot accept more deposits.',
+    category: 'limits',
+    isCommon: false,
+  },
+
+  // ============================================
+  // ARRAY/BATCH ERRORS
+  // ============================================
+
+  MultiVault_ArraysNotSameLength: {
+    errorName: 'MultiVault_ArraysNotSameLength',
+    userMessage: 'Invalid batch operation',
+    description:
+      'The arrays provided for this batch operation have different lengths. All arrays must have the same number of elements.',
+    category: 'batch',
+    isCommon: false,
+  },
+
+  MultiVault_InvalidArrayLength: {
+    errorName: 'MultiVault_InvalidArrayLength',
+    userMessage: 'Invalid number of items in batch',
+    description:
+      'The batch operation contains either zero items or exceeds the maximum batch size of 150 items.',
+    category: 'batch',
+    isCommon: false,
+  },
+
+  // ============================================
+  // APPROVAL ERRORS
+  // ============================================
+
+  MultiVault_CannotApproveOrRevokeSelf: {
+    errorName: 'MultiVault_CannotApproveOrRevokeSelf',
+    userMessage: 'Cannot modify own approval',
+    description:
+      'You cannot approve or revoke approval for yourself. Approval is only for allowing other addresses to act on your behalf.',
+    category: 'approval',
+    isCommon: false,
+  },
+
+  // ============================================
+  // TERM EXISTENCE ERRORS
+  // ============================================
+
+  MultiVault_TermDoesNotExist: {
+    errorName: 'MultiVault_TermDoesNotExist',
+    userMessage: "This entity or claim doesn't exist",
+    description:
+      'The specified term (atom or triple) has not been created on-chain. It may have been deleted or never existed.',
+    category: 'existence',
+    isCommon: true,
+  },
+
+  // ============================================
+  // EPOCH/UTILIZATION ERRORS
+  // ============================================
+
+  MultiVault_EpochNotTracked: {
+    errorName: 'MultiVault_EpochNotTracked',
+    userMessage: 'No activity recorded for this period',
+    description:
+      'There is no recorded activity for the specified epoch in the user history.',
+    category: 'epoch',
+    isCommon: false,
+  },
+
+  MultiVault_InvalidEpoch: {
+    errorName: 'MultiVault_InvalidEpoch',
+    userMessage: 'Invalid time period',
+    description: 'The specified epoch is in the future or otherwise invalid.',
+    category: 'epoch',
+    isCommon: false,
+  },
+
+  // ============================================
+  // WALLET ERRORS
+  // ============================================
+
+  MultiVault_OnlyAssociatedAtomWallet: {
+    errorName: 'MultiVault_OnlyAssociatedAtomWallet',
+    userMessage: "Only the entity's wallet can claim fees",
+    description:
+      'Atom wallet deposit fees can only be claimed by the associated atom wallet contract.',
+    category: 'wallet',
+    isCommon: false,
+  },
+
+  // ============================================
+  // MULTIVAULTCORE ERRORS
+  // ============================================
+
+  MultiVaultCore_InvalidAdmin: {
+    errorName: 'MultiVaultCore_InvalidAdmin',
+    userMessage: 'Invalid admin address',
+    description:
+      'The contract cannot be initialized with a zero address admin.',
+    category: 'internal',
+    isCommon: false,
+  },
+
+  MultiVaultCore_AtomDoesNotExist: {
+    errorName: 'MultiVaultCore_AtomDoesNotExist',
+    userMessage: 'Entity not found',
+    description:
+      'The specified atom ID does not correspond to any existing atom on-chain.',
+    category: 'existence',
+    isCommon: true,
+  },
+
+  MultiVaultCore_TripleDoesNotExist: {
+    errorName: 'MultiVaultCore_TripleDoesNotExist',
+    userMessage: 'Claim not found',
+    description:
+      'The specified triple ID does not correspond to any existing triple on-chain.',
+    category: 'existence',
+    isCommon: true,
+  },
+
+  MultiVaultCore_TermDoesNotExist: {
+    errorName: 'MultiVaultCore_TermDoesNotExist',
+    userMessage: 'Entity or claim not found',
+    description:
+      'The specified term ID does not correspond to any existing atom or triple on-chain.',
+    category: 'existence',
+    isCommon: true,
+  },
+} as const
+
+/**
+ * All error categories for filtering/grouping
+ */
+export const ERROR_CATEGORIES = [
+  'atom',
+  'triple',
+  'deposit',
+  'redeem',
+  'balance',
+  'limits',
+  'batch',
+  'approval',
+  'existence',
+  'epoch',
+  'wallet',
+  'internal',
+] as const
+
+export type ErrorCategory = (typeof ERROR_CATEGORIES)[number]
+
+/**
+ * Get all errors marked as commonly encountered by users
+ */
+export const COMMON_ERRORS = Object.entries(MULTIVAULT_ERRORS)
+  .filter(([, info]) => info.isCommon)
+  .reduce(
+    (acc, [key, value]) => {
+      acc[key] = value
+      return acc
+    },
+    {} as Record<string, MultiVaultErrorInfo>
+  )
+
+/**
+ * Total count of mapped errors
+ */
+export const TOTAL_ERROR_COUNT = Object.keys(MULTIVAULT_ERRORS).length // 31 errors
+
+/**
+ * Extract error name from various error formats
+ *
+ * Handles:
+ * - Viem ContractFunctionRevertedError with error.name
+ * - Error messages containing error names (e.g., "MultiVault_AtomExists")
+ * - Nested error.cause structures
+ *
+ * @param error - The error object from a contract call
+ * @returns The extracted error name or undefined if not found
+ */
+function extractErrorName(error: unknown): string | undefined {
+  if (!error) return undefined
+
+  // Type guard for error-like objects
+  const isErrorLike = (e: unknown): e is { message?: string; name?: string; cause?: unknown; data?: { errorName?: string } } =>
+    typeof e === 'object' && e !== null
+
+  if (!isErrorLike(error)) return undefined
+
+  // Check for viem's ContractFunctionRevertedError structure
+  // These have error.data.errorName
+  if (error.data?.errorName) {
+    return error.data.errorName
+  }
+
+  // Check for error.name that matches MultiVault pattern
+  if (error.name?.startsWith('MultiVault')) {
+    return error.name
+  }
+
+  // Search error message for known error names
+  if (error.message) {
+    for (const errorName of Object.keys(MULTIVAULT_ERRORS)) {
+      if (error.message.includes(errorName)) {
+        return errorName
+      }
+    }
+  }
+
+  // Check nested cause
+  if (error.cause) {
+    return extractErrorName(error.cause)
+  }
+
+  return undefined
+}
+
+/**
+ * Parse a contract error and return user-friendly error information
+ *
+ * This function attempts to match the error against known MultiVault errors
+ * and returns structured information for display in the UI.
+ *
+ * @param error - The error object from a contract call
+ * @returns Parsed error information with user-friendly message
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await createAtom(...)
+ * } catch (err) {
+ *   const parsed = parseMultiVaultError(err)
+ *   toast.error(parsed.userMessage)
+ *   if (parsed.isMultiVaultError) {
+ *     console.log('Contract error:', parsed.errorName)
+ *   }
+ * }
+ * ```
+ */
+export function parseMultiVaultError(error: unknown): ParsedMultiVaultError {
+  const errorName = extractErrorName(error)
+
+  if (errorName && MULTIVAULT_ERRORS[errorName]) {
+    const errorInfo = MULTIVAULT_ERRORS[errorName]
+    return {
+      userMessage: errorInfo.userMessage,
+      description: errorInfo.description,
+      isCommon: errorInfo.isCommon,
+      errorName: errorInfo.errorName,
+      category: errorInfo.category,
+      isMultiVaultError: true,
+    }
+  }
+
+  // Fallback for unknown errors
+  return {
+    userMessage: 'Transaction failed',
+    description: 'An unexpected error occurred. Please try again.',
+    isCommon: false,
+    isMultiVaultError: false,
+  }
+}
+
+/**
+ * Check if an error is a specific MultiVault error
+ *
+ * @param error - The error to check
+ * @param errorName - The specific error name to check for
+ * @returns True if the error matches the specified error name
+ *
+ * @example
+ * ```typescript
+ * if (isMultiVaultError(err, 'MultiVault_AtomExists')) {
+ *   // Handle atom already exists case
+ * }
+ * ```
+ */
+export function isMultiVaultError(
+  error: unknown,
+  errorName: keyof typeof MULTIVAULT_ERRORS
+): boolean {
+  const extracted = extractErrorName(error)
+  return extracted === errorName
+}
+
+/**
+ * Check if an error is any known MultiVault error
+ *
+ * @param error - The error to check
+ * @returns True if the error is a known MultiVault error
+ */
+export function isKnownMultiVaultError(error: unknown): boolean {
+  const extracted = extractErrorName(error)
+  return extracted !== undefined && extracted in MULTIVAULT_ERRORS
+}

package/src/utils/search/formatting.tsx

@@ -0,0 +1,95 @@
+import React from 'react'
+
+/**
+ * Format stake amount for display (converts from wei to TRUST with suffixes)
+ *
+ * @param marketCap - The market cap in wei (18 decimals)
+ * @returns Formatted string like "1.5K", "2.3M", etc.
+ *
+ * @example
+ * formatStake('1000000000000000000') // "1"
+ * formatStake('1500000000000000000000') // "1.5K"
+ * formatStake('2300000000000000000000000') // "2.3M"
+ */
+export function formatStake(marketCap: string | number | undefined): string {
+  if (!marketCap) return '0'
+
+  // Convert from wei (18 decimals) to TRUST
+  const trustValue = Number(BigInt(marketCap)) / 1e18
+
+  if (trustValue === 0) return '0'
+
+  // Helper to format with proper decimals and remove trailing zeros
+  const formatWithDecimals = (value: number, decimals: number = 2): string => {
+    return value.toFixed(decimals).replace(/\.?0+$/, '')
+  }
+
+  // Format in TRUST with K/M/B suffixes
+  if (trustValue >= 1e9) {
+    return `${formatWithDecimals(trustValue / 1e9, 2)}B`
+  } else if (trustValue >= 1e6) {
+    return `${formatWithDecimals(trustValue / 1e6, 2)}M`
+  } else if (trustValue >= 1e3) {
+    return `${formatWithDecimals(trustValue / 1e3, 2)}K`
+  } else {
+    // For smaller values, show up to 2 decimals
+    return formatWithDecimals(trustValue, 2)
+  }
+}
+
+/**
+ * Highlight matching text in search results
+ * Returns React elements with highlighted portions
+ *
+ * @param text - The text to highlight
+ * @param searchTerm - The search term to highlight
+ * @returns React elements with matching text highlighted
+ *
+ * @example
+ * highlightMatch('Vitalik Buterin', 'vitalik')
+ * // Returns: [<strong>Vitalik</strong>, ' Buterin']
+ */
+export function highlightMatch(
+  text: string,
+  searchTerm: string
+): React.ReactNode {
+  if (!text || !searchTerm) return text
+
+  const regex = new RegExp(`(${escapeRegExp(searchTerm)})`, 'gi')
+  const parts = text.split(regex)
+
+  return parts.map((part, i) =>
+    part.toLowerCase() === searchTerm.toLowerCase() ? (
+      <strong key={i} className="bg-yellow-500/20 text-yellow-500">
+        {part}
+      </strong>
+    ) : (
+      part
+    )
+  )
+}
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegExp(string: string): string {
+  return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * Format a term_id for display (first 5 characters after 0x)
+ *
+ * @param termId - The full term_id (e.g., "0x123456789...")
+ * @returns Shortened display format (e.g., "12345")
+ *
+ * @example
+ * formatTermId('0x123456789098765432') // "12345"
+ */
+export function formatTermId(termId: string): string {
+  if (!termId) return ''
+  if (termId.startsWith('0x')) {
+    return termId.slice(2, 7)
+  }
+  return termId.slice(0, 5)
+}
+

package/src/utils/search/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Search utilities for atom search functionality
+ * Shared between hivemind-explorer and intuition-extension
+ */
+
+// Ranking
+export {
+  calculateMatchScore,
+  rankAtoms,
+  getAtomDisplayName,
+  getAtomDescription,
+  getAtomImage,
+} from './ranking'
+
+// Formatting
+export { formatStake, highlightMatch, formatTermId } from './formatting'
+
+// Types
+export type {
+  AtomVault,
+  AtomValue,
+  AtomCreator,
+  GraphQLAtom,
+  RankedAtom,
+  SearchSummary,
+  SearchResult,
+} from './types'
+