How the vault works, line by line.

01 · Overview

One vault per coin, and four things that happen to it.

A STASH vault holds one coin, the asset. Deposit it and you receive shares, named s plus the coin's ticker (sUSDG for USDG). The coin pays its holders something else, the reward: trading fees, ETH, a stablecoin, a stock token. The keeper sells that reward for more of the asset, and the gain is released into the share rate over the vesting window. Redeem and you get the asset back, in kind, at the current rate.

The factory creates one vault per coin and then steps away: it holds no funds and has no power over a vault once it is deployed. The vault has no proxy, no mint entrypoint, no blacklist, no transfer hook and no tax setter, and its asset, reward, router and pool fee are fixed at creation.

1

vault per coin · VaultExists

4

keys at creation: admin, guardian, treasury, keeper

0

proxies and mint entrypoints

The files

• src/StashVault.solthe vault: shares, the rate, deposit, harvest, redeem, the roles and their limits
• src/StashFactory.solcreates one vault per coin, refuses duplicate keys and missing pools, can retire a vault
• src/lib/TwapOracle.solthe pool's 30-minute average price, vendored from Uniswap v3-periphery
• src/lib/FullMath.sol512-bit mulDiv for every conversion, so large balances cannot overflow

02 · Accounting

What the vault counts, and what it leaves out.

totalAssets()

balance minus what is still vesting

+3

share decimals over the coin

1,000

virtual shares, 1 virtual coin unit

Three views describe the coin inside the vault. rawAssets() is the asset's balance, vested or not. lockedProfitRemaining() is the part of the last harvest that has not been released yet. totalAssets() is the first minus the second: the principal the shares have a claim on, and the only number the rate is made of.

Reward tokens waiting in the vault are inventory, not principal. They count for nothing until a harvest turns them into the asset. That is also why a vault whose asset is its own reward is refused at construction (AssetIsReward): its inventory would count as principal and anyone could move the rate by sending it in.

Virtual shares

Every conversion adds 1,000 virtual shares against one virtual unit of the asset: shares = assets × (totalSupply + 1,000) ÷ (totalAssets + 1) and back again. This is the first-depositor and donation-inflation guard: someone who deposits one unit and then donates to the empty vault cannot capture more than they give, and loses about half of it. It is also why an empty vault opens at a rate of exactly 1e27.

All four conversions (convertToShares, convertToAssets, deposit, redeem) and the rate use a 512-bit mulDiv. In 256 bits the products overflowed on large balances of big-supply coins; they cannot now.

Share decimals: the coin's plus three

decimals() on the share returns the asset's decimals plus DECIMALS_OFFSET = 3, so one share still reads as about one coin in a wallet while the three extra digits absorb rounding. A coin with fewer than four decimals is refused (UnsupportedDecimals): there, the single virtual unit is a large piece of a whole coin, and a one-unit deposit stranded half of every harvest in a share nobody could redeem. More than 18 is refused too.

03 · The share rate

One formula: exchangeRateRay()

The share rate is how much coin one whole share is worth, scaled by 10²⁷ (a ray) so it keeps its precision in integer maths. The site prints it divided by 1e27, to nine decimals.

Why it never falls

• Deposits and redemptions change the coin and the shares in proportion, and both round down in the vault's favour, so the ratio can only stay or edge up by a rounding unit.
• At the instant of a harvest the balance and the lock rise by the same amount, so totalAssets() does not move. The rate rises only as the lock releases, in a straight line.
• Coin sent straight to the vault raises it at once. Nobody loses by that: a depositor still gets back what their shares are worth. It is one reason every vault is seeded before it opens.
• No function lowers it. The invariant suite runs fuzzed sequences of deposits, harvests, redemptions, donations and admin calls and checks after every step that the rate is at least 1e27 and at least what it was.

The Harvest event records rateRayAfter, the rate at the instant of that harvest, which is before its gain has vested. For the current value, call exchangeRateRay().

04 · Deposit

Deposit: shares for what actually arrived.

Approve the vault for the coin first (the coin's own approve), then deposit. The call runs these checks in this order; any one of them reverts the whole transaction, and the error names which.

1. Deposits paused? The guardian or the admin can pause them.

   :371

   DepositsArePaused()0x5a65d188

2. Receiver is the zero address?

   :372

   ZeroAddress()0xd92e233d

3. Zero assets?

   :373

   ZeroAmount()0x1f2a2005

4. Pull the coin. totalAssets() is read before and after transferFrom.

   :375-378

   transferFrom

5. Measure what arrived. A coin with a transfer tax lands short; shares are minted on what landed, not on what was asked.

   :382-383

   ZeroAmount()0x1f2a2005

6. Price the shares. received × (supply + 1,000) ÷ (assetsBefore + 1), 512-bit, rounded down.

   :387-388

   ZeroShares()0x9811e0c7

7. Fewer shares than you asked for? Your floor, minSharesOut.

   :389

   SlippageShares(got, wanted)0x3e0dcb4a

8. Mint the shares to the receiver and emit Deposit.

   :391-392

   mint · Deposit

previewDeposit is an upper bound: with a taxed coin the real count can be lower. Set minSharesOut from the preview minus the slippage you accept; the app does exactly that, in integer maths, for every deposit.

05 · Harvest

Harvest: the payout becomes more of the coin.

The keeper is the only address that can call it. It sells the vault's whole reward balance for the asset on the pool fixed at creation, through Uniswap v3's SwapRouter02, and books the gain into the vesting lock. No share is minted: supply stays where it is, and the coin per share goes up as the lock releases.

1. Caller is not the keeper?

   :442

   NotKeeper()0xf512b278

2. Harvests paused? Guardian or admin.

   :443

   HarvestIsPaused()0xe9dd7496

3. Too soon? The first harvest is free; after that, one per harvestInterval.

   :445-446

   HarvestTooSoon()0xcb562bd0

4. No reward to sell?

   :448-449

   NothingToHarvest()0x3f29331a

5. Take the fee in the reward token: harvested × feeBps ÷ 10,000 to the treasury. Never from principal.

   :451-452

   fee → treasury

6. Measure what is left to sell (the reward may be taxed too).

   :455-456

   NothingToHarvest()0x3f29331a

7. Price the floor from the pool before the swap: the higher of harvestFloor(swapIn) and your minAssetsOut. Too small to be worth one unit of the asset, or no price history, and there is no harvest.

   :460-463

   UnpricedHarvest()0x557bb5af

8. Swap: approve the router for exactly the amount, exactInputSingle reward → asset with amountOutMinimum 0, then set the allowance back to 0.

   :467-482

   swap · allowance 0

9. Gained less than the floor? Checked on the vault's own measured gain, not on the router's figure.

   :485-486

   SlippageAssets(got, wanted)0x806e3e09

10. Lock the gain, record lastHarvest and emit Harvest. Set last, so a reverted harvest does not use up the interval.

    :490-505

    lock · Harvest

The throttle

After the first harvest, the next one has to wait harvestInterval: 120 seconds by default. The admin can raise it to 7 days or lower it to 60 seconds, not below: a keeper that could harvest every block could repeat a bad-price harvest every block. It can never be longer than the vesting window, or a week of yield could pile into one release.

What the keeper decides, and what it does not

The keeper decides when. It can pass a minAssetsOut above the pool's floor and that stricter number binds; a looser one is ignored. It cannot pick the pool, the router or the fee tier, cannot harvest more often than the throttle, cannot skip the fee split, and never touches principal. If it disappears, nothing is harvested and payouts wait in the vault; redeem does not depend on it, and the admin can appoint another.

06 · Price floor maths

The price floor comes from the pool, not from the keeper.

Before it swaps, the vault asks the pool the swap goes through what it has been paying on average. harvestFloor(swapIn) takes the pool's mean tick over twapWindow (30 minutes by default), converts swapIn at that tick, and takes off the pool's own fee and the tolerance, in one 512-bit step:

How far below the average, per fee tier

With the default 1% tolerance, the floor is this fraction of the 30-minute quote, for each tier of the WETH/USDG pools on Robinhood Chain:

The rules around it

• One venue. The pool is looked up at construction from the router's own factory, never passed in, so the floor and the swap read the same pool.
• No history, no harvest. If the pool cannot answer for the whole window (too young, or too little observation history), observe() fails and the harvest reverts with TwapUnavailable(pool, window). The keeper's number never stands in for a missing price.
• Can be loosened, never switched off. The admin can set the window from 10 minutes to 2 hours and the tolerance up to 10%, not beyond.
• Checked on the vault's own gain. The router is given a minimum of zero; the vault compares what actually arrived with the floor. A coin with a transfer tax loses the tax on every fill, so its vault needs a tolerance that covers the tax, or every harvest reverts, loudly.
• Upstream maths. meanTick rounds towards negative infinity as upstream does, and getQuoteAtTick is the upstream body unchanged, vendored from Uniswap v3-periphery's OracleLibrary so the contracts have no external dependency.

07 · Vesting maths

Vesting: a gain reaches the rate in a straight line.

A harvest does not hand its gain to the shares at once. It books the gain into a lock, and the lock releases linearly until lockedProfitUntil:

The division floors the released part, not the remaining one, so the lock rounds in the vault's favour: at most one unit is released later than a perfectly straight line, never one earlier. The remaining lock is also capped at the balance, defensively.

A running lock keeps its own dates

The lock carries its own start (lockedProfitAt) and end (lockedProfitUntil). setVestingPeriod changes only the window the next harvest will use: lengthening it cannot push principal down, and shortening it cannot pull an outstanding gain forward. When a new harvest lands while a lock is still running, the unreleased remainder is carried into the new lock with the new gain, the clock restarts at that moment, and the end becomes the later of now + vestingPeriod and the old end. It is never pulled earlier.

08 · Redeem

Redeem: the same coin back, at the current rate.

In kind: you get the vault's asset, never the reward and never anything else. No exit fee and no queue. The one exception is an admin redemption pause, which lasts 72 hours at most (see Pauses).

1. Redemption paused? Only the admin can pause it, for 72 hours at most.

   :407

   RedeemIsPaused()0xd67e879f

2. Receiver is the zero address?

   :408

   ZeroAddress()0xd92e233d

3. Zero shares?

   :409

   ZeroAmount()0x1f2a2005

4. Redeeming someone else's shares? Their allowance is spent, unless it is unlimited.

   :411-417

   ERC20InsufficientAllowance()0x2fc50d60

5. Price the coin. shares × (totalAssets + 1) ÷ (totalSupply + 1,000), 512-bit, rounded down. The part still vesting is not counted, so it keeps releasing to the shares that stay.

   :419-420

   convert

6. Clamp to what is counted. Defensive: a 256-run fuzz shows it never engages.

   :423

   clamp

7. Nothing to pay, or less than your floor?

   :424-425

   SlippageAssets(got, wanted)0x806e3e09

8. Burn the shares, send the coin and emit Withdraw.

   :427-430

   burn · transfer · Withdraw

In the dry run, redeeming every share six hours after the harvest paid out 12,474.511184 USDG on a 10,000 deposit, and one unit, 0.000001 USDG, stayed in the vault: rounding in its favour. dry run on a local fork, nothing broadcast

09 · Roles and powers

Four keys, and exactly how far each one reaches.

The factory refuses to create a vault unless admin, guardian, treasury and keeper are four different non-zero addresses (DuplicateRole, 0x86afdf28). After that, the admin can reassign the guardian, the treasury and the keeper; those setters only check for a non-zero address. The admin role itself moves in two steps: transferAdmin names a successor and acceptAdmin, called by that successor, completes it.

The admin's settings, and the walls it cannot pass

Rescue

rescue(token, to, amount) sweeps a token sent to the vault by mistake. It refuses the asset, the reward and the share token by address, and then, because a token can have two contract addresses over one ledger, it snapshots the asset and reward balances and reverts with CannotRescueCore if either one moved. It is guarded on the effect, not on the name.

10 · Pauses

Three switches. None of them touches the rate.

11 · When a vault opens

A vault opens only when its yield is real.

The contract cannot tell a real payout from a buyback, so these are the project's rules, applied before a vault takes a deposit. The evidence for each goes on Proof as transaction hashes.

• Buybacks don't count. A buyback pays no holder, so there is nothing for a vault to receive.
• No dead coins. The factory refuses a pair with no pool (PoolDoesNotExist(asset, reward, fee), 0x137b894c), and the create script refuses an empty one: the chain cannot tell a thin pool from a healthy one.
• One vault per coin. A second is refused (VaultExists, 0x70743b38). A vault created on the wrong fee tier, or griefed before its seed deposit, can be retired with retireVault so a replacement can open; its holders keep every right, redeem included.
• Seeded first. Every vault gets a first deposit from the project before it opens, so an empty vault is never the target of a donation.

12 · ERC-4626 deviations

Where it leaves ERC-4626, on purpose.

The share accounting is ERC-4626 in shape: asset(), totalAssets(), the converters, the previews and the standard Deposit and Withdraw events. Two of the standard four entrypoints promise an exact amount out. With a coin that charges a transfer tax, what arrives is only known after the pull, so those two are left out instead of being wrong.

14 · Chain constants

Robinhood Chain, and the contracts a vault leans on.

These addresses come from config/addresses.json, the site's one source of truth, and link to Blockscout. Proof re-reads the chain in your browser: the chain id, that each address has code, and that the router reports this factory.

WETH/USDG pools

The pools the site measured, with their depth at the block it was read. Depth moves every block; this is a dated snapshot, not a live figure.

15 · Glossary

The words on this page.

Asset

The one coin a vault holds and pays back. asset().

Reward

What the asset pays its holders. Inventory until a harvest sells it. reward().

Share · sCOIN

The vault's ERC-20, named s plus the asset's ticker, with three more decimals than the asset.

Share rate

Coin per whole share, exchangeRateRay() ÷ 1e27. Starts at exactly 1, never falls.

Ray

A fixed-point number with 27 decimals.

Basis point · bps

One hundredth of a percent. 10,000 bps = 100%.

Principal

What the shares have a claim on: totalAssets().

Lock · vesting window

Where a harvest's gain waits, released in a straight line over the window (6 h by default).

Harvest

The keeper's call that sells the reward for more of the asset.

Keeper

The one address allowed to harvest.

Guardian

The address that can pause deposits and harvests, and nothing else.

Admin

The address that sets the vault's settings within their walls.

Treasury

The address the fee is sent to.

TWAP

Time-weighted average price: here, the pool's mean tick over the price window.

Tolerance

How far under the average, after the pool fee, a harvest may fill. maxSlippageBps.

Floor

The least a harvest must add to the vault, or it reverts. harvestFloor().

Virtual shares

1,000 shares and one coin unit that exist only inside the conversions.

Seed deposit

The project's first deposit into a vault, before it opens.

In kind

Paid in the same coin you deposited, not in anything else.

Selector · topic0

The four-byte id of a function or error, and the 32-byte id of an event.