By name: keeperhub-plugins-ajna description: Production-grade v1.0.0 elite guide to Ajna Protocol on KeeperHub.
Ajna Protocol
Overview
Documentation for Ajna Protocol integration and usage within the KeeperHub ecosystem.
Ajna is a permissionless, oracle-free lending protocol. This plugin provides actions for liquidation keeper operations (kick, bucket-take, settle, withdraw bonds) and vault keeper operations (drain, move liquidity, buffer management) across two lending pools on Base: cbBTC/usBTCd and usBTCd/webmx. All read actions work without credentials. Write actions require a connected wallet. Supported chains: Base (8453) only.
Get Auction Status
Get the current auction state for a borrower across any Ajna pool. Returns kick time, collateral, debt to cover, price, neutral price, and bond factor. Inputs: Outputs: When to use: Check whether an auction is active and what price it is currently at before deciding to take. Use in combination with Pool Kick and Pool Bucket Take to build a complete liquidation keeper workflow.
Get HPB Index
Get the highest price bucket index currently active in an Ajna pool. Inputs: Outputs: When to use: Determine where the highest-priced liquidity sits. Useful as an input to bucket take operations and for monitoring pool health.
Get Pool LUP
Get the Lowest Utilized Price of an Ajna pool. Inputs: Outputs: When to use: Monitor the pool’s liquidity utilization level. The LUP determines whether borrowers are collateralized and eligible for kicking.
Get Pool HTP
Get the Highest Threshold Price of an Ajna pool. Inputs: Outputs: When to use: Monitor the pool’s highest threshold price to identify borrowers near liquidation. Compare against LUP to assess overall pool risk.
Get Borrower Info
Get complete loan information for a specific borrower in an Ajna pool. Inputs: Outputs: When to use: Inspect a specific borrower’s position before deciding to kick them. Compare threshold price against LUP to confirm they are eligible for liquidation.
Price to Bucket Index
Convert a WAD-denominated price to the corresponding Ajna bucket index. Inputs: Outputs: When to use: Translate a price value into a bucket index when configuring vault operations or targeting a specific price range for bucket take.
Bucket Index to Price
Convert an Ajna bucket index to its corresponding WAD-denominated price. Inputs: Outputs: When to use: Look up the price represented by a given bucket index. Useful for display and for verifying bucket positions in vault workflows.
Get Deposit Index
Get the bucket index that contains a given amount of deposit for an Ajna pool. Inputs: Outputs: When to use: Find which bucket holds enough deposit to cover a given debt level. Used to select the correct limit index when kicking borrowers.
Pool 1 Kicker Info
Get the claimable and locked bond amounts for a kicker address in the cbBTC/usBTCd pool. Inputs: Outputs: When to use: Check how much bond is available to withdraw after auctions complete. Use before calling Pool 1 Withdraw Bonds to confirm the claimable amount.
Pool 1 Auction Info
Get full auction details for a specific borrower in the cbBTC/usBTCd pool. Inputs: Outputs: When to use: Verify auction state and timing before taking or settling. Check kick time to determine how long the auction has been running.
Pool 1 Bucket Info
Get information for a specific bucket by index in the cbBTC/usBTCd pool. Inputs: Outputs: When to use: Inspect liquidity depth at a target bucket before executing a bucket take or move operation.
Pool 1 Inflator Info
Get the pool inflator and last update timestamp for the cbBTC/usBTCd pool. Inputs: None Outputs: When to use: Monitor how long since interest was last accrued. Use to decide when to call Pool 1 Update Interest.
Pool 1 Kick
Kick an undercollateralized borrower to initiate a liquidation auction in the cbBTC/usBTCd pool. The caller provides a bond and earns rewards if the auction clears at or above the neutral price. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Start a liquidation when a borrower’s threshold price exceeds the LUP. Precede with Get Borrower Info and Get Pool LUP to confirm eligibility.
Pool 1 Bucket Take
Take collateral from an active liquidation auction using bucket liquidity in the cbBTC/usBTCd pool. LP holders in the target bucket receive collateral in exchange for their quote tokens. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Execute a liquidation take using existing bucket liquidity. Call after confirming an active auction via Pool 1 Auction Info or Get Auction Status.
Pool 1 Settle
Settle a completed liquidation auction in the cbBTC/usBTCd pool, distributing remaining collateral and debt across buckets. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Finalize an auction after the auction period has ended or all debt has been covered. Settle unlocks bonded kicker funds.
Pool 1 Withdraw Bonds
Withdraw claimable kicker bond from the cbBTC/usBTCd pool to a recipient address. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Reclaim kicker rewards after successful liquidations. Call Pool 1 Kicker Info first to confirm the claimable balance.
Pool 1 Update Interest
Accrue and update the interest rate for the cbBTC/usBTCd pool. Inputs: None Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Keep pool interest up to date. Call periodically or before executing pool operations to ensure accurate debt accounting.
Pool 2 Kicker Info
Get the claimable and locked bond amounts for a kicker address in the usBTCd/webmx pool. Inputs: Outputs: When to use: Check how much bond is available to withdraw after auctions complete in Pool 2. Use before calling Pool 2 Withdraw Bonds.
Pool 2 Auction Info
Get full auction details for a specific borrower in the usBTCd/webmx pool. Inputs: Outputs: When to use: Verify auction state for Pool 2 before taking or settling. Check kick time to determine elapsed auction duration.
Pool 2 Bucket Info
Get information for a specific bucket by index in the usBTCd/webmx pool. Inputs: Outputs: When to use: Inspect liquidity at a target bucket in Pool 2 before bucket take or liquidity movement operations.
Pool 2 Inflator Info
Get the pool inflator and last update timestamp for the usBTCd/webmx pool. Inputs: None Outputs: When to use: Monitor interest accrual staleness for Pool 2. Use to decide when to call Pool 2 Update Interest.
Pool 2 Kick
Kick an undercollateralized borrower to initiate a liquidation auction in the usBTCd/webmx pool. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Start a liquidation in Pool 2 when a borrower’s threshold price exceeds the LUP.
Pool 2 Bucket Take
Take collateral from an active liquidation auction using bucket liquidity in the usBTCd/webmx pool. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Execute a liquidation take in Pool 2 using existing bucket liquidity.
Pool 2 Settle
Settle a completed liquidation auction in the usBTCd/webmx pool. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Finalize an auction in Pool 2 after the auction period ends or all debt is covered.
Pool 2 Withdraw Bonds
Withdraw claimable kicker bond from the usBTCd/webmx pool. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Reclaim kicker rewards from Pool 2 after successful liquidations.
Pool 2 Update Interest
Accrue and update the interest rate for the usBTCd/webmx pool. Inputs: None Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Keep Pool 2 interest up to date. Call periodically or before pool operations.
Vault 1 Is Paused
Check whether the cbBTC/usBTCd vault is currently paused. Inputs: None Outputs: When to use: Gate vault operations on pause state. If the vault is paused, skip drain, move, and buffer operations to avoid reverts.
Vault 1 Get Buckets
Get all active bucket indices currently held in the cbBTC/usBTCd vault. Inputs: None Outputs: When to use: Enumerate all buckets the vault holds positions in. Use as input to LP-to-value or drain operations when iterating over all positions.
Vault 1 Total Assets
Get the total quote token assets managed by the cbBTC/usBTCd vault. Inputs: None Outputs: When to use: Monitor the vault’s total value. Use in rebalancing workflows to compare against buffer total and calculate target allocations.
Vault 1 LP to Value
Convert an LP amount to its quote token value for a specific bucket in the cbBTC/usBTCd vault. Inputs: Outputs: When to use: Calculate the current quote token value of a bucket position before moving or draining it.
Vault 1 Drain Bucket
Drain all liquidity from a specific bucket in the cbBTC/usBTCd vault, withdrawing all quote tokens and collateral. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Remove liquidity from an out-of-range or empty bucket to consolidate vault positions.
Vault 1 Move Liquidity
Move liquidity from one bucket to another within the cbBTC/usBTCd vault. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Rebalance vault liquidity between price buckets. Use when the LUP shifts and optimal bucket range changes.
Vault 1 Move From Buffer
Move liquidity from the buffer contract into a pool bucket in the cbBTC/usBTCd vault. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Deploy buffered capital into the pool when the buffer ratio exceeds the target. Use Vault 1 Buffer Total and Vault 1 Buffer Ratio to determine the amount to deploy.
Vault 1 Move To Buffer
Move liquidity from a pool bucket into the buffer in the cbBTC/usBTCd vault. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Pull liquidity from the pool into the buffer when the buffer ratio falls below the target. Provides dry powder for deposit redemptions.
Vault 2 Is Paused
Check whether the usBTCd/webmx vault is currently paused. Inputs: None Outputs: When to use: Gate vault operations on pause state for Vault 2.
Vault 2 Get Buckets
Get all active bucket indices currently held in the usBTCd/webmx vault. Inputs: None Outputs: When to use: Enumerate all active positions in Vault 2 for iteration and value calculations.
Vault 2 Total Assets
Get the total quote token assets managed by the usBTCd/webmx vault. Inputs: None Outputs: When to use: Monitor the total value of Vault 2. Use in rebalancing comparisons against buffer total.
Vault 2 LP to Value
Convert an LP amount to its quote token value for a specific bucket in the usBTCd/webmx vault. Inputs: Outputs: When to use: Calculate the current quote token value of a Vault 2 bucket position.
Vault 2 Drain Bucket
Drain all liquidity from a specific bucket in the usBTCd/webmx vault. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Remove liquidity from an out-of-range bucket in Vault 2.
Vault 2 Move Liquidity
Move liquidity from one bucket to another within the usBTCd/webmx vault. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Rebalance Vault 2 liquidity when the pool’s price range shifts.
Vault 2 Move From Buffer
Move liquidity from the buffer into a pool bucket in the usBTCd/webmx vault. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Deploy buffered capital in Vault 2 when buffer ratio is above target.
Vault 2 Move To Buffer
Move liquidity from a pool bucket into the buffer in the usBTCd/webmx vault. Inputs: Outputs: success, transactionHash, transactionLink, error
success
transactionHash
transactionLink
error
When to use: Pull liquidity from Vault 2 into the buffer when buffer ratio falls below target.
Vault 1 Buffer Ratio
Get the target buffer ratio configured for the cbBTC/usBTCd vault. Inputs: None Outputs: When to use: Read the target ratio before deciding whether to call Move From Buffer or Move To Buffer. Compare against current buffer total divided by total assets.
Vault 1 Min Bucket Index
Get the minimum allowed bucket index for the cbBTC/usBTCd vault. Inputs: None Outputs: When to use: Validate target bucket indices before move operations to ensure they are within the allowed range.
Vault 2 Buffer Ratio
Get the target buffer ratio configured for the usBTCd/webmx vault. Inputs: None Outputs: When to use: Read the target ratio for Vault 2 before buffer rebalancing decisions.
Vault 2 Min Bucket Index
Get the minimum allowed bucket index for the usBTCd/webmx vault. Inputs: None Outputs: When to use: Validate target bucket indices for Vault 2 move operations.
Vault 1 Buffer Total
Get the total liquidity held in the cbBTC/usBTCd buffer contract. Inputs: None Outputs: When to use: Read current buffer balance before rebalancing. Divide by Vault 1 Total Assets to compute the current buffer ratio and compare against the target.
Vault 2 Buffer Total
Get the total liquidity held in the usBTCd/webmx buffer contract. Inputs: None Outputs: When to use: Read the current buffer balance for Vault 2 before deciding on buffer rebalancing operations.
Automated Liquidation Keeper (Pool 1)
Schedule (every 5 min) -> Ajna: Get Borrower Info -> Ajna: Get Pool LUP -> Condition (thresholdPrice > lup) -> Ajna: Pool 1 Kick
Schedule (every 5 min) -> Ajna: Get Borrower Info -> Ajna: Get Pool LUP -> Condition (thresholdPrice > lup) -> Ajna: Pool 1 Kick
Periodically check a borrower’s threshold price against the pool’s LUP. If the borrower is undercollateralized, kick them to start the liquidation auction.
Liquidation Settle and Bond Withdrawal
Webhook (auction ended) -> Ajna: Pool 1 Auction Info -> Ajna: Pool 1 Settle -> Ajna: Pool 1 Kicker Info -> Condition (claimable > 0) -> Ajna: Pool 1 Withdraw Bonds -> Discord: Send Message
Webhook (auction ended) -> Ajna: Pool 1 Auction Info -> Ajna: Pool 1 Settle -> Ajna: Pool 1 Kicker Info -> Condition (claimable > 0) -> Ajna: Pool 1 Withdraw Bonds -> Discord: Send Message
On auction completion webhook, settle the auction, check for claimable bond, withdraw it, and send a Discord notification with the transaction link.
Vault Buffer Rebalancing (Vault 1)
Schedule (hourly) -> Ajna: Vault 1 Total Assets -> Ajna: Vault 1 Buffer Total -> Ajna: Vault 1 Buffer Ratio -> Condition (bufferTotal / totalAssets < ratio) -> Ajna: Vault 1 Move To Buffer
Schedule (hourly) -> Ajna: Vault 1 Total Assets -> Ajna: Vault 1 Buffer Total -> Ajna: Vault 1 Buffer Ratio -> Condition (bufferTotal / totalAssets < ratio) -> Ajna: Vault 1 Move To Buffer
Hourly check whether the buffer has fallen below its target ratio and automatically move liquidity from a pool bucket into the buffer to restore the target.
Vault Pause Guard
Schedule (every 1 min) -> Ajna: Vault 1 Is Paused -> Condition (isPaused == false) -> Ajna: Vault 1 Get Buckets -> Ajna: Vault 1 LP to Value -> Ajna: Vault 1 Move Liquidity
Schedule (every 1 min) -> Ajna: Vault 1 Is Paused -> Condition (isPaused == false) -> Ajna: Vault 1 Get Buckets -> Ajna: Vault 1 LP to Value -> Ajna: Vault 1 Move Liquidity
Check vault pause state before running any rebalancing operations. If the vault is paused, the condition gate stops the workflow without executing writes.
All contracts are deployed on Base only. Cross-chain operation is not supported. Aerodrome Chainlink