Automated Liquidation Protection

What this template does

This CRE workflow implements a confidential liquidation-defense system for DeFi lending positions. It runs on a cron schedule, continuously evaluates a borrower's collateral health, and automatically executes defensive actions before a position reaches the liquidation threshold. Exchange credentials, LLM API keys, risk thresholds, and execution preferences all remain protected inside confidential execution.

Data flow:

1. Fetch current risk state: collateral and debt pricing, health factor, liquidation proximity, LTV, liquidation threshold, and market volatility.
2. Load policy parameters from secrets: reserve deployment caps, minimum reserve balance, health factor targets, collateral and repayment limits, sequencing preference, and preferred venues.
3. Compute a composite risk score from proximity, LTV buffer, health factor, and volatility.
4. Send risk state and policy to an LLM reasoning model to select and sequence defensive actions.
5. Enforce all policy constraints against the proposed action plan before execution.
6. Execute the approved defense plan through the exchange or DeFi API.

If liquidation proximity is above the warning threshold (the position has sufficient buffer), the workflow exits with SAFE and takes no action.

Defensive Actions and Policy Constraints

Defensive action types

Policy constraints

All policy values are loaded from secrets at runtime. Reserve-based constraints are enforced as hard limits before any execution call. Sequencing and venue preferences guide the LLM action plan.

Risk signals monitored

Risk score

The workflow computes a composite risk score to guide action selection:

proximityRisk  = max(0, warningThreshold − liquidationProximity) × 5
ltvBufferRisk  = max(0, LTV − (liquidationThreshold − 5)) × 2
healthRisk     = max(0, minHealthFactor − healthFactor) × 100
volatilityRisk = volatilityIndex × 25
riskScore      = proximityRisk + ltvBufferRisk + healthRisk + volatilityRisk

Prerequisites

• Bun runtime
• CRE CLI (cre)
• A DeFi risk monitoring or exchange API that exposes position health signals
• An LLM API endpoint for reasoning (e.g., an OpenAI-compatible endpoint)

Configuration

The workflow ships with two config files:

• automated-liquidation-protection-ts/config.staging.json (TypeScript) and automated-liquidation-protection-go/config.staging.json (Go): targets mock server endpoints
• automated-liquidation-protection-ts/config.production.json (TypeScript) and automated-liquidation-protection-go/config.production.json (Go): same structure with empty URLs for you to populate

Key fields:

Secrets

Copy .env.example to .env and populate all values before running locally. The workflow enforces a strict limit of exactly 11 secrets per invocation.

Quick start

TypeScript

Run all commands from the automated-liquidation-protection directory (the project root).

1. Install dependencies

   cd automated-liquidation-protection-ts && bun install && cd ..
   

2. Create environment file

   cp .env.example .env
   

3. Start mock server

   cd automated-liquidation-protection-ts && bun run mock:server
   

4. In another terminal, run checks and simulate

   cd automated-liquidation-protection-ts
   bun run typecheck
   bun run test
   cd .. && cre workflow simulate ./automated-liquidation-protection-ts --project-root ./ --target=staging-settings --env ./.env
   

Go

Run all commands from the automated-liquidation-protection directory (the project root).

1. Create environment file

   cp .env.example .env
   

2. Start the mock server from the TypeScript directory (requires Node or Bun)

   cd automated-liquidation-protection-ts && bun run mock:server
   

3. In another terminal, run checks and simulate

   cd automated-liquidation-protection-go
   go vet ./...
   go test ./...
   cd .. && cre workflow simulate ./automated-liquidation-protection-go --project-root ./ --target=staging-settings --env ./.env
   

Production checklist

• Populate config.production.json with real mock_base_url and openai_url.
• Register all 11 secrets in the CRE secrets manager and verify secret IDs match those defined in config.production.json under secrets_ids.
• Set MOCK_LIQUIDATION_MIN_STABLECOIN_RESERVE_BALANCE to a value that provides a meaningful reserve buffer for your position size.
• Set CRE_ETH_PRIVATE_KEY if any defensive action routes through on-chain execution.
• Confirm the exchange API returns the expected risk state schema before deploying.
• Run bun run typecheck && bun run test (TypeScript) or go vet ./... && go test ./... (Go) before registering.
• Run cre workflow simulate against production endpoints to validate end-to-end behavior.
• Register the workflow:
  • TypeScript: cre workflow register ./automated-liquidation-protection-ts --project-root ./ --target=production-settings
  • Go: cre workflow register ./automated-liquidation-protection-go --project-root ./ --target=production-settings

Troubleshooting

Reserve floor breach error

If you see action X breaches reserve floor: projected Y < floor Z, the proposed action would reduce stablecoin reserves below the configured minimum. Increase MOCK_LIQUIDATION_MIN_STABLECOIN_RESERVE_BALANCE, reduce MOCK_LIQUIDATION_MAX_STABLECOIN_RESERVE_DEPLOYMENT, or reduce position size.

Secrets must be finite numbers

If you see secret X must be a finite number, one of the numeric policy secrets was set to a non-numeric value. Confirm that all numeric environment variables in .env are valid floats or integers (e.g., 1.25, not "n/a").

LLM response format mismatch

If the LLM response cannot be parsed, the model must return either an output_text field or a nested output[].content[].text structure. If neither is present, you will see the error openai response did not contain output_text. Check your LLM endpoint logs or mock server configuration to verify the response format.

HTTP request failures

If you see request failed status=4XX, confirm the mock server is running (bun run mock:server) and that the API keys in .env match the values expected by the mock server.

Workflow logs liquidation-no-action

This is expected behavior when the position is healthy. The log includes proximity=X threshold=Y reason=Z to confirm the position state and why no action was taken.