BNW Wallet
1 Introduction
1.1 Purpose
BNW Wallet is the official cross-platform wallet (browser extension + mobile) for the BlockchainNW EVM-compatible blockchain.
This SRS defines the functional and non-functional requirements for MVP v1.0, targeting developers, testers, product owners, and security auditors.
1.2 Document conventions
- RFC 2119 keywords MUST, SHOULD, MAY.
- JSON fields are shown in camelCase.
- All times are UTC unless otherwise noted.
1.3 Intended audience & reading suggestions
| Role | Interest |
|---|---|
| Core-chain devs | Architecture & interface specs |
| Mobile / extension devs | UI flows & UX constraints |
| QA | Acceptance criteria & test cases |
| Security auditors | Threat model & crypto primitives |
| Ops / Release | Build, signing & update pipeline |
1.4 Product scope
BNW Wallet enables end-users to create and manage BNW accounts, sign transactions, interact with dApps, stake BNW, and participate in on-chain governance, while maintaining consumer-grade usability and enterprise-grade security.
1.5 References
- IEEE 830-1998 – Software Requirements Specification
- EIP-155, EIP-1559, EIP-712, EIP-1193, EIP-2612
- BIP-39 & BIP-44
- BNW Scan SRS v1.0 (2025-04-26)
2 Overall description
2.1 Product perspective
BNW Wallet is a purely client-side application that talks to BlockchainNW full-nodes over JSON-RPC/WebSocket, consumes explorer APIs for metadata, and exposes an EIP-1193 provider to dApps.
┌────────────┐ JSON‑RPC ┌──────────────┐
│ Wallet │◄─────────────────►│ BNW Node │
│(Ext/Mobile)│ WebSocket/HTTP(S) │(PoSA, EVM) │
└────────────┘ └──────────────┘
▲ ▲
│ └─► dApps – EIP‑1193 (browser) / WalletConnect v2 (mobile)
└────► BNW REST/GQL for token & NFT metadata (optional)
2.2 Product functions (high level)
- Key management – BIP-39 HD wallet, Ledger support, Secure Enclave/Keychain.
- Transaction flow – build, sign (EIP-155/EIP-1559), broadcast, history.
- Token & NFT dashboard – ERC-20/721/1155, auto-detect, custom import.
- dApp connector – in-page provider (extension) & WalletConnect v2 (mobile).
- Staking / Validator panel – delegate, claim rewards, un-bond, APR.
- Governance – create & vote proposals, result notifications.
- Security & Recovery – biometric/PIN unlock, anti-phishing phrase, auto-lock.
- Settings – custom RPC, gas presets, chain switch (testnet).
- Analytics opt-in – anonymous crash & usage telemetry.
2.3 User classes & characteristics
| Class | Description | Technical level |
|---|---|---|
| Retail user | Manage assets & stake | Low |
| Power user / Dev | Interact with dApps | Medium |
| Validator | Stake & monitor nodes | High |
| Governance participant | Propose & vote | Medium |
2.4 Operating environment
- Browser extension: Chrome ≥ 115, Firefox ≥ 120 (Manifest V3, Plasmo).
- Mobile: Flutter 3.x, Android ≥ 8.0, iOS ≥ 13 (arm64).
- Backend: none (client-side only). Optional push server (FCM/APNS).
2.5 Design & implementation constraints
- Audited cryptography libs: ethers-rs/ethers-js (extension), dart-ethereum (mobile).
- Secret keys MUST NOT leave device.
- Build pipelines reproducible; binaries signed with org certificates.
- GPL code MUST NOT contaminate the codebase (license Apache 2.0).
2.6 Assumptions & dependencies
- BlockchainNW mainnet chain ID 0x22B8 (8888 decimal).
- RPC endpoints HA with latency < 300 ms.
- BNW Scan provides
/token/{address}metadata.
3 External interface requirements
3.1 User interfaces
- Extension popup – account selector, balance, recent tx.
- Extension full-page – token list, NFT gallery, stake panel, settings.
- Mobile app – bottom-nav (Assets ▸ Explore ▸ Stake ▸ Governance ▸ Settings).
- Light/Dark theme, i18n (EN, VI), WCAG 2.1 AA contrast.
3.2 Hardware interfaces
Optional USB/BLE/HID for Ledger Nano X/S+; fallback U2F.
3.3 Software interfaces
| Interface | Standard | Notes |
|---|---|---|
| JSON-RPC | Ethereum JSON-RPC v1 | eth_sendRawTransaction, eth_feeHistory, … |
| WalletConnect | v2 | Mobile only |
| In-page provider | EIP-1193 | Exposes window.blockchainnw |
| Sign typed data | EIP-712 | Method eth_signTypedData_v4 |
| Permit | EIP-2612 | Gas-less approvals |
| Push | FCM/APNS | Topic /tx/{hash} (encrypted) |
3.4 Communications interfaces
All traffic MUST be HTTPS/WSS TLS 1.3; custom self-hosted RPC allowed with warning.
4 System features & functional requirements
Identifiers FR-x.y for traceability.
4.1 Key Management
- FR-1.1 Generate 12/24-word BIP-39 mnemonic (EN & VI wordlists).
- FR-1.2 Derive accounts
m/44'/8888'/0'/0/n. - FR-1.3 Import via hex key, JSON-keystore, or Ledger.
- FR-1.4 Encrypt seed with AES-256-GCM; unlock by PIN/biometric.
- FR-1.5 Secure “View Seed” with 2-step confirmation.
4.2 Transaction lifecycle
- FR-2.1 Estimate gas (EIP-1559) with presets Low/Market/Fast.
- FR-2.2 Show decoded tx (method, params, fees in BNW & USD).
- FR-2.3 Sign locally; broadcast; poll until CONFIRMED or timeout.
- FR-2.4 Speed-up/cancel (nonce-replacement).
- FR-2.5 Store ≥ 1 000 tx history per account, filterable.
4.3 Token & NFT management
- FR-3.1 Auto-detect ERC-20 via Transfer events; fetch logo.
- FR-3.2 Import custom token by address/decimals.
- FR-3.3 Render ERC-721/1155 thumbnails via IPFS gateway.
- FR-3.4 Send / batch-send NFTs.
4.4 dApp connectivity
- FR-4.1 Inject provider at
window.blockchainnw(EIP-1193). - FR-4.2 Connection prompt UI & origin whitelist.
- FR-4.3 Sign EIP-712 with human-readable preview.
- FR-4.4 WalletConnect v2 QR (mobile).
4.5 Staking & validator ops
- FR-5.1 Display validator list, commission, APR.
- FR-5.2 Delegate, un-delegate, claim rewards.
- FR-5.3 Show personal reward history, pending un-bond.
4.6 Governance
- FR-6.1 List proposals with quorum & countdown.
- FR-6.2 Create proposal (if thresholds met).
- FR-6.3 Vote For/Against/Abstain; show gas & lock time.
- FR-6.4 Push notice on result.
4.7 Security & anti-phishing
- FR-7.1 User-defined anti-phishing phrase on signing screens.
- FR-7.2 Auto-lock after idle (> 5 min default).
- FR-7.3 SRP-based password hashing (extension).
- FR-7.4 Daily-updated malicious URL block-list.
4.8 Settings & advanced
- FR-8.1 Switch mainnet/testnet (separate keystore).
- FR-8.2 Add custom RPC with chain-ID validation.
- FR-8.3 Toggle anonymous telemetry (payload preview).
- FR-8.4 Export encrypted vault; import on another device.
5 Non-functional requirements
| Category | ID | Requirement |
|---|---|---|
| Performance | NFR-1 | Sign + broadcast ≤ 1 s (p95 local). |
| Reliability | NFR-2 | Crash-free sessions ≥ 99.8 % (mobile, 30-day rolling). |
| Availability | NFR-3 | Optional push server SLA ≥ 99.9 %. |
| Security | NFR-4 | 0 critical & 0 high CVSS ≥ 7 findings in SAST/DAST. |
| Usability | NFR-5 | ≤ 2 taps from home to “Send” (mobile). |
| I18n | NFR-6 | English & Vietnamese; RTL-ready. |
| Accessibility | NFR-7 | WCAG 2.1 AA compliance. |
| Portability | NFR-8 | Extension works on x86_64 & ARM64; app on arm64 & simulator. |
| Maintainability | NFR-9 | Lint 0 errors, unit tests ≥ 70 % coverage. |
| Compliance | NFR-10 | GDPR & Vietnam PDPD – no PII without consent. |
6 Use-case overview
| ID | Title | Primary actor | Brief |
|---|---|---|---|
| UC-01 | Create wallet | New user | Generate seed, confirm words, set PIN |
| UC-02 | Send BNW | Retail user | Enter address/QR, amount, gas, confirm |
| UC-03 | Connect dApp | Power user | Site requests connection; user approves |
| UC-04 | Delegate stake | Validator | Choose validator, amount, sign tx |
| UC-05 | Vote proposal | Governance user | Open proposal, vote option, submit |
| UC-06 | Recover wallet | Any | Import mnemonic, validate checksum |
7 Other requirements
- Build & release – CI/CD via GitHub Actions; deterministic build; notarization (macOS) and Play App Signing.
- Telemetry – OpenTelemetry OTLP; user-controlled toggle.
- Threat model – STRIDE document maintained separately.
- App-store compliance – Google Play & Apple App Store crypto policies.
8 Appendices
8.1 Glossary
| Term | Definition |
|---|---|
| BlockchainNW | Permissionless EVM-compatible chain |
| BNW | Native currency (chain ID 0x22B8 / 8888) |
| PoSA | Proof-of-Staked-Authority consensus |
| dApp | Decentralised application |
| HD Wallet | Hierarchical Deterministic wallet (BIP-32/39/44) |
| EIP | Ethereum Improvement Proposal |
8.2 Open issues
- Hardware-wallet BLE support on mobile.
- EIP-4337 Account Abstraction (post-Q4 2025).
- Built-in swap UI deferred to v1.2.