1const (
 2	// By default, devOps will get 0% of the protocol fee (which means gov/staker will get 100% of the protocol fee)
 3	// This percentage can be modified through governance.
 4	StoreKeyDevOpsPct StoreKey = "devOpsPct"
 5
 6	// accuToGovStaker tracks the cumulative amount allocated to GovStaker,
 7	// including allocations that are still pending distribution.
 8	StoreKeyAccuToGovStaker StoreKey = "accuToGovStaker" // tokenPath -> amount
 9	// accuToDevOps tracks the cumulative amount allocated to DevOps,
10	// including allocations that are still pending distribution.
11	StoreKeyAccuToDevOps StoreKey = "accuToDevOps" // tokenPath -> amount
12
13	// Distribution-history trees track cumulative amounts actually transferred.
14	StoreKeyDistributedToGovStakerHistory StoreKey = "distributedToGovStakerHistory" // tokenPath -> amount
15	StoreKeyDistributedToDevOpsHistory    StoreKey = "distributedToDevOpsHistory"    // tokenPath -> amount
16
17	// reservedTokens tracks token paths collected but not yet distributed.
18	StoreKeyReservedTokens StoreKey = "reservedTokens"
19
20	// accrualEpoch, accrualBuckets and accrualPendingTokens track the gov/staker share
21	// per token path and accrual epoch until gov/staker folds it into its accumulator.
22	StoreKeyAccrualEpoch         StoreKey = "accrualEpoch"
23	StoreKeyAccrualBuckets       StoreKey = "accrualBuckets"       // tokenPath -> (epoch -> amount)
24	StoreKeyAccrualPendingTokens StoreKey = "accrualPendingTokens" // tokenPath -> true
25)

1func AddToProtocolFee(cur realm, tokenPath string, amount int64) error

1func AdvanceAccrualEpoch(cur realm) int64

1func ConsumeAccrualBuckets(cur realm, tokenPath string, limit int) ([]int64, []int64)

1func DistributeProtocolFee(cur realm)

1func DistributeProtocolFeeByTokenPath(cur realm, tokenPath string)

1func GetAccrualBuckets(tokenPath string, limit int) ([]int64, []int64)

1func GetAccrualEpoch() int64

1func GetAccrualPendingTokens() []string

1func GetAccuTransferToDevOpsByTokenPath(tokenPath string) int64

1func GetAccuTransferToGovStakerByTokenPath(tokenPath string) int64

1func GetAccuTransfersToDevOps() map[string]int64

1func GetAccuTransfersToGovStaker() map[string]int64

1func GetActualDistributedToDevOps() map[string]int64

1func GetActualDistributedToDevOpsByTokenPath(tokenPath string) int64

1func GetActualDistributedToGovStaker() map[string]int64

1func GetActualDistributedToGovStakerByTokenPath(tokenPath string) int64

1func GetDevOpsPct() int64

1func GetDomainPath() string

1func GetGovStakerPct() int64

1func GetImplementationPackagePath() string

1func GetReservedTokens() []string

1func GetVersionPackagePath() string

1func NewBPTreeN(fanout int) *bptree.BPTree

1func RegisterInitializer(cur realm, initializer func(_ int, rlm realm, protocolFeeStore IProtocolFeeStore) IProtocolFee)

1func Render(path string) string

1func SetDevOpsPct(cur realm, pct int64)

1func SetGovStakerPct(cur realm, pct int64)

1func UpgradeImpl(cur realm, packagePath string)

1func NewProtocolFeeStore(kvStore store.KVStore) IProtocolFeeStore

1type IProtocolFee interface {
2	IProtocolFeeManager
3	IProtocolFeeGetter
4	Render(path string) string
5}

  1type IProtocolFeeGetter interface {
  2	// GetDevOpsPct returns the configured DevOps allocation.
  3	//
  4	// Returns:
  5	//   - pct: DevOps fee allocation in basis-point units, from 0 through 10000
  6	GetDevOpsPct() int64
  7
  8	// GetGovStakerPct returns the configured GovStaker allocation.
  9	//
 10	// Returns:
 11	//   - pct: GovStaker fee allocation in basis-point units, from 0 through 10000
 12	GetGovStakerPct() int64
 13
 14	// GetReservedTokens returns token paths whose collected fees await distribution.
 15	//
 16	// Returns:
 17	//   - tokenPaths: token contract paths in the reserved-token index
 18	GetReservedTokens() []string
 19
 20	// GetAccuTransfersToGovStaker returns cumulative allocations assigned to GovStaker.
 21	//
 22	// Returns:
 23	//   - transfers: map from token contract path to cumulative allocated amount in base units
 24	GetAccuTransfersToGovStaker() map[string]int64
 25
 26	// GetAccuTransfersToDevOps returns cumulative allocations assigned to DevOps.
 27	//
 28	// Returns:
 29	//   - transfers: map from token contract path to cumulative allocated amount in base units
 30	GetAccuTransfersToDevOps() map[string]int64
 31
 32	// GetAccuTransferToGovStakerByTokenPath returns the GovStaker allocation for one token.
 33	//
 34	// Parameters:
 35	//   - path: token contract path whose cumulative GovStaker allocation is queried
 36	//
 37	// Returns:
 38	//   - amount: cumulative GovStaker allocation for path in token base units, or zero if absent
 39	GetAccuTransferToGovStakerByTokenPath(path string) int64
 40
 41	// GetAccuTransferToDevOpsByTokenPath returns the DevOps allocation for one token.
 42	//
 43	// Parameters:
 44	//   - path: token contract path whose cumulative DevOps allocation is queried
 45	//
 46	// Returns:
 47	//   - amount: cumulative DevOps allocation for path in token base units, or zero if absent
 48	GetAccuTransferToDevOpsByTokenPath(path string) int64
 49
 50	// GetActualDistributedToGovStaker returns cumulative amounts transferred to GovStaker.
 51	//
 52	// Returns:
 53	//   - transfers: map from token contract path to cumulative amount actually transferred in base units
 54	GetActualDistributedToGovStaker() map[string]int64
 55
 56	// GetActualDistributedToDevOps returns cumulative amounts transferred to DevOps.
 57	//
 58	// Returns:
 59	//   - transfers: map from token contract path to cumulative amount actually transferred in base units
 60	GetActualDistributedToDevOps() map[string]int64
 61
 62	// GetActualDistributedToGovStakerByTokenPath returns the completed GovStaker transfer for one token.
 63	//
 64	// Parameters:
 65	//   - path: token contract path whose completed GovStaker transfer is queried
 66	//
 67	// Returns:
 68	//   - amount: cumulative GovStaker amount actually transferred for path in base units, or zero if absent
 69	GetActualDistributedToGovStakerByTokenPath(path string) int64
 70
 71	// GetActualDistributedToDevOpsByTokenPath returns the completed DevOps transfer for one token.
 72	//
 73	// Parameters:
 74	//   - path: token contract path whose completed DevOps transfer is queried
 75	//
 76	// Returns:
 77	//   - amount: cumulative DevOps amount actually transferred for path in base units, or zero if absent
 78	GetActualDistributedToDevOpsByTokenPath(path string) int64
 79
 80	// GetAccrualEpoch returns the epoch assigned to newly collected GovStaker fees.
 81	//
 82	// Returns:
 83	//   - epoch: current non-negative accrual epoch
 84	GetAccrualEpoch() int64
 85
 86	// GetAccrualPendingTokens returns token paths that still have pending accrual buckets.
 87	//
 88	// Returns:
 89	//   - tokenPaths: token contract paths with at least one pending GovStaker accrual bucket
 90	GetAccrualPendingTokens() []string
 91
 92	// GetAccrualBuckets reads pending token buckets without removing them.
 93	//
 94	// Parameters:
 95	//   - tokenPath: token contract path whose GovStaker accrual buckets are queried
 96	//   - limit: maximum number of oldest buckets; zero or negative returns all pending buckets
 97	//
 98	// Returns:
 99	//   - epochs: selected accrual epoch numbers in ascending order
100	//   - amounts: fee amounts corresponding positionally to epochs, in token base units
101	GetAccrualBuckets(tokenPath string, limit int) ([]int64, []int64)
102}

 1type IProtocolFeeManager interface {
 2	// Mutating methods take `_ int, rlm realm` so a leading integer discriminator
 3	// (callers pass 0) and the current protocol_fee realm context are threaded
 4	// from proxy entry points down to cross-realm token transfers and store writes
 5	// performed inside each implementation. The discriminator is explicit at every
 6	// call site, making the realm threading visible to readers.
 7	// DistributeProtocolFee distributes all reserved protocol fees to DevOps and
 8	// GovStaker according to the configured allocation percentages.
 9	//
10	// Parameters:
11	//   - _: cross-call discriminator; callers pass 0
12	//   - rlm: propagated protocol_fee realm context; implementation validates it as current
13	DistributeProtocolFee(_ int, rlm realm)
14
15	// DistributeProtocolFeeByTokenPath distributes the reserved fee for one token path.
16	//
17	// Parameters:
18	//   - _: cross-call discriminator; callers pass 0
19	//   - rlm: propagated protocol_fee realm context; implementation validates it as current
20	//   - tokenPath: token contract path whose reserved fee should be distributed
21	DistributeProtocolFeeByTokenPath(_ int, rlm realm, tokenPath string)
22
23	// SetDevOpsPct updates the DevOps share; the GovStaker share becomes 10000 minus pct.
24	//
25	// Parameters:
26	//   - _: cross-call discriminator; callers pass 0
27	//   - rlm: propagated protocol_fee realm context; implementation validates it as current
28	//   - pct: DevOps allocation in basis-point units, from 0 through 10000 inclusive
29	SetDevOpsPct(_ int, rlm realm, pct int64)
30
31	// SetGovStakerPct updates the GovStaker share; the DevOps share becomes 10000 minus pct.
32	//
33	// Parameters:
34	//   - _: cross-call discriminator; callers pass 0
35	//   - rlm: propagated protocol_fee realm context; implementation validates it as current
36	//   - pct: GovStaker allocation in basis-point units, from 0 through 10000 inclusive
37	SetGovStakerPct(_ int, rlm realm, pct int64)
38
39	// AddToProtocolFee records and pulls an approved fee from an authorized protocol caller.
40	//
41	// Parameters:
42	//   - _: cross-call discriminator; callers pass 0
43	//   - rlm: propagated protocol_fee realm context; implementation rejects a non-current value
44	//   - tokenPath: token contract path from which the approved fee is pulled
45	//   - amount: non-negative fee amount in token base units; zero is a successful no-op
46	//
47	// Returns:
48	//   - err: nil after accounting and transfer succeed; an error when realm validation, halt checks, or storage/transfer operations fail
49	AddToProtocolFee(_ int, rlm realm, tokenPath string, amount int64) error
50
51	// AdvanceAccrualEpoch closes the current epoch and selects the next epoch for new fees.
52	//
53	// Parameters:
54	//   - _: cross-call discriminator; callers pass 0
55	//   - rlm: propagated protocol_fee realm context; implementation validates it as current
56	//
57	// Returns:
58	//   - epoch: newly stored non-negative accrual epoch
59	AdvanceAccrualEpoch(_ int, rlm realm) int64
60
61	// ConsumeAccrualBuckets removes pending buckets for one token in epoch order.
62	//
63	// Parameters:
64	//   - _: cross-call discriminator; callers pass 0
65	//   - rlm: propagated protocol_fee realm context; implementation validates it as current
66	//   - tokenPath: token contract path whose pending GovStaker buckets are consumed
67	//   - limit: maximum number of oldest buckets; zero or negative consumes all pending buckets
68	//
69	// Returns:
70	//   - epochs: consumed epoch numbers in ascending order
71	//   - amounts: fee amounts corresponding positionally to epochs, in token base units
72	ConsumeAccrualBuckets(_ int, rlm realm, tokenPath string, limit int) ([]int64, []int64)
73}

  1type IProtocolFeeStore interface {
  2	// HasDevOpsPctStoreKey reports whether the persisted DevOps percentage key exists.
  3	//
  4	// Returns:
  5	//   - exists: true when the DevOps percentage key is present in the KV store
  6	HasDevOpsPctStoreKey() bool
  7
  8	// InitializeDevOpsPct creates the DevOps percentage key with its default value.
  9	//
 10	// Parameters:
 11	//   - _: cross-call discriminator; callers pass 0
 12	//   - rlm: propagated protocol_fee realm context required for the authorized store write
 13	//
 14	// Returns:
 15	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
 16	InitializeDevOpsPct(_ int, rlm realm) error
 17
 18	// GetDevOpsPct reads the persisted DevOps percentage.
 19	//
 20	// Returns:
 21	//   - pct: stored DevOps allocation in basis-point units
 22	GetDevOpsPct() int64
 23
 24	// SetDevOpsPct persists a new DevOps percentage.
 25	//
 26	// Parameters:
 27	//   - _: cross-call discriminator; callers pass 0
 28	//   - rlm: propagated protocol_fee realm context required for the authorized store write
 29	//   - pct: DevOps allocation in basis-point units
 30	//
 31	// Returns:
 32	//   - err: nil when the value is stored; an error for invalid realm context or KV-store failure
 33	SetDevOpsPct(_ int, rlm realm, pct int64) error
 34
 35	// HasAccuToGovStakerStoreKey reports whether the GovStaker allocation tree key exists.
 36	//
 37	// Returns:
 38	//   - exists: true when the cumulative GovStaker allocation tree is present in the KV store
 39	HasAccuToGovStakerStoreKey() bool
 40
 41	// InitializeAccuToGovStaker creates the cumulative GovStaker allocation tree.
 42	//
 43	// Parameters:
 44	//   - _: cross-call discriminator; callers pass 0
 45	//   - rlm: propagated protocol_fee realm context required for the authorized store write
 46	//
 47	// Returns:
 48	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
 49	InitializeAccuToGovStaker(_ int, rlm realm) error
 50
 51	// GetAccuToGovStaker returns the tree of cumulative GovStaker allocations by token.
 52	//
 53	// Returns:
 54	//   - tree: persistent BPTree keyed by token path with int64 allocation values
 55	GetAccuToGovStaker() *bptree.BPTree
 56
 57	// GetAccuToGovStakerItem reads one token's cumulative GovStaker allocation.
 58	//
 59	// Parameters:
 60	//   - tokenPath: token contract path used as the allocation-tree key
 61	//
 62	// Returns:
 63	//   - amount: stored allocation in token base units, or zero when tokenPath is absent
 64	//   - exists: true when tokenPath has a stored allocation; false when absent
 65	GetAccuToGovStakerItem(tokenPath string) (int64, bool)
 66
 67	// SetAccuToGovStakerItem stores one token's cumulative GovStaker allocation.
 68	//
 69	// Parameters:
 70	//   - _: cross-call discriminator; callers pass 0
 71	//   - rlm: propagated protocol_fee realm context required for the authorized store write
 72	//   - tokenPath: token contract path used as the allocation-tree key
 73	//   - amount: cumulative GovStaker allocation in token base units to store
 74	//
 75	// Returns:
 76	//   - err: nil when the value is stored; an error for invalid realm context, missing tree, or KV-store failure
 77	SetAccuToGovStakerItem(_ int, rlm realm, tokenPath string, amount int64) error
 78
 79	// HasAccuToDevOpsStoreKey reports whether the DevOps allocation tree key exists.
 80	//
 81	// Returns:
 82	//   - exists: true when the cumulative DevOps allocation tree is present in the KV store
 83	HasAccuToDevOpsStoreKey() bool
 84
 85	// InitializeAccuToDevOps creates the cumulative DevOps allocation tree.
 86	//
 87	// Parameters:
 88	//   - _: cross-call discriminator; callers pass 0
 89	//   - rlm: propagated protocol_fee realm context required for the authorized store write
 90	//
 91	// Returns:
 92	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
 93	InitializeAccuToDevOps(_ int, rlm realm) error
 94
 95	// GetAccuToDevOps returns the tree of cumulative DevOps allocations by token.
 96	//
 97	// Returns:
 98	//   - tree: persistent BPTree keyed by token path with int64 allocation values
 99	GetAccuToDevOps() *bptree.BPTree
100
101	// GetAccuToDevOpsItem reads one token's cumulative DevOps allocation.
102	//
103	// Parameters:
104	//   - tokenPath: token contract path used as the allocation-tree key
105	//
106	// Returns:
107	//   - amount: stored allocation in token base units, or zero when tokenPath is absent
108	//   - exists: true when tokenPath has a stored allocation; false when absent
109	GetAccuToDevOpsItem(tokenPath string) (int64, bool)
110
111	// SetAccuToDevOpsItem stores one token's cumulative DevOps allocation.
112	//
113	// Parameters:
114	//   - _: cross-call discriminator; callers pass 0
115	//   - rlm: propagated protocol_fee realm context required for the authorized store write
116	//   - tokenPath: token contract path used as the allocation-tree key
117	//   - amount: cumulative DevOps allocation in token base units to store
118	//
119	// Returns:
120	//   - err: nil when the value is stored; an error for invalid realm context, missing tree, or KV-store failure
121	SetAccuToDevOpsItem(_ int, rlm realm, tokenPath string, amount int64) error
122
123	// HasDistributedToGovStakerHistoryStoreKey reports whether the GovStaker history tree key exists.
124	//
125	// Returns:
126	//   - exists: true when the cumulative GovStaker distribution-history tree is present
127	HasDistributedToGovStakerHistoryStoreKey() bool
128
129	// InitializeDistributedToGovStakerHistory creates the GovStaker distribution-history tree.
130	//
131	// Parameters:
132	//   - _: cross-call discriminator; callers pass 0
133	//   - rlm: propagated protocol_fee realm context required for the authorized store write
134	//
135	// Returns:
136	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
137	InitializeDistributedToGovStakerHistory(_ int, rlm realm) error
138
139	// GetDistributedToGovStakerHistory returns cumulative actual GovStaker transfers by token.
140	//
141	// Returns:
142	//   - tree: persistent BPTree keyed by token path with int64 transferred amounts
143	GetDistributedToGovStakerHistory() *bptree.BPTree
144
145	// GetDistributedToGovStakerHistoryItem reads one token's actual GovStaker transfer.
146	//
147	// Parameters:
148	//   - tokenPath: token contract path used as the history-tree key
149	//
150	// Returns:
151	//   - amount: stored transferred amount in token base units, or zero when tokenPath is absent
152	//   - exists: true when tokenPath has a stored history amount; false when absent
153	GetDistributedToGovStakerHistoryItem(tokenPath string) (int64, bool)
154
155	// SetDistributedToGovStakerHistoryItem stores one token's actual GovStaker transfer.
156	//
157	// Parameters:
158	//   - _: cross-call discriminator; callers pass 0
159	//   - rlm: propagated protocol_fee realm context required for the authorized store write
160	//   - tokenPath: token contract path used as the history-tree key
161	//   - amount: cumulative amount actually transferred to GovStaker in token base units
162	//
163	// Returns:
164	//   - err: nil when the value is stored; an error for invalid realm context, missing tree, or KV-store failure
165	SetDistributedToGovStakerHistoryItem(_ int, rlm realm, tokenPath string, amount int64) error
166
167	// HasDistributedToDevOpsHistoryStoreKey reports whether the DevOps history tree key exists.
168	//
169	// Returns:
170	//   - exists: true when the cumulative DevOps distribution-history tree is present
171	HasDistributedToDevOpsHistoryStoreKey() bool
172
173	// InitializeDistributedToDevOpsHistory creates the DevOps distribution-history tree.
174	//
175	// Parameters:
176	//   - _: cross-call discriminator; callers pass 0
177	//   - rlm: propagated protocol_fee realm context required for the authorized store write
178	//
179	// Returns:
180	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
181	InitializeDistributedToDevOpsHistory(_ int, rlm realm) error
182
183	// GetDistributedToDevOpsHistory returns cumulative actual DevOps transfers by token.
184	//
185	// Returns:
186	//   - tree: persistent BPTree keyed by token path with int64 transferred amounts
187	GetDistributedToDevOpsHistory() *bptree.BPTree
188
189	// GetDistributedToDevOpsHistoryItem reads one token's actual DevOps transfer.
190	//
191	// Parameters:
192	//   - tokenPath: token contract path used as the history-tree key
193	//
194	// Returns:
195	//   - amount: stored transferred amount in token base units, or zero when tokenPath is absent
196	//   - exists: true when tokenPath has a stored history amount; false when absent
197	GetDistributedToDevOpsHistoryItem(tokenPath string) (int64, bool)
198
199	// SetDistributedToDevOpsHistoryItem stores one token's actual DevOps transfer.
200	//
201	// Parameters:
202	//   - _: cross-call discriminator; callers pass 0
203	//   - rlm: propagated protocol_fee realm context required for the authorized store write
204	//   - tokenPath: token contract path used as the history-tree key
205	//   - amount: cumulative amount actually transferred to DevOps in token base units
206	//
207	// Returns:
208	//   - err: nil when the value is stored; an error for invalid realm context, missing tree, or KV-store failure
209	SetDistributedToDevOpsHistoryItem(_ int, rlm realm, tokenPath string, amount int64) error
210
211	// HasReservedTokensStoreKey reports whether the reserved-token index key exists.
212	//
213	// Returns:
214	//   - exists: true when the reserved-token index is present in the KV store
215	HasReservedTokensStoreKey() bool
216
217	// InitializeReservedTokens creates the empty reserved-token index.
218	//
219	// Parameters:
220	//   - _: cross-call discriminator; callers pass 0
221	//   - rlm: propagated protocol_fee realm context required for the authorized store write
222	//
223	// Returns:
224	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
225	InitializeReservedTokens(_ int, rlm realm) error
226
227	// GetReservedTokens returns token paths currently marked as awaiting distribution.
228	//
229	// Returns:
230	//   - tokenPaths: keys in the reserved-token index
231	GetReservedTokens() []string
232
233	// HasReservedToken reports whether tokenPath is in the reserved-token index.
234	//
235	// Parameters:
236	//   - tokenPath: token contract path to look up in the reserved-token index
237	//
238	// Returns:
239	//   - exists: true when tokenPath is reserved for distribution
240	HasReservedToken(tokenPath string) bool
241
242	// AddReservedToken marks tokenPath as awaiting fee distribution.
243	//
244	// Parameters:
245	//   - _: cross-call discriminator; callers pass 0
246	//   - rlm: propagated protocol_fee realm context required for the authorized store write
247	//   - tokenPath: token contract path to add to the reserved-token index
248	//
249	// Returns:
250	//   - err: nil when added or already present; an error for invalid realm context or KV-store failure
251	AddReservedToken(_ int, rlm realm, tokenPath string) error
252
253	// RemoveReservedToken removes tokenPath from the reserved-token index when present.
254	//
255	// Parameters:
256	//   - _: cross-call discriminator; callers pass 0
257	//   - rlm: propagated protocol_fee realm context required for the authorized store write
258	//   - tokenPath: token contract path to remove from the reserved-token index
259	//
260	// Returns:
261	//   - err: nil when removed or already absent; an error for invalid realm context or KV-store failure
262	RemoveReservedToken(_ int, rlm realm, tokenPath string) error
263
264	// HasAccrualEpochStoreKey reports whether the accrual-epoch key exists.
265	//
266	// Returns:
267	//   - exists: true when the current accrual epoch is present in the KV store
268	HasAccrualEpochStoreKey() bool
269
270	// InitializeAccrualEpoch creates the accrual-epoch key with epoch zero.
271	//
272	// Parameters:
273	//   - _: cross-call discriminator; callers pass 0
274	//   - rlm: propagated protocol_fee realm context required for the authorized store write
275	//
276	// Returns:
277	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
278	InitializeAccrualEpoch(_ int, rlm realm) error
279
280	// GetAccrualEpoch reads the epoch currently assigned to newly collected fees.
281	//
282	// Returns:
283	//   - epoch: current non-negative accrual epoch
284	GetAccrualEpoch() int64
285
286	// SetAccrualEpoch persists a new current accrual epoch.
287	//
288	// Parameters:
289	//   - _: cross-call discriminator; callers pass 0
290	//   - rlm: propagated protocol_fee realm context required for the authorized store write
291	//   - accrualEpoch: epoch number to store for subsequently collected fees
292	//
293	// Returns:
294	//   - err: nil when the epoch is stored; an error for invalid realm context or KV-store failure
295	SetAccrualEpoch(_ int, rlm realm, accrualEpoch int64) error
296
297	// HasAccrualBucketsStoreKey reports whether the accrual-buckets tree key exists.
298	//
299	// Returns:
300	//   - exists: true when the per-token accrual-bucket tree is present
301	HasAccrualBucketsStoreKey() bool
302
303	// InitializeAccrualBuckets creates the empty per-token accrual-bucket tree.
304	//
305	// Parameters:
306	//   - _: cross-call discriminator; callers pass 0
307	//   - rlm: propagated protocol_fee realm context required for the authorized store write
308	//
309	// Returns:
310	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
311	InitializeAccrualBuckets(_ int, rlm realm) error
312
313	// GetAccrualBuckets reads the oldest pending buckets for one token without removing them.
314	//
315	// Parameters:
316	//   - tokenPath: token contract path whose accrual buckets are queried
317	//   - limit: maximum number of oldest buckets; zero or negative returns all pending buckets
318	//
319	// Returns:
320	//   - epochs: selected accrual epoch numbers in ascending order
321	//   - amounts: bucket amounts corresponding positionally to epochs, in token base units
322	GetAccrualBuckets(tokenPath string, limit int) ([]int64, []int64)
323
324	// AddAccrualBucket adds amount to one token's bucket for an accrual epoch.
325	//
326	// Parameters:
327	//   - _: cross-call discriminator; callers pass 0
328	//   - rlm: propagated protocol_fee realm context required for the authorized store write
329	//   - tokenPath: token contract path whose accrual bucket is updated
330	//   - epoch: accrual epoch receiving the fee amount
331	//   - amount: fee amount in token base units to add to that epoch bucket
332	//
333	// Returns:
334	//   - err: nil when the bucket is stored; an error for invalid realm context or KV-store failure
335	AddAccrualBucket(_ int, rlm realm, tokenPath string, epoch int64, amount int64) error
336
337	// RemoveAccrualBuckets removes specified epoch buckets for one token.
338	//
339	// Parameters:
340	//   - _: cross-call discriminator; callers pass 0
341	//   - rlm: propagated protocol_fee realm context required for the authorized store write
342	//   - tokenPath: token contract path whose buckets are removed
343	//   - epochs: accrual epoch numbers to remove; an empty result removes no buckets
344	//
345	// Returns:
346	//   - err: nil when removal succeeds; an error for invalid realm context or KV-store failure
347	RemoveAccrualBuckets(_ int, rlm realm, tokenPath string, epochs []int64) error
348
349	// HasAccrualPendingTokensStoreKey reports whether the pending-token index key exists.
350	//
351	// Returns:
352	//   - exists: true when the index of tokens with pending buckets is present
353	HasAccrualPendingTokensStoreKey() bool
354
355	// InitializeAccrualPendingTokens creates the empty pending-token index.
356	//
357	// Parameters:
358	//   - _: cross-call discriminator; callers pass 0
359	//   - rlm: propagated protocol_fee realm context required for the authorized store write
360	//
361	// Returns:
362	//   - err: nil when initialization succeeds; an error for invalid realm context or KV-store failure
363	InitializeAccrualPendingTokens(_ int, rlm realm) error
364
365	// GetAccrualPendingTokens returns token paths indexed as owning pending buckets.
366	//
367	// Returns:
368	//   - tokenPaths: token contract paths present in the pending-token index
369	GetAccrualPendingTokens() []string
370
371	// AddAccrualPendingToken marks a token path as owning at least one pending bucket.
372	//
373	// Parameters:
374	//   - _: cross-call discriminator; callers pass 0
375	//   - rlm: propagated protocol_fee realm context required for the authorized store write
376	//   - tokenPath: token contract path to add to the pending-token index
377	//
378	// Returns:
379	//   - err: nil when added or already present; an error for invalid realm context or KV-store failure
380	AddAccrualPendingToken(_ int, rlm realm, tokenPath string) error
381
382	// RemoveAccrualPendingToken removes a token path from the pending-token index when present.
383	//
384	// Parameters:
385	//   - _: cross-call discriminator; callers pass 0
386	//   - rlm: propagated protocol_fee realm context required for the authorized store write
387	//   - tokenPath: token contract path to remove after its pending buckets are consumed
388	//
389	// Returns:
390	//   - err: nil when removed or already absent; an error for invalid realm context or KV-store failure
391	RemoveAccrualPendingToken(_ int, rlm realm, tokenPath string) error
392}

1type StoreKey string