my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	name: pump-bonding-curve
#3	description: "Constant-product AMM bonding curve math for Pump token pricing — buy/sell quoting, fee-aware calculations, market cap computation, tiered fees, ceiling division, virtual vs real reserves, and edge-case handling."
#4	metadata:
#5	openclaw:
#6	homepage: https://github.com/nirholas/pump-fun-sdk
#7	---
#8
#9	# Bonding Curve — Pricing, Quoting & AMM Mathematics
#10
#11	Implement and maintain the constant-product AMM bonding curve math that powers Pump token pricing — including buy/sell quoting, fee-aware calculations, market cap computation, reserve management, and edge-case handling for new, active, and migrated curves.
#12
#13	## Context
#14
#15	Pump tokens are priced using a constant-product bonding curve ($x \times y = k$) where $x$ = virtual SOL reserves and $y$ = virtual token reserves. The bonding curve determines token prices during the pre-graduation phase. Once market cap reaches a threshold, the token "graduates" and migrates to a PumpAMM pool.
#16
#17	## Key Files
#18
#19	- `src/bondingCurve.ts` — all bonding curve math functions (buy/sell quoting, market cap)
#20	- `src/fees.ts` — fee computation (basis points, tiered fees, ceiling division)
#21	- `src/state.ts` — `BondingCurve`, `Global`, `FeeConfig`, `FeeTier` interfaces
#22
#23	## Constant-Product Formula
#24
#25	$$x \times y = k$$
#26
#27	Buy (tokens out for SOL in):
#28	$$\text{tokensOut} = \frac{dx \times Y}{X + dx}$$
#29
#30	Where $dx$ = SOL input (after fees), $X$ = virtual SOL reserves, $Y$ = virtual token reserves.
#31
#32	Sell (SOL out for tokens in):
#33	$$\text{solOut} = \frac{dy \times X}{Y + dy}$$
#34
#35	Where $dy$ = tokens sold, $X$ = virtual SOL reserves, $Y$ = virtual token reserves.
#36
#37	## Fee Stripping
#38
#39	Fees are deducted from the SOL amount before applying the bonding curve formula:
#40
#41	```typescript
#42	inputAmount = (amount - 1) * 10000 / (totalFeeBps + 10000)
#43	```
#44
#45	The `- 1` before fee stripping is intentional to handle rounding edge cases.
#46
#47	## Market Cap Calculation
#48
#49	$$\text{marketCap} = \frac{\text{virtualSolReserves} \times \text{mintSupply}}{\text{virtualTokenReserves}}$$
#50
#51	Where `mintSupply` defaults to `ONE_BILLION_SUPPLY` ($1 \times 10^{15}$ — 1B tokens with 6 decimals).
#52
#53	## Fee Tiers
#54
#55	When a `FeeConfig` exists, fees are market-cap-dependent. Fee tiers are iterated in reverse order — the first tier from the end whose `marketCapLamportsThreshold ≤ currentMarketCap` is selected.
#56
#57	```typescript
#58	interface FeeTier {
#59	marketCapLamportsThreshold: BN;
#60	fees: { lpFeeBps: BN; protocolFeeBps: BN; creatorFeeBps: BN };
#61	}
#62	```
#63
#64	## Ceiling Division
#65
#66	$$\text{ceilDiv}(a, b) = \frac{a + b - 1}{b}$$
#67
#68	```typescript
#69	function ceilDiv(a: BN, b: BN): BN {
#70	return a.add(b).sub(new BN(1)).div(b);
#71	}
#72	```
#73
#74	## Virtual vs Real Reserves
#75
#76	\| Reserve Type \| Includes \| Used For \|
#77	\|-------------\|----------\|----------\|
#78	\| `virtualSolReserves` \| Real SOL + protocol-added virtual offset \| AMM formula calculation \|
#79	\| `virtualTokenReserves` \| Real tokens + virtual offset \| AMM formula calculation \|
#80	\| `realTokenReserves` \| Actual tokens available \| Buy output cap \|
#81	\| `realSolReserves` \| Actual SOL deposited \| Withdrawal limit \|
#82
#83	## Edge Cases
#84
#85	\| Case \| Behavior \|
#86	\|------\|----------\|
#87	\| Zero amount \| Returns `BN(0)` \|
#88	\| Migrated curve (`complete === true`, zero reserves) \| Returns `BN(0)` \|
#89	\| Null bonding curve \| Creates a fresh curve via `newBondingCurve(global)` \|
#90	\| Tokens exceed real reserves \| Caps at `realTokenReserves` \|
#91	\| Creator fee \| Only charged if `bondingCurve.creator != PublicKey.default` or it's a new curve \|
#92
#93	## BondingCurve State
#94
#95	```typescript
#96	interface BondingCurve {
#97	virtualTokenReserves: BN;
#98	virtualSolReserves: BN;
#99	realTokenReserves: BN;
#100	realSolReserves: BN;
#101	tokenTotalSupply: BN;
#102	complete: boolean; // true = graduated to AMM
#103	creator: PublicKey;
#104	isMayhemMode: boolean;
#105	}
#106	```
#107
#108	## Patterns to Follow
#109
#110	- All amounts use `BN` (bn.js) for arbitrary-precision integer arithmetic — never use JavaScript `number`
#111	- Fee amounts are in basis points (1 bps = 0.01%, 10,000 bps = 100%)
#112	- Always deduct fees before applying the AMM formula, not after
#113	- Use ceiling division (`ceilDiv`) for fee computation to ensure the protocol never loses dust
#114	- Quote functions are pure — no network calls, no side effects, no mutable state
#115	- Always check `bondingCurve.complete` before building trade instructions
#116
#117	## Common Pitfalls
#118
#119	- Confusing virtual reserves (includes virtual offset) with real reserves (actual amounts)
#120	- Not accounting for fees when quoting — raw quote functions give different results than fee-aware ones
#121	- Trying to trade on a graduated curve (`complete === true`) will fail on-chain
#122	- Fee tiers iterate in reverse order — not forward
#123	- Market cap calculation uses `mintSupply` not `tokenTotalSupply`
#124	- The fee stripping formula subtracts 1 from the amount first — this is intentional
#125	- `getBuySolAmountFromTokenAmountQuote` adds `+ 1` to the result to ensure sufficient SOL
#126
#127

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public