{"id":28507339,"url":"https://github.com/exactly/liquidation-bot","last_synced_at":"2025-07-05T06:31:32.635Z","repository":{"id":72601923,"uuid":"495414897","full_name":"exactly/liquidation-bot","owner":"exactly","description":"bot and contract for liquidating accounts in exactly protocol.","archived":false,"fork":false,"pushed_at":"2024-05-31T20:34:33.000Z","size":948,"stargazers_count":26,"open_issues_count":10,"forks_count":10,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-06-08T20:36:45.288Z","etag":null,"topics":["blockchain","defi","ethereum","optimism","rust","solidity"],"latest_commit_sha":null,"homepage":"https://exact.ly","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exactly.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-23T13:07:21.000Z","updated_at":"2024-10-21T01:47:07.000Z","dependencies_parsed_at":"2023-05-24T15:30:40.288Z","dependency_job_id":"abf85243-d4d4-49ef-a7a3-5d91a23ca379","html_url":"https://github.com/exactly/liquidation-bot","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/exactly/liquidation-bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exactly%2Fliquidation-bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exactly%2Fliquidation-bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exactly%2Fliquidation-bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exactly%2Fliquidation-bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exactly","download_url":"https://codeload.github.com/exactly/liquidation-bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exactly%2Fliquidation-bot/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263696217,"owners_count":23497513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","defi","ethereum","optimism","rust","solidity"],"created_at":"2025-06-08T20:30:44.909Z","updated_at":"2025-07-05T06:31:32.604Z","avatar_url":"https://github.com/exactly.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Liquidation bot\n\n## Dependencies\n\n- Rust;\n- Node.\n\nThe liquidation bot is written in Rust; therefore, it must be installed and set up on the machine.\n\n## How to install and run it\n\nCloning the project:\n\n```shell\ngit clone git@github.com:exactly-protocol/liquidation-bot.git\n```\n\nDeploying flash loan contracts:\n\n```shell\nnpm i --legacy-peer-deps\nnpx hardhat --network \u003cnetwork\u003e deploy\n```\n\nRunning the project:\n\nA `.env` file should be created on the root directory of the project with the following parameters:\n\n```env\nCHAIN_ID=[ID of the chain used]\n[CHAIN_NAME]_NODE=[Link to the RPC provider - MUST be a WebSocket address]\n[CHAIN_NAME]_NODE_RELAYER=[Link to the RPC provider used on liquidations - MUST be an HTTP address]\nMNEMONIC=[Seed phrase for the bot's account]\nREPAY_OFFSET=1\nTOKEN_PAIRS=[Pairs of tokens with their fees on Uniswap - it should follows this format `[[\"TOKEN1\",\"TOKEN2\", FEE12],[\"TOKEN3\",\"TOKEN4\", FEE34]...]`]\nBACKUP=0\n```\n\nAfter the `.env` file has been created, run the project with the command:\n\n```shell\ncargo run\n```\n\n## How it works\n\n### The Bot\n\nThe bot works by remounting the users' positions using the protocol's emitted events with the minimum number of calls directly to the contracts. This makes the bot more efficient in recreating such states.\n\nAfter the bot connects to the RPC provider through WebSocket, it subscribes to receive the events stream.\n\nEach one of those events is parsed and transcribed into the user's data.\n\nWhenever there's an idle moment on receiving new events, the bot does a check for liquidations.\n\nIf a user is in a state to be liquidated (with a health factor smaller than 1), the flash loan contract's liquidation function is called.\n\nThe debt is liquidated.\n\nThe bot liquidates the user's debt seizing their collateral with the highest value.\n\nAll the users that could be liquidated will be.\nAfter the liquidations, the bot returns to wait for more events and recreate the user's positions.\n\n### Flash loan contract\n\nThe flash loan contract calls protocol's liquidation function.\n\nIt checks its amount on the specific debt asset available on the contract's balance to repay the user's debt. In case it has less than the amount needed to liquidate the user, it does as follow:\n\n1. Borrow on Uniswap V3 the difference between what it has and the user's debt;\n1. Waits for a callback notifying it that the amount was received;\n1. Repays the debt;\n1. Receives the collateral;\n1. Swaps it to the same as the user's debt;\n1. Repays Uniswap.\n\n## Structure\n\nThe project is structured as follows:\n\n- main.rs\n\n    Set up the bot to connect correctly to RPC Provider.\n\n    Starts the service and handles most of the errors.\n\n- protocol.rs\n\n    It's where most of the tasks are executed.\n\n  - A subscription to the event's stream is made on the main thread;\n\n  - Each event received is parsed;\n\n  - Positions are created;\n\n  - A debounce for idleness is made in another thread;\n\n  - When the bot is idle for enough time, this thread checks for liquidations\n    and send them to the `liquidation` module;\n\n- liquidation.rs\n\n\tCarry a queue of liquidations to be executed. The health factor is re-calculated before the `liquidate` function is called.\n\n- account.rs\n\n    This structure is used to store users' data.\n\n- market.rs\n\n    Stores updated information created by the protocol's events about all the markets.\n\n- exactly_events.rs\n\n    Redirect the events to suitable structures.\n\n- config.rs\n\n    Handle environment variables such as RPC provider link access, wallet's mnemonic, etc.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexactly%2Fliquidation-bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexactly%2Fliquidation-bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexactly%2Fliquidation-bot/lists"}