diff --git a/.kiro/specs/batch-notification-creation/.config.kiro b/.kiro/specs/batch-notification-creation/.config.kiro new file mode 100644 index 00000000..97ea20d3 --- /dev/null +++ b/.kiro/specs/batch-notification-creation/.config.kiro @@ -0,0 +1 @@ +{"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 new file mode 100644 index 00000000..65606031 --- /dev/null +++ b/.kiro/specs/batch-notification-creation/design.md @@ -0,0 +1,90 @@ +# 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 new file mode 100644 index 00000000..0e9c2f2a --- /dev/null +++ b/.kiro/specs/batch-notification-creation/requirements.md @@ -0,0 +1,75 @@ +# 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 new file mode 100644 index 00000000..bb1a7d92 --- /dev/null +++ b/.kiro/specs/batch-notification-creation/tasks.md @@ -0,0 +1,250 @@ +# 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 new file mode 100644 index 00000000..6a7b41d6 --- /dev/null +++ b/.kiro/specs/custom-error-types/.config.kiro @@ -0,0 +1 @@ +{"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 new file mode 100644 index 00000000..b9391324 --- /dev/null +++ b/.kiro/specs/custom-error-types/design.md @@ -0,0 +1,60 @@ +# 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 new file mode 100644 index 00000000..4166f9b4 --- /dev/null +++ b/.kiro/specs/custom-error-types/requirements.md @@ -0,0 +1,52 @@ +# 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 new file mode 100644 index 00000000..da6f4c0a --- /dev/null +++ b/.kiro/specs/custom-error-types/tasks.md @@ -0,0 +1,147 @@ +# 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 new file mode 100644 index 00000000..4757415b --- /dev/null +++ b/.kiro/specs/event-detail-drawer/.config.kiro @@ -0,0 +1 @@ +{"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 new file mode 100644 index 00000000..e69de29b diff --git a/.kiro/specs/event-detail-drawer/requirements.md b/.kiro/specs/event-detail-drawer/requirements.md new file mode 100644 index 00000000..36c2cb03 --- /dev/null +++ b/.kiro/specs/event-detail-drawer/requirements.md @@ -0,0 +1,227 @@ +# 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