diff --git a/.kiro/specs/audit-logging-system/.config.kiro b/.kiro/specs/audit-logging-system/.config.kiro deleted file mode 100644 index 66da1478..00000000 --- a/.kiro/specs/audit-logging-system/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "audit-logging-system", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/audit-logging-system/design.md b/.kiro/specs/audit-logging-system/design.md deleted file mode 100644 index 8721d2c8..00000000 --- a/.kiro/specs/audit-logging-system/design.md +++ /dev/null @@ -1,95 +0,0 @@ -# Design Document - -## Overview - -This design implements a comprehensive audit logging system for recording notification lifecycle events with immutability and queryability guarantees. - -## Architecture - -### Data Model - -```typescript -interface AuditLogEntry { - entryId: string; // Unique identifier - notificationId: string; // Reference to notification - timestamp: number; // Unix timestamp - eventType: EventType; // CREATION, DELIVERY_ATTEMPT, etc. - actor: string; // Address or identifier - status: 'success' | 'failure'; // Operation status - metadata: { - recipient?: string; - channel?: string; - errorReason?: string; - retryCount?: number; - [key: string]: any; // Flexible for event-specific data - }; - createdAt: number; // When log was created - immutable: true; // Flag indicating immutability -} - -enum EventType { - CREATION = 'CREATION', - DELIVERY_ATTEMPT = 'DELIVERY_ATTEMPT', - DELIVERY_SUCCESS = 'DELIVERY_SUCCESS', - DELIVERY_FAILURE = 'DELIVERY_FAILURE', - ACKNOWLEDGMENT = 'ACKNOWLEDGMENT' -} -``` - -### Storage Strategy - -1. **Primary Storage**: Database/persistent store for all audit logs -2. **Indexing**: Create indexes on notificationId, recipient, eventType, timestamp -3. **Archival**: Move logs older than retention period to archive -4. **Performance**: Use read-optimized queries for audit log retrieval - -### Query Interface - -```typescript -interface AuditLogQuery { - notificationId?: string; - recipient?: string; - eventType?: EventType | EventType[]; - dateRange?: { - startTime: number; - endTime: number; - }; - actor?: string; - limit?: number; // Default 100, max 1000 - offset?: number; // For pagination -} - -interface QueryResult { - entries: AuditLogEntry[]; - total: number; - hasMore: boolean; -} -``` - -### Integration Points - -1. **Event Subscriber**: Log CREATION events -2. **Discord Service**: Log DELIVERY_ATTEMPT, DELIVERY_SUCCESS, DELIVERY_FAILURE -3. **Notification Expiration**: Log EXPIRATION events -4. **API Endpoints**: Provide query interface for clients - -### Immutability Enforcement - -- No UPDATE operations on audit logs -- DELETE only through archive/purge administrative functions -- Logs stored in append-only structure -- Database constraints to prevent modification - -## Performance Considerations - -- Indexes on query fields (notificationId, recipient, eventType, timestamp) -- Pagination for large queries -- Cache frequently accessed audit logs -- Archive old logs to separate storage - -## Compliance and Retention - -- Default retention: 365 days -- Configurable retention policy -- Audit trails for who accessed what logs -- Compliance reporting endpoints \ No newline at end of file diff --git a/.kiro/specs/audit-logging-system/requirements.md b/.kiro/specs/audit-logging-system/requirements.md deleted file mode 100644 index 7e75e1fb..00000000 --- a/.kiro/specs/audit-logging-system/requirements.md +++ /dev/null @@ -1,97 +0,0 @@ -# Requirements Document - -## Introduction - -This feature creates an audit logging system that records notification lifecycle events for compliance and operational monitoring, enabling complete visibility into delivery attempts and outcomes. - -## Glossary - -- **Audit Log**: Immutable record of notification lifecycle events -- **Lifecycle Event**: Creation, delivery attempt, delivery failure, acknowledgment -- **Audit Record**: Single entry in the audit log with timestamp and event details -- **Query Endpoint**: API or function to retrieve and filter audit logs -- **Immutable**: Cannot be modified or deleted after creation -- **Compliance**: Meeting regulatory and operational requirements - -## Requirements - -### Requirement 1: Audit Event Schema - -**User Story:** As a compliance officer, I want a well-defined audit event schema, so that all events are recorded consistently. - -#### Acceptance Criteria - -1. THE audit event schema SHALL include: eventId, notificationId, timestamp, eventType, actor, status, metadata -2. THE eventType SHALL be one of: CREATION, DELIVERY_ATTEMPT, DELIVERY_SUCCESS, DELIVERY_FAILURE, ACKNOWLEDGMENT -3. THE actor field SHALL identify who/what triggered the event -4. THE metadata field SHALL be flexible JSON object for event-specific data -5. ALL fields SHALL be optional except eventId, timestamp, and eventType - -### Requirement 2: Creation Event Logging - -**User Story:** As an auditor, I want to see when notifications are created, so that I can track notification lifecycle start. - -#### Acceptance Criteria - -1. WHEN a notification is created, THE system SHALL log a CREATION event -2. THE CREATION event SHALL include: notificationId, creator address, recipient, title, content -3. THE CREATION event SHALL be logged before notification is marked active -4. THE event SHALL not be lost even if creation partially fails - -### Requirement 3: Delivery Attempt Logging - -**User Story:** As an operations manager, I want to see all delivery attempts, so that I can troubleshoot delivery issues. - -#### Acceptance Criteria - -1. WHEN delivery is attempted, THE system SHALL log a DELIVERY_ATTEMPT event -2. THE DELIVERY_ATTEMPT event SHALL include: notificationId, recipient, channel (Discord, etc.), timestamp -3. IF delivery succeeds, THE system SHALL log DELIVERY_SUCCESS event -4. IF delivery fails, THE system SHALL log DELIVERY_FAILURE event with error reason -5. EACH delivery attempt SHALL be logged independently - -### Requirement 4: Failure Logging - -**User Story:** As a support engineer, I want detailed failure logs, so that I can diagnose delivery problems. - -#### Acceptance Criteria - -1. WHEN delivery fails, THE system SHALL log failure reason/error message -2. THE failure log SHALL include: error type, error message, retry count, next retry time (if applicable) -3. RETRIES SHALL be logged as separate events -4. FAILURE logs SHALL be retained for troubleshooting - -### Requirement 5: Acknowledgment Logging - -**User Story:** As a product manager, I want to see when notifications are acknowledged, so that I can track user engagement. - -#### Acceptance Criteria - -1. WHEN a notification is acknowledged, THE system SHALL log an ACKNOWLEDGMENT event -2. THE ACKNOWLEDGMENT event SHALL include: notificationId, recipient, timestamp -3. MULTIPLE acknowledgments for same notification SHALL be supported -4. ACKNOWLEDGMENT timing relative to delivery SHALL be trackable - -### Requirement 6: Query Endpoints - -**User Story:** As a system user, I want to query audit logs, so that I can analyze notification history. - -#### Acceptance Criteria - -1. THE system SHALL provide query endpoint for retrieving audit logs -2. QUERIES SHALL support filtering by: notificationId, recipient, eventType, dateRange, actor -3. QUERIES SHALL return results in chronological order -4. QUERIES SHALL support pagination for large result sets -5. QUERIES SHALL be fast (sub-second response times) - -### Requirement 7: Immutability and Retention - -**User Story:** As a compliance manager, I want audit logs to be immutable, so that historical records cannot be tampered with. - -#### Acceptance Criteria - -1. AUDIT logs SHALL NOT be modifiable or deletable after creation -2. AUDIT logs SHALL be retained for minimum 365 days -3. ARCHIVED logs older than retention period MAY be removed -4. RETENTION policy SHALL be configurable -5. DELETION of logs SHALL only be allowed through privileged administrative function \ No newline at end of file diff --git a/.kiro/specs/audit-logging-system/tasks.md b/.kiro/specs/audit-logging-system/tasks.md deleted file mode 100644 index 2ada855d..00000000 --- a/.kiro/specs/audit-logging-system/tasks.md +++ /dev/null @@ -1,291 +0,0 @@ -# Implementation Plan: audit-logging-system - -## Overview - -This implementation plan creates a comprehensive audit logging system for recording notification lifecycle events with queryability and immutability guarantees. - -## Tasks - -- [ ] 1. Define audit log data structures - - [ ] 1.1 Create AuditLogEntry interface - - Fields: entryId, notificationId, timestamp, eventType, actor, status, metadata - - _Requirements: 1.1, 1.2_ - - - [ ] 1.2 Create EventType enum - - Values: CREATION, DELIVERY_ATTEMPT, DELIVERY_SUCCESS, DELIVERY_FAILURE, ACKNOWLEDGMENT - - _Requirements: 1.2_ - - - [ ] 1.3 Create AuditLogQuery interface for filtering - - Fields: notificationId, recipient, eventType, dateRange, actor, limit, offset - - _Requirements: 6.2_ - - - [ ] 1.4 Create QueryResult interface - - Fields: entries, total, hasMore - - _Requirements: 6.2, 6.4_ - -- [ ] 2. Implement audit log storage - - [ ] 2.1 Create database schema for audit logs - - Table/collection structure - - Indexes on query fields - - _Requirements: 6.1, 6.5_ - - - [ ] 2.2 Implement append-only storage pattern - - Ensure logs cannot be modified - - Enforce immutability at storage level - - _Requirements: 7.1, 7.2_ - - - [ ] 2.3 Configure retention policy - - Default 365 days - - Configurable per deployment - - _Requirements: 7.2, 7.4_ - - - [ ] 2.4 Implement archival mechanism - - Move old logs to archive storage - - Maintain query access to archived logs - - _Requirements: 7.3_ - -- [ ] 3. Implement AuditLogger service - - [ ] 3.1 Create AuditLogger class - - Methods: logCreation(), logDeliveryAttempt(), logDeliverySuccess(), logDeliveryFailure(), logAcknowledgment() - - Persist all events to database - - _Requirements: 2.1, 3.1, 4.1, 5.1_ - - - [ ] 3.2 Implement logCreation() method - - Accept: notificationId, creator, recipient, title, content - - Log CREATION event with metadata - - _Requirements: 2.1, 2.2, 2.3, 2.4_ - - - [ ] 3.3 Implement logDeliveryAttempt() method - - Accept: notificationId, recipient, channel - - Log DELIVERY_ATTEMPT event - - _Requirements: 3.1, 3.2, 3.3_ - - - [ ] 3.4 Implement logDeliverySuccess() method - - Accept: notificationId, recipient, channel - - Log DELIVERY_SUCCESS event - - _Requirements: 3.3, 3.4_ - - - [ ] 3.5 Implement logDeliveryFailure() method - - Accept: notificationId, recipient, channel, errorReason, retryCount - - Log DELIVERY_FAILURE event - - _Requirements: 3.4, 4.1, 4.2, 4.3, 4.4_ - - - [ ] 3.6 Implement logAcknowledgment() method - - Accept: notificationId, recipient - - Log ACKNOWLEDGMENT event - - _Requirements: 5.1, 5.2, 5.3_ - -- [ ] 4. Implement query interface - - [ ] 4.1 Create queryAuditLogs() function - - Accept AuditLogQuery parameters - - Return QueryResult with entries and pagination - - _Requirements: 6.1, 6.2, 6.3, 6.4_ - - - [ ] 4.2 Implement filtering by notificationId - - Query all events for a specific notification - - _Requirements: 6.2_ - - - [ ] 4.3 Implement filtering by recipient - - Query all events for a specific recipient - - _Requirements: 6.2_ - - - [ ] 4.4 Implement filtering by eventType - - Query events of specific type(s) - - Support multiple types in single query - - _Requirements: 6.2_ - - - [ ] 4.5 Implement filtering by dateRange - - Query events within time period - - _Requirements: 6.2_ - - - [ ] 4.6 Implement filtering by actor - - Query events by who triggered them - - _Requirements: 6.2_ - - - [ ] 4.7 Implement pagination support - - Support limit and offset parameters - - Return hasMore flag for client - - _Requirements: 6.4_ - -- [ ] 5. Integrate logging into event processing - - [ ] 5.1 Update EventSubscriber to log CREATION - - Call auditLogger.logCreation() when processing new notification - - _Requirements: 2.1, 2.2_ - - - [ ] 5.2 Update EventSubscriber to log failures - - Log when event processing fails - - Include error details - - _Requirements: 4.1, 4.2_ - - - [ ] 5.3 Update DiscordNotificationService to log delivery attempts - - Log DELIVERY_ATTEMPT before sending - - Log DELIVERY_SUCCESS if successful - - Log DELIVERY_FAILURE if unsuccessful - - _Requirements: 3.1, 3.2, 3.3, 3.4_ - - - [ ] 5.4 Add notification expiration logging - - Log when notifications expire - - Include expiration details in metadata - - _Requirements: 2.1_ - -- [ ] 6. Create API endpoints for audit queries - - [ ] 6.1 Create GET /audit-logs endpoint - - Query audit logs with filters - - Support query parameters: notificationId, recipient, eventType, startTime, endTime, limit, offset - - _Requirements: 6.1, 6.2, 6.3, 6.4_ - - - [ ] 6.2 Create GET /audit-logs/:notificationId endpoint - - Get all audit logs for a specific notification - - Return full lifecycle - - _Requirements: 6.1, 6.2, 6.3_ - - - [ ] 6.3 Create GET /audit-logs/recipient/:recipient endpoint - - Get all audit logs for a specific recipient - - _Requirements: 6.1, 6.2_ - - - [ ] 6.4 Create GET /audit-logs/stats endpoint - - Return audit log statistics - - Include: total events, events by type, date range, etc. - - _Requirements: 6.1_ - -- [ ] 7. Implement immutability guarantees - - [ ] 7.1 Add database constraints to prevent modification - - Use NOT NULL constraints on immutable field - - Add trigger to prevent UPDATE operations - - _Requirements: 7.1_ - - - [ ] 7.2 Implement access control for deletion - - Only administrators can purge old logs - - Require authorization for deletion - - _Requirements: 7.5_ - - - [ ] 7.3 Add audit trail for admin actions - - Log who accessed audit logs and when - - _Requirements: 7.1_ - -- [ ] 8. Create unit tests - - [ ] 8.1 Create audit-logger.test.ts - - Test each logging method - - Test event creation with correct metadata - - _Requirements: All_ - - - [ ] 8.2 Test logCreation() - - Verify event is logged with correct details - - _Requirements: 2.1, 2.2, 2.3, 2.4_ - - - [ ] 8.3 Test logDeliveryAttempt() - - Verify event is logged before delivery - - _Requirements: 3.1, 3.2_ - - - [ ] 8.4 Test logDeliverySuccess() - - Verify success event is logged - - _Requirements: 3.3_ - - - [ ] 8.5 Test logDeliveryFailure() - - Verify failure event with error details - - _Requirements: 4.1, 4.2, 4.3_ - - - [ ] 8.6 Test logAcknowledgment() - - Verify acknowledgment event is logged - - _Requirements: 5.1, 5.2_ - -- [ ] 9. Create query tests - - [ ] 9.1 Create audit-query.test.ts - - Test query interface - - _Requirements: 6.1, 6.2, 6.3, 6.4_ - - - [ ] 9.2 Test query by notificationId - - Verify correct logs returned - - _Requirements: 6.2_ - - - [ ] 9.3 Test query by recipient - - Verify correct logs returned - - _Requirements: 6.2_ - - - [ ] 9.4 Test query by eventType - - Test single and multiple types - - _Requirements: 6.2_ - - - [ ] 9.5 Test query by dateRange - - Verify only logs in range returned - - _Requirements: 6.2_ - - - [ ] 9.6 Test pagination - - Verify limit and offset work correctly - - Verify hasMore flag accurate - - _Requirements: 6.4_ - - - [ ] 9.7 Test query performance - - Verify sub-second response times - - _Requirements: 6.5_ - -- [ ] 10. Create integration tests - - [ ] 10.1 Create audit-integration.test.ts - - End-to-end test of notification lifecycle logging - - _Requirements: All_ - - - [ ] 10.2 Test complete notification lifecycle - - Create → Deliver → Acknowledge - - Verify all events logged in order - - _Requirements: 2.1, 3.1, 4.1, 5.1_ - - - [ ] 10.3 Test failure and retry scenario - - Delivery attempt → Failure → Retry → Success - - Verify all events logged with correct context - - _Requirements: 3.1, 4.1, 4.3_ - - - [ ] 10.4 Test immutability - - Attempt to modify audit log entry - - Verify error is returned - - _Requirements: 7.1_ - - - [ ] 10.5 Test retention policy - - Create old entries - - Verify they are archived/removed per policy - - _Requirements: 7.2, 7.3, 7.4_ - -- [ ] 11. Create documentation - - [ ] 11.1 Document audit log schema - - List all fields and types - - Explain each event type - - _Requirements: 1.1, 1.2_ - - - [ ] 11.2 Document query API - - Provide examples for each query type - - Document filter syntax - - _Requirements: 6.1, 6.2, 6.3, 6.4_ - - - [ ] 11.3 Document retention policy - - Explain default and custom retention - - Document archival process - - _Requirements: 7.2, 7.4_ - - - [ ] 11.4 Document compliance features - - Explain immutability guarantees - - Document audit trail for admin access - - _Requirements: 7.1, 7.5_ - -- [ ] 12. Final testing checkpoint - - [ ] 12.1 Run all tests - - Ensure no regressions - - Verify all requirements met - - _Requirements: All_ - - - [ ] 12.2 Performance testing - - Measure query times - - Verify performance meets requirements - - _Requirements: 6.5_ - - - [ ] 12.3 Compliance verification - - Verify immutability enforcement - - Test retention policy - - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5_ - -## Notes - -- Audit logs should be append-only to ensure immutability -- All lifecycle events should be logged regardless of success/failure -- Query performance is critical - proper indexing is essential -- Retention policy must be configurable and enforced -- Consider separate storage/archival for old logs -- Compliance and regulatory requirements may require additional fields \ No newline at end of file diff --git a/.kiro/specs/batch-notification-creation/.config.kiro b/.kiro/specs/batch-notification-creation/.config.kiro deleted file mode 100644 index 97ea20d3..00000000 --- a/.kiro/specs/batch-notification-creation/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "batch-notification-creation", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/batch-notification-creation/design.md b/.kiro/specs/batch-notification-creation/design.md deleted file mode 100644 index 65606031..00000000 --- a/.kiro/specs/batch-notification-creation/design.md +++ /dev/null @@ -1,90 +0,0 @@ -# Design Document - -## Overview - -This design implements batch notification creation to improve efficiency and reduce gas costs for organizations creating multiple notifications. - -## Architecture - -### Function Signature - -```rust -pub fn create_notification_batch( - env: &Env, - organization: Address, - notifications: Vec, - max_batch_size: u32, -) -> Result, Error> -``` - -### Data Structures - -```rust -pub struct NotificationParams { - pub recipient: Address, - pub title: String, - pub content: String, - pub expiration: u64, -} - -pub struct BatchResult { - pub created_ids: Vec, - pub total_gas_used: u64, -} -``` - -### Processing Flow - -1. **Validation Phase** - - Check authorization (only organization can create) - - Validate batch size (not exceeding max) - - Validate each notification parameters - - Validate recipient addresses - -2. **Creation Phase** - - Create notifications in loop - - Store each in persistent storage - - Collect IDs for return - -3. **Event Emission Phase** - - Emit event for each created notification - - Include batch metadata in events - - Maintain event order - -### Gas Optimization Strategies - -1. **Single State Write**: Batch all writes together -2. **Minimal Copying**: Reuse parameters where possible -3. **Efficient Storage**: Use vec operations instead of individual stores -4. **Early Validation**: Fail fast before any state changes - -### Limitations - -- Maximum 100 notifications per batch (configurable) -- All or nothing: batch fails if any notification fails -- All recipients in a batch created in single transaction -- Cannot mix different notification types in one batch - -## Error Handling - -```rust -pub enum Error { - BatchSizeExceeded, // > max_batch_size - EmptyBatch, // 0 recipients - InvalidRecipient(usize), // Invalid recipient at index - InsufficientFunds, // Not enough balance for batch - Unauthorized, // Not organization owner -} -``` - -## Gas Comparison - -**Individual Creations**: Creating 10 notifications individually -- Per notification: ~5000 gas -- Total: 50,000 gas - -**Batch Creation**: Creating 10 notifications in batch -- Overhead: ~2000 gas -- Per notification: ~3500 gas -- Total: 37,000 gas -- Savings: ~26% \ No newline at end of file diff --git a/.kiro/specs/batch-notification-creation/requirements.md b/.kiro/specs/batch-notification-creation/requirements.md deleted file mode 100644 index 0e9c2f2a..00000000 --- a/.kiro/specs/batch-notification-creation/requirements.md +++ /dev/null @@ -1,75 +0,0 @@ -# Requirements Document - -## Introduction - -This feature introduces a batch notification creation mechanism that allows organizations to create multiple notifications in a single transaction, improving efficiency and reducing gas costs. - -## Glossary - -- **Batch Operation**: Creating multiple notifications in a single transaction -- **Recipient Array**: List of addresses or identifiers for notification recipients -- **Gas Consumption**: Cost in network fees for executing blockchain operations -- **Transaction**: Single atomic operation on the blockchain -- **Notification Creation**: Process of registering a new notification in the system - -## Requirements - -### Requirement 1: Batch Creation Function - -**User Story:** As an organization administrator, I want to create multiple notifications in a single transaction, so that I can reduce operational overhead. - -#### Acceptance Criteria - -1. THE system SHALL support a createNotificationBatch() function -2. THE function SHALL accept an array of notification parameters -3. THE function SHALL process all notifications atomically -4. IF any notification fails validation, THE entire batch SHALL be rejected -5. IF the batch succeeds, ALL notifications SHALL be created - -### Requirement 2: Recipient Array Validation - -**User Story:** As a system administrator, I want invalid recipients to be rejected appropriately, so that malformed batches don't partially succeed. - -#### Acceptance Criteria - -1. THE system SHALL validate each recipient in the batch -2. THE system SHALL reject recipients with invalid format -3. THE system SHALL reject empty recipient arrays -4. THE system SHALL reject null or undefined recipients -5. THE system SHALL support configurable maximum batch size (e.g., 100 recipients per batch) -6. IF validation fails for any recipient, THE entire batch SHALL be rejected - -### Requirement 3: Event Emission - -**User Story:** As an off-chain listener, I want events for each created notification, so that I can track all creations. - -#### Acceptance Criteria - -1. THE system SHALL emit a creation event for each notification in the batch -2. THE events SHALL be emitted in the same transaction -3. EACH event SHALL include the notification ID and recipient -4. THE event order SHALL match the input batch order - -### Requirement 4: Gas Efficiency - -**User Story:** As a cost-conscious organization, I want batch creation to reduce gas costs, so that my operational expenses are lower. - -#### Acceptance Criteria - -1. BATCH creation SHALL consume less gas per notification than individual creations -2. GAS savings SHALL be at least 20% for typical batches -3. THE system SHALL NOT include unnecessary data in batch operations -4. LARGER batches SHALL have proportionally greater gas savings - -### Requirement 5: Testing and Documentation - -**User Story:** As a developer, I want comprehensive tests and documentation, so that I can confidently use batch creation. - -#### Acceptance Criteria - -1. UNIT tests SHALL cover single and multiple notifications -2. UNIT tests SHALL cover edge cases (empty batch, max size, invalid recipients) -3. INTEGRATION tests SHALL verify batch creation end-to-end -4. BENCHMARK tests SHALL measure gas consumption -5. DOCUMENTATION SHALL explain limitations and best practices -6. DOCUMENTATION SHALL include examples for 10, 50, and 100 notification batches \ No newline at end of file diff --git a/.kiro/specs/batch-notification-creation/tasks.md b/.kiro/specs/batch-notification-creation/tasks.md deleted file mode 100644 index bb1a7d92..00000000 --- a/.kiro/specs/batch-notification-creation/tasks.md +++ /dev/null @@ -1,250 +0,0 @@ -# Implementation Plan: batch-notification-creation - -## Overview - -This implementation plan adds batch notification creation functionality to reduce gas costs and improve operational efficiency for organizations. - -## Tasks - -- [ ] 1. Define batch operation types and structures - - [ ] 1.1 Create NotificationParams struct - - Fields: recipient, title, content, expiration - - _Requirements: 1.1, 1.2_ - - - [ ] 1.2 Create BatchResult struct - - Fields: created_ids, total_gas_used - - _Requirements: 1.1, 4.4_ - - - [ ] 1.3 Define batch size constants - - MAX_BATCH_SIZE = 100 - - MIN_BATCH_SIZE = 1 - - _Requirements: 2.5_ - - - [ ] 1.4 Define error types for batch operations - - BatchSizeExceeded, EmptyBatch, InvalidRecipient, etc. - - _Requirements: 2.2, 2.3, 2.4_ - -- [ ] 2. Implement batch validation logic - - [ ] 2.1 Create validate_batch() function - - Check batch not empty - - Check batch size <= MAX_BATCH_SIZE - - _Requirements: 2.1, 2.3, 2.5_ - - - [ ] 2.2 Create validate_recipients() function - - Check each recipient is valid address - - Check no null/undefined recipients - - Check recipients not empty - - _Requirements: 2.1, 2.2, 2.3, 2.4_ - - - [ ] 2.3 Create validate_notification_params() function - - Validate title not empty - - Validate content not empty - - Validate expiration is valid - - _Requirements: 2.1, 2.2_ - - - [ ] 2.4 Integrate validation into batch function - - Call all validators before processing - - Return error immediately if any fails - - _Requirements: 2.1, 2.2, 2.3, 2.4_ - -- [ ] 3. Implement batch creation core function - - [ ] 3.1 Create create_notification_batch() function - - Accept organization, notifications array, max_batch_size - - Call validators - - Create notifications in loop - - Return array of created IDs - - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5_ - - - [ ] 3.2 Implement atomic transaction handling - - Ensure all-or-nothing semantics - - Rollback on any error - - _Requirements: 1.4, 1.5_ - - - [ ] 3.3 Implement authorization check - - Verify caller is organization - - Use require_auth for signature verification - - _Requirements: 1.1_ - - - [ ] 3.4 Implement storage of batch metadata - - Store batch ID and creation timestamp - - Store array of notification IDs - - _Requirements: 3.1, 3.2, 3.3_ - -- [ ] 4. Implement event emission for batch - - [ ] 4.1 Emit event for each notification in batch - - Create NotificationCreated event per notification - - Include batch ID in metadata - - _Requirements: 3.1, 3.2, 3.3_ - - - [ ] 4.2 Ensure event order matches input order - - Events emitted in same order as input array - - _Requirements: 3.4_ - - - [ ] 4.3 Include batch metadata in events - - Event should reference batch operation - - Include total batch size - - _Requirements: 3.1, 3.2, 3.3_ - -- [ ] 5. Optimize for gas efficiency - - [ ] 5.1 Minimize state writes in batch operation - - Batch all writes together if possible - - Use efficient data structures - - _Requirements: 4.1, 4.3_ - - - [ ] 5.2 Optimize parameter passing - - Minimize copying of data - - Use references where possible - - _Requirements: 4.1, 4.3_ - - - [ ] 5.3 Profile gas usage before optimization - - Measure baseline gas usage - - Identify hot spots - - _Requirements: 4.2, 4.4_ - -- [ ] 6. Create unit tests for batch operations - - [ ] 6.1 Create batch_tests.rs file - - Set up test infrastructure - - Create test fixtures - - _Requirements: 5.1, 5.2, 5.3_ - - - [ ] 6.2 Test single notification batch - - Create batch with 1 notification - - Verify notification created - - Verify event emitted - - _Requirements: 5.1, 5.6_ - - - [ ] 6.3 Test multiple notification batch - - Create batch with 10 notifications - - Verify all created - - Verify all events emitted in order - - _Requirements: 5.1, 5.2_ - - - [ ] 6.4 Test maximum batch size - - Create batch with MAX_BATCH_SIZE notifications - - Verify all created - - _Requirements: 5.1, 5.2, 5.6_ - - - [ ] 6.5 Test empty batch rejection - - Attempt to create batch with 0 notifications - - Verify EmptyBatch error returned - - _Requirements: 5.1, 2.3_ - - - [ ] 6.6 Test batch size exceeded rejection - - Attempt to create batch with > MAX_BATCH_SIZE - - Verify BatchSizeExceeded error returned - - _Requirements: 5.1, 2.5_ - - - [ ] 6.7 Test invalid recipient rejection - - Attempt batch with invalid address format - - Verify entire batch rejected - - _Requirements: 5.1, 2.2, 2.6_ - - - [ ] 6.8 Test null recipient rejection - - Attempt batch with null recipient - - Verify batch rejected - - _Requirements: 5.1, 2.4, 2.6_ - - - [ ] 6.9 Test batch atomicity - all or nothing - - Create batch where one notification fails - - Verify entire batch rolled back - - Verify no notifications created - - _Requirements: 5.1, 1.4, 1.5_ - - - [ ] 6.10 Test authorization - only organization can create - - Attempt batch creation by non-organization - - Verify Unauthorized error - - _Requirements: 5.1_ - -- [ ] 7. Create integration tests - - [ ] 7.1 Create batch_integration_tests.rs - - Test end-to-end batch creation - - Verify persistence - - _Requirements: 5.3_ - - - [ ] 7.2 Test batch creation with varying sizes - - Test 1, 10, 50, 100 notification batches - - Verify all succeed - - _Requirements: 5.3, 5.6_ - - - [ ] 7.3 Test event emission for large batch - - Create 100 notification batch - - Verify 100 events emitted in order - - _Requirements: 3.1, 3.2, 3.4, 5.3_ - - - [ ] 7.4 Test batch metadata persistence - - Create batch - - Query batch metadata - - Verify all fields present - - _Requirements: 3.1, 3.2, 3.3_ - -- [ ] 8. Create gas benchmarking tests - - [ ] 8.1 Benchmark individual notifications - - Create 10 notifications one by one - - Measure total gas consumed - - _Requirements: 4.2, 4.4, 5.4_ - - - [ ] 8.2 Benchmark batch creation - - Create batch of 10 notifications - - Measure total gas consumed - - Compare against individual - - _Requirements: 4.2, 4.4, 5.4_ - - - [ ] 8.3 Benchmark various batch sizes - - Test 1, 5, 10, 50, 100 notification batches - - Measure gas per notification - - Calculate savings percentage - - _Requirements: 4.1, 4.2, 4.4_ - - - [ ] 8.4 Document gas benchmarks - - Create benchmark report - - Include comparison table - - Include recommendations - - _Requirements: 4.2, 5.5_ - -- [ ] 9. Create usage examples - - [ ] 9.1 Document batch creation API - - Function signature - - Parameter descriptions - - Return value documentation - - _Requirements: 5.5, 5.6_ - - - [ ] 9.2 Provide examples for different batch sizes - - Example: 10 notification batch - - Example: 50 notification batch - - Example: 100 notification batch - - _Requirements: 5.6_ - - - [ ] 9.3 Document error handling - - Document each error type - - Provide recovery recommendations - - _Requirements: 5.5_ - - - [ ] 9.4 Document limitations - - Maximum batch size - - All-or-nothing semantics - - Single notification type per batch - - _Requirements: 5.5_ - -- [ ] 10. Final testing checkpoint - - [ ] 10.1 Run all tests - - Ensure no regressions - - Verify all requirements met - - _Requirements: 5.1, 5.2, 5.3_ - - - [ ] 10.2 Verify gas efficiency targets - - Confirm >= 20% savings - - Document actual savings - - _Requirements: 4.1, 4.2, 4.4_ - - - [ ] 10.3 Code review preparation - - Ensure code quality - - Add comments and documentation - - _Requirements: 5.5, 5.6_ - -## Notes - -- All-or-nothing atomicity is critical - batch fails completely if any notification fails -- Gas optimization should be measured and documented -- Examples should cover common batch sizes (10, 50, 100) -- Consider adding metrics collection for gas measurements -- Documentation should explain when to use batch vs individual creation \ No newline at end of file diff --git a/.kiro/specs/custom-error-types/.config.kiro b/.kiro/specs/custom-error-types/.config.kiro deleted file mode 100644 index 6a7b41d6..00000000 --- a/.kiro/specs/custom-error-types/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "custom-error-types", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/custom-error-types/design.md b/.kiro/specs/custom-error-types/design.md deleted file mode 100644 index b9391324..00000000 --- a/.kiro/specs/custom-error-types/design.md +++ /dev/null @@ -1,60 +0,0 @@ -# Design Document - -## Overview - -This design replaces generic error strings with custom Rust error types in the Soroban smart contract to reduce deployment size and improve gas efficiency. - -## Architecture - -### Error Type Structure - -```rust -#[derive(Debug)] -pub enum NotificationError { - // Authorization errors - AdminUnauthorized, - InvalidAdmin, - - // State errors - ContractPaused, - AlreadyPaused, - NotPaused, - - // Notification errors - NotificationNotFound, - InvalidNotification, - InvalidRecipient, - - // Validation errors - InvalidTimestamp, - InvalidEventPayload, - EmptyRecipientList, - TooManyRecipients, - - // State transition errors - InvalidStateTransition, - DuplicateOperation, -} -``` - -### Implementation Strategy - -1. Define comprehensive error enum in `base/errors.rs` -2. Replace all `require!` macro with custom error returns -3. Update error handling in all modules -4. Add error conversion traits if needed -5. Update tests to verify error types - -### Integration Points - -- **Authorization module**: AdminUnauthorized, InvalidAdmin -- **Pause mechanism**: ContractPaused, AlreadyPaused, NotPaused -- **Event validation**: InvalidEventPayload, InvalidTimestamp -- **Notification creation**: NotificationNotFound, InvalidNotification -- **Recipient validation**: InvalidRecipient, EmptyRecipientList, TooManyRecipients - -### Gas Savings - -- Custom error enums: ~4 bytes per error vs 30+ bytes for strings -- Estimated reduction: 10-20% of contract size -- Reduced storage reads for error handling \ No newline at end of file diff --git a/.kiro/specs/custom-error-types/requirements.md b/.kiro/specs/custom-error-types/requirements.md deleted file mode 100644 index 4166f9b4..00000000 --- a/.kiro/specs/custom-error-types/requirements.md +++ /dev/null @@ -1,52 +0,0 @@ -# Requirements Document - -## Introduction - -This feature replaces generic error strings with custom error types to reduce deployment size and gas usage. In Soroban, this means using custom Rust error enums instead of string panic messages. - -## Glossary - -- **Custom Error Type**: Enum defining specific error conditions in Rust -- **Generic Error String**: Human-readable error message string -- **Contract Size**: Total bytes of compiled contract code -- **Gas Usage**: Operational cost of contract execution -- **Error Variant**: Individual case in an error enum -- **Error Handling**: Code that manages error conditions - -## Requirements - -### Requirement 1: Replace Generic Revert Strings - -**User Story:** As a contract developer, I want generic error strings replaced with custom error types, so that deployment size is reduced. - -#### Acceptance Criteria - -1. ALL applicable panic strings and error messages SHALL use custom error types -2. GENERIC error strings SHALL be converted to specific error enum variants -3. EACH error type SHALL have a descriptive name -4. ERROR types SHALL be defined in base/errors.rs module -5. ERROR messages SHALL not exceed necessary description length - -### Requirement 2: Descriptive Error Names - -**User Story:** As an integrator, I want error names to be descriptive, so that I can understand what went wrong. - -#### Acceptance Criteria - -1. EACH error variant name SHALL clearly indicate the error condition -2. ERROR names SHALL follow Rust naming conventions (PascalCase) -3. ERROR names SHALL avoid generic terms like "Error" or "Failed" -4. ERROR documentation SHALL explain when each error occurs -5. ERROR variants SHALL be organized logically in the error enum - -### Requirement 3: Test Coverage - -**User Story:** As a QA engineer, I want tests to confirm expected errors, so that error handling is verified. - -#### Acceptance Criteria - -1. UNIT tests SHALL verify that operations produce expected error types -2. TESTS SHALL cover both success and failure paths -3. TESTS SHALL verify correct error is returned for each condition -4. INTEGRATION tests SHALL confirm error propagation through call stacks -5. ERROR recovery scenarios SHALL be tested \ No newline at end of file diff --git a/.kiro/specs/custom-error-types/tasks.md b/.kiro/specs/custom-error-types/tasks.md deleted file mode 100644 index da6f4c0a..00000000 --- a/.kiro/specs/custom-error-types/tasks.md +++ /dev/null @@ -1,147 +0,0 @@ -# Implementation Plan: custom-error-types - -## Overview - -This implementation plan replaces generic error strings with custom error types throughout the Soroban contract to reduce deployment size and improve gas efficiency. - -## Tasks - -- [ ] 1. Define custom error enum - - [ ] 1.1 Create comprehensive error enum in base/errors.rs - - Add all error variants needed across contract - - Add documentation for each variant - - Include AdminUnauthorized, ContractPaused, InvalidNotification, etc. - - _Requirements: 1.1, 1.2, 2.1, 2.2_ - - - [ ] 1.2 Implement error traits - - Implement Display trait for human-readable errors - - Implement From traits for error conversion if needed - - _Requirements: 2.1, 2.2_ - -- [ ] 2. Replace authorization error strings - - [ ] 2.1 Update require_admin() function - - Replace string-based errors with AdminUnauthorized variant - - Update all panic messages to use custom error - - _Requirements: 1.1, 1.2_ - - - [ ] 2.2 Update authorization checks - - Replace all authorization error strings in contract - - Use consistent error types across all auth points - - _Requirements: 1.1, 1.2_ - -- [ ] 3. Replace pause mechanism error strings - - [ ] 3.1 Update pause() function errors - - Replace AlreadyPaused error strings with custom type - - Replace AdminUnauthorized strings with custom type - - _Requirements: 1.1, 1.2_ - - - [ ] 3.2 Update unpause() function errors - - Replace NotPaused error strings with custom type - - Replace AdminUnauthorized strings with custom type - - _Requirements: 1.1, 1.2_ - - - [ ] 3.3 Update check_not_paused() guard - - Replace ContractPaused error strings with custom type - - Apply throughout notification operations - - _Requirements: 1.1, 1.2_ - -- [ ] 4. Replace notification creation error strings - - [ ] 4.1 Update create_notification() errors - - Replace InvalidNotification strings with custom type - - Replace InvalidRecipient strings with custom type - - Replace EmptyRecipientList strings with custom type - - _Requirements: 1.1, 1.2_ - - - [ ] 4.2 Update recipient validation errors - - Replace TooManyRecipients strings with custom type - - Replace InvalidRecipient strings with custom type - - _Requirements: 1.1, 1.2_ - -- [ ] 5. Replace event validation error strings - - [ ] 5.1 Update validateEventPayload() errors - - Replace InvalidEventPayload strings with custom type - - Replace InvalidTimestamp strings with custom type - - _Requirements: 1.1, 1.2_ - - - [ ] 5.2 Update topic validation errors - - Replace validation error strings with custom types - - _Requirements: 1.1, 1.2_ - -- [ ] 6. Replace state transition error strings - - [ ] 6.1 Update state validation errors - - Replace InvalidStateTransition strings with custom type - - Replace DuplicateOperation strings with custom type - - _Requirements: 1.1, 1.2_ - -- [ ] 7. Add unit tests for error types - - [ ] 7.1 Create error handling tests - - Test that operations return expected error types - - Test error messages are descriptive - - Test error types match documented behavior - - _Requirements: 3.1, 3.2, 3.3_ - - - [ ] 7.2 Test authorization errors - - Verify AdminUnauthorized returned for non-admin calls - - Verify InvalidAdmin returned for invalid admin addresses - - _Requirements: 3.1, 3.2, 3.3_ - - - [ ] 7.3 Test pause mechanism errors - - Verify ContractPaused returned when operations blocked - - Verify AlreadyPaused returned for duplicate pause - - Verify NotPaused returned for unpause when not paused - - _Requirements: 3.1, 3.2, 3.3_ - - - [ ] 7.4 Test notification creation errors - - Verify InvalidNotification returned for invalid notifications - - Verify InvalidRecipient returned for bad recipients - - Verify EmptyRecipientList returned for no recipients - - Verify TooManyRecipients returned for oversized batch - - _Requirements: 3.1, 3.2, 3.3_ - - - [ ] 7.5 Test event validation errors - - Verify InvalidEventPayload returned for malformed events - - Verify InvalidTimestamp returned for bad timestamps - - _Requirements: 3.1, 3.2, 3.3_ - -- [ ] 8. Add integration tests - - [ ] 8.1 Test error propagation - - Verify errors propagate correctly through call stacks - - Verify callers receive expected error types - - _Requirements: 3.4_ - - - [ ] 8.2 Test error recovery - - Verify system can recover after error conditions - - Verify state is consistent after errors - - _Requirements: 3.5_ - -- [ ] 9. Verify deployment size reduction - - [ ] 9.1 Compare contract sizes - - Measure before and after deployment sizes - - Document size reduction percentage - - _Requirements: 1.1, 1.2_ - - - [ ] 9.2 Verify gas efficiency - - Benchmark error handling gas costs before/after - - Document gas usage improvements - - _Requirements: 1.1_ - -- [ ] 10. Update documentation - - [ ] 10.1 Document error types - - Add error reference documentation - - Include when each error occurs - - Include error recovery steps - - _Requirements: 2.1, 2.2, 2.3_ - - - [ ] 10.2 Update contract documentation - - Update error handling guide - - Add error handling examples - - Document custom error usage patterns - - _Requirements: 2.1, 2.2, 2.3_ - -## Notes - -- Custom error enums are more efficient than string errors -- Each error variant should have a descriptive name -- Error types should be organized by category -- Tests must verify correct error type for each condition -- Documentation should help integrators understand errors \ No newline at end of file diff --git a/.kiro/specs/event-detail-drawer/.config.kiro b/.kiro/specs/event-detail-drawer/.config.kiro deleted file mode 100644 index 4757415b..00000000 --- a/.kiro/specs/event-detail-drawer/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "8f42c1d7-e3a9-4c2e-b1f6-9e4a2c5d8b3a", "workflowType": "requirements-first", "specType": "feature"} diff --git a/.kiro/specs/event-detail-drawer/design.md b/.kiro/specs/event-detail-drawer/design.md deleted file mode 100644 index e69de29b..00000000 diff --git a/.kiro/specs/event-detail-drawer/requirements.md b/.kiro/specs/event-detail-drawer/requirements.md deleted file mode 100644 index 36c2cb03..00000000 --- a/.kiro/specs/event-detail-drawer/requirements.md +++ /dev/null @@ -1,227 +0,0 @@ -# Requirements Document: Event Detail Drawer - -## Introduction - -The event detail drawer is a dedicated UI component that allows users to inspect individual blockchain events in detail without navigating away from the event feed. Currently, users must navigate to separate pages or open multiple windows to examine event metadata, transaction details, and payload information. This feature provides an in-context inspection mechanism through a slide-out drawer panel that displays comprehensive event information while maintaining the user's position in the event feed. The drawer supports keyboard navigation, accessible interaction patterns, and readable display of long payload values. - -## Glossary - -- **Event Detail Drawer**: A modal slide-out panel that displays comprehensive information about a selected blockchain event -- **Event Feed**: The list or timeline view displaying multiple blockchain events -- **Blockchain Event**: An emission from a smart contract containing metadata, payload, transaction data, and timestamps -- **Event Metadata**: Core event information including event name, type, contract address, ledger number, transaction hash, and timestamp -- **Event Payload**: The custom data associated with an event, potentially containing long strings or nested structures -- **Drawer Panel**: The visible slide-out container that slides in from the side to display event details -- **Backdrop**: The semi-transparent overlay behind the drawer that obscures the feed -- **Feed Position**: The user's current scroll position and visible range in the event list -- **Long Value**: A payload field or metadata string that exceeds typical display width and requires special handling (>80 characters) -- **Readable Display**: A format that allows users to view and work with long values without horizontal scrolling or truncation artifacts -- **Keyboard Accessibility**: The ability to open, navigate, and close the drawer using keyboard input only -- **Focus Management**: The proper sequencing and restriction of keyboard focus within the drawer when open -- **Event_Inspector**: The system component responsible for extracting and formatting event information for display -- **Drawer_Controller**: The system component managing drawer open/close state and feed position preservation - -## Requirements - -### Requirement 1: Open Drawer on Event Selection - -**User Story:** As a user, I want to click on an event in the feed to open a detail drawer, so that I can inspect its information without losing my place. - -#### Acceptance Criteria - -1. WHEN a user clicks on an event in the event feed, THE Event_Inspector SHALL open the Drawer_Panel -2. WHEN the Drawer_Panel opens, THE backdrop SHALL render behind the panel and feed -3. WHEN the Drawer_Panel opens, THE event being inspected SHALL be visually highlighted or indicated in the feed -4. WHEN a user double-clicks an event, THE Drawer_Panel SHALL open only once (no duplicate opening) -5. WHEN the Drawer_Panel is already open and a user selects a different event, THE Drawer_Panel SHALL update to display the newly selected event without closing and reopening - -### Requirement 2: Display Event Metadata in Drawer - -**User Story:** As a user, I want to see complete event metadata in the drawer, so that I can verify event details at a glance. - -#### Acceptance Criteria - -1. THE Drawer_Panel SHALL display the event name prominently in the header -2. THE Drawer_Panel SHALL display the contract address that emitted the event -3. THE Drawer_Panel SHALL display the event type classification -4. THE Drawer_Panel SHALL display the ledger number where the event was recorded -5. THE Drawer_Panel SHALL display the event ID uniquely identifying the event -6. THE Drawer_Panel SHALL display the transaction hash if present, or a null indicator if unavailable -7. THE Drawer_Panel SHALL display the timestamp when the event was received by the listener -8. WHEN event metadata contains ISO 8601 timestamps, THE Drawer_Panel SHALL format them as human-readable dates (e.g., "2024-01-15 14:30:45 UTC") - -### Requirement 3: Display Readable Long Payload Values - -**User Story:** As a user, I want to see long payload values without truncation or horizontal scrolling, so that I can read complete values easily. - -#### Acceptance Criteria - -1. WHEN a payload field value exceeds 80 characters, THE Event_Inspector SHALL NOT truncate it with an ellipsis (…) -2. WHEN a payload field value is longer than viewport width, THE Event_Inspector SHALL wrap the text to multiple lines -3. WHEN a payload field contains a long hash or encoded value, THE Event_Inspector SHALL allow the value to word-wrap or break at word boundaries where possible -4. WHEN a payload field contains special characters, newlines, or unicode characters, THE Event_Inspector SHALL preserve and display them legibly -5. THE Drawer_Panel SHALL provide adequate vertical scrolling within the drawer for payloads with many fields -6. WHEN hovering over a long payload value, THE Drawer_Panel MAY provide a tooltip or full value preview (optional enhancement) - -### Requirement 4: Close Drawer and Preserve Feed Position - -**User Story:** As a user, I want to close the drawer and return to my current position in the event feed, so that I don't lose my reading progress. - -#### Acceptance Criteria - -1. WHEN a user clicks the close button in the drawer header, THE Drawer_Controller SHALL close the drawer and render it invisible -2. WHEN a user clicks the backdrop behind the drawer, THE Drawer_Controller SHALL close the drawer -3. WHEN a user presses the Escape key while the drawer is open, THE Drawer_Controller SHALL close the drawer -4. WHEN the drawer closes, THE Drawer_Controller SHALL preserve the feed's scroll position (if not scrolled by user during drawer open) -5. WHEN the drawer closes, THE feed focus SHALL return to the previously selected or focused element in the feed -6. WHEN the drawer is closed, THE backdrop SHALL be removed from the DOM or rendered invisible -7. WHEN a user opens and closes the drawer multiple times while browsing, THE feed position SHALL remain consistent across opens (unless manually scrolled) - -### Requirement 5: Support Keyboard Navigation - -**User Story:** As a user, I want to interact with the drawer using only keyboard input, so that I can use the dashboard efficiently without a mouse. - -#### Acceptance Criteria - -1. WHEN the drawer is open, THE Tab key SHALL cycle focus through interactive elements within the drawer -2. WHEN the drawer is open, THE Shift+Tab key combination SHALL cycle focus backwards through drawer elements -3. WHEN focus is on the close button and Enter or Space is pressed, THE drawer SHALL close -4. WHEN the drawer is open, THE Escape key SHALL close the drawer from any focused element -5. WHEN the drawer is open, Tab focus SHALL not leave the drawer to cycle through feed elements (focus trap) -6. WHEN the drawer closes, keyboard focus SHALL return to the event that opened it or the nearest focusable element in the feed -7. WHEN the drawer is open, THE first interactive element in the drawer SHALL receive focus automatically (or the drawer container itself) -8. WHEN the drawer is open, THE close button SHALL be reachable via keyboard Tab navigation - -### Requirement 6: Copy Event Data to Clipboard - -**User Story:** As a user, I want to copy event metadata values to my clipboard, so that I can easily share or paste event information into other applications. - -#### Acceptance Criteria - -1. WHEN the drawer displays the contract address, THE Event_Inspector SHALL provide a copy button adjacent to it -2. WHEN the drawer displays the event ID, THE Event_Inspector SHALL provide a copy button adjacent to it -3. WHEN the drawer displays the transaction hash, THE Event_Inspector SHALL provide a copy button adjacent to it -4. WHEN a user clicks a copy button, THE complete untruncated value SHALL be copied to the clipboard -5. WHEN a copy action succeeds, THE Drawer_Panel SHALL display a brief confirmation message (e.g., "Address copied") -6. WHEN a copy action fails, THE Drawer_Panel SHALL display an error message indicating the failure -7. THE copy confirmation message SHALL automatically dismiss after 1.5-2 seconds -8. WHEN a user copies a value, keyboard focus SHALL remain on the copy button - -### Requirement 7: Display Abbreviated Values with Full Value Context - -**User Story:** As a user, I want to see abbreviated values while being able to access the complete value, so that the drawer remains compact while providing full transparency. - -#### Acceptance Criteria - -1. WHEN a contract address or hash value is longer than 20 characters, THE Event_Inspector SHALL abbreviate it by showing first 10 characters + "..." + last 8 characters -2. WHEN a user hovers over an abbreviated value, THE tooltip SHALL display the complete unabbreviated value -3. WHEN an abbreviated value is displayed, THE Event_Inspector SHALL provide a copy button to copy the full value -4. WHEN an abbreviated value's tooltip is displayed, it SHALL remain visible for at least 1 second after the user stops hovering -5. WHEN abbreviating values, THE Event_Inspector SHALL use a consistent abbreviation pattern across all abbreviated fields -6. WHEN a value cannot be abbreviated (e.g., under 20 characters), THE Event_Inspector SHALL display the full value without abbreviation - -### Requirement 8: Support Multiple Content Sections - -**User Story:** As a user, I want the drawer to organize event information into logical sections, so that I can quickly find the information I need. - -#### Acceptance Criteria - -1. THE Drawer_Panel SHALL organize content into distinct sections (Sender Details, Blockchain Context, Event Payload, Status History) -2. EACH section SHALL have a visible section header with a title -3. THE Drawer_Panel SHALL display sections in a logical vertical order (metadata first, then payload, then status) -4. WHEN a section contains no data, THE Drawer_Panel MAY hide the section or display it with a "No data" message -5. WHEN a section contains many fields, THE Drawer_Panel SHALL maintain vertical scrolling to access all fields -6. EACH section SHALL have clear visual separation from other sections (e.g., borders, spacing, or background) - -### Requirement 9: Handle Missing or Null Event Data - -**User Story:** As a user, I want the drawer to gracefully handle missing event data, so that missing values don't break the interface. - -#### Acceptance Criteria - -1. WHEN an event property is null or undefined, THE Event_Inspector SHALL display a placeholder like "—" or "Not available" -2. WHEN the transaction hash is unavailable, THE Event_Inspector SHALL display a null indicator and not show the copy button for that field -3. WHEN event metadata is partially missing, THE Drawer_Panel SHALL still render all available information -4. WHEN the event payload is empty, THE Event_Inspector SHALL display the payload section with a message like "No payload data" -5. WHEN event timestamps are invalid or unparseable, THE Event_Inspector SHALL display the raw timestamp value with a note - -### Requirement 10: Provide Accessibility Features - -**User Story:** As a user with a screen reader, I want the drawer to announce its content and state clearly, so that I can understand the drawer and its information. - -#### Acceptance Criteria - -1. THE Drawer_Panel SHALL have the ARIA role "dialog" -2. THE Drawer_Panel SHALL have aria-modal="true" to indicate it is a modal -3. THE Drawer_Panel SHALL have a descriptive aria-label (e.g., "Event detail drawer for [event name]") -4. THE close button SHALL have aria-label="Close drawer" -5. WHEN the drawer opens, screen readers SHALL announce "Event details dialog opened" or similar -6. WHEN copy confirmation appears, THE Drawer_Panel SHALL use role="status" aria-live="polite" to announce the copy confirmation -7. WHEN errors occur, error messages SHALL use role="alert" to announce errors to screen readers -8. THE section headers SHALL use semantic heading tags (e.g.,

) to create a logical heading hierarchy -9. THE backdrop SHALL have aria-hidden="true" to prevent screen readers from reading it -10. EACH metadata row SHALL be clearly associated with its label (use
and
/
or