Set up keeper automation

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

Keepers are off-chain bots that monitor on-chain conditions and execute automated operations like redemption queue processing and asset retrieval. This guide walks you through setting up keeper automation for your Vehicles and Multi-Vehicles.

How keepers work

The keeper system has three components:

Job Listing contracts — on-chain registries that define what needs to be automated and when
Keeper contract — processes batches of job executions submitted by authorized forwarders
Keeper bot — off-chain service that polls job status and submits execution reports

Register a Multi-Vehicle for automation

To enable automation, register your Multi-Vehicle with the MultiVehicleJobListing contract. This creates two persistent jobs: one for feeding the redemption queue and one for retrieving assets.

// Register with thresholds (in base asset units)
jobListing.registerMultiVehicle(
    multiVehicle,    // MultiVehicle address
    100e18,          // Redemption threshold
    100e18           // Retrieval threshold
);

// Coming soon

You can also register via CLI:

cast send $JOB_LISTING_ADDRESS \
  "registerMultiVehicle(address,uint256,uint256)" \
  $MULTI_VEHICLE_ADDRESS $REDEMPTION_THRESHOLD $RETRIEVAL_THRESHOLD \
  --private-key $ADMIN_PK

Configure thresholds

Thresholds prevent the keeper from executing transactions for trivial amounts, optimizing gas costs.Redemption threshold — the job triggers when both:

Withdrawable assets in the Multi-Vehicle exceed the threshold
Pending demand in the QueryRedeemQueue exceeds the threshold

Retrieval threshold — the job triggers when:

Retrievable assets in the QueryRedeemQueue exceed the threshold

To update thresholds, call registerMultiVehicle again with new values.

Job types

Redemption Queue Feed

Automates providing liquidity to the redemption queue when there is pending demand and available withdrawable assets.

Status check: redemptionStatus(multiVehicle)
Execution: feedQueryRedeemQueue(multiVehicle)
Condition: withdrawableAssets >= threshold AND pendingDemand >= threshold

Asset Retrieval

Automates retrieving assets from the redemption queue back to the Multi-Vehicle accounting engine.

Status check: retrievalStatus(multiVehicle)
Execution: retrieveQueryRedeemQueueAssets(multiVehicle)
Condition: retrievableAssets >= threshold

Sub-Query Progression

Automates progressing individual sub-queries sent to sub-vehicles (e.g., async protocols like Ethena).

Status check: subqueryStatus(subQuery, query)
Execution: progressQuery(subQuery, query)
Condition: Sub-vehicle query has moved past PROCESSING or PAUSED

Job status values

Status	Meaning
`POLL`	Not ready — check again later
`EXEC`	Ready — submit the execution report
`STOP`	Finished or unregistered — stop monitoring

Integrate with the Keeper contract

The Keeper processes batches of executions via reports — arrays of ReportDataItem structs.

struct ReportDataItem {
    address execTarget;    // Contract to call
    bytes execCalldata;    // Encoded function call
}

// Submit a report (requires KEEPER_ON_REPORT role)
keeper.onReport(metadata, encodedReport);

// Coming soon

If any call in the report reverts, the entire transaction reverts. This ensures atomicity for the batch.

Run the keeper bot

The keeper bot is a Python service that polls the indexer for JobStarted events and executes jobs when ready.

Environment variables

Variable	Description
`RPC_URL`	Ethereum node RPC URL
`KEEPER_ADDRESS`	Address of the Keeper contract
`FORWARDER_PRIVATE_KEY`	Private key of the forwarder account
`GRAPHQL_ENGINE_URL`	URL of the GraphQL indexer

Deploy with Docker

# Build the image
docker build -t railnet-keeper tools/keeper/

# Run the container
docker run -it --env-file .env railnet-keeper

Required roles

Role	Required for
`JOB_LISTING_REGISTER`	Registering new jobs
`JOB_LISTING_UNREGISTER`	Removing jobs
`JOB_LISTING_EXECUTE`	Executing registered jobs
`KEEPER_ON_REPORT`	Submitting reports to the Keeper

Getting started

Add a yield source

How-to guides

Reference

Set up keeper automation

How keepers work

Register a Multi-Vehicle for automation

Job types

Job status values

Integrate with the Keeper contract

Run the keeper bot

Environment variables

Deploy with Docker

Required roles

​How keepers work

​Register a Multi-Vehicle for automation

​Job types

​Job status values

​Integrate with the Keeper contract

​Run the keeper bot

​Environment variables

​Deploy with Docker

​Required roles

How keepers work

Register a Multi-Vehicle for automation

Job types

Job status values

Integrate with the Keeper contract

Run the keeper bot

Environment variables

Deploy with Docker

Required roles