FlashArb-AI · Neros0 · Feb 3, 2025 · Feb 3, 2025
diff --git a/README.md b/README.md
@@ -1,66 +1,159 @@
-## Foundry
+# FlashArbAI Project
 
-**Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.**
+## Overview
 
-Foundry consists of:
+FlashArbAI is a decentralized finance (DeFi) arbitrage bot that leverages Balancer V2 flash loans to identify and execute arbitrage opportunities across decentralized exchanges (DEXs). The project integrates with the Goat Framework and utilizes the Eliza AI agent plugin to provide a conversational interface for users. Users can interact with the AI agent to discover supported token pairs, monitor arbitrage opportunities, and execute trades when profitable opportunities arise.
 
--   **Forge**: Ethereum testing framework (like Truffle, Hardhat and DappTools).
--   **Cast**: Swiss army knife for interacting with EVM smart contracts, sending transactions and getting chain data.
--   **Anvil**: Local Ethereum node, akin to Ganache, Hardhat Network.
--   **Chisel**: Fast, utilitarian, and verbose solidity REPL.
+The core of the project is the `Arbitrage` smart contract, which handles flash loans, token swaps, and profit calculations. The contract is deployed on the Mode Sepolia Testnet and supports DEXs that share the same interface as Uniswap V3.
 
-## Documentation
+## Features
 
-https://book.getfoundry.sh/
+- **Balancer V2 Flash Loans**: Borrow tokens without collateral to execute arbitrage trades.
+- **Uniswap V3 Integration**: Swap tokens on Uniswap V3-compatible DEXs.
+- **AI-Powered Interface**: Interact with the Eliza AI agent to discover and monitor arbitrage opportunities.
+- **Customizable Token Pairs**: Users can select from a list of supported token pairs for arbitrage.
+- **Profit Distribution**: Profits from arbitrage trades are transferred to the contract owner.
 
-## Usage
+## Smart Contract Details
 
-### Build
+### Contract: `Arbitrage.sol`
 
-```shell
-$ forge build
-```
+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.
 
-### Test
+#### Key Functions
 
-```shell
-$ forge test
-```
+1. **`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.
 
-### Format
+2. **`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.
 
-```shell
-$ forge fmt
-```
+3. **`_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.
 
-### Gas Snapshots
+#### Events
 
-```shell
-$ forge snapshot
-```
+- **`TokensSwapped`**:
+  - Emitted when a token swap is executed.
+  - Parameters:
+    - `tokenIn`: Address of the input token.
+    - `tokenOut`: Address of the output token.
+    - `amountIn`: Amount of input tokens swapped.
+    - `minAmountOut`: Minimum amount of output tokens received.
 
-### Anvil
+## Setup Instructions
 
-```shell
-$ anvil
-```
+### Prerequisites
 
-### Deploy
+1. **Foundry**: Install Foundry for smart contract development and testing.
+   ```bash
+   curl -L https://foundry.paradigm.xyz | bash
+   foundryup
+   ```
 
-```shell
-$ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>
-```
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/your-repo/flash-arb-ai.git
+   cd flash-arb-ai
+   ```
 
-### Cast
+2. Install dependencies:
+    ```bash
+    forge install
+    ```
 
-```shell
-$ cast <subcommand>
+3. Compile the smart contract:
+    ```bash
+    forge build
+    ```
+
+4. Deploy the contract to the Mode Sepolia Testnet:
+    ```bash
+    forge script script/DeployArbitrage.s.sol:DeployArbitrage <MODE_SEPOLIA_RPC_URL> --private-key <PRIVATE_KEY> --broadcast --verify --verifier blockscout --verifier-url https://sepolia.explorer.mode.network/api/
+    ```
+
+### Configuration
+
+1. Update the foundry.toml file with your Mode Sepolia Testnet RPC URL and private key.
+
+2. Configure the Eliza AI agent plugin in the Goat Framework to interact with the Arbitrage contract.
+
+## Usage
+### Interacting with the AI Agent
+1. Start the Goat Framework with the Eliza AI agent plugin.
+2. Use the conversational interface to query supported token pairs:
+```
+User: What token pairs are supported for arbitrage?
+Eliza: Supported token pairs are: ETH/USDC, USDC/DAI, WBTC/ETH.
 ```
 
-### Help
+3. Monitor arbitrage opportunities:
+```
+User: Are there any arbitrage opportunities for ETH/USDC?
+Eliza: Yes, there is an arbitrage opportunity for ETH/USDC. Would you like to execute the trade?
+```
 
-```shell
-$ forge --help
-$ anvil --help
-$ cast --help
+4. Execute the trade:
 ```
+User: Execute the trade.
+Eliza: Executing trade... Trade completed successfully. Profit: 0.5 ETH.
+```
+
+### Executing Trades Programmatically
+1. Call the `executeTrade` function on the Arbitrage contract using Foundry:
+    ```bash
+    cast send <CONTRACT_ADDRESS> "executeTrade(address[],address[],address[],uint24,uint256)" \
+    "[<ROUTER1>, <ROUTER2>]" "[<QUOTER1>, <QUOTER2>]" "[<TOKEN1>, <TOKEN2>]" <FEE> <FLASH_AMOUNT> \
+    --rpc-url <MODE_SEPOLIA_RPC_URL> --private-key <PRIVATE_KEY>
+    ```
+
+2. Monitor the TokensSwapped event to track trade execution and profits:
+    ```bash
+    cast logs --from-block <START_BLOCK> --to-block <END_BLOCK> --address <CONTRACT_ADDRESS> \
+    --topic "TokensSwapped(address,address,uint256,uint256)" --rpc-url <MODE_SEPOLIA_RPC_URL>
+    ```
+
+## Testing
+Foundry is used for testing the Arbitrage contract. To run the tests:
+
+1. Write your tests in the test directory.
+
+2. Run the tests using:
+    ```bash
+    forge test
+    ```
+
+## Contributing
+Contributions to the FlashArbAI project are welcome! Please follow these steps:
+
+1. Fork the repository.
+
+2. Create a new branch for your feature or bug fix.
+
+3. 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.
+- Goat Framework and Eliza AI agent for the conversational interface.
diff --git a/broadcast/DeployArbitrage.s.sol/919/run-1738612553.json b/broadcast/DeployArbitrage.s.sol/919/run-1738612553.json
@@ -0,0 +1,57 @@
+{
+  "transactions": [
+    {
+      "hash": "0x5d3face61953331033fdba56e45dea0c8beca460094d1011d1af5e9dd895ce1e",
+      "transactionType": "CREATE",
+      "contractName": "Arbitrage",
+      "contractAddress": "0x70643248405dc951a10dc4e9ce4a910f10fc1be3",
+      "function": null,
+      "arguments": null,
+      "transaction": {
+        "from": "0xfe63ba8189215e5c975e73643b96066b6ad41a45",
+        "gas": "0x1166b6",
+        "value": "0x0",
+        "input": "0x608060405234801561001057600080fd5b50600080546001600160a01b03191633179055610e80806100326000396000f3fe608060405234801561001057600080fd5b50600436106100415760003560e01c806361fe164b146100465780638da5cb5b1461005b578063f04f27071461008a575b600080fd5b6100596100543660046108a4565b61009d565b005b60005461006e906001600160a01b031681565b6040516001600160a01b03909116815260200160405180910390f35b610059610098366004610a12565b610206565b600060405180608001604052808781526020018681526020018581526020018462ffffff168152506040516020016100d59190610b61565b60408051601f198184030181526001808452838301909252925060009190602080830190803683370190505090508460008151811061011657610116610bd5565b60200260200101518160008151811061013157610131610bd5565b6001600160a01b039290921660209283029190910190910152604080516001808252818301909252600091816020016020820280368337019050509050838160008151811061018257610182610bd5565b6020908102919091010152604051632e1c224f60e11b815273ba12222222228d8ba445958a75a0704d566bf2c890635c38449e906101ca903090869086908990600401610c31565b600060405180830381600087803b1580156101e457600080fd5b505af11580156101f8573d6000803e3d6000fd5b505050505050505050505050565b3373ba12222222228d8ba445958a75a0704d566bf2c81461022657600080fd5b60008180602001905181019061023c9190610d3c565b905060008460008151811061025357610253610bd5565b602002602001015190506102ca826000015160008151811061027757610277610bd5565b6020026020010151836040015160008151811061029657610296610bd5565b60200260200101518385604001516001815181106102b6576102b6610bd5565b6020026020010151600087606001516105ad565b6103c082600001516001815181106102e4576102e4610bd5565b6020026020010151836040015160018151811061030357610303610bd5565b6020026020010151846040015160018151811061032257610322610bd5565b60209081029190910101516040516370a0823160e01b81523060048201526001600160a01b03909116906370a0823190602401602060405180830381865afa158015610372573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906103969190610e08565b85604001516000815181106103ad576103ad610bd5565b60200260200101518587606001516105ad565b81604001516000815181106103d7576103d7610bd5565b602090810291909101015160405163a9059cbb60e01b815273ba12222222228d8ba445958a75a0704d566bf2c86004820152602481018390526001600160a01b039091169063a9059cbb906044016020604051808303816000875af1158015610444573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906104689190610e21565b50816040015160008151811061048057610480610bd5565b60200260200101516001600160a01b031663a9059cbb60008054906101000a90046001600160a01b031684604001516000815181106104c1576104c1610bd5565b60209081029190910101516040516370a0823160e01b81523060048201526001600160a01b03909116906370a0823190602401602060405180830381865afa158015610511573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906105359190610e08565b6040516001600160e01b031960e085901b1681526001600160a01b03909216600483015260248201526044016020604051808303816000875af1158015610580573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906105a49190610e21565b50505050505050565b60405163095ea7b360e01b81526001600160a01b0387811660048301526024820186905286169063095ea7b3906044016020604051808303816000875af11580156105fc573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906106209190610e21565b5060408051610100810182526001600160a01b0387811682528581166020830190815262ffffff8581168486019081523060608601908152426080870190815260a087018c815260c088018b8152600060e08a01908152995163414bf38960e01b815289518916600482015296518816602488015293519094166044860152905185166064850152516084840152905160a48301525160c48201529251811660e484015290919088169063414bf38990610104016020604051808303816000875af11580156106f3573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906107179190610e08565b50604080516001600160a01b03808916825286166020820152908101869052606081018490527f25f1d03755df23c30e25db2dbd3891e31ce084bdfbfc46f9fe5e446ee5f9b2d49060800160405180910390a150505050505050565b634e487b7160e01b600052604160045260246000fd5b6040516080810167ffffffffffffffff811182821017156107ac576107ac610773565b60405290565b604051601f8201601f1916810167ffffffffffffffff811182821017156107db576107db610773565b604052919050565b600067ffffffffffffffff8211156107fd576107fd610773565b5060051b60200190565b6001600160a01b038116811461081c57600080fd5b50565b600082601f83011261083057600080fd5b81356020610845610840836107e3565b6107b2565b82815260059290921b8401810191818101908684111561086457600080fd5b8286015b8481101561088857803561087b81610807565b8352918301918301610868565b509695505050505050565b62ffffff8116811461081c57600080fd5b600080600080600060a086880312156108bc57600080fd5b853567ffffffffffffffff808211156108d457600080fd5b6108e089838a0161081f565b965060208801359150808211156108f657600080fd5b61090289838a0161081f565b9550604088013591508082111561091857600080fd5b506109258882890161081f565b935050606086013561093681610893565b949793965091946080013592915050565b600082601f83011261095857600080fd5b81356020610968610840836107e3565b82815260059290921b8401810191818101908684111561098757600080fd5b8286015b84811015610888578035835291830191830161098b565b600082601f8301126109b357600080fd5b813567ffffffffffffffff8111156109cd576109cd610773565b6109e0601f8201601f19166020016107b2565b8181528460208386010111156109f557600080fd5b816020850160208301376000918101602001919091529392505050565b60008060008060808587031215610a2857600080fd5b843567ffffffffffffffff80821115610a4057600080fd5b818701915087601f830112610a5457600080fd5b81356020610a64610840836107e3565b82815260059290921b8401810191818101908b841115610a8357600080fd5b948201945b83861015610aaa578535610a9b81610807565b82529482019490820190610a88565b98505088013592505080821115610ac057600080fd5b610acc88838901610947565b94506040870135915080821115610ae257600080fd5b610aee88838901610947565b93506060870135915080821115610b0457600080fd5b50610b11878288016109a2565b91505092959194509250565b600081518084526020808501945080840160005b83811015610b565781516001600160a01b031687529582019590820190600101610b31565b509495945050505050565b602081526000825160806020840152610b7d60a0840182610b1d565b90506020840151601f1980858403016040860152610b9b8383610b1d565b9250604086015191508085840301606086015250610bb98282610b1d565b91505062ffffff60608501511660808401528091505092915050565b634e487b7160e01b600052603260045260246000fd5b6000815180845260005b81811015610c1157602081850181015186830182015201610bf5565b506000602082860101526020601f19601f83011685010191505092915050565b6001600160a01b0385811682526080602080840182905286519184018290526000928782019290919060a0860190855b81811015610c7f578551851683529483019491830191600101610c61565b5050858103604087015287518082529082019350915080870160005b83811015610cb757815185529382019390820190600101610c9b565b505050508281036060840152610ccd8185610beb565b979650505050505050565b600082601f830112610ce957600080fd5b81516020610cf9610840836107e3565b82815260059290921b84018101918181019086841115610d1857600080fd5b8286015b84811015610888578051610d2f81610807565b8352918301918301610d1c565b600060208284031215610d4e57600080fd5b815167ffffffffffffffff80821115610d6657600080fd5b9083019060808286031215610d7a57600080fd5b610d82610789565b825182811115610d9157600080fd5b610d9d87828601610cd8565b825250602083015182811115610db257600080fd5b610dbe87828601610cd8565b602083015250604083015182811115610dd657600080fd5b610de287828601610cd8565b60408301525060608301519250610df883610893565b6060810192909252509392505050565b600060208284031215610e1a57600080fd5b5051919050565b600060208284031215610e3357600080fd5b81518015158114610e4357600080fd5b939250505056fea264697066735822122051e80441e89853f9f77fb1bf6cb3cbc4fba3462cc76862049360440e5414516264736f6c63430008120033",
+        "nonce": "0x1f",
+        "chainId": "0x397"
+      },
+      "additionalContracts": [],
+      "isFixedGasLimit": false
+    }
+  ],
+  "receipts": [
+    {
+      "status": "0x1",
+      "cumulativeGasUsed": "0xeb536",
+      "logs": [],
+      "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
+      "type": "0x2",
+      "transactionHash": "0x5d3face61953331033fdba56e45dea0c8beca460094d1011d1af5e9dd895ce1e",
+      "transactionIndex": "0x2",
+      "blockHash": "0x556308c813765ece340e0516c90cd186c38269e1a07162658895977457b7fdc3",
+      "blockNumber": "0x183268e",
+      "gasUsed": "0xd62b4",
+      "effectiveGasPrice": "0xfd",
+      "from": "0xfe63ba8189215e5c975e73643b96066b6ad41a45",
+      "to": null,
+      "contractAddress": "0x70643248405dc951a10dc4e9ce4a910f10fc1be3",
+      "l1BaseFeeScalar": "0x3d1",
+      "l1BlobBaseFee": "0x1",
+      "l1BlobBaseFeeScalar": "0x8ee87",
+      "l1Fee": "0x26992a70dd",
+      "l1GasPrice": "0x12bf9641c",
+      "l1GasUsed": "0x83b3"
+    }
+  ],
+  "libraries": [],
+  "pending": [],
+  "returns": {
+    "0": {
+      "internal_type": "contract Arbitrage",
+      "value": "0x70643248405DC951a10DC4E9CE4a910F10fC1bE3"
+    }
+  },
+  "timestamp": 1738612553,
+  "chain": 919,
+  "commit": "da11364"
+}