Recurve Docs
Website GitHub Open app

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:

  1. Paused? Do nothing.
  2. A proposal is pending. Wait while its window is open. Once closed, execute it if execute simulates cleanly; otherwise abandon it (below) and move on.
  3. No cycle is open: no executed funding waits to be settled, and nothing is deployed. Deployable = float − queued exits − the reserve (RESERVE_BPS of total assets). If that clears MIN_TRADE, propose a buy for it; otherwise idle.
  4. A return has executed this cycle: settle the funding proposal with what Liquidated reported, before anything else.
  5. 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, or HOLD_SECONDS have passed since the funding executed — otherwise hold.
  6. 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

VariableRequiredWhat it is
PRIVATE_KEYyesThe 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_REGISTRYyesThe fund
RECURVE_STRATEGYyesIts PortfolioStrategyV2
RECURVE_TOKENyesThe one basket leg the strategy buys, despite the name: NVDA, 0xd0601CE157Db5bdC3162BbaC2a2C8aF5320D9EEC
DEX_QUOTERyesUniswap V3 QuoterV2, 0x33e885ed0ec9bf04ecfb19341582aadcb4c8a9e7
RECURVE_CHAIN_ID4663, the default
RECURVE_RPC_URLOverrides the network's public endpoint. Must be the same chain
RECURVE_DEPLOY_BLOCKBlock the governor went up; bounds the log scan
LOG_CHUNKBlocks per eth_getLogs. Default 100,000, the most the Robinhood Chain RPC accepts
MIN_TRADESmallest funding worth a proposal, in whole units of the asset. Default 0.001
RESERVE_BPSShare of total assets kept idle so small exits clear instantly. Default 1000 (10%)
HOLD_SECONDSUnwind this long after funding. Unset holds until exits or FORCE_UNWIND demand it
PRICE_TOLERANCE_BPSSee the floor. Default 300
FORCE_UNWINDtrue: sell, return, settle, then stay idle
PAUSEDtrue: read and report, never act
DRY_RUNtrue: simulate every action and log it; send nothing
RUNNER_INTERVAL_MSPoll 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.