FlashArbAI Project

FlashArbAI is a decentralized finance (DeFi) arbitrage bot that leverages Balancer V2 flash loans to identify and execute profitable arbitrage opportunities across decentralized exchanges (DEXs). It integrates with the Goat Framework and utilizes the Eliza AI agent plugin to provide a conversational interface for interacting with trades and opportunities.

Overview

FlashArbAI uses Balancer V2 flash loans to borrow tokens without collateral and perform arbitrage trades on Uniswap V3-compatible DEXs. The AI-powered Eliza agent provides a natural language interface to:

Discover supported token pairs
Monitor arbitrage opportunities
Execute profitable trades

The core of the project is the Arbitrage smart contract, responsible for flash loans, token swaps, and profit calculations.

Features

Balancer V2 Flash Loans: Borrow tokens without collateral to execute trades.
Uniswap V3 Integration: Perform token swaps across Uniswap V3-compatible DEXs.
AI-Powered Interface: Use Eliza AI for opportunity discovery and execution.
Customizable Token Pairs: Define and adjust arbitrage token pairs.
Profit Distribution: Profits are automatically transferred to the contract owner.

System Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Eliza AI      │────│  FlashArbAI     │────│   Balancer V2   │
│   Agent         │    │  Arbitrage      │    │   Flash Loans   │
│                 │    │  Contract       │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│    User         │    │   Uniswap V3    │    │   Other DEXs    │
│  Interface      │    │   Compatible    │    │   (SushiSwap,   │
│                 │    │     DEXs        │    │   PancakeSwap)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

Workflow

Opportunity Detection: AI agent monitors price differences across supported DEXs
Flash Loan Initiation: Contract requests flash loan from Balancer V2
Arbitrage Execution: Execute swaps across different DEXs to capture price differences
Profit Calculation: Calculate net profit after fees and gas costs
Loan Repayment: Repay flash loan and transfer profits to contract owner

Smart Contract Details

Contract: `Arbitrage.sol`

The Arbitrage contract is the core of the FlashArbAI project. It implements the IFlashLoanRecipient interface to receive flash loans from Balancer V2 and executes arbitrage trades on Uniswap V3-compatible DEXs.

Key Functions

executeTrade:
- Initiates a flash loan to execute an arbitrage trade.
- Parameters:
  - _routerPath: Addresses of the swap routers for each trade.
  - _quoterPath: Addresses of the quoters for price calculations.
  - _tokenPath: Addresses of the tokens involved in the trade.
  - _fee: Pool fee for the swap.
  - _flashAmount: Amount of tokens to flash loan.
receiveFlashLoan:
- Callback function invoked by Balancer V2 after providing the flash loan.
- Executes the arbitrage trade by swapping tokens on the specified DEXs.
- Repays the flash loan and transfers profits to the contract owner.
_swapOnV3:
- Internal function to execute a token swap on a Uniswap V3-compatible DEX.
- Parameters:
  - _router: Address of the swap router.
  - _tokenIn: Address of the input token.
  - _amountIn: Amount of input tokens to swap.
  - _tokenOut: Address of the output token.
  - _amountOut: Minimum amount of output tokens expected.
  - _fee: Pool fee for the swap.

Events

event TokensSwapped(
    address indexed tokenIn,
    address indexed tokenOut,
    uint256 amountIn,
    uint256 amountOut
);

event ArbitrageExecuted(
    address indexed tokenA,
    address indexed tokenB,
    uint256 profit,
    uint256 gasUsed
);

Setup Instructions

Prerequisites

Foundry: Install Foundry for smart contract development and testing.
```
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

Installation

Clone the repository:

git clone https://github.com/your-repo/flash-arb-ai.git
cd flash-arb-ai

Install dependencies:
```
forge install
```
Compile the smart contract:
```
forge build
```

Deploy the contract, here is an example for Any Testnet:

forge script script/DeployArbitrage.s.sol:DeployArbitrage <ANYTESTNET_RPC_URL> --private-key <PRIVATE_KEY> --broadcast --verify --verifier blockscout --verifier-url $VERIFIER_URL

Environment Variables

Create .env file in the root directory:

# Network Configuration
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_PROJECT_ID
MAINNET_RPC_URL=https://mainnet.infura.io/v3/YOUR_PROJECT_ID

# Private Keys
PRIVATE_KEY=your_private_key_here

# Contract Addresses
BALANCER_VAULT=0xBA12222222228d8Ba445958a75a0704d566BF2C8
UNISWAP_V3_ROUTER=0xE592427A0AEce92De3Edee1F18E0157C05861564

# API Keys
ETHERSCAN_API_KEY=your_etherscan_api_key
COINGECKO_API_KEY=your_coingecko_api_key

Configuration

Update the foundry.toml file with your network RPC URL.
Configure supported token pairs in config/tokens.json:

{
  "supportedPairs": [
    {
      "tokenA": "0xA0b86a33E6441a1e60b5C5B5B5B1b5B5B5B5B5B5",
      "tokenB": "0xB0b86a33E6441a1e60b5C5B5B5B1b5B5B5B5B5B5",
      "name": "WETH/USDC",
      "minProfitThreshold": "0.01"
    }
  ]
}

Usage

Executing Trades Programmatically

Call the executeTrade function on the Arbitrage contract using Foundry:

cast send <CONTRACT_ADDRESS> "executeTrade(address[],address[],address[],uint24,uint256)" \
"[<ROUTER1>, <ROUTER2>]" "[<QUOTER1>, <QUOTER2>]" "[<TOKEN1>, <TOKEN2>]" <FEE> <FLASH_AMOUNT> \
--rpc-url <SEPOLIA_RPC_URL> --private-key <PRIVATE_KEY>

Monitor the TokensSwapped event to track trade execution and profits:

cast logs --from-block <START_BLOCK> --to-block <END_BLOCK> --address <CONTRACT_ADDRESS> \
--topic "TokensSwapped(address,address,uint256,uint256)" --rpc-url <SEPOLIA_RPC_URL>

Using the AI Agent Interface

Start the Eliza AI agent:

pnpm run start:agent

Sample queries:

"Show me profitable arbitrage opportunities"
"Execute arbitrage for WETH/USDC"
"What's the profit potential for ETH/DAI?"

Interact with the agent using natural language:
- "Show me profitable arbitrage opportunities"
- "Execute arbitrage for WETH/USDC pair"
- "What's the current profit potential for ETH/DAI?"

Testing

Foundry is used for testing the Arbitrage contract. To run the tests:

Write your tests in the test directory.
Run the tests using:
```
forge test
```

Test Coverage

Generage test coverage reports:

forge coverage

Security Considerations

Known Risks

MEV (Maximal Extractable Value): Arbitrage transactions may be front-run by MEV bots
Flash Loan Attacks: Ensure proper validation of flash loan repayment
Slippage: Market conditions can change between opportunity detection and execution
Smart Contract Risk: Potential bugs in contract logic or external dependencies

Security Measures

Reentrancy guards on critical functions
Slippage protection with configurable thresholds
Access control for sensitive operations
Regular security audits (planned)

Performance Optimization

Gas Optimization

Use of assembly for critical calculations
Batch operations where possible
Optimized storage patterns
Efficient event emission

Monitoring & Analytics

Track key metrics:

Arbitrage success rate
Average profit per trade
Gas costs vs. profits
Network congestion impact

Troubleshooting

Common Issues

Issue: Flash loan execution fails

Solution: Check token balances and ensure sufficient liquidity

Issue: High gas costs eating into profits

Solution: Adjust minimum profit thresholds and monitor network conditions

Issue: Slippage too high

Solution: Increase slippage tolerance or reduce trade size

API Reference

Contract Methods

executeTrade

Executes an arbitrage trade using flash loans.

Parameters:

_routerPath(address[]): Array of router addresses
_quoterPath(address[]): Array of quoter addresses
_tokenPath(address[]): Array of token addresses
_fee (uint24): Pool fee
_flashAmount(uint256): Flash loan amount

Returns: Transaction hash

getProfit

Calculates potential profit for a given arbitrage opportunity.

Parameters:

tokenA (address): First token address
tokenB (address): Second token address
amount (uint256): Trade amount

Returns: Estimated profit (uint256)

Roadmap

Phase 1 (Current)

✅ Core arbitrage contract development ✅ Balancer V2 flash loan integration ✅ Uniswap V3 compatibility 🚧 AI agent integration

Phase 2 (Planned)

🔄 Multi-DEX support expansion 🔄 Advanced profit optimization algorithms 🔄 Web dashboard for monitoring 🔄 Mobile app development

Phase 3 (Planned)

🔄 Cross-chain arbitrage 🔄 Institutional-grade API 🔄 Automated portfolio management 🔄 Third-party integrations

Contributing

Contributions to the FlashArbAI project are welcome! Please follow these steps:

Fork the repository.
Create a new branch for your feature or bug fix.
Submit a pull request with a detailed description of your changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

Balancer Labs for the Balancer V2 flash loan functionality.
Uniswap Labs for the Uniswap V3 integration.

Known Issues

Only works with Uniswap V3 forks (for now)
Needs more slippage protection
Might fail if liquidity is too low

FAQ

What tokens are supported? Check config/tokens.json.
Which networks are supported? Currently Sepolia and Mainnet.
Average gas cost per trade? Depends on network congestion.
How to add a new DEX? Update integration logic and configurations accordingly.

Disclaimer

This software is provided "as is" without warranty. Users are responsible for understanding the risks associated with DeFi trading and flash loans. Always test thoroughly on testnets before using with real funds.

⚠️ Warning: Flash loan arbitrage involves significant financial risk. Only use funds you can afford to lose and ensure you understand the technology before deployment.

Name		Name	Last commit message	Last commit date
Latest commit History 407 Commits
.github/workflows		.github/workflows
broadcast		broadcast
lib		lib
script		script
src		src
test		test
uniswap-clone		uniswap-clone
.DS_Store		.DS_Store
.gitignore		.gitignore
.gitmodules		.gitmodules
README.md		README.md
foundry.toml		foundry.toml
makefile		makefile

Revan0x01/contracts

Folders and files

Latest commit

History

Repository files navigation

FlashArbAI Project

Table of Contents

Overview

Features

System Architecture

Workflow

Smart Contract Details

Contract: Arbitrage.sol

Key Functions

Events

Setup Instructions

Prerequisites

Installation

Environment Variables

Configuration

Usage

Executing Trades Programmatically

Using the AI Agent Interface

Testing

Test Coverage

Security Considerations

Known Risks

Security Measures

Performance Optimization

Gas Optimization

Monitoring & Analytics

Track key metrics:

Troubleshooting

Common Issues

API Reference

Contract Methods

Parameters:

Returns: Transaction hash

Parameters:

Roadmap

Phase 1 (Current)

Phase 2 (Planned)

Phase 3 (Planned)

Contributing

License

Acknowledgments

Known Issues

FAQ

Disclaimer

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Contract: `Arbitrage.sol`

Packages