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	—

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.