# TermAuction.sol ## TermAuction This contract calculates a clearing price in a blind double auction and manages auction clearing and settlement *This contract belongs to the Term Auction group of contracts and is specific to a Term Repo deployment* ### ClearingPriceState ```solidity struct ClearingPriceState { uint256 offerPrice; uint256 offerIndex; uint256 bidIndex; uint256 cumSumOffers; uint256 cumSumBids; uint256 maxClearingVolume; uint256 nextOfferIndex; uint256 nextBidIndex; uint256 nextCumSumOffers; uint256 nextCumSumBids; uint256 nextOfferPrice; uint256 nextMaxClearingVolume; bool minCumSumCorrection; uint256 nextBidPrice; uint256 clearingPrice; } ``` ### THREESIXTY\_DAYCOUNT\_SECONDS ```solidity uint256 THREESIXTY_DAYCOUNT_SECONDS ``` ### ADMIN\_ROLE ```solidity bytes32 ADMIN_ROLE ``` ### DEVOPS\_ROLE ```solidity bytes32 DEVOPS_ROLE ``` ### INITIALIZER\_ROLE ```solidity bytes32 INITIALIZER_ROLE ``` ### termRepoId ```solidity bytes32 termRepoId ``` ### termAuctionId ```solidity bytes32 termAuctionId ``` ### auctionEndTime ```solidity uint256 auctionEndTime ``` ### dayCountFractionMantissa ```solidity uint256 dayCountFractionMantissa ``` ### termRepoServicer ```solidity contract ITermRepoServicer termRepoServicer ``` ### termAuctionBidLocker ```solidity contract ITermAuctionBidLocker termAuctionBidLocker ``` ### termAuctionOfferLocker ```solidity contract ITermAuctionOfferLocker termAuctionOfferLocker ``` ### purchaseToken ```solidity contract IERC20MetadataUpgradeable purchaseToken ``` ### emitter ```solidity contract ITermEventEmitter emitter ``` ### controller ```solidity contract ITermController controller ``` ### clearingPrice ```solidity uint256 clearingPrice ``` ### clearingPricePostProcessingOffset ```solidity uint256 clearingPricePostProcessingOffset ``` ### auctionCompleted ```solidity bool auctionCompleted ``` ### auctionCancelledForWithdrawal ```solidity bool auctionCancelledForWithdrawal ``` ### completeAuctionPaused ```solidity bool completeAuctionPaused ``` ### termContractPaired ```solidity bool termContractPaired ``` ### onlyWhileAuctionClosed ```solidity modifier onlyWhileAuctionClosed() ``` This only runs if the auction is closed (after auction end time) *This uses the block timestamp to determine if the auction is closed* ### whenCompleteAuctionNotPaused ```solidity modifier whenCompleteAuctionNotPaused() ``` ### notTermContractPaired ```solidity modifier notTermContractPaired() ``` ### constructor ```solidity constructor() public ``` ### initialize ```solidity function initialize(string termRepoId_, string auctionId_, uint256 auctionEndTime_, uint256 termStart_, uint256 redemptionTimestamp_, contract IERC20MetadataUpgradeable purchaseToken_, address termAuctionInitializer_, uint256 clearingPricePostProcessingOffset_) external ``` Initializes the contract *See: * ### pairTermContracts ```solidity function pairTermContracts(contract ITermEventEmitter emitter_, contract ITermController controller_, contract ITermRepoServicer termRepoServicer_, contract ITermAuctionBidLocker termAuctionBidLocker_, contract ITermAuctionOfferLocker termAuctionOfferLocker_, address devopsMultisigAddress_, address adminWallet_, string version_) external ``` ### completeAuction ```solidity function completeAuction(struct CompleteAuctionInput completeAuctionInput) external ``` Calculates an auction's clearing price, assigns bids/offers, and returns unassigned funds #### Parameters | Name | Type | Description | | -------------------- | --------------------------- | ----------------------------------------------------------------------------------------- | | completeAuctionInput | struct CompleteAuctionInput | A struct containing all revealed and unrevealed bids and offers and expired rollover bids | ### cancelAuction ```solidity function cancelAuction(struct CompleteAuctionInput completeAuctionInput) public ``` Cancels an auction and returns all funds to bidders and fulfillBiders #### Parameters | Name | Type | Description | | -------------------- | --------------------------- | ----------------------------------------------------------------------------------------- | | completeAuctionInput | struct CompleteAuctionInput | A struct containing all revealed and unrevealed bids and offers and expired rollover bids | ### cancelAuctionForWithdrawal ```solidity function cancelAuctionForWithdrawal(address[] rolloverBorrowers, address[] rolloverPairOffTermRepoServicer) public ``` Cancels an auction and sets auctionCancelledForWithdrawal to true to open unlocking tenders ### \_increaseCumSumBids ```solidity function _increaseCumSumBids(struct TermAuctionRevealedBid[] sortedBids, uint256 startIndex, uint256 previousCumSumBids, uint256 currentPrice) internal pure returns (uint256, uint256) ``` ### \_decreaseCumSumBids ```solidity function _decreaseCumSumBids(struct TermAuctionRevealedBid[] sortedBids, uint256 startIndex, uint256 previousCumSumBids, uint256 currentPrice) internal pure returns (uint256, uint256) ``` ### \_minUint256 ```solidity function _minUint256(uint256 a, uint256 b) internal pure returns (uint256) ``` Returns the min of two `uint256` values #### Parameters | Name | Type | Description | | ---- | ------- | --------------------------- | | a | uint256 | The first value to compare | | b | uint256 | The second value to compare | #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------- | | \[0] | uint256 | The min of the two values | ### \_calculateClearingPrice ```solidity function _calculateClearingPrice(struct TermAuctionRevealedBid[] sortedBids, struct TermAuctionRevealedOffer[] sortedOffers, uint256 clearingOffset) internal pure returns (uint256, uint256) ``` Calculates the intersection between bid/offer schedules to arrive at a clearing price *Imagine a graph with price along the X-axis and cumsum(bid/offerAmount\*price) along the Y-axis. This function finds the point where the supply line crosses the demand line using binary search* #### Parameters | Name | Type | Description | | -------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- | | sortedBids | struct TermAuctionRevealedBid\[] | A sorted array of bids used to arrive at a demand schedule | | sortedOffers | struct TermAuctionRevealedOffer\[] | A sorted array of offers used to arrive at a supply schedule | | clearingOffset | uint256 | The offset to apply to the marginal bid and offer indexes when calculating the final clearing price | #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------------------------------------------- | | \[0] | uint256 | clearingPrice The price at which Term Auction will be cleared | | \[1] | uint256 | | ### \_findFirstIndexForPrice ```solidity function _findFirstIndexForPrice(uint256 price, struct TermAuctionRevealedBid[] sortedBids, uint256 startIndex) internal pure returns (uint256 i, uint256 totalAmount) ``` Finds the index of the first bid with a bidPrice of `price` and calculate the cumsum of the bid amounts up to that index #### Parameters | Name | Type | Description | | ---------- | -------------------------------- | --------------------------------- | | price | uint256 | The price to search for | | sortedBids | struct TermAuctionRevealedBid\[] | An array of sorted bids to search | | startIndex | uint256 | The index to start searching from | #### Return Values | Name | Type | Description | | ----------- | ------- | ----------------------------------------------------- | | i | uint256 | The index of the first bid with a bidPrice of `price` | | totalAmount | uint256 | The cumsum of the bid amounts up to return index i | ### \_findLastIndexForPrice ```solidity function _findLastIndexForPrice(uint256 price, struct TermAuctionRevealedOffer[] sortedOffers, uint256 startIndex) internal pure returns (uint256 i, uint256 totalAmount) ``` Finds the index of the last offer with a offerPrice of `price` and calculate the cumsum of the offer amounts up to that index #### Parameters | Name | Type | Description | | ------------ | ---------------------------------- | --------------------------------- | | price | uint256 | The price to search for | | sortedOffers | struct TermAuctionRevealedOffer\[] | An array of offers to search | | startIndex | uint256 | The index to start searching from | #### Return Values | Name | Type | Description | | ----------- | ------- | -------------------------------------------------------- | | i | uint256 | The index of the last offer with a offerPrice of `price` | | totalAmount | uint256 | The cumsum of the offer amounts up to return index i | ### \_fullyAssignBid ```solidity function _fullyAssignBid(struct TermAuctionRevealedBid bid) internal returns (uint256) ``` Fully assigns a bid #### Parameters | Name | Type | Description | | ---- | ----------------------------- | ----------------- | | bid | struct TermAuctionRevealedBid | The bid to assign | #### Return Values | Name | Type | Description | | ---- | ------- | ---------------------------- | | \[0] | uint256 | The amount that was assigned | ### \_fullyAssignOffer ```solidity function _fullyAssignOffer(struct TermAuctionRevealedOffer offer) internal returns (uint256) ``` Fully assigns an offer #### Parameters | Name | Type | Description | | ----- | ------------------------------- | ------------------- | | offer | struct TermAuctionRevealedOffer | The offer to assign | #### Return Values | Name | Type | Description | | ---- | ------- | ---------------------------- | | \[0] | uint256 | The amount that was assigned | ### \_partiallyAssignBid ```solidity function _partiallyAssignBid(struct TermAuctionRevealedBid bid, uint256 assignedAmount) internal returns (uint256) ``` Partially assigns a bid #### Parameters | Name | Type | Description | | -------------- | ----------------------------- | -------------------- | | bid | struct TermAuctionRevealedBid | The bid to assign | | assignedAmount | uint256 | The amount to assign | #### Return Values | Name | Type | Description | | ---- | ------- | ---------------------------- | | \[0] | uint256 | The amount that was assigned | ### \_partiallyAssignOffer ```solidity function _partiallyAssignOffer(struct TermAuctionRevealedOffer offer, uint256 assignedAmount) internal returns (uint256) ``` Partially assigns an offer #### Parameters | Name | Type | Description | | -------------- | ------------------------------- | -------------------- | | offer | struct TermAuctionRevealedOffer | The offer to assign | | assignedAmount | uint256 | The amount to assign | #### Return Values | Name | Type | Description | | ---- | ------- | ---------------------------- | | \[0] | uint256 | The amount that was assigned | ### \_assignRolloverBid ```solidity function _assignRolloverBid(address borrower, uint256 purchasePrice, uint256 repurchasePrice, address rolloverPairOffTermRepoServicer) internal ``` ### \_markRolloverAsProcessed ```solidity function _markRolloverAsProcessed(address rolloverPairOffTermRepoServicer, address borrower) internal ``` ### \_assignBids ```solidity function _assignBids(struct TermAuctionRevealedBid[] sortedBids, uint256 maxAssignable, uint256 purchaseTokenDecimals) internal returns (uint256) ``` Assigns bids up to `maxAssignable` *This method allocates pro-rata across an the marginal price group (pro-rata on the margin) and attempts to prevent residuals from accumulating to a single bid* #### Parameters | Name | Type | Description | | --------------------- | -------------------------------- | -------------------------------------------------------------- | | sortedBids | struct TermAuctionRevealedBid\[] | An array of sorted bids to process | | maxAssignable | uint256 | The maximum bid amount that can be assigned across all bidders | | purchaseTokenDecimals | uint256 | The number of decimals of the purchase token | #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------- | | \[0] | uint256 | The total amount assigned | ### \_assignOffers ```solidity function _assignOffers(struct TermAuctionRevealedOffer[] sortedOffers, uint256 maxAssignable, uint256 purchaseTokenDecimals) internal returns (uint256) ``` Assigns offers up to `maxAssignable` *This method allocates pro-rata across an the marginal price group (pro-rata on the margin) and attempts to prevent residuals from accumulating to a single offer* #### Parameters | Name | Type | Description | | --------------------- | ---------------------------------- | --------------------------------------------------------------- | | sortedOffers | struct TermAuctionRevealedOffer\[] | An array of sorted offers to process | | maxAssignable | uint256 | The maximum offer amount that can be assigned across all offers | | purchaseTokenDecimals | uint256 | The number of decimals of the purchase token | #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------- | | \[0] | uint256 | The total amount assigned | ### \_calculateRepurchasePrice ```solidity function _calculateRepurchasePrice(uint256 purchasePrice) internal view returns (uint256) ``` Calculates repurchase price given a purchase price (equivalent to principal plus interest) #### Parameters | Name | Type | Description | | ------------- | ------- | ------------------ | | purchasePrice | uint256 | The purchase price | #### Return Values | Name | Type | Description | | ---- | ------- | ------------------------------------------------------------------------------------------------- | | \[0] | uint256 | The repurchase price obtained by applying the clearing rate on an Actual/360 day-count convention | ### \_calculateAndStoreClearingPrice ```solidity function _calculateAndStoreClearingPrice(struct TermAuctionRevealedBid[] sortedBids, struct TermAuctionRevealedOffer[] sortedOffers) internal returns (uint256, uint256) ``` ### pauseCompleteAuction ```solidity function pauseCompleteAuction() external ``` \_This function pauses the TermAuction contract preventing public state changes See {Pausable-*pause}.* ### unpauseCompleteAuction ```solidity function unpauseCompleteAuction() external ``` Unpuses the TermAuction contract allowing public state changes \_See {Pausable-*unpause}.* ### \_authorizeUpgrade ```solidity function _authorizeUpgrade(address impl) internal ``` *required override by the OpenZeppelin UUPS module* #### Parameters | Name | Type | Description | | ---- | ------- | ---------------------------------- | | impl | address | new impl address for proxy upgrade | --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://developers.term.finance/0.9.0/term-repo-class/term-auction-group/termauction.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.