# krishankshh/nofeeswap architecture

> Architecture diagram of the GitHub repository krishankshh/nofeeswap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/krishankshh/nofeeswap
- Repository: https://github.com/krishankshh/nofeeswap

## Overview

1. This repo is a three-runtime local protocol environment: a React dApp in `frontend/`, a Hardhat-based local chain in `chain/`, and a TypeScript mempool/sandwich bot in `bot/`. The `core/` and `operator/` directories are not the live app; they are reference protocol implementations with heavy test coverage.

2. The primary user-facing boundary is the frontend. It is a React 19 + TypeScript + Vite app that routes between `Dashboard`, `Swap`, `Pool`, and `Liquidity` pages. The UI is split into reusable layout, wallet, pool, and transaction components, with stateful behavior concentrated in custom hooks.

3. Frontend chain access is centralized through `ethers.js v6` hooks and contract/config files. The app reads ABIs from `frontend/src/abis/`, contract addresses from `src/config/contracts.ts`, chain metadata from `src/config/chains.ts`, and token metadata from `src/config/tokens.ts`. This keeps UI components separate from Web3 plumbing.

4. Wallet integration is a distinct subsystem. `useWallet` and the wallet components manage MetaMask connect/disconnect, network detection, and chain switching. That wallet state feeds swap, pool, and liquidity flows, which then use transaction hooks for approve/submit/pending/confirmed/reverted lifecycle handling.

5. The local chain in `chain/` is the execution backend for the dApp and bot. It is a Hardhat network deployment with a deployment script that initializes test ERC-20s, deploys a `NofeeOperatorLike` contract, seeds a default pool, and writes addresses to `chain/deployments/localhost.json`.

6. `NofeeOperatorLike` is the on-chain contract boundary the frontend targets. In this assignment it stands in for the real NoFeeSwap operator interface, exposing pool initialization, swap, and liquidity management entry points. The frontend’s swap/liquidity pages are built against that interface, not against the underlying protocol internals.

7. The bot in `bot/` is a separate runtime that also targets the same local Hardhat chain. Its architecture is a pipeline: pending-transaction monitoring in `index.ts`, calldata parsing in `decoder.ts`, profitability estimation in `profitability.ts`, then front-run/back-run execution against the operator contract.

8. The bot and frontend share the same chain state but serve different roles. The frontend is an interactive client for a user with MetaMask, while the bot is an autonomous actor watching the mempool and submitting transactions based on decoded swap intent and estimated slippage/profit.

9. The `core/` and `operator/` directories are the protocol reference layer. They contain Solidity/Python test harnesses, Brownie/Hardhat configs, and Echidna fuzzing setups that validate the real NoFeeSwap logic. Architecturally, they inform the protocol model but are not part of the simplified local app runtime.

10. Data flow is therefore: user action in the React UI → wallet signature in MetaMask → ethers.js call through frontend hooks → Hardhat local contracts → updated on-chain state read back into the UI. In parallel, the bot consumes pending transactions from the same node, decodes them, and reacts before they are mined.

11. The most important diagram boundaries are: browser/UI, wallet provider, local blockchain node, deployed contracts, bot process, and reference protocol/test repos. A separate boundary worth noting is that several UI features, like the kernel editor and liquidity chart, are presentation-oriented and do not write the full NoFeeSwap kernel model on-chain in this simplified setup.

Main entry points: [`frontend/src/pages`](https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/pages) (Pages), [`frontend/src/hooks`](https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/hooks) (Web3 Hooks), [`chain/deployments/localhost.json`](https://github.com/krishankshh/nofeeswap/blob/main/chain/deployments/localhost.json) (Operator Contract), [`frontend/src/hooks/useWallet.tsx`](https://github.com/krishankshh/nofeeswap/blob/main/frontend/src/hooks/useWallet.tsx) (Wallet)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App Shell<br/>react-vite spa<br/>[App.tsx]"]
  node_frontend_pages["Pages<br/>user flows"]
  node_frontend_layout["Layout<br/>ui shell"]
  node_frontend_wallet["Wallet<br/>metamask integration<br/>[useWallet.tsx]"]
  node_frontend_web3["Web3 Hooks<br/>ethers v6 access"]
  node_frontend_config["Chain Config<br/>addresses and metadata"]
  node_frontend_components["UI Components<br/>reusable widgets"]
  node_frontend_pool_editor["Kernel Editor<br/>pool presentation<br/>[KernelEditor.tsx]"]
end

subgraph group_chain["Local Chain"]
  node_chain_deploy["Deploy Script<br/>hardhat deployment<br/>[deploy.ts]"]
  node_chain_network[("Hardhat Node<br/>local chain<br/>[hardhat.config.ts]")]
  node_chain_contract["Operator Contract<br/>on-chain boundary<br/>[localhost.json]"]
end

subgraph group_bot["Bot"]
  node_bot_entry["Mempool Watcher<br/>bot entrypoint<br/>[index.ts]"]
  node_bot_decoder["Calldata Parser<br/>tx decoding<br/>[decoder.ts]"]
  node_bot_profit["Profit Model<br/>profitability<br/>[profitability.ts]"]
  node_bot_exec["Trade Executor<br/>front-run/back-run<br/>[index.ts]"]
end

subgraph group_reference["Reference Protocol"]
  node_reference_core["Core Reference<br/>protocol model"]
  node_reference_operator["Operator Reference<br/>protocol model"]
end

node_frontend_app -->|"routes"| node_frontend_pages
node_frontend_app -->|"wraps"| node_frontend_layout
node_frontend_pages -->|"uses"| node_frontend_components
node_frontend_pages -->|"renders"| node_frontend_pool_editor
node_frontend_components -->|"consumes"| node_frontend_wallet
node_frontend_wallet -->|"drives"| node_frontend_web3
node_frontend_web3 -->|"reads"| node_frontend_config
node_frontend_web3 -->|"calls"| node_chain_contract
node_frontend_pages -->|"depends on"| node_frontend_wallet
node_frontend_pages -->|"reads state"| node_frontend_web3
node_chain_deploy -->|"deploys to"| node_chain_network
node_chain_deploy -->|"writes"| node_chain_contract
node_bot_entry -->|"pipes to"| node_bot_decoder
node_bot_decoder -->|"analyzes"| node_bot_profit
node_bot_profit -->|"signals"| node_bot_exec
node_bot_exec -->|"targets"| node_chain_contract
node_bot_entry -->|"observes"| node_chain_network
node_frontend_web3 -->|"connects to"| node_chain_network
node_reference_core -.->|"informs"| node_chain_contract
node_reference_operator -.->|"informs"| node_chain_contract
node_reference_core -.->|"complements"| node_reference_operator

click node_frontend_app "https://github.com/krishankshh/nofeeswap/blob/main/frontend/src/App.tsx"
click node_frontend_pages "https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/pages"
click node_frontend_layout "https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/components/layout"
click node_frontend_wallet "https://github.com/krishankshh/nofeeswap/blob/main/frontend/src/hooks/useWallet.tsx"
click node_frontend_web3 "https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/hooks"
click node_frontend_config "https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/config"
click node_frontend_components "https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/components"
click node_frontend_pool_editor "https://github.com/krishankshh/nofeeswap/blob/main/frontend/src/components/pool/KernelEditor.tsx"
click node_chain_deploy "https://github.com/krishankshh/nofeeswap/blob/main/chain/scripts/deploy.ts"
click node_chain_network "https://github.com/krishankshh/nofeeswap/blob/main/chain/hardhat.config.ts"
click node_chain_contract "https://github.com/krishankshh/nofeeswap/blob/main/chain/deployments/localhost.json"
click node_bot_entry "https://github.com/krishankshh/nofeeswap/blob/main/bot/src/index.ts"
click node_bot_decoder "https://github.com/krishankshh/nofeeswap/blob/main/bot/src/decoder.ts"
click node_bot_profit "https://github.com/krishankshh/nofeeswap/blob/main/bot/src/profitability.ts"
click node_bot_exec "https://github.com/krishankshh/nofeeswap/blob/main/bot/src/index.ts"
click node_reference_core "https://github.com/krishankshh/nofeeswap/tree/main/core"
click node_reference_operator "https://github.com/krishankshh/nofeeswap/tree/main/operator"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend_app,node_frontend_pages,node_frontend_layout,node_frontend_wallet,node_frontend_web3,node_frontend_config,node_frontend_components,node_frontend_pool_editor toneBlue
class node_chain_deploy,node_chain_network,node_chain_contract toneAmber
class node_bot_entry,node_bot_decoder,node_bot_profit,node_bot_exec toneMint
class node_reference_core,node_reference_operator toneRose
```

## Components

### Frontend

React dApp and UI runtime

- [App Shell](https://github.com/krishankshh/nofeeswap/blob/main/frontend/src/App.tsx): react-vite spa · Top-level React 19 + TypeScript client entry and routing shell · `frontend/src/App.tsx`
- [Pages](https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/pages): user flows · Dashboard, Swap, Pool, and Liquidity screens · `frontend/src/pages`
- [Layout](https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/components/layout): ui shell · Shared page chrome and navigation · `frontend/src/components/layout`
- [Wallet](https://github.com/krishankshh/nofeeswap/blob/main/frontend/src/hooks/useWallet.tsx): metamask integration · Connect, network detection, and chain switching · `frontend/src/hooks/useWallet.tsx`
- [Web3 Hooks](https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/hooks): ethers v6 access · Centralized contract, pool, balance, and transaction access · `frontend/src/hooks`
- [Chain Config](https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/config): addresses and metadata · ABI, contract, chain, and token metadata used by the UI · `frontend/src/config`
- [UI Components](https://github.com/krishankshh/nofeeswap/tree/main/frontend/src/components): reusable widgets · Wallet, pool, and transaction-facing interface components · `frontend/src/components`
- [Kernel Editor](https://github.com/krishankshh/nofeeswap/blob/main/frontend/src/components/pool/KernelEditor.tsx): pool presentation · Pool-oriented editing and visualization surface · `frontend/src/components/pool/KernelEditor.tsx`

### Local Chain

Hardhat execution backend and deployments

- [Deploy Script](https://github.com/krishankshh/nofeeswap/blob/main/chain/scripts/deploy.ts): hardhat deployment · Seeds tokens, deploys operator, initializes default pool, writes localhost addresses · `chain/scripts/deploy.ts`
- [Hardhat Node](https://github.com/krishankshh/nofeeswap/blob/main/chain/hardhat.config.ts): local chain · Local execution environment and deployment target · `chain/hardhat.config.ts`
- [Operator Contract](https://github.com/krishankshh/nofeeswap/blob/main/chain/deployments/localhost.json): on-chain boundary · NofeeOperatorLike entry point for pool, swap, and liquidity actions · `chain/deployments/localhost.json`

### Bot

Autonomous mempool trading runtime

- [Mempool Watcher](https://github.com/krishankshh/nofeeswap/blob/main/bot/src/index.ts): bot entrypoint · Monitors pending transactions and orchestrates the trading loop · `bot/src/index.ts`
- [Calldata Parser](https://github.com/krishankshh/nofeeswap/blob/main/bot/src/decoder.ts): tx decoding · Decodes pending swap intent into structured trade signals · `bot/src/decoder.ts`
- [Profit Model](https://github.com/krishankshh/nofeeswap/blob/main/bot/src/profitability.ts): profitability · Estimates slippage and execution profitability · `bot/src/profitability.ts`
- [Trade Executor](https://github.com/krishankshh/nofeeswap/blob/main/bot/src/index.ts): front-run/back-run · Submits reactions against the operator contract on the local chain · `bot/src/index.ts`

### Reference Protocol

Protocol model and verification harnesses

- [Core Reference](https://github.com/krishankshh/nofeeswap/tree/main/core): protocol model · Protocol implementation and extensive verification harnesses · `core`
- [Operator Reference](https://github.com/krishankshh/nofeeswap/tree/main/operator): protocol model · Operator-side reference implementation and tests · `operator`

## Connections

- App Shell → Pages: routes · App shell directs users to the main screens
- App Shell → Layout: wraps · Shared layout provides page chrome
- Pages → UI Components: uses · Pages compose reusable UI components
- Pages → Kernel Editor: renders · Pool page surfaces kernel editing and visualization
- UI Components → Wallet: consumes · Wallet UI reflects connect and network state
- Wallet → Web3 Hooks: drives · Wallet state feeds contract and transaction hooks
- Web3 Hooks → Chain Config: reads · Hooks resolve ABIs, addresses, chains, and tokens
- Web3 Hooks → Operator Contract: calls · ethers.js interactions target the deployed operator boundary
- Pages → Wallet: depends on · Swap, pool, and liquidity flows require active wallet state
- Pages → Web3 Hooks: reads state · UI reflects balances, pools, and transaction lifecycle
- Deploy Script → Hardhat Node: deploys to · Deployment script targets the local Hardhat chain
- Deploy Script → Operator Contract: writes · Deployment produces the local operator address record
- Mempool Watcher → Calldata Parser: pipes to · Watcher forwards pending transactions to decoder
- Calldata Parser → Profit Model: analyzes · Decoded trade data is scored for execution value
- Profit Model → Trade Executor: signals · Profitability output determines whether to trade
- Trade Executor → Operator Contract: targets · Execution leg submits transactions to the operator contract
- Mempool Watcher → Hardhat Node: observes · Bot watches the same local node as the frontend
- Web3 Hooks → Hardhat Node: connects to · UI reads and writes against the same local blockchain
- Core Reference → Operator Contract: informs · Core protocol model underlies the simplified operator boundary
- Operator Reference → Operator Contract: informs · Operator reference validates the contract behavior model
- Core Reference → Operator Reference: complements · The two reference trees cover protocol and operator perspectives