Whitepaper · v1.0

Liquid yield and guarded markets

How Lunar turns a concentrated liquidity position into a fungible claim, and how it routes crypto and tokenized equities through one execution path that carries a price floor into every pool it touches.

1. Abstract

A concentrated liquidity position is productive capital that behaves like an illiquid one. It earns a share of every swap that crosses its range, and it cannot be sent, sold or borrowed against without first being torn down. Lunar removes that trade off. A position is held by a vault and represented by a fungible ERC-20 called a YieldShare: the fees keep accruing to the pool while the claim on them moves freely through the rest of DeFi.

The second half of the protocol is execution. Crypto and tokenized equities on Robinhood Chain settle through the same router, along a route chosen by walking real pool state rather than by consulting a price feed, and every hop of that route carries a minimum price that the router itself enforces.

Lunar is non custodial. It never holds keys, never takes deposits and cannot move funds. The protocol produces calldata; a wallet decides whether that calldata is ever signed.

2. The problem

Concentrated liquidity made market making capital efficient and made positions awkward to own. Three consequences follow, and they compound:

  • A position is not fungible. It is an NFT describing one pool, one fee tier and one tick range. Two positions in the same pool are different objects. Nothing built for ERC-20 can hold it.
  • Exiting is destructive. To free the capital you burn the position, which forfeits the range you had chosen and pays gas twice, once to leave and once to come back.
  • The yield is trapped inside. Fees accumulate in the position rather than arriving as an asset. They cannot be spent, lent or used as collateral until the position is unwound.

The result is capital that is technically working and practically frozen. Every strategy built on top of it inherits that constraint.

3. Design goals

Four constraints shaped everything that follows.

  1. Read, never assume. Prices, depth, routes and returns are derived from chain state at the moment they are shown. No cached quote is presented as a live one.
  2. The user keeps custody. No contract in the system takes discretionary control of a balance, and no approval is granted without a scope and an expiry.
  3. Failure should be cheap. A trade that cannot meet its price is rejected before it is offered, and rejected again by the router if conditions move between signing and inclusion.
  4. One surface for two asset classes. Crypto and tokenized equities differ in what they represent, not in how they settle. They share the pools, the router and the interface.

4. YieldShares

A YieldShare is a fungible ERC-20 issued against a vault owned liquidity position. Depositing both sides of a supported pair mints shares in proportion to the value added; burning shares returns the underlying reserves plus the fees earned while those shares were outstanding.

Because the claim is fungible, everything ERC-20 tooling already does becomes available to a liquidity provider: transfer it, quote it on an order book, post it as collateral, wrap it in a strategy. The position never moves. Only the claim does.

Range management sits inside the vault rather than in the provider's wallet. A programmable hook adjusts the range as price travels, so the depth stays where trading actually happens without the holder paying gas for each rebalance or watching for a broken range.

5. Vault accounting

A vault tracks three quantities: the reserves it controls, the fees the position has collected, and the supply of shares outstanding. Net asset value per share is the first two divided by the third, and it is computed from the pool rather than reported by the vault.

This matters for a specific reason. A vault that publishes its own performance can be wrong in its own favour. A vault whose NAV is reconstructed from feeGrowthGlobal0X128, feeGrowthGlobal1X128 and the position's liquidity cannot: anyone can recompute the same number from the same public state and get the same answer.

Deposits and withdrawals price against that NAV, so joining or leaving does not dilute the holders who stayed.

6. Measuring yield

Reported APR is measured, not modelled. Each pool exposes two monotonic accumulators recording fee growth per unit of liquidity for each token. Sampling those accumulators at two moments gives exactly what the pool paid its liquidity across that interval: 

feesEarned = (feeGrowthGlobal_t1 - feeGrowthGlobal_t0) * liquidity / 2^128
apr        = feesEarned / positionValue * (yearMs / elapsedMs)

No volume assumption, no extrapolation from a single trade, no incentive schedule dressed up as yield. The figure answers one narrow question honestly: what did this liquidity actually collect over this window.

The trade off is that a measurement needs time. Robinhood Chain prunes historical state after a few thousand blocks, so the accumulators cannot be read retroactively; they have to be sampled forward. Until a pool has been observed long enough, the interface says it is sampling rather than inventing a number to fill the column.

7. Routing

A quote is produced by simulating the swap against real pool state. For each candidate pool the simulation walks initialised ticks from the current price, consuming input and crossing liquidity boundaries exactly as the pool contract would, until the input is exhausted or the pool runs out of usable depth.

Every fee tier is tried for the direct pair, plus two hop routes through the chain's two natural intermediaries: the dollar asset and wrapped ether. The route with the best output wins. Because the walk is a real simulation rather than a spot price multiplication, the quoted output already contains the price impact of the size being traded, and quoting a larger trade correctly returns a worse price.

8. The per hop floor

A conventional swap protects the trade with one number: the minimum total output. That single check is satisfiable by a route in which one hop is executed at a terrible price and another compensates, which is precisely the shape a sandwich takes on a multi hop path.

The router on Robinhood Chain accepts a stronger commitment. Alongside the minimum output, its V3_SWAP_EXACT_IN command takes an array of per hop minimum prices, each scaled by 1036: 

V3_SWAP_EXACT_IN(
  address  recipient,
  uint256  amountIn,
  uint256  amountOutMin,
  bytes    path,
  bool     payerIsUser,
  uint256[] minHopPriceX36   // one floor per hop
)

Lunar derives each floor from the simulated price of that hop, relaxed by the slippage tolerance, and the router reverts if any single hop clears below its floor. An adversary who reorders the block cannot hide a bad leg behind a good one, because each leg is checked on its own.

The floors are shown in human units before signing, so the guarantee being accepted is legible rather than implied.

9. Approvals

Allowances are the quietest risk in DeFi: an unlimited approval granted once outlives the trade, the session and often the protocol. Lunar uses a two step scoped model instead.

A token is approved to the canonical permission contract, which then issues the router a spending allowance carrying both an amount and an expiry. Once that expiry passes the permission lapses on its own. No standing claim survives a trade that has already settled.

10. Tokenized equities

Tokenized equities on Robinhood Chain are ERC-20s that track listed shares and ETFs. Mechanically they are ordinary tokens: they sit in the same pools, quote through the same simulation and settle through the same router. Nothing in the execution path treats them specially.

What differs is that they have an external reference price. Lunar reads the oracle feed alongside the pool price and displays both, together with the premium between them. A pool that has drifted from the reference is a fact worth seeing before trading, not a detail to smooth over.

The same honesty applies to depth. An equity pool with no usable liquidity is shown without a price rather than with a price nobody could actually trade at.

11. Security model

  • Custody. Keys never leave the wallet. The protocol cannot initiate a transfer.
  • Approvals. Scoped by amount and expiry, never unlimited and never open ended.
  • Execution. A minimum output for the trade and a minimum price for every hop inside it.
  • Simulation. Each transaction is estimated against the node before it is offered, so a call that would revert is caught before it costs gas.
  • Verifiability. Every number links to the explorer. Pool state, balances and yield can be recomputed independently from public data.

12. Known limits

Stating these plainly is part of the design.

  • Yield can only be measured forward. The chain prunes historical state, so a newly indexed pool has no APR until it has been sampled, and the interface says so.
  • A listed asset with no liquid pool has no price here. Several listed tokens are in exactly that state today and are shown without one.
  • Per hop floors reduce the value of reordering a trade. They do not make a chain reorder impossible.
  • Tokenized equities carry the credit and redemption terms of their issuer. Lunar prices the token, which is not the same thing as pricing the share behind it.
  • Automated range management improves fee capture. It does not remove impermanent loss, which is a property of providing liquidity rather than of any particular vault.

13. References

The technical documentation carries the contract addresses, the exact calldata layout, the public API and the self hosting instructions. The roadmap records what is live and what is next.

Technical documentation · Roadmap · Terminal

This document describes a protocol and an interface onto public markets. It is not investment advice, and nothing in it is an offer or a solicitation.