controller.lua

local coroutine = require "coroutine"
local bint = require ".bint"(1024)
local utils = require ".utils"
local json = require "json"

local liquidations = {}
local assertions = {}
local scheduler = {}
local oracle = {}
local tokens = {}
local queue = {}

-- oToken module ID
Module = Module or "C6CQfrL29jZ-LYXV2lKn09d3pBIM6adDFwWqh2ICikM"

-- oracle id and tolerance
Oracle = Oracle or "4fVi8P-xSRWxZ0EE0EpltDe8WJJvcD9QyFXMqfk-1UQ"
MaxOracleDelay = MaxOracleDelay or 1200000

-- admin addresses
Owners = Owners or {}

-- liquidops logo tx id
ProtocolLogo = ProtocolLogo or ""

-- holds all the processes that are part of the protocol
-- a member consists of the following fields:
-- - id: string (this is the address of the collateral supported by LiquidOps)
-- - ticker: string (the ticker of the collateral)
-- - oToken: string (the address of the oToken process for the collateral)
-- - denomination: integer (the denomination of the collateral)
---@type Friend[]
Tokens = Tokens or {}

-- queue for operations that change the user's position
---@type { address: string, origin: string }[]
Queue = Queue or {}

-- current timestamp
Timestamp = Timestamp or 0

-- cached auctions (position wallet address, timestamp when discovered)
---@type table<string, number>
Auctions = Auctions or {}

-- maximum and minimum discount that can be applied to a loan in percentages
MaxDiscount = MaxDiscount or 5
MinDiscount = MinDiscount or 1

-- the period till the auction reaches the minimum discount (market price)
DiscountInterval = DiscountInterval or 1000 * 60 * 60 -- 1 hour

PrecisionFactor = 1000000

-- minimum liquidation percentage (a liquidator is required to liquidate at least this percentage of the total loan)
MinLiquidationThreshold = MinLiquidationThreshold or 20

---@alias TokenData { ticker: string, denomination: number }
---@alias PriceParam { ticker: string, quantity: Bint?, denomination: number }
---@alias CollateralBorrow { token: string, ticker: string, quantity: string }
---@alias QualifyingPosition { target: string, depts: CollateralBorrow[], collaterals: CollateralBorrow[], discount: string }

Handlers.add(
 "setup-patching",
 function () return "continue" end,
 function (msg)
 ao.send({
 device = "patch@1.0",
 ["token-info"] = { name = "LiquidOps Controller" },
 oracle = Oracle,
 ["discount-config"] = {
 min = MinDiscount,
 max = MaxDiscount,
 interval = DiscountInterval
 },
 tokens = Tokens,
 queue = Queue,
 auctions = Auctions
 })
 end
)

Handlers.add(
 "sync-timestamp",
 function () return "continue" end,
 function (msg) Timestamp = msg.Timestamp end
)

Handlers.add(
 "info",
 { Action = "Info" },
 function (msg)
 msg.reply({
 Name = "LiquidOps Controller",
 Module = Module,
 Oracle = Oracle,
 ["Max-Discount"] = tostring(MaxDiscount),
 ["Min-Discount"] = tostring(MinDiscount),
 ["Discount-Interval"] = tostring(DiscountInterval),
 Data = json.encode(Tokens)
 })
 end
)

Handlers.add(
 "sync-auctions",
 Handlers.utils.hasMatchingTagOf("Action", { "Cron", "Get-Liquidations" }),
 function (msg)
 -- fetch prices first, so the processing of the positions won't be delayed
 local rawPrices = oracle.sync()

 -- generate position messages
 ---@type MessageParam[]
 local positionMsgs = {}

 for _, token in ipairs(Tokens) do
 table.insert(positionMsgs, { Target = token.oToken, Action = "Positions" })
 end

 -- get all user positions
 ---@type Message[]
 local rawPositions = scheduler.schedule(table.unpack(positionMsgs))

 -- protocol positions in USD
 ---@type table<string, { liquidationLimit: Bint, borrowBalance: Bint, debts: CollateralBorrow[], collaterals: CollateralBorrow[] }>
 local allPositions = {}
 local zero = bint.zero()

 -- add positions
 for _, market in ipairs(rawPositions) do
 ---@type boolean, table<string, { Capacity: string, ["Borrow-Balance"]: string, Collateralization: string, ["Liquidation-Limit"]: string }>
 local parsed, marketPositions = pcall(json.decode, market.Data)
 assert(parsed, "Could not parse market data for " .. market.From)

 local ticker = market.Tags["Collateral-Ticker"]
 local denomination = tonumber(market.Tags["Collateral-Denomination"]) or 0
 local collateral = utils.find(
 function (t) return t.oToken == market.From end,
 Tokens
 )

 -- add each position in the market by their usd value
 for address, position in pairs(marketPositions) do
 local posLiquidationLimit = bint(position["Liquidation-Limit"] or 0)
 local posBorrowBalance = bint(position["Borrow-Balance"] or 0)

 local hasCollateral = bint.ult(zero, posLiquidationLimit)
 local hasLoan = bint.ult(zero, posBorrowBalance)

 if hasCollateral or hasLoan then
 allPositions[address] = allPositions[address] or {
 liquidationLimit = zero,
 borrowBalance = zero,
 debts = {},
 collaterals = {}
 }

 -- add liquidation limit
 if hasCollateral and collateral ~= nil then
 allPositions[address].liquidationLimit = allPositions[address].liquidationLimit + oracle.getValue(
 rawPrices,
 posLiquidationLimit,
 ticker,
 denomination
 )
 table.insert(allPositions[address].collaterals, {
 token = collateral.id,
 ticker = ticker,
 quantity = position.Collateralization
 })
 end

 -- add borrow balance
 if hasLoan and collateral ~= nil then
 allPositions[address].borrowBalance = allPositions[address].borrowBalance + oracle.getValue(
 rawPrices,
 posBorrowBalance,
 ticker,
 denomination
 )
 table.insert(allPositions[address].debts, {
 token = collateral.id,
 ticker = ticker,
 quantity = position["Borrow-Balance"]
 })
 end
 end
 end
 end

 ---@type QualifyingPosition[]
 local qualifyingPositions = {}

 -- now find the positions that can be auctioned
 -- and update existing auctions
 for address, position in pairs(allPositions) do
 -- check if the position can be liquidated
 if bint.ult(position.liquidationLimit, position.borrowBalance) then
 -- add auction
 liquidations.addAuction(address, msg.Timestamp)

 -- calculate discount
 local discount = tokens.getDiscount(address)

 if msg.Tags.Action == "Get-Liquidations" then
 table.insert(qualifyingPositions, {
 target = address,
 debts = position.debts,
 collaterals = position.collaterals,
 discount = discount
 })
 end
 else
 -- remove auction, it is no longer necessary
 liquidations.removeAuction(address)
 end
 end

 if msg.Tags.Action == "Get-Liquidations" then
 msg.reply({
 Data = json.encode({
 liquidations = qualifyingPositions,
 tokens = Tokens,
 maxDiscount = MaxDiscount,
 minDiscount = MinDiscount,
 discountInterval = DiscountInterval,
 prices = rawPrices,
 precisionFactor = PrecisionFactor
 })
 })
 end
 end
)

-- Verify if the caller of an admin function is
-- authorized to run this action
---@param action string Accepted action
---@return PatternFunction
function assertions.isAdminAction(action)
 return function (msg)
 if msg.From ~= ao.env.Process.Id and not utils.includes(msg.From, Owners) then
 return false
 end

 return msg.Tags.Action == action
 end
end

Handlers.add(
 "list",
 assertions.isAdminAction("List"),
 function (msg)
 -- token to be listed
 local token = msg.Tags.Token

 assert(
 assertions.isAddress(token),
 "Invalid token address"
 )
 assert(
 utils.find(function (t) return t.id == token end, Tokens) == nil,
 "Token already listed"
 )

 -- check configuration
 local liquidationThreshold = tonumber(msg.Tags["Liquidation-Threshold"])
 local collateralFactor = tonumber(msg.Tags["Collateral-Factor"])
 local reserveFactor = tonumber(msg.Tags["Reserve-Factor"])
 local baseRate = tonumber(msg.Tags["Base-Rate"])
 local initRate = tonumber(msg.Tags["Init-Rate"])
 local jumpRate = tonumber(msg.Tags["Jump-Rate"])
 local cooldownPeriod = tonumber(msg.Tags["Cooldown-Period"])
 local kinkParam = tonumber(msg.Tags["Kink-Param"])

 assert(
 collateralFactor ~= nil and type(collateralFactor) == "number",
 "Invalid collateral factor"
 )
 assert(
 collateralFactor // 1 == collateralFactor and collateralFactor >= 0 and collateralFactor <= 100,
 "Collateral factor has to be a whole percentage between 0 and 100"
 )
 assert(
 liquidationThreshold ~= nil and type(liquidationThreshold) == "number",
 "Invalid liquidation threshold"
 )
 assert(
 liquidationThreshold // 1 == liquidationThreshold and liquidationThreshold >= 0 and liquidationThreshold <= 100,
 "Liquidation threshold has to be a whole percentage between 0 and 100"
 )
 assert(
 liquidationThreshold > collateralFactor or liquidationThreshold == 0 and collateralFactor == 0,
 "Liquidation threshold must be greater than the collateral factor"
 )
 assert(
 reserveFactor ~= nil and type(reserveFactor) == "number",
 "Invalid reserve factor"
 )
 assert(
 reserveFactor // 1 == reserveFactor and reserveFactor >= 0 and reserveFactor <= 100,
 "Reserve factor has to be a whole percentage between 0 and 100"
 )
 assert(
 baseRate ~= nil and assertions.isValidNumber(baseRate),
 "Invalid base rate"
 )
 assert(
 initRate ~= nil and assertions.isValidNumber(initRate),
 "Invalid init rate"
 )
 assert(
 jumpRate ~= nil and assertions.isValidNumber(jumpRate),
 "Invalid jump rate"
 )
 assert(
 assertions.isTokenQuantity(msg.Tags["Value-Limit"]),
 "Invalid value limit"
 )
 assert(
 cooldownPeriod ~= nil and assertions.isValidInteger(cooldownPeriod),
 "Invalid cooldown period"
 )
 assert(
 kinkParam ~= nil and type(kinkParam) == "number",
 "Invalid kink parameter"
 )
 assert(
 kinkParam // 1 == kinkParam and kinkParam >= 0 and kinkParam <= 100,
 "Kink parameter has to be a whole percentage between 0 and 100"
 )

 -- check if token is supported
 local supported, info = tokens.isSupported(token)

 assert(supported, "Token not supported by the protocol")

 -- spawn logo
 local logo = msg.Tags.Logo or info.Tags.Logo

 -- the oToken configuration
 local config = {
 Name = "LiquidOps " .. tostring(info.Tags.Name or info.Tags.Ticker or ""),
 ["Collateral-Id"] = token,
 ["Collateral-Ticker"] = info.Tags.Ticker,
 ["Collateral-Name"] = info.Tags.Name,
 ["Collateral-Denomination"] = info.Tags.Denomination,
 ["Collateral-Factor"] = msg.Tags["Collateral-Factor"],
 ["Liquidation-Threshold"] = tostring(liquidationThreshold),
 ["Reserve-Factor"] = tostring(reserveFactor),
 ["Base-Rate"] = msg.Tags["Base-Rate"],
 ["Init-Rate"] = msg.Tags["Init-Rate"],
 ["Jump-Rate"] = msg.Tags["Jump-Rate"],
 ["Kink-Param"] = msg.Tags["Kink-Param"],
 ["Value-Limit"] = msg.Tags["Value-Limit"],
 ["Cooldown-Period"] = msg.Tags["Cooldown-Period"],
 Oracle = Oracle,
 ["Oracle-Delay-Tolerance"] = tostring(MaxOracleDelay),
 Logo = logo,
 Authority = ao.authorities[1],
 Friends = json.encode(Tokens)
 }

 -- spawn new oToken process
 local spawnResult = ao.spawn(Module, config).receive()
 local spawnedID = spawnResult.Tags.Process

 -- notify all other tokens
 for _, t in ipairs(Tokens) do
 if t.oToken ~= spawnedID then
 ao.send({
 Target = t.oToken,
 Action = "Add-Friend",
 Friend = spawnedID,
 Token = token,
 Ticker = info.Tags.Ticker,
 Denomination = info.Tags.Denomination
 })
 end
 end

 -- add token to tokens list
 table.insert(Tokens, {
 id = token,
 ticker = info.Tags.Ticker,
 oToken = spawnedID,
 denomination = tonumber(info.Tags.Denomination) or 0
 })

 msg.reply({
 Action = "Token-Listed",
 Token = token,
 ["Spawned-Id"] = spawnedID,
 Data = json.encode(config)
 })
 end
)

Handlers.add(
 "unlist",
 assertions.isAdminAction("Unlist"),
 function (msg)
 -- token to be removed
 local token = msg.Tags.Token

 assert(
 assertions.isAddress(token),
 "Invalid token address"
 )

 -- find token index
 ---@type integer|nil
 local idx = utils.find(
 function (t) return t.id == token end,
 Tokens
 )

 assert(type(idx) == "number", "Token is not listed")

 -- id of the oToken for this token
 local oToken = Tokens[idx].oToken

 -- unlist
 table.remove(Tokens, idx)

 -- notify all other oTokens
 for _, t in ipairs(Tokens) do
 ao.send({
 Target = t.oToken,
 Action = "Remove-Friend",
 Friend = oToken
 })
 end

 msg.reply({
 Action = "Token-Unlisted",
 Token = token,
 ["Removed-Id"] = oToken
 })
 end
)

Handlers.add(
 "batch-update",
 assertions.isAdminAction("Batch-Update"),
 function (msg)
 -- check if update is already in progress
 assert(not UpdateInProgress, "An update is already in progress")

 -- allow skipping oTokens
 local skip = msg.Tags.Skip and json.decode(msg.Tags.Skip)

 -- generate update msgs
 ---@type MessageParam[]
 local updateMsgs = {}

 for _, t in ipairs(Tokens) do
 if not skip or utils.includes(t.oToken, skip) then
 table.insert(updateMsgs, {
 Target = t.oToken,
 Action = "Update",
 Data = msg.Data
 })
 end
 end

 -- set updating in progress. this will halt interactions
 -- by making the queue check always return true for any
 -- address
 UpdateInProgress = true

 -- request updates
 ---@type Message[]
 local updates = scheduler.schedule(table.unpack(updateMsgs))

 UpdateInProgress = false

 -- filter failed updates
 local failed = utils.filter(
 ---@param res Message
 function (res) return res.Tags.Error ~= nil or res.Tags.Updated ~= "true" end,
 updates
 )

 -- reply with results
 msg.reply({
 Updated = tostring(#Tokens - #failed),
 Failed = tostring(#failed),
 Data = json.encode(utils.map(
 ---@param res Message
 function (res) return res.From end,
 failed
 ))
 })
 end
)

Handlers.add(
 "get-tokens",
 { Action = "Get-Tokens" },
 function (msg)
 msg.reply({
 Data = json.encode(Tokens)
 })
 end
)

Handlers.add(
 "get-oracle",
 { Action = "Get-Oracle" },
 function (msg)
 msg.reply({ Oracle = Oracle })
 end
)

Handlers.add(
 "refund-invalid",
 function (msg)
 return msg.Tags.Action == "Credit-Notice" and
 msg.Tags["X-Action"] ~= "Liquidate"
 end,
 function (msg)
 ao.send({
 Target = msg.From,
 Action = "Transfer",
 Quantity = msg.Tags.Quantity,
 Recipient = msg.Tags.Sender,
 ["X-Action"] = "Refund",
 ["X-Refund-Reason"] = "This process does not accept the transferred token " .. msg.From
 })
 end
)

Handlers.add(
 "liquidate",
 { Action = "Credit-Notice", ["X-Action"] = "Liquidate" },
 function (msg)
 -- liquidation target
 local target = msg.Tags["X-Target"]

 -- liquidator address
 local liquidator = msg.Tags.Sender

 -- token to be liquidated, currently lent to the target
 -- (the token that is paying for the loan = transferred token)
 local liquidatedToken = msg.From

 -- the token that the liquidator will earn for
 -- paying off the loan
 -- the user has to have a position in this token
 local rewardToken = msg.Tags["X-Reward-Token"]

 -- prepare liquidation, check required environment
 local success, errorMsg, expectedRewardQty, oTokensParticipating, removeWhenDone = pcall(function ()
 assert(
 assertions.isAddress(target) and target ~= liquidator,
 "Invalid liquidation target"
 )
 assert(
 assertions.isAddress(liquidator),
 "Invalid liquidator address"
 )
 assert(
 assertions.isAddress(rewardToken),
 "Invalid reward token address"
 )
 assert(
 assertions.isTokenQuantity(msg.Tags.Quantity),
 "Invalid transfer quantity"
 )
 assert(
 assertions.isTokenQuantity(msg.Tags["X-Min-Expected-Quantity"]),
 "Invalid minimum expected quantity"
 )

 -- try to find the liquidated token, the reward token and
 -- generate the position messages in one loop for efficiency
 ---@type { liquidated: string; reward: string; }
 local oTokensParticipating = {}

 ---@type MessageParam[]
 local positionMsgs = {}

 for _, t in ipairs(Tokens) do
 if t.id == liquidatedToken then oTokensParticipating.liquidated = t.oToken end
 if t.id == rewardToken then oTokensParticipating.reward = t.oToken end

 table.insert(positionMsgs, {
 Target = t.oToken,
 Action = "Position",
 Recipient = target
 })
 end

 assert(
 oTokensParticipating.liquidated ~= nil,
 "Cannot liquidate the incoming token as it is not listed"
 )
 assert(
 oTokensParticipating.reward ~= nil,
 "Cannot liquidate for the reward token as it is not listed"
 )

 -- fetch prices first so the user positions won't be outdated
 local prices = oracle.sync()

 -- check user position
 ---@type Message[]
 local positions = scheduler.schedule(table.unpack(positionMsgs))

 -- check queue
 assert(
 not queue.isQueued(target),
 "User is queued for an operation"
 )

 -- get tokens that need a price fetch
 local zero = bint.zero()

 ---@type PriceParam[], PriceParam[]
 local liquidationLimits, borrowBalances = {}, {}

 -- symbols to sync
 ---@type string[]
 local symbols = {}

 -- incoming and outgoing token data
 ---@type TokenData, TokenData
 local inTokenData, outTokenData = {}, {}

 -- the total collateral of the desired reward token
 -- in the user's position for the reward token
 local availableRewardQty = zero

 -- the total borrow of the liquidated token in the
 -- user's position
 local availableLiquidateQty = zero

 -- check if the user has any open positions (active loans)
 local hasOpenPosition = false

 -- populate capacities, symbols, incoming/outgoing token data and collateral qty
 for _, pos in ipairs(positions) do
 local symbol = pos.Tags["Collateral-Ticker"]
 local denomination = tonumber(pos.Tags["Collateral-Denomination"]) or 0

 -- convert quantities
 local liquidationLimit = bint(pos.Tags["Liquidation-Limit"] or 0)
 local borrowBalance = bint(pos.Tags["Borrow-Balance"] or 0)

 if pos.From == oTokensParticipating.liquidated then
 inTokenData = { ticker = symbol, denomination = denomination }
 availableLiquidateQty = borrowBalance
 end

 if pos.From == oTokensParticipating.reward then
 outTokenData = { ticker = symbol, denomination = denomination }
 availableRewardQty = bint(pos.Tags.Collateralization or 0)
 end

 -- only sync if there is a position
 if bint.ult(zero, borrowBalance) or bint.ult(zero, liquidationLimit) then
 table.insert(symbols, symbol)
 table.insert(borrowBalances, {
 ticker = symbol,
 quantity = borrowBalance,
 denomination = denomination
 })
 table.insert(liquidationLimits, {
 ticker = symbol,
 quantity = liquidationLimit,
 denomination = denomination
 })
 end

 -- update user position indicator
 if bint.ult(zero, borrowBalance) then
 hasOpenPosition = true
 end
 end

 assert(
 inTokenData.ticker ~= nil and inTokenData.denomination ~= nil,
 "Incoming token data not found"
 )
 assert(
 outTokenData.ticker ~= nil and outTokenData.denomination ~= nil,
 "Outgoing token data not found"
 )
 assert(
 bint.ult(zero, availableRewardQty),
 "No available reward quantity"
 )
 assert(
 bint.ult(zero, availableLiquidateQty),
 "No available liquidate quantity"
 )

 -- check if the user has any open positions
 if not hasOpenPosition then
 -- remove from auctions if present
 liquidations.removeAuction(target)

 -- error and trigger refund
 error("User does not have an active loan")
 end

 -- ensure "liquidation-limit / borrow-balance < 1"
 -- this means that the user is eligible for liquidation
 local totalLiquidationLimit = utils.reduce(
 function (acc, curr) return acc + curr.value end,
 zero,
 oracle.getValues(prices, liquidationLimits)
 )
 local totalBorrowBalance = utils.reduce(
 function (acc, curr) return acc + curr.value end,
 zero,
 oracle.getValues(prices, borrowBalances)
 )

 assert(
 bint.ult(totalLiquidationLimit, totalBorrowBalance),
 "Target not eligible for liquidation"
 )

 -- get token quantities
 local inQty = bint(msg.Tags.Quantity)

 -- USD value of the liquidation
 local usdValue = oracle.getValue(
 prices,
 inQty,
 inTokenData.ticker,
 inTokenData.denomination
 )

 -- ensure that at least the minimum threshold is reached
 -- when repaying the loan or the liquidator is repaying the
 -- full amount, in case the total value of the loan they're
 -- repaying is under 20% of the user's loans' total value
 assert(
 bint.ule(availableLiquidateQty, inQty) or bint.ule(
 bint.udiv(
 totalBorrowBalance * bint(MinLiquidationThreshold * 100 // 1),
 bint(100 * 100)
 ),
 usdValue
 ),
 "Liquidators are required to repay at least " ..
 tostring(MinLiquidationThreshold) ..
 "% of the total loan or the entire loan of a token"
 )

 -- market value of the liquidation
 local marketValueInQty = oracle.getValueInToken(
 {
 ticker = inTokenData.ticker,
 quantity = inQty,
 denomination = inTokenData.denomination
 },
 outTokenData,
 prices
 )

 -- make sure that the user's position is enough to pay the liquidator
 -- (at least the market value of the tokens)
 assert(
 bint.ule(marketValueInQty, availableRewardQty),
 "The user does not have enough tokens in their position for this liquidation"
 )

 -- apply auction
 local discount = tokens.getDiscount(target)

 -- update the expected reward quantity using the discount
 local expectedRewardQty = marketValueInQty

 if discount > 0 then
 expectedRewardQty = bint.udiv(
 expectedRewardQty * bint(100 * PrecisionFactor + discount),
 bint(100 * PrecisionFactor)
 )
 end

 -- if the discount is higher than the position in the
 -- reward token, we need to update it with the maximum
 -- possible amount
 if bint.ult(availableRewardQty, expectedRewardQty) then
 expectedRewardQty = availableRewardQty
 end

 -- the minimum quantity expected by the user
 local minExpectedRewardQty = bint(msg.Tags["X-Min-Expected-Quantity"] or 0)

 -- make sure the user is receiving at least
 -- the minimum amount of tokens they're expecting
 assert(
 bint.ule(minExpectedRewardQty, expectedRewardQty),
 "Could not meet the defined slippage"
 )

 -- check queue
 assert(
 not queue.isQueued(target),
 "User is already queued for liquidation"
 )

 -- whether or not to remove the auction after this liquidation is complete.
 -- this checks if the position becomes healthy after the liquidation
 local removeWhenDone = bint.ule(
 totalBorrowBalance - oracle.getValue(prices, bint.min(inQty, availableLiquidateQty), inTokenData.ticker, inTokenData.denomination),
 totalLiquidationLimit - oracle.getValue(prices, expectedRewardQty, outTokenData.ticker, outTokenData.denomination)
 )

 return "", expectedRewardQty, oTokensParticipating, removeWhenDone
 end)

 -- check if liquidation is possible
 if not success then
 -- signal error
 ao.send({
 Target = liquidator,
 Action = "Liquidate-Error",
 Error = string.gsub(errorMsg, "%[[%w_.\" ]*%]:%d*: ", "")
 })

 -- refund
 return ao.send({
 Target = msg.From,
 Action = "Transfer",
 Quantity = msg.Tags.Quantity,
 Recipient = liquidator
 })
 end

 -- since a liquidation is possible for the target
 -- we add it to the list of discovered auctions
 liquidations.addAuction(target, msg.Timestamp)

 -- queue the liquidation at this point, because
 -- the user position has been checked, so the liquidation is valid
 -- we don't want anyone to be able to liquidate from this point
 queue.add(target, ao.id)

 -- TODO: timeout here? (what if this doesn't return in time, the liquidation remains in a pending state)
 -- TODO: this timeout can be done with a Handler that removed this coroutine

 -- liquidation reference to identify the result
 -- (we cannot use .receive() here, since both the target
 -- and the default response reference will change, because
 -- of the chained messages)
 local liquidationReference = msg.Id .. "-" .. liquidator

 -- liquidate the loan
 ao.send({
 Target = liquidatedToken,
 Action = "Transfer",
 Quantity = msg.Tags.Quantity,
 Recipient = oTokensParticipating.liquidated,
 ["X-Action"] = "Liquidate-Borrow",
 ["X-Liquidator"] = liquidator,
 ["X-Liquidation-Target"] = target,
 ["X-Reward-Market"] = oTokensParticipating.reward,
 ["X-Reward-Quantity"] = tostring(expectedRewardQty),
 ["X-Liquidation-Reference"] = liquidationReference
 })

 -- wait for result
 local loanLiquidationRes = Handlers.receive({
 From = oTokensParticipating.liquidated,
 ["Liquidation-Reference"] = liquidationReference
 })

 -- remove from queue (discard result - if we get to this point, the user should be queued by the controller)
 queue.remove(target, ao.id)

 -- check loan liquidation result
 -- (at this point, we do not need to refund the user
 -- because the oToken process handles that)
 if loanLiquidationRes.Tags.Error or loanLiquidationRes.Tags.Action ~= "Liquidate-Borrow-Confirmation" then
 return ao.send({
 Target = liquidator,
 Action = "Liquidate-Error",
 Error = loanLiquidationRes.Tags.Error
 })
 end

 -- if the auction is done (no more loans to liquidate)
 -- we need to remove it from the discovered auctions
 if removeWhenDone then
 liquidations.removeAuction(target)
 end

 -- send confirmation to the liquidator
 ao.send({
 Target = liquidator,
 Action = "Liquidate-Confirmation",
 ["Liquidation-Target"] = target,
 ["From-Quantity"] = msg.Tags.Quantity,
 ["From-Token"] = liquidatedToken,
 ["To-Quantity"] = tostring(expectedRewardQty),
 ["To-Token"] = rewardToken
 })

 -- send notice to the target
 ao.send({
 Target = target,
 Action = "Liquidate-Notice",
 ["From-Quantity"] = msg.Tags.Quantity,
 ["To-Quantity"] = tostring(expectedRewardQty)
 })
 end
)

Handlers.add(
 "add-queue",
 function (msg)
 if msg.Action ~= "Add-To-Queue" then return false end
 return utils.find(
 function (t) return t.oToken == msg.From end,
 Tokens
 ) ~= nil
 end,
 function (msg)
 local user = msg.Tags.User

 -- validate address
 if not assertions.isAddress(user) then
 return msg.reply({ Error = "Invalid user address" })
 end

 -- check if the user has already been added
 if queue.isQueued(user) or UpdateInProgress then
 return msg.reply({ Error = "User already queued" })
 end

 -- add to queue
 queue.add(user, msg.From)

 msg.reply({ ["Queued-User"] = user })
 end
)

Handlers.add(
 "remove-queue",
 function (msg)
 if msg.Action ~= "Remove-From-Queue" then return false end
 return utils.find(
 function (t) return t.oToken == msg.From end,
 Tokens
 ) ~= nil
 end,
 function (msg)
 local user = msg.Tags.User

 -- validate address
 if not assertions.isAddress(user) then
 return msg.reply({ Error = "Invalid user address" })
 end

 -- try to remove the user from the queue
 local res = queue.remove(user, msg.From)

 if res ~= "removed" then
 return msg.reply({
 Error = res == "not_queued" and
 "The user is not queued" or
 "The user was queued from another origin"
 })
 end

 -- reply with confirmation
 msg.reply({ ["Unqueued-User"] = user })
 end
)

Handlers.add(
 "check-queue",
 { Action = "Check-Queue-For" },
 function (msg)
 local user = msg.Tags.User

 -- validate address
 if not assertions.isAddress(user) then
 return msg.reply({ ["In-Queue"] = "false" })
 end

 -- the user is queued if they're either in the collateral
 -- or the liquidation queues
 return msg.reply({
 ["In-Queue"] = json.encode(queue.isQueued(user) or UpdateInProgress)
 })
 end
)

Handlers.add(
 "get-auctions",
 { Action = "Get-Auctions" },
 function (msg)
 msg.reply({
 ["Initial-Discount"] = tostring(MaxDiscount),
 ["Final-Discount"] = tostring(MinDiscount),
 ["Discount-Interval"] = tostring(DiscountInterval),
 Data = next(Auctions) ~= nil and json.encode(Auctions) or "{}"
 })
 end
)

-- Add a user to the queue list
---@param addr string User address
---@param origin string Queue request origin
function queue.add(addr, origin)
 table.insert(Queue, {
 address = addr,
 origin = origin
 })
 ao.send({
 device = "patch@1.0",
 queue = Queue
 })
end

-- Remove a user from the queue list, if the origin matches
---@param addr string User address
---@param origin string Queue request origin
---@return "removed"|"not_queued"|"invalid_origin"
function queue.remove(addr, origin)
 -- find entry to remove
 local idx = nil

 for i, entry in ipairs(Queue) do
 if entry.address == addr then
 -- different origin
 if entry.origin ~= origin then
 return "invalid_origin"
 end

 idx = i
 end
 end

 -- the address was not found in the queue
 if not idx then
 return "not_queued"
 end

 -- remove from queue table
 table.remove(Queue, idx)

 -- patch
 ao.send({
 device = "patch@1.0",
 queue = Queue
 })

 return "removed"
end

-- Check if an address is queued
---@param addr string User address
---@param origin string? Optional origin to verify against
function queue.isQueued(addr, origin)
 return utils.find(
 function (u)
 if origin ~= nil and u.origin ~= origin then
 return false
 end

 return u.address == addr
 end,
 Queue
 ) ~= nil
end

-- Removes an auction with a cooldown
---@param target string Auction target address
function liquidations.removeAuction(target)
 if Auctions[target] == nil then return end

 local removeAuctionAfter = Timestamp + 1000 * 60 * 60 * 3 -- in 3 hours
 local handlerName = "auctions-remove-" .. target

 Handlers.remove(handlerName)
 Handlers.once(
 handlerName,
 function (msg)
 if msg.Timestamp > removeAuctionAfter then
 return "continue"
 end
 return false
 end,
 function ()
 Auctions[target] = nil

 -- patch
 ao.send({
 device = "patch@1.0",
 auctions = Auctions
 })
 end
 )
end

-- Adds a newly discovered auction
---@param target string Auction target address
---@param discovered number Discovery timestamp
function liquidations.addAuction(target, discovered)
 -- delete handler that would remove the auction and add auction
 Handlers.remove("auctions-remove-" .. target)

 -- add discovery date if the user isn't already in auctions
 if Auctions[target] == nil then
 Auctions[target] = discovered

 -- patch
 ao.send({
 device = "patch@1.0",
 auctions = { [target] = discovered }
 })
 end
end

-- Verify if the provided value is an address
---@param addr any Address to verify
---@return boolean
function assertions.isAddress(addr)
 if type(addr) ~= "string" then return false end
 if string.len(addr) ~= 43 then return false end
 if string.match(addr, "^[A-z0-9_-]+$") == nil then return false end

 return true
end

-- Check if token is supported by the protocol
-- (token supports aos 2.0 replies and replies with a proper info response)
-- Returns if the token is supported and the token info
---@param addr string Token address
function tokens.isSupported(addr)
 -- send info request
 ao.send({
 Target = addr,
 Action = "Info",
 })

 -- wait for proper response
 local res = Handlers.receive({
 From = addr,
 Ticker = "^.+$",
 Name = "^.+$",
 Denomination = "^.+$"
 })

 local repliesSupported = res.Tags["X-Reference"] ~= nil

 local denomination = tonumber(res.Tags.Denomination)
 local validDenomination = denomination ~= nil and
 denomination == denomination // 1 and
 denomination > 0 and
 denomination <= 18

 return repliesSupported and validDenomination, res
end

-- Checks if an input is not inf or nan
---@param val number Input to check
function assertions.isValidNumber(val)
 return type(val) == "number" and
 val == val and
 val ~= math.huge and
 val ~= -math.huge
end

-- Checks if an input is not inf or nan and is an integer
---@param val number Input to check
function assertions.isValidInteger(val)
 return assertions.isValidNumber(val) and val % 1 == 0
end

-- Validates if the provided value can be parsed as a Bint
---@param val any Value to validate
---@return boolean
function assertions.isBintRaw(val)
 local success, result = pcall(
 function ()
 -- check if the value is convertible to a Bint
 if type(val) ~= "number" and type(val) ~= "string" and not bint.isbint(val) then
 return false
 end

 -- check if the val is an integer and not infinity, in case if the type is number
 if type(val) == "number" and not assertions.isValidInteger(val) then
 return false
 end

 return true
 end
 )

 return success and result
end

-- Verify if the provided value can be converted to a valid token quantity
---@param qty any Raw quantity to verify
---@return boolean
function assertions.isTokenQuantity(qty)
 local numVal = tonumber(qty)
 if not numVal or numVal <= 0 then return false end
 if not assertions.isBintRaw(qty) then return false end
 if type(qty) == "number" and qty < 0 then return false end
 if type(qty) == "string" and string.sub(qty, 1, 1) == "-" then
 return false
 end

 return true
end

-- Get current discount for a target
---@param target string Target address
function tokens.getDiscount(target)
 -- apply auction model
 -- time passed in milliseconds since the discovery of this auction
 local timePassed = Timestamp - (Auctions[target] or Timestamp)

 -- if the time passed is higher than the discount interval
 -- we reached the minimum discount price, so we
 -- set the time passed to the corresponding interval
 if timePassed > DiscountInterval then
 timePassed = DiscountInterval
 end

 -- current discount percentage:
 -- a linear function of the time passed,
 -- the discount becomes 0 when the discount
 -- interval is over
 local discount = math.max((DiscountInterval - timePassed) * MaxDiscount * PrecisionFactor // DiscountInterval, MinDiscount)

 return discount
end

function scheduler.schedule(...)
 -- get the running handler's thread
 local thread = coroutine.running()

 -- repsonse handler
 local responses = {}
 local messages = {...}

 -- if there are no messages to be sent, we don't do anything
 if #messages == 0 then return {} end

 ---@type HandlerFunction
 local function responseHandler(msg)
 table.insert(responses, msg)

 -- continue execution when all responses are back
 if #responses == #messages then
 -- if the result of the resumed coroutine is an error, then we should bubble it up to the process
 local _, success, errmsg = coroutine.resume(thread, responses)

 assert(success, errmsg)
 end
 end

 -- send messages
 for _, msg in ipairs(messages) do
 ao.send(msg)

 -- wait for response
 Handlers.once(
 { From = msg.Target, ["X-Reference"] = tostring(ao.reference) },
 responseHandler
 )
 end

 -- yield execution, till all responses are back
 return coroutine.yield({ From = messages[#messages], ["X-Reference"] = tostring(ao.reference) })
end

-- Get price data for an array of token symbols
function oracle.sync()
 ---@type RawPrices
 local res = {}

 -- all collateral tickers
 local symbols = utils.map(
 ---@param f Friend
 function (f) return f.ticker end,
 Tokens
 )

 -- no tokens to sync
 if #symbols == 0 then return res end

 ---@type string|nil
 local rawData = ao.send({
 Target = Oracle,
 Action = "v2.Request-Latest-Data",
 Tickers = json.encode(symbols)
 }).receive().Data

 -- no price data returned
 if not rawData or rawData == "" then return res end

 ---@type boolean, OracleData
 local parsed, data = pcall(json.decode, rawData)

 assert(parsed, "Could not parse oracle data")

 for ticker, p in pairs(data) do
 -- only add data if the timestamp is up to date
 if p.t + MaxOracleDelay >= Timestamp then
 res[ticker] = {
 price = p.v,
 timestamp = p.t
 }
 end
 end

 return res
end

-- Get the value of a single quantity
---@param rawPrices RawPrices Raw price data
---@param quantity Bint Token quantity
---@param ticker string Token ticker
---@param denomination number Token denomination
function oracle.getValue(rawPrices, quantity, ticker, denomination)
 local res = oracle.getValues(rawPrices, {
 { ticker = ticker, denomination = denomination, quantity = quantity }
 })

 assert(res[1] ~= nil, "No price calculated")

 return res[1].value
end

-- Get the value of quantities of the provided assets. The function
-- will only provide up to date values, outdated and nil values will be
-- filtered out
---@param rawPrices RawPrices Raw results from the oracle
---@param quantities PriceParam[] Token quantities
function oracle.getValues(rawPrices, quantities)
 ---@type { ticker: string, value: Bint }[]
 local results = {}

 local one = bint.one()
 local zero = bint.zero()

 for _, v in ipairs(quantities) do
 if not v.quantity then v.quantity = one end
 if not bint.eq(v.quantity, zero) then
 -- make sure the oracle returned the price
 assert(rawPrices[v.ticker] ~= nil, "No price returned from the oracle for " .. v.ticker)

 -- the value of the quantity
 -- (USD price value is denominated for precision,
 -- but the result needs to be divided according
 -- to the underlying asset's denomination,
 -- because the price data is for the non-denominated
 -- unit)
 local value = bint.udiv(
 v.quantity * oracle.getUSDDenominated(rawPrices[v.ticker].price),
 -- optimize performance by repeating "0" instead of a power operation
 bint("1" .. string.rep("0", v.denomination))
 )

 -- add data
 table.insert(results, {
 ticker = v.ticker,
 value = value
 })
 else
 table.insert(results, {
 ticker = v.ticker,
 value = zero
 })
 end
 end

 return results
end

-- Get the value of one token quantity in another
-- token quantity
---@param from { ticker: string, quantity: Bint, denomination: number } From token ticker, quantity and denomination
---@param to TokenData Target token ticker and denomination
---@param rawPrices RawPrices Pre-fetched prices
---@return Bint
function oracle.getValueInToken(from, to, rawPrices)
 -- prices
 local fromPrice = oracle.getUSDDenominated(rawPrices[from.ticker].price)
 local toPrice = oracle.getUSDDenominated(rawPrices[to.ticker].price)

 -- get value of the "from" token quantity in USD with extra precision
 local usdValue = bint.udiv(
 from.quantity * fromPrice,
 bint("1" .. string.rep("0", from.denomination))
 )

 -- convert usd value to the token quantity
 -- accounting for the denomination
 return bint.udiv(
 usdValue * bint("1" .. string.rep("0", to.denomination)),
 toPrice
 )
end

-- Get the precision used for USD biginteger values
function oracle.getUSDDenomination() return 12 end

-- Get the fractional part's length
---@param val number Full number
function oracle.getFractionsCount(val)
 -- check if there is a fractional part
 -- by trying to find it with a pattern
 local fractionalPart = string.match(oracle.floatToString(val), "%.(.*)")

 if not fractionalPart then return 0 end

 -- get the length of the fractional part
 return string.len(fractionalPart)
end

-- Get a USD value in a 12 denominated form
---@param val number USD value as a floating point number
---@return Bint
function oracle.getUSDDenominated(val)
 local denominator = oracle.getUSDDenomination()

 -- remove decimal point
 local denominated = string.gsub(oracle.floatToString(val), "%.", "")

 -- get the count of decimal places after the decimal point
 local fractions = oracle.getFractionsCount(val)

 local wholeDigits = string.len(denominated) - fractions
 denominated = denominated .. string.rep("0", denominator)
 denominated = string.sub(denominated, 1, wholeDigits + denominator)

 return bint(denominated)
end

-- Convert a lua number to a string
---@param val number The value to convert
function oracle.floatToString(val)
 return string.format("%.17f", val):gsub("0+$", ""):gsub("%.$", "")
end