Skip to content Search Apps Documentation Source Content Run Reset Eval Playground File Folder Download Copy Actions State String Boolean Number Struct Map Slice Pointer Function Closure Reference Nil Package Type Interface Unknown

Community realm. Read the code first. Community realm, deployed by its author. Read the code before you interact or send coins.

types.gno

5.26 Kb · 179 lines
  1// Package types holds the value types shared by core, the minters, the
  2// market and the readers. Every type is plain data (no pointers into realm
  3// state), so passing one across a realm boundary hands over a copy and
  4// never a capability.
  5package types
  6
  7import (
  8	"errors"
  9)
 10
 11// State is a collection's lifecycle (design §4.1):
 12//
 13//	Draft -> Scheduled -> Minting -> Closed -> Final
 14//
 15// Scheduled->Minting and Minting->Closed happen by block height; core
 16// reports the effective state and materializes it on the next write.
 17type State int
 18
 19const (
 20	StateDraft State = iota
 21	StateScheduled
 22	StateMinting
 23	StateClosed
 24	StateFinal
 25)
 26
 27func (s State) String() string {
 28	switch s {
 29	case StateDraft:
 30		return "draft"
 31	case StateScheduled:
 32		return "scheduled"
 33	case StateMinting:
 34		return "minting"
 35	case StateClosed:
 36		return "closed"
 37	case StateFinal:
 38		return "final"
 39	}
 40	return "unknown"
 41}
 42
 43// MaxUnitPrice caps every price (ugnot) so price*count and fee math stay
 44// far from int64 overflow: 1e15 ugnot = 1e9 GNOT.
 45const MaxUnitPrice = 1_000_000_000_000_000
 46
 47// Payee receives Bps/10000 of a payment.
 48type Payee struct {
 49	Addr address
 50	Bps  int64
 51}
 52
 53// CollectionSpec is what a minter asks core to create. Payees travel as
 54// "addr:bps,…" strings and are parsed by core, so core never stores a slice
 55// allocated by another realm.
 56type CollectionSpec struct {
 57	Name, Symbol, Description string
 58	EngineID, Params          string
 59	MaxSupply, RoyaltyBps     int64
 60	PrimaryPayees             string
 61	RoyaltyPayees             string
 62}
 63
 64// BeaconCommitted is the platform's commit-reveal beacon as a collection's
 65// randomness source (LaunchSpec.BeaconSource "" means the same).
 66const BeaconCommitted = "committed"
 67
 68// LaunchSpec freezes a collection's sale window and commitments (I-6).
 69//
 70// BeaconSource picks the second entropy source when UseBeacon is set:
 71// "" or BeaconCommitted for the platform beacon's commit-reveal, or the
 72// package path of an admin-approved randomness provider realm (e.g. a drand
 73// relay); it must be "" without UseBeacon.
 74type LaunchSpec struct {
 75	StartHeight, EndHeight int64
 76	RevealWindow           int64 // blocks after close; core bounds it
 77	CreatorCommit          string
 78	UseBeacon              bool
 79	BeaconSource           string
 80}
 81
 82// CollectionInfo is core's typed read model for other realms.
 83type CollectionInfo struct {
 84	ID, Name, Symbol, Description string
 85	Creator                       address
 86	Minter, EngineID, Params      string
 87	State                         State
 88	MaxSupply, Minted, Reserved   int64
 89	StartHeight, EndHeight        int64
 90	RevealDeadline                int64 // 0 before Launch
 91	RoyaltyBps                    int64
 92	Badge                         string // provenance badge once Final
 93}
 94
 95// Fees are the protocol's fee parameters; core enforces hard caps.
 96type Fees struct {
 97	CreateFee    int64 // ugnot per collection
 98	PrimaryBps   int64 // of every primary sale
 99	SecondaryBps int64 // of every market sale
100	Treasury     address
101	EngineCapBps int64 // platform cap on engine-author fees (<= engine.MaxFeeBps)
102}
103
104// Phase kinds.
105const (
106	PhaseAllow  = "allow"
107	PhasePublic = "public"
108)
109
110// Phase is one sale window. A fixed price has StartPrice == FloorPrice and
111// no steps; a Dutch auction starts at StartPrice and drops StepAmount every
112// StepBlocks until FloorPrice (design §4.5). WalletCap counts lifetime
113// mints of the collection (I-9); 0 means no cap.
114type Phase struct {
115	Kind, Set                string
116	StartHeight, EndHeight   int64
117	StartPrice, FloorPrice   int64
118	StepBlocks, StepAmount   int64
119	WalletCap                int64
120}
121
122// Validate checks a phase in isolation; the minter checks the set grammar
123// and how phases relate to each other.
124func (p Phase) Validate() error {
125	switch p.Kind {
126	case PhasePublic:
127		if p.Set != "" {
128			return errors.New("a public phase has no allowlist set")
129		}
130	case PhaseAllow:
131		if p.Set == "" {
132			return errors.New("an allow phase needs a set")
133		}
134	default:
135		return errors.New("phase kind must be allow or public")
136	}
137	if p.StartHeight <= 0 || p.EndHeight < p.StartHeight {
138		return errors.New("phase heights must satisfy 0 < start <= end")
139	}
140	if p.FloorPrice < 0 || p.StartPrice < p.FloorPrice || p.StartPrice > MaxUnitPrice {
141		return errors.New("prices must satisfy 0 <= floor <= start <= MaxUnitPrice")
142	}
143	if p.StartPrice == p.FloorPrice {
144		if p.StepBlocks != 0 || p.StepAmount != 0 {
145			return errors.New("a fixed-price phase has no steps")
146		}
147	} else if p.StepBlocks <= 0 || p.StepAmount <= 0 {
148		return errors.New("a Dutch phase needs positive stepBlocks and stepAmount")
149	}
150	if p.WalletCap < 0 {
151		return errors.New("walletCap must be >= 0")
152	}
153	return nil
154}
155
156// Covers reports whether height h is inside the phase window.
157func (p Phase) Covers(h int64) bool {
158	return h >= p.StartHeight && h <= p.EndHeight
159}
160
161// PriceAt is the unit price at height h:
162//
163//	max(floor, start - floor((h-startH)/stepBlocks) * stepAmount)
164//
165// computed so that no intermediate value can overflow.
166func (p Phase) PriceAt(h int64) int64 {
167	if p.StartPrice == p.FloorPrice || h <= p.StartHeight {
168		return p.StartPrice
169	}
170	steps := (h - p.StartHeight) / p.StepBlocks
171	if steps > (p.StartPrice-p.FloorPrice)/p.StepAmount {
172		return p.FloorPrice
173	}
174	price := p.StartPrice - steps*p.StepAmount
175	if price < p.FloorPrice {
176		return p.FloorPrice
177	}
178	return price
179}