Feature/singleton dex flash accounting

[maurievm]

BNBSwap - Smart DeFi Hub 🚀

Singleton DEX on BNB Chain with Flash Accounting and Native Limit Orders

BNBSwap combines Uniswap V2's simplicity with Uniswap V4's efficiency, adding unique features that make it the most gas-efficient and user-friendly DEX on BNB Chain.

🌟 Key Features

⚡ Flash Accounting

Save 33-44% gas on multi-hop swaps

Unlike traditional DEXes that transfer tokens on every hop, BNBSwap uses internal balance tracking (similar to Uniswap V4). Tokens only move at the end of the transaction, drastically reducing gas costs.

Example: A 3-hop swap (BNB → USDT → BTCB) uses ~56% less gas than traditional routing.

📊 Native Limit Orders

CEX-style limit orders on BNB Chain

Set "buy at X price" orders directly on-chain. Orders are automatically executed by keeper bots when the AMM price crosses your target.

• Non-Custodial: Funds remain in the contract but are reserved for the order.
• Gas-Free Cancellation: Cancel orders anytime before execution (standard gas fee applies).
• Auto-Execution: Incentivized keepers (0.1% fee) execute orders instantly when price is met.
• Smart Bot: Optimized keeper bot with caching and event listening included.

🏗️ Singleton Architecture

One contract to rule them all

All liquidity pools share a single contract, enabling:

• Gas-efficient multi-hop routing
• Native ETH/BNB support (no wrapping required)
• Simplified contract interactions and approvals

💰 Standard AMM

• Proven x*y=k formula
• 0.3% swap fee (0.25% to LPs, 0.05% to protocol/burn)
• Fair liquidity provision

📦 Project Structure

BNBSWAP/
├── contracts/          # Solidity smart contracts (Foundry)
│   ├── src/
│   │   ├── SingletonSwap.sol       # Main DEX contract
│   │   └── libraries/
│   │       ├── SwapMath.sol        # AMM math
│   │       └── FlashAccounting.sol # Delta tracking
│   └── test/           # Comprehensive tests (37/37 passing)
│
├── frontend/           # Next.js + wagmi + viem UI
│   └── src/
│       └── components/
│           ├── SwapCard.tsx        # Swap interface
│           ├── LiquidityCard.tsx   # LP management
│           └── LimitOrderCard.tsx  # Limit orders UI (Auto-approval flow)
│
└── bot/                # Order execution keeper bot
    ├── bot.js          # Optimized Node.js bot with caching
    └── README.md       # Bot setup guide

🚀 Quick Start

1. Contracts

cd contracts
forge build
forge test  # Runs all 37 tests

Deployment:

1. Copy .env.example to .env and add PRIVATE_KEY and BNB_TESTNET_RPC.
2. Run deployment script:

forge script script/Deploy.s.sol --rpc-url $BNB_TESTNET_RPC --broadcast

2. Frontend

cd frontend
npm install
cp .env.local.example .env.local 
# Add NEXT_PUBLIC_SINGLETON_SWAP_ADDRESS
npm run dev

3. Order Execution Bot

cd bot
npm install
cp .env.example .env
# Configure PRIVATE_KEY and SINGLETON_SWAP_ADDRESS
node bot.js

🧪 Test Results

37/37 tests passing ✅

We maintain strict 100% test coverage for critical paths:

• Flash Accounting: 8 tests (Settlement, Multi-hop, Native ETH)
• Limit Orders: 8 tests (Placement, Execution, Cancellation, Permissions)
• SingletonSwap: 16 tests (Liquidity, Swaps, Isolation, Registry, Edge Cases)
• Security: Specific tests for reentrancy and invalid inputs.

Run tests with trace:

forge test -vv

🔗 Deployed Addresses (BNB Testnet)

Contract	Address
SingletonSwap	0xBdae0CF292881D00520263f35E4450E72a818783
Mock USDT	0x323...
Mock BTCB	0x948...

🎯 Why BNBSwap?

1. Gas Efficiency: 33-44% savings vs standard DEXes via Flash Accounting.
2. Novel Features: Native limit orders on BNB Chain without off-chain relayers.
3. Complete Ecosystem: Fully integrated Contracts, Frontend, and Keeper Bot.
4. Production Ready: Comprehensive test suite (37 tests), robust error handling.
5. UX Focus: Auto-approval flows, detailed logging, and clean UI.

📚 Documentation

• Implementation Plan
• Walkthrough
• Bot Manual

🔧 Tech Stack

• Contracts: Solidity 0.8.20, Foundry
• Frontend: Next.js 14, TailwindCSS, wagmi, viem
• Bot: Node.js, ethers.js v6
• Network: BNB Smart Chain (Testnet/Mainnet)

📄 License

MIT

---

Built for BNB Chain Hackathon