Community Liquidator (Rust)

Overview

Community Liquidator is a Rust-based application designed to monitor and liquidate unhealthy loans on the Base blockchain. It can run as an AWS Lambda function on a schedule or as a standalone application with a built-in scheduler.

Key Features:

• Automated loan health monitoring
• Configurable health factor thresholds
• Built-in 3-hour execution interval
• AWS Lambda and standalone operation modes
• Optimized for performance and reliability
• Comprehensive logging and error handling

Architecture

Core Components

Component	File	Description
Main Entry Point	src/main.rs	Lambda handler and local execution logic
Liquidation Engine	src/liquidation.rs	Core liquidation logic and blockchain interaction
Database Operations	src/db.rs	Tracking of processed loans
Utility Functions	src/utils.rs	Helper functions and parameter generation

Workflow

1. Initialization

   • Load configuration from environment variables
   • Connect to the Base blockchain
   • Initialize the local database

2. Loan Discovery

   • Query the blockchain for all active loans
   • Filter out previously processed loans

3. Health Assessment

   • For each loan, evaluate:
     • Current health factor
     • Protocol liquidation status
     • Comparison against configured thresholds

4. Liquidation Execution

   • Generate appropriate liquidation parameters
   • Submit liquidation transactions
   • Monitor transaction confirmation
   • Record successful liquidations

Setup Guide

Prerequisites

• Rust: Latest stable version
• Cargo: Rust package manager
• SQLite: For local database operations
• Base Blockchain: Access to RPC endpoint
• AWS CLI: (Optional) For Lambda deployment

Environment Configuration

1. Create Environment File

   cp .env.example .env

2. Configure Required Variables

   # Blockchain Configuration
   DIAMOND_ADDRESS=<contract-address>
   NODE_URL=<base-rpc-endpoint>
   
   # Account Configuration
   ACCOUNT_ADDRESS=<wallet-address>
   ACCOUNT_PK=<private-key>
   
   # Liquidation Parameters
   MIN_HEALTH=1.45
   PROMISE_LIMIT=5
   

Building the Application

cargo build --release

The optimized binary will be available at target/release/community-liquidator-rs.

Usage

Local Execution

The application includes a built-in scheduler that runs every 3 hours:

cargo run --release

Features:

• Immediate initial execution
• Automatic 3-hour interval scheduling
• Detailed logging with timestamps
• Graceful shutdown with Ctrl+C

Sample Output

INFO: Starting liquidation bot with 3-hour interval
INFO: Press Ctrl+C to gracefully shut down the bot
INFO: Running liquidation check at startup (2025-03-12T12:46:54+05:30)
INFO: Liquidation bot started
INFO: Running check at 2025-03-12T12:46:55+05:30
INFO: No liquidable loans found
INFO: Liquidation check completed in 1.23s

AWS Lambda Deployment

Testing with Lambda Emulator

1. Install the AWS Lambda Runtime Interface Emulator

   brew install aws-lambda-rie

2. Run with Lambda Runtime

   cargo lambda watch

Deploying to AWS

1. Build for Lambda

   cargo lambda build --release

2. Deploy to AWS

   cargo lambda deploy --iam-role <lambda-execution-role-arn>

AWS Configuration

EventBridge Scheduling

To run the liquidator on a 3-hour schedule in AWS:

1. Create an EventBridge Rule

   {
     "name": "community-liquidator-schedule",
     "schedule-expression": "rate(3 hours)",
     "state": "ENABLED",
     "targets": [
       {
         "id": "1",
         "arn": "arn:aws:lambda:REGION:ACCOUNT_ID:function:community-liquidator-rs"
       }
     ]
   }

2. Configure Lambda Permissions

   aws lambda add-permission \
     --function-name community-liquidator-rs \
     --statement-id EventBridgeInvoke \
     --action lambda:InvokeFunction \
     --principal events.amazonaws.com \
     --source-arn <eventbridge-rule-arn>

IAM Requirements

The Lambda function requires an IAM role with:

• Basic Execution Role: CloudWatch Logs access
• Optional: Additional permissions for monitoring or alerting

Lambda Environment Variables

Variable	Description	Example
DIAMOND_ADDRESS	Protocol contract address	0x123...abc
NODE_URL	Base RPC endpoint	https://mainnet.base.org
ACCOUNT_ADDRESS	Liquidator wallet address	0xabc...123
ACCOUNT_PK	Liquidator private key	0x123...
MIN_HEALTH	Health factor threshold	1.45
PROMISE_LIMIT	Concurrent RPC calls	5

Docker Deployment to AWS Lambda

This project includes scripts to build and deploy the liquidation bot as a Docker container to AWS Lambda. This approach offers better versioning, distribution through ECR, and simplified dependency management.

Prerequisites

• Docker installed and running
• AWS CLI configured with appropriate permissions
• IAM role for Lambda execution with necessary permissions

Building the Docker Image

Use the provided build script to create a Docker image:

./scripts/build.sh --arch arm64 --tag v1.0.0

Options:

• --arch: Target architecture (amd64 or arm64), default: amd64
• --tag: Image tag, default: latest
• --ecr: ECR repository name (if pushing to ECR)
• --region: AWS region for ECR, default: us-east-1

Deploying to AWS Lambda

Use the deployment script to build, push to ECR, and deploy to Lambda:

./scripts/deploy.sh --arch arm64 --tag v1.0.0 --region us-east-1 --function community-liquidator --memory 512 --timeout 900 --schedule "rate(3 hours)"

Options:

• --arch: Target architecture (amd64 or arm64), default: amd64
• --tag: Image tag, default: latest
• --region: AWS region, default: us-east-1
• --function: Lambda function name, default: community-liquidator
• --memory: Memory size in MB, default: 256
• --timeout: Timeout in seconds, default: 900
• --schedule: CloudWatch Events schedule expression, default: rate(3 hours)

Environment Variables in Lambda

After deployment, configure the required environment variables in the AWS Lambda console or using the AWS CLI:

aws lambda update-function-configuration \
  --function-name community-liquidator \
  --environment "Variables={DIAMOND_ADDRESS=0x...,NODE_URL=https://...,ACCOUNT_ADDRESS=0x...,ACCOUNT_PK=0x...,MIN_HEALTH=1.45,PROMISE_LIMIT=5,RUST_LOG=info}" \
  --region us-east-1

Security Best Practices

• Store sensitive values like ACCOUNT_PK in AWS Secrets Manager and retrieve them at runtime
• Use IAM roles with minimal required permissions
• Enable AWS Lambda function URL authentication if exposing an HTTP endpoint
• Consider using AWS Parameter Store for environment-specific configuration