Bonding Curve — Advanced Internals

Reference for Genesis Bonding Curve swap price formulas, reserve exhaustion handling, and the BondingCurveBucketV2 onchain account structure.

Summary

This page covers implementation-level details for integrators building swap engines, pricing tools, or protocol tooling on top of the Genesis Bonding Curve. For executing swap transactions using the SDK, see Bonding Curve Swap Integration. For indexing events emitted by the program, see Indexing & Events.

• Swap formulas — exact ceil(k / x) buy and sell calculations
• Reverse calculation — computing required input for a desired output
• Reserve exhaustion — how the system clamps and recalculates when supply is near zero
• BondingCurveBucketV2 — full field reference for the onchain account

For the conceptual model, fee structure, and lifecycle overview, see Theory of Operation.

Swap Price Formulas

All swap calculations use the combined reserves:

totalSol    = virtualSol + realSol
totalTokens = virtualTokens + realTokens
k           = totalSol × totalTokens

Buy (SOL in, Tokens out)

inputReserve     = totalSol
outputReserve    = totalTokens

newInputReserve  = inputReserve + amountIn
newOutputReserve = ceil(k / newInputReserve)
tokensOut        = outputReserve - newOutputReserve

Sell (Tokens in, SOL out)

inputReserve     = totalTokens
outputReserve    = totalSol

newInputReserve  = inputReserve + amountIn
newOutputReserve = ceil(k / newInputReserve)
solOut           = outputReserve - newOutputReserve

Ceiling Division

Ceiling division (ceil(k / x)) is used in all swap calculations. This ensures the constant product invariant is never violated:

newInputReserve × (outputReserve − outputAmount) ≥ k

The pool can only gain value through trades, never lose it. Any rounding error accumulates in favor of the pool.

Reverse Calculation: Required Input for a Desired Output

Used internally when clamping reserves at exhaustion — computes exactly how much input is needed to produce a specific output:

newOutputReserve = outputReserve - desiredAmountOut
newInputReserve  = ceil(k / newOutputReserve)
requiredAmountIn = newInputReserve - inputReserve

This is also useful for UX flows where the user specifies a desired token amount and the UI needs to show the exact SOL cost.

Reserve Exhaustion and Clamping

When a swap would produce more output than the curve has available, the system clamps the output and recalculates the input — the transaction does not fail.

Buy Clamping (Token Supply Exhausted)

If tokensOut > baseTokenBalance:

1. Output is capped at baseTokenBalance
2. Required SOL input is recalculated using the reverse formula
3. The buyer pays only for the tokens actually available
4. This final buy also triggers graduation

Sell Clamping (SOL Supply Exhausted)

If the bucket does not hold enough SOL to cover both the gross output and the fees:

1. The system works backwards from the available SOL balance
2. Fees are recalculated on the available amount
3. The seller receives what remains after fees
4. Required token input is recalculated to match via the reverse formula

BondingCurveBucketV2 Account Structure

The BondingCurveBucketV2 account stores all bonding curve state. See the Genesis JavaScript SDK for the full TypeScript type definition.

Core Reserve Fields

Fee Configuration Fields

Swap Condition Fields

BondingCurveBucketV2 Extensions

The bucket includes an extensions block with independently configurable optional features:

Notes

• virtualSol and virtualTokens are set at curve creation and are immutable — they permanently define the price curve shape
• ceil(k / x) division is used in all swap calculations to ensure the pool never loses value; rounding accumulates in favor of the pool
• Graduation fires automatically on full token exhaustion — no separate instruction or crank is required
• The BondingCurveBucketV2 discriminator is unique per account type; the BondingCurveSwapEvent discriminator is always byte 255

Quick Reference