Video · Slides · Demo · Flow diagrams

Anyone who needs committed liquidity during a high-IL window funds a bounty. LPs who stay collect a base reward plus an IL payout proportional to the IL fraction suffered, scaled by rewardAmount.

Impermanent loss is worst when a pool needs liquidity most: at launch, during a depeg, after an exploit, around a token unlock. Fee revenue is thin. Volatility is highest. Rational LPs stay out. SamanaHook makes it rational to stay in by insuring against IL during the commitment window.

In every case: someone with a stake in pool depth funds a bounty, LPs commit capital for a fixed window, and collect a flat rewardAmount plus an IL payout proportional to the IL fraction suffered.

A bounty targets a specific Uniswap v4 pool and commits a reward budget to attract and insure LPs during a defined window. All rewards, insurance payouts, and fees are denominated in a single owner-set bountyToken (e.g. USDC) - no cross-token accounting, no price-oracle dependency.

• createBounty() - create a bounty with reward parameters and an initial budget deposit
• fundBounty() - top up the budget at any time while the bounty is active
• deactivateBounty() - shut down and recover uncommitted budget; already-reserved LP rewards remain claimable

The budget is the net deposit after protocol fee, a single pot of bountyToken that funds both flat rewards and IL insurance payouts. Full-range LPs see two deductions: flat reward at qualification, IL insurance payout at claim. Concentrated LPs see only the flat reward deduction.

Phase 1 - Creation: deposit transferred in; protocol fee deducted upfront; remainder becomes budget. Requires budget >= rewardAmount.

Phase 2 - LP qualifies: when an LP crosses minLiquidity, rewardAmount is deducted from budget and credited to that LP's lpState.pending. lpState.lockupEnd is set. For full-range positions, lpState.entryPrice is snapshotted as the pool's TWAP at that moment; concentrated positions skip the snapshot and receive no IL payout.

Phase 3 - Lockup: budget unchanged. LP holds position and bears IL.

Phase 4 - LP claims: if ilCoverageBps > 0 and the LP holds a full-range position, the IL insurance payout is computed and added to the base reward; the IL portion is deducted from remaining budget, capped at whatever budget is left. A single transfer sends the total (base + payout) to the LP.

Phase 5 - Deactivation: remaining budget refunded to creator. Already-credited lpState.pending balances are not refundable. They belong to qualified LPs and can still be claimed after deactivation.

Example (1000 USDC deposit, no protocol fee, ilCoverageBps = 10000, one LP):

→ Parameter guidance and sizing examples by scenario

→ Bounty creation flow diagram

Per-LP state is stored in lpState(poolId, lp) and contains:

1. Add liquidity to the pool, the hook tracks your net liquidity (adds minus removes)
2. When your net liquidity crosses minLiquidity, the hook credits your lpState.pending, sets your lockupEnd timestamp, and snapshots the TWAP price (30-min default) as your entry price (manipulation-resistant, not the instantaneous spot)
3. Hold through the lockupDuration
4. Call claimReward() to receive your base reward plus any IL insurance payout

→ Qualification flow diagram

Removing liquidity is blocked until your lpState.lockupEnd timestamp passes. Once past it, call claimReward() to pull:

• Base reward: the flat rewardAmount credited at qualification
• IL insurance payout: computed at claim time if ilCoverageBps > 0:

base       = rewardAmount (flat reward credited at qualification)
entrySqrt  = TWAP sqrtPriceX96 at qualification time
exitSqrt   = TWAP sqrtPriceX96 at claimReward() call time
r          = (exitSqrt / entrySqrt)²
IL         = 1 − (2√r / (1 + r))
payout     = min(base × IL × (ilCoverageBps / 10000), remaining budget)

→ Lockup flow diagram · Claim flow diagram

Per-LP, not collective. Two LPs each adding half the threshold don't combine to qualify. This avoids coordination games at the cost of requiring individual minimums.

IL insurance draws from remaining budget. Base reward is committed at qualification. IL insurance payout at claim draws from whatever budget is left.

Pull-payment pattern. Rewards are credited to lpState.pending at qualification and transferred only when the LP calls claimReward(). This avoids reentrancy in hook callbacks and allows claims to succeed even after the bounty is deactivated.

No external price oracle. Both the entry price (snapshotted at qualification) and the exit price (read at claimReward()) are time-weighted averages of the pool's own tick history (twapWindow, default 30 min). No third-party feed means no stale-price risk and no infrastructure dependency. Flash loans cannot sustain a price deviation across multiple blocks, so both measurements are resistant to single-block manipulation.

Single bounty token for rewards and fees. All bounties pay out in one owner-set bountyToken rather than per-bounty reward tokens. This keeps fee accounting trivially correct (no unit mismatch, no oracle), keeps the treasury holding one known liquid asset, and avoids the failure mode where a pool's own new token crashes exactly when IL is highest.

Three options, in increasing order of realism:

1. Local lifecycle test - full lifecycle in a self-contained Foundry test, no setup required.

forge test --match-test test_lifecycle -vv

→ Demo script and expected output

2. Sepolia fork test - same hook deployed against the live Sepolia PoolManager on a fork. Skipped automatically when SEPOLIA_RPC_URL is not set.

SEPOLIA_RPC_URL=https://... forge test --match-contract SamanaHookForkTest -vv

3. Live Sepolia walkthrough - broadcast real transactions against the deployed contracts: bounty creation, LP qualification, lockup reverts, budget exhaustion, and IL insurance payout.

→ Demo instructions

Sender caveat. Hook callbacks receive the router address as sender, not the end-user LP. Lockups and rewards are attributed to the router. Production deployments should encode the real LP address in hookData and read it in the hook callbacks. The current version is correct for single-user routers and direct integrations.

• Pro-rata collective bounties - two LPs each contributing half the liquidity goal split the reward proportionally
• ERC1155 position tokens - lockup metadata travels with the position, enabling secondary markets, delegation, and fractionalization