1. Overview
The Blockchain Explorer UI dApp is a cyberpunk-themed blockchain visualization application designed for the GRIDNET OS decentralized operating system. It provides a comprehensive interface for exploring blockchain data, including blocks, transactions, and domains, with real-time updates and detailed data visualization.
This documentation outlines the architecture, data flow, and implementation details of the Blockchain Explorer UI dApp, with particular focus on its integration with the GRIDNET OS core systems.
2. System Architecture
The Blockchain Explorer UI dApp follows a layered architecture pattern with clear separation of concerns between UI rendering, business logic, and data access components.
2.1 High-Level Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Blockchain Explorer UI dApp │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ │ │ │ │ │ │
│ │ UI Layer │◄──►│ Business │◄──►│ Data Access Layer │ │
│ │ │ │ Logic Layer │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────┬───────────┘ │
└─────────────────────────────────────────────────┬───────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ CVMContext │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ API │ │ Event │ │ GridScript Command │ │
│ │ Interface │◄──►│ System │◄──►│ Processor │ │
│ └─────────────┘ └─────────────┘ └─────────┬───────────┘ │
└─────────────────────────────────────────────────┬───────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ WebSocket Connection │
└─────────────────────────────────┬───────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GRIDNET Decentralized Network │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Core Node 1 │◄──►│ Core Node 2 │◄──►│ Core Node n │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
2.2 Component Architecture
┌───────────────────────────────────────────────────────────────────────┐
│ CUIBlockchainExplorer (Main Class) │
│ ┌────────────────┐ ┌───────────────┐ ┌──────────────────────────┐ │
│ │ UI Components │ │Event Handlers │ │ Data Processors │ │
│ │ ┌────────────┐ │ │┌─────────────┐│ │┌────────────────────────┐│ │
│ │ │ Tables │ │ ││VMMetaData ││ ││processBlockData ││ │
│ │ └────────────┘ │ │└─────────────┘│ │└────────────────────────┘│ │
│ │ ┌────────────┐ │ │┌─────────────┐│ │┌────────────────────────┐│ │
│ │ │ Charts │ │ ││GridScript ││ ││processTransactionData ││ │
│ │ └────────────┘ │ │└─────────────┘│ │└────────────────────────┘│ │
│ │ ┌────────────┐ │ │┌─────────────┐│ │┌────────────────────────┐│ │
│ │ │ Details │ │ ││DFSMsg ││ ││processDomainData ││ │
│ │ └────────────┘ │ │└─────────────┘│ │└────────────────────────┘│ │
│ │ ┌────────────┐ │ │┌─────────────┐│ │┌────────────────────────┐│ │
│ │ │ Search │ │ ││SearchResults││ ││processSearchResults ││ │
│ │ └────────────┘ │ │└─────────────┘│ │└────────────────────────┘│ │
│ └────────────────┘ └───────────────┘ └──────────────────────────┘ │
│ │
│ ┌────────────────┐ ┌───────────────┐ ┌──────────────────────────┐ │
│ │ API Methods │ │ Cache System │ │ Controller Thread │ │
│ │ ┌────────────┐ │ │┌─────────────┐│ │┌────────────────────────┐│ │
│ │ │searchBlock-│ │ ││recentBlocks ││ ││mControlerThreadF ││ │
│ │ │chain │ │ │└─────────────┘│ │└────────────────────────┘│ │
│ │ └────────────┘ │ │┌─────────────┐│ │ │ │
│ │ ┌────────────┐ │ ││recentTX ││ │ │ │
│ │ │getBlock- │ │ │└─────────────┘│ │ │ │
│ │ │Details │ │ │┌─────────────┐│ │ │ │
│ │ └────────────┘ │ ││txStats ││ │ │ │
│ └────────────────┘ └───────────────┘ └──────────────────────────┘ │
└───────────────────────────────────────────────────────────────────────┘
3. Key Components
3.1 UI Layer
The UI layer is implemented as a responsive web interface using vanilla JavaScript, HTML5, and CSS3. It includes:
- Dashboard: Overview of blockchain statistics with charts and recent activity
- Blocks Explorer: Detailed listing and visualization of blockchain blocks
- Transactions Explorer: Search and view transaction details
- Domains Explorer: Search and display domain information
- Statistics Section: Advanced analytics and blockchain metrics
The UI is built with a cyberpunk theme featuring neon colors, dark backgrounds, and glowing elements. It’s fully responsive, adapting to different window sizes while maintaining usability.
3.2. Business Logic Layer
The business logic layer handles:
- Data transformation and formatting
- Search functionality
- API request coordination
- Event handling
- Error management
- Data caching
This layer sits between the UI and the data access layer, providing clean interfaces in both directions.
3.3. Data Access Layer
The data access layer interfaces with the GRIDNET OS CVMContext to:
- Request blockchain data
- Subscribe to blockchain events
- Process incoming event data
- Parse BER-encoded responses
This layer abstracts away the complexities of the underlying blockchain communication, providing simple, Promise-based interfaces to the business logic layer.
4. Communication Flow
4.1 Data Request Flow
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ UI Event │ │ API Method │ │ CVMContext │ │ GridScript │
│ (e.g., │───►│ Call │───►│ Method │───►│ Command │
│ search) │ │ │ │ │ │ │
└─────────────┘ └─────────────┘ └─────────────┘ └─────┬───────┘
│
┌────────────────────────────────────────────────────┐ │
│ Decentralized Network │◄─┘
└──────────────────────────┬─────────────────────────┘
│
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ UI Update │ │ Event │ │ VMMeta │ │ BER-Encoded │
│ │◄───│ Handler │◄───│ Callback │◄───│ Response │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
4.2 Event Registration and Processing
The Blockchain Explorer UI dApp registers for several event types:
┌─────────────────────────────────────────────────────────────────┐
│ CUIBlockchainExplorer Constructor │
└──────────────────┬──────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Event Registration │
│ │
│ ┌─────────────────────┐ ┌────────────────────────────────┐ │
│ │Standard Events │ │Blockchain-Specific Events │ │
│ │ │ │ │ │
│ │• VMMetaDataListener │ │• NewSearchResultsListener │ │
│ │• NewDFSMsgListener │ │• NewBlockDetailsListener │ │
│ │• GridScriptListener │ │• NewDomainDetailsListener │ │
│ │ │ │• NewTransactionDetailsListener │ │
│ │ │ │• BlockchainStatsListener │ │
│ └─────────────────────┘ └────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Event Handlers │
│ ┌─────────────────────────┐ ┌───────────────────────────────┐ │
│ │• newVMMetaDataCallback │ │• handleSearchResults │ │
│ │• newDFSMsgCallback │ │• handleBlockDetails │ │
│ │• newGridScriptResults │ │• handleDomainDetails │ │
│ │ │ │• handleTransactionDetails │ │
│ │ │ │• handleBlockchainStats │ │
│ └─────────────────────────┘ └───────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
5. Blockchain Explorer API Integration
5.1 CVMContext API Methods
The Blockchain Explorer UI dApp utilizes the following API methods provided by CVMContext:
| Method | Description | Parameters |
|---|---|---|
| getRecentTransactions | Retrieves recent blockchain transactions | size, page, threadID, processHandle, mode, reqID |
| getRecentBlocks | Retrieves recent blockchain blocks | size, page, sortBlocksByEnumVal, threadID, processHandle, mode, reqID |
| getTransactionDailyStats | Gets transaction statistics by day | days, threadID, processHandle, mode, reqID |
| getBlockchainStatus | Gets overall blockchain status | threadID, processHandle, mode, reqID |
| searchBlockchain | Searches for entities matching a query | query, size, page, flags, threadID, processHandle, mode, reqID |
| getNetworkUtilization24h | Gets network utilization over last 24 hours | threadID, processHandle, mode, reqID |
| getBlockSize24h | Gets average block size over last 24 hours | threadID, processHandle, mode, reqID |
| getBlockRewards24h | Gets average block rewards over last 24 hours | threadID, processHandle, mode, reqID |
| getAverageKeyBlockTime24h | Gets average key-block time over last 24 hours | threadID, processHandle, mode, reqID |
| getAverageBlockTime24h | Gets average block time over last 24 hours | threadID, processHandle, mode, reqID |
| getBlockDetails | Gets details for a specific block | blockID, includeTX, threadID, processHandle, mode, reqID |
| getDomainHistory | Gets transaction history for a domain | address, size, page, sortBy, threadID, processHandle, mode, reqID |
| getDomainDetails | Gets details for a domain | address, perspective, threadID, processHandle, mode, reqID |
| getTransactionDetails | Gets details for a transaction | transactionID, threadID, processHandle, mode, reqID |
| getLiveness | Gets the current blockchain liveness state | threadID, processHandle, mode, reqID |
| getUSDTPrice | Gets the current USDT price | threadID, processHandle, mode, reqID |
| getHeight | Gets the current blockchain height | isKeyHeight, threadID, processHandle, mode, reqID |
| subscribeToBlockchainUpdates | Subscribes to blockchain updates | N/A |
| unsubscribeFromBlockchainUpdates | Unsubscribes from blockchain updates | N/A |
5.2 Under the Hood: GridScript Command Processing
┌─────────────────────────────────────────────────────────────────┐
│ Data Request Process │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 1. UI dApp calls CVMContext.getBlockDetails(blockID, true, ...) │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 2. CVMContext formats a GridScript 'context' command: │
│ "context -c getBlockDetails -search <blockID> -tx" │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 3. Command is sent via WebSocket to a GRIDNET Core node │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 4. Core nodes process the command across the decentralized │
│ network using onion routing via QUIC connections │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 5. Resulting data is BER-encoded into a meta-data package │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 6. BER-encoded package is routed back to the requesting node │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 7. Data is sent to the UI dApp via WebSocket │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 8. CVMContext decodes the BER-encoded meta-data │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 9. CVMContext notifies UI dApp via registered event handlers │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│10. UI dApp processes the data and updates the UI │
└─────────────────────────────────────────────────────────────────┘
6. Data Processing Pipeline
6.1 Blockchain Object Processing
The UI dApp processes three main types of blockchain objects:
- CBlockDesc - Block descriptors
- CTransactionDesc - Transaction descriptors
- CDomainDesc - Domain descriptors
These objects are received as BER-encoded data and deserialized into their respective JavaScript classes. The UI dApp then uses specialized processing methods to extract and format the data for display:
┌─────────────────────────────────────────────────────────────────┐
│ Data Processing Sequence Diagram │
└─────────────────┬───────────────────────────────────────────────┘
│
▼
┌──────────────────────────┐ ┌─────────────────────────────────┐
│BER-Encoded Meta-Data │───►│CVMContext Deserializes into │
│from Network │ │Appropriate Object: │
└──────────────────────────┘ │• CBlockDesc │
│• CTransactionDesc │
│• CDomainDesc │
│• CSearchResults │
└──────────────┬──────────────────┘
│
▼
┌──────────────────────────┐ ┌─────────────────────────────────┐
│Object-specific Event │◄───│Event Notification │
│Handler: │ │ │
│• handleBlockDetails │ │ │
│• handleTransactionDetails│ │ │
│• handleDomainDetails │ │ │
│• handleSearchResults │ │ │
└──────────────┬───────────┘ └─────────────────────────────────┘
│
▼
┌──────────────────────────┐ ┌─────────────────────────────────┐
│Data Processing Methods: │───►│Processed Data Objects │
│• processBlockData │ │(JavaScript objects with:) │
│• processTransactionData │ │• Raw data │
│• processDomainData │ │• Formatted values │
│• processSearchResults │ │• UI-friendly properties │
└──────────────┬───────────┘ └─────────────┬───────────────────┘
│ │
└──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│UI Update Methods: │
│• displayBlockDetails │
│• displayTransactionDetails │
│• displayDomainDetails │
│• displaySearchResults │
└─────────────────────────────────────────────────────────────────┘
6.2 Search Functionality
The search function implements a smart detection system to determine what type of entity the user is searching for:
┌─────────────────────────────────────────────────────────────────┐
│ Search Flow Diagram │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│User Query Input │
└─────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│Query Analysis and Pattern Detection │
└────┬────────────────┬────────────────┬─────────────────────┬────┘
│ │ │ │
▼ ▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│Domain Name │ │64-Char Hex │ │Receipt ID │ │General │
│Pattern │ │Pattern │ │Pattern │ │Search │
│(Contains │ │(Block or │ │(30-40 bytes│ │(No specific│
│period) │ │Transaction)│ │or Base58) │ │pattern) │
└──────┬─────┘ └─────┬──────┘ └──────┬─────┘ └──────┬─────┘
│ │ │ │
▼ ▼ ▼ ▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│searchDomain│ │viewBlock │ │viewTX │ │searchBlock │
│API method │ │Details + │ │Details │ │chain API │
│ │ │viewTXDetail│ │ │ │method │
└──────┬─────┘ └─────┬──────┘ └──────┬─────┘ └──────┬─────┘
│ │ │ │
└──────────────┴────────────────┴────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│Display Results │
└─────────────────────────────────────────────────────────────────┘
7. Implementation Details
7.1 Object Class Integration
The UI dApp integrates with several key blockchain data classes:
- CBlockDesc - Represents a blockchain block with properties like height, transactions, miner, etc.
- CTransactionDesc - Represents a transaction with sender, receiver, value, etc.
- CDomainDesc - Represents a domain with balance, transaction history, etc.
- CSearchResults - Contains search results with visitor pattern for type-safe access
- ResultData - Variant-like object inside CSearchResults for type handling
The integration is done through specialized processing methods that ensure proper property access and error handling.
7.2 Real-time Updates
The Explorer implements real-time updates through:
- A controller thread that periodically refreshes data
- Blockchain update subscription for push notifications
- Event-based updates when specific data changes
┌─────────────────────────────────────────────────────────────────┐
│ Real-time Update Methods │
└─────────────────────────────────────────────────────────────────┘
│
┌───────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
┌────────────────┐ ┌────────────────┐ ┌────────────────┐
│Periodic Polling│ │Event-Driven │ │User-Triggered │
│ │ │Updates │ │Refresh │
│• Controller │ │ │ │ │
│ Thread │ │• Subscription │ │• Manual Refresh│
│• 10s Interval │ │• Event Handlers│ │• Search Actions│
└────────────────┘ └────────────────┘ └────────────────┘
7.3 Error Handling
The Explorer implements comprehensive error handling at multiple levels:
- Network-level error handling - For API call failures
- Data processing error handling - For malformed or unexpected data
- UI-level error handling - For user input validation and feedback
Errors are logged to the console with detailed information and displayed to the user in a user-friendly manner.
8. Optimization Techniques
8.1 Data Caching
The UI dApp implements a multi-level caching system to minimize network requests:
- In-memory cache for frequently accessed data (recent blocks, transactions)
- Local variable caching for UI-specific formatted data
- Memoization for expensive calculations
8.2 Lazy Loading
Data is loaded on demand to minimize initial load times:
- Section-specific data loading when user navigates to a section
- Pagination for large data sets
- Progressive loading of detailed information
8.3 UI Optimizations
- Efficient table updates via Tabulator.js
- Throttled chart rendering with Plotly.js
- DOM updates batched for better performance
- Hardware-accelerated CSS transitions
9. Future Enhancements
Potential future enhancements for the Blockchain Explorer UI dApp include:
- Advanced filtering and search capabilities
- Customizable dashboard with user-defined widgets
- Export functionality for blockchain data
- Visual transaction flow diagrams
- Dark/light theme toggle
- Deep linking for sharing specific blockchain views
- Historical data comparison tools
- Integration with block and transaction validators
10. Conclusion
The Blockchain Explorer UI dApp provides a comprehensive interface for exploring and understanding the GRIDNET blockchain. Its architecture ensures efficient data retrieval, processing, and visualization while maintaining a responsive and intuitive user experience.
The separation of concerns between UI, business logic, and data access layers allows for maintainability and future extensibility. The event-driven design enables real-time updates and efficient resource utilization.
By leveraging the GRIDNET OS CVMContext API and implementing proper blockchain data object handling, the Explorer provides a powerful tool for blockchain exploration while adhering to GRIDNET OS development guidelines.