# 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
```
(define-data-var last-vault-id uint u0)
```
A data variable that stores the ID of the most recently opened Vault.
### opened-vault-count
```
(define-data-var opened-vault-count uint u0)
```
A data variable that keeps track of the current number of opened Vaults.
### liquidated-vault-count
```
(define-data-var liquidated-vault-count uint u0)
```
A data variable that stores the total number of Vaults that have been liquidated.
### vaults
```
(define-map vaults uint
{
id: uint,
owner: principal,
collateral: uint,
debt: uint,
height: uint,
liquidated: bool
}
)
```
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
```
(define-map vault-entries principal (list 20 uint))
```
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
```
(define-map last-removed-entry principal uint)
```
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
(define-public (open-vault (collateral uint) (debt uint)))
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
```
(define-public (borrow-vault (id uint) (amount uint)))
```
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
```
(define-public (collateralize-vault (id uint) (amount uint)))
```
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
```
(define-public (repay-vault (id uint) (amount uint)))
```
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
```
(define-public (withdraw-vault (id uint) (amount uint)))
```
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
```
(define-public (transfer-vault (id uint) (account principal)))
```
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
```
(define-public (close-vault (id uint)))
```
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
```
(define-public (liquidate-vault (id uint)))
```
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
```
(define-public (purchase-vault (id uint) (amount uint)))
```
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
```
(define-private (get-collateral-ratio (collateral uint) (debt uint)))
```
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
```
(define-private (remove-vault-entry (id uint)))
```
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
```
(define-read-only (get-last-vault-id))
```
A read-only function that returns the ID of the last opened Vault.
### get-opened-vault-count
```
(define-read-only (get-opened-vault-count))
```
A read-only function that returns the number of Vaults that are currently opened.
### get-liquidated-vault-count
```
(define-read-only (get-liquidated-vault-count))
```
A read-only function that returns the number of Vaults that have been liquidated.
### get-vault
```
(define-read-only (get-vault (id uint)))
```
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
```
(define-read-only (get-vault-entries (account principal)))
```
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
```
(define-read-only (get-vaults (account principal)))
```
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
```
(define-read-only (get-can-liquidate-vault (id uint)))
```
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 |