> For the complete documentation index, see [llms.txt](https://sovavault.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sovavault.gitbook.io/docs/technical-resources/smart-contract-architecture.md).

# Smart Contract Architecture

### Key Architecture Principles

* **ERC-4626 Vault Standard**: Used to implement tokenized yield-bearing vaults with deposit/withdraw logic.
* **Minimal Proxy Pattern (EIP-1167)**: Enables gas-efficient cloning of strategy templates.
* **Role-Based Access Control (RBAC)**: Grants fine-grained permissions to different actors across the protocol.
* **Hook-Based Extensibility**: Compliance and control logic is modular via configurable hooks.

***

### Contract Components

#### Registry

* Central deployment and registration hub.
* Maintains mappings of valid strategies, tokens, assets, and hooks.

#### Strategies

* Logic for deploying capital into off-chain or on-chain opportunities.
* Types include `BasicStrategy`, `ReportedStrategy`, and `GatedMintRWAStrategy`.
* Each strategy is linked to its own tokenized vault.

#### tRWA Tokens

* ERC-4626-compatible vaults.
* Represent user shares in the underlying strategy.
* Types include:
  * `tRWA`: Standard implementation with compliance hooks.
  * `GatedMintRWA`: Supports two-phase deposits and escrow mechanics.

#### Role Manager

* Manages hierarchical access control using bitflag role identifiers.
* Enables protocol security and delegation.

#### Hook & Rules Engine

* Compliance hooks (e.g. KYC) intercept user operations.
* Hooks can be dynamically added/removed per operation (deposit, transfer, withdraw).

#### Reporters

* External oracles that provide NAV or price data.
* E.g., `PriceOracleReporter` to report off-chain asset values.

***

### 🛠️ Common Standards Used

| Standard    | Purpose                                     |
| ----------- | ------------------------------------------- |
| ERC-4626    | Vault logic and share accounting            |
| EIP-1167    | Gas-efficient proxy deployment              |
| Custom RBAC | Role-based permissions across all contracts |

***

### Core Roles

| Role Name          | Bitflag | Description                                |
| ------------------ | ------- | ------------------------------------------ |
| PROTOCOL\_ADMIN    | 1       | Can configure global protocol settings     |
| STRATEGY\_ADMIN    | 2       | Manages strategies and registry entries    |
| RULES\_ADMIN       | 4       | Controls hook permissions and rules engine |
| STRATEGY\_OPERATOR | 8       | Executes fund operations within strategies |
| KYC\_OPERATOR      | 16      | Manages KYC allow/deny lists               |
| PRICE\_UPDATER     | 32      | Updates external pricing oracles           |

***

### Lifecycle Flow (Simplified)

1. **Strategy Deployment**
   * Registry clones strategy using proxy pattern.
   * Strategy initializes and links to newly deployed vault token.
2. **User Deposit**
   * User deposits USDC or BTC (wrapped) into tRWA token.
   * Hooks validate the deposit.
   * Shares are minted to the user.
3. **Strategy Execution**
   * Strategy manager moves funds to yield sources.
4. **Redemption**
   * Users withdraw assets by redeeming tRWA tokens.
   * Yield and NAV reflected in token share value.