Glossary

Protocol#

Bonding curve — the BondingCurvePool a launch trades against before it graduates. Prices trades on virtual reserves with a constant product, so it can quote from block one with no deposited liquidity.

Virtual reserves — virtualEthReserve and virtualTokenReserve, the numbers that set the price. They exist only in storage; they are not balances.

Real reserves — realEthReserve and realTokenReserve, the ETH actually held and the curve tokens actually left to sell.

Graduation — the atomic migration from the curve into a JoseonSwap pool, triggered by the buy that sells out the curve allocation.

Launch pair — the token/WETH pair created by a graduation. Only the launch factory can create one, and only the migration manager can seed it.

Plain pair — any other JoseonSwap pair, created permissionlessly. No creator, so LPs keep a larger fee share.

Seed manager — the address permitted to perform a launch pair's first mint. Always the migration manager.

UNSEEDED / OPEN — a launch pair's two states. UNSEEDED blocks swap, burn, skim, and sync; the seeded first mint flips it to OPEN, after which it behaves like any pair.

Permanent locker — PermanentLiquidityLocker, which holds a graduation's initial LP position. It has no withdraw function.

Amounts and units#

WAD — a fixed-point value scaled by 1e18. Prices and progress are WAD, so 1e18 means 100% or one whole unit.

bps — basis points, hundredths of a percent. 10000 bps is 100%, so the 2% curve fee is 200 bps and the 0.30% swap fee is 30.

Base units — the integer form of an amount: wei for ETH, and 1e18 per token. Every API amount is a decimal string in base units, because the values exceed what a JS number can hold.

FDV — fully diluted valuation, price times total supply. Since supply is fixed at 1B with no mint function, FDV and market cap converge as tokens leave the curve.

Lifecycle#

CURVE_ACTIVE — state 0. Trading against the bonding curve.

GRADUATING — state 1. Trading paused mid-migration. One transaction wide.

DEX_ACTIVE — state 2. Trading through JoseonSwapRouter.

Progress — the share of the 800M curve allocation that has sold, WAD-scaled.

willGraduate — the flag quoteBuy returns when your buy would end the curve.

Fees and roles#

Creator — whoever called createToken. Earns 70% of curve fees and, after graduation, 50% of the pair's swap fees.

CTO — a handover of the fee recipient to a new address. Fees already accrued stay with the previous recipient; only later trades accrue to the new one.

Fee recipient — the address in LaunchRegistry.feeRecipientOf(token) that creator fees are paid to. Read at trade time on the curve, at claim time on a pair.

Fee shares — an off-chain split of the creator share across multiple wallets, displayed but not enforced on-chain.

feeTo — the factory address that protocol swap fees are claimed to.

Pull payment — fees accrue in storage and are claimed by a call, rather than being pushed on every trade. Keeps the swap path cheap and free of external calls.

Infrastructure#

GIWA — the OP Stack L2 this runs on. Chain ID 91342 on Sepolia, roughly 1-second blocks.

Flashblocks — GIWA's preconfirmation RPC, ~200ms. Good for optimistic UI, not a substitute for a receipt.

Indexer — the Cloudflare Worker at api.joseon.fun that reads events into D1 and serves the JSON API.

Stack — one complete deployment of all seven contracts. Versions coexist on-chain but the app targets exactly one.

Checkpoint — the persisted block the indexer resumes from, so restarts neither skip nor double-count.