/liquidation-bot

Primary LanguageTypeScript

Evaa Protocol Hackathon 2023

Hackathon Theme and Objectives

  • Focus: Focused on developing liquidation bots for the Evaa Protocol, to earn profits by efficiently liquidating undercollateralized positions to maintain market stability.
  • Relevance: Highly relevant to current trends in TON DeFi, with a focus on maintaining market stability and security.

telegram-cloud-photo-size-5-6266854178676652995-y

Table of Contents

  1. Introduction to Evaa & Liquidation Bots
  2. Evaa Hackathon Overview
  3. Participation Details
  4. Hackathon Prizes
  5. Evaluation Criteria
  6. Developer Resources
  7. Submission Guidelines
  8. Task Brief
  9. Understanding the EVAA Protocol GET Methods
  10. Understanding the EVAA Protocol Liquidation TX
  11. Network Fee Calculation for Lending Master Contract Operations
  12. Leaderboard & Participation
  13. Partners & Sponsors

Introduction to Evaa & Liquidation Bots

Evaa Protocol:

  • Overview: Evaa Protocol is a key player in TON DeFi.
  • Functionality: Specializes in the lending and borrowing of digital assets.
  • Collateralization: Emphasizes strict collateral requirements to ensure the integrity and trustworthiness of blockchain transactions.
  • Market Stability: Implements proactive measures for stability and security, particularly effective during market downturns.

Liquidation Bots:

  • Purpose: Serve as automated guardians in the volatile DeFi market.
  • Operation: Constantly monitor market conditions and collateral levels in lending protocols.
  • Liquidation Trigger: Automatically initiate the liquidation process when a borrower's collateral falls below a certain threshold.
  • Role in DeFi: Essential for maintaining balance and reliability in platforms like Evaa, helping to manage risks associated with lending and borrowing.

Evaa Hackathon Overview

The Evaa Hackathon is all about creating smart liquidation bots for the Evaa system. It's a chance for developers to show their skills, bring new ideas to the fast-moving DeFi world, and earn rewards and recognition.

Competition Timeline

Bot Development Phase

  • Start of Development: November 27th
  • End of Development: December 31th

Liquidation Bots Competition

  • Contest: 1 Week of Jan

Judging Period

  • Judging: 2 Week of Jan

Announcement of Winners

  • Winner Announcement: 2 Week of Jan

Participation Details

🌍 A Global Invitation: Developers and DeFi enthusiasts worldwide are invited to:

  • Create innovative Liquidation Bots for the Evaa ecosystem.
  • Build unique utilities on top of TON (The Open Network) protocols.

🔗 Engage and Innovate: Participate in the Evaa Hackathon and:

  • Dive into the world of TON DeFi, exploring and creating solutions.
  • Connect with peers and the Evaa team in the Protocol Hub.
  • Connect with other builders in the Evaa Buidl.

Join the movement at the Evaa Protocol Hub: Evaa Telegram. Join devs at the Evaa Buidl: Evaa BUIDL.

Hackathon Prizes

Prizes Breakdown

Here's a detailed look at the prizes being offered:

EVAA Liquidation Bot Competition

  • Prize Pool: $3,000
  • Objective: Develop a bot that can effectively liquidate positions on the Evaa platform. The top-performing bots will share the prize pool based on their liquidation efficiency and profitability.

DeDust Liquidation Bounty

  • Prize Pool: $2,500
  • Objective: Create a bot that specializes in liquidating assets on the DeDust platform. Successful bots will be judged on their speed, accuracy, and the volume of successful liquidations.

TON Access Orbs Bounty

  • Prize Pool: $2,500
  • Objective: Integrate TON Access provided by Orbs into your bot to streamline operations and enhance functionality. The most innovative and effective use of TON Access will be rewarded.

StonFi Liquidation Bounty

  • Prize Pool: $1,200
  • Objective: Construct a bot capable of executing liquidations on the StonFi protocol. Prizes will be awarded to bots that deliver the best performance metrics regarding speed and economic efficiency.

Bonus Offer

  • TON API Credits: Each participant will receive 100 TON of Credits for use on the TON API, courtesy of TONKEEPER. This offer is limited to the first 50 participants who sign up and utilize the API in their hackathon project.

Evaluation Criteria

Criteria Details

Participants must achieve the most substantial accumulated profit through repeated liquidations on the Evaa Protocol amidst market volatility using bots prepared during the development phase. It's essential to emphasize that liquidations should occur multiple times, not just once.

To liquidate, participants must either:

  • Liquidate a debt in Token A backed by Token B, then convert the received Token B back to Token A. Profit is calculated as the increase in Token A's balance, measured in USD at the transaction's current exchange rate.
  • Convert Token B to Token A, liquidate a debt in Token A backed by Token B. Profit is the surge in Token B's balance, converted to USD at the prevailing exchange rate during the transaction.
  • Convert Token C to Token A, liquidate a debt in Token A secured by Token B, and then swap the acquired Token B for Token C. Profit here is the rise in Token C's balance, denoted in USD based on the transaction's rate.

Additional Requirement:

  • Use a unique query_id for each operation sequence for easier tracking and analysis.

Open-Sourcing Bonus

  • We understand the temptation to keep a high-performing bot's code proprietary, especially if it proves profitable. However, we encourage open sourcing.
  • If you share your bot's source code with the community, you will receive a special Evaa NFT designated for open-source developers.
  • Beyond the tangible rewards, open-sourcing your solution will earn you the respect and admiration of the community.

Bonus for Using Partners' Technologies

  • Our ecosystem allies, such as DeDust, StonFi, Orbs, and Tonkeeper, have established bounties for the hackathon.
  • By incorporating our partners' technologies into your bot's development, you not only enhance its capabilities but also become eligible for additional prizes.
  • These bounties serve as an excellent opportunity to explore new technologies while earning rewards for your innovative contributions.

Judges

  • A distinguished panel of DeFi experts and core Evaa Protocol team members

Additional Condition for the Hackathon

  • Unique query_id for Each Operation Sequence: Participants are required to use a unique query_id for each sequence of operations (liquidation + swap, swap + liquidation, swap + liquidation + swap). This will facilitate the tracking and analysis of operations, simplifying the validation process and efficiency assessment of the bots.

Developer Resources

An Open Source Basic Liquidation Bot That You Can Get Started With

Access the open-source hackathon version of the basic liquidation bot to interact with EVAA's smart contracts:

Hackathon Version Front-End

Access the hackathon version of the application to interact with the smart contracts:

Contract Addresses

  • Hackathon Evaa Master SC: EQBgEeF46Blyistz-KyGh80NwZuQAdlrEoKSECUGJ5VSHt7H
  • IOTA NFT ID for hackathon stand: 0x85f0045998038bebd076987deb4d4c680a323cb04380491eaa7857b6469ba923
  • Testnet Evaa SC with positions: EQAzAwpmJcfIYYHWtsgOgZS7dEX2wSKc1AZvX8LOqGIqlwZD (check it)
  • IOTA NFT ID for Testnet SC: 0x98f8eb12127ee205a7b84e6910021e1e65ec5c8d92f89acdffea7be20104e899
  • DeDust Factory: EQBfBWT7X2BHg9tXAxzhz2aKiNTU1tpt5NsiK0uSDW_YAJ67
  • DeDust Native Vault (where all the TON tokens are): EQDa4VOnTYlLvDJ0gZjNYm5PXfSmmtL6Vs6A_CZEtXCNICq_
  • STON.fi Router: EQB3ncyBUTjZUA5EnFKR5_EnOMI9V1tTEAAPaiU71gc4TiUt

Hackathon stand link here https://front-end-hazel-iota.vercel.app/

SDK Documentation

  • DeDust SDK:
    The DeDust SDK facilitates seamless interactions with the DeDust Protocol, optimized for TypeScript / JavaScript.
    For more details, refer to the DeDust SDK documentation.

  • STON.fi SDK:
    The STON.fi SDK provides tools for the STON.fi protocol.
    For an in-depth exploration, check the STON.fi SDK documentation.

Additional Resources

Submission Guidelines

  • Initiate a GitHub repository on November 24th and commit your project code to EvaaFi Repository.
  • Submit your repository link through the Evaa Protocol Hub

Task Brief

The Evaa Protocol invites you to engineer a liquidation bot that:

  1. Constantly monitors user positions in real-time on Evaa Protocol.
  2. Triggers liquidation for positions exceeding the 107% threshold.
  3. Seamlessly executes asset swaps on designated DEXs.

DEX Incentives:

  • DEX DeDust: Bounty for using DeDust as a liquidation platform.
  • DEX StonFi: Bounty for using StonFi as a liquidation platform.

API Incentives:

  • TON ACCESS: Bounty for platform usage.

Free credits:

  • TON API: 100 TON in API Credits for platform usage.

Your bot should smartly navigate these DEXs and make strategic decisions for optimal liquidation.

Understanding the EVAA Protocol GET Methods

1. get_wallet_data

  • Description: Retrieves wallet data, such as the balance.
  • Usage: 
    myBalance.usdt = (await tonClient.runMethod(jettonWallets.usdt, 'get_wallet_data')).stack.readBigNumber();
  • Arguments:
    • Wallet address (e.g., jettonWallets.usdt)
  • Return:
      assetBalance = Uint(64);

2. getAssetsData

  • Description: Returns data about assets.
  • Usage: 
    const assetsDataResult = await tonClient.runMethod(masterAddress, 'getAssetsData');
  • Name: getAssetsData
  • Arguments:
    • Master address (e.g., masterAddress)
  • Return:
      [
        Dict<key: int256, {
          sRate = Uint(64);
          bRate = Uint(64);
          totalSupply = Uint(64);
          totalBorrow = Uint(64);
          lastAccural = Uint(32);
          balance = Uint(64);
          }>
      ]

3. getAssetsConfig

  • Description: Returns the asset configuration.
  • Usage: 
    const assetConfigResult = await tonClient.runMethod(masterAddress, 'getAssetsConfig');
  • Name: getAssetsConfig
  • Arguments:
    • Master address (e.g., masterAddress)
  • Return:
      [
        Dict<key=tokenId: int256, {
          oracle = slice; 
          decimals = Uint(8); 
          collateralFactor = Uint(16); 
          liquidationThreshold = Uint(16); 
          liquidationPenalty = Uint(16); 
          baseBorrowRate = Uint(64); 
          borrowRateSlopeLow = Uint(64); 
          borrowRateSlopeHigh = Uint(64); 
          supplyRateSlopeLow = Uint(64); 
          supplyRateSlopeHigh = Uint(64); 
          targeUtilization = Uint(64);
          }>
      ]

4. getAllUserScData

  • Description: Returns all user data related to the smart contract.
  • Usage: 
    userDataResult = await tonClient.runMethodWithError(userContractAddress, 'getAllUserScData');
  • Arguments:
    • User smart contract address (e.g., userContractAddress)
  • Return:
      [
        Dict<key=: int256,{
          codeVersion = Uint(64);
          userAddress = Uint(64);
          userPrincipals = {
            ton?: Uint(64),
            usdt?: Uint(64),
            usdc?: Uint(64),
          };
        }>
      ]

Understanding the EVAA Protocol Liquidation TX

TON Loan Asset

If the loan asset is TON (TON Crystal), the following steps are performed:

  1. Set the liquidation opcode to 0x3.
  2. Store the query ID, which can be 0.
  3. Store the user's wallet address (not the user SC address). This address is used to calculate the user SC address.
  4. Store the ID of the token to be received. It's a SHA256 HASH derived from the Jetton wallet address of the EVAA master smart contract.
  5. Store the minimal amount of tokens required to satisfy the liquidation.
  6. Set a constant value of -1 (can always be -1).
  7. Reference the pricessCell, which contains prices obtainable from the IOTA NFT.
  8. Conclude the cell.

Amount to send: task.liquidationAmount, minus 0.33 for blockchain fees. The EVAA smart contract will calculate the amount of collateral tokens to send back based on this number.

Destination address: evaaMaster.

Other Loan Assets

For loan assets other than TON, the following steps are performed:

  1. Set the jetton transfer opcode to 0xf8a7ea5.
  2. Store the query ID, which can be 0.
  3. Store the amount of jettons to send (The EVAA smart contract will calculate the amount of collateral tokens to send back based on this number).
  4. Store the address of the jetton receiver smart contract, which is the EVAA master.
  5. Store the address of the contract to receive leftover TONs.
  6. Set a bit to 0.
  7. Store the TON amount to forward in a token notification (Note: Clarification needed).
  8. Set another bit to 1.
  9. Reference a sub-cell, which replicates the TON liquidation logic.
  10. Conclude the main cell.

Amount to send: toNano('1') for transaction chain fees (Note: Clarification needed).

Destination address: The Jetton wallet associated with the loan asset.

This code provides a clear explanation of the liquidation process, with detailed comments to understand each step.

Network Fee Calculation for Lending Master Contract Operations

In order to determine the amount of TONs needed for network fees (with some excess, where the unused portion is refunded), you should call the corresponding get-method on the Lending Master contract:

  • int supply_min_attachment(int fwd_fee) method_id
  • int withdraw_min_attachment(int fwd_fee, cell withdraw_user_message) method_id
  • int liquidate_min_attachment(int fwd_fee) method_id

All these methods accept "fwd_fee" as the first parameter. This should be taken from one of the recent Supply/Withdraw/Liquidate requests (corresponding to the method being called) from TON/Jetton wallet to the Lending Master. Note that "request" refers to the first message that enters the lending protocol and initiates the corresponding operation. Keep in mind that "fwd_fee" might vary when sending TONs and Jettons.

The withdraw_min_attachment get-method also requires "withdraw_user_message" as the second parameter. To determine if the attached TONs are sufficient for proceeding with a Withdraw request, the Master contract uses a real assembled message about to be sent to the Lending-User contract. For convenience, you can obtain a sample "withdraw_user_message" to be used for determining the amount to attach by calling:

  • cell dummy_withdraw_user_message() method_id on the Lending Master contract.

Remember, you can always attach more than required; any excess attachment will be refunded.

Leaderboard and Participation

  • A public leaderboard will cultivate competitiveness among participants.
  • Track the number of successful liquidations for each participant's bot.

Partners and Sponsors

We are proud to collaborate with a network of organizers, partners and sponsors dedicated to fostering innovation and growth in our ecosystem.

Below are the links to our partners' websites where you can learn more about their services and contributions to our project:

We extend our heartfelt thanks to our partners for their support and dedication. Together, we are building a more robust and more interconnected blockchain ecosystem.