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

# Admin Panel API Reference

## AdminContext API

### Hooks

#### `useAdmin()`

Main hook for accessing admin functionality.

**Returns:**
```typescript
{
  // 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`
```typescript
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`
```typescript
interface AuditLog {
  id: string
  user: string
  action: string
  resourceType: string
  resourceId: string
  details?: any
  status: 'success' | 'error'
  timestamp: number
}
```

#### `AdminPreferences`
```typescript
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:**
```typescript
{
  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:**
```typescript
{
  valid: boolean
  error?: string
}
```

#### `estimateSafeGas(transaction: SafeTransaction, owners: Address[], threshold: number)`
Estimates gas for Safe transaction.

**Returns:**
```typescript
{
  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.