# ShareManager

### Overview

The `ShareManager` is an abstract upgradeable contract responsible for managing vault share issuance, allocation, whitelisting, permissions, and lockups in a modular vault system. It relies on a compact bitmask (`flags`) for enabling/disabling features and supports configurable per-account permissions.

### Key Responsibilities

* Tracking total and active share supply
* Managing global and per-account lockups
* Verifying whitelist and transfer permissions
* Enforcing mint/burn/transfer pauses
* Allocating and claiming shares through queues
* Emitting granular control events on state transitions

### Storage

Storage is accessed via a deterministic slot generated by `SlotLibrary.getSlot("ShareManager", name, version)`.

```solidity
struct ShareManagerStorage {
    address vault;
    uint256 flags; // Encodes permissions and lockup durations
    uint256 allocatedShares;
    bytes32 whitelistMerkleRoot;
    mapping(address => AccountInfo) accounts;
}
```

### Permission System

Controlled through roles defined as:

* `SET_FLAGS_ROLE`: Allows changing global flags (e.g., mint pause, whitelist enforcement).
* `SET_ACCOUNT_INFO_ROLE`: Grants permission to set per-account configuration.
* `SET_WHITELIST_MERKLE_ROOT_ROLE`: Grants permission to set new whitelist merkle root.
* All share-related actions are guarded via:
  * `onlyQueue()`
  * `onlyVaultOrQueue()`
  * `onlyRole(...)`

### View Functions

* `vault()`: Returns the vault address.
* `sharesOf(account)`: Total shares (active + claimable).
* `activeSharesOf(account)`: Abstract; must be implemented by child.
* `claimableSharesOf(account)`: Reads from the `IShareModule`.
* `totalShares()`: `allocatedShares + activeShares()`
* `accounts(account)`: Returns `AccountInfo` struct (deposit/transfer flags, lockups, blacklisting).
* `flags()`: Decoded bitmask as `Flags` struct.
* `whitelistMerkleRoot()`: Current root used for off-chain whitelist proof verification.
* `isDepositorWhitelisted(account, proof)`: Verifies Merkle proof or checks local permission flags.
* `updateChecks(from, to)`: Reverts on violations (paused actions, lockups, blacklisting, etc.).

### Mutable Functions

* `setVault(...)`: One-time vault initialization.
* `setFlags(...)`: Updates global bitmask configuration.
* `setWhitelistMerkleRoot(…)`: Updates whitelist merkle root.
* `setAccountInfo(...)`: Sets access rights for an individual address.
* `claimShares(...)`: Claims shares from the vault’s `IShareModule`.
* `allocateShares(...)`: Allocates shares for future minting (only callable by a queue).
* `mintAllocatedShares(...)`: Mints shares from allocated pool to user.
* `mint(...)`: Mints shares to a user with optional lockup.
* `burn(...)`: Burns a user’s shares (only queue).
* `__ShareManager_init(...)`: Sets Merkle root at construction or upgrade.

### Internal Hooks (Implemented by Child)

```solidity
function _mintShares(address account, uint256 value) internal virtual;
function _burnShares(address account, uint256 value) internal virtual;
```

These abstract functions allow concrete implementations to define how share balances are recorded or tokenized.

### Bitmask-Controlled Features

Controlled via `ShareManagerFlagLibrary`:

* `hasMintPause`
* `hasBurnPause`
* `hasTransferPause`
* `hasWhitelist`
* `hasTransferWhitelist`
* `globalLockup`
* `targetedLockup`

Lockups are enforced in `updateChecks`.