uwu-factory-v1-1-0
The uwu-factory-v1-1-0
contract serves as the central management system for Vaults and is the sole authorized caller for minting and burning tokens in the uwu-token-v1-1-0
contract. Users can deposit STX as collateral into the contract and mint UWU tokens in return. Furthermore, users can deposit UWU into the contract and burn it by repaying debt, allowing them to reclaim their STX collateral.
Data Storage
These structures allow the contract to maintain its state, track information, and ensure data consistency throughout the contract's lifecycle.
last-vault-id
A data variable that stores the ID of the most recently opened Vault.
opened-vault-count
A data variable that keeps track of the current number of opened Vaults.
liquidated-vault-count
A data variable that stores the total number of Vaults that have been liquidated.
vaults
A map that stores information related to each Vault, including its ID, the owning principal, the amount of deposited collateral, the current debt, the block-height at which the Vault was opened (in Stacks blocks), and the liquidation status of the Vault.
vault-entries
A map that maintains a record of the IDs of each of the opened Vaults owned by each principal, with a maximum limit of 20 Vaults per principal at any given time.
last-removed-entry
A map that stores the most recent ID removed from the vault-entries
map for each principal.
Public Functions
These functions are accessible by external contracts or users, enabling interaction with the contract and state modification.
open-vault
A public function that creates a new Vault for the tx-sender
using the provided collateral and debt amounts. The collateral ratio must be at least 150%. A minimum of 25 UWU (u25000000
) must be borrowed and a 100bps (1.00%) one-time borrow fee is taken from the debt borrowed.
Parameter | Type | Description |
collateral | uint | The amount of collateral to deposit |
debt | uint | The amount of debt to borrow |
borrow-vault
A public function that enables the owner of a specified Vault to take on additional debt in that Vault. The tx-sender
must be the owner of the Vault. The Vault cannot be liquidated, and the collateral ratio must be at least 150%, taking into account the newly borrowed amount. A minimum of 1 UWU (u1000000
) must be borrowed and a 100bps (1.00%) one-time borrow fee is taken from the debt borrowed. If the Vault has zero debt, a minimum of 25 UWU (u25000000
) must be borrowed.
Parameter | Type | Description |
id | uint | The ID of the Vault to borrow from |
amount | uint | The amount of debt to borrow |
collateralize-vault
A public function that allows the owner of a specified Vault to deposit additional collateral into that Vault. The tx-sender
must be the owner of the Vault, and the Vault cannot be liquidated.
Parameter | Type | Description |
id | uint | The ID of the Vault to collateralize |
amount | uint | The amount of collateral to deposit |
repay-vault
A public function that allows the owner of a specified Vault to repay the debt of that Vault. The tx-sender
must be the owner of the Vault, and the Vault cannot be liquidated. The amount repaid must either equal the total debt of the Vault or leave a remaining debt of at least 25 UWU (u25000000
) in the Vault to prevent dust amounts from being left behind.
Parameter | Type | Description |
id | uint | The ID of the Vault to repay debt in |
amount | uint | The amount of debt to repay |
withdraw-vault
A public function that enables the owner of a specified Vault to withdraw excess collateral from that Vault. The tx-sender
must be the owner of the Vault, the Vault cannot be liquidated, and the collateral ratio must remain at least 150% after accounting for the withdrawn amount.
Parameter | Type | Description |
id | uint | The ID of the Vault to withdraw from |
amount | uint | The amount of collateral to withdraw |
transfer-vault
A public function that permits the owner of a specified Vault to transfer ownership of that Vault to a new principal. The tx-sender
must be the owner of the Vault, the Vault cannot be liquidated, and the receiver cannot currently own more than 20 Vaults. Once transferred, the receiver gains full control of the Vault, and the original owner loses access unless the Vault is transferred back. The ID of the Vault is removed from the original owner's vault-entries
map and added to the new owner's map.
Parameter | Type | Description |
id | uint | The ID of the Vault to transfer |
account | principal | The principal receiving ownership of the Vault |
close-vault
A public function that enables the owner of a specified Vault to close that Vault. The tx-sender
must be the owner of the Vault, and both the collateral and debt amounts in the Vault must be zero. Once closed, the Vault ID is removed from the owner's vault-entries
map, and the information associated with the Vault is deleted from the vaults
map.
Parameter | Type | Description |
id | uint | The ID of the Vault to close |
liquidate-vault
A public function that allows anyone to liquidate a specified Vault if its collateral ratio falls below 150%. The tx-sender
does not need to be the owner of the Vault. If liquidated, the Vault is then purchasable via the purchase-vault
public function. Following liquidation, the owner can no longer deposit collateral, borrow UWU, or execute other actions on the vault, except for closing it once the collateral and debt amounts reach zero.
Parameter | Type | Description |
id | uint | The ID of the Vault to liquidate |
purchase-vault
A public function that enables anyone to repay the debt in a specified liquidated Vault in exchange for the Vault's collateral. The tx-sender
does not need to be the owner. Users can purchase any portion of the Vault, receiving a proportionate share of the collateral. For instance, if a user repays 10% of the debt in a liquidated Vault, they would receive 10% of the Vault's collateral. The amount purchased must either equal the total debt of the Vault or leave a remaining debt of at least 25 UWU (u25000000
) in the Vault to prevent dust amounts from being left behind.
Parameter | Type | Description |
id | uint | The ID of the Vault to purchase from |
amount | uint | The amount of debt to repay |
Private Functions
These functions are accessible only within the contract they are defined in, providing encapsulation and preventing external access to specific functionality.
get-collateral-ratio
A private function that calculates the collateral ratio based on the given collateral and debt amounts.
Parameter | Type | Description |
collateral | uint | The amount of collateral |
debt | uint | The amount of debt |
remove-vault-entry
A private function that removes a specified ID linked to an open Vault, owned by the tx-sender
, from the vault-entries
map. This function does not remove the Vault from the vaults
map.
Parameter | Type | Description |
id | uint | The ID to remove |
Read-only Functions
These functions do not modify the contract's state and are used for querying or retrieving data. They can be called by external contracts or users but will not change the underlying state.
get-last-vault-id
A read-only function that returns the ID of the last opened Vault.
get-opened-vault-count
A read-only function that returns the number of Vaults that are currently opened.
get-liquidated-vault-count
A read-only function that returns the number of Vaults that have been liquidated.
get-vault
A read-only function that returns the information associated with a Vault, including its owner, deposited collateral, current debt, the block-height at which the Vault was opened (in Stacks blocks), and its liquidation status.
Parameter | Type | Description |
id | uint | The ID of the Vault to query |
get-vault-entries
A read-only function that retrieves the list of IDs associated with the Vaults currently opened and owned by a specified principal.
Parameter | Type | Description |
account | principal | The principal to query |
get-vaults
A read-only function that fetches the detailed information for each opened Vault owned by a specified principal.
Parameter | Type | Description |
account | principal | The principal to query |
get-can-liquidate-vault
A read-only function that returns whether a Vault can be liquidated, along with its current collateral ratio.
Parameter | Type | Description |
id | uint | The ID of the Vault to query |
Last updated