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}