# johngrantuk/balancerbot architecture

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

- Interactive diagram: https://gitdiagram.com/johngrantuk/balancerbot
- Repository: https://github.com/johngrantuk/balancerbot

## Overview

This repository’s product is an off-chain Ethereum arbitrage bot backed by an atomic on-chain executor. The principal workflow reads exchange prices, compares Kyber’s ETH-to-token quote with Uniswap’s token-to-ETH rate, prepares token approval and trade calls, then submits a trade through the executor. The README documents the executor’s all-or-nothing two-leg swap. The React client appears to be an unrelated Truffle starter example, so it is not included. Contract internals are represented from README descriptions because their source was not sampled.

Main entry points: [`main.js`](https://github.com/johngrantuk/balancerbot/blob/master/main.js) (Bot runner), [`contracts/KyberUniArbContract.sol`](https://github.com/johngrantuk/balancerbot/blob/master/contracts/KyberUniArbContract.sol) (Atomic arbitrage executor), [`contracts/UniswapExchange.sol`](https://github.com/johngrantuk/balancerbot/blob/master/contracts/UniswapExchange.sol) (Uniswap exchange), [`contracts/ERC20Token.sol`](https://github.com/johngrantuk/balancerbot/blob/master/contracts/ERC20Token.sol) (ERC20 token)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bot["Bot and pricing"]
  node_main["Bot runner<br/>[main.js]"]
  node_pricecheck["Rate comparison<br/>[main.js]"]
end

subgraph group_execution["Trade execution"]
  node_approval["Approval flow<br/>[main.js]"]
  node_tradebuild["Trade preparation<br/>[main.js]"]
  node_txsubmit["Transaction submission<br/>[main.js]"]
  node_arb["Atomic arbitrage executor"]
end

subgraph group_protocols["Exchange protocols"]
  node_kyberquote["Kyber quote client<br/>[main.js]"]
  node_uniswapmarket["Uniswap market client<br/>[main.js]"]
  node_kyberproxy["Kyber proxy"]
  node_uniswap["Uniswap exchange"]
end

subgraph group_assets["Token assets"]
  node_token["ERC20 token<br/>[ERC20Token.sol]"]
end

node_operator(("Bot operator"))
node_rpc[("Ethereum RPC")]
node_network["Kyber Network"]
node_uniswapnet["Uniswap protocol"]

node_operator -->|"starts"| node_main
node_main -->|"checks approval"| node_approval
node_main -->|"checks rates"| node_pricecheck
node_pricecheck -->|"requests quote"| node_kyberquote
node_pricecheck -->|"reads market"| node_uniswapmarket
node_kyberquote -->|"queries rates"| node_network
node_uniswapmarket -->|"reads reserves"| node_uniswapnet
node_approval -->|"calls approval"| node_arb
node_approval -->|"checks allowance"| node_token
node_approval -->|"gets exchange"| node_uniswap
node_main -->|"prepares trade"| node_tradebuild
node_tradebuild -->|"gets execution details"| node_uniswapmarket
node_main -->|"submits trade"| node_txsubmit
node_txsubmit -->|"sends transaction"| node_arb
node_txsubmit -->|"broadcasts signed transaction"| node_rpc
node_arb -->|"swaps via Kyber"| node_kyberproxy
node_arb -->|"swaps via Uniswap"| node_uniswap
node_arb -->|"trades ERC20"| node_token

click node_main "https://github.com/johngrantuk/balancerbot/blob/master/main.js"
click node_pricecheck "https://github.com/johngrantuk/balancerbot/blob/master/main.js"
click node_kyberquote "https://github.com/johngrantuk/balancerbot/blob/master/main.js"
click node_uniswapmarket "https://github.com/johngrantuk/balancerbot/blob/master/main.js"
click node_approval "https://github.com/johngrantuk/balancerbot/blob/master/main.js"
click node_tradebuild "https://github.com/johngrantuk/balancerbot/blob/master/main.js"
click node_txsubmit "https://github.com/johngrantuk/balancerbot/blob/master/main.js"
click node_arb "https://github.com/johngrantuk/balancerbot/blob/master/contracts/KyberUniArbContract.sol"
click node_kyberproxy "https://github.com/johngrantuk/balancerbot/blob/master/contracts/KyberNetworkProxy.sol"
click node_uniswap "https://github.com/johngrantuk/balancerbot/blob/master/contracts/UniswapExchange.sol"
click node_token "https://github.com/johngrantuk/balancerbot/blob/master/contracts/ERC20Token.sol"

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_main,node_pricecheck toneBlue
class node_approval,node_tradebuild,node_txsubmit,node_arb,node_rpc toneAmber
class node_kyberquote,node_uniswapmarket,node_kyberproxy,node_uniswap toneMint
class node_token toneRose
class node_operator,node_network,node_uniswapnet toneIndigo
```

## Components

### Bot and pricing

- [Bot runner](https://github.com/johngrantuk/balancerbot/blob/master/main.js): `main.js`
- [Rate comparison](https://github.com/johngrantuk/balancerbot/blob/master/main.js): `main.js`

### Trade execution

- [Approval flow](https://github.com/johngrantuk/balancerbot/blob/master/main.js): `main.js`
- [Trade preparation](https://github.com/johngrantuk/balancerbot/blob/master/main.js): `main.js`
- [Transaction submission](https://github.com/johngrantuk/balancerbot/blob/master/main.js): `main.js`
- [Atomic arbitrage executor](https://github.com/johngrantuk/balancerbot/blob/master/contracts/KyberUniArbContract.sol): `contracts/KyberUniArbContract.sol`

### Exchange protocols

- [Kyber quote client](https://github.com/johngrantuk/balancerbot/blob/master/main.js): `main.js`
- [Uniswap market client](https://github.com/johngrantuk/balancerbot/blob/master/main.js): `main.js`
- [Kyber proxy](https://github.com/johngrantuk/balancerbot/blob/master/contracts/KyberNetworkProxy.sol): `contracts/KyberNetworkProxy.sol`
- [Uniswap exchange](https://github.com/johngrantuk/balancerbot/blob/master/contracts/UniswapExchange.sol): `contracts/UniswapExchange.sol`

### Token assets

- [ERC20 token](https://github.com/johngrantuk/balancerbot/blob/master/contracts/ERC20Token.sol): `contracts/ERC20Token.sol`

### Other components

- **Bot operator**
- **Ethereum RPC**
- **Kyber Network**
- **Uniswap protocol**

## Connections

- Bot operator → Bot runner: starts (evidence: `main.js`)
- Bot runner → Approval flow: checks approval (evidence: `main.js`)
- Bot runner → Rate comparison: checks rates (evidence: `main.js`)
- Rate comparison → Kyber quote client: requests quote (evidence: `main.js`)
- Rate comparison → Uniswap market client: reads market (evidence: `main.js`)
- Kyber quote client → Kyber Network: queries rates (evidence: `main.js`)
- Uniswap market client → Uniswap protocol: reads reserves (evidence: `main.js`)
- Approval flow → Atomic arbitrage executor: calls approval (evidence: `main.js`)
- Approval flow → ERC20 token: checks allowance (evidence: `main.js`)
- Approval flow → Uniswap exchange: gets exchange (evidence: `main.js`)
- Bot runner → Trade preparation: prepares trade (evidence: `main.js`)
- Trade preparation → Uniswap market client: gets execution details (evidence: `main.js`)
- Bot runner → Transaction submission: submits trade (evidence: `main.js`)
- Transaction submission → Atomic arbitrage executor: sends transaction (evidence: `main.js`)
- Transaction submission → Ethereum RPC: broadcasts signed transaction (evidence: `main.js`)
- Atomic arbitrage executor → Kyber proxy: swaps via Kyber (evidence: `README.md`)
- Atomic arbitrage executor → Uniswap exchange: swaps via Uniswap (evidence: `README.md`)
- Atomic arbitrage executor → ERC20 token: trades ERC20 (evidence: `README.md`)
