Search Apps Documentation Source Content File Folder Download Copy Actions Download State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

v0 source pure

Package curve is a linear, one-way bonding curve for issuing a token against a reserve: price rises linearly with the...

Overview

Package curve is a linear, one-way bonding curve for issuing a token against a reserve: price rises linearly with the position on the curve, and the cost of minting is the exact integral, computed in 128-bit so it never overflows and never issues a coin for less than its backing.

Why a reciprocal slope

The marginal price is p(s) = s/D — a RECIPROCAL denominator D, not a numerator slope. That is not cosmetic. The cost of moving from s0 to s1 is the integral (s1²−s0²)/(2D). With a numerator slope k the product k·(s1²−s0²) can exceed 2^128 for a realistic k at a large supply, and the single 128-bit multiply overflows. As 1/D the numerator is only s1²−s0², at most cap² which for a cap near 9.2e14 is about 2^100 — always inside 128 bits — and D sits safely in the divisor. D is chosen from economics: larger D is a gentler curve.

No coin is ever minted below its backing

Two rounding rules, and one belt-and-suspenders check, guarantee it:

  • Cost rounds UP. The buyer pays at least the integral, so backing (the sum of integrals) never exceeds treasury (the sum charged).
  • Minted rounds DOWN. It floors the number of coins a payment buys — but it does not trust the square root. It uses isqrt only for a CANDIDATE, then corrects ±1 against the canonical Cost, so an off-by-one in the root can never over-issue. This re-check is mandatory, not optional.

A value, not an object

A Curve is immutable configuration (the slope denominator and the position cap); it holds no mutable state and is never a heap object. The CURVE POSITION — how far up the curve issuance has walked — lives in the consuming realm as a monotonic counter it passes in as `from`. Burning or redeeming the token must NOT move that counter back: the curve prices the next mint off total-ever- minted, and walking it backward would let the same region be bought twice.

Functions 1

func New 

1func New(d, cap int64) Curve
source

New builds a curve with reciprocal slope d and position cap. A larger d is a gentler price rise. cap bounds the position so cap² stays inside 128 bits and the token's own supply ceiling is respected.

Types 1

type Curve

struct 
1type Curve struct {
2	d   int64 // reciprocal slope: marginal price p(s) = s/d
3	cap int64 // the highest position issuance may reach
4}
source

Curve is a linear one-way bonding curve. Build it with New.

Methods on Curve

func Backing

method on Curve 
1func (c Curve) Backing(s int64) int64
source

func Cap

method on Curve 
1func (c Curve) Cap() int64
source

func Cost

method on Curve 
1func (c Curve) Cost(from, delta int64) (coin int64, ok bool)
source

Cost is the coin a buyer must pay to move the position from `from` to `from+delta`, the integral of the price over that span, ROUNDED UP. ok is false when the move would pass the cap or the cost would not fit in an int64 (only at absurd positions). Minting zero costs zero.

func D

method on Curve 
1func (c Curve) D() int64
source

D and Cap expose the construction parameters.

func Minted

method on Curve 
1func (c Curve) Minted(from, coin int64) (delta, spent int64)
source

Minted is the largest whole number of coins `coin` can buy starting at position `from`, and the coin actually spent on them (≤ coin; the caller keeps or refunds the remainder). It floors: it finds a candidate with a 128-bit integer square root, then corrects ±1 against the canonical Cost, so issued coin is never worth more than what was paid, and it is zero when even one coin costs more than `coin`.

func Price

method on Curve 
1func (c Curve) Price(s int64) int64
source

Price is the marginal price at position s (coin per unit), floor(s/d). Backing is the reserve behind one unit at position s, exactly half the marginal price — the reason every buyer pays about twice the backing of the coin they buy.

Imports 2

  • math/bits stdlib
  • math/overflow stdlib

Source Files 2