Custodies tracked finite ONI inventory and releases exact reserved rewards.
Onigiri Protocol / Documentation
Bounded ONI emissions. Permanent Sushi liquidity. A new flywheel.
Onigiri is a yield protocol for Robinhood Chain. ETH, $ONI, and fungible ONI/WETH Sushi V3 liquidity shares earn from a finite, pre-funded ONI inventory. Protocol fees fund two equal primary routes: permanent ONI destruction and permanent SUSHI/WETH liquidity. Only realized trading fees from that liquidity fund the secondary 50/40/10 flywheel.
Onigiri in plain English
Onigiri is a place to deposit one of three supported assets and earn rewards for participating. You can deposit ETH, ONI, or oniLP. The protocol records your credited deposit, calculates your share of available rewards, and lets you withdraw your credited principal whenever withdrawals are open—which they remain even if new deposits are paused.
The design has two goals at the same time. It gives participants access to a finite pool of ONI rewards, and it uses protocol fees to build assets that stay inside the protocol. Half of protocol working capital permanently removes ONI from circulation. The other half builds permanent SUSHI/WETH liquidity that can earn trading fees.
Choose the vault that matches the asset you already hold and the type of exposure you want.
After the entry fee, the remaining amount is tracked as yours and kept separate from protocol money.
All three vaults share a pre-funded reward inventory through separate pool accounting.
This second reward comes only from actual SUSHI/WETH trading fees, never from treasury principal.
The two kinds of return
ONI emissions and SUSHI revenue are different. ONI emissions come from ONI that already exists and has been placed in RewardVault. The protocol does not mint more ONI. SUSHI revenue is earned later, when traders use the protocol-owned SUSHI/WETH liquidity and pay trading fees. Keeping these sources separate makes it possible to explain exactly where every reward came from.
What the protocol does not do
Onigiri does not lend user deposits, use leverage, bridge funds to another network, or move principal through a discretionary strategy. Credited ETH stays as ETH, credited ONI stays as ONI, and credited oniLP stays as oniLP. The system's external revenue source is Sushi V3 trading activity.
Stake a supported asset, earn from a finite ONI reserve, and help route protocol fees into permanent ONI burns and permanent SUSHI/WETH liquidity.
The complete economic loop
The 3% protocol portion never has a single destination. Kitchen always divides it equally across both primary routes. The treasury split is separate and applies only after SUSHI/WETH LP trading fees have been realized.
gross vault entry or exit
|
+-- 1% developer fee, paid in kind
+-- 96% credited stake or withdrawal proceeds
|
+-- 3% protocol working capital
|
KITCHEN
/ \
50% 50%
/ \
ONI buy/direct SUSHI/WETH protocol-owned liquidity
burn |
+-- realized V3 trading fees only
|
+-- 50% compound POL
+-- 40% buy and burn ONI
+-- 10% normalize to SUSHI
|
active ONI stakers
Kitchen's 50/50 split allocates protocol working capital. Treasury's 50/40/10 split allocates only realized trading-fee value. Treasury principal is never part of the second split.
Follow one deposit through the system
Imagine depositing 100 units of a supported vault asset. One unit goes to the fixed developer recipient, three units become protocol working capital, and the remaining 96 units become your credited stake. The same percentages apply when you withdraw, while claiming rewards carries no fee.
The three protocol units then enter Kitchen. Kitchen does not make a judgment call about where they should go. Its rules always divide that working capital into two equal halves: one half supports ONI destruction, and one half supports permanent SUSHI/WETH liquidity.
Why the second split happens later
Owning liquidity and earning revenue from liquidity are not the same thing. The SUSHI and WETH placed into the position are principal: they are the assets doing the work. Trading fees are the new value earned while that position serves traders. Only those earned fees enter the 50/40/10 flywheel, so the system never has to spend the liquidity principal to create a holder payout.
The $ONI flywheel
A flywheel is a system in which one useful action helps create the conditions for the next one. In Onigiri, staking activity creates protocol working capital. That working capital supports ONI destruction and permanent SUSHI/WETH liquidity. Trading through that liquidity can earn fees, and those fees are routed back into compounding, more ONI destruction, and SUSHI rewards for active ONI stakers.
The loop is rules-based. It does not depend on someone deciding what to buy each week or moving funds into a new strategy. Every stage has a fixed source, a fixed calculation, and a fixed destination.
bounded ONI reward inventory
|
v
ETH / ONI / oniLP staking
|
+-- 3% protocol working capital from entry and exit
|
KITCHEN
/ \
50% ONI burn 50% permanent SUSHI/WETH POL
|
trading activity
|
realized fees only
/ | \
50% compound 40% ONI burn 10% SUSHI
| |
deeper permanent POL active ONI stakers
Bounded rewards begin the motion
Pre-funded ONI rewards give ETH, ONI, and oniLP holders a reason to participate while reward inventory is available. More participation can produce more entry-and-exit activity, and the protocol's 3% portion of those movements becomes working capital. The reward program is bounded because RewardVault holds a finite amount of existing ONI and cannot mint more.
Permanent liquidity carries value forward
Half of Kitchen working capital builds a SUSHI/WETH position that remains owned by the protocol. That capital is not paid out or withdrawn after one cycle. It stays available to serve future trades. Half of the fees later realized from those trades is compounded into the position, allowing earned revenue to add to the permanent liquidity base.
Two routes support permanent ONI destruction
ONI destruction appears in both layers of the flywheel. Kitchen directs 50% of protocol working capital to buying and burning ONI or sending fee-denominated ONI directly to the burn destination. Later, treasury directs 40% of realized SUSHI/WETH trading-fee value to another ONI buy-and-burn route. The sources are different, but both destinations are permanent.
SUSHI revenue connects the loop to ONI staking
The remaining 10% of realized trading-fee value is normalized into SUSHI and sent to active ONI stakers. This gives the ONI vault a reward stream tied to actual Sushi market usage, separate from its bounded ONI emission stream. If no ONI is staked, the SUSHI waits in a queue until it can be distributed safely.
The flywheel can outlive emissions
New ONI emissions end when the unreserved RewardVault inventory is exhausted. The permanent-liquidity side does not depend on minting another reward token. Existing POL can continue serving trades, realized fees can continue compounding and burning ONI, and the SUSHI holder allocation can continue flowing to active ONI stake.
The 50/50 Kitchen split routes protocol working capital. The later 50/40/10 treasury split routes only realized trading fees. Keeping those layers separate is what lets the flywheel grow without spending user deposits or POL principal.
Capital and revenue provenance
User principal is never treasury capital.
| Balance | Source | Permitted destination | Explicitly excluded |
|---|---|---|---|
| Credited ETH | ETH farm user deposits | That user's withdrawal | Kitchen, swaps, POL, rewards |
| Credited ONI | ONI farm user deposits | That user's withdrawal | Kitchen, burns, rewards |
| Credited oniLP | LP farm user deposits | That user's withdrawal | Protocol redemption |
| Reserved reward ONI | RewardVault funding | Authenticated claimant for its pool | Other pools, owner, Kitchen |
| Kitchen capital | Isolated 3% protocol fees and donations | 50% burn / 50% POL | Credited principal |
| POL principal | Kitchen flywheel leg and compounded fees | Active or deterministically recentered LP | Holder payout, sweep, redemption |
| SUSHI holder rewards | Realized SUSHI/WETH trading fees | Active ONI stakers | Treasury principal and carried liquidity |
Think of separate labeled envelopes
The contracts treat each kind of balance as though it lives in a clearly labeled envelope. An envelope for user deposits cannot be opened by Kitchen. An envelope for promised rewards cannot be used by another pool. An envelope for protocol-owned liquidity cannot be mistaken for trading revenue. The tokens may exist in connected contracts, but their accounting purpose remains explicit.
Principal means the asset base that belongs to a user or keeps a liquidity position operating. Working capital means the protocol-owned 3% fee amount routed by Kitchen. Revenue means value newly earned as trading fees. These words describe different sources and therefore different permitted destinations.
Why source tracking matters
A token balance alone cannot explain who owns it or what it may be used for. Onigiri records both the amount and its source. This provenance is what prevents a convenient-looking balance from being reused for an unrelated purpose. It is also what makes the protocol's core solvency rules possible to check onchain.
Three staking vaults
| Pool | Stake | Yield | Custody guarantee |
|---|---|---|---|
| ETH Vault | Native ETH | Finite ONI emissions | Credited ETH remains idle and withdrawable |
| ONI Vault | $ONI | Finite ONI + realized-fee SUSHI | Principal, ONI rewards, and SUSHI rewards use separate ledgers |
| LP Vault | oniLP shares | Finite ONI emissions | Credited fungible shares remain physically reserved |
Each pool has an independent immutable Emax and K curve. Reward claims have no 4% fee. Pausing affects new stakes only; withdrawals and claims remain callable.
Choosing a vault
This is the simplest path for an ETH holder. Credited ETH sits in the vault and earns finite ONI emissions.
ONI stakers receive finite ONI emissions and are the only group that shares the 10% SUSHI holder allocation.
This path is for participants who already own shares of the canonical ONI/WETH liquidity vault.
Deposits, ONI rewards, and any SUSHI rewards are accounted for independently.
Depositing, earning, and leaving
A deposit first checkpoints rewards so the time before your arrival belongs to the people who were already staked. Your fee is then separated and only the remainder becomes credited principal. While you remain staked, later checkpoints add your share of new rewards to the pool's accounting. When you claim, rewards are paid without a claim fee. When you withdraw, the vault applies the exit fee and returns the remaining asset to you.
No vault promises a fixed personal rate. Each pool's total emission rate responds continuously to the amount staked in that pool, and an individual participant's share depends on how much of the pool they represent.
What happens when you use Onigiri
The interface may reduce each action to a button, but the contracts follow a careful order underneath. That order protects earlier participants, separates fees from deposits, and makes sure a reward is backed before it appears as claimable.
When you stake ETH
The ETH vault first updates reward accounting through the current block. It sends 1% of the incoming ETH to the fixed developer recipient and records 3% for Kitchen. The remaining 96% becomes your credited ETH principal. That credited ETH is not wrapped, traded, lent, or supplied elsewhere. Your vault balance begins earning its share of the ETH pool's ONI emissions from that point forward.
When you stake ONI
The ONI vault follows the same fee pattern in ONI. Your credited ONI earns from the ONI pool's finite emission budget. It may also earn SUSHI after the protocol-owned SUSHI/WETH position realizes trading fees and treasury sends the holder portion into the vault. The ONI reward balance, SUSHI reward balance, and ONI principal balance remain three distinct obligations.
When you stake oniLP
You deposit fungible shares rather than a Sushi position NFT. The LP vault separates the fee shares before it credits your principal. The developer receives the 1% share portion. Only the protocol's 3% share portion may be redeemed into ONI and ETH for Kitchen. Your credited oniLP shares stay inside the LP vault and cannot be included in that redemption.
When you claim rewards
A claim first brings the pool's accounting current. The vault calculates what its global reward index owes your stake, subtracts anything already recorded as paid, and requests exactly that amount from the pool's reserved reward balance. ONI and SUSHI reward claims do not pass through the entry-and-exit fee split.
When you withdraw
The vault checkpoints before changing your stake, applies the fixed exit fee to the amount being withdrawn, and returns the remainder. Any rewards already earned remain claimable according to their own ledgers. A pause on new deposits does not turn into a lock on withdrawals or reward claims.
oniLP uses complete-NAV share pricing
OniEthLiquidityVault wraps one canonical ONI/WETH V3 position into transferable 18-decimal shares. Before every mint or burn, it checkpoints fee growth with a zero-liquidity burn and collects all uncollected V3 fees into share-owned reserves.
complete NAV before mint =
TWAP value of ONI reserves
+ WETH reserves
+ TWAP value of active position principal
+ fees crystallized before the supply change
new shares =
contribution TWAP value * existing supply
/ complete NAV before mint
Because fee crystallization precedes the denominator, a depositor entering immediately before collection cannot capture fees earned by incumbent shares. Redemption follows the same order: crystallize fees, assign pro-rata reserves, burn pro-rata position liquidity, and add all principal from that burn without a second pro-rata reduction.
Share valuation and redemption read liquidity from the actual V3 pool position. They do not trust a local liquidity counter, so direct liquidity donations are included.
What an oniLP share represents
A Sushi V3 liquidity position normally has two assets inside it and may also have trading fees waiting to be collected. OniEthLiquidityVault places that whole position behind a regular, divisible token called oniLP. Owning 1% of all oniLP shares means owning 1% of the vault's complete economic value—not merely 1% of the tokens that happen to be sitting idle in its wallet.
NAV means net asset value. In this vault, complete NAV includes idle ONI, idle WETH, the assets currently active in the Sushi position, and fees earned before the share supply changes. Every part is translated into a common WETH value so deposits and redemptions can be compared fairly.
Why fees are collected before shares change
Suppose ten people supplied liquidity yesterday and the position earned fees overnight. A new person should not be able to deposit this morning and receive part of yesterday's earnings. Before minting new shares, the vault makes the pool account for every fee earned so far and includes that value in the share price. The newcomer receives shares only for the new value they contribute.
The same fairness rule applies on the way out. Before shares are burned, the vault makes all value visible, calculates the exiting holder's proportion, removes the matching amount of position liquidity, and pays the corresponding ONI and native ETH. Existing holders keep their proportion of everything left behind.
Why TWAP is used for value
TWAP means time-weighted average price. Instead of trusting a single instant that may contain a brief price spike, the vault uses an average observed through the canonical pool over a fixed window. This gives share calculations a steadier reference and makes a momentary trade less able to distort how many shares a deposit receives.
Finite rewards become irrevocable at checkpoint
RewardVault contains existing ONI; it cannot mint. FarmController calculates all three pools from one global interval and one pre-change stake snapshot.
rate_i = Emax_i * stake_i / (stake_i + K_i)
available = tracked RewardVault inventory
- total rewards already reserved
if total scheduled > available:
budget_i = scheduled_i * available / total scheduled
- 01Checkpoint together
All pool schedules use the same timestamp and pre-change stake.
- 02Scale only the new interval
If inventory is short, all three budgets are reduced proportionally.
- 03Reserve atomically
Every represented reward is added to that pool's reserve in the same transaction as its reward index.
- 04Claim from one reserve
A vault can debit only its own pool. Later shortages cannot reduce a published index.
Unrepresented rounding dust remains unreserved. Direct token transfers to RewardVault are observable but do not enter the schedule until accepted through the checkpointing donation path.
How the reward curve feels in practice
Emax is the highest total emission speed a pool can approach. K describes how much stake is needed for that pool to reach half of that speed. When a pool is small, adding stake raises its total reward flow meaningfully. As the pool grows, total emissions keep rising but approach the ceiling more slowly. Because more stake is also sharing those rewards, the reward rate per deposited unit falls as participation grows.
Each vault has its own curve. Activity in the ETH pool does not directly rewrite the ONI or LP curve. The pools meet only when the controller checks whether the shared finite RewardVault inventory can cover the next interval for all three.
A checkpoint turns time into a funded promise
Rewards build up over time, but the accounting is advanced at checkpoints. A checkpoint measures the elapsed interval, calculates all three pool budgets from the stake that existed during that interval, and reserves the required ONI at the same moment it raises the reward indexes. Once an index says a reward has accrued, matching ONI has already been spoken for.
This is why an old reward cannot be cut later. If RewardVault is too low to fund a new interval in full, the controller reduces only that new interval and reduces every pool proportionally. It never reaches backward into rewards that earlier checkpoints already assigned.
When finite ONI inventory runs out
New ONI emissions stop when no unreserved inventory remains. That does not erase reserved rewards, block principal withdrawals, or stop realized SUSHI revenue. Users may still claim ONI already committed to them, and the Kitchen and treasury can continue their independent fee-driven work.
LP fees are isolated before redemption
Every entry and exit computes the 1% developer balance, 3% protocol balance, and user remainder independently. In the LP farm, those are share balances—not estimates of underlying assets.
gross oniLP shares
|
+-- 1% developer shares --> immutable developer recipient
+-- 3% protocol shares --> redeem to ONI + ETH --> Kitchen
+-- remainder --> credited principal or user payout
The contract checks physical oniLP solvency before the developer transfer, before the protocol redemption, after the protocol redemption, and before completing a withdrawal. Only the isolated protocol shares can become Kitchen working capital.
A simple 100-unit example
If 100 units enter a farm, 1 unit is the developer portion, 3 units are the protocol portion, and 96 units become credited stake, subject to the contract's downward rounding at token precision. The fee is paid in the asset used by that vault: ETH for the ETH vault, ONI for the ONI vault, and oniLP shares for the LP vault.
The exit is a separate event with the same percentages. If a user asks to withdraw 100 credited units, 1% of that withdrawal goes to the developer recipient, 3% becomes protocol working capital, and the user receives the remainder. A reward claim is different: the full claimable reward is paid with no 4% deduction.
Why LP fee shares are separated first
An oniLP share owns a fraction of an underlying ONI/WETH position. The LP farm therefore cannot safely estimate the 3% fee in ONI and ETH while those shares are mixed with user balances. It first marks the exact developer shares, protocol shares, and user shares as separate amounts. Only then may the protocol shares be redeemed. This ordering proves that the redemption came from protocol-owned fee value rather than credited user shares.
Kitchen: exact primary routing
Kitchen accepts isolated protocol-owned ONI/ETH fee assets and explicit donations. It does not receive or allocate credited principal, and SUSHI/WETH trading fees remain in the separate treasury revenue path.
ETH buys ONI to burn. ONI is transferred directly to the burn recipient.
ETH enters treasury. ONI is first normalized to ETH, then deployed as liquidity.
oniBurnBps = 5_000
sushiFlywheelBps = 5_000
oniBurnBps + sushiFlywheelBps = 10_000
The constructor rejects any other weights. Processing is permissionless, thresholded, cooled down, batch-limited, and atomic across each selected asset route.
What Kitchen actually does
Kitchen is an automatic router, not an investment manager. It receives only protocol-owned ONI and ETH, keeps a running balance for each asset, and processes eligible amounts through routes fixed at deployment. No caller decides the split, substitutes another token, or sends the output to a personal address.
The threshold and cooldown avoid turning every tiny fee into a separate trade. Batch limits keep one maintenance call bounded. If an amount is too small to produce a meaningful quote, it remains pending for a later batch instead of being forced through at an unusable size.
The ONI destruction half
When this half begins as ETH, the protocol buys ONI through the approved ONI/WETH route and sends the result to the fixed burn recipient. When it already begins as ONI, it can go directly to that destination. In either case, the result is permanent ONI destruction rather than a treasury balance that can later return to circulation.
The SUSHI/WETH liquidity half
This half is normalized into ETH and handed to the treasury liquidity path. The treasury buys the matching SUSHI needed for a two-sided position and adds both assets to permanent protocol-owned liquidity. The position then serves SUSHI/WETH traders and may earn fees from their swaps.
Kitchen receives isolated protocol fees and explicit donations. It has no route that pulls credited ETH, credited ONI, credited oniLP, or reserved ONI rewards into its balances.
Deterministic SUSHI/WETH POL management
The liquidity adapter permanently owns a direct SUSHI/WETH V3 position. Its compile-time width is exactly 120,000 ticks—roughly 162,750× from boundary to boundary—and is tick-aligned. Its center is derived from the arithmetic-mean TWAP; permissionless callers never provide ticks.
center = floorToTickSpacing(arithmeticMeanTwapTick)
lower = center - 60,000 ticks
upper = center + 60,000 ticks
eligible for recenter when:
twapTick < lower || twapTick >= upper
- 01Validate price
Spot must remain within the immutable deviation ceiling around TWAP.
- 02Crystallize fees first
Old-position SUSHI and WETH fees enter fee-only reserves.
- 03Isolate principal
The full old position burns into separate principal reserves.
- 04Derive and rebalance
Only principal uses bounded typed SUSHI/WETH swaps; no arbitrary route exists.
- 05Remint
Principal enters the sole TWAP-derived range; residual principal stays explicitly reserved.
recenter() is parameterless. It cannot change width, pool, tokens, fee tier, TWAP window, slippage, recipient, or allocation. There is no external POL removal or sweep function.
What protocol-owned liquidity means
POL stands for protocol-owned liquidity. The protocol, rather than an individual depositor, owns the SUSHI and WETH placed in this position. That liquidity is designed to stay in the system permanently. It gives traders a pool in which to exchange SUSHI and WETH, and trading activity may produce fees for the protocol's revenue flywheel.
Why a V3 position has a range
Sushi V3 liquidity works inside a chosen price range. While the market price is inside that range, the position can serve trades and earn fees. If the price moves outside it, the position remains owned and accounted for, but it is no longer actively serving both sides of the market. Recentring moves the assets into a new range around the longer-term observed price.
Onigiri uses a deliberately wide, fixed-width range. Wide coverage reduces how often maintenance is needed, while the TWAP-derived center gives the next position an objective reference. The range can move when the market genuinely moves, but its width and method of calculation do not change.
Why the caller cannot choose the new range
Anyone may pay the gas to call an eligible recenter, which helps the position remain maintainable without depending on one operator. The caller is only starting a predefined procedure. The contracts calculate the ticks, verify the observed prices, separate fees from principal, rebalance through approved routes, and return principal to the newly derived position.
Holder SUSHI comes only from realized LP fees
The adapter tracks pendingFeeSushi/pendingFeeWeth separately from principalSushiReserve/principalWethReserve. Collection can transfer only the fee ledger to SushiTreasuryVault.
1. snapshot treasury SUSHI and ETH balances
2. crystallize and collect adapter fee reserves
3. require reported amounts == exact balance deltas
4. convert collected SUSHI fees to ETH
5. combine with collected WETH fee value
6. allocate fee-only normalized value:
50% compound POL
40% buy and burn ONI
10% buy SUSHI for active ONI stakers
The 10% leg therefore includes the WETH component of V3 fees: it is normalized to the common ETH value and converted into SUSHI before transfer. OniFarmVault advances accSushiRewardPerShare only after the bound treasury has transferred the corresponding SUSHI into the farm. Carried treasury liquidity and POL principal never enter this calculation.
What “realized fees” means
A liquidity position can contain principal, fees that have accumulated in the pool, and unused assets waiting for a future liquidity addition. Onigiri calls revenue realized only after the adapter crystallizes the position's earned fees and the treasury verifies the exact SUSHI and WETH amounts it actually received. A reported estimate or a pre-existing treasury balance is not enough.
Why both fee assets are normalized
Sushi V3 pays fees in both assets of the pair. If the flywheel divided only the SUSHI side, the WETH side would not contribute proportionally. The treasury therefore translates both collected fee components into one common ETH value before applying 50/40/10. This makes each destination receive its intended share of the complete fee event.
After the split, the compound portion returns to protocol-owned liquidity. The burn portion buys ONI and destroys it. The holder portion buys SUSHI and transfers that SUSHI into OniFarmVault. Only after the tokens arrive does the ONI farm increase its SUSHI-per-share index.
What happens when nobody is staking ONI
The holder allocation is not handed to an arbitrary address and is not divided by zero. It remains queued until ONI stake exists. A later permissionless call can then index the queued SUSHI across active ONI stake, preserving the intended destination.
Permissionless, bounded automation
Any account may checkpoint emissions, process eligible Kitchen batches, harvest realized fees, distribute queued SUSHI when stake exists, or recenter out-of-range POL. Permissionless means execution access, not parameter control.
Permissionless does not mean uncontrolled
A permissionless function is a public maintenance button. Any account can press it, so the protocol does not have to wait for a special keeper. The button's result is still determined entirely by contract rules. The caller cannot choose a friendlier price, invent a route, change a recipient, widen a range, or include a different balance.
Bounded means the work has limits. Price checks compare the immediate market with the time-weighted reference. Slippage rules set a minimum acceptable output. Maximum trade sizes and chunk counts cap how much can happen in one call. Thresholds and cooldowns prevent needless repeated processing of tiny balances.
Routine maintenance available to anyone
- Bring all three ONI reward pools to the current checkpoint.
- Process an eligible batch of Kitchen working capital.
- Crystallize and harvest realized SUSHI/WETH trading fees.
- Distribute queued SUSHI when active ONI stake exists.
- Recenter POL when TWAP has moved outside the active range.
- Leave ineligible or undersized work safely pending for later.
Contract architecture
Checkpoints all three saturating curves and owns per-pool reward reserves.
Reserves credited native ETH and routes only fee ETH.
Separates ONI principal, ONI emissions, and realized-fee SUSHI.
Issues complete-NAV oniLP shares over canonical ONI/WETH liquidity.
Reserves credited oniLP and redeems only isolated 3% fee shares.
Applies the exact 50% burn / 50% POL primary allocation.
Allows only typed ONI/WETH and SUSHI/WETH exact-input routes.
Owns POL, fee/principal ledgers, and parameterless TWAP recentering.
Routes only realized fee deltas through immutable 50/40/10 weights.
A guided tour through the contracts
The farm vaults are the user-facing custody layer. They accept the supported staking assets, keep credited principal backed, and calculate each account's rewards. They do not decide how much ONI the whole system may emit; FarmController does that for all three pools together.
FarmController turns elapsed time and live stake into pool reward budgets. RewardVault is the finite store of existing ONI that backs those budgets. The controller may reserve and release rewards through authenticated pool paths, while RewardVault itself cannot mint ONI.
Fee assets travel through a different side of the architecture. Kitchen handles the primary 50/50 working-capital split. The swap and buyback adapters restrict which markets may be used. The Sushi liquidity adapter holds permanent POL and distinguishes its principal from its earned fees. SushiTreasuryVault verifies those fees and applies the secondary 50/40/10 revenue split.
OniEthLiquidityVault and LpFarmVault have related but different jobs. The first turns a canonical ONI/WETH position into fairly priced fungible oniLP shares. The second lets those shares participate in the finite ONI reward program while keeping user shares separate from fee shares.
Core accounting invariants
RewardVault.totalReleased <= RewardVault.totalFunded
totalReservedRewards <= RewardVault.remainingInventory
pool claim debits only that pool's reservedRewards
ETH farm balance >= credited ETH
ONI farm balance >= credited ONI
LP farm oniLP >= credited oniLP
ONI farm SUSHI >= indexed + queued SUSHI liability
entry / exit = 1% developer + 3% protocol + remainder
Kitchen = 50% ONI destruction + 50% SUSHI/WETH POL
fee revenue = 50% compound + 40% ONI burn + 10% SUSHI
POL fee reserves and principal reserves are separately backed
oniLP supply changes occur only after V3 fee crystallization
How to read an invariant
An invariant is a rule that must remain true before and after every successful transaction. The symbol >= means “is at least.” For example, “ETH farm balance is at least credited ETH” says the vault must physically hold enough ETH to cover all ETH it records as user principal.
The reward invariants say that the system cannot release more ONI than it was funded with, and one pool cannot spend another pool's reservation. The fee invariants say every entry and exit can be reconstructed as developer fee, protocol fee, and user remainder. The liquidity invariants say principal and revenue remain separately backed even when the position is collected or recentered.
These are not target percentages that may drift over time. They are accounting boundaries the contracts enforce while processing deposits, withdrawals, claims, routing, liquidity maintenance, and fee harvests.
Immutable protocol parameters
| Parameter | Value / rule | Mutation after deployment |
|---|---|---|
| Entry / exit fee | 1% developer + 3% protocol | None |
| Reward claim fee | 0% | None |
| Kitchen primary split | 50% ONI destruction / 50% POL | None |
| Realized-fee split | 50% compound / 40% ONI burn / 10% SUSHI | None |
| Farm rate | Emax × S / (S + K), per pool | None |
| POL range | 120,000-tick width, TWAP-derived center | Width cannot change; center changes only by formula |
| Execution bounds | TWAP window, slippage, trade size, threshold, cooldown | None |
What immutable means here
An immutable parameter is fixed when its contract is deployed and has no later setter. The entry and exit fees, routing weights, pool curve settings, price-check windows, execution bounds, canonical assets, and relevant market identities cannot be casually tuned after users begin participating.
The contracts are non-upgradeable, so their implementation cannot be replaced through a proxy. ONI itself also sits outside Onigiri's control: it is launched externally, and the protocol has no ONI minting, supply-management, blacklist, or token-fee authority.
Some system state naturally changes without changing the rules. Stake totals move as users enter and leave. Reward inventory falls as rewards accrue and are claimed. A POL range may recenter when the immutable formula says it is out of range. Those are expected outcomes of fixed rules acting on new conditions.
A plain-language glossary
These terms appear throughout the protocol because they describe different kinds of value and different stages of accounting. The distinctions matter, but the ideas are straightforward once each word has a stable meaning.
| Term | Simple meaning | Why it matters in Onigiri |
|---|---|---|
| Stake | An asset deposited into a vault to participate in rewards. | Stake size helps determine a user's share of later pool rewards. |
| Principal | The underlying asset balance credited to a user or committed to a liquidity position. | Principal is kept separate from protocol working capital and realized revenue. |
| Yield | Value earned while participating. | Onigiri yield may be finite ONI emissions or realized-fee SUSHI, depending on the vault. |
| Emission | The scheduled release of an existing reward asset over time. | ONI emissions transfer pre-funded ONI; they do not create new ONI. |
| Reward inventory | The finite ONI balance accepted into RewardVault for future schedules. | Unreserved inventory limits how much new ONI can accrue. |
| Liquidity | Two assets made available in a market so traders can exchange between them. | Onigiri builds permanent SUSHI/WETH liquidity and wraps canonical ONI/WETH liquidity into oniLP. |
| LP | Short for liquidity provider or liquidity position. | An LP position holds market-making assets and may earn trading fees. |
| oniLP | A fungible token representing a proportional claim on the complete ONI/WETH liquidity vault. | It makes one canonical V3 position divisible and stakeable. |
| NAV | Net asset value: the total economic value behind all shares. | Complete NAV prevents new oniLP deposits from capturing value earned earlier. |
| POL | Protocol-owned liquidity. | The SUSHI/WETH position belongs permanently to the protocol rather than to farm depositors. |
| Trading fee | A small amount paid by a trader for using a liquidity pool. | Realized SUSHI/WETH fees are Onigiri's external revenue source. |
| Realized | Actually collected and verified, rather than merely estimated. | Only realized fee deltas may enter the treasury revenue split. |
| TWAP | A price averaged over a fixed period of time. | It guides minimum swap output, oniLP valuation, and deterministic POL recentering. |
| Spot price | The market price at one immediate moment. | The protocol compares spot with TWAP to reject operations during excessive short-term deviation. |
| Checkpoint | An accounting update that converts elapsed time into reserved rewards. | Once checkpointed, represented rewards are funded promises that later shortages cannot reduce. |
| Reserve | A balance set aside for one defined obligation. | Pool rewards, POL principal, POL fees, and vault principal use separate reserves. |
| Burn | Sending tokens to the fixed destruction destination so they cannot return to circulation. | Half of Kitchen working capital and 40% of realized fee value support ONI destruction. |
| Basis point | One hundredth of one percent. | 5,000 basis points means exactly 50%. |
| Recenter | Moving liquidity into a newly calculated price range. | The SUSHI/WETH range recenters only when TWAP exits the current range. |
| WETH | ETH represented as an ERC-20 token for use in smart contracts. | Liquidity positions use WETH internally; user-facing ETH redemptions are unwrapped to native ETH. |
Common questions
Does Onigiri create or mint ONI?
No. ONI is launched outside the protocol. Farming rewards are existing ONI transferred into RewardVault and accepted into its tracked inventory. When unreserved inventory is exhausted, new ONI emissions stop.
Where does the yield come from?
There are two sources. Finite ONI emissions come from the pre-funded RewardVault inventory. SUSHI paid to active ONI stakers comes only from realized trading fees earned by permanent SUSHI/WETH liquidity.
Can user deposits be sent through Kitchen?
No. Kitchen accepts the isolated 3% protocol portion, assets redeemed from protocol-owned oniLP fee shares, and explicit donations. Credited user principal is not protocol working capital.
Are reward claims charged the 4% fee?
No. The 1% developer and 3% protocol split applies to farm entry and exit. ONI and SUSHI reward claims are paid without that fee.
What happens when ONI rewards run out?
Only new ONI accrual stops. ONI already reserved by earlier checkpoints remains claimable, credited principal remains withdrawable, and fee-driven Kitchen and SUSHI revenue operations continue.
Why can the displayed reward rate change?
Each pool uses a smooth curve based on its current total stake. More participation raises the pool's total emission rate toward its fixed ceiling, while also spreading rewards across more stake. The rate is not a fixed promise to each deposited unit.
Why do only ONI stakers receive SUSHI?
The realized-fee flywheel assigns its 10% holder portion specifically to active ONI stake. ETH and oniLP stakers receive finite ONI emissions but do not share that SUSHI index.
What if there are SUSHI rewards but no ONI stakers?
The SUSHI remains queued rather than being lost or redirected. Once ONI stake exists, a permissionless distribution call can add the queued amount to the ONI farm's SUSHI reward index.
Is oniLP the same as a Sushi V3 NFT?
No. OniEthLiquidityVault manages the canonical concentrated-liquidity position and issues divisible ERC-20-style oniLP shares over its complete value. Users can transfer or stake those fungible shares without handling the underlying position directly.
Can a maintenance caller choose a different pool or price range?
No. Permissionless callers decide only whether to start eligible work. Assets, pools, routes, fee tiers, price windows, range width, range formula, execution bounds, and recipients are fixed by the deployed contracts.
Can protocol-owned SUSHI/WETH liquidity be withdrawn?
No external removal or sweep path exists. Recentring may remove assets from an old range only as part of placing the separately accounted principal into the next deterministic range.
What does pausing change?
Pausing stops new stakes. It does not disable withdrawals or reward claims, so the pause mechanism cannot turn into a principal lock.