BNW Scan

Table of Contents

1. Introduction
2. Overall Description
3. External Interface Requirements
4. System Features (Functional Requirements)
5. Non-Functional Requirements
6. Other Requirements
7. Appendices

1 – Introduction

1.1 Purpose

This SRS describes all functional and non-functional requirements for BNW Scan, an open-source blockchain explorer forked from Blockscout. It will guide developers, DevOps engineers, QA, product owners, and third-party integrators in implementing, testing, and deploying the explorer.

1.2 Scope

BNW Scan indexes and serves on-chain data from the BlockchainNW (EVM-compatible) network and any future testnets. Deliverables include:

• Core Indexer & API (Elixir/Phoenix micro-services + Rust verification service)
• Web UI (Next.js + Tailwind)
• Etherscan-compatible REST API
• GraphQL & WebSocket subscriptions
• Smart-contract verification service (Sourcify / Hardhat compatible)
• Admin & telemetry dashboards

Out-of-scope: generalised cross-chain explorers, non-EVM chains.

1.3 Definitions, Acronyms

• ERC-20 / ERC-721 / ERC-1155 – Token standards supported.
• PoSA – Proof-of-Staked-Authority consensus used by BlockchainNW.
• Indexer – Background service that streams blocks from full nodes and writes to PostgreSQL.
• Verification Service – Micro-service that rebuilds contract byte-code and matches it on-chain.

1.4 References

• Blockscout Documentation – Features & APIs
• IEEE 830-1998 – Software Requirements Specification standard.
• BlockchainNW Network SRS – v1.0 (27 Apr 2025)

1.5 Overview

Section 2 presents product context; Section 3 lists interfaces; Section 4 enumerates detailed features with acceptance criteria; Section 5 captures quality attributes; Section 6 covers compliance & deployment; Appendices provide data models and SLA tables.

2 – Overall Description

2.1 Product Perspective

BNW Scan is a downstream fork of Blockscout v5, customised for PoSA-specific data (validator set, slashing events) and branded UI. It runs as an independent micro-service set inside the overall BlockchainNW infrastructure.

2.2 Product Functions (high-level)

• Data Ingestion: stream, decode, normalise, and store blocks, transactions, logs, traces.
• Search: full-text & exact-match search across addresses, tx-hashes, blocks, ENS-style names.
• Visualisation: UI pages for blocks, tx, addresses, tokens, contracts, validator statistics, governance.
• Analytics: charts for gas price, TPS, token distribution, DEX volume, validator uptime.
• Developer Utilities: ABI-aware contract interaction (Read/Write), verification, API keys, rate-limiting.
• Admin: re-index, back-fill, node-health checks, Prometheus metrics.

2.3 User Classes & Characteristics

• End-Users: casual holders checking balances.
• Developers: dApp builders querying APIs.
• Validators: operators tracking uptime & penalties.
• Auditors/Analysts: need trace & label tools.
• Ops/Admin: maintain indexer, database, cache.

2.4 Operating Environment

• Backend: Elixir 1.16, OTP 26, Rust 1.79 micro-services; Docker/Kubernetes.
• Database: PostgreSQL 15 with TimescaleDB for metrics; Redis for caches.
• Nodes: ≥2 BlockchainNW full nodes (JSON-RPC, WebSocket) behind load-balancer.
• Browsers: Latest Chrome, Firefox, Edge, Safari, and mobile web.

2.5 Design & Implementation Constraints

• Must keep MIT licensing of upstream Blockscout modules.
• UI theming follows BlockchainNW design system.
• All secrets managed via Kubernetes Secrets & Vault.
• Supports both IPv4 & IPv6.

2.6 User Documentation

• Online docs at docs.bnwscan.com/scan (Sphinx-generated).
• Postman collection for REST API.
• OpenAPI 3.1 JSON schema for endpoints.

2.7 Assumptions & Dependencies

• Stable RPC endpoint availability (<1 s latency).
• PostgreSQL provisioned with ≥1 TB NVMe.
• Mail service (SendGrid) for watch-list notifications.
• External price oracle for fiat conversions.

3 – External Interface Requirements

3.1 User Interfaces

• Responsive web UI (desktop ≥1366 px, mobile ≥360 px) – dark/light.
• Modal contract interaction with MetaMask/WalletConnect.
• Admin UI (auth via GitHub OAuth + TOTP).

3.2 Hardware Interfaces

None (pure software).

3.3 Software Interfaces

Interface	Protocol	Description	Notes
JSON-RPC Proxy	HTTP/WebSocket	Pass-through to underlying node	Rate-limited
REST API (Etherscan style)	HTTPS	?module=account&action=balance etc.	Auth by API key
GraphQL	HTTPS/WebSocket	/graphql explorer IDE	Supports subscriptions
Verification API	HTTPS	Upload source, compiler params	Returns status/metadata
Prometheus	HTTP	/metrics endpoints	Use standard exporter ports

3.4 Communications Interfaces

• TLS 1.3 only, HSTS, ALPN http/2.
• WebSocket push for pending tx & new blocks (<250 ms lag).

4 – System Features (Functional Requirements)

Each feature includes ID, Description, Priority, Stimulus/Response, Acceptance Criteria.

4.1 Block Indexing (F-001)

Must ingest new blocks within 2 s of finality.
Given a new block event, system writes canonical row in blocks table and indexes receipts.
AC: After full sync, blocks.height always equals chain tip − ≤1.

4.2 Deep Search (F-002)

Users can paste address, tx-hash, block number, or ENS name into a single search box.
AC: Search returns result page in ≤300 ms p95.

4.3 Transaction Detail View (F-003)

Shows status, fee, gas price, traces, internal tx, decoded input.
AC: All ERC-20 transfers displayed in “Token Transfers” tab.

4.4 Address Dashboard (F-004)

Balance, nonce, token portfolio, NFTs, transaction list, labels, watch-list toggle.
AC: Adding address to watch-list triggers verification email.

4.5 Token Pages (F-005)

For ERC-20, ERC-721, ERC-1155: metadata, holders, transfers, total supply chart.
AC: “Holders” table paginates server-side and supports CSV export.

4.6 Contract Verification & Interaction (F-006)

Users can verify via UI upload, Hardhat plugin, or API; once verified, Read/Write tabs appear.
AC: Bytecode match algorithm returns verified == true when re-compiled hash equals on-chain code.

4.7 Validator & Governance Panels (F-007)

Custom to BlockchainNW: validator list, stake, uptime, slashing events; governance proposals read from chain.
AC: Validator uptime calculated over latest 10 000 blocks and colour-coded.

4.8 Analytics & Charts (F-008)

TPS, gas price heat-map, token volume, TVL (if AMM indexer enabled).
AC: Charts refresh with WebSocket ticks; no full-page reload.

4.9 API Key Management (F-009)

Logged-in users generate & revoke keys; per-key quota limits.
AC: Exceeding quota returns HTTP 429 with Retry-After.

4.10 Notifications (F-010)

Email / WebSocket alerts for watched addresses or contracts.
AC: Alert email sent within 30 s of matching event.

4.11 Admin Operations (F-011)

Re-index from block 0 or arbitrary height; toggle feature flags (NFT support, Gas tracker).
AC: Re-index status shows progress % and ETA.

5 – Non-Functional Requirements

Category	Requirement
Performance	Index new block ≤2 s; REST API p95 latency ≤200 ms under 2 000 rps.
Scalability	Horizontal scale via Kubernetes replicas; tested to 50 000 concurrent WebSocket connections.
Reliability	99.9 % monthly uptime (≤43 min downtime).
Security	OWASP Top-10 coverage; CSP, CSRF tokens, rate limiting, reCAPTCHA on auth; regular SCA scans.
Privacy	GDPR & Vietnamese PDPD compliance; no wallet keys stored.
Maintainability	Codebase adheres to Elixir Credo & Rust Clippy A levels; CI with full test suite.
Internationalisation	EN & VI locales at launch; i18n JSON message bundles.
Accessibility	WCAG 2.1 AA conformance for front-end.
Observability	Structured JSON logs, OpenTelemetry trace IDs, Prometheus metrics with Grafana dashboards.
Portability	Docker images run on x86-64 & ARM64; no host-specific dependencies.
Energy Efficiency	Auto-scaling infra; idle replicas scale down at <10 % CPU.
Upgradeability	Zero-downtime rolling deploy; DB migrations version-controlled.
Compliance & Auditability	Full audit trail of admin actions; chain-data immutably stored; monthly penetration test.

6 – Other Requirements

6.1 Legal & Licensing

Upstream Blockscout components remain MIT-licensed; custom modules licensed Apache 2.0 to align with broader BlockchainNW repos.

6.2 Deployment & Migration

• Helm chart bnw-scan defines StatefulSet for DB and Deployments for services.
• Blue-green rollout strategy with health probes.
• Data migration scripts provided for Blockscout → BlockchainNW schema deltas.

7 – Appendices

7.1 Database ER Diagram

• blocks, transactions, logs, traces, tokens, token_transfers, contracts, verification, validators, governance_events, user_notifications.

7.2 Service-Level Objectives (SLO)

Metric	Target	Measurement Window
API availability	≥99.9 %	30 days
Indexing lag	≤1 block	99th percentile
Search latency	≤300 ms	95th percentile

7.3 Open Issues

1. Evaluate integrated NFT image caching strategy (IPFS pinning vs Cloudflare R2).
2. Consider adding real-time mempool streaming micro-service.
3. Research WASM micro-front-end for plug-in analytics.