Stonkwell docs

Overview

Stonkwell runs managed liquidity for Equity Tokens on Robinhood Chain. Each Well holds one Equity Token / USDG position on Uniswap v4. You sink USDG, the Well earns swap fees from traders, and 70% of those fees compound back into the Well. The other 30% is spent buying $WELL and burning it.

Every contract is open source and verified. There are no off-chain valuations: Held Value, share prices and collateral values are all computed on-chain from Chainlink prices.

Wells

Sinking into a Well. Deposit USDG and receive Well shares (ERC-4626). Your shares are your portion of the Well's Held Value.
Ranges. A keeper places the Well's balances in a concentrated range around the Chainlink price and re-ranges when price moves. Rebalances revert if the price is stale or the pool has drifted more than 2% from the oracle.
USDG exits. withdraw/redeem pull your slice of the range and sell Equity Token for USDG. The swap must clear within 1% of the oracle price, and you pay that cost, not the holders who stay.
In-kind exits. redeemInKind returns your share of Equity Token and USDG with no swap and no price check. It works while paused, over weekends, and during oracle outages.
Caps. Each Well has a Held Value cap. Launch Wells open at $25,000 each and rise only through the timelock.

Fees, drawdown and retire

Swap fees are collected on every sink, exit and rebalance, and whenever anyone calls harvest.

70% stays in the Well and raises the value of every share.
30% goes to the FeeRouter, which forwards all of it to DrawdownRetire. That contract swaps the fees into $WELL through registered pools, subject to per-run limits and a minimum interval, then burns the $WELL in the same transaction. It has no withdrawal function.
Pointing the FeeRouter anywhere else requires a public 48-hour delay.

Borrow Desk

Each Credit Line is an isolated market for one Well. Lenders supply USDG and earn a variable rate. Borrowers pledge Well shares and borrow USDG against them.

Collateral is valued at the Chainlink price. Pool prices never affect it.
The META Credit Line launches with a 40% max LTV, a 55% liquidation threshold, a 6% liquidation bonus and a 50% close factor.
A single Credit Line may hold at most 30% of a Well's shares as collateral.
Borrowing and liquidation need a fresh price. Repaying is always possible.
Rates follow a kinked curve: 2% base, rising to 8% at 80% utilization, then steeply above that.

Prices and market hours

Equity Token prices come from Chainlink feeds that follow US market hours: 24 hours a day, five days a week, with a 24-hour heartbeat. A price counts as fresh for up to 26 hours. Stonkwell also checks the USDG/USD feed and the Equity Token's corporate-action flag.

When a price is not fresh, sinking, USDG exits, rebalances, borrowing and liquidations pause automatically. In-kind exits and repayments stay open.

Governance and safety

Admin is a 48-hour timelock controlled by a multisig. Only the admin can unpause, raise caps, or change fees, risk limits, feeds and pools.
Guardian is a separate multisig. It can pause, lower caps and halt drawdowns. It cannot unpause, raise limits or move funds.
Keeper rebalances and runs drawdowns within on-chain limits.
No contract has a function that lets any role take user funds.

Glossary

Well: A managed Equity Token / USDG liquidity vault, for example the AMD Well.
Equity Token: A tokenized debt security on Robinhood Chain that tracks a stock or ETF.
Sinking into a Well: Depositing USDG into a Well.
Held Value: The total USDG value of a Well's assets at the oracle price.
Yield Rate: Recent fee income to Well holders, annualized. Historical, not a forecast.
Credit Line / Borrow Desk: Isolated USDG lending markets backed by Well shares.
Programs: Managed allocations built from Wells and Credit Lines.
Drawdown and retire: Spending the protocol fee share on $WELL and burning it.
$WELL: Stonkwell's fixed-supply token.