Skip to main content

ILimitOrders

Git Source

Title: ILimitOrders

Interface for limit order functionality for the Convertible Deposit Auctioneer

Users create orders specifying max price, MEV bots fill when price is favorable. User deposits are held in sUSDS to generate yield, which accrues to a configurable recipient.

Functions​

yieldRecipient​

Recipient of accrued yield

function yieldRecipient() external view returns (address);

nextOrderId​

Next order ID to be assigned

function nextOrderId() external view returns (uint256);

totalUsdsOwed​

Total USDS owed to all order owners (principal tracking)

function totalUsdsOwed() external view returns (uint256);

setYieldRecipient​

Update the yield recipient address

function setYieldRecipient(address newRecipient_) external;

Parameters

NameTypeDescription
newRecipient_addressThe new yield recipient

addDepositPeriod​

Add a new deposit period and associated receipt token

This function will revert if:

  • The contract is not enabled
  • The caller is not the owner
  • The deposit period is 0
  • The receipt token address is 0
  • The deposit period is already configured
  • The deposit period is not enabled in the auctioneer
function addDepositPeriod(uint8 depositPeriod_, address receiptToken_) external;

Parameters

NameTypeDescription
depositPeriod_uint8The deposit period to add
receiptToken_addressThe receipt token address for the deposit period

removeDepositPeriod​

Remove a deposit period and associated receipt token

This function will revert if:

  • The contract is not enabled
  • The caller is not the owner
  • The deposit period is not configured Note: Active orders for this deposit period will fail to fill until the deposit period is re-added. Users can cancel their orders if needed.
function removeDepositPeriod(uint8 depositPeriod_) external;

Parameters

NameTypeDescription
depositPeriod_uint8The deposit period to remove

createOrder​

Create a new limit order

This function will revert if:

  • The contract is not enabled
  • The deposit budget, max price, or min fill size is invalid
  • The receipt token is not configured in this contract
  • The deposit period is not enabled in the auctioneer
  • The caller cannot receive ERC721 tokens
  • The min fill size is below the auctioneer minimum bid
function createOrder(
    uint8 depositPeriod_,
    uint256 depositBudget_,
    uint256 incentiveBudget_,
    uint256 maxPrice_,
    uint256 minFillSize_
) external returns (uint256 orderId);

Parameters

NameTypeDescription
depositPeriod_uint8The deposit period for the CD position
depositBudget_uint256USDS budget for bids
incentiveBudget_uint256USDS budget for filler incentives (paid proportionally)
maxPrice_uint256Maximum execution price (USDS per OHM)
minFillSize_uint256Minimum USDS per fill (except final fill)

Returns

NameTypeDescription
orderIduint256The ID of the created order

fillOrder​

Fill a limit order

This function will revert if:

  • The contract is not enabled
  • The order is not active
  • The order budget has been fully spent
  • The fill amount is below the minimum fill size (unless this is the final fill)
  • The deposit period is not enabled
  • The receipt token is not configured
  • The execution price is above the maximum price
  • The previewBid function returns zero OHM output
function fillOrder(uint256 orderId_, uint256 fillAmount_) external returns (uint256, uint256, uint256);

Parameters

NameTypeDescription
orderId_uint256The ID of the order to fill
fillAmount_uint256The amount of USDS to use for the bid

Returns

NameTypeDescription
<none>uint256uint256 The actual fill amount (may be capped to remaining deposit)
<none>uint256uint256 The incentive amount paid to the filler
<none>uint256uint256 The remaining deposit budget after the fill

cancelOrder​

Cancel an active order and return remaining funds

This function will revert if:

  • The caller is not the order owner
  • The order is not active
  • The order is fully spent Note that if the contract is disabled, this function will still operate in order to allow users to withdraw their deposited funds.
function cancelOrder(uint256 orderId_) external;

Parameters

NameTypeDescription
orderId_uint256The ID of the order to cancel

getAccruedYield​

Calculate current accrued yield in USDS terms

function getAccruedYield() external view returns (uint256);

Returns

NameTypeDescription
<none>uint256uint256 The current accrued yield in USDS terms

getAccruedYieldShares​

Calculate accrued yield in sUSDS shares

Uses previewWithdraw to safely account for rounding

function getAccruedYieldShares() external view returns (uint256);

Returns

NameTypeDescription
<none>uint256uint256 The current accrued yield in sUSDS terms

sweepYield​

Sweep all accrued yield to the yield recipient as sUSDS

function sweepYield() external returns (uint256 shares);

Returns

NameTypeDescription
sharesuint256The amount of sUSDS swept to the yield recipient

getOrder​

Get a limit order by ID

function getOrder(uint256 orderId_) external view returns (LimitOrder memory);

Parameters

NameTypeDescription
orderId_uint256The ID of the order

Returns

NameTypeDescription
<none>LimitOrderLimitOrder The limit order

getOrdersForUser​

Get limit order IDs by user

function getOrdersForUser(address user_) external view returns (uint256[] memory);

Parameters

NameTypeDescription
user_addressThe address of the user

Returns

NameTypeDescription
<none>uint256[]uint256[] The IDs of the user's orders

previewFillOrder​

Preview a fill order

function previewFillOrder(uint256 orderId_, uint256 fillAmount_)
    external
    view
    returns (bool canFill, string memory reason, uint256 effectivePrice, uint256 incentive);

Parameters

NameTypeDescription
orderId_uint256The ID of the order
fillAmount_uint256The amount of USDS to use for the bid

Returns

NameTypeDescription
canFillboolWhether the order can be filled
reasonstringThe reason the order cannot be filled
effectivePriceuint256The effective price of the fill
incentiveuint256The incentive amount for the fill

calculateIncentive​

Calculate incentive and incentive rate for a given fill amount

function calculateIncentive(uint256 orderId_, uint256 fillAmount_)
    external
    view
    returns (uint256 incentive, uint256 incentiveRate);

Parameters

NameTypeDescription
orderId_uint256The ID of the order
fillAmount_uint256The amount of USDS to use for the bid

Returns

NameTypeDescription
incentiveuint256The incentive amount for the fill
incentiveRateuint256The incentive rate for the fill

canFillOrder​

Check if an order can be filled at a given size

function canFillOrder(uint256 orderId_, uint256 fillAmount_)
    external
    view
    returns (bool canFill, string memory reason, uint256 effectivePrice);

Parameters

NameTypeDescription
orderId_uint256The ID of the order
fillAmount_uint256The amount of USDS to use for the bid

Returns

NameTypeDescription
canFillboolWhether the order can be filled
reasonstringThe reason the order cannot be filled
effectivePriceuint256The effective price of the fill

getRemaining​

Get remaining deposit and incentive budgets for order

function getRemaining(uint256 orderId_) external view returns (uint256 deposit, uint256 incentive);

Parameters

NameTypeDescription
orderId_uint256The ID of the order

Returns

NameTypeDescription
deposituint256The remaining deposit budget
incentiveuint256The remaining incentive budget

getExecutionPrice​

Get current execution price for a fill amount

function getExecutionPrice(uint8 depositPeriod_, uint256 fillAmount_) external view returns (uint256);

Parameters

NameTypeDescription
depositPeriod_uint8The deposit period
fillAmount_uint256The amount of USDS to use for the bid

Returns

NameTypeDescription
<none>uint256effectivePrice The effective price of the fill

getFillableOrders​

Find fillable orders for a deposit period

WARNING: Gas-intensive. Intended for off-chain use only.

function getFillableOrders(uint8 depositPeriod_) external view returns (uint256[] memory);

Parameters

NameTypeDescription
depositPeriod_uint8The deposit period

Returns

NameTypeDescription
<none>uint256[]uint256[] The IDs of the fillable orders

getFillableOrders​

Find fillable orders for a deposit period between given order IDs

For use if getFillableOrders(uint8 depositPeriod_) exceeds limit

WARNING: Gas-intensive. Intended for off-chain use only.

function getFillableOrders(uint8 depositPeriod_, uint256 index0, uint256 index1)
    external
    view
    returns (uint256[] memory);

Parameters

NameTypeDescription
depositPeriod_uint8The deposit period
index0uint256The starting order ID
index1uint256The ending order ID

Returns

NameTypeDescription
<none>uint256[]uint256[] The IDs of the fillable orders

Events​

OrderCreated​

Emitted when a new order is created

event OrderCreated(
    uint256 indexed orderId,
    address indexed owner,
    uint8 depositPeriod,
    uint256 depositBudget,
    uint256 incentiveBudget,
    uint256 maxPrice,
    uint256 minFillSize
);

Parameters

NameTypeDescription
orderIduint256The ID of the created order
owneraddressThe owner of the order
depositPerioduint8The deposit period for the CD position
depositBudgetuint256The USDS budget for bids
incentiveBudgetuint256The USDS budget for filler incentives (paid proportionally)
maxPriceuint256The maximum execution price (USDS per OHM)
minFillSizeuint256The minimum USDS per fill (except final fill)

OrderFilled​

Emitted when an order is filled

event OrderFilled(
    uint256 indexed orderId,
    address indexed filler,
    uint256 fillAmount,
    uint256 incentivePaid,
    uint256 ohmOut,
    uint256 positionId
);

Parameters

NameTypeDescription
orderIduint256The ID of the filled order
filleraddressThe address of the filler
fillAmountuint256The amount of USDS used for the bid
incentivePaiduint256The amount of USDS paid as incentive
ohmOutuint256The amount of OHM output
positionIduint256The ID of the filled position

OrderCancelled​

Emitted when an order is cancelled

event OrderCancelled(uint256 indexed orderId, uint256 usdsReturned);

Parameters

NameTypeDescription
orderIduint256The ID of the cancelled order
usdsReturneduint256The amount of USDS returned to the order owner

YieldSwept​

Emitted when yield is swept

event YieldSwept(address indexed recipient, uint256 sUsdsAmount);

Parameters

NameTypeDescription
recipientaddressThe address of the recipient
sUsdsAmountuint256The amount of sUSDS swept

YieldRecipientUpdated​

Emitted when the yield recipient is updated

event YieldRecipientUpdated(address indexed newRecipient);

Parameters

NameTypeDescription
newRecipientaddressThe new address of the recipient

DepositPeriodAdded​

Emitted when a deposit period and receipt token are added

event DepositPeriodAdded(uint8 indexed depositPeriod, address indexed receiptToken);

Parameters

NameTypeDescription
depositPerioduint8The deposit period that was added
receiptTokenaddressThe receipt token address for the deposit period

DepositPeriodRemoved​

Emitted when a deposit period and receipt token are removed

event DepositPeriodRemoved(uint8 indexed depositPeriod);

Parameters

NameTypeDescription
depositPerioduint8The deposit period that was removed

Errors​

InvalidParam​

Used when a function parameter is invalid

error InvalidParam(string param);

OrderNotActive​

Used when an order is not active

error OrderNotActive();

OrderFullySpent​

Used when an order is fully spent

error OrderFullySpent();

FillBelowMinimum​

Used when a fill amount is below the minimum fill size

error FillBelowMinimum();

PriceAboveMax​

Used when a fill amount is above the maximum price

error PriceAboveMax();

NotOrderOwner​

Used when the caller is not the order owner

error NotOrderOwner();

DepositPeriodNotEnabled​

Used when a deposit period is not enabled

error DepositPeriodNotEnabled();

ReceiptTokenNotConfigured​

Used when a receipt token is not configured

error ReceiptTokenNotConfigured();

ArrayLengthMismatch​

Used when an array length mismatch is detected

error ArrayLengthMismatch();

ZeroOhmOut​

Used when the previewBid function returns zero OHM output

error ZeroOhmOut();

Structs​

LimitOrder​

Limit order struct

This struct is used to store limit order information

struct LimitOrder {
    address owner;
    uint8 depositPeriod;
    bool active;
    uint256 depositBudget;
    uint256 incentiveBudget;
    uint256 depositSpent;
    uint256 incentiveSpent;
    uint256 maxPrice;
    uint256 minFillSize;
}

Properties

NameTypeDescription
owneraddressThe owner of the order
depositPerioduint8The deposit period for the CD position
activeboolWhether the order is active
depositBudgetuint256The USDS budget for bids
incentiveBudgetuint256The USDS budget for filler incentives (paid proportionally)
depositSpentuint256The amount of USDS spent on the deposit
incentiveSpentuint256The amount of USDS spent on the incentive
maxPriceuint256The maximum execution price (USDS per OHM)
minFillSizeuint256The minimum USDS per fill (except final fill)