# Assign OVM Roles

This guide explains how to assign permissions within the Obol Vault Manager (OVM) smart contract using its bitwise role system and outlines key security recommendations.

***

## 1. Understanding the Bitwise Role System

The OVM contract manages permissions by assigning each role a unique power-of-two value (a single binary bit). To grant multiple roles, you simply add (or bitwise OR) their values together to produce a single, final integer that the smart contract reads.

### Contract Role Definitions

| Role Name                  | Decimal Value | Hex Value | Primary Purpose                               |
| -------------------------- | ------------- | --------- | --------------------------------------------- |
| **`WITHDRAWAL_ROLE`**      | 1             | `0x01`    | Initiate validator withdrawals/claims.        |
| **`CONSOLIDATION_ROLE`**   | 2             | `0x02`    | Initiate validator consolidation (migration). |
| **`SET_BENEFICIARY_ROLE`** | 4             | `0x04`    | Set/change the principal/withdrawal address.  |
| **`RECOVER_FUNDS_ROLE`**   | 8             | `0x08`    | Emergency recovery of stuck assets.           |
| **`SET_REWARD_ROLE`**      | 16            | `0x10`    | Set/change the reward fee recipient address.  |
| **`DEPOSIT_ROLE`**         | 32            | `0x20`    | Submit validator deposit data.                |

## 2. Guide to Assigning and Managing Roles

The easiest way to generate the required hex code is by using the dedicated calculator tool.

### Step 1: Find the hex code (Using the Calculator)

Use the following interactive tool to instantly find the code for your required role combination:

* [**OVM Roles Calculator**](https://dazzling-genie-4aaac7.netlify.app/)

1. **Select Roles:** Go to the calculator and click the **Checkboxes** for all the roles you need to grant.
2. **Retrieve Code:** The calculator will automatically calculate and display the final **Total hex code** (e.g., `0x11`) and **Total Decimal Code** (e.g., 17). Use the **Total hex code** in the next stage.

### Step 2: Assign the Roles On-Chain

Roles are assigned using the **`grantRoles`** function on the OVM smart contract.

1. **Go to Etherscan:** Navigate to the Block Explorer page for your deployed OVM smart contract.
2. **Access Write Contract:** Click the **"Contract"** tab, and then the **"Write Contract"** sub-tab.
3. **Connect Wallet:** Click **"Connect to Web3"** and connect the wallet that currently holds **ownership** of the OVM contract.
4. **Execute `grantRoles`:**
   * Find the function **`grantRoles`**.
   * **`user (address)`:** Enter the wallet address you want to grant permissions to (this is the target operator's address).
   * **`roles (uint256)`:** Input the **Decimal Value** (e.g., `17`) or **Hex Value** (e.g., `0x11`) copied from the calculator.
   * Click **"Write"** and approve the transaction.

<figure><img src="https://2241724632-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqEcekJHEGL3v8mnLzK2b%2Fuploads%2Fgit-blob-74b9a53a1517de4f092abc4d366bb86cae58162b%2FAssignOVMRoles1.png?alt=media" alt=""><figcaption></figcaption></figure>

## 3. Review the Roles

1. Assigned roles will show up in the Launchpad to the designated address.

<figure><img src="https://2241724632-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqEcekJHEGL3v8mnLzK2b%2Fuploads%2Fgit-blob-cc42b4ef72d3c51009f572c4d88fb3cea5d6364a%2FAssignOVMRoles2.png?alt=media" alt=""><figcaption></figcaption></figure>

2. Sometimes the Launchpad may take a short time to reflect role updates due to RPC issues.. Try refreshing if this occurs. You can also use Etherscan directly to confirm roles.

<figure><img src="https://2241724632-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqEcekJHEGL3v8mnLzK2b%2Fuploads%2Fgit-blob-66735bc5f471d993d5f8fd786ac01b1c1c4407d7%2FAssignOVMRoles3.png?alt=media" alt=""><figcaption></figcaption></figure>

## 4. Security and Recommendations 🔒

The security of the cluster relies entirely on the assignment and control of these roles. Follow these best practices:

### A. Principle of Least Privilege

* **Avoid `0x3F` (All Roles):** Never grant the full combination code (`0x3F` or 63) to any address that doesn't absolutely require it (like the primary owner/governance multi-sig).
* **Role Separation:** Grant only the specific roles an operator needs for their job. For example:
  * A technical operator managing deposits/withdrawals needs `WITHDRAWAL_ROLE` (1), `CONSOLIDATION_ROLE` (2), and `DEPOSIT_ROLE` (32).
  * A separate, highly-trusted governance multi-sig should hold **high-privilege roles** like `SET_BENEFICIARY_ROLE` (4), `SET_REWARD_ROLE` (16), and `RECOVER_FUNDS_ROLE` (8).

### B. Ownership & Trust

* **Secure the Owner:** The address that can call `grantRoles` and `revokeRoles` is the most powerful. This address **must be a hardware wallet or, ideally, a Gnosis SAFE multi-sig wallet.**
* **Cluster Creation Timing:** It is recommended to **grant final roles before sharing cluster invites** with external invitees. This ensures the security model is locked down before the cluster scales.
* **Renounce Ownership (Conditional):** If the cluster's roles are intended to be fixed forever (e.g., in a fully immutable system), you can **renounce ownership** after setting the final roles. However, if any role needs to be modifiable later (like changing the fee recipient), the owner must retain the ability to execute `grantRoles`.

<figure><img src="https://2241724632-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqEcekJHEGL3v8mnLzK2b%2Fuploads%2Fgit-blob-705d1eba1367f48d473fea051ddb2264ce42835a%2FAssignOVMRoles4.png?alt=media" alt=""><figcaption></figcaption></figure>

## 5. Miscellaneous: How does Bitwise Logic Work?

The final hex code is generated by the **Bitwise OR** operation. Since every role value is a unique power of two, the code for any combination is simply the sum of the desired decimal values.

| Role Combination Requested            | Decimal Addition | Bitwise OR (Binary)                                     | Final hex code |
| ------------------------------------- | ---------------- | ------------------------------------------------------- | -------------- |
| **WITHDRAWAL** and **DEPOSIT**        | 1+32=33          | `000001` \| `100000` = `100001`                         | **`0x21`**     |
| **CONSOLIDATION** and **SET\_REWARD** | 2+16=18          | `000010` \| `010000` = `010010`                         | **`0x12`**     |
| **All 4 Basic Roles**                 | 1+2+4+8=15       | `000001` \| `000010` \| `000100` \| `001000` = `001111` | **`0x0F`**     |