Protocol
Vaults
Every fund is an ERC-4626 vault with voting shares. It holds the idle balance, counts what is deployed, and lets capital out to a strategy only through its governor.
Standard where it counts
RecurveVault is ERC-4626, so deposit, mint,
convertToAssets, previewRedeem and the rest behave the way any
integrator expects. It also extends ERC20Votes, which is what lets the governor
snapshot voting weight, and ERC20Permit, so shares can be approved by signature.
Shares carry the asset's decimals (no decimals offset) and an empty vault mints 1:1.
Deposit cap
depositCap is a ceiling on totalAssets(), set in the constructor
and enforced through the standard hooks: maxDeposit returns the room left under the
cap in asset terms (zero once totalAssets() reaches it, whoever the receiver is)
and maxMint the same room in shares. deposit and mint
revert above those with OpenZeppelin's ERC4626ExceededMaxDeposit and its mint
counterpart. Because the cap is on total assets, profit a strategy brings back consumes cap
room.
raiseDepositCap(uint256 newCap) // deployer only, emits DepositCapRaised(previousCap, newCap)
One-directional: whoever deployed the vault can raise it, anyone else reverts with
OnlyDeployer, and a value at or below the current cap reverts with
CapCannotDecrease. The Recurve Fund starts at 10,000 USDG (DEPOSIT_CAP
in the deploy settings).
Accounting
totalAssets() = idle balance + deployedAssets
float() = idle balance
deployedAssets is carried explicitly rather than inferred, because a position
mid-strategy is neither in the balance nor visible to balanceOf. It is the sum of
what is booked to each strategy target, deployedTo(target): every
fundStrategy adds to a target's part, and the target's return takes that part off
again.
| Function | Returns |
|---|---|
totalAssets() | Everything owed to depositors |
float() | The idle balance. Queued exits reserve nothing from it (the pendingWithdrawalAssets field it subtracts is never written) |
deployedAssets() | Committed to live strategies |
deployedTo(target) | The part of it booked to one target |
depositCap() | Ceiling on totalAssets() |
queueLength() | Redemption requests ever created, claimed ones included |
withdrawalQueue(i) | (shares, requestedAt, receiver, claimed) |
requestIdsOf(owner) | Queue positions belonging to an owner |
A strategy hands capital back through returnFromStrategy, which takes the
assets in and the deployment off the books in one call. totalAssets() and the
share price move by exactly the gain or the loss, once, and no exit is ever priced with the
returned assets counted twice. A venue that pays back with a plain transfer does not get
this: its deployment stays booked until settle, and until then the share price
is too high by what it sent back.
How capital moves
fundStrategy(target, assets) is the governor's way out: it transfers assets to
the target, adds them to deployedAssets, and reverts with FloatTooLow
if the request exceeds the idle balance. Only the governor can call it, and the governor only
calls it from an executed proposal.
returnFromStrategy(assets) is the way back. The strategy approves the vault and
calls it; the vault pulls the assets, clears whatever was booked to the caller and emits
StrategySettled(assets, pnl) with the amount it actually received. Anyone may call
it: a caller with nothing booked to it only gives the vault assets, and the one deployment a
caller can close is its own. settleStrategy(target, returned) is governor-only and
closes what is still booked to a target that paid back with a plain transfer, taking
returned as the governor reports it; after a returnFromStrategy it has
nothing to close and does nothing.
Depositors have a second exit the queue does not cover. The standard ERC-4626
withdraw and redeem are not overridden: they pay from the idle balance
and, when it is short, revert inside the asset's transfer instead of queueing.
maxWithdraw and maxRedeem report the holder's full position, not what
the balance can pay. Use requestRedeem, as the app and SDK do, to get the queue.
Redemption
requestRedeem(uint256 shares, address receiver, address owner) -> uint256 requestId
claimRedeem(uint256 requestId) -> uint256 assets
requestRedeem pays instantly when previewRedeem(shares) fits in the
idle balance and returns type(uint256).max as a sentinel. Otherwise it moves the
shares into the vault's own custody, appends to the queue, emits
WithdrawalQueued(owner, requestId, shares), and returns the queue index. The
receiver is fixed at request time.
claimRedeem prices at claim time, not request time — that is the whole reason
the queue exists. It reverts with RequestNotReady while the idle balance cannot
cover the shares' current value, RequestAlreadyClaimed on a repeat, and
NotRequestOwner unless the caller is the address that owned the shares when the
request was made (not the receiver, not an operator). Ready requests can be claimed in any
order; there is no expiry and no cancel.
Escrowed shares keep counting toward supply until the claim burns them, which is why
totalAssets does not net them out — and they carry no voting weight while they
wait, because the vault delegates to nobody.
Votes
Voting weight is checkpointed by block. getPastVotes(holder, block) is what the
governor reads at a proposal's snapshot; it is zero for a holder who never called
delegate. getPastTotalSupply(block) is the denominator for the veto
threshold and counts every share, delegated or not. A delegation in the same block as a proposal
is not visible to that proposal's snapshot.