> For the complete documentation index, see [llms.txt](https://docs.townsq.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.townsq.xyz/institution-backed-yield-vault-features/yield-vault/reference/functions-reference.md).

# Functions Reference

## Function reference

Functions available to you as a depositor, plus the standard ERC-4626 surface and where it deviates.

{% hint style="warning" %}
**Integrators start here.** This vault deviates from ERC-4626 in three ways that will break naive integrations: withdrawal requires a prior request, `maxWithdraw`/`maxRedeem` over-report, and allowance-based withdrawal is disabled.
{% endhint %}

### Entering

#### `deposit(uint256 assets, address receiver) → uint256 shares`

Standard. Transfers `assets` from you, mints shares to `receiver`. Assets are forwarded to the Manager in the same transaction.

Reverts: `InvalidMinShares` (below minimum), `InvalidDeposit` (zero amount/shares/receiver), `EnforcedPause`.

#### `mint(uint256 shares, address receiver) → uint256 assets`

Standard. Mints an exact share count, pulling however many assets that requires.

### Exiting

#### `requestRedeem(uint256 shares)`

**Step 1 of withdrawal.** Burns your shares immediately, quotes your payout at the current price net of the exit fee, stores it, and starts the cooldown.

Mints the exit fee to the treasury as shares.

Reverts: `RedemptionRequestAlreadyExists`, `ZeroAmount`, `InsufficientShares`, `InsufficientAssets`, `MaxRedeemCapExceeded`, `EnforcedPause`.

{% hint style="danger" %}
Irreversible. There is no cancel function.
{% endhint %}

#### `redeem(uint256 shares, address receiver, address owner) → uint256 assets`

**Step 2.** Pays out your stored request. `shares` must **exactly equal** the stored share count. `msg.sender` must equal `owner`.

Reverts: `NoRedemptionRequest`, `CooldownNotFinished`, `InvalidWithdrawalRequest` (inexact amount), `NotAuthorized` (caller ≠ owner), `EnforcedPause`, or an ERC-20 transfer revert if the vault is unfunded.

#### `withdraw(uint256 assets, address receiver, address owner) → uint256 shares`

Same as `redeem`, but keyed on the stored asset amount instead. Same exact-match and self-only rules.

### Reading your position

| Function                          | Returns                                    |
| --------------------------------- | ------------------------------------------ |
| `balanceOf(address)`              | Your share balance                         |
| `getRedeemRequest(address)`       | `(shares, assets, timestamp, exists)`      |
| `canExecuteRedeem(address)`       | Whether the cooldown has elapsed           |
| `previewRedeem(uint256 shares)`   | Assets you would be quoted, **net of fee** |
| `convertToAssets(uint256 shares)` | Gross value, no fee applied                |
| `convertToShares(uint256 assets)` | Shares for a given asset amount            |
| `exchangeRate()`                  | Current share price                        |

### Reading vault state

| Function                              | Returns                                             |
| ------------------------------------- | --------------------------------------------------- |
| `totalAssets()`                       | Recognised assets — excludes profit still vesting   |
| `getUnvestedAmount()`                 | Profit reported but not yet in the share price      |
| `totalSupply()`                       | Shares outstanding                                  |
| `totalRequestedAmount()`              | Assets owed to all pending requests                 |
| `fee()`                               | Exit fee, `1e18` = 1%                               |
| `cooldownPeriod()`, `vestingPeriod()` | In seconds                                          |
| `paused()`                            | Whether deposits and withdrawals are blocked        |
| `asset()`                             | The underlying token address                        |
| `decimals()`                          | Share decimals — **18**, even for a 6-decimal asset |

### Reading yield state

On the Yield contract:

| Function                                     | Returns                           |
| -------------------------------------------- | --------------------------------- |
| `epoch()`                                    | Current epoch number              |
| `lastDistributionTime()`                     | Timestamp of the last report      |
| `profit()`, `loss()`                         | Cumulative reported figures       |
| `treasuryDebt()`                             | Unabsorbed loss the treasury owes |
| `maxYieldPercentage()`, `maxFeePercentage()` | Caps, in basis points             |
| `minDistributionInterval()`                  | Minimum seconds between reports   |

### ERC-4626 deviations

| Function                            | Standard behaviour            | Here                                                  |
| ----------------------------------- | ----------------------------- | ----------------------------------------------------- |
| `withdraw` / `redeem`               | Immediate                     | Requires a prior `requestRedeem` and elapsed cooldown |
| `maxWithdraw` / `maxRedeem`         | Accurate ceiling              | **Not overridden — over-reports**                     |
| Allowance withdrawal                | Approved spender can withdraw | **Disabled** — `caller` must equal `owner`            |
| `previewWithdraw` / `previewRedeem` | No fee                        | Includes the exit fee                                 |
| `previewDeposit` / `previewMint`    | —                             | Unchanged; entry is free                              |
| `totalAssets`                       | Token balance                 | Accounting figure; vault holds no assets              |

{% hint style="danger" %}
Do not size a withdrawal from `maxWithdraw` or `maxRedeem`. Use `getRedeemRequest` and pass the stored value back exactly.
{% endhint %}

### Functions you cannot call

Listed so you know they exist and who controls them:

| Function                                                | Contract        | Restricted to                                                       |
| ------------------------------------------------------- | --------------- | ------------------------------------------------------------------- |
| `execute`                                               | Manager         | Operator                                                            |
| `transferToVault`                                       | Manager         | Operator                                                            |
| `redeemFor`                                             | Vault / Manager | Manager only — pays the user their locked amount, no cooldown check |
| `distributeYield`                                       | Yield           | Rebalancer                                                          |
| `setFee`, `setCooldownPeriod`, `setVestingPeriod`       | Vault           | Admin                                                               |
| `pause`, `unpause`, `emergencyRecover`                  | Vault           | Admin                                                               |
| `setWhitelistedAddresses`, `setTreasury`                | Manager         | Admin                                                               |
| `updateTotalAssets`, `mintVaultToken`, `burnVaultToken` | Vault           | Manager only                                                        |