Math Utilities

Initialize a fresh curve state

Start with newBondingCurve(global, creator) when you need the starting reserve state implied by the current global config. Supply the intended on-chain creator; the helper does not substitute the Global authority.

const curve = newBondingCurve(global, creator);

This is useful in:

• simulations
• tests
• tooling that needs to reason about a not-yet-created token

Estimate current curve market cap

Estimate market cap directly from reserves and supply:

const marketCap = bondingCurveMarketCap({
  mintSupply: bondingCurve.tokenTotalSupply,
  virtualGorReserves: bondingCurve.virtualGorReserves,
  virtualTokenReserves: bondingCurve.virtualTokenReserves,
});

This is useful for analytics, dashboards and monitoring that need a reserve-derived market cap. It does not select the new independent Curve fees.

Check settled curve accounting

isSettled(bondingCurve) checks completion and four zero recorded reserves. Both withdrawal and migration settle a curve. The helper is pure: it does not fetch accounts or establish where liquidity went.

import { isSettled } from '@dumpster-cash/dumpster-sdk';

const settled = isSettled(bondingCurve);

To establish migration, use the validated pool returned by migration state fetching. Settlement alone does not prove migration.

Quote bonding-curve trades

These helpers use the Curve fee policy and BN integer arithmetic. Amounts and reserves are raw units. They do not mutate supplied amounts, state or configuration.

For token amount A and virtual reserves Vt/Vg:

An explicit default creator omits its component; missing creator evidence rejects. No LP fee or first-buy flag applies. Stored reserves move by principal, not total debit or net payout.

These helpers answer three different questions. Choose the one that matches your workflow.

1. Spend a known amount of GOR and estimate token output

const tokenAmountOut = getBuyTokenAmountFromGorAmount({
  feeConfig,
  bondingCurve,
  amount: gorAmount,
});

This matches the case:

• "I want to spend 250 GOR"

The amount is a trade budget, not a promise to spend all of it. An integer search selects the greatest affordable output within remaining sale inventory. It can leave a remainder; use a buy preview to obtain the actual spend. For valid active state, zero budget or no affordable positive output returns zero. Do not build a zero-token buy from that no-trade result.

2. Target an exact token output and estimate GOR cost

const gorCost = getBuyGorAmountFromTokenAmount({
  feeConfig,
  bondingCurve,
  amount: tokenAmountOut,
});

This matches the case:

• "I want exactly 1,000,000 base units"

The result includes both rounded fees. A positive request above real sale inventory rejects rather than clamping. Quotes support valid zero-fee and aggregate-100% configurations; neither implies a recommended governance setting.

3. Sell a known token amount and estimate GOR back

const gorOut = getSellGorAmountFromTokenAmount({
  feeConfig,
  bondingCurve,
  amount: tokenAmountIn,
});

This matches the case:

• "I want to sell 5,000,000 base units"

The helper floors gross output, deducts the independently rounded fees and returns net GOR. It rejects insufficient recorded real GOR and fee subtraction underflow. A positive token input can legitimately return zero when gross is zero or fees equal gross; this preserves the current curve source, not a requirement to accept a zero minimum.

For a raw-unit example with Vt = Vg = 100, sufficient real inventory/liquidity and rates 950/300: buying 10 costs principal 12 plus fees 2; budget 13 buys 9 for 12 and leaves 1; selling 10 returns gross 9 minus fees 2 = 7. These are arithmetic examples, not token prices.

Quote DumpsterSwap trades

These helpers work directly from pool reserves.

Buy exact output

getAmmBuyQuote(baseReserves, quoteReserves, baseOut) returns the quote input required for a target base output.

const quoteIn = getAmmBuyQuote(
  baseReserves,
  quoteReserves,
  baseAmountOut
);

Sell exact input

getAmmSellQuote(baseReserves, quoteReserves, baseIn) returns the quote output for a known base input.

const quoteOut = getAmmSellQuote(
  baseReserves,
  quoteReserves,
  baseAmountIn
);

LP math

Initial LP supply

calculateInitialLp(baseIn, quoteIn) is useful when previewing pool creation.

const lpSupply = calculateInitialLp(baseIn, quoteIn);

Deposit amounts

calculateDepositAmounts(lpOut, baseReserves, quoteReserves, lpSupply) is useful when a depositor targets a specific LP token output.

const { baseIn, quoteIn } = calculateDepositAmounts(
  lpOut,
  baseReserves,
  quoteReserves,
  lpSupply
);

Withdraw amounts

calculateWithdrawAmounts(lpIn, baseReserves, quoteReserves, lpSupply) is useful when a user burns LP and wants the underlying token outputs.

const { baseOut, quoteOut } = calculateWithdrawAmounts(
  lpIn,
  baseReserves,
  quoteReserves,
  lpSupply
);

MINIMUM_LIQUIDITY is the locked floor used during initial pool creation.