smom-dbis-138/frontend-dapp/API_REFERENCE.md

Admin Panel API Reference

AdminContext API

Hooks

useAdmin()

Main hook for accessing admin functionality.

Returns:

{
  // Admin actions
  adminActions: AdminAction[]
  createAdminAction: (action: Omit<AdminAction, 'id' | 'status' | 'createdAt'> | AdminAction) => AdminAction
  updateAdminAction: (id: string, updates: Partial<AdminAction>) => void
  deleteAdminAction: (id: string) => void
  
  // Audit logs
  auditLogs: AuditLog[]
  addAuditLog: (log: Omit<AuditLog, 'id' | 'timestamp'>) => void
  exportAuditLogs: () => string
  
  // Preferences
  preferences: AdminPreferences
  updatePreferences: (updates: Partial<AdminPreferences>) => void
  
  // Impersonation
  impersonationAddress: string | null
  setImpersonationAddress: (address: string | null) => void
  isImpersonating: boolean
  
  // Admin check
  isAdmin: boolean
}

Types

AdminAction

interface AdminAction {
  id: string
  type: string
  contractAddress: `0x${string}`
  functionName: string
  args: unknown[]
  status: TransactionRequestStatus
  hash?: `0x${string}`
  error?: string
  createdAt: number
  executedAt?: number
}

AuditLog

interface AuditLog {
  id: string
  user: string
  action: string
  resourceType: string
  resourceId: string
  details?: any
  status: 'success' | 'error'
  timestamp: number
}

AdminPreferences

interface AdminPreferences {
  defaultExecutionMethod: 'direct' | 'multisig' | 'timelock'
  showAdvancedOptions: boolean
  autoApprove: boolean
  theme: 'dark' | 'light'
}

Utility Functions

Security Utilities (src/utils/security.ts)

validateAddress(address: string)

Validates an Ethereum address and returns checksummed version.

Parameters:

• address: string - Address to validate

Returns:

{
  valid: boolean
  checksummed?: string
  error?: string
}

generateSecureId()

Generates a cryptographically secure random ID.

Returns: string

rateLimit(action: string, limit: number, window: number)

Checks if an action exceeds rate limit.

Parameters:

• action: string - Action identifier
• limit: number - Maximum number of actions
• window: number - Time window in milliseconds

Returns: boolean - true if within limit

Encryption Utilities (src/utils/encryption.ts)

encryptData(data: string, key: string)

Encrypts data using AES-256-GCM.

Parameters:

• data: string - Data to encrypt
• key: string - Encryption key

Returns: Promise<string> - Encrypted data (hex)

decryptData(encrypted: string, key: string)

Decrypts encrypted data.

Parameters:

• encrypted: string - Encrypted data (hex)
• key: string - Decryption key

Returns: Promise<string> - Decrypted data

SecureStorage

Class for secure localStorage with encryption.

Methods:

• setItem(key: string, value: string): Promise<void>
• getItem(key: string): Promise<string | null>
• removeItem(key: string): void
• clear(): void

ENS Utilities (src/utils/ens.ts)

resolveENS(address: string)

Resolves an address to ENS name.

Parameters:

• address: string - Ethereum address

Returns: Promise<string | null> - ENS name or null

resolveAddress(name: string)

Resolves an ENS name to address.

Parameters:

• name: string - ENS name (e.g., "vitalik.eth")

Returns: Promise<string | null> - Address or null

clearENSCache()

Clears the ENS cache.

Returns: void

Safe SDK Helpers (src/helpers/admin/safeHelpers.ts)

validateSafeConfig(config: SafeConfig)

Validates Safe wallet configuration.

Parameters:

• config: SafeConfig - Safe configuration

Returns:

{
  valid: boolean
  error?: string
}

estimateSafeGas(transaction: SafeTransaction, owners: Address[], threshold: number)

Estimates gas for Safe transaction.

Returns:

{
  safeTxGas: bigint
  baseGas: bigint
  totalGas: bigint
}

Transaction Simulator (src/utils/transactionSimulator.ts)

simulateFunctionCall(publicClient, contractAddress, abi, functionName, args, from?)

Simulates a contract function call.

Returns: Promise<SimulationResult>

simulateBatch(publicClient, calls)

Simulates a batch of calls.

Returns: Promise<SimulationResult[]>

Real-time Monitoring (src/utils/realtimeMonitor.ts)

getRealtimeMonitor(wsUrl?)

Gets the real-time monitor instance.

Returns: RealtimeMonitor

Methods:

• subscribeToBlocks(chainId, callback)
• subscribeToTransaction(txHash, callback)
• subscribeToContractEvents(contractAddress, eventName, callback)
• subscribeToStateChanges(contractAddress, callback)
• connect(wsUrl?)
• disconnect()

Contract Events (src/utils/contractEvents.ts)

subscribeToContractEvents(publicClient, contractAddress, abi, eventName, callback, fromBlock?)

Subscribes to contract events.

Returns: Promise<() => void> - Unsubscribe function

waitForEvent(publicClient, contractAddress, abi, eventName, timeout?)

Waits for a specific event to occur.

Returns: Promise<ContractEvent>

getRecentEvents(publicClient, contractAddress, abi, eventName, blockRange?)

Gets recent events for a contract.

Returns: Promise<ContractEvent[]>

Gas Oracle (src/helpers/admin/gasOracle.ts)

fetchGasPrices()

Fetches current gas price recommendations from Etherscan.

Returns: Promise<GasPriceRecommendation | null>

getRecommendedGasPrice(recommendations, urgency)

Gets recommended gas price based on urgency.

Parameters:

• recommendations: GasPriceRecommendation
• urgency: 'slow' | 'standard' | 'fast'

Returns: Gas price recommendation object

Session Manager (src/utils/sessionManager.ts)

SessionManager

Class for managing admin sessions.

Methods:

• startSession(user: string): void
• extendSession(): void
• endSession(): void
• isSessionValid(): boolean
• getSessionData(): SessionData | null
• clearExpiredSessions(): void

Constants (src/utils/constants.ts)

DEFAULTS

Default configuration values.

STORAGE_KEYS

LocalStorage key constants.

RATE_LIMITS

Rate limiting configuration.

---

Note: This API reference covers the main utilities and hooks. For component-specific APIs, refer to individual component documentation.