store.gno

  1package protocol_fee
  2
  3import (
  4	"errors"
  5
  6	bptree "gno.land/p/nt/bptree/v0"
  7	ufmt "gno.land/p/nt/ufmt/v0"
  8
  9	"gno.land/p/gnoswap/gnsmath/v1"
 10	"gno.land/p/gnoswap/store/v1"
 11	"gno.land/p/gnoswap/utils/v1"
 12)
 13
 14type StoreKey string
 15
 16// String returns the textual store-key value.
 17//
 18// Returns:
 19//   - key: The string representation of the StoreKey.
 20func (s StoreKey) String() string {
 21	return string(s)
 22}
 23
 24const (
 25	// By default, devOps will get 0% of the protocol fee (which means gov/staker will get 100% of the protocol fee)
 26	// This percentage can be modified through governance.
 27	StoreKeyDevOpsPct StoreKey = "devOpsPct"
 28
 29	// accuToGovStaker tracks the cumulative amount allocated to GovStaker,
 30	// including allocations that are still pending distribution.
 31	StoreKeyAccuToGovStaker StoreKey = "accuToGovStaker" // tokenPath -> amount
 32	// accuToDevOps tracks the cumulative amount allocated to DevOps,
 33	// including allocations that are still pending distribution.
 34	StoreKeyAccuToDevOps StoreKey = "accuToDevOps" // tokenPath -> amount
 35
 36	// Distribution-history trees track cumulative amounts actually transferred.
 37	StoreKeyDistributedToGovStakerHistory StoreKey = "distributedToGovStakerHistory" // tokenPath -> amount
 38	StoreKeyDistributedToDevOpsHistory    StoreKey = "distributedToDevOpsHistory"    // tokenPath -> amount
 39
 40	// reservedTokens tracks token paths collected but not yet distributed.
 41	StoreKeyReservedTokens StoreKey = "reservedTokens"
 42
 43	// accrualEpoch, accrualBuckets and accrualPendingTokens track the gov/staker share
 44	// per token path and accrual epoch until gov/staker folds it into its accumulator.
 45	StoreKeyAccrualEpoch         StoreKey = "accrualEpoch"
 46	StoreKeyAccrualBuckets       StoreKey = "accrualBuckets"       // tokenPath -> (epoch -> amount)
 47	StoreKeyAccrualPendingTokens StoreKey = "accrualPendingTokens" // tokenPath -> true
 48)
 49
 50const (
 51	defaultDevOpsPct = int64(0)
 52	errSpoofedRealm  = "rlm does not match the current crossing frame"
 53)
 54
 55// NewBPTreeN allocates a BP-tree under /r/gnoswap/protocol_fee's realm context
 56// so tree.Set leaf-slot writes clear the readonly-taint gate regardless of
 57// which realm (protocol_fee/v1, mock, tests) calls Set. Callers must allocate
 58// protocol_fee trees through here rather than bptree.NewBPTreeN directly.
 59//
 60// Parameters:
 61//   - fanout: Branching factor passed to the BP-tree constructor.
 62//
 63// Returns:
 64//   - tree: A new BP-tree configured with fanout and allocated in the protocol-fee realm context.
 65func NewBPTreeN(fanout int) *bptree.BPTree {
 66	return bptree.NewBPTreeN(fanout)
 67}
 68
 69type protocolFeeStore struct {
 70	kvStore store.KVStore
 71}
 72
 73// handle devOpsPct store data
 74//
 75// Returns:
 76//   - exists: True when the DevOps percentage store key is present in the KV store.
 77func (s *protocolFeeStore) HasDevOpsPctStoreKey() bool {
 78	return s.kvStore.Has(StoreKeyDevOpsPct.String())
 79}
 80
 81// InitializeDevOpsPct creates the DevOps allocation percentage entry with its default value.
 82//
 83// Parameters:
 84//   - _: Crossing discriminator for the store operation; pass 0.
 85//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
 86//
 87// Returns:
 88//   - err: Nil when the key is initialized; otherwise the current-realm or KV-store write error.
 89func (s *protocolFeeStore) InitializeDevOpsPct(_ int, rlm realm) error {
 90	if !rlm.IsCurrent() {
 91		return errors.New(errSpoofedRealm)
 92	}
 93
 94	return s.kvStore.Set(0, rlm, StoreKeyDevOpsPct.String(), defaultDevOpsPct)
 95}
 96
 97// GetDevOpsPct reads the persisted DevOps allocation percentage.
 98//
 99// Returns:
100//   - pct: The stored DevOps allocation percentage in basis points; the method panics if the key is missing or cannot be decoded as int64.
101func (s *protocolFeeStore) GetDevOpsPct() int64 {
102	devOpsPct, err := s.kvStore.GetInt64(StoreKeyDevOpsPct.String())
103	if err != nil {
104		panic(err)
105	}
106
107	return devOpsPct
108}
109
110// SetDevOpsPct persists the DevOps allocation percentage.
111//
112// Parameters:
113//   - _: Crossing discriminator for the store operation; pass 0.
114//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
115//   - pct: DevOps share of protocol fees in basis points; the state layer constrains this value to 0 through 10000 before calling the store.
116//
117// Returns:
118//   - err: Nil when the percentage is persisted; otherwise the current-realm or KV-store write error.
119func (s *protocolFeeStore) SetDevOpsPct(_ int, rlm realm, pct int64) error {
120	if !rlm.IsCurrent() {
121		return errors.New(errSpoofedRealm)
122	}
123
124	return s.kvStore.Set(0, rlm, StoreKeyDevOpsPct.String(), pct)
125}
126
127// handle accuToGovStaker store data
128//
129// Returns:
130//   - exists: True when the cumulative Gov/Staker allocation tree key is present in the KV store.
131func (s *protocolFeeStore) HasAccuToGovStakerStoreKey() bool {
132	return s.kvStore.Has(StoreKeyAccuToGovStaker.String())
133}
134
135// InitializeAccuToGovStaker creates the cumulative Gov/Staker allocation tree.
136//
137// Parameters:
138//   - _: Crossing discriminator for the store operation; pass 0.
139//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
140//
141// Returns:
142//   - err: Nil when the tree is initialized; otherwise the current-realm or KV-store write error.
143func (s *protocolFeeStore) InitializeAccuToGovStaker(_ int, rlm realm) error {
144	if !rlm.IsCurrent() {
145		return errors.New(errSpoofedRealm)
146	}
147
148	return s.kvStore.Set(0, rlm, StoreKeyAccuToGovStaker.String(), NewBPTreeN(16))
149}
150
151// GetAccuToGovStaker reads the cumulative Gov/Staker allocation tree.
152//
153// Returns:
154//   - tree: The BP-tree mapping token paths to cumulative amounts; the method panics if the store value is absent or has the wrong type.
155func (s *protocolFeeStore) GetAccuToGovStaker() *bptree.BPTree {
156	accuToGovStaker, err := s.kvStore.GetBPTree(StoreKeyAccuToGovStaker.String())
157	if err != nil {
158		panic(err)
159	}
160
161	return accuToGovStaker
162}
163
164// GetAccuToGovStakerItem reads one token's cumulative Gov/Staker allocation.
165//
166// Parameters:
167//   - tokenPath: Token path whose cumulative allocation should be looked up.
168//
169// Returns:
170//   - amount: The stored cumulative allocation for tokenPath, or zero when no entry exists.
171//   - found: True when tokenPath has an entry in the allocation tree; false when it is absent.
172func (s *protocolFeeStore) GetAccuToGovStakerItem(tokenPath string) (int64, bool) {
173	accuToGovStaker, err := s.kvStore.GetBPTree(StoreKeyAccuToGovStaker.String())
174	if err != nil {
175		panic(err)
176	}
177
178	result := accuToGovStaker.Get(tokenPath)
179	if result == nil {
180		return 0, false
181	}
182
183	amount, ok := result.(int64)
184	if !ok {
185		panic(ufmt.Errorf("failed to cast result to int64: %T", result))
186	}
187
188	return amount, true
189}
190
191// SetAccuToGovStakerItem updates one token's cumulative Gov/Staker allocation.
192//
193// Parameters:
194//   - _: Crossing discriminator for the store operation; pass 0.
195//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
196//   - tokenPath: Token path whose cumulative allocation is replaced.
197//   - amount: Cumulative Gov/Staker allocation to store for tokenPath.
198//
199// Returns:
200//   - err: Nil when the allocation tree is persisted; otherwise the current-realm, tree-read, or KV-store write error.
201func (s *protocolFeeStore) SetAccuToGovStakerItem(_ int, rlm realm, tokenPath string, amount int64) error {
202	if !rlm.IsCurrent() {
203		return errors.New(errSpoofedRealm)
204	}
205
206	accuToGovStaker, err := s.kvStore.GetBPTree(StoreKeyAccuToGovStaker.String())
207	if err != nil {
208		return err
209	}
210
211	accuToGovStaker.Set(tokenPath, amount)
212
213	return s.kvStore.Set(0, rlm, StoreKeyAccuToGovStaker.String(), accuToGovStaker)
214}
215
216// handle accuToDevOps store data
217//
218// Returns:
219//   - exists: True when the cumulative DevOps allocation tree key is present in the KV store.
220func (s *protocolFeeStore) HasAccuToDevOpsStoreKey() bool {
221	return s.kvStore.Has(StoreKeyAccuToDevOps.String())
222}
223
224// InitializeAccuToDevOps creates the cumulative DevOps allocation tree.
225//
226// Parameters:
227//   - _: Crossing discriminator for the store operation; pass 0.
228//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
229//
230// Returns:
231//   - err: Nil when the tree is initialized; otherwise the current-realm or KV-store write error.
232func (s *protocolFeeStore) InitializeAccuToDevOps(_ int, rlm realm) error {
233	if !rlm.IsCurrent() {
234		return errors.New(errSpoofedRealm)
235	}
236
237	return s.kvStore.Set(0, rlm, StoreKeyAccuToDevOps.String(), NewBPTreeN(16))
238}
239
240// GetAccuToDevOps reads the cumulative DevOps allocation tree.
241//
242// Returns:
243//   - tree: The BP-tree mapping token paths to cumulative amounts; the method panics if the store value is absent or has the wrong type.
244func (s *protocolFeeStore) GetAccuToDevOps() *bptree.BPTree {
245	accuToDevOps, err := s.kvStore.GetBPTree(StoreKeyAccuToDevOps.String())
246	if err != nil {
247		panic(err)
248	}
249
250	return accuToDevOps
251}
252
253// GetAccuToDevOpsItem reads one token's cumulative DevOps allocation.
254//
255// Parameters:
256//   - tokenPath: Token path whose cumulative allocation should be looked up.
257//
258// Returns:
259//   - amount: The stored cumulative allocation for tokenPath, or zero when no entry exists.
260//   - found: True when tokenPath has an entry in the allocation tree; false when it is absent.
261func (s *protocolFeeStore) GetAccuToDevOpsItem(tokenPath string) (int64, bool) {
262	accuToDevOps, err := s.kvStore.GetBPTree(StoreKeyAccuToDevOps.String())
263	if err != nil {
264		panic(err)
265	}
266
267	result := accuToDevOps.Get(tokenPath)
268	if result == nil {
269		return 0, false
270	}
271
272	amount, ok := result.(int64)
273	if !ok {
274		panic(ufmt.Errorf("failed to cast result to int64: %T", result))
275	}
276
277	return amount, true
278}
279
280// SetAccuToDevOpsItem updates one token's cumulative DevOps allocation.
281//
282// Parameters:
283//   - _: Crossing discriminator for the store operation; pass 0.
284//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
285//   - tokenPath: Token path whose cumulative allocation is replaced.
286//   - amount: Cumulative DevOps allocation to store for tokenPath.
287//
288// Returns:
289//   - err: Nil when the allocation tree is persisted; otherwise the current-realm, tree-read, or KV-store write error.
290func (s *protocolFeeStore) SetAccuToDevOpsItem(_ int, rlm realm, tokenPath string, amount int64) error {
291	if !rlm.IsCurrent() {
292		return errors.New(errSpoofedRealm)
293	}
294
295	accuToDevOps, err := s.kvStore.GetBPTree(StoreKeyAccuToDevOps.String())
296	if err != nil {
297		return err
298	}
299
300	accuToDevOps.Set(tokenPath, amount)
301
302	return s.kvStore.Set(0, rlm, StoreKeyAccuToDevOps.String(), accuToDevOps)
303}
304
305// handle distributedToGovStakerHistory store data
306// HasDistributedToGovStakerHistoryStoreKey reports whether the Gov/Staker distribution-history tree exists.
307//
308// Returns:
309//   - exists: True when the Gov/Staker distribution-history tree key is present in the KV store.
310func (s *protocolFeeStore) HasDistributedToGovStakerHistoryStoreKey() bool {
311	return s.kvStore.Has(StoreKeyDistributedToGovStakerHistory.String())
312}
313
314// InitializeDistributedToGovStakerHistory creates the Gov/Staker distribution-history tree.
315//
316// Parameters:
317//   - _: Crossing discriminator for the store operation; pass 0.
318//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
319//
320// Returns:
321//   - err: Nil when the history tree is initialized; otherwise the current-realm or KV-store write error.
322func (s *protocolFeeStore) InitializeDistributedToGovStakerHistory(_ int, rlm realm) error {
323	if !rlm.IsCurrent() {
324		return errors.New(errSpoofedRealm)
325	}
326
327	return s.kvStore.Set(0, rlm, StoreKeyDistributedToGovStakerHistory.String(), NewBPTreeN(16))
328}
329
330// GetDistributedToGovStakerHistory reads the cumulative Gov/Staker distribution-history tree.
331//
332// Returns:
333//   - tree: The BP-tree mapping token paths to amounts actually distributed to Gov/Staker; the method panics if the stored value is absent or has the wrong type.
334func (s *protocolFeeStore) GetDistributedToGovStakerHistory() *bptree.BPTree {
335	distributedToGovStakerHistory, err := s.kvStore.GetBPTree(StoreKeyDistributedToGovStakerHistory.String())
336	if err != nil {
337		panic(err)
338	}
339
340	return distributedToGovStakerHistory
341}
342
343// GetDistributedToGovStakerHistoryItem reads one token's cumulative Gov/Staker distribution history.
344//
345// Parameters:
346//   - tokenPath: Token path whose distributed amount should be looked up.
347//
348// Returns:
349//   - amount: The stored cumulative amount distributed to Gov/Staker for tokenPath, or zero when no entry exists.
350//   - found: True when tokenPath has a history entry; false when it is absent.
351func (s *protocolFeeStore) GetDistributedToGovStakerHistoryItem(tokenPath string) (int64, bool) {
352	distributedToGovStakerHistory, err := s.kvStore.GetBPTree(StoreKeyDistributedToGovStakerHistory.String())
353	if err != nil {
354		panic(err)
355	}
356
357	result := distributedToGovStakerHistory.Get(tokenPath)
358	if result == nil {
359		return 0, false
360	}
361
362	amount, ok := result.(int64)
363	if !ok {
364		panic(ufmt.Errorf("failed to cast result to int64: %T", result))
365	}
366
367	return amount, true
368}
369
370// SetDistributedToGovStakerHistoryItem updates one token's cumulative Gov/Staker distribution history.
371//
372// Parameters:
373//   - _: Crossing discriminator for the store operation; pass 0.
374//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
375//   - tokenPath: Token path whose distributed amount is replaced.
376//   - amount: Cumulative amount actually distributed to Gov/Staker to store for tokenPath.
377//
378// Returns:
379//   - err: Nil when the history tree is persisted; otherwise the current-realm, tree-read, or KV-store write error.
380func (s *protocolFeeStore) SetDistributedToGovStakerHistoryItem(_ int, rlm realm, tokenPath string, amount int64) error {
381	if !rlm.IsCurrent() {
382		return errors.New(errSpoofedRealm)
383	}
384
385	distributedToGovStakerHistory, err := s.kvStore.GetBPTree(StoreKeyDistributedToGovStakerHistory.String())
386	if err != nil {
387		return err
388	}
389
390	distributedToGovStakerHistory.Set(tokenPath, amount)
391
392	return s.kvStore.Set(0, rlm, StoreKeyDistributedToGovStakerHistory.String(), distributedToGovStakerHistory)
393}
394
395// HasDistributedToDevOpsHistoryStoreKey reports whether the DevOps distribution-history tree exists.
396//
397// Returns:
398//   - exists: True when the DevOps distribution-history tree key is present in the KV store.
399//
400// handle distributedToDevOpsHistory store data
401func (s *protocolFeeStore) HasDistributedToDevOpsHistoryStoreKey() bool {
402	return s.kvStore.Has(StoreKeyDistributedToDevOpsHistory.String())
403}
404
405// InitializeDistributedToDevOpsHistory creates the DevOps distribution-history tree.
406//
407// Parameters:
408//   - _: Crossing discriminator for the store operation; pass 0.
409//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
410//
411// Returns:
412//   - err: Nil when the history tree is initialized; otherwise the current-realm or KV-store write error.
413func (s *protocolFeeStore) InitializeDistributedToDevOpsHistory(_ int, rlm realm) error {
414	if !rlm.IsCurrent() {
415		return errors.New(errSpoofedRealm)
416	}
417
418	return s.kvStore.Set(0, rlm, StoreKeyDistributedToDevOpsHistory.String(), NewBPTreeN(16))
419}
420
421// GetDistributedToDevOpsHistory reads the cumulative DevOps distribution-history tree.
422//
423// Returns:
424//   - tree: The BP-tree mapping token paths to amounts actually distributed to DevOps; the method panics if the stored value is absent or has the wrong type.
425func (s *protocolFeeStore) GetDistributedToDevOpsHistory() *bptree.BPTree {
426	distributedToDevOpsHistory, err := s.kvStore.GetBPTree(StoreKeyDistributedToDevOpsHistory.String())
427	if err != nil {
428		panic(err)
429	}
430
431	return distributedToDevOpsHistory
432}
433
434// GetDistributedToDevOpsHistoryItem reads one token's cumulative DevOps distribution history.
435//
436// Parameters:
437//   - tokenPath: Token path whose distributed amount should be looked up.
438//
439// Returns:
440//   - amount: The stored cumulative amount distributed to DevOps for tokenPath, or zero when no entry exists.
441//   - found: True when tokenPath has a history entry; false when it is absent.
442func (s *protocolFeeStore) GetDistributedToDevOpsHistoryItem(tokenPath string) (int64, bool) {
443	distributedToDevOpsHistory, err := s.kvStore.GetBPTree(StoreKeyDistributedToDevOpsHistory.String())
444	if err != nil {
445		panic(err)
446	}
447
448	result := distributedToDevOpsHistory.Get(tokenPath)
449	if result == nil {
450		return 0, false
451	}
452
453	amount, ok := result.(int64)
454	if !ok {
455		panic(ufmt.Errorf("failed to cast result to int64: %T", result))
456	}
457
458	return amount, true
459}
460
461// SetDistributedToDevOpsHistoryItem updates one token's cumulative DevOps distribution history.
462//
463// Parameters:
464//   - _: Crossing discriminator for the store operation; pass 0.
465//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
466//   - tokenPath: Token path whose distributed amount is replaced.
467//   - amount: Cumulative amount actually distributed to DevOps to store for tokenPath.
468//
469// Returns:
470//   - err: Nil when the history tree is persisted; otherwise the current-realm, tree-read, or KV-store write error.
471func (s *protocolFeeStore) SetDistributedToDevOpsHistoryItem(_ int, rlm realm, tokenPath string, amount int64) error {
472	if !rlm.IsCurrent() {
473		return errors.New(errSpoofedRealm)
474	}
475
476	distributedToDevOpsHistory, err := s.kvStore.GetBPTree(StoreKeyDistributedToDevOpsHistory.String())
477	if err != nil {
478		return err
479	}
480
481	distributedToDevOpsHistory.Set(tokenPath, amount)
482
483	return s.kvStore.Set(0, rlm, StoreKeyDistributedToDevOpsHistory.String(), distributedToDevOpsHistory)
484}
485
486// handle reservedTokens store data
487//
488// reservedTokens is the set of token paths that collected a fee not yet transferred out
489// by DistributeProtocolFee. It is kept as a tree so that a single token can be added or
490// settled without rewriting the whole set.
491//
492// Returns:
493//   - exists: True when the reserved-token index key is present in the KV store.
494func (s *protocolFeeStore) HasReservedTokensStoreKey() bool {
495	return s.kvStore.Has(StoreKeyReservedTokens.String())
496}
497
498// InitializeReservedTokens creates the reserved-token index tree.
499//
500// Parameters:
501//   - _: Crossing discriminator for the store operation; pass 0.
502//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
503//
504// Returns:
505//   - err: Nil when the index tree is initialized; otherwise the current-realm or KV-store write error.
506func (s *protocolFeeStore) InitializeReservedTokens(_ int, rlm realm) error {
507	if !rlm.IsCurrent() {
508		return errors.New(errSpoofedRealm)
509	}
510
511	return s.kvStore.Set(0, rlm, StoreKeyReservedTokens.String(), NewBPTreeN(16))
512}
513
514func (s *protocolFeeStore) getReservedTokenTree() *bptree.BPTree {
515	reservedTokens, err := s.kvStore.GetBPTree(StoreKeyReservedTokens.String())
516	if err != nil {
517		panic(err)
518	}
519
520	return reservedTokens
521}
522
523// GetReservedTokens returns all token paths currently reserved for distribution.
524//
525// Returns:
526//   - tokenPaths: Token paths present in the reserved-token index, in BP-tree iteration order.
527func (s *protocolFeeStore) GetReservedTokens() []string {
528	return collectTreeKeys(s.getReservedTokenTree())
529}
530
531// HasReservedToken reports whether tokenPath is currently reserved for distribution.
532//
533// Parameters:
534//   - tokenPath: Token path to look up in the reserved-token index.
535//
536// Returns:
537//   - exists: True when tokenPath is in the reserved-token index; false otherwise.
538func (s *protocolFeeStore) HasReservedToken(tokenPath string) bool {
539	return s.getReservedTokenTree().Has(tokenPath)
540}
541
542// AddReservedToken adds tokenPath to the reserved-token index.
543//
544// Parameters:
545//   - _: Crossing discriminator for the store operation; pass 0.
546//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
547//   - tokenPath: Token path collected for protocol-fee distribution.
548//
549// Returns:
550//   - err: Nil when tokenPath is already present or has been added; otherwise the current-realm or KV-store write error.
551func (s *protocolFeeStore) AddReservedToken(_ int, rlm realm, tokenPath string) error {
552	if !rlm.IsCurrent() {
553		return errors.New(errSpoofedRealm)
554	}
555
556	reservedTokens := s.getReservedTokenTree()
557	if reservedTokens.Has(tokenPath) {
558		return nil
559	}
560
561	reservedTokens.Set(tokenPath, true)
562
563	return s.kvStore.Set(0, rlm, StoreKeyReservedTokens.String(), reservedTokens)
564}
565
566// RemoveReservedToken removes one tokenPath from the reserved-token set when present.
567//
568// Parameters:
569//   - _: Crossing discriminator for the store operation; pass 0.
570//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
571//   - tokenPath: Token path to remove from the reserved-token set.
572//
573// Returns:
574//   - err: Nil when tokenPath is absent or has been removed; otherwise the current-realm or KV-store write error.
575func (s *protocolFeeStore) RemoveReservedToken(_ int, rlm realm, tokenPath string) error {
576	if !rlm.IsCurrent() {
577		return errors.New(errSpoofedRealm)
578	}
579
580	reservedTokens := s.getReservedTokenTree()
581	if _, removed := reservedTokens.Remove(tokenPath); !removed {
582		return nil
583	}
584
585	return s.kvStore.Set(0, rlm, StoreKeyReservedTokens.String(), reservedTokens)
586}
587
588// handle accrualEpoch store data
589//
590// accrualEpoch numbers the intervals between gov/staker stake changes. gov/staker
591// advances it on every stake change, so every fee that arrives is attributed to the
592// stake distribution in force when it arrived.
593//
594// Returns:
595//   - exists: True when the accrual-epoch store key is present in the KV store.
596func (s *protocolFeeStore) HasAccrualEpochStoreKey() bool {
597	return s.kvStore.Has(StoreKeyAccrualEpoch.String())
598}
599
600// InitializeAccrualEpoch initializes the current fee-accrual epoch to zero.
601//
602// Parameters:
603//   - _: Crossing discriminator for the store operation; pass 0.
604//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
605//
606// Returns:
607//   - err: Nil when the epoch key is initialized; otherwise the current-realm or KV-store write error.
608func (s *protocolFeeStore) InitializeAccrualEpoch(_ int, rlm realm) error {
609	if !rlm.IsCurrent() {
610		return errors.New(errSpoofedRealm)
611	}
612
613	return s.kvStore.Set(0, rlm, StoreKeyAccrualEpoch.String(), int64(0))
614}
615
616// GetAccrualEpoch reads the epoch under which new Gov/Staker accrual buckets are recorded.
617//
618// Returns:
619//   - epoch: The persisted current accrual epoch; the method panics if the key is missing or cannot be decoded as int64.
620func (s *protocolFeeStore) GetAccrualEpoch() int64 {
621	accrualEpoch, err := s.kvStore.GetInt64(StoreKeyAccrualEpoch.String())
622	if err != nil {
623		panic(err)
624	}
625
626	return accrualEpoch
627}
628
629// SetAccrualEpoch persists the current fee-accrual epoch.
630//
631// Parameters:
632//   - _: Crossing discriminator for the store operation; pass 0.
633//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
634//   - accrualEpoch: Epoch number assigned to newly collected Gov/Staker accrual buckets.
635//
636// Returns:
637//   - err: Nil when the epoch is persisted; otherwise the current-realm or KV-store write error.
638func (s *protocolFeeStore) SetAccrualEpoch(_ int, rlm realm, accrualEpoch int64) error {
639	if !rlm.IsCurrent() {
640		return errors.New(errSpoofedRealm)
641	}
642
643	return s.kvStore.Set(0, rlm, StoreKeyAccrualEpoch.String(), accrualEpoch)
644}
645
646// handle accrualBuckets store data
647//
648// accrualBuckets holds, per token path, the gov/staker share collected during each
649// accrual epoch that gov/staker has not folded into its accumulator yet. Folding
650// consumes the oldest buckets first, so a token is settled in epoch order.
651//
652// Returns:
653//   - exists: True when the accrual-bucket store key is present in the KV store.
654func (s *protocolFeeStore) HasAccrualBucketsStoreKey() bool {
655	return s.kvStore.Has(StoreKeyAccrualBuckets.String())
656}
657
658// InitializeAccrualBuckets creates the nested accrual-bucket tree.
659//
660// Parameters:
661//   - _: Crossing discriminator for the store operation; pass 0.
662//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
663//
664// Returns:
665//   - err: Nil when the bucket tree is initialized; otherwise the current-realm or KV-store write error.
666func (s *protocolFeeStore) InitializeAccrualBuckets(_ int, rlm realm) error {
667	if !rlm.IsCurrent() {
668		return errors.New(errSpoofedRealm)
669	}
670
671	return s.kvStore.Set(0, rlm, StoreKeyAccrualBuckets.String(), NewBPTreeN(16))
672}
673
674func (s *protocolFeeStore) getAccrualBucketTree() *bptree.BPTree {
675	accrualBuckets, err := s.kvStore.GetBPTree(StoreKeyAccrualBuckets.String())
676	if err != nil {
677		panic(err)
678	}
679
680	return accrualBuckets
681}
682
683func (s *protocolFeeStore) getTokenAccrualBucketTree(accrualBuckets *bptree.BPTree, tokenPath string) *bptree.BPTree {
684	result := accrualBuckets.Get(tokenPath)
685	if result == nil {
686		return nil
687	}
688
689	tokenBuckets, ok := result.(*bptree.BPTree)
690	if !ok {
691		panic(ufmt.Errorf("failed to cast result to *bptree.BPTree: %T", result))
692	}
693
694	return tokenBuckets
695}
696
697// GetAccrualBuckets returns up to limit of the oldest pending buckets of tokenPath in
698// epoch order. A limit of zero or less returns every pending bucket.
699//
700// Parameters:
701//   - tokenPath: Token path whose pending Gov/Staker accrual buckets should be read.
702//   - limit: Maximum number of buckets to return; zero or a negative value returns all pending buckets.
703//
704// Returns:
705//   - epochs: Epoch numbers for the returned buckets, in ascending BP-tree iteration order.
706//   - amounts: Gov/Staker amounts for the returned epochs; amounts[i] corresponds to epochs[i].
707func (s *protocolFeeStore) GetAccrualBuckets(tokenPath string, limit int) ([]int64, []int64) {
708	epochs := []int64{}
709	amounts := []int64{}
710
711	tokenBuckets := s.getTokenAccrualBucketTree(s.getAccrualBucketTree(), tokenPath)
712	if tokenBuckets == nil {
713		return epochs, amounts
714	}
715
716	tokenBuckets.Iterate("", "", func(key string, value any) bool {
717		if limit > 0 && len(epochs) >= limit {
718			return true
719		}
720
721		amount, ok := value.(int64)
722		if !ok {
723			panic(ufmt.Errorf("failed to cast result to int64: %T", value))
724		}
725
726		epochs = append(epochs, decodeEpochKey(key))
727		amounts = append(amounts, amount)
728
729		return false
730	})
731
732	return epochs, amounts
733}
734
735// AddAccrualBucket adds amount to the bucket of tokenPath at epoch.
736//
737// Parameters:
738//   - _: Crossing discriminator for the store operation; pass 0.
739//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
740//   - tokenPath: Token path whose Gov/Staker accrual bucket is updated.
741//   - epoch: Non-negative accrual epoch identifying the bucket; negative epochs panic during key encoding.
742//   - amount: Amount to add to the existing bucket value.
743//
744// Returns:
745//   - err: Nil when the bucket tree is persisted; otherwise the current-realm or KV-store write error.
746func (s *protocolFeeStore) AddAccrualBucket(_ int, rlm realm, tokenPath string, epoch int64, amount int64) error {
747	if !rlm.IsCurrent() {
748		return errors.New(errSpoofedRealm)
749	}
750
751	accrualBuckets := s.getAccrualBucketTree()
752	tokenBuckets := s.getTokenAccrualBucketTree(accrualBuckets, tokenPath)
753	if tokenBuckets == nil {
754		tokenBuckets = NewBPTreeN(16)
755		accrualBuckets.Set(tokenPath, tokenBuckets)
756	}
757
758	key := encodeEpochKey(epoch)
759	existing := int64(0)
760	if result := tokenBuckets.Get(key); result != nil {
761		current, ok := result.(int64)
762		if !ok {
763			panic(ufmt.Errorf("failed to cast result to int64: %T", result))
764		}
765		existing = current
766	}
767
768	tokenBuckets.Set(key, gnsmath.SafeAddInt64(existing, amount))
769
770	return s.kvStore.Set(0, rlm, StoreKeyAccrualBuckets.String(), accrualBuckets)
771}
772
773// RemoveAccrualBuckets drops the buckets of tokenPath at the given epochs. The token's
774// tree is dropped as well once no bucket remains.
775//
776// Parameters:
777//   - _: Crossing discriminator for the store operation; pass 0.
778//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
779//   - tokenPath: Token path whose selected accrual buckets are removed.
780//   - epochs: Epoch numbers whose buckets should be deleted; an absent token or epoch is ignored.
781//
782// Returns:
783//   - err: Nil when removals are applied (including an absent token); otherwise the current-realm or KV-store write error.
784func (s *protocolFeeStore) RemoveAccrualBuckets(_ int, rlm realm, tokenPath string, epochs []int64) error {
785	if !rlm.IsCurrent() {
786		return errors.New(errSpoofedRealm)
787	}
788
789	accrualBuckets := s.getAccrualBucketTree()
790	tokenBuckets := s.getTokenAccrualBucketTree(accrualBuckets, tokenPath)
791	if tokenBuckets == nil {
792		return nil
793	}
794
795	for _, epoch := range epochs {
796		tokenBuckets.Remove(encodeEpochKey(epoch))
797	}
798
799	if tokenBuckets.Size() == 0 {
800		accrualBuckets.Remove(tokenPath)
801	}
802
803	return s.kvStore.Set(0, rlm, StoreKeyAccrualBuckets.String(), accrualBuckets)
804}
805
806// handle accrualPendingTokens store data
807//
808// accrualPendingTokens is the set of token paths that still own at least one accrual
809// bucket, so gov/staker can enumerate what it has to fold without scanning every token.
810//
811// Returns:
812//   - exists: True when the pending-token index key is present in the KV store.
813func (s *protocolFeeStore) HasAccrualPendingTokensStoreKey() bool {
814	return s.kvStore.Has(StoreKeyAccrualPendingTokens.String())
815}
816
817// InitializeAccrualPendingTokens creates the index of tokens with pending accrual buckets.
818//
819// Parameters:
820//   - _: Crossing discriminator for the store operation; pass 0.
821//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
822//
823// Returns:
824//   - err: Nil when the pending-token index is initialized; otherwise the current-realm or KV-store write error.
825func (s *protocolFeeStore) InitializeAccrualPendingTokens(_ int, rlm realm) error {
826	if !rlm.IsCurrent() {
827		return errors.New(errSpoofedRealm)
828	}
829
830	return s.kvStore.Set(0, rlm, StoreKeyAccrualPendingTokens.String(), NewBPTreeN(16))
831}
832
833func (s *protocolFeeStore) getAccrualPendingTokenTree() *bptree.BPTree {
834	accrualPendingTokens, err := s.kvStore.GetBPTree(StoreKeyAccrualPendingTokens.String())
835	if err != nil {
836		panic(err)
837	}
838
839	return accrualPendingTokens
840}
841
842// GetAccrualPendingTokens returns token paths that still own accrual buckets.
843//
844// Returns:
845//   - tokenPaths: Token paths in the pending-accrual index, in BP-tree iteration order.
846func (s *protocolFeeStore) GetAccrualPendingTokens() []string {
847	return collectTreeKeys(s.getAccrualPendingTokenTree())
848}
849
850// AddAccrualPendingToken adds tokenPath to the pending-accrual index.
851//
852// Parameters:
853//   - _: Crossing discriminator for the store operation; pass 0.
854//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
855//   - tokenPath: Token path with at least one accrual bucket pending.
856//
857// Returns:
858//   - err: Nil when tokenPath is already present or has been added; otherwise the current-realm or KV-store write error.
859func (s *protocolFeeStore) AddAccrualPendingToken(_ int, rlm realm, tokenPath string) error {
860	if !rlm.IsCurrent() {
861		return errors.New(errSpoofedRealm)
862	}
863
864	accrualPendingTokens := s.getAccrualPendingTokenTree()
865	if accrualPendingTokens.Has(tokenPath) {
866		return nil
867	}
868
869	accrualPendingTokens.Set(tokenPath, true)
870
871	return s.kvStore.Set(0, rlm, StoreKeyAccrualPendingTokens.String(), accrualPendingTokens)
872}
873
874// RemoveAccrualPendingToken drops one token from the set. It writes only when the
875// token was listed.
876//
877// Parameters:
878//   - _: Crossing discriminator for the store operation; pass 0.
879//   - rlm: Propagated realm context for this store write; it must be current (`rlm.IsCurrent()`).
880//   - tokenPath: Token path to remove from the pending-accrual index.
881//
882// Returns:
883//   - err: Nil when tokenPath is absent or has been removed; otherwise the current-realm or KV-store write error.
884func (s *protocolFeeStore) RemoveAccrualPendingToken(_ int, rlm realm, tokenPath string) error {
885	if !rlm.IsCurrent() {
886		return errors.New(errSpoofedRealm)
887	}
888
889	accrualPendingTokens := s.getAccrualPendingTokenTree()
890	if _, removed := accrualPendingTokens.Remove(tokenPath); !removed {
891		return nil
892	}
893
894	return s.kvStore.Set(0, rlm, StoreKeyAccrualPendingTokens.String(), accrualPendingTokens)
895}
896
897func collectTreeKeys(tree *bptree.BPTree) []string {
898	keys := make([]string, 0, tree.Size())
899	tree.Iterate("", "", func(key string, _ any) bool {
900		keys = append(keys, key)
901		return false
902	})
903
904	return keys
905}
906
907func encodeEpochKey(epoch int64) string {
908	if epoch < 0 {
909		panic(ufmt.Sprintf("negative epoch not supported: %d", epoch))
910	}
911
912	return utils.EncodeUint64(uint64(epoch))
913}
914
915func decodeEpochKey(key string) int64 {
916	return gnsmath.SafeUint64ToInt64(utils.DecodeUint64(key))
917}
918
919// NewProtocolFeeStore creates a protocol-fee store backed by the provided KV store.
920// This function is used by the upgrade system to create storage instances for each implementation.
921//
922// Parameters:
923//   - kvStore: Domain KV store used to persist protocol-fee state.
924//
925// Returns:
926//   - protocolFeeStore: An IProtocolFeeStore implementation backed by kvStore.
927func NewProtocolFeeStore(kvStore store.KVStore) IProtocolFeeStore {
928	return &protocolFeeStore{
929		kvStore: kvStore,
930	}
931}