Operate an Allocation Strategy

In Railnet smart contracts, an Allocation Strategy is implemented as a MultiVehicle. See Glossary for all terminology.

This guide covers how to authorize yield sources, configure allocation queues, and run day-to-day operations for your Allocation Strategy — moving assets between sectors, dispatching to yield sources, rebalancing allocations, handling redemptions, and integrating with keepers for automation.

The MultiVehicle exposes only its manager. Reach every engine through it:

Solidity

IVehicleManager manager = MultiVehicle(multiVehicle).manager();

ISectorAccountingEngine accounting = manager.accountingEngine();
IQueueStrategyEngine strategy = manager.queueStrategyEngine();
ISubQueryEngine subQueryEngine = manager.subQueryEngine();
IQueryRedeemQueue redeemQueue = manager.redeemQueue();

Prerequisites

A deployed Allocation Strategy ecosystem (see Create an Allocation Strategy)
Your External Access Control (EAC) contract address
At least one authorized yield source
The following roles on your EAC:
- MULTI_VEHICLE_MOVE and MULTI_VEHICLE_DISPATCH, scoped to the Sector Accounting Engine
- MULTI_VEHICLE_SET_QUEUES, scoped to the Queue Strategy Engine

Operating a platform-owned Allocation Strategy

If a Conduit owner deployed the Allocation Strategy and invited you to manage it, be aware of the guardrails:

Yield source authorization is controlled by the owner. You manage allocations within the set of sources they have authorized.
Fee structure is set by the owner. You earn through the configured performance fee share.
Admin access remains with the owner. You cannot grant roles to others or change the access control configuration.

Your operational roles are scoped to specific contracts — you can move capital, dispatch, and manage queues, but cannot change the strategic boundaries. See Guardrails for details.

Authorize yield sources

Before your Allocation Strategy can allocate assets to a yield source, the source must be authorized on the Vehicle Manager.

The Vehicle Manager validates that a yield source uses the same base asset as the Allocation Strategy, is a contract, and reports ready().

Requires: MULTI_VEHICLE_SET_VEHICLE_AUTHORIZATION role scoped to the Vehicle Manager.

Find your Vehicle Manager address

Authorization is performed on the Vehicle Manager. Read it from the MultiVehicle, or look it up via the Railnet API.

IVehicleManager manager = MultiVehicle(multiVehicle).manager();

// Coming soon

Authorize a yield source

Call authorize for the default configuration, or authorizeAndConfigure to set the vehicle’s mode and cap in the same transaction.

// Authorize an Aave V3 vehicle with the default config
address aaveVehicle = 0x...; // The sub-vehicle address
manager.authorize(IVehicle(aaveVehicle));

// Authorize a Morpho Blue vehicle with an explicit cap
address morphoVehicle = 0x...;
manager.authorizeAndConfigure(
    IVehicle(morphoVehicle),
    VehicleManagerStore.VehicleConfig({
        mode: VehicleMode.Automatic,
        cap: Target({value: 250_000e6, threshold: 0})
    })
);

// Coming soon

Change a cap or mode later with manager.configure(vehicle, config).

Unauthorize a yield source

To remove a yield source, first redeem all assets out of it, then unauthorize it.

// Unauthorize a vehicle (ensure no funds remain allocated)
manager.unauthorize(IVehicle(vehicleToRemove));

// Coming soon

Unauthorizing a yield source does not automatically redeem existing positions. Withdraw all funds from the source before removing it.

syncVehicleActivationStatus is not an authorization call. It takes a single vehicle argument, is callable only by the SubQueryEngine, and keeps the accounting engine’s internal active vehicles list in sync as positions and in-flight queries appear or clear.

Configure allocation queues

The Queue Strategy Engine determines how assets are distributed across authorized yield sources using deposit and redeem queues.

Target semantics

Deposit queue
Redeem queue

In the deposit queue, target.value acts as a ceiling — the share holdings a yield source is filled up to before the queue moves to the next entry.

The queue processes in order: the first entry is filled first, up to its target, then the second entry, and so on.
type(uint256).max means no limit (allocate all available to this source).
target.threshold is a tolerance band: the entry is skipped when holdings are already within threshold of the target, so tiny top-ups don’t churn gas.
The queue does not enforce ongoing ratios. If yields diverge across sources, allocations will drift.

Example: With deposit queue [{Aave, target: 80000e18}, {Morpho, target: 20000e18}]:

First 80,000 shares go to Aave
Next 20,000 shares go to Morpho
Any additional shares overflow to subsequent entries

In the redeem queue, target.value acts as a floor — the share holdings a yield source is drained down to before the queue moves on.

The queue processes in order: the first entry is drained first, down to its target, then the second entry.
0 means no minimum (the source can be fully drained).
target.threshold widens the floor: the entry is skipped when holdings are already within threshold above the target.

Example: With redeem queue [{Morpho, target: 0}, {Aave, target: 0}]:

Withdrawals come from Morpho first, down to 0 shares
Then Aave is drained if more is needed

Set queues

Requires: MULTI_VEHICLE_SET_QUEUES role scoped to the Queue Strategy Engine.

IQueueStrategyEngine strategy = MultiVehicle(multiVehicle).manager().queueStrategyEngine();

// Define deposit queue: Aave first (up to 80,000 shares), then Morpho (unlimited)
IQueueStrategyEngine.QueueEntry[] memory depositQueue = new IQueueStrategyEngine.QueueEntry[](2);
depositQueue[0] = IQueueStrategyEngine.QueueEntry({
    vehicle: IVehicle(aaveVehicle),
    target: Target({value: 80_000e18, threshold: 0})
});
depositQueue[1] = IQueueStrategyEngine.QueueEntry({
    vehicle: IVehicle(morphoVehicle),
    target: Target({value: type(uint256).max, threshold: 0})  // unlimited
});

// Define redeem queue: Morpho first, then Aave
IQueueStrategyEngine.QueueEntry[] memory redeemQueue = new IQueueStrategyEngine.QueueEntry[](2);
redeemQueue[0] = IQueueStrategyEngine.QueueEntry({
    vehicle: IVehicle(morphoVehicle),
    target: Target({value: 0, threshold: 0})
});
redeemQueue[1] = IQueueStrategyEngine.QueueEntry({
    vehicle: IVehicle(aaveVehicle),
    target: Target({value: 0, threshold: 0})
});

// Both queues are replaced atomically
strategy.setQueues(depositQueue, redeemQueue);

// Coming soon

A common pattern is to set the redeem queue in reverse order of the deposit queue. This ensures that the last yield source to receive deposits is the first to be drained during redemptions.

How asset flow works

The Sector Accounting Engine tracks every asset and share in a sector, a bytes32 identifier. Five are fixed, plus one staging sector per authorized yield source:

Sector	Holds	Counted in
`ENTRY`	virtual source for assets entering the system	neither (untracked)
`AVAILABLE`	idle base-asset liquidity	`totalAssets()` and `withdrawable()`
`RESERVED`	base assets you have explicitly parked aside	`totalAssets()` only
`SectorLib.toSector(vehicle)`	assets or shares staged for one yield source	`totalAssets()`
`ALLOCATION`	vehicle shares from settled deposits	`totalAssets()`
`EXIT`	virtual sink for assets leaving the system	neither (untracked)

RESERVED exists so you can hold liquidity back: it counts toward NAV but neither auto-fulfill nor the Queue Strategy Engine can consume it. Getting liquidity in or out of RESERVED always takes an explicit move. The typical operator workflow is: move assets from AVAILABLE into a vehicle’s sector, then dispatch to execute the deposit into the yield source.

View holdings and allocations

Before operating, check the current state of your Allocation Strategy’s sectors and allocations.

ISectorAccountingEngine accounting = MultiVehicle(multiVehicle).manager().accountingEngine();

// Total assets across all sectors and sub-vehicles
uint256 totalAssets = accounting.totalAssets();

// Idle base-asset liquidity (the AVAILABLE sector; RESERVED is excluded)
uint256 withdrawable = accounting.withdrawable();

// One sector's balance for one token
uint256 idleUsdc = accounting.getSectorBalance(SectorLib.AVAILABLE, IERC20(usdc));
uint256 stagedUsdc = accounting.getSectorBalance(SectorLib.toSector(IVehicle(aaveVehicle)), IERC20(usdc));

// Full holdings breakdown for one yield source
(
    uint256 sharesAfterUnlocks,         // settled shares in ALLOCATION
    uint256 sharesBeforeCreates,        // shares staged for new redeem queries
    uint256 expectedSharesAfterUnlocks, // ephemeral shares from in-flight deposits
    uint256 expectedAssetsAfterUnlocks, // projected assets once in-flight redeems unlock
    uint256 assetsBeforeCreates         // assets staged for new deposit queries
) = accounting.vehicleHoldings(IVehicle(aaveVehicle));

// Headroom before the vehicle's cap or its own limits bind
uint256 depositable = accounting.maxDepositable(IVehicle(aaveVehicle));
uint256 redeemable = accounting.maxRedeemable(IVehicle(aaveVehicle));

// Coming soon

You can also query the Railnet API:

GraphQL

query SectorBalances($address: String!) {
  SectorBalance(
    where: {
      sector: {
        accountingEngine: {
          multiVehicle: { vehicle: { address: { _ilike: $address } } }
        }
      }
    }
  ) {
    asset
    value
    sector {
      name
      sectorId
    }
  }
}

Move assets to a yield source

Use move to shift the base asset from AVAILABLE into a yield source’s sector. This stages the assets for dispatch. Requires: MULTI_VEHICLE_MOVE role scoped to the Sector Accounting Engine.

Moving assets does not deposit them into the yield source yet. You must call dispatch afterward to execute the deposit.

ISectorAccountingEngine accounting = MultiVehicle(multiVehicle).manager().accountingEngine();

// Move 10,000 USDC from idle liquidity into the vehicle's staging sector
accounting.move(
    ISectorAccountingEngine.MoveParams({
        from: SectorLib.AVAILABLE,
        to: SectorLib.toSector(IVehicle(targetVehicle)),
        asset: usdc,
        amount: 10_000e6,               // USDC has 6 decimals
        operationId: keccak256("top-up-aave-2026-08")
    })
);

// Coming soon

Set amount to type(uint256).max to move the entire sector balance. operationId is a free-form tag echoed into the emitted event — reuse one value across the steps of a multi-step operation so dashboards and indexers can group them.

Dispatch assets to a yield source

After staging assets in a yield source’s sector, call dispatch to create the deposit query on that source. This executes the actual deposit. Requires: MULTI_VEHICLE_DISPATCH role scoped to the Sector Accounting Engine.

ISectorAccountingEngine accounting = MultiVehicle(multiVehicle).manager().accountingEngine();

(Query memory query, State dispatchState) = accounting.dispatch(
    ISectorAccountingEngine.DispatchParams({
        vehicle: IVehicle(targetVehicle),
        mode: Mode.DEPOSIT,
        amount: 10_000e6,
        settledDestination: SectorLib.ALLOCATION,   // shares land here on success
        rejectedDestination: SectorLib.AVAILABLE,   // assets return here on failure
        minOutput: 9_950e18,                        // slippage floor; 0 accepts any output
        data: "",
        operationId: keccak256("top-up-aave-2026-08")
    })
);

// Coming soon

dispatchState is the state the sub-query reached in this call — SETTLED for a sync source, PROCESSING for an async one.

amount: type(uint256).max dispatches the whole sector balance and auto-limits to the vehicle’s cap instead of reverting, but it requires minOutput: 0. A slippage bound may only bind to an explicit amount, never to the execution-time sector balance.

You can batch move and dispatch operations: stage assets into several yield source sectors first, then dispatch to each source in sequence.

Rebalance between yield sources

There is no single rebalance call. You compose one from the same primitives, reusing one operationId so the steps read as a single logical operation off-chain:

Redeem from the source

Dispatch a REDEEM for the source vehicle’s shares, sending the proceeds to AVAILABLE.

Solidity

bytes32 opId = keccak256("rebalance-aave-to-morpho");

(, State redeemState) = accounting.dispatch(
    ISectorAccountingEngine.DispatchParams({
        vehicle: IVehicle(sourceVehicle),
        mode: Mode.REDEEM,
        amount: 5_000e18,                        // shares to redeem
        settledDestination: SectorLib.AVAILABLE,
        rejectedDestination: SectorLib.ALLOCATION,
        minOutput: 4_950e6,                      // minimum base assets back
        data: "",
        operationId: opId
    })
);

Stage the proceeds for the destination

Once the redeem settles, move the freed assets into the destination vehicle’s sector.

Solidity

accounting.move(
    ISectorAccountingEngine.MoveParams({
        from: SectorLib.AVAILABLE,
        to: SectorLib.toSector(IVehicle(targetVehicle)),
        asset: usdc,
        amount: type(uint256).max,               // everything that arrived
        operationId: opId
    })
);

Dispatch into the destination

Solidity

accounting.dispatch(
    ISectorAccountingEngine.DispatchParams({
        vehicle: IVehicle(targetVehicle),
        mode: Mode.DEPOSIT,
        amount: type(uint256).max,
        settledDestination: SectorLib.ALLOCATION,
        rejectedDestination: SectorLib.AVAILABLE,
        minOutput: 0,                            // required with the max sentinel
        data: "",
        operationId: opId
    })
);

If the source’s redemption is asynchronous, step 1 returns PROCESSING and the assets are not in AVAILABLE yet. Wait for the sub-query to settle before running steps 2 and 3 — check vehicleHoldings or the indexed query state.

Handle user deposits

When users deposit into the Allocation Strategy, assets flow through the STEAM lifecycle. With allocation queues configured, deposits are automatically distributed to yield sources based on the deposit queue priority.

// User creates a deposit query
Query memory query = Query({
    owner: depositor,
    receiver: depositor,
    input: Asset({ asset: address(usdc), value: 500e6 }),
    // `output.value` is a minimum (slippage floor); 0 disables the floor
    output: Asset({ asset: address(multiVehicle), value: 0 }),
    mode: Mode.DEPOSIT,
    salt: keccak256("deposit-001"),
    data: ""
});

// STEAM lifecycle: create → unlock
multiVehicle.create(query);
multiVehicle.unlock(query);

// Coming soon

Handle redemptions

Redemptions follow the STEAM lifecycle. The Queue Strategy Engine processes redeems according to the redeem queue priority.

// User creates a redeem query
Query memory query = Query({
    owner: depositor,
    receiver: depositor,
    input: Asset({ asset: address(multiVehicle), value: 1_000e18 }),
    // `output.value` is a minimum (slippage floor); 0 disables the floor
    output: Asset({ asset: address(usdc), value: 0 }),
    mode: Mode.REDEEM,
    salt: keccak256("redeem-001"),
    data: ""
});

multiVehicle.create(query);

// For async redemptions, the query progresses through the redeem queue
// Once assets are available:
multiVehicle.unlock(query);

// Coming soon

Keeper integration

Keepers are off-chain bots that automate routine operations. As an operator, understanding keeper integration helps you decide what to automate vs manage manually.

What keepers automate

Operation	Description
Redemption queue feeding	Provides liquidity to the redemption queue when there is pending demand
Asset retrieval	Retrieves settled assets from the redemption queue back to accounting
Fee share redemption	Progresses redemption queries for fee shares
Sub-query progression	Advances async sub-queries (e.g. Ethena withdrawals)

What remains manual

Operation	Why
Capital allocation (`move`)	Requires strategic judgment
Dispatching to yield sources	Depends on allocation strategy
Rebalancing	Market-driven decision
Queue configuration changes	Strategic decision

Check keeper status

If your Allocation Strategy is registered with the keeper system, verify automation is running:

GraphQL

query KeeperJobs($address: String!) {
  Job(where: { execTarget: { _ilike: $address } }) {
    id
    status
    execTarget
    event {
      tx {
        hash
        block { timestamp }
      }
    }
  }
}

status is STARTED, DONE, or CANCELLED. There is no last-execution timestamp field — read it from event.tx.block.timestamp. If keepers are not processing redemptions, you can handle them manually (see Troubleshooting below).

Update queue priorities

You can change the allocation strategy at any time by updating the deposit and redeem queues.

IQueueStrategyEngine strategy = MultiVehicle(multiVehicle).manager().queueStrategyEngine();

Target memory unlimited = Target({value: type(uint256).max, threshold: 0});
Target memory drainFully = Target({value: 0, threshold: 0});

// New deposit queue: prioritize Morpho, then Aave
IQueueStrategyEngine.QueueEntry[] memory newDepositQueue = new IQueueStrategyEngine.QueueEntry[](2);
newDepositQueue[0] = IQueueStrategyEngine.QueueEntry({vehicle: IVehicle(morphoVehicle), target: unlimited});
newDepositQueue[1] = IQueueStrategyEngine.QueueEntry({vehicle: IVehicle(aaveVehicle), target: unlimited});

// New redeem queue: drain Aave first, then Morpho
IQueueStrategyEngine.QueueEntry[] memory newRedeemQueue = new IQueueStrategyEngine.QueueEntry[](2);
newRedeemQueue[0] = IQueueStrategyEngine.QueueEntry({vehicle: IVehicle(aaveVehicle), target: drainFully});
newRedeemQueue[1] = IQueueStrategyEngine.QueueEntry({vehicle: IVehicle(morphoVehicle), target: drainFully});

// Replaces both queues; every vehicle must still be authorized and ready
strategy.setQueues(newDepositQueue, newRedeemQueue);

// Coming soon

Troubleshooting

Stuck redemptions

If redemptions are not progressing (e.g. due to keeper failure or insufficient liquidity):1. Feed the redeem queue — if withdrawable assets are available. Requires MULTI_VEHICLE_FEED_QUERY_REDEEM_QUEUE scoped to the Vehicle Manager:

Solidity

IVehicleManager manager = MultiVehicle(multiVehicle).manager();
manager.feedQueryRedeemQueue();

2. Progress stuck sub-queries — if a sub-query is stuck in a non-terminal state. Requires MULTI_VEHICLE_PROGRESS_QUERY scoped to the SubQueryEngine:

Solidity

ISubQueryEngine subQueryEngine = manager.subQueryEngine();
subQueryEngine.progressQuery(subQuery, query);

3. Dispatch staged assets — if assets sit in a yield source’s sector with no active query:

Solidity

accounting.dispatch(
    ISectorAccountingEngine.DispatchParams({
        vehicle: IVehicle(targetVehicle),
        mode: Mode.DEPOSIT,
        amount: type(uint256).max,
        settledDestination: SectorLib.ALLOCATION,
        rejectedDestination: SectorLib.AVAILABLE,
        minOutput: 0,
        data: "",
        operationId: bytes32(0)
    })
);

Stuck deposits

If a deposit query is stuck in PROCESSING state, the yield source may require manual progression (common with async protocols like Ethena):

Solidity

ISubQueryEngine subQueryEngine = MultiVehicle(multiVehicle).manager().subQueryEngine();
subQueryEngine.progressQuery(subQuery, query);

Check the yield source’s STEAM state to understand what transition is needed.

Failed dispatches

If dispatch reverts, common causes include:

No staged assets — check the yield source’s sector has a non-zero balance with getSectorBalance
Source not authorized — verify the yield source is still authorized: manager.isAuthorized(vehicle)
Missing role — confirm you hold MULTI_VEHICLE_DISPATCH scoped to the Sector Accounting Engine
Slippage bound — minOutput must be 0 when amount is type(uint256).max
Cap reached — maxDepositable(vehicle) returns 0 when the vehicle is at its configured cap or paused
Source rejection — the yield source’s create may be reverting (check the underlying protocol’s status)

Allocation queue not behaving as expected

Remember that queues use ceiling (deposit) and floor (redeem) semantics:

Deposit queue targets are maximums, not ratios — allocations will drift with yield
If all yield sources have reached their ceiling, new deposits stay idle in AVAILABLE
Redeem queue targets are minimums — a source won’t be drained below its target

Update queue targets as your strategy evolves. See Configure allocation queues.

Next steps

Risk management

Evaluate yield sources, manage concentration risk, and handle emergencies.

Configure fees

Set up performance, management, and transactional fee structures.

Getting started

Allocation Strategies

Advanced Strategies

Reference

Operate an Allocation Strategy

Prerequisites

Operating a platform-owned Allocation Strategy

Authorize yield sources

Configure allocation queues

Target semantics

Set queues

How asset flow works

View holdings and allocations

Move assets to a yield source

Dispatch assets to a yield source

Rebalance between yield sources

Handle user deposits

Handle redemptions

Keeper integration

What keepers automate

What remains manual

Check keeper status

Update queue priorities

Troubleshooting

Next steps

Risk management

Configure fees

​Prerequisites

​Operating a platform-owned Allocation Strategy

​Authorize yield sources

​Configure allocation queues

​Target semantics

​Set queues

​How asset flow works

​View holdings and allocations

​Move assets to a yield source

​Dispatch assets to a yield source

​Rebalance between yield sources

​Handle user deposits

​Handle redemptions

​Keeper integration

​What keepers automate

​What remains manual

​Check keeper status

​Update queue priorities

​Troubleshooting

​Next steps

Risk management

Configure fees

Prerequisites

Operating a platform-owned Allocation Strategy

Authorize yield sources

Configure allocation queues

Target semantics

Set queues

How asset flow works

View holdings and allocations

Move assets to a yield source

Dispatch assets to a yield source

Rebalance between yield sources

Handle user deposits

Handle redemptions

Keeper integration

What keepers automate

What remains manual

Check keeper status

Update queue priorities

Troubleshooting

Next steps