DOCUMENTATION

Lunarray is a two-contract protocol layer attached to a fixed-supply token launched on Pons v2 (Robinhood Chain). It is live from the bonding curve on and keeps running on Uniswap v4 after graduation. It turns the token's creator fees into ETH yield for stakers and into buybacks that pay out bonds.

Overview

• FeeSplitter is the token's creatorFeeRecipient on Pons. Anyone can call harvest(); it claims the accrued ETH and splits it between the treasury and the engine using a share fixed at deploy.
• BondEngine receives the protocol share. Part is streamed to stakers as ETH, part is held as a reserve that buys the token back every epoch on the live market: the Pons curve before graduation, the Uniswap v4 pool after. Bought tokens go to the crypt, which pays bonds.
• Bonds let holders deposit the token when it trades below its moving target and receive a bonus after vesting. The deeper the discount, the larger the bonus.

Lifecycle

1. Deploy FeeSplitter with the treasury address and share (60%).
2. Launch on Pons with creatorFeeRecipient = FeeSplitter and creatorTaxBps = 500. Both the tax and the fact that fees route through the splitter are visible on-chain from block one.
3. Deploy BondEngine right after the launch. It reads the launch record from the Pons factory: the curve address, the pool fee and the tick spacing. The v4 pool id is derived on-chain from that pool key. The deployer wires FeeSplitter.setProtocol(engine) exactly once.
4. Curve phase. Anyone calls start(): the first sample is the curve price and epochs begin. Fees are harvested, stakers earn ETH, and every epoch the engine buys back on the curve. Bonds open after minSamples epochs like on any other market.
5. Graduation. Pons migrates liquidity to Uniswap v4 inside the buy that fills the curve. The engine notices curve.graduated() and reads and buys from the pool from then on. Same sample series, same epoch counter, no restart.
6. Steady state. Every epoch a keeper calls poke(). Stakers accrue ETH, buybacks fill the crypt, bonds mature and are settled in order.

Fee split

Pons charges a base fee on every trade (currently 1%, of which 70% goes to the creator) plus the creator tax chosen at launch and immutable afterwards: 5% for LUNARRAY. All creator proceeds are credited in ETH to the recipient's balance in the Pons FeeEscrow, on the curve and on the pool alike.

Market & oracle

priceSource() tells which market is live: 1 = the Pons curve (until curve.graduated() is true), 2 = the Uniswap v4 pool (once its sqrtPriceX96 is set), 0 = none.

• Curve: price = tokenReserve / quoteReserve from curve.getReserves(), the same pricing reserves (phantom quote included) Pons uses to quote trades.
• Pool: price from sqrtPriceX96 in the Uniswap v4 StateView for the exact pool key Pons created (currency0 = ETH, currency1 = token, fee 0, tick spacing 200, hook = Pons MemeHook).

Either way the value is stored as tokens per ETH once per epoch, in a ring buffer of up to 168 samples (7 days at 1-hour epochs). Graduation does not break the series: the pool opens at the price the curve ended on.

Target is the arithmetic mean of the last window samples. Discount is how far the current spot is below the target: discount = (spotTPE − targetTPE) / spotTPE, where a higher tokens-per-ETH means a cheaper token. When spot is at or above target the discount is zero and bonds are closed.

Bonds

bond(amount, minBonusBps) is available when the engine has at least minSamples samples, entries are not paused, and the discount is above zero.

1. entryBurnBps of the amount is sent to the dead address.
2. The remainder is the principal and goes to the crypt.
3. The payout is principal × (1 + bonus), where bonus = maxBonusBps × min(discount, bandBps) / bandBps.
4. The bond matures after vestEpochs epochs.

Bonds are paid strictly first-in, first-out by settle(n), which anyone can call. A bond is paid when it has matured and the crypt holds at least its payout. If the crypt is short, the queue waits for the next buybacks; nothing is paid out of order.

exit(id) cancels an unsettled bond at any time: the owner gets the principal minus penaltyBps, and the penalty stays in the crypt for the other bondholders.

Buybacks

On every poke() the engine takes releaseBps of its ETH reserve and buys the token on the live market. Tokens received are added to the crypt and counted in totalBoughtBack.

• On the curve: curve.buy(eth, 0, engine). Pons charges its normal fees (the 5% creator tax included, which flows back through the splitter). If the buy is larger than what is left on the curve, Pons fills what it can and refunds the rest in the same transaction; the engine recognises the refund and keeps it in the reserve, it is never counted as new revenue. If the curve rejects the buy for any reason, the epoch still advances and the ETH stays in the reserve (BuybackSkipped).
• On the pool: exact-input swap directly on the Uniswap v4 PoolManager (unlock → swap → settle ETH → take tokens). The Pons hook applies its fees exactly as it would for any trader.

Releasing a fixed fraction per epoch makes the buyback a predictable, continuous bid that cannot be front-run for size: the amount is public before the epoch ends.

Staking

stake(amount) deposits the token; unstake(amount) withdraws it at any time. Rewards are ETH, tracked with a per-share accumulator. earned(user) shows what is claimable, and claimRewards() sends it. Staking never pauses withdrawals: only new deposits can be paused by the guardian. sLUNARRAY is an optional liquid receipt on top: 1:1, transferable, rewards follow the balance.

Idle funds

The crypt and the ETH reserve belong to the protocol, not to any user. If the bond side is never used they would otherwise sit there forever. sweepIdle() lets the guardian move both to the treasury, but only when no bond is outstanding and no bond was opened, settled or exited for 30 days (IDLE_DELAY). The idle clock is public: idleFor().

Keepers

Everything that keeps the protocol moving is permissionless:

# reference keeper (Hardhat project)
ENGINE=0x… SPLITTER=0x… LOOP=1 npx hardhat run scripts/3-start-and-poke.js --network robinhood

Parameters

Changing any parameter requires proposeParams() by the guardian followed by a public executeParams() at least 48 hours later. Bounds are enforced on-chain (for example, entry burn ≤ 10%, penalty ≤ 50%).

Security & governance

• No proxy, no upgrade path. The bytecode you verify is the bytecode that runs forever.
• The token itself is the unmodified Pons launcher token: fixed supply, no tax logic, no owner.
• Reentrancy guards on every state-changing entry point; ETH is only sent via call after state updates. ETH coming back from the curve during a buy is recognised by sender and never split as revenue.
• Dev allocation. The tokens the dev wallet bought at launch sit in DevLock: a time lock with a fixed beneficiary, no owner and no other function. Nothing leaves before unlockAt, and the date can only be extended. The terminal shows the locked share of supply live, read from the lock contract.

Risks

• Bond queue risk. Bond payouts exceed principal. If fee inflows stop and no new bonds are opened, the queue can stall with matured bonds unpaid. exit() is always available at the penalty, subject to crypt liquidity.
• Price risk. Buybacks buy a volatile token. The crypt's ETH value can fall faster than it is refilled.
• Curve risk. On the bonding curve the price only moves with buys and sells on the curve itself; early samples can be far from where the pool eventually opens.
• Oracle risk. The target is a simple moving average of on-chain spot samples. A sustained manipulation over many epochs would move it.
• Smart-contract risk. The code is tested (unit and mainnet-fork) but not audited at the time of writing.
• Platform risk. Fee accrual depends on the Pons escrow, curve and hook contracts, which are outside this protocol's control.

Contracts

FAQ

Why are rewards paid in ETH and not in the token?

Because the fees arrive in ETH and because a reward that does not come from printing the token is the only kind that does not dilute holders.

Does anything happen before graduation?

Everything does. The engine starts on the curve: fees are harvested, stakers earn ETH, the reserve buys back on the curve every epoch and bonds open after the minimum number of samples. Graduation only changes where the price is read and where the buyback is executed.

Who decides when to pause?

The guardian address, and only for new entries. Anyone can always withdraw. A pause expires by itself after at most 7 days unless renewed.

Can the creator tax change?

No. It is set once in the Pons launch transaction and is immutable. The fee recipient can only be changed through the Pons factory with a 3-day timelock, which is public.

What if nobody ever bonds?

Stakers keep earning regardless. The crypt and the reserve would idle; after 30 days without any bond the guardian can move them to the treasury with sweepIdle(). Nothing that belongs to a user is part of that.