Operating a fund
Running the agent
recurve-runner is the reference agent: one process per fund that proposes a position, executes it once the window closes, unwinds it when the policy says so, and settles.
What it does
The runner polls the chain every minute, rebuilds the fund's state from it, decides exactly
one action, and carries it out. It keeps no state of its own — the governor's
ProposalPosted / ProposalExecuted logs, each proposal's live state,
the strategy's balances and its Liquidated event are the whole picture — so a
restart mid-cycle picks up wherever the chain is.
1 propose buy float -> the leg, held by the strategy
hold until HOLD_SECONDS, an exit the float
cannot pay, or FORCE_UNWIND
2 propose sell the leg -> base asset, in the strategy
3 propose returnToVault base asset -> the vault (Liquidated)
4 settle(id of step 1, amount from Liquidated)
One funding per cycle. Float that arrives mid-cycle stays idle until the cycle settles: the
governor books one settle per deployment, and a second funding would make its fee
and PnL accounting wrong. Every step is its own proposal and waits its own veto window, so a
round trip is at least three days of windows on the scripted parameters, plus however long the
position is held.
The policy
Each round the runner reads a view — float, deployed, total assets, what queued exits are owed at the current share price, the newest live Pending proposal, the executed funding proposal, the strategy's holdings, the returned amount if the return has run — and decides:
- Paused? Do nothing.
- A proposal is pending. Wait while its window is open. Once closed, execute
it if
executesimulates cleanly; otherwise abandon it (below) and move on. - No cycle is open: no executed funding waits to be settled, and nothing is
deployed. Deployable = float − queued exits − the reserve (
RESERVE_BPSof total assets). If that clearsMIN_TRADE, propose a buy for it; otherwise idle. - A return has executed this cycle:
settlethe funding proposal with whatLiquidatedreported, before anything else. - The leg is held and has not been sold this cycle: sell it if an unwind is
due —
FORCE_UNWIND, queued exits exceed the float, orHOLD_SECONDShave passed since the funding executed — otherwise hold. - Base sits in the strategy: propose
returnToVault.
Each step runs once per cycle, and what has already executed decides which is next; the strategy's balances only say whether there is anything to do it with. Anyone can send the strategy a speck of either token, and it must not cost the fund another day's veto window.
The decision layer is a pure function with its own tests; nothing that touches an RPC decides anything.
The price floor
A proposal is quoted when it is posted and executed a day later. The live quote cannot be
the floor — any move against the fund inside the window would revert the fill — so the calldata
states quote × (1 − PRICE_TOLERANCE_BPS) as its quote, and the strategy then
enforces its own maxSlippageBps below that. With the defaults (300 bps tolerance,
300 bps strategy cap) a buy executes at anything within roughly 6% of the price at proposal
time. That is the number a watcher sees in the calldata, and the number an operator should set
deliberately: wider survives a volatile day, narrower gives a sandwich less room. The quote
comes from Uniswap's QuoterV2 on the pool tier the strategy is wired to, read
from the strategy itself so the two cannot disagree.
Stuck proposals
If the market moved past the floor by the time the window closes, or enough watchers
blocked it, execute reverts. The runner simulates before sending, logs
ABANDONED once, remembers the id, and proposes again at a fresh quote. The old
proposal stays Pending on the governor forever — there is no cancel — but nothing can
execute it except an agent key, and this one never will. Only the newest Pending proposal is
ever considered; older ones are never revived, because their calldata was priced for a market
nobody has looked at since.
The performance fee comes out of the agent's wallet
settle pulls the fee from msg.sender. Before settling a profitable
cycle the runner computes the fee, checks the wallet holds it in the vault's asset, approves
exactly that amount to the governor, and only then settles. If the balance is short it logs
the exact amount needed and retries next round; the position is already back in the vault by
then, so nothing is at risk while it waits. Keep the agent wallet funded with ETH for gas and
with the vault's asset for fees.
Configuration
| Variable | Required | What it is |
|---|---|---|
PRIVATE_KEY | yes | The agent key. Must be an agent on the governor, hold ETH for gas and the vault's asset for fees |
RECURVE_VAULT, RECURVE_GOVERNOR, RECURVE_REGISTRY | yes | The fund |
RECURVE_STRATEGY | yes | Its PortfolioStrategyV2 |
RECURVE_TOKEN | yes | The one basket leg the strategy buys, despite the name: NVDA, 0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC |
DEX_QUOTER | yes | Uniswap V3 QuoterV2, 0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7 |
RECURVE_CHAIN_ID | 4663, the default | |
RECURVE_RPC_URL | Overrides the network's public endpoint. Must be the same chain | |
RECURVE_DEPLOY_BLOCK | Block the governor went up; bounds the log scan | |
LOG_CHUNK | Blocks per eth_getLogs. Default 100,000, the most the Robinhood Chain RPC accepts | |
MIN_TRADE | Smallest funding worth a proposal, in whole units of the asset. Default 0.001 | |
RESERVE_BPS | Share of total assets kept idle so small exits clear instantly. Default 1000 (10%) | |
HOLD_SECONDS | Unwind this long after funding. Unset holds until exits or FORCE_UNWIND demand it | |
PRICE_TOLERANCE_BPS | See the floor. Default 300 | |
FORCE_UNWIND | true: sell, return, settle, then stay idle | |
PAUSED | true: read and report, never act | |
DRY_RUN | true: simulate every action and log it; send nothing | |
RUNNER_INTERVAL_MS | Poll interval. Default 60000 | |
PORT | /health port. Default 8080 |
The pool fee tier, the strategy's slippage cap and the governor's performance fee are read from the contracts, not configured, so they cannot disagree.
Boot checks
The process refuses to start, with the reason on the first line of the log, if: the RPC is not Robinhood Chain; the governor, vault and strategy do not reference each other; the token is not in the strategy's basket; the key is not an agent; the quoter cannot price the strategy's pool; or the wallet holds no ETH. A read that returns no data names the address, so an address from another chain fails at boot rather than at the first transaction.
Operating it
GET /health answers with the last round: what it decided, when, and the last
error if any. It returns 503 after three failed rounds in a row, so point a
healthcheck at it. Failed rounds back off exponentially to ten minutes. Every write is
simulated before it is sent; start any new deployment with DRY_RUN=true and read a
few rounds of log before removing it.
git clone https://github.com/Recurve-Money/recurve-runner
cd recurve-runner && npm install
cp .env.example .env # fill it in, keep DRY_RUN=true; the runner loads .env from its folder
npm start
It is one long-running Node process with no state of its own: any host that restarts it on failure will do. Set every required variable there first.