Detailed Instructions

Keepers run specialized software or bots that poll the public mempool and query smart contracts to identify risky positions. The key metric is the Health Factor (HF), calculated as (Collateral Value * Liquidation Threshold) / Borrowed Value. A position becomes eligible for liquidation when its HF drops below 1.0 (or a protocol-specific threshold like 1.05).

• Sub-step 1: Query Protocol Contracts: The keeper calls the getUserAccountData function on a protocol like Aave to fetch a user's health factor.
• Sub-step 2: Monitor Oracle Prices: The keeper simultaneously checks the latest price feeds from oracles (e.g., Chainlink's latestAnswer for ETH/USD) to ensure the collateral valuation is current.
• Sub-step 3: Identify Targets: The bot filters all positions, flagging those where healthFactor < liquidationThreshold.

Tip: Efficient keepers use event listeners (like HealthFactorUpdated) instead of constant polling to save on RPC calls and gas costs.

javascriptCopy
// Example query to Aave V3 on Ethereum Mainnet
const userData = await aaveContract.getUserAccountData('0xUserAddress');
// userData.healthFactor is returned as a BigNumber (e.g., 1.1e18 for 1.1)
if (userData.healthFactor.lt(ethers.utils.parseUnits('1.0', 18))) {
    // Position is undercollateralized
}

Detailed Instructions

Upon finding a target, the keeper calculates the optimal liquidation amount. Protocols offer a liquidation bonus (or penalty) as an incentive, typically 5-15%, allowing the keeper to buy collateral at a discount. The calculation ensures the user's health factor is restored above the safe threshold (e.g., back to 1.1) without over-liquidating.

• Sub-step 1: Determine Close Factor: Protocols like Compound have a close factor (e.g., 50%) limiting the max borrow amount that can be liquidated in one transaction.
• Sub-step 2: Compute Debt to Cover: The keeper calculates the debtToCover needed to raise the HF above the threshold, often using the formula: debtToCover = (borrowedValue * (1 - targetHF / currentHF)).
• Sub-step 3: Apply Bonus: The keeper determines the collateralSeized amount using the bonus: collateralSeized = debtToCover / (oraclePrice * (1 - liquidationBonus)).

Tip: The liquidation bonus must outweigh the gas cost and any slippage for the transaction to be profitable.

solidityCopy
// Simplified logic from a typical liquidation function
function calculateLiquidationAmount(
    uint256 debtValue,
    uint256 collateralValue,
    uint256 liquidationBonus // e.g., 1100 for a 10% bonus (1100/1000 = 1.1)
) internal pure returns (uint256 debtToCover, uint256 collateralSeized) {
    // ... calculation logic here
}

Detailed Instructions

The keeper constructs and broadcasts a transaction calling the protocol's specific liquidation function. On Aave V3, this is the liquidationCall() function. The transaction must be submitted with sufficient gas and a competitive gas price to outbid other keepers in the same block—a process known as MEV (Maximal Extractable Value) searcher behavior.

• Sub-step 1: Build Transaction: The keeper encodes the call with parameters: collateral asset address (e.g., 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 for WETH), debt asset address, user address, debt to cover, and receiveAToken flag.
• Sub-step 2: Estimate Gas & Profit: The keeper simulates the transaction using eth_estimateGas to ensure it won't revert and calculates net profit: (Collateral Discount Value) - (Gas Cost in ETH * ETH Price).
• Sub-step 3: Submit to Network: The keeper sends the signed transaction, often via a private RPC or flashbots bundle to avoid front-running.

Tip: Using a private transaction relay or a service like Flashbots Protect can prevent costly failed transactions from being seen and copied by competitors.

javascriptCopy
// Example transaction call to Aave V3 Pool contract
const tx = await poolContract.liquidationCall(
    '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH collateral
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC debt
    '0xUnsafeUserAddress',
    5000000000, // debtToCover in USDC units (e.g., $5000)
    false // do not receive aToken
);

Detailed Instructions

After a successful liquidation, the keeper receives the discounted collateral tokens. The final step involves converting this collateral into the debt asset (or stablecoin) to realize the profit and repay any flash loans used. This often triggers a decentralized exchange (DEX) arbitrage loop.

• Sub-step 1: Swap Collateral for Debt Asset: The keeper immediately swaps the seized WETH for USDC on a DEX like Uniswap V3 to lock in the discount and hedge price risk. A common command is to call swapExactTokensForTokens on a router contract.
• Sub-step 2: Repay Flash Loan (if used): If the liquidation was funded via a flash loan from a protocol like Balancer or Dydx, the keeper must repay the loan plus fees within the same transaction.
• Sub-step 3: Verify Protocol Health: The keeper (or a separate monitoring service) confirms the liquidated user's health factor is now above the threshold (e.g., >1.0), restoring safety to the protocol.

Tip: The entire process—from flash loan to swap—is often bundled into a single atomic transaction using a smart contract to eliminate capital risk.

solidityCopy
// Example flow within a keeper's contract
function executeLiquidation(address user) external {
    // 1. Take flash loan of USDC
    // 2. Call pool.liquidationCall(...)
    // 3. Swap received WETH for USDC on Uniswap
    // 4. Repay flash loan
    // 5. Send profit to keeper
}

Detailed Instructions

A Keeper is an off-chain bot that monitors on-chain conditions and executes transactions to maintain the health of a lending protocol. Its primary roles are liquidations (repaying undercollateralized loans to seize collateral) and interest rate updates (applying accrued interest to user accounts). The keeper earns a liquidation bonus or gas reimbursement for successful transactions. To be profitable, the keeper's gas costs must be lower than its rewards. You must understand the specific protocol's smart contracts, such as the Comptroller in Compound or the LendingPool in Aave, which emit events when a loan becomes eligible for liquidation (e.g., when the Health Factor drops below 1.0).

• Sub-step 1: Study the Protocol Documentation: Review the official docs for the target protocol (e.g., Aave V3, Compound V3) to identify the exact functions for liquidations and updates.
• Sub-step 2: Analyze the Smart Contracts: Use a block explorer like Etherscan to examine the contract ABI and identify key functions like liquidateBorrow(address borrower, uint repayAmount, address cTokenCollateral).
• Sub-step 3: Calculate Profitability: Model gas costs against potential rewards. A loan might have a collateral factor of 75% and a liquidation incentive of 8%, meaning you can seize $108,000 worth of collateral for repaying a $100,000 debt.

Tip: Start by monitoring protocols on testnets (like Goerli or Sepolia) to understand the event flow without financial risk.

Detailed Instructions

You need a reliable connection to the blockchain and a framework for building your bot. The core infrastructure includes an Ethereum node provider (e.g., Alchemy, Infura, or a self-hosted node), a wallet with funded ETH for gas, and a scripting environment. Most keepers are built using TypeScript/JavaScript with Ethers.js or Python with Web3.py. You will also need an event listener to monitor the blockchain for specific log emissions. For production, consider using a Keeper network like Chainlink Keepers or Gelato, which can automate transaction execution based on predefined conditions, handling gas optimization and reliability.

• Sub-step 1: Choose a Node Provider: Sign up for a service like Alchemy and obtain your HTTP WebSocket endpoint (e.g., wss://eth-mainnet.g.alchemy.com/v2/YOUR_API_KEY).
• Sub-step 2: Set Up a Wallet: Create a new wallet using ethers and fund it. Securely store your private key in an environment variable.

javascriptCopy
const { Wallet } = require('ethers');
const provider = new ethers.providers.WebSocketProvider(ALCHEMY_WSS);
const wallet = new Wallet(process.env.PRIVATE_KEY, provider);

• Sub-step 3: Install Dependencies: Initialize a Node.js project and install ethers and dotenv.

Tip: Use a service with high uptime and archive data access to ensure you don't miss any events. Consider setting up alerting for node health.

Detailed Instructions

The core of your keeper is the logic that filters blockchain events and decides when to act. You must listen for events like LiquidationCall (Aave) or LiquidateBorrow (Compound). When an event is detected, your bot must fetch the current state of the loan by calling view functions on the protocol contracts to verify it is still undercollateralized. Calculate the maximum repayable amount and the liquidation bonus. A critical check is the close factor, which may limit the percentage of a loan you can liquidate in one transaction (e.g., 50% in Compound). Your code must also simulate the transaction using eth_call to estimate gas and ensure profitability before broadcasting.

• Sub-step 1: Create the Event Filter: Define the filter for the specific event from the protocol's contract address.

javascriptCopy
const liquidationFilter = {
    address: '0x7d2768dE32b0b80b7a3454c06BdAc94A69DDc7A9', // Aave V2 LendingPool
    topics: [ethers.utils.id('LiquidationCall(address,address,address,uint256,address,bool)')]
};

• Sub-step 2: Fetch Loan Health Data: Call getUserAccountData(userAddress) on the Aave protocol to get the current health factor.
• Sub-step 3: Build and Simulate the Transaction: Construct the liquidation transaction data and use provider.call() to simulate it, checking for errors and estimating gas.

Tip: Implement robust error handling for failed simulations and revert reasons. Use a gas estimation multiplier (e.g., 1.2x) to account for volatility.

Detailed Instructions

Execution in a competitive keeper environment requires speed and gas optimization. You must broadcast your transaction with a competitive gas price to be included in a block before others. Use a gas station API or the provider's getFeeData() to get current base fee and priority fee (tip). Consider using a flashbots bundle or similar MEV-protected relay to submit transactions privately, preventing front-running. After sending, monitor the transaction receipt for status (1 for success, 0 for failure). If it fails, analyze the revert reason and adjust your logic. Keep detailed logs of all attempts, profits, and losses for accounting and strategy refinement.

• Sub-step 1: Set Dynamic Gas Parameters: Fetch network conditions and set a priority fee that is 10-20% above the estimated market rate to increase speed.

javascriptCopy
const feeData = await provider.getFeeData();
const tx = {
    to: LENDING_POOL_ADDRESS,
    data: liquidateCalldata,
    gasLimit: 500000,
    maxPriorityFeePerGas: feeData.maxPriorityFeePerGas.mul(110).div(100), // +10%
    maxFeePerGas: feeData.maxFeePerGas
};

• Sub-step 2: Submit the Transaction: Send the signed transaction using your wallet and capture the transaction hash.
• Sub-step 3: Monitor and Confirm: Wait for at least 6 block confirmations on Ethereum mainnet before considering the transaction final and logging the profit.

Tip: For time-sensitive liquidations, consider deploying your keeper logic as a smart contract on a Layer 2 or sidechain with lower latency and fees, such as Arbitrum or Optimism.

Detailed Instructions

Deploy your keeper script to a reliable server (e.g., AWS EC2, Google Cloud) or use a serverless function with a cron trigger. Ensure it runs continuously with a process manager like PM2. Implement comprehensive logging (using Winston or similar) to record all monitored events, transaction attempts, and balance changes. Set up alerting (via Discord, Telegram, or PagerDuty) for critical failures, such as the bot wallet running low on ETH for gas or the node connection dropping. Regularly update your bot to accommodate protocol upgrades (new contract deployments) and changes to economic parameters like liquidation bonuses. Periodically review your profitability and adjust your gas bidding strategy based on network congestion.

• Sub-step 1: Containerize the Application: Use Docker to create a consistent deployment environment. Define the necessary environment variables in a docker-compose.yml file.
• Sub-step 2: Set Up Logging and Metrics: Log all actions to a file and a service like Datadog. Track key metrics: liquidation_opportunities_found, transactions_sent, total_profit_eth.
• Sub-step 3: Create Health Checks: Implement an HTTP endpoint that returns the bot's status (wallet balance, last block processed, uptime) and integrate it with a monitoring service.

Tip: Maintain a separate 'treasury' wallet to periodically sweep profits from your operational wallet, minimizing the exposure of your capital.