BNW EVM

Table of Contents

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

1. Introduction

1.1 Purpose

This SRS defines the functional and non‑functional requirements for BlockchainNW—a permissionless, EVM‑compatible blockchain built atop the upstream geth (Go‑Ethereum) EVM core with Proof‑of‑Staked‑Authority (PoSA) consensus. The document intends to provide a single authoritative reference for developers, validators, auditors, DevOps engineers, product owners and any stakeholder involved in designing, implementing, testing, and operating the network.

1.2 Scope

BlockchainNW retains full compatibility with the Ethereum Virtual Machine (EVM) and all BEP‑20/ERC‑20/721 token standards while introducing custom governance, configurable staking parameters, and tighter on‑chain monitoring. The primary deliverables include:

• geth (core node daemon)
• geth (command‑line wallet & node tooling)
• Consensus contracts (PoSA)
• Staking & Governance dApps
• SDKs & API gateways (RPC, WebSocket, gRPC, GraphQL)
• Explorer & Indexer
• DevOps artifacts (Helm charts, Ansible playbooks, systemd units)

Out‑of‑scope: Layer‑2 rollups, non‑EVM execution, zero‑knowledge proofs (road‑mapped).

1.3 Definitions, Acronyms, and Abbreviations

Term	Definition
BEP‑20	Binance Smart Chain token standard, ERC‑20‑compatible.
PoSA	Proof‑of‑Staked‑Authority consensus—hybrid of PoS and PoA.
Validator	Node that applies consensus rules, produces blocks, and signs finality seals.
Full Node	Node that verifies every block & transaction but does not propose blocks.
Light Client	Client that checks block headers only.
RPC	Remote Procedure Call endpoint (JSON‑RPC 2.0).
EVM	Ethereum Virtual Machine—byte‑code execution environment.
Genesis	First block in the blockchain.

1.4 References

• Binance Smart Chain — Whitepaper v1.1
• Ethereum Yellow Paper – v2024 Edinburgh
• EIP‑1559 Fee Market Change
• IEEE‑830‑1998 SRS standard

1.5 Overview

Section 2 offers a high‑level view of system context; Section 3 details interface contracts; Section 4 enumerates every feature with acceptance criteria; Section 5 addresses quality attributes; Section 6 covers compliance, licensing, and migration; Appendices list genesis parameters and message schemas.

2. Overall Description

2.1 Product Perspective

BlockchainNW is implemented on the canonical geth 1.22 codebase enhanced with PoSA modules and preserves fast finality (~3 s block time) and low fees while introducing:

• Parametric block gas limit adjustable via on‑chain governance.
• Upgradeable consensus contracts enabling future algorithm changes without hard‑fork.
• Extended telemetry (Prometheus metrics, OpenTelemetry traces).
• Native staking rewards distributed every epoch (≈200 blocks).

2.2 Product Functions

1. Network bootstrap – generate genesis.json, allocate initial balances, set validator set.
2. Block production & validation – implement Clique‑style epoch and step timers; verify seals.
3. EVM execution – run Berlin‑plus op‑codes, support London EIP‑1559.
4. Transaction pool – maintain mempool, prioritize by effective gas price, prune invalid txs.
5. State pruning – implement ancient‑storage to archive state roots older than --prune=N blocks.
6. Cross‑chain bridge hooks – emit events for relayers (future BEP‑100 cross‑chain). … (Complete list in Section 4)

2.3 User Classes and Characteristics

Class	Description	Technical Expertise
Validator Operator	Runs validator nodes, stakes native BNW, participates in governance.	DevOps, security‑hardened Linux
Full‑Node Operator	Mirrors blockchain state, offers RPC endpoints.	Intermediate
dApp Developer	Deploys smart contracts, builds front‑ends.	Solidity/Rust
End User	Uses wallet to transfer tokens, interact with dApps.	Basic

2.4 Operating Environment

• Target OS: Ubuntu 22.04 LTS (containers) and Alpine 3.19.
• CPU: x86‑64 (AVX2) & ARM64.
• Memory: ≥16 GB RAM for validators; ≥8 GB for full nodes.
• Storage: NVMe SSD ≥1 TB @ 2 k IOPS.
• Network: ≥100 Mbps symmetric with <100 ms RTT to majority peers.

2.5 Design and Implementation Constraints

• Must compile with Go 1.22.x.
• Must be Apache‑2.0 licensed.
• Genesis cannot exceed 4 million accounts due to initial state size.
• Consensus changes require ⅔ validator signatures plus ⅔ governance vote.

2.6 User Documentation

• Validator Handbook (markdown & PDF)
• Developer Portal (Docusaurus site)
• Swagger/OpenAPI specs for REST endpoints.

2.7 Assumptions and Dependencies

• Chain ID is 8888 (hex 0x22B8).
• BNW total supply is minted at genesis.
• R&D budget allows 5 FTE developers for 12 months.

3. External Interface Requirements

3.1 User Interfaces

• BlockchainNW Wallet – web & mobile wallets
• Explorer UI – React + Next.js, real‑time WebSocket updates.

3.2 Hardware Interfaces

Not applicable—runs on commodity servers.

3.3 Software Interfaces

Interface	Protocol	Spec/Version
JSON‑RPC	HTTP 1.1 / WebSocket	eth_*, net_*, bnw_get*
gRPC	Proto3	Node service definitions
Prometheus	HTTP	/metrics endpoint
P2P	libp2p‑derived	DEVp2p v5

3.4 Communications Interfaces

• TCP 30303/UDP 30303 for P2P.
• TLS‑enabled RPC port 8545.
• WebSocket port 8546.

4. System Features

Each feature includes Description, Stimulus/Response, Functional Requirements (FR‑x).

4.1 Genesis Initialization

Description: The system must accept a genesis file conforming to canonical geth genesis schema and initialize state accordingly.

• FR‑01: geth init --genesis genesis.json SHALL validate schema and hash values.
• FR‑02: The tool SHALL create keystore directories and copy static nodes.

4.2 Proof‑of‑Staked‑Authority Consensus

• FR‑03: Validators SHALL rotate proposer order every epoch using deterministic round‑robin.
• FR‑04: Block time target SHALL be 3 s (configurable ±1 s tolerance).
• FR‑05: Double‑signing SHALL be detected; offending validator is slashed 50 % stake and jailed for 1 week (604 800 s).

4.3 EVM Execution Engine

• FR‑06: Support opcode set up to EVM “Cancun” hard‑fork (EIP‑4844 blobs optional, flagged off by default).
• FR‑07: Gas price SHALL follow EIP‑1559 with base‑fee elasticity of ±12.5 % per block.

4.4 Staking Module

• FR‑08: Users SHALL delegate BNW to validators via staking smart contract.
• FR‑09: Rewards SHALL be distributed proportionally every epoch minus 3 % protocol fee.
• FR‑10: Unbonding period SHALL be 7 days (604 800 s).

4.5 Governance Module

• FR‑11: Any account with ≥ 10 000 BNW bonded stake MAY submit proposal.
• FR‑12: Voting period SHALL last 7 days; 1 BNW = 1 vote weight.
• FR‑13: Proposal passage requires ≥ 50 % quorum and ≥ 50 % “Yes”.

4.6 RPC & API Services

• FR‑14: Node SHALL expose JSON‑RPC endpoints compliant with eth‑namespace.
• FR‑15: Maximum batch size of 1 000 requests; exceeding returns HTTP 413.

4.7 Telemetry & Monitoring

• FR‑16: All nodes SHALL export Prometheus metrics <15 s scrape interval.
• FR‑17: Critical alerts (block lag >9 s, peers <10) SHALL be sent to OpsPager webhook.

4.8 Cross‑Chain Bridge Compatibility

Description: Provide hooks and event schemas compatible with Binance Bridge for BEP‑2⇄BNW transfers.

• FR‑18: Node SHALL emit BridgeTransfer(address token, bytes32 toChain, … ) events on finalized blocks.
• FR‑19: Canonical bridge contract address SHALL be configurable via governance proposal.
• FR‑20: Relayer whitelist SHALL be stored on‑chain and updateable.

4.9 Validator Set Management

Description: Dynamically update validator set via governance and slashing module.

• FR‑21: Candidate validator MUST stake ≥ 100 000 BNW to join set.
• FR‑22: Validator set size SHALL auto‑expand up to 50 nodes when total stake > 500 M BNW.
• FR‑23: geth SHALL refresh validator list every epoch reading contract storage.

4.10 State Synchronization & Fast‑Sync

Description: Support BSC fast‑sync and snapshot sync for rapid bootstrap.

• FR‑24: Fast‑sync target snapshot height SHALL trail head by ≤ 2 000 blocks.
• FR‑25: Snapshot files MUST be chunked ≤ 512 MiB to ease transport.

4.11 EVM Pre‑compile Extensions

Description: Include extended EVM pre‑compiles (e.g., 0x65 Blake2b, 0x66 Sha512, 0x67 Secp256r1).

• FR‑26: Gas schedule for each pre‑compile SHALL match the reference gas schedule values.
• FR‑27: Pre‑compile addresses are reserved and non‑re‑deployable.

4.12 Panic Mode (Chain Halt)

Description: Emergency validator consensus message to stop block production.

• FR‑28: ≥ ⅔ validators signing HaltMsg SHALL freeze chain at height H.
• FR‑29: Unfreeze requires governance proposal with ≥ ⅔ quorum.

4.13 Hard‑Fork Governance

Description: Fork‑choice changes managed through on‑chain vote rather than manual config.

• FR‑30: geth SHALL auto‑activate hard‑fork when contract flag forkId toggles to active.
• FR‑31: Node that refuses fork SHALL disconnect peers with mismatched forkId.

4.14 Transaction Trace & Debug API

Description: Provide parity‑style trace_* RPC for debuggers.

• FR‑32: Trace API MUST be disabled by default; enabling requires --rpc.trace.
• FR‑33: Trace result depth limit default 10 calls; configurable.

4.15 Oracle Price Feed Module

Description: On‑chain price feed aggregated from multiple oracles.

• FR‑34: Medianizer contract SHALL accept 7 reporters and compute median price.
• FR‑35: Invalid reporter (off by > 10 %) penalized 1 BNW per incident.

5. Non‑Functional Requirements

5.1 Performance

• NFR‑01: Network must finalize 95 % of blocks within 6 s.
• NFR‑02: Transactions throughput ≥150 TPS (simple transfers) under benchmark load.

5.2 Scalability

• NFR‑03: System shall support ≥100 validators and ≥20 000 full nodes without protocol changes.

5.3 Security

• NFR‑04: All RPC endpoints must support JWT‑based authentication when --auth flag used.
• NFR‑05: Private keys stored in HSM or encrypted keystore (PBKDF2, 600K iterations).
• NFR‑06: Compliance with OWASP TOP 10 for explorer and wallets.

5.4 Reliability & Availability

• NFR‑07: Validators target 99.5 % monthly availability.
• NFR‑08: Node crash recovery must not exceed 5 minutes with fast‑sync.

5.5 Maintainability

• NFR‑09: Codebase must reach ≥80 % unit‑test coverage.
• NFR‑10: CI/CD pipeline shall complete <10 minutes per commit.

5.6 Portability

• NFR‑11: Containers must run on x86‑64 and ARM64 without modification.
• NFR‑12: Source builds reproducible via docker build . on any Linux distro.

5.7 Internationalization & Localization

• NFR‑13: Wallet UI must support i18n (English default, Vietnamese, Spanish).

5.8 Interoperability

• NFR‑14: Smart contracts compiled for Ethereum/BSC mainnet SHALL deploy on BlockchainNW without source modifications.
• NFR‑15: ABI‑compatible RPC ensures existing tooling (Hardhat, Truffle, Foundry) works out‑of‑box.

5.9 Regulatory Compliance & Auditability

• NFR‑16: All contract byte‑code and metadata published to verified source repository.
• NFR‑17: Chain activity logs retained ≥ 7 years for compliance.

5.10 Energy Efficiency

• NFR‑18: Average validator CPU utilization < 30 % at 150 TPS benchmark.

5.11 Upgradeability & Backward Compatibility

• NFR‑19: Minor protocol upgrades MUST keep block gas limit invariant.
• NFR‑20: Node binary MUST support replaying historical chain from genesis.

5.12 Observability

• NFR‑21: 100 % of critical paths instrumented with OpenTelemetry spans.
• NFR‑22: P99 RPC latency ≤ 250 ms under 100 req/s load.

6. Other Requirements

6.1 Legal & Regulatory

• Must comply with FinCEN Travel Rule for transfers ≥US$3000 (via TravelRule contract).
• GDPR‑compliant privacy notice for explorer user data.

6.2 Licensing

• All original source code licensed under Apache 2.0.
• Forked BSC code retains original GPL‑3.0; dual‑licensing managed via modular separation.

6.3 Deployment & Migration

• MVP network shall launch testnet by 2025‑07‑31 and mainnet by 2025‑10‑31.
• Snapshot & state‑sync mechanism for rapid node bootstrapping.

7. Appendices

7.1 Genesis Parameters

Field	Value
chainId	8888 (0x22B8)
homesteadBlock	0
eip1559Block	0
clique period	3
clique epoch	200
gasLimit	30000000

7.1.1 Full genesis.json template

{
  "config": {
    "chainId": 8888,
    "homesteadBlock": 0,
    "eip1559Block": 0,
    "clique": {
      "period": 3,
      "epoch": 200
    }
  },
  "difficulty": "0x1",
  "gasLimit": "0x1C9C380",
  "extradata": "0x<32‑bytes vanity><list of validator addresses padded to 65 bytes><random>
                 (initial validator seals appended after genesis creation)",
  "alloc": {
    "0x0000000000000000000000000000000000000000": { "balance": "0" },
    "0xAAAA…": { "balance": "100000000000000000000000000" }
  }
}

• config – chain rules and hard‑fork heights.
• difficulty – must be 0x1 for PoSA chains.
• extradata – 32‑byte vanity + validator list; size = 32 + validatorCount × 20 + 65.
• alloc – pre‑funded accounts and system contract balances (staking, governance).

7.1.2 Allocation conventions

Account	Purpose	Balance
StakingContract	Bond/unbond BNW	0 (minted on stake)
GovernanceTreasury	Proposal deposits & slashing	0
TeamVesting	4‑year linear vesting	200 M BNW

7.2 PoSA State Transition Model

Validator lifecycle states:

State	Description	Entered by	Exits to
Bonded	Candidate has ≥100 000 BNW staked but not yet active	bond()	Active, Unbonding
Active	Participates in proposer rotation	epochRotate()	Jailed, Unbonding
Jailed	Temporarily removed due to slash/downtime	slash()	Active after jail time
Unbonding	Stake locked for 7 days	unbond()	Exited
Exited	Funds withdrawn	withdraw()	—

Transition Function T(s, e) → sʼ:

if e == Slash && s == Active  => Jailed
if e == UnbondReq && s ∈ {Bonded, Active} => Unbonding
if e == EpochEnd && s == Bonded && stake ≥ MinStake => Active
…

Epoch Processing (every 200 blocks):

1. Gather proposer set.
2. Re‑sort by stake weight.
3. Emit ValidatorSet(address[] newSet) event.

7.3 Epoch & Step Timing Logic

• Step (block interval): 3 s target.
• Epoch: 200 blocks ≈ 600 s.
• Intra‑Step timings:
  • Propose  ≤ 1 s
  • Prevote  ≤ 1 s
  • Commit  ≤ 1 s

Node pseudo‑code:

for step := 0; ; step++ {
    if isProposer(step) {
        proposeBlock()
    }
    collectPrevotes()
    if quorumReached() { commit() }
    time.Sleep(3 * time.Second)
}

7.4 Message Schemas

• StakeMsg – stake(address validator, uint256 amount)
• VoteMsg – vote(uint256 proposalId, bool support)

7.5 Open Issues

1. Decide on blob‑transaction support (EIP‑4844) before mainnet.
2. Evaluate integration with IBC for cross‑chain transfers.