> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usmewe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TrustVault.sol

> Protocol liquidity pool contract

# TrustVault Contract

The TrustVault contract manages the protocol's liquidity pool, handling staking, borrowing, and yield distribution.

## Overview

| Property         | Value          |
| ---------------- | -------------- |
| Solidity Version | 0.8.24         |
| License          | MIT            |
| Audited          | Yes            |
| Upgradeable      | No (immutable) |

## Contract Address

<Tabs>
  <Tab title="Mainnet">
    ```
    BASE Mainnet: 0x...
    ```
  </Tab>

  <Tab title="Testnet">
    ```
    BASE Sepolia: 0x...
    ```
  </Tab>
</Tabs>

## Interface

```solidity theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

interface ITrustVault {
    // Events
    event Deposited(address indexed user, uint256 amount, uint256 shares);
    event Withdrawn(address indexed user, uint256 shares, uint256 amount);
    event Borrowed(address indexed user, uint256 amount, uint256 dueDate);
    event Repaid(address indexed user, uint256 loanId, uint256 amount);
    event DefaultRecorded(address indexed user, uint256 loanId);

    // View Functions
    function totalAssets() external view returns (uint256);
    function totalShares() external view returns (uint256);
    function exchangeRate() external view returns (uint256);
    function utilizationRate() external view returns (uint256);
    function borrowRate() external view returns (uint256);
    function supplyRate() external view returns (uint256);

    // User Functions
    function deposit(uint256 amount) external returns (uint256 shares);
    function withdraw(uint256 shares) external returns (uint256 amount);
    function borrow(uint256 amount, uint256 duration) external returns (uint256 loanId);
    function repay(uint256 loanId) external;

    // View User State
    function balanceOf(address user) external view returns (uint256);
    function getUserLoans(address user) external view returns (Loan[] memory);
}
```

## Data Structures

```solidity theme={null}
struct Loan {
    uint256 id;
    address borrower;
    uint256 principal;
    uint256 interest;
    uint256 dueDate;
    LoanStatus status;
}

enum LoanStatus {
    ACTIVE,
    REPAID,
    DEFAULTED
}
```

## Key Functions

### deposit

Stake USDC and receive tmUSDC shares.

```solidity theme={null}
function deposit(uint256 amount) external returns (uint256 shares);
```

**Parameters:**

* `amount`: Amount of USDC to deposit (6 decimals)

**Returns:**

* `shares`: Amount of tmUSDC shares received

**Example:**

<CodeGroup>
  ```solidity Solidity theme={null}
  ITrustVault vault = ITrustVault(VAULT_ADDRESS);
  IERC20(USDC).approve(VAULT_ADDRESS, 1000e6);
  uint256 shares = vault.deposit(1000e6);
  ```

  ```typescript ethers.js theme={null}
  const vault = new ethers.Contract(VAULT_ADDRESS, VAULT_ABI, signer);
  const usdc = new ethers.Contract(USDC_ADDRESS, ERC20_ABI, signer);

  await usdc.approve(VAULT_ADDRESS, ethers.parseUnits("1000", 6));
  const tx = await vault.deposit(ethers.parseUnits("1000", 6));
  await tx.wait();
  ```
</CodeGroup>

### borrow

Borrow USDC based on Trust Score.

```solidity theme={null}
function borrow(uint256 amount, uint256 duration) external returns (uint256 loanId);
```

**Parameters:**

* `amount`: Amount of USDC to borrow
* `duration`: Loan duration in seconds

**Requirements:**

* Caller must have sufficient Trust Score
* Amount must not exceed borrowing limit
* Vault must have sufficient liquidity

### repay

Repay an active loan.

```solidity theme={null}
function repay(uint256 loanId) external;
```

**Parameters:**

* `loanId`: ID of the loan to repay

**Requirements:**

* Caller must be the borrower
* Loan must be active
* Caller must have approved sufficient USDC

## Interest Rate Model

The vault uses a utilization-based interest rate:

```solidity theme={null}
function calculateBorrowRate(uint256 utilization) public pure returns (uint256) {
    // Base rate: 2%
    uint256 baseRate = 2e16;

    if (utilization <= 80e16) {
        // Linear increase up to 80% utilization
        return baseRate + (utilization * 3e16) / 80e16;
    } else {
        // Steep increase above 80%
        uint256 excess = utilization - 80e16;
        return 5e16 + (excess * 50e16) / 20e16;
    }
}
```

## Security

<Warning>
  The TrustVault integrates with an oracle for Trust Score verification. Only authorized oracles can update scores.
</Warning>

### Access Control

| Function         | Access              |
| ---------------- | ------------------- |
| deposit          | Anyone              |
| withdraw         | Share holders       |
| borrow           | Trust Score holders |
| updateTrustScore | Oracle only         |
| pause            | Admin only          |

### Emergency Functions

```solidity theme={null}
function pause() external onlyAdmin;
function unpause() external onlyAdmin;
function emergencyWithdraw() external onlyAdmin;
```

## Events

Monitor contract activity by subscribing to events:

```typescript theme={null}
vault.on("Deposited", (user, amount, shares) => {
  console.log(`${user} deposited ${amount} USDC for ${shares} shares`);
});

vault.on("Borrowed", (user, amount, dueDate) => {
  console.log(`${user} borrowed ${amount} USDC, due ${dueDate}`);
});
```

<Card title="View on GitHub" icon="github" href="https://github.com/Topxl/UsMeWe/blob/main/contracts/src/TrustVault.sol">
  Full source code
</Card>