# 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="/files/yON87vaQQDYWmp7uy79G" alt=""><figcaption></figcaption></figure>

## 3. Review the Roles

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

<figure><img src="/files/5AN80kqowfvXWyFcyIQp" 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="/files/K59SMf5usytisl4kfRQP" 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="/files/E7I0n7vfJUk9tSxVM0Fj" 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`**     |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.obol.org/next/advanced-and-troubleshooting/advanced/assign-ovm-roles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.