How woolfi works.

Every swap routes through the hook's beforeSwap callback. The hook reads two oracle prices and the pool's current ratio, computes the implied drift from fair value, and returns an asymmetric fee. Swaps that move the pool toward fair are discounted below the base fee; swaps that move it away are surcharged. The result is a market force that pulls the pool back to the implied equilibrium without LPs or stakers having to actively manage anything.

The catalog spans stock/USDG, stock/WETH, stock/stock spread, and crypto pools. One hook contract serves all 18; each pool has its own oracles, risk settings, and URU vault. Before launch every pool shows as pre-launch and actions stay disabled. At launch all 18 go live together.

All 18 pools go live together at launch. WETH/USDG and NVDA/USDG are seeded at launch; the rest are open for the first liquidity providers, including one-click migration from Uniswap v3.

Every pool is initialized at a launch price taken from Chainlink, so the first LP deposits at a fair ratio rather than setting the price. A pool with no deposits yet shows a needs liquidity tag: there is nothing to trade against until someone adds liquidity, Zaps in one token, or migrates a v3 position. The terminal lists seeded pools first.

An empty pool has nothing to trade against, so its price stays put while Chainlink moves. The keeper re-syncs every empty pool to the Chainlink price on each run, and anyone can do the same from the Liquidity tab with Sync to Chainlink price: one transaction, gas only, no tokens move. That keeps the first deposit at a fair ratio and stops a stale empty pool from tripping a false structural break.

Connect a Robinhood Chain wallet, select a live pool, approve the token you want to spend, and swap. The hook chooses the fee from the trade's direction and oracle drift; the router enforces your minimum output. A single trade that would push the price more than the hard threshold from Chainlink is rejected; try a smaller amount. Urufu Gemu holders then claim funded rebates from the Rebate tab. Users who want fee income can instead add both pool assets as liquidity or stake URU as risk-bearing underwriting.

Liquidity providers deposit token0 and token1, mint non-transferable LP shares against a WoolFiPositionManager, and collect a share of swap fees in both tokens. They do not bear structural-break risk.

URU underwriters deposit URU into a per-pool vault. They may earn a configured cut of swap fees in the pool assets, but bear structural-break risk: a vault drawdown can fund a rebalance and reduce vault positions pro rata. URU is the underwriting asset; it is not presented as a governance voting token.

Unstaking takes 2 days, then you have 1 day to withdraw before the request lapses and must be made again. Your requested stake stays exposed until it is paid out. Withdrawals also pause while a structural break is being confirmed, or while a price gap past the hard threshold is waiting for the market to reopen, so nobody can leave ahead of the drawdown it may lead to. Governance changes wait 3 days, longer than the unstake cooldown, and cannot touch a pool while its break is pending, so a queued change never lands on stakers who are locked in.

A wallet holding at least one verified Urufu Gemu NFT when its router swap settles earns back 15% of the fee it actually paid, capped at the base fee, in the input token. A corrective trade that paid a discounted fee gets 15% of that discounted fee; surcharges above the base fee are not rebated. Multiple NFTs do not stack the benefit, and the weekly cap is per wallet. Rebates are funded in advance and claimed from the terminal.

Hours are configured per pool. When a stock token's underlying market is closed, WoolFi cannot promise that the spread will converge, so the pool changes behavior:

• Swaps stay open, at a flat symmetric fee. The asymmetric mechanic is paused until reopen.
• Deposits are blocked. The in-band check may rely on a stale underlying-market quote while directional fees are paused.
• Withdrawals stay open the entire time. Existing LPs already committed with a defined risk profile.
• Structural-break detection is paused. The hard-threshold drawdown only runs when prices are live.

Each stock-token pool resumes its active-market behavior according to its configured schedule. WETH/USDG is always open.

Robinhood Stock Tokens are issued by Robinhood Assets (Jersey) Limited (RHJ). They provide economic exposure to referenced securities but not ownership, voting rights, or other shareholder rights. Issuer terms and geographic restrictions apply. WoolFi does not determine eligibility; users must confirm they may hold and trade each token.

If the pool price drifts more than the hard threshold (default 15%) from the Chainlink price, the pool enters a structural break. It happens in two steps so a brief spike cannot cost URU stakers anything:

1. Detected. The hook caches the fair price, admits only corrective swaps, and blocks new deposits. Nothing is drawn from the vault. The terminal shows Break detected: confirming with a countdown, or waiting for market open when the market is closed.
2. Confirmed. After the waiting period (default 1 hour of open-market time, never during the opening stabilization window), anyone can call confirm. If the price is still past the threshold, the URU vault is drawn down once, capped at the pool's drawdown share, to fund the rebalance. If it has recovered, the break simply clears and nothing is taken.
3. Recovered. Once a confirmed pool is back inside its tolerance band, anyone can unlock it. The keeper bot does both calls automatically; governance can also resolve a break directly.

Withdrawals stay open in every state. Separately, every swap in every state is checked: a single trade that would push an in-range pool past the hard threshold is rejected outright.

Already providing liquidity for one of these pairs on Uniswap v3? The Liquidity tab has a Migrate v3 mode. Pick your position and WoolFi's migrator withdraws it, collects its accrued fees, and deposits everything full-range into the matching WoolFi pool in one transaction. Anything the full-range ratio cannot use is refunded to you, and the empty v3 NFT stays in your wallet. You approve the migrator for that one NFT first.

Migration follows the same rules as a normal deposit: the pool must be in band, not in a break, and (for stock pools) the market must be open. Migrating into an empty pool whose price has drifted? Use Sync to Chainlink price first.

The repo ships an open-source arbitrage agent that keeps WoolFi pools close to the price on Uniswap v3 without needing its own capital. It borrows inside a single v4 transaction, trades the WoolFi pool toward fair value (paying the discounted corrective fee), hedges on Uniswap v3, and repays, keeping the difference. If the trade is not profitable the whole transaction reverts.

Anyone can run it. An optional AI layer writes plain-English summaries of each opportunity; it never decides trades. Source and setup ↗

Drift

How far the pool price sits from the Chainlink price, measured in basis points.

Fair value

The price implied by the two Chainlink feeds for the pair; the target the hook pulls the pool toward.

Corrective / Adversarial

A swap that moves the pool toward fair value is corrective and pays a lower fee; one that moves it away is adversarial and pays a higher fee.

Tolerance band

The drift range (default 500 bps either side) inside which the pool charges only the flat base fee.

Hard threshold

The drift level (default 1500 bps) at which the hook declares a structural break.

Structural break

The contained state after a hard-threshold crossing: fair price is cached, only corrective swaps are admitted, new deposits are blocked, withdrawals stay open. It is detected first and confirmed later; see Structural breaks above.

Break confirmation

The second step of a break. After a waiting period of open-market time, anyone can confirm; the URU vault is drawn down only if the price is still past the threshold.

Break guard

A per-swap check: a single trade that would push the pool more than the hard threshold from Chainlink is rejected.

Unseeded pool

A live pool that nobody has deposited into yet. It opens at the Chainlink launch price and waits for its first liquidity provider.

Price sync

Moving an empty pool to the current Chainlink price with the pool aligner. With no liquidity there is nothing to trade against, so it costs only gas. The keeper does it automatically; the Liquidity tab offers it before a first deposit.

Migration

Moving a Uniswap v3 position into a WoolFi pool in one transaction with the v3 migrator.

Timelock

The contract that owns WoolFi's settings. The multisig can only queue a change; it waits 3 days in public before it can run. The emergency pause is the one exception and takes effect instantly.

Stabilization

A short window after the referenced market opens during which asymmetric fees stay off so the first prints can settle.

bps

Basis points. 1 bp = 0.01%, so 100 bps = 1%.

URU

An external token, bought elsewhere, that is staked into per-pool vaults as underwriting capital. It carries no WoolFi governance rights.

Underwriting

Staking URU to backstop a pool in exchange for a share of its swap fees, while accepting drawdown risk if the pool breaks.

Drawdown

The portion of a pool's URU vault (default 20%) used to fund a rebalance when a structural break is confirmed. It happens at most once per break.

Urufu Gemu

An NFT collection. Holding one earns the wallet 15% of the fee it actually paid on each swap, capped at the base fee, funded in advance and capped weekly per wallet.

Zap

Depositing a single token; the zapper swaps half of it through an approved executor so you end up with both pool tokens and LP shares in one transaction.

• PROJECT_SPEC.md·canonical specification↗
• Source on GitHub·contracts + tests↗
• arb-agent·zero-capital arbitrage bot↗