In Yearn V3, the role manager grants or removes vault permissions; a report keeper uses REPORTING_MANAGER to call process_report. Direct calls to add a strategy, set its maximum debt and request debt updates use separate role bits. Holding vault shares grants an asset claim, while these administrative permissions belong to addresses recorded by the vault.
Start with the allocator contract
This walkthrough covers the allocator VaultV3 API 3.1.1 at commit 89ab996, checked on 28 October 2026. It explains that source snapshot, not the present permissions of a particular deployed vault.
Yearn distinguishes an allocator vault from the strategies into which it deposits. A strategy can be a separate ERC-4626 vault serving several allocators and direct depositors. Optional periphery contracts can manage roles, allocations and fees. These boundaries are explicit in the official V3 overview.
A depositor owns shares in the allocator. The allocator, in turn, can own shares in its strategies. Our ERC-4626 shares versus assets guide explains those units; the lending receipt-token accounting guide separates an accounting claim from liquidity and permission. Neither share ownership nor an ERC-20 allowance automatically populates the vault's administrative role mapping.
The role manager controls the permission assignments
The vault stores one role-manager address and a separate role mask for each account. A mask is an integer whose individual bits represent permissions. The role manager can replace, add or remove those bits for an address.
Being the role manager does not automatically satisfy an operational role check. A role manager with mask zero must first grant itself the required bit before directly adding a strategy or processing a report. That is a sequencing constraint, not a limit on its ability to grant authority.
The reverse distinction matters too. An account holding every defined operational bit still cannot assign roles merely because its mask is large. The pinned authorization tests also check that even the ALL mask does not authorize the role-manager-only name and symbol setters. Review the manager address as well as the masks.
Decode the four roles used by this workflow
The release defines 14 roles. These four govern strategy admission, allocation and reporting. Their decimal values come from the pinned role constants; the external function gates check each separately.
| Role | Decimal bit | Authorized direct action |
|---|---|---|
| ADD_STRATEGY_MANAGER | 1 | Add a strategy with add_strategy |
| REPORTING_MANAGER | 32 | Process its accounting with process_report |
| DEBT_MANAGER | 64 | Request an allocation change with update_debt |
| MAX_DEBT_MANAGER | 128 | Set its ceiling with update_max_debt_for_strategy |
Combining distinct bits uses bitwise OR. An admission committee with the add and ceiling permissions has mask 129: 1 OR 128. A bot with reporting and allocation permissions has mask 96: 32 OR 64. A reporting-only keeper has mask 32.
For one required bit, authorization can be checked as: the account mask AND the required bit must equal the required bit. Thus 32 AND 64 equals zero: reporting permission does not authorize a direct debt update. A contract can hold several roles, but one role does not imply another.
Follow an admission, allocation and report
Consider a hypothetical vault with five distinct addresses. M is its role manager, C an admission committee, A an allocator, K a report keeper and H a share holder. M assigns the following masks. These are teaching assignments, not observed Yearn addresses or recommended governance arrangements.
| Address | Mask | Add | Set ceiling | Allocate | Report |
|---|---|---|---|---|---|
| M, role manager | 0 | No | No | No | No |
| C, committee | 129 | Yes | Yes | No | No |
| A, allocator | 64 | No | No | Yes | No |
| K, keeper | 32 | No | No | No | Yes |
| H, share holder | 0 | No | No | No | No |
The table describes direct calls under the current masks. M can still grant permissions, including to itself. H can use ordinary depositor operations subject to their separate ownership, allowance, liquidity and limit checks.
Use an ordinary underlying token U. Initially the vault holds 1,000 U idle and has no strategy debt. Its minimum idle setting is 100 U; automatic allocation is off. The vault is active and unpaused. Strategy S accepts the same asset and has a nonrestrictive deposit limit. Assume exact transfers and conversions for these selected values, no fees or refunds, and no intervening activity except the specified valuation change.
Yearn's management guide describes the admission sequence: a newly added strategy starts with zero maximum debt, then receives a ceiling, then can receive an allocation.
In the following ledger, the final column always shows idle / recorded debt / maximum debt, all in U.
| Step and caller | Requested action | Result | Idle / debt / max |
|---|---|---|---|
| 1: K | Add S | Reverts: missing bit 1 | 1,000 / 0 / 0 |
| 2: C | Add S | Active; receives no funds | 1,000 / 0 / 0 |
| 3: A | Target debt 600 | Succeeds; allocates zero | 1,000 / 0 / 0 |
| 4: C | Set maximum debt 600 | Ceiling changes only | 1,000 / 0 / 600 |
| 5: K | Target debt 600 | Reverts: missing bit 64 | 1,000 / 0 / 600 |
| 6: A | Target debt 600 | Allocates 600 | 400 / 600 / 600 |
| 7: K | Process report for S | Reads value 660; gain 60 | 400 / 660 / 600 |
| 8: A | Target debt 700 | Returns existing debt 660 | 400 / 660 / 600 |
| 9: M, then K | Remove K's bit 32; K reports | Report reverts | 400 / 660 / 600 |
Authorization does not guarantee an allocation
Step 3 passes the caller check, but the ceiling is still zero. The debt-increase branch reduces the requested target to that ceiling. Under the stated assumptions it completes with zero assets deposited. A successful receipt therefore cannot substitute for checking the returned debt and post-state.
After step 4, step 6 can allocate 600 U. The idle balance becomes 1,000 minus 600, or 400 U, which exceeds the 100 U minimum. Setting the ceiling itself neither transfers those funds nor gives C the allocation permission.
A report can move accounted debt above the ceiling
For step 7, stipulate that S's conversion now values the allocator's strategy shares at 660 U. This is the value of the allocator's position, not S's entire assets. The gain is 660 minus 600, or 60 U.
The reporting implementation reads that position value. K passes only the strategy address; the 660 U comes from S's conversion. With no fees or refunds, recorded strategy debt rises to 660 U and idle stays 400 U. No 60 U cash transfer into the allocator is implied.
The 600 U ceiling restricts new allocations; it does not cap the value recognized by reports. At step 8, the requested increase to 700 is clamped to 600. Because 600 is below existing debt of 660, this increase branch returns the existing debt without transferring assets. It does not automatically withdraw the gain.
Reporting authority also does not select the fee rules. Those depend on the separately configured accountant; accountant fees versus reported profit follows that additional calculation.
A vault report keeper is separate from a strategy keeper
Calling the allocator's process_report does not call the strategy's report function. It reads the strategy-share balance and convertToAssets result. Inspect the strategy's own valuation and maintenance rules before assuming a vault report harvested rewards.
For the separately pinned TokenizedStrategy implementation, report uses onlyKeepers. Its authorization check accepts that strategy's keeper or management address. Allocator bit 32 does not install an address into those strategy-local positions. An arbitrary ERC-4626 strategy can have different maintenance rules again.
Also follow any helper contract between an operator and the vault. The official management guide describes a default setup using a permissionless Keeper. A publicly callable helper can hold the required vault role while its users hold none. The vault checks the helper as its immediate caller. Review both the helper's entry rules and its vault mask before concluding that a wallet lacks an effective route to reporting.
Changing roles does not rebalance assets
At step 9, removing K's reporting bit leaves its mask at zero. The failed report does not unwind the earlier allocation or erase the recognized gain. Permission changes and asset movements need separate records.
Choose the role-editing method deliberately. In the role-management implementation, set_role replaces the complete mask, add_role preserves existing bits and remove_role clears only specified bits. Removing bit 32 from mask 96 leaves 64; replacing 96 with 32 removes allocation authority.
Transferring the role-manager position uses nomination followed by acceptance. Until acceptance, the old manager remains current. The transfer tests verify that intermediate state. Acceptance changes the manager address and clears the nominee field; it does not migrate or clear the operational role masks. Check the old and new managers' masks separately.
Validate the exact call before relying on the role label
Use the same observation block for the relevant reads, then validate in this order:
- Identify the chain, allocator address, implementation and apiVersion. Identify the strategy separately.
- Read role_manager and the immediate caller's roles. For a helper or multisig route, inspect who can make that contract issue the call.
- Match the function to its required bit. Then check the strategy's activation, ceiling, recorded debt, idle reserve and relevant strategy limits.
- Simulate the exact caller, function and arguments. For a debt decrease, also inspect its loss bound. The Yearn maxLoss versus swap slippage guide separately follows a holder's withdrawal and subsequent swap.
- After confirmation, compare events, token movements and post-state with the intended result. Preserve an unchanged debt value when a successful call moved nothing.
For the final hypothetical state, record K's mask as zero, idle as 400 U, debt as 660 U and maximum debt as 600 U. If a receipt or post-state differs, explain that discrepancy before treating the next action as authorized or funded.