Skip to main content

BNW DEX

Table of Contents​

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

1 Introduction ​

1.1 Purpose​

This SRS specifies functional and non-functional requirements for BNW DEX, an Automated Market Maker (AMM) forked from Pancake Swap and running exclusively on the EVM layer of the BlockchainNW blockchain. Yield-farming contracts (MasterChef) are intentionally omitted to keep the protocol minimal and reduce smart-contract risk.

1.2 Scope​

  • Smart-contract suite: Factory, Router, Pair (LP) contracts, auxiliary libraries.
  • Front-end: Web DApp integrating with BNW Wallet, MetaMask, WalletConnect.
  • Back-end (optional): Indexer & analytics micro-services for charts, TVL, and on-chain event caching.
  • Governance hooks: Upgrade-safe parameter management controlled by the BlockchainNW DAO (future).

1.3 Definitions, Acronyms & Abbreviations​

TermDescription
AMMAutomated Market Maker
LPLiquidity-Pool token
DEXDecentralized Exchange
BNWNative token of the BlockchainNW ecosystem
EVMEthereum Virtual Machine

1.4 References​

  1. Pancake Swap core contracts v3.x
  2. BlockchainNW SRS (this wiki)
  3. ERC-20, ERC-2612 (permit) token standards

1.5 Overview​

This document describes the product architecture, detailed functional modules, user-interface constraints, quality attributes, and deployment considerations.

2 Overall Description ​

2.1 Product Perspective​

BNW DEX is a fork-adaptation of Pancake Swap with the following changes:

  • Hard-coded network ID & native token (BNW).
  • Lower block-time assumption (≈ 2 s).
  • Custom fee-distribution addresses (treasury, dev-fund, burn).
  • No liquidity-mining rewards; LPs earn trading fees only.

2.2 Product Functions (High-Level)​

  1. Token Swaps – constant-product AMM (x * y = k).
  2. Add / Remove Liquidity – mint & burn LP tokens.
  3. Analytics – pool TVL, volume, price charts.
  4. Fee Management – configurable protocol-fee split, optional buy-back-and-burn.
  5. Permissionless Listing – anyone may create a pair by paying a listing fee.

2.3 User Classes & Characteristics​

ClassDescription
TraderSwaps tokens; expects low slippage & clear price impact.
Liquidity ProviderSupplies tokens, earns 0.20 % swap fees.
DAO GovernorAdjusts protocol parameters through governance.
Developer/IntegratorBuilds third-party tools, bots, or mobile UIs.

2.4 Operating Environment​

  • Blockchain: BlockchainNW (EVM chain id = 0x1669 example).
  • Client: Modern browsers with Web3 injection or WalletConnect.
  • Node RPC: HTTPS/WSS endpoints; average latency < 300 ms.

2.5 Assumptions & Dependencies​

  • BlockchainNW mainnet finality ≤ 6 s.
  • Swap & liquidity functions fit within 6 M gas.
  • GPL-3 license compliance for forked code.

3 System Features & Functional Requirements ​

3.1 Factory Contract (F-1)​

  • F-1.1: Create new Pair deterministically via CREATE2.
  • F-1.2: Emit PairCreated with token addresses, pair address, index.
  • F-1.3: Allow fee-setter to update protocolFeeTo address.

3.2 Pair (LP) Contract (F-2)​

  • F-2.1: Provide swap, mint, burn, skim, sync identical to Pancake v2.
  • F-2.2: Implement permit (EIP-2612) for gas-less approvals.
  • F-2.3: Accrue 0.17 % fee to LPs, 0.03 % to protocolFeeTo.

3.3 Router Contract (F-3)​

  • F-3.1: Optimal routing across pairs; support multi-hop path arrays.
  • F-3.2: Deadline parameter to prevent front-running.
  • F-3.3: Provide swapExactTokensForTokens, swapTokensForExactTokens, addLiquidity, removeLiquidity, etc.

3.4 Front-End DApp (F-4)​

  • F-4.1: Connect to BNW Wallet / MetaMask; display balances, LP positions.
  • F-4.2: Real-time slippage calc & price-impact warnings.
  • F-4.3: Analytics dashboard (TVL, 24 h volume, top pools).
  • F-4.4: Internationalization (en, vi).

4 External Interface Requirements ​

4.1 User Interfaces​

  • Web: React + Next.js SPA, responsive ≥ 360 px width.
  • Mobile: Deep-link to BNW Wallet; QR WalletConnect URI.

4.2 Software Interfaces​

  • JSON-RPC 2.0: eth_call, eth_sendRawTransaction.
  • WebSocket: logs subscription for pool updates.
  • REST API (optional): cached analytics endpoints.

4.3 Communications Interfaces​

  • HTTPS TLS 1.3 for front-end; WSS for real-time feeds.
  • IPFS / Arweave hosting for static assets (optional).

5 Non-Functional Requirements ​

CategoryRequirement
PerformanceAvg. swap confirmation ≤ 6 s; front-end LCP < 2.5 s.
ScalabilityPool count tested up to 5 000 without gas regression.
Security2 independent audits; OpenZeppelin tests ≥ 90 % coverage.
AvailabilityFront-end CDN uptime ≥ 99.9 %; redundant RPC clusters.
MaintainabilityModular contracts; upgrade via factory-replace or proxy.
ComplianceGPL-3 license with NOTICE maintained.
LocalizationEnglish & Vietnamese UI strings.

6 Other Requirements ​

6.1 Deployment & DevOps​

  • Genesis settings include protocolFeeTo address.
  • Helm charts / Terraform modules for RPC & analytics.
  • CI/CD (GitHub Actions) runs forge test, slither, mythx.

6.2 Monitoring & Alerting​

  • Prometheus exporter (block height, tx rate, pool TVL).
  • Grafana dashboards; Slack alert on swap failure > 1 %.

6.3 Documentation​

  • Auto-generated Solidity NatSpec → Docsify site.
  • User guide pages in BlockchainNW docs portal.

6.4 Future Roadmap (Non-binding)​

  • v0.3: Optional ve-token gauge system if community later demands incentives.
  • v1.0: Cross-chain swap via BlockchainNW Bridge.

7 Appendices ​

A. Smart-Contract Address Map​

ContractAddress (mainnet)Address (testnet)
FactoryTBDTBD
RouterTBDTBD

B. Swap Flow Diagram​

User Tx → Router → Pair(s) → Factory (fee) → Event logs → Front-end updates

(Mermaid/UML diagram to be attached in a later revision.)