https://github.com/aboutcircles/circles_arbbots
Circles arrbot to support equlibration of prices
https://github.com/aboutcircles/circles_arbbots
Last synced: 5 months ago
JSON representation
Circles arrbot to support equlibration of prices
- Host: GitHub
- URL: https://github.com/aboutcircles/circles_arbbots
- Owner: aboutcircles
- Created: 2025-01-20T11:54:02.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-12-12T17:51:50.000Z (6 months ago)
- Last Synced: 2025-12-14T08:45:17.558Z (6 months ago)
- Language: TypeScript
- Homepage:
- Size: 523 KB
- Stars: 3
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
- awesome-circles - circles_arbbots - Arbitrage bots that help equilibrate prices across CRC tokens. (Research, Simulation & Reputation / Developer Demos)
README
# ArbBot
A specialized arbitrage bot for the Circles ecosystem with two distinct implementations:
## Generic Arbitrage Bot
The generic implementation uses a graph-based approach to find and execute profitable trading opportunities:
```text
1. INITIALIZATION
├─ Initialize data interface and graph structure
├─ Connect to required APIs (Balancer, Circles)
└─ Set up configuration parameters
2. GRAPH CONSTRUCTION
├─ Load initial nodes from database
├─ Fetch group members and trust relationships
├─ Calculate initial price estimates
└─ Build complete graph with liquidity edges
3. DEAL FINDING & EXECUTION
├─ SELECT EDGE
│ ├─ Random exploration (with probability EXPLORATION_RATE)
│ └─ Best score selection based on:
│ score = (targetPrice - sourcePrice) × edgeLiquidity
│
├─ UPDATE VALUES
│ ├─ Refresh spot prices for source and target nodes
│ └─ Update edge liquidity through trust relationships
│
├─ CALCULATE OPTIMAL TRADE
│ ├─ Start with minimum extractable amount
│ ├─ Double amount iteratively while profitable
│ └─ Select best profit/amount combination
│
└─ EXECUTE TRADE
├─ Verify profit > threshold
├─ Build Balancer swap parameters
└─ Execute transaction
```
## Group-Specific Arbitrage Bot
The group-focused implementation targets arbitrage between group tokens and member tokens:
```text
1. INITIALIZATION
├─ Load environment variables and contracts
├─ Initialize Circles SDK and APIs
└─ Set up database connections
2. DEAL FINDING & EXECUTION
├─ FOR EACH GROUP MEMBER:
│ ├─ Update token prices via Balancer quotes
│ │
│ ├─ EVALUATE BOTH DIRECTIONS:
│ │ ├─ Group token → Member token
│ │ └─ Member token → Group token
│ │
│ ├─ OPTIMIZE TRADE SIZE:
│ │ ├─ Start with MIN_EXTRACTABLE_AMOUNT
│ │ ├─ Double amount while:
│ │ │ ├─ Price remains favorable
│ │ │ ├─ Required tokens are available
│ │ │ └─ Profit increases
│ │ └─ Select most profitable amount
│ │
│ └─ CHECK PROFITABILITY:
│ outputAmount - inputAmount > EPSILON
│
├─ ENSURE LIQUIDITY
│ ├─ Check current token balances (ERC20 + ERC1155)
│ ├─ Calculate required additional tokens
│ ├─ Pull tokens through pathfinder if needed
│ └─ Convert tokens (wrap/unwrap)
│
└─ EXECUTE TRADE
├─ Set token approvals if needed
├─ Build Balancer swap parameters
└─ Execute transaction
```