KerfOverview
What Kerf is, the nine contracts and four services that make it, and how they call each other.
Kerf is one venue on Robinhood Chain where an LP position is something you can trade and a trade is something that earns. Nine contracts turn one token into a managed Uniswap position, a limit order that earns while it waits, a vault, a hedged vault or a dated note; four services put a chart, a portfolio and a perp venue in front of them. Nothing is upgradeable, no admin function reaches a user's position, and the two keys a server holds are named in Hedged vaults and Perps via Lighter.
What it is
Two halves were cut together to make it.
The liquidity half is LP management on Uniswap v3 and v4: an atomic swap-and-mint zap that takes one token and gives back a position, three range presets, permissionless harvest and rebalance under a policy the owner sets, fee-earning limit orders, a Trending / Established screener, and ERC-4626 vaults over single pools - plain, hedged and structured.
The trading half is a terminal: Lighter perps with USDG collateral, spot through the Universal Router, email login with embedded wallets, a portfolio with LP metrics, and a Theses feed where a position carries the argument for it.
Kerf keeps both halves and wires them to each other. The chart you draw a range on is the chart you buy from. The vault you deposit into shorts the same asset it LPs. The token you track on /launch becomes a vault you can deposit into on /yield.
The shape of the system
On chain, every contract is non-upgradeable, every external mutator carries a reentrancy guard, every state change emits an event, and every reference to a Uniswap contract is immutable and set at construction. The web app writes to the chain directly: chain guard, eth_call simulation, wallet confirm, send, then a refetch of the indexer at 1.5, 4 and 10 seconds. It reads everything else from the API.
Off chain there are four processes:
| Service | Runtime | One job |
|---|---|---|
| Indexer | Ponder 0.16 | Folds Uniswap and Kerf events into tables and serves them over GraphQL to the API, and only to the API. |
| API | Fastify, Postgres | /radar, /portfolio, /theses, /vaults, /launch, market data with fallbacks, the perp venue proxy, points and referrals. |
| Bots | inside the API process, opt-in by env | A keeper that harvests, rebalances and fills; a hedger that sizes each hedged vault's short and reports it; a graduator that tracks and graduates tokens. |
| Signer | FastAPI, Python | Holds each user's Lighter order key, Fernet-encrypted, and signs orders. It has no code path that submits a withdrawal. |
Everything the API and the bots compute is pure TypeScript in @kerf/core - tick maths, range shapes, zap maths, impermanent loss, APR, the basis signal, the LP delta, the keeper policy, the payoff curves - tested against fixtures the Solidity exports, so a number on a card is the number the contract will enforce.
The contracts
| Contract | One job |
|---|---|
KerfZapV3 / KerfZapV4 | One token in, one position out. Skims 25 bps, swaps the excess side, mints, refunds the dust. Holds nothing between calls. |
RangeOrders | A single-sided position parked on one side of the price: a limit order that collects swap fees until the price crosses it. Anyone may fill; only the owner may cancel. |
PositionKeeper | Lets anyone harvest or rebalance an enrolled position under rules only its owner can set, for a bounty the owner also sets. |
LPVault | An ERC-4626 vault over one Uniswap v3 range, priced behind a TWAP guard, capped for the beta, harvested and rebalanced permissionlessly. |
HedgedLPVault | An LPVault whose price exposure is shorted on Lighter by a hedger key that can fund and report but never withdraw. |
StructuredVault | A dated note: an LP sleeve plus a long perp sleeve (Income) or a T-bill sleeve (Protected), unwound to the asset at maturity. |
VaultFactory | Deploys the three vault kinds as EIP-1167 clones and initialises each in the same transaction. Its list is a list, not an endorsement. |
LaunchPipeline | track a token's first pool, graduate it into a vault once it is three days old and deep enough. |
PreMarketPerp | A constant-product virtual AMM for tokens no venue lists: USDG margin, 3x, an insurance fund, and a documented way of socialising bad debt. |
FeeRouter + ReferralRegistry | Every protocol fee lands in one place and splits 20% to the user's referrer. |
Locked decisions
These do not change without a new deployment:
- Chain: Robinhood Chain, id 4663, and no other.
- No token. There is a referral registry and an off-chain points ledger. Nothing is promised about either.
- Non-custodial everywhere except the Lighter order key, which can trade an account and cannot withdraw from it.
- The beta caps are 5 WETH and 15 000 USDG per vault and are immutable once a vault exists; raising one means deploying a new vault.
- Every contract is non-upgradeable and has no admin function that touches a user position.
- Fees: 25 bps on a zap or a spot swap, 10% of earned fees on a harvest, never a fee on principal. The whole table is in Fees & referrals.
How to read these docs
Chapters 02 to 04 follow one token from the zap to a managed position. Chapters 05 to 07 are the vaults, from the plain one to the dated notes, and 06 is where the one trust assumption lives. Chapters 08 and 09 are the two perp venues - the one Kerf runs and the one it is a client of. Chapter 10 is the off-chain layer, 11 is the money, and 12 and 13 are for whoever deploys or reviews the system.
Every diagram is generated from data in the repository, so a node label matches a function, a struct field or a constant you can grep for.
contracts/src/the nine contracts and their librariespackages/core/src/the pure maths every service sharesdocs/superpowers/specs/2026-09-06-kerf-design.mdthe locked design decisions