How ankr-network/uscan works
Project Type and Purpose
• This project is a blockchain scanning tool designed for EVM-based networks. Its purpose is to scan and process blockchain data – blocks, transactions, contracts (including well-known EIPs like ERC20, ERC721, etc.) – along with syncing operations and “job” scheduling to continuously update the system state.
• The project is written in Go (evident from main.go, go.mod, and the “cmd” package) and supports both command-line usage (via the cmd folder) and a web-based interface (noted in the “web” directory with assets, HTML files, and JavaScript/CSS).
Analyzing the File Structure – Key Components
• Entry Points:
• cmd folder: Contains root.go, version.go – these define the CLI entry points.
• main.go: Likely serves as the main entry point for starting the application.
• Core Scanning and Sync Logic:
• pkg/core: Contains various “syncing” modules, each handling different aspects such as block syncing, contract syncing, account syncing, etc.
• pkg/job: Manages various jobs (e.g., sync jobs for blocks, transactions, internal transactions) which probably enable background task processing.
• Blockchain-Specific Modules:
• pkg/apis: Likely defines API interfaces and endpoints related to blockchain data.
• pkg/contract: Contains implementations for contract interactions (with several subdirectories for specific EIPs) that handle blockchain smart contract standards.
• pkg/rpcclient: Defines the RPC client for communicating with blockchain nodes.
• Data Persistence and Storage:
• pkg/kv with subdirectories (mdbx and memorydb): Provide key-value storage solutions.
• pkg/storage: Contains forkdb and fulldb modules responsible for persisting different views or indexes of the blockchain data.
• Utility and Support Libraries:
• pkg/utils, pkg/types, and pkg/response: Handle utility functions, type definitions (for block, transaction, account, etc.), and standardized response/error handling.
• pkg/log: Manages logging across the project.
• pkg/workpool: Implements a worker pool for job execution, ensuring that tasks are processed concurrently.
• Additional Components:
• “share” package: Likely holds shared variables or helper methods.
• “web” directory: Contains the front-end assets (JavaScript, CSS, HTML) which likely serve as the user interface for viewing the scan results.
• Deployment and configuration files: Dockerfile, docker-compose.yaml, Makefile, etc., indicate containerization and script-based build/deploy processes.
• Main Components to Represent:
• User Interface Layer: Include the “web” assets where end users interact.
• CLI / Service Entry: Represent the “cmd” layer (as a CLI or an API service start point).
• Core Processing Engine: This includes the “pkg/core” modules (syncing logic) and “pkg/job” (job scheduling) for processing blockchain data.
• Blockchain Interaction Layer: The “pkg/rpcclient” and “pkg/contract” components; these are responsible for connecting to blockchain nodes and handling smart contract interactions.
• Data Persistence Layer: Capture the “pkg/kv” and “pkg/storage” systems which handle long-term data storage, including forkdb and fulldb.
• API/Service Layer: The “pkg/apis” which expose blockchain scan data and may be consumed either by the UI or third-party integrations.
• Auxiliary Services: Logging from “pkg/log”, utility functions from “pkg/utils”, and worker management via “pkg/workpool.”
• Relationships & Data Flow:
• That the CLI/service entry (cmd/main.go) initializes the system which then launches the core sync engine to pull data from the blockchain via the RPC client.
• How the retrieved and processed data is stored in the persistence layer.
• That both the API layer and the web interface retrieve data from the persistence layer to present it to the user.
• Interactions between the job scheduler and the core syncing components, visualizing asynchronous processing.
• Architectural Patterns & Design Principles:
• Layered Architecture: Clear separation between the user interface, business logic, persistence, and external integration layers.
• Modular Design: Each “pkg” sub-package targets a specific functionality (for instance, separate modules for handling different EIPs).
• Asynchronous Processing: Represented by the job queues and worker pools (pkg/job and pkg/workpool).
• Containerization: Incorporate a note that Docker and docker-compose facilitate deployment and scalability.