aitbc/docs/apps/explorer/simple-explorer.md

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

cd /opt/aitbc/apps/simple-explorer
.venv/bin/pip install -r requirements.txt

Configuration

Set environment variables in .env:

BLOCKCHAIN_RPC_URL=http://localhost:8006
CHAIN_ID=ait-mainnet
EXPLORER_PORT=8080

Running the Service

.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

# 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

GET /api/v1/explorer/block/{height}

Get Block by Hash

GET /api/v1/explorer/block/hash/{hash}

Get Latest Blocks

GET /api/v1/explorer/blocks/latest?limit=20

Transaction Viewing

Get Transaction by Hash

GET /api/v1/explorer/transaction/{hash}

Get Transactions by Address

GET /api/v1/explorer/transactions/address/{address}?limit=50

Get Latest Transactions

GET /api/v1/explorer/transactions/latest?limit=50

Address Viewing

Get Address Details

GET /api/v1/explorer/address/{address}

Get Address Balance

GET /api/v1/explorer/address/{address}/balance

Get Address Transactions

GET /api/v1/explorer/address/{address}/transactions?limit=50

Search

Search

GET /api/v1/explorer/search?q={query}

Search Blocks

GET /api/v1/explorer/search/blocks?q={query}

Search Transactions

GET /api/v1/explorer/search/transactions?q={query}

Search Addresses

GET /api/v1/explorer/search/addresses?q={query}

Statistics

Get Chain Statistics

GET /api/v1/explorer/stats

Get Network Status

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