TwoClickLiquidationSkeleton

Implementation of the Liquidation sub-skeleton facet for the TMI-Fraction Protocol.

_This facet serves as a sub-core component (sub-skeleton) of a TMI-Fraction Platform, enabling eligible users (e.g., designated liquidators) to liquidate SALE BBO (BuyBackOption) campaigns in cases of buyback failure or margin call failure.

IMPORTANT:

• This implementation is intended only for Platforms that support SALE BBO (BuyBackOption) campaigns where wrapped assets are digital twin on-chain representations (twin NFTs) of real-world assets (RWA).

• This implementation features a two (2) step liquidation process:

  1. Forced Unlocking of Twin NFT: An eligible user (e.g., the campaign’s designated liquidator) invokes forcefullyUnlockWrappersNft() to forcibly unlock the campaign's twin NFT representing the RWA under liquidation. The NFT is transferred to the caller, granting ownership rights over the underlying RWA. The recipient may then handle the RWA off-chain (e.g., sell it at auction and convert the proceeds into the campaign’s funding currency).

  2. Buyback After Liquidation: A designated user (e.g., the same user from the previous step) fulfills the campaign’s obligation by executing a buyback via buyBackAfterLiquidation(), ensuring the liquidation process is completed.

The first step of the liquidation process is triggered when forcefullyUnlockWrappersNft() is executed, following a sequential pipeline of three phases:

• State Check: The Platform interacts with its LiquidationState sub-internal facet to verify that the targeted campaign is in a valid state for liquidation.

• Eligibility Check: The Platform interacts with its LiquidationEligibility sub-internal facet to verify that the user (caller) meets the campaign's eligibility criteria to perform liquidation.

• Unlock Action: The Platform interacts with its LiquidationForceUnlock sub-internal facet to forcibly unlock the campaign's wrapped twin NFT and transfer it to the user (caller).

The second step of the liquidation process is triggered when buyBackAfterLiquidation() is executed, following a sequential pipeline of four phases:

• State Check: The Platform interacts with its LiquidationState sub-internal facet to verify that the targeted campaign is in a valid state for liquidation.

• Eligibility Check: The Platform interacts with its LiquidationEligibility sub-internal facet to verify that the user (caller) meets the campaign's eligibility criteria to perform liquidation.

• Unlock Verification: The Platform verifies, through its LiquidationForceUnlock sub-internal facet, that the twin NFT has been successfully unlocked in the previous step.

• Buyback Post-Liquidation Action: The Platform interacts with its LiquidationBuyBack sub-internal facet to transfer the funds (campaign's required total obligation) from the user (caller) to the Platform and subsequently update the campaign's state, thereby finalizing the liquidation process._

InvalidBuybackBeforeForceUnlock

error InvalidBuybackBeforeForceUnlock(uint256 campaignId)

Thrown when buyBackAfterLiquidation() is invoked before the campaign's wrapped NFT has been unlocked.

ForceUnlockHappened

event ForceUnlockHappened(uint256 campaignId, address receiver)

Emitted at forcefullyUnlockWrappersNft().

BuyBackAfterLiquidation

event BuyBackAfterLiquidation(uint256 campaignId, address account)

Emitted at buyBackAfterLiquidation().

forcefullyUnlockWrappersNft

function forcefullyUnlockWrappersNft(uint256 campaignId) external

Allows an eligible party to forcibly unlock the campaign's wrapped NFT, enabling proper handling and buyback post liquidation to occur.

_Users must meet eligibility criteria (see liquidation Eligibility sub-internal facets).

This action should only be allowed when the campaign's state is LIQUIDATION.

Emits a {ForceUnlockHappened} event._

Parameters

buyBackAfterLiquidation

function buyBackAfterLiquidation(uint256 campaignId) external

Allows an eligible party to perform a buyback in the specified campaign after the campaign's wrapped NFT has been forcibly unlocked.

_The caller must meet eligibility criteria (see liquidation Eligibility sub-internal facets).

This action can only be executed after the campaign's wrapped NFT has been forcibly unlocked (see forcefullyUnlockWrappersNft()) and should only be allowed when the campaign's state is `LIQUIDATION._

Parameters

oracleHook

function oracleHook(uint256) external view returns (bool)

This hook is called by the oracle when the campaign's liquidation state has been reached, and the oracle needs to verify whether it can update the state based on certain conditions.

_Selector: 0xa90f93b8

In the current version, if the price of the underlying asset (RWA) falls below the campaign's obligation and is not rebalanced through margin addition or price resettlement within the designated time window, the liquidation process must be executed and finalized. Thus, currently, when a SALE BBO campaign reaches the LIQUIDATION state, it can only progress to another state through the execution of buyBackAfterLiquidation() and cannot progress via the oracle itself, as no fallback mechanisms are in place yet (e.g., Insurance Pool).

IMPORTANT:

• An insurance pool feature will be added in a future update._