Collateral vault

The collateral vault puzzle enables XCH to be locked and BYC to be minted based on XCH price. Their vaults are custom singletons and can be created permissionlessly by anyone. The inner puzzle of the collateral vault must be chosen/designed suitably as it could lead to the operations/funds becoming inaccessible. Loans that are taken out from the collateral vault accrue stability fees. If the collateral locked falls below the liquidation threshold, the vault becomes eligible for liquidation and the owner operations become inaccessible. The vault also keeps track of the following:

• Collateral in the vault

• The principal amount of outstanding loans (total borrowed - total repaid)

• Auction state - the state of the liquidation auction if it has started

• Inner puzzle hash

• Discounted principal

The debt in the vault is not stored in a separate variable but calculated on an ad hoc basis as follows:

debt(t) = discounted_principal * CCSFDF_t  (where CCSFDF_t is the Current Cumulative Stability Fee Discount Factor at time t)

The stability fee could therefore be calculated as

SF = debt - principal

Operations

The following operations can be performed on the collateral vault:

• Owner operations. These operations can only be triggered by the owner.

  • The deposit-collateral operation increases the collateral amount in the vault.

  • The withdraw-collateral operation decreases the collateral amount in the vault while verifying that the collateral remaining is above the liquidation threshold.

  • The borrow-BYC (create debt) operation signals the tail to issue a certain BYC amount while verifying that the requested amount of BYC to mint does not take the vault below liquidation threshold.

  • The repay-BYC (debt + fees) operation repays the provided amount to the vault and transfers the stability fee to a treasury coin.

  • The transfer-the-vault operation allows changing the inner puzzle hash of the vault.

  • The transfer-fees-to-treasury operation transfers the stability fee to the treasury.

• Keeper operations. These operations can be triggered by keepers.

  • The start-auction operation sets the auction_state parameters. If the collateral in the vault falls below the minimum collateral required, an auction could be started. A small amount from the total fee is stored as the initiator-incentive balance to incentivize keepers to initiate liquidations.

  • The bid operation allows keepers to bid on the collateral. The puzzle calculates the amount of XCH the bidder will receive based on the amount of BYC they bid. (Read more about an issue discovered in the calculation in Finding .) The bid amount first goes to the initiator, then to the treasury, and the remaining amount is melted.

  • For the recover-bad-debt operation, if all the collateral has been sold off to bidders without all debt being repaid, this puzzle could be used. This amount is withdrawn from the treasury coin and melted.

Condition filtering and solution-parameters verification

The vault operations, args, and the statutes inner puzzle hash is provided via the REMARK condition from the inner puzzle if the operation is an owner operation and directly from the solution provided by the keeper if the operation is a keeper operation. It is important for the puzzle to accurately filter out the REMARK condition. Furthermore, it is crucial that the inner puzzle does not output any other protocol-specific conditions and does not have any CREATE_COIN condition as it might lead to incorrectly proving lineage with curried-in parameters.

The parameters provided in the solution must also be verified to be accurate, and this is done via either asserting their values from the statutes announcements or returning other conditions from the vault that verify their correctness. For instance, the statutes_cumulative_stability_fee_rate and current_timestamp are verified via the statutes announcement and the ASSERT_SECONDS_ABSOLUTE/ASSERT_BEFORE_SECONDS_ABSOLUTE condition, respectively. Failure to verify any such parameter might lead to critical issues as, in that case, these parameters could be set to user-provided values without being verified (read more about this in Finding ).

Test coverage

Intended branches

Negative behavior