Access control and roles

This page covers the smart contract implementation details. See Glossary.

External Access Control (EAC) is Railnet’s central permission system. Based on OpenZeppelin’s AccessControlDefaultAdminRules, it manages permissions across all vehicles and protocol components with granular, auditable control.

Role types

EAC supports three distinct types of roles to provide flexible permission management.

Global roles

Global roles are standard bytes32 identifiers that apply across the entire protocol. When you grant an account a global role, it holds that permission for all protocol components that check for it.

// Grant a global role
eac.grantRole(VEHICLE_STEAM_DEPOSIT, aliceAddress);

// Check a global role
bool hasAccess = eac.hasRole(VEHICLE_STEAM_DEPOSIT, aliceAddress); // true for all vehicles

// VEHICLE_STEAM_REDEEM works identically for redeem operations
eac.grantRole(VEHICLE_STEAM_REDEEM, aliceAddress);

// Coming soon

Scoped roles

Scoped roles are restricted to a specific contract address (the scope). This allows fine-grained permissions, such as granting an account the ability to manage a specific vehicle without giving it permissions over all vehicles. Internally, a scoped role is represented as keccak256(abi.encodePacked(role, scope)).

// Grant VEHICLE_STEAM_DEPOSIT to Alice for a specific vehicle only
eac.grantScopedRole(VEHICLE_STEAM_DEPOSIT, vehicleAddress, aliceAddress);

// Alice has deposit access to this specific vehicle
bool hasAccess = eac.hasScopedRole(VEHICLE_STEAM_DEPOSIT, vehicleAddress, aliceAddress); // true

// But NOT to other vehicles
bool hasGlobal = eac.hasRole(VEHICLE_STEAM_DEPOSIT, aliceAddress); // false

// VEHICLE_STEAM_REDEEM works the same way for redeem operations
eac.grantScopedRole(VEHICLE_STEAM_REDEEM, vehicleAddress, aliceAddress);

// Coming soon

Public roles

Public roles are effectively granted to everyone. When you make a role public, hasRole and hasScopedRole checks for that role return true for any account.

// Make VEHICLE_STEAM_DEPOSIT public for a specific vehicle
eac.setScopedRolePublic(VEHICLE_STEAM_DEPOSIT, vehicleAddress, true);

// Now anyone can deposit on that vehicle
bool anyoneHasAccess = eac.hasScopedRole(VEHICLE_STEAM_DEPOSIT, vehicleAddress, bob); // true

// VEHICLE_STEAM_REDEEM can be made public separately for redeem operations
eac.setScopedRolePublic(VEHICLE_STEAM_REDEEM, vehicleAddress, true);

// Coming soon

The DEFAULT_ADMIN_ROLE cannot be made public. While a role is public, grantRole, revokeRole, renounceRole, grantScopedRole, revokeScopedRole, and renounceScopedRole all revert with PublicRoleAuthDenied for it — make it private again before managing individual holders.

Checking permissions

EAC provides three methods for checking access:

Method	Checks	Use when
`hasRole(role, account)`	Global role only (or public)	You need protocol-wide access
`hasScopedRole(role, scope, account)`	Scoped role only (or public for scope)	You need access to a specific contract
`hasRoleOrScopedRole(role, scope, account)`	Either global OR scoped	Most common — allows both patterns

Contracts do not call these views directly. They route through AccessControlLib, which wraps hasRoleOrScopedRole in two flavours:

gatedCheckRole(role, scope, account) is fail-closed: it reverts ZeroAddress when the contract has no access control set, then reverts MissingRole unless the account holds the role globally or scoped. Every operator-facing function uses this variant.
ungatedCheckRole(role, account) is fail-open: an unset access control means access control is disabled and the call passes. Vehicles reach it through _onlyRoleWhenEnabled, which additionally skips the check entirely until the Vehicle is enabled, so the factory can seed the initial deposit before roles exist.

Admin management

EAC implements a secure, time-delayed mechanism for transferring the default admin role:

Initiate transfer

The current admin calls beginDefaultAdminTransfer(newAdmin) to start the transfer process.

Wait for delay

A configurable time delay must pass before the transfer can complete.

Accept transfer

The pending admin calls acceptDefaultAdminTransfer() to complete the transfer.

The delay is the initialDelay (in seconds) passed to the constructor, and is changed later with changeDefaultAdminDelay(uint48 newDelay) — which is itself scheduled rather than immediate.

The default admin role can never be dropped: beginDefaultAdminTransfer(address(0)) and renounceRole(DEFAULT_ADMIN_ROLE, ...) both revert with DefaultAdminCannotBeRenounced.

Role reference

Factory roles

Role	Description
`FACTORY_SPAWN`	Spawn vehicles and ecosystem contracts (FeeManager, ModulesManager, AccountList, OwnerRegistry) via their factories
`CONDUIT_SPAWN`	Spawn Conduits via the `ConduitFactory`
`FACTORY_DEPRECATE`	Deprecate a factory to prevent future deployments
`ASSET_REGISTRY_SET_ASSET`	Authorize, deauthorize, or reconfigure assets in the AssetRegistry

Beacon and proxy roles

Role	Description
`BEACON_UPGRADE`	Upgrade the implementation address of a beacon
`BEACON_FREEZE`	Permanently freeze a beacon (irreversible)
`BEACON_PAUSE`	Pause beacon operations
`BEACON_UNPAUSE`	Resume paused beacon operations

Vehicle roles

Role	Description
`VEHICLE_STEAM_DEPOSIT`	Interact with STEAM functions (`create`, `resume`, `unlock`, `recover`) on deposit queries
`VEHICLE_STEAM_REDEEM`	Interact with STEAM functions (`create`, `resume`, `unlock`, `recover`) on redeem queries
`VEHICLE_SET_INTERCEPTIONS`	Configure reward interception rules
`VEHICLE_ALLOW`	Manage the allowlist of modules in the vehicle’s ModulesManager
`VEHICLE_EXEC`	Execute an allowed module on the vehicle
`VEHICLE_PROCESS_QUEUE`	Submit a size-bounded request from an async vehicle’s deposit or redeem queue (the unbounded `processRequest()` stays permissionless)

STEAM authorization is split across deposit and redeem so operators can gate each direction independently — for example, keeping deposits open while pausing redemptions during a strategy wind-down, or restricting deposits to KYC’d addresses while exits remain public.

Conduit roles

Role	Description
`CONDUIT_SET_INTERCEPTIONS`	Configure the Conduit’s reward interception rules
`CONDUIT_SET_TRANSFER_ENABLED`	Flip the Conduit’s one-way `transferEnabled` latch via `enableTransfers()`
`CONDUIT_FORCE_REDEEM`	Force-redeem (eject) blocked or sanctioned Conduit holders
`CONDUIT_PROCESS`	Process Conduit queries on behalf of any owner (keepers)
`ACCOUNT_LIST_MANAGER`	Manage AccountList membership, mode, and sanctions configuration

FeeManager roles

Role	Description
`FEE_MANAGER_SET_FEES`	Update fee percentages
`FEE_MANAGER_SET_FEE_RECIPIENTS`	Update fee recipient addresses
`FEE_MANAGER_DISPATCH_ERC20`	Distribute collected fees

Multi-Vehicle roles

Role	Description
`MULTI_VEHICLE_DEPOSIT`	Deposit assets into the accounting engine
`MULTI_VEHICLE_MOVE`	Move assets or shares between sectors
`MULTI_VEHICLE_DISPATCH`	Dispatch a deposit or redeem to a sub-vehicle
`MULTI_VEHICLE_SET_QUEUES`	Configure the deposit and redeem queues
`MULTI_VEHICLE_PROGRESS_QUERY`	Advance sub-query states in the SubQueryEngine
`MULTI_VEHICLE_SET_VEHICLE_AUTHORIZATION`	Authorize, configure, or unauthorize sub-vehicles on the VehicleManager
`MULTI_VEHICLE_SET_THRESHOLDS`	Set operational thresholds and the maximum total assets
`MULTI_VEHICLE_FEED_QUERY_REDEEM_QUEUE`	Feed assets to the query redeem queue
`MULTI_VEHICLE_RETRIEVE_QUERY_REDEEM_QUEUE_ASSETS`	Retrieve assets from the query redeem queue

ModulesManager roles

Role	Description
`MODULE_MANAGER`	Add or remove modules in the ModulesManager registry

Module registration and removal take effect immediately; there is no module timelock and no cancellation role. Authorizing a registered module on a specific target is a separate step gated by that target’s VEHICLE_ALLOW, and executing it is gated by VEHICLE_EXEC.

Keeper roles

Role	Description
`JOB_LISTING_REGISTER`	Register new keeper jobs
`JOB_LISTING_UNREGISTER`	Remove registered keeper jobs
`JOB_LISTING_EXECUTE`	Execute registered jobs
`KEEPER_ON_REPORT`	Forward job reports to the Keeper contract

FreezablePausableBeacon

Vehicle and Conduit proxies read their implementation address from a FreezablePausableBeacon. The beacon holds the implementation; the EAC gates who may upgrade, freeze, pause, or unpause it. The beacon has two protective states:

Freeze
Pause

A permanent and irreversible state. Once frozen, the implementation address can never be upgraded again. This provides a “trustless” guarantee that the contract logic is immutable.

// Permanently freeze the beacon (irreversible)
// Requires BEACON_FREEZE, and the beacon must not be paused
beacon.freeze();

// Coming soon

A temporary and reversible state. While paused, implementation() reverts with EnforcedPause, effectively disabling all proxies that rely on this beacon. pauseFor can only extend an active pause — shortening it reverts CannotShortenPause.

// Pause indefinitely (BEACON_PAUSE)
beacon.pause();

// Or pause for a specific duration (BEACON_PAUSE)
beacon.pauseFor(7 days);

// Resume operations (BEACON_UNPAUSE)
beacon.unpause();

// Coming soon

Common permission patterns

Grant an operator access to a specific Multi-Vehicle

Use scoped roles to restrict the operator to a single Multi-Vehicle. Scope each role to the contract that carries the gated function, not to the Multi-Vehicle itself: MULTI_VEHICLE_DISPATCH is gated on the Sector Accounting Engine, while MULTI_VEHICLE_SET_QUEUES is gated on the Queue Strategy Engine.

IVehicleManager manager = MultiVehicle(multiVehicleAddress).manager();
address accounting = address(manager.accountingEngine());
address strategy = address(manager.queueStrategyEngine());

eac.grantScopedRole(MULTI_VEHICLE_DISPATCH, accounting, operatorAddress);
eac.grantScopedRole(MULTI_VEHICLE_MOVE, accounting, operatorAddress);
eac.grantScopedRole(MULTI_VEHICLE_SET_QUEUES, strategy, operatorAddress);

// Coming soon

Open a vehicle to public STEAM queries

Make the STEAM roles public for a specific vehicle so any user can interact. Deposits and redeems can be opened independently:

eac.setScopedRolePublic(VEHICLE_STEAM_DEPOSIT, vehicleAddress, true);
eac.setScopedRolePublic(VEHICLE_STEAM_REDEEM, vehicleAddress, true);

// Coming soon

Set up a fee manager operator

Grant the roles needed to manage and distribute fees:

eac.grantScopedRole(FEE_MANAGER_SET_FEES, feeManagerAddress, operatorAddress);
eac.grantScopedRole(FEE_MANAGER_SET_FEE_RECIPIENTS, feeManagerAddress, operatorAddress);
eac.grantScopedRole(FEE_MANAGER_DISPATCH_ERC20, feeManagerAddress, operatorAddress);

// Coming soon

Getting started

How-to guides

Reference

Access control and roles

Role types

Global roles

Scoped roles

Public roles

Checking permissions

Admin management

Role reference

Factory roles

Beacon and proxy roles

Vehicle roles

Conduit roles

FeeManager roles

Multi-Vehicle roles

ModulesManager roles

Keeper roles

FreezablePausableBeacon

Common permission patterns

​Role types

​Global roles

​Scoped roles

​Public roles

​Checking permissions

​Admin management

​Role reference

​Factory roles

​Beacon and proxy roles

​Vehicle roles

​Conduit roles

​FeeManager roles

​Multi-Vehicle roles

​ModulesManager roles

​Keeper roles

​FreezablePausableBeacon

​Common permission patterns

Role types

Global roles

Scoped roles

Public roles

Checking permissions

Admin management

Role reference

Factory roles

Beacon and proxy roles

Vehicle roles

Conduit roles

FeeManager roles

Multi-Vehicle roles

ModulesManager roles

Keeper roles

FreezablePausableBeacon

Common permission patterns