Move blockchain app READMEs to centralized documentation
Some checks failed
API Endpoint Tests / test-api-endpoints (push) Successful in 10s
Blockchain Synchronization Verification / sync-verification (push) Failing after 3s
CLI Tests / test-cli (push) Failing after 4s
Documentation Validation / validate-docs (push) Successful in 8s
Documentation Validation / validate-policies-strict (push) Successful in 4s
Integration Tests / test-service-integration (push) Successful in 38s
Multi-Node Blockchain Health Monitoring / health-check (push) Successful in 2s
P2P Network Verification / p2p-verification (push) Successful in 3s
Security Scanning / security-scan (push) Successful in 40s
Smart Contract Tests / test-solidity (map[name:aitbc-token path:packages/solidity/aitbc-token]) (push) Successful in 15s
Smart Contract Tests / lint-solidity (push) Successful in 8s

- Relocate blockchain-event-bridge README content to docs/apps/blockchain/blockchain-event-bridge.md
- Relocate blockchain-explorer README content to docs/apps/blockchain/blockchain-explorer.md
- Replace app READMEs with redirect notices pointing to new documentation location
- Consolidate documentation in central docs/ directory for better organization
This commit is contained in:
aitbc
2026-04-23 12:24:48 +02:00
parent cd240485c6
commit 522655ef92
55 changed files with 7033 additions and 1536 deletions

View File

@@ -0,0 +1,207 @@
# Simple Explorer
## Status
✅ Operational
## Overview
Simple blockchain explorer for viewing blocks, transactions, and addresses on the AITBC blockchain.
## Architecture
### Core Components
- **Block Viewer**: Displays block information and details
- **Transaction Viewer**: Displays transaction information
- **Address Viewer**: Displays address details and transaction history
- **Search Engine**: Searches for blocks, transactions, and addresses
- **Data Fetcher**: Fetches data from blockchain RPC
## Quick Start (End Users)
### Prerequisites
- Python 3.13+
- Access to blockchain RPC endpoint
- Web browser
### Installation
```bash
cd /opt/aitbc/apps/simple-explorer
.venv/bin/pip install -r requirements.txt
```
### Configuration
Set environment variables in `.env`:
```bash
BLOCKCHAIN_RPC_URL=http://localhost:8006
CHAIN_ID=ait-mainnet
EXPLORER_PORT=8080
```
### Running the Service
```bash
.venv/bin/python main.py
```
### Access Explorer
Open `http://localhost:8080` in a web browser to access the explorer.
## Developer Guide
### Development Setup
1. Clone the repository
2. Create virtual environment: `python -m venv .venv`
3. Install dependencies: `pip install -r requirements.txt`
4. Configure blockchain RPC endpoint
5. Run tests: `pytest tests/`
### Project Structure
```
simple-explorer/
├── src/
│ ├── block_viewer/ # Block viewing
│ ├── transaction_viewer/ # Transaction viewing
│ ├── address_viewer/ # Address viewing
│ ├── search_engine/ # Search functionality
│ └── data_fetcher/ # Data fetching
├── templates/ # HTML templates
├── static/ # Static assets
├── tests/ # Test suite
└── pyproject.toml # Project configuration
```
### Testing
```bash
# Run all tests
pytest tests/
# Run data fetcher tests
pytest tests/test_fetcher.py
# Run search engine tests
pytest tests/test_search.py
```
## API Reference
### Block Viewing
#### Get Block by Height
```http
GET /api/v1/explorer/block/{height}
```
#### Get Block by Hash
```http
GET /api/v1/explorer/block/hash/{hash}
```
#### Get Latest Blocks
```http
GET /api/v1/explorer/blocks/latest?limit=20
```
### Transaction Viewing
#### Get Transaction by Hash
```http
GET /api/v1/explorer/transaction/{hash}
```
#### Get Transactions by Address
```http
GET /api/v1/explorer/transactions/address/{address}?limit=50
```
#### Get Latest Transactions
```http
GET /api/v1/explorer/transactions/latest?limit=50
```
### Address Viewing
#### Get Address Details
```http
GET /api/v1/explorer/address/{address}
```
#### Get Address Balance
```http
GET /api/v1/explorer/address/{address}/balance
```
#### Get Address Transactions
```http
GET /api/v1/explorer/address/{address}/transactions?limit=50
```
### Search
#### Search
```http
GET /api/v1/explorer/search?q={query}
```
#### Search Blocks
```http
GET /api/v1/explorer/search/blocks?q={query}
```
#### Search Transactions
```http
GET /api/v1/explorer/search/transactions?q={query}
```
#### Search Addresses
```http
GET /api/v1/explorer/search/addresses?q={query}
```
### Statistics
#### Get Chain Statistics
```http
GET /api/v1/explorer/stats
```
#### Get Network Status
```http
GET /api/v1/explorer/network/status
```
## Configuration
### Environment Variables
- `BLOCKCHAIN_RPC_URL`: Blockchain RPC endpoint
- `CHAIN_ID`: Blockchain chain ID
- `EXPLORER_PORT`: Explorer web server port
- `CACHE_ENABLED`: Enable data caching
- `CACHE_TTL`: Cache time-to-live in seconds
### Display Parameters
- **Blocks Per Page**: Number of blocks per page (default: 20)
- **Transactions Per Page**: Number of transactions per page (default: 50)
- **Address History Limit**: Transaction history limit per address
### Caching
- **Block Cache**: Cache block data
- **Transaction Cache**: Cache transaction data
- **Address Cache**: Cache address data
- **Cache TTL**: Time-to-live for cached data
## Troubleshooting
**Explorer not loading**: Check blockchain RPC connectivity and explorer port.
**Data not updating**: Verify cache configuration and RPC endpoint availability.
**Search not working**: Check search index and data availability.
**Address history incomplete**: Verify blockchain sync status and data availability.
## Security Notes
- Use HTTPS in production
- Implement rate limiting for API endpoints
- Sanitize user inputs
- Cache sensitive data appropriately
- Monitor for abuse
- Regularly update dependencies