> 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/overview/architecture.md).

# Architecture

### Contract Relationships

```
                    ┌──────────────────────┐
   user ──deposit──▶│    townSqToken       │──safeTransferFrom──▶ Manager
   user ──request──▶│  (ERC4626, UUPS)     │                      (holds all assets)
   user ──withdraw─▶│                      │◀──transferToVault────┘
                    └──────────┬───────────┘
                               │ reads manager.treasury()
                               │ reads manager.yield()
                               │ reads manager.maxRedeemCap()
                               │ reads manager.minSharesInVaultToken()
                               ▼
                    ┌──────────────────────┐
                    │      Manager         │──call()──▶ whitelisted DeFi protocols
                    │       (UUPS)         │
                    └──────────▲───────────┘
                               │ manageAssetAndShares()
                    ┌──────────┴───────────┐
   rebalancer ─────▶│       Yield          │──transferInRewards()──▶ townSqToken
                    │       (UUPS)         │
                    └──────────────────────┘
```

All three core contracts sit behind `townSqProxy` (ERC1967 + UUPS). All three contracts are UUPS-upgradeable behind ERC-1967 proxies. The addresses you interact with are the proxies, and they do not change when the implementation is upgraded.

### Who can do what

Full enumeration in Roles and permissions.

| Actor                                       | Can                                                                                  | Cannot                                                |
| ------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| **You**                                     | Deposit, request redemption, collect your own redemption                             | Anything else                                         |
| **Operator**                                | Deploy capital to whitelisted addresses, fund the vault, settle a user's request     | Change the allowlist, report yield, change parameters |
| **Rebalancer**                              | Report each epoch's profit or loss                                                   | Move any asset                                        |
| **Admin** (timelock, 48h)                   | Set the allowlist, fees, cooldown, caps; pause and unpause; emergency-recover assets | —                                                     |
| **Guardian**                                | Pause the vault, remove whitelist entries — instantly                                | Unpause, add to the allowlist, change parameters      |
| **Governance (root admin)** (timelock, 48h) | Upgrade all contracts, grant and revoke every role                                   | —                                                     |

{% hint style="warning" %}
The Admin role can both whitelist a destination and extract assets from the vault, and both go through a **48-hour timelock** — delayed and public, but not prevented. Deposit sizing should account for this. See Governance and the timelock.
{% endhint %}