Manage Roles and Authorizations for a Multi-Vehicle

This guide helps you interact with an external access control to manage roles & authorize vehicles on a Multi-Vehicle to operate it as an asset-manager.

Steps:

Multi-Vehicle Roles & Purposes

Before granting roles, it’s important to understand the different roles available for managing a Multi-Vehicle:

Authorization Roles

MULTI_VEHICLE_SET_VEHICLE_AUTHORIZATION

• Purpose: Authorize which yield sources (vehicles) are allowed to be used by the Multi-Vehicle
• Use Case: Adding or removing vehicles from the Multi-Vehicle’s authorized list
• Target: MultiVehicle’s Vehicle Manager

Asset Management Roles

Role names are keccak256 of the string, and nothing validates them. Granting a name that no longer exists succeeds — it just guards nothing, and every operation then reverts MissingRole with no visible cause. The authoritative list is src/libs/Roles.sol in hangar.

MULTI_VEHICLE_MOVE

• Purpose: Move assets or shares between sectors or vehicles
• Use Case: Staging assets into a vehicle’s sector, or moving shares out of Allocation
• Target: MultiVehicle’s Sector Accounting Engine
• Note: Replaces the former MULTI_VEHICLE_MOVE_ASSETS and MULTI_VEHICLE_MOVE_SHARES, which were collapsed into one role when moveAssets/moveShares became a single move()

MULTI_VEHICLE_DISPATCH

• Purpose: Dispatch assets from the Multi-Vehicle to sub-vehicles
• Use Case: Sending assets to specific yield sources
• Target: MultiVehicle’s Sector Accounting Engine

MULTI_VEHICLE_DEPOSIT

• Purpose: Perform deposits into the Multi-Vehicle
• Use Case: Depositing base assets, optionally allocating them in the same call
• Target: MultiVehicle’s Sector Accounting Engine

MULTI_VEHICLE_PROGRESS_QUERY

• Purpose: Progress in-flight queries
• Use Case: Advancing an asynchronous sub-vehicle query toward settlement
• Target: MultiVehicle’s Sub Query Engine

Rebalancing Roles

There is no rebalance role, because there is no longer a rebalance() entrypoint. A rebalance is composed from move and dispatch, so it needs MULTI_VEHICLE_MOVE and MULTI_VEHICLE_DISPATCH — see the operate guide.

Queue Management Roles

MULTI_VEHICLE_SET_QUEUES

• Purpose: Configure deposit and withdraw queues for the system
• Use Case: Setting up the order in which vehicles are used for deposits and withdrawals
• Target: MultiVehicle’s Queue Strategy Engine

Query & Steam Roles

VEHICLE_STEAM_DEPOSIT and VEHICLE_STEAM_REDEEM

• Purpose: Allows other contracts or users to interact with the Vehicle or Multi-Vehicle using queries
• Use Case: Gating access to specific users or vehicles, or making it public for restricted access
• Target (scope): the sub-vehicle the query is opened on
• Grant to: the Multi-Vehicle’s SubQueryEngine — it is the contract that calls the sub-vehicle, so it is the address the sub-vehicle checks. Granting these to your own wallet, or scoping them to the Multi-Vehicle, guards nothing and leaves dispatch reverting MissingRole.
• Note: Formerly one VEHICLE_STEAM role, now split by direction so deposit and redeem access can be granted independently

Without this pair, everything up to and including move succeeds and only dispatch fails — the accounting is internal to the Multi-Vehicle, and the sub-vehicle’s own access control is the first thing outside it that a dispatch touches. Grant the deposit side to allocate and the redeem side to pull capital back out:

eac.grantScopedRole(VEHICLE_STEAM_DEPOSIT, subVehicle, subQueryEngine);
eac.grantScopedRole(VEHICLE_STEAM_REDEEM, subVehicle, subQueryEngine);

Factory Roles

FACTORY_SPAWN

• Purpose: Grant deployment rights on the Multi-Vehicle factory
• Use Case: Allowing addresses to deploy new Multi-Vehicles
• Target: Railnet’s Factory

1. Set a role on your external access control

As described in the deploy guide, the external access control is the central place to manage roles on railnet. In this section, we present how to assign a specific role related to managing a multi-vehicle to another wallet address than the default admin one.

For this section we assume that you know the external access control address that you deployed for your organization.

Required roles for this guide:

• MULTI_VEHICLE_SET_VEHICLE_AUTHORIZATION — needed for Step 2 (Authorize Vehicle), scoped to the Vehicle Manager
• MULTI_VEHICLE_SET_QUEUES — needed for Step 3 (Configure Queues), scoped to the Queue Strategy Engine

Also needed for the Operate Multi-Vehicle guide:

• MULTI_VEHICLE_MOVE — needed to move assets or shares between sectors and vehicles
• MULTI_VEHICLE_DISPATCH — needed to dispatch assets to a vehicle

Rebalancing needs no role of its own: it is move + dispatch, so those two cover it.

2. Authorize a new vehicle on your Multi-Vehicle

Requirements: Connected wallet need to have the role MULTI_VEHICLE_SET_VEHICLE_AUTHORIZATION.

To authorize a vehicle on a multi-vehicle you need to interact with the Vehicle Manager.

Get your multi-vehicle Vehicle Manager

We will use the indexing service to get the address of the Vehicle Manager of the multi-vehicle of your choice.

Get available vehicles on railnet

Below find how you can search for all vehicles on railnet that are not multi-vehicles.

Authorize a vehicle

Vehicle authorizations are performed on the Vehicle Manager of the MultiVehicle.

3. Configure Strategy Queues

After authorizing vehicles, you can define your allocation strategy using deposit and redeem queues. These queues determine the priority and allocation caps for how assets are distributed across your authorized vehicles.

Requirements:

• Connected wallet must have the MULTI_VEHICLE_SET_QUEUES role
• All vehicles in queues must be authorized
• Target: Queue Strategy Engine (not Accounting Engine)

Get your Multi-Vehicle Queue Strategy Engine

First, retrieve the Queue Strategy Engine address for your Multi-Vehicle:

Set Queues

Configure your deposit and redeem queues to define your allocation strategy:

Target Semantics

Understanding how target values work is crucial for configuring your queues correctly:

Deposit Queue

• Purpose: target = ceiling (max shares to allocate to this vehicle before moving to next queue entry)
• Processing: Queue processes in order - first entry allocated first, up to its target, then second entry, etc.
• Behavior: Does NOT enforce ongoing ratios - if yields diverge, allocations drift
• Special Value: type(uint256).max = no limit (allocate all available)

Example: With deposit queue [{vehicle: A, target: 80000e18}, {vehicle: B, target: 20000e18}]:

1. First 80,000 shares go to vehicle A
2. Next 20,000 shares go to vehicle B
3. Any additional shares beyond 100,000 total would overflow to subsequent entries (if any)

Redeem Queue

• Purpose: target = floor (min shares to maintain in this vehicle)
• Processing: Queue processes in order - first entry redeemed from first, down to its target, then second entry, etc.
• Behavior: Withdrawals prioritize earlier entries while respecting minimum thresholds
• Special Value: 0 = no minimum (can withdraw all from this vehicle)

Example: With redeem queue [{vehicle: B, target: 0}, {vehicle: A, target: 0}]:

1. Withdrawals come from vehicle B first, down to 0 shares
2. Then withdrawals come from vehicle A if needed