Morpho Blue Liquidation Bot — Etherlink

Liquidation bot targeting xU3O8 (Uranium) collateral markets on Morpho Blue deployed on Etherlink.

Architecture

tez_newPreconfirmedReceipts (WebSocket)
  |
  |-- Oracle events (ValueUpdate, PriceFeedUpdate)
  |     -> fetch oracle prices -> check all positions
  |
  +-- Morpho events (Borrow, Repay, SupplyCollateral, ...)
        -> update local state -> check all positions

The bot maintains a full event-sourced replica of all position and market state from on-chain events. Health checks are pure local computation -- no per-borrower RPC calls.

Components

• Rust bot -- event-sourced position tracking, oracle monitoring, liquidation detection and execution
  • main.rs -- orchestration, WS receipt loop, .env loading
  • state.rs -- event-sourced State, position/market tracking, health checks, LIF computation
  • executor.rs -- uranium-v3 swap encoding, transaction building/signing, liquidation execution
  • rpc.rs -- Blockscout historical replay, oracle price fetching, market config loading
  • ws.rs -- receipt stream types, oracle/Morpho log decoders
  • constants.rs -- contract addresses, market IDs, chain config
• Solidity contract (src/MorphoFlashLiquidator.sol) -- flash liquidation via Morpho callback, swaps collateral for USDC through uranium-v3

Supported Markets

6 xU3O8/USDC markets using RedStone + Pyth oracle feeds:

LLTV	Oracle	Markets
62.5%	Wrapper / Direct	#8, #11
77%	Wrapper / Direct	#7, #10
86%	Wrapper / Direct	#6, #9

Quick Start

Prerequisites

• Rust 1.94+
• Foundry (forge, cast)

1. Build

cargo build --release
forge install foundry-rs/forge-std
forge build

2. Configure

Create a .env file at the project root:

ETHERLINK_WS_URL=wss://your-node/ws
ETHERLINK_RPC_URL=https://your-node
PRIVATE_KEY=0x...
LIQUIDATOR_CONTRACT=0x...

Variable	Required	Description
ETHERLINK_WS_URL	Yes	WebSocket endpoint supporting tez_newPreconfirmedReceipts
ETHERLINK_RPC_URL	Yes	HTTP JSON-RPC endpoint
PRIVATE_KEY	No	EOA private key for signing liquidation txs
LIQUIDATOR_CONTRACT	No	Deployed MorphoFlashLiquidator address

3. Deploy the liquidator contract

forge script script/Deploy.s.sol \
  --rpc-url $ETHERLINK_RPC_URL \
  --broadcast --private-key $PRIVATE_KEY

Copy the deployed address into LIQUIDATOR_CONTRACT in .env.

4. Run

cargo run --release

Without PRIVATE_KEY and LIQUIDATOR_CONTRACT, the bot runs in simulation mode: it monitors all positions, logs liquidation opportunities with expected profit, but does not send transactions.

With both set, the bot automatically executes flash liquidations when profitable opportunities are detected.

To see per-position health details:

RUST_LOG=morpho_liquidator=debug cargo run --release

How It Works

1. Startup: queries market configs from Morpho, replays all historical events from Blockscout to reconstruct position state, fetches oracle prices
2. Listening: subscribes to tez_newPreconfirmedReceipts WebSocket stream
3. On oracle price update: re-fetches oracle prices, checks all positions for liquidatability
4. On Morpho event: updates local state (positions, market totals), re-checks health
5. On liquidatable position: logs opportunity; if execution mode is enabled, encodes a uranium-v3 swap and sends a flash liquidation transaction

Flash Liquidation Flow

The MorphoFlashLiquidator contract enables zero-capital liquidations:

1. Bot calls liquidate() on our contract
2. Contract calls morpho.liquidate() with callback data
3. Morpho transfers seized xU3O8 to our contract
4. In onMorphoLiquidate callback: swap xU3O8 -> USDC via uranium-v3, approve Morpho to pull repayment
5. Profit (USDC) transferred to owner

Reference

• morpho_blue_etherlink_markets.md -- full market data, oracle architecture, historical liquidations
• liquidation_mechanics.md -- LLTV, LIF, bad debt, health check math
• strategy_decisions.md -- design decisions and tradeoffs