types.gno
64.21 Kb · 1616 lines
1package staker
2
3import (
4 u256 "gno.land/p/gnoswap/uint256/v1"
5 rotree "gno.land/p/nt/bptree/rotree/v0"
6 bptree "gno.land/p/nt/bptree/v0"
7)
8
9type IStaker interface {
10 IStakerManager
11 IStakerGetter
12 Render(path string) string
13}
14
15type IStakerManager interface {
16 // StakeToken stakes an LP position NFT, transfers custody to the staker, and
17 // starts internal GNS and eligible external reward accounting.
18 //
19 // Parameters:
20 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
21 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
22 // - positionId: LP position NFT identifier whose liquidity will be staked.
23 // - referrer: Optional referral address or identifier supplied for referral tracking.
24 //
25 // Returns:
26 // - poolPath: Canonical token0:token1:fee path of the pool containing the staked position.
27 //
28 StakeToken(_ int, rlm realm, positionId uint64, referrer string) string
29
30 // UnStakeToken records the position's exit checkpoint, removes it from active
31 // staking, and returns the NFT to its owner.
32 //
33 // Parameters:
34 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
35 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
36 // - positionId: LP position NFT identifier to remove from staking.
37 //
38 // Returns:
39 // - poolPath: Canonical pool path from the position's active deposit.
40 //
41 UnStakeToken(_ int, rlm realm, positionId uint64) string
42
43 // CollectReward settles both GNS emission and all currently payable external
44 // incentive rewards for a live deposit or an unstaked exit checkpoint.
45 //
46 // Parameters:
47 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
48 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
49 // - positionId: LP position NFT identifier, or an identifier with an exit checkpoint.
50 //
51 // Returns:
52 // - internalRewardToUser: Decimal string for the GNS amount transferred to the position owner.
53 // - internalRewardPenalty: Decimal string for the GNS warm-up penalty sent to the community pool.
54 // - externalRewards: Map keyed by reward-token path containing gross external reward amounts before the staking fee.
55 // - externalPenalties: Map keyed by reward-token path containing warm-up penalties retained by each incentive.
56 //
57 CollectReward(_ int, rlm realm, positionId uint64) (string, string, map[string]int64, map[string]int64)
58
59 // CollectEmissionReward settles only the internal GNS emission for a live
60 // deposit or an unstaked exit checkpoint.
61 //
62 // Parameters:
63 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
64 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
65 // - positionId: LP position NFT identifier, or an identifier with an exit checkpoint.
66 //
67 // Returns:
68 // - rewardToUser: GNS amount transferred to the position owner.
69 // - rewardPenalty: GNS warm-up penalty transferred to the community pool.
70 //
71 CollectEmissionReward(_ int, rlm realm, positionId uint64) (int64, int64)
72
73 // CollectExternalIncentiveReward settles one external incentive for a live
74 // deposit or an unstaked exit checkpoint.
75 //
76 // Parameters:
77 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
78 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
79 // - positionId: LP position NFT identifier, or an identifier with an exit checkpoint.
80 // - incentiveId: External incentive identifier to settle for the position.
81 //
82 // Returns:
83 // - rewardAmount: Gross reward-token amount calculated for the incentive before the staking fee.
84 // - penaltyAmount: Warm-up penalty amount retained by the incentive rather than sent to the owner.
85 //
86 CollectExternalIncentiveReward(_ int, rlm realm, positionId uint64, incentiveId string) (int64, int64)
87
88 // SetPoolTier assigns an internal GNS-emission tier to an existing pool.
89 //
90 // Parameters:
91 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
92 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
93 // - poolPath: Canonical pool path whose emission tier is being assigned.
94 // - tier: Pool tier index in [0, AllTierCount); zero removes the pool from the internal emission target.
95 //
96 SetPoolTier(_ int, rlm realm, poolPath string, tier uint64)
97
98 // ChangePoolTier changes the internal GNS-emission tier of an existing pool.
99 //
100 // Parameters:
101 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
102 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
103 // - poolPath: Canonical pool path whose emission tier is being changed.
104 // - tier: Replacement pool tier index in [0, AllTierCount); zero removes the pool from the internal emission target.
105 //
106 ChangePoolTier(_ int, rlm realm, poolPath string, tier uint64)
107
108 // RemovePoolTier removes a pool from the internal GNS-emission tier system.
109 //
110 // Parameters:
111 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
112 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
113 // - poolPath: Canonical pool path to remove from tier membership.
114 //
115 RemovePoolTier(_ int, rlm realm, poolPath string)
116
117 // CreateExternalIncentive funds and registers an external reward program for a
118 // target pool over the requested Unix-time interval.
119 //
120 // Parameters:
121 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
122 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
123 // - targetPoolPath: Canonical pool path whose positions may earn the incentive.
124 // - rewardToken: Registered token path used to pay the external reward.
125 // - rewardAmount: Total reward-token amount deposited for the incentive.
126 // - startTimestamp: Inclusive Unix-second timestamp at which rewards begin accruing.
127 // - endTimestamp: Unix-second timestamp at which the reward interval ends.
128 //
129 CreateExternalIncentive(
130 _ int,
131 rlm realm,
132 targetPoolPath string,
133 rewardToken string,
134 rewardAmount int64,
135 startTimestamp int64,
136 endTimestamp int64,
137 )
138
139 // EndExternalIncentive finalizes an ended external incentive and refunds its
140 // remaining reward tokens and deposited GNS to the requested address.
141 //
142 // Parameters:
143 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
144 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
145 // - targetPoolPath: Canonical pool path containing the incentive.
146 // - incentiveId: Unique external incentive identifier to finalize.
147 // - refundAddress: Address receiving refundable reward tokens and the GNS deposit.
148 //
149 EndExternalIncentive(_ int, rlm realm, targetPoolPath, incentiveId string, refundAddress address)
150
151 // CancelExternalIncentive removes an external incentive before it starts and
152 // refunds the available funded amounts to its creator.
153 //
154 // Parameters:
155 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
156 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
157 // - targetPoolPath: Canonical pool path containing the incentive.
158 // - incentiveId: Unique external incentive identifier to cancel.
159 //
160 CancelExternalIncentive(_ int, rlm realm, targetPoolPath, incentiveId string)
161
162 // CollectExternalIncentivePenalty transfers accumulated warm-up penalties
163 // from an ended external incentive to the requested address.
164 //
165 // Parameters:
166 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
167 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
168 // - targetPoolPath: Canonical pool path containing the incentive.
169 // - incentiveId: Ended external incentive identifier whose penalties are collected.
170 // - refundAddress: Address receiving the collected reward-token penalty.
171 //
172 // Returns:
173 // - penaltyAmount: Amount actually transferred, capped by the staker's available balance and zero when no penalty is accrued.
174 //
175 CollectExternalIncentivePenalty(_ int, rlm realm, targetPoolPath, incentiveId string, refundAddress address) int64
176
177 // AddToken adds a registered non-default token path to the external-incentive allowlist.
178 //
179 // Parameters:
180 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
181 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
182 // - tokenPath: Registered token contract path to allow for new external incentives.
183 //
184 AddToken(_ int, rlm realm, tokenPath string)
185
186 // RemoveToken removes a non-default token path from the external-incentive allowlist.
187 //
188 // Parameters:
189 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
190 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
191 // - tokenPath: Allowed token contract path to remove from future incentive creation.
192 //
193 RemoveToken(_ int, rlm realm, tokenPath string)
194
195 // SetDeniedRewardToken sets or clears the operational deny flag for a reward token.
196 // The flag prevents new incentives while leaving already-created incentives collectible.
197 //
198 // Parameters:
199 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
200 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
201 // - tokenPath: Reward-token contract path whose deny flag is being changed.
202 // - denied: true to deny new incentives for the token, or false to remove the denial.
203 //
204 SetDeniedRewardToken(_ int, rlm realm, tokenPath string, denied bool)
205
206 // SetWarmUp changes the duration associated with one of the fixed warm-up ratios.
207 //
208 // Parameters:
209 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
210 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
211 // - pct: Warm-up completion ratio selector; supported values are 30, 50, 70, and 100.
212 // - timeDuration: Warm-up duration in seconds for the selected ratio; finite tiers are bounded by 365 days.
213 //
214 SetWarmUp(_ int, rlm realm, pct, timeDuration int64)
215
216 // SetDepositGnsAmount updates the GNS deposit required when creating an external incentive.
217 //
218 // Parameters:
219 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
220 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
221 // - amount: Nonnegative GNS amount required as each external-incentive deposit.
222 //
223 SetDepositGnsAmount(_ int, rlm realm, amount int64)
224
225 // SetMinimumRewardAmount updates the default minimum reward amount for external incentives.
226 //
227 // Parameters:
228 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
229 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
230 // - amount: Nonnegative reward-token amount used when no token-specific minimum exists.
231 //
232 SetMinimumRewardAmount(_ int, rlm realm, amount int64)
233
234 // SetTokenMinimumRewardAmount sets or removes a token-specific external-incentive minimum.
235 //
236 // Parameters:
237 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
238 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
239 // - paramsStr: Colon-delimited tokenPath:amount string; amount 0 removes that token's override.
240 //
241 SetTokenMinimumRewardAmount(_ int, rlm realm, paramsStr string)
242
243 // SetUnStakingFee updates the fee charged against collected staking rewards.
244 //
245 // Parameters:
246 // - _: Leading integer discriminator for implementation forwarding; proxy methods pass 0.
247 // - rlm: Current realm context forwarded unchanged by the staker proxy (0, cur, ...).
248 // - fee: Unstaking fee rate in basis points, where 10,000 basis points represents 100%.
249 //
250 SetUnStakingFee(_ int, rlm realm, fee uint64)
251}
252
253type IStakerGetter interface {
254 // GetPool returns the registered pool for a canonical pool path.
255 //
256 // Parameters:
257 // - poolPath: Canonical token0:token1:fee path identifying the pool.
258 //
259 // Returns:
260 // - pool: Pointer to the registered pool; nil when lookup fails.
261 // - err: Nil on success, or an error when the pool is absent or cannot be decoded.
262 //
263 GetPool(poolPath string) (*Pool, error)
264
265 // GetPoolRewardCaches exposes a read-only tree of a pool's reward-cache snapshots,
266 // keyed by encoded block timestamps.
267 //
268 // Parameters:
269 // - poolPath: Canonical pool path whose reward cache is requested.
270 //
271 // Returns:
272 // - rewardCaches: Read-only reward-cache tree, or nil when the pool does not exist.
273 //
274 GetPoolRewardCaches(poolPath string) *rotree.ReadOnlyTree
275
276 // GetPoolIncentives exposes a read-only tree of a pool's external incentives,
277 // keyed by incentive identifier.
278 //
279 // Parameters:
280 // - poolPath: Canonical pool path whose incentives are requested.
281 //
282 // Returns:
283 // - incentives: Read-only external-incentive tree, or nil when the pool does not exist.
284 //
285 GetPoolIncentives(poolPath string) *rotree.ReadOnlyTree
286
287 // GetPoolGlobalRewardRatioAccumulations exposes a read-only tree of global
288 // reward-ratio snapshots keyed by encoded block timestamps.
289 //
290 // Parameters:
291 // - poolPath: Canonical pool path whose global accumulations are requested.
292 //
293 // Returns:
294 // - accumulations: Read-only global reward-ratio tree, or nil when the pool does not exist.
295 //
296 GetPoolGlobalRewardRatioAccumulations(poolPath string) *rotree.ReadOnlyTree
297
298 // GetPoolHistoricalTicks exposes a read-only tree of historical pool ticks
299 // keyed by encoded block timestamps.
300 //
301 // Parameters:
302 // - poolPath: Canonical pool path whose historical ticks are requested.
303 //
304 // Returns:
305 // - historicalTicks: Read-only historical-tick tree, or nil when the pool does not exist.
306 //
307 GetPoolHistoricalTicks(poolPath string) *rotree.ReadOnlyTree
308
309 // GetDeposit returns the staker deposit associated with an LP position NFT.
310 //
311 // Parameters:
312 // - lpTokenId: LP position NFT identifier used as the deposit key.
313 //
314 // Returns:
315 // - deposit: Stored deposit for the position; nil when lookup fails.
316 // - err: Nil on success, or an error when no deposit exists for the identifier.
317 //
318 GetDeposit(lpTokenId uint64) (*Deposit, error)
319
320 // CollectableEmissionReward calculates the currently claimable internal GNS
321 // emission without mutating the position.
322 //
323 // Parameters:
324 // - positionId: LP position identifier for a live deposit or exit checkpoint.
325 //
326 // Returns:
327 // - reward: Claimable internal GNS amount at the current chain time and height.
328 // - err: Nil on success, or an error when the position is neither staked nor checkpointed or calculation fails.
329 //
330 CollectableEmissionReward(positionId uint64) (int64, error)
331
332 // CollectableExternalIncentiveReward calculates the currently claimable amount
333 // for one external incentive without mutating the position.
334 //
335 // Parameters:
336 // - positionId: LP position identifier for a live deposit or exit checkpoint.
337 // - incentiveId: External incentive identifier whose reward is queried.
338 //
339 // Returns:
340 // - reward: Claimable gross reward-token amount, or zero when that incentive contributes no reward.
341 // - err: Nil on success, or an error when the position or reward calculation is invalid.
342 //
343 CollectableExternalIncentiveReward(positionId uint64, incentiveId string) (int64, error)
344
345 // GetCreatedHeightOfIncentive returns the chain height recorded when an incentive was created.
346 //
347 // Parameters:
348 // - poolPath: Pool path containing the incentive.
349 // - incentiveId: External incentive identifier to inspect.
350 //
351 // Returns:
352 // - createdHeight: Chain height persisted at incentive creation.
353 // - err: Nil on success, or an error when the pool or incentive does not exist.
354 //
355 GetCreatedHeightOfIncentive(poolPath string, incentiveId string) (int64, error)
356
357 // GetIncentiveCreatedTimestamp returns the Unix-second creation time of an incentive.
358 //
359 // Parameters:
360 // - poolPath: Pool path containing the incentive.
361 // - incentiveId: External incentive identifier to inspect.
362 //
363 // Returns:
364 // - createdTimestamp: Unix-second timestamp recorded at creation.
365 // - err: Nil on success, or an error when the pool or incentive does not exist.
366 //
367 GetIncentiveCreatedTimestamp(poolPath string, incentiveId string) (int64, error)
368
369 // GetIncentiveTotalRewardAmount returns the amount originally funded for an incentive.
370 //
371 // Parameters:
372 // - poolPath: Pool path containing the incentive.
373 // - incentiveId: External incentive identifier to inspect.
374 //
375 // Returns:
376 // - totalRewardAmount: Original reward-token amount funded at creation.
377 // - err: Nil on success, or an error when the pool or incentive does not exist.
378 //
379 GetIncentiveTotalRewardAmount(poolPath string, incentiveId string) (int64, error)
380
381 // GetIncentiveDistributedRewardAmount returns the reward amount already
382 // distributed to positions or refunded when the incentive ended.
383 //
384 // Parameters:
385 // - poolPath: Pool path containing the incentive.
386 // - incentiveId: External incentive identifier to inspect.
387 //
388 // Returns:
389 // - distributedRewardAmount: Cumulative distributed or refunded reward-token amount.
390 // - err: Nil on success, or an error when the pool or incentive does not exist.
391 //
392 GetIncentiveDistributedRewardAmount(poolPath string, incentiveId string) (int64, error)
393
394 // GetIncentiveRemainingRewardAmount returns the current undistributed reward balance.
395 //
396 // Parameters:
397 // - poolPath: Pool path containing the incentive.
398 // - incentiveId: External incentive identifier to inspect.
399 //
400 // Returns:
401 // - remainingRewardAmount: Reward-token amount still held for future distribution or refund.
402 // - err: Nil on success, or an error when the pool or incentive does not exist.
403 //
404 GetIncentiveRemainingRewardAmount(poolPath string, incentiveId string) (int64, error)
405
406 // GetIncentiveAccumulatedPenaltyAmount returns warm-up penalties accumulated
407 // from collections for an incentive.
408 //
409 // Parameters:
410 // - poolPath: Pool path containing the incentive.
411 // - incentiveId: External incentive identifier to inspect.
412 //
413 // Returns:
414 // - penaltyAmount: Reward-token penalty amount accumulated for later collection.
415 // - err: Nil on success, or an error when the pool or incentive does not exist.
416 //
417 GetIncentiveAccumulatedPenaltyAmount(poolPath string, incentiveId string) (int64, error)
418
419 // GetIncentiveDepositGnsAmount returns the GNS deposit locked by an incentive.
420 //
421 // Parameters:
422 // - poolPath: Pool path containing the incentive.
423 // - incentiveId: External incentive identifier to inspect.
424 //
425 // Returns:
426 // - depositGnsAmount: GNS amount deposited as the incentive's collateral.
427 // - err: Nil on success, or an error when the pool or incentive does not exist.
428 //
429 GetIncentiveDepositGnsAmount(poolPath string, incentiveId string) (int64, error)
430
431 // GetIncentiveRefunded reports whether the incentive has been finalized and refunded.
432 //
433 // Parameters:
434 // - poolPath: Pool path containing the incentive.
435 // - incentiveId: External incentive identifier to inspect.
436 //
437 // Returns:
438 // - refunded: True after EndExternalIncentive has marked the incentive refunded; false otherwise.
439 // - err: Nil on success, or an error when the pool or incentive does not exist.
440 //
441 GetIncentiveRefunded(poolPath string, incentiveId string) (bool, error)
442
443 // IsIncentiveActive reports whether an unrefunded incentive is within its
444 // inclusive start/end Unix-second interval at the current time.
445 //
446 // Parameters:
447 // - poolPath: Pool path containing the incentive.
448 // - incentiveId: External incentive identifier to inspect.
449 //
450 // Returns:
451 // - active: True only when the current time is between the incentive bounds and it is not refunded.
452 // - err: Nil on success, or an error when the pool or incentive does not exist.
453 //
454 IsIncentiveActive(poolPath string, incentiveId string) (bool, error)
455
456 // GetDepositExternalRewardLastCollectTimestamp returns the last collection
457 // timestamp for one deposit/incentive pair.
458 //
459 // Parameters:
460 // - lpTokenId: LP position NFT identifier owning the external reward cursor.
461 // - incentiveId: External incentive identifier whose cursor is requested.
462 //
463 // Returns:
464 // - timestamp: Unix-second cursor, falling back to stake time when the incentive has never been collected.
465 // - err: Nil on success, or an error when the deposit does not exist.
466 //
467 GetDepositExternalRewardLastCollectTimestamp(lpTokenId uint64, incentiveId string) (int64, error)
468
469 // GetDepositGnsAmount returns the configured GNS deposit required per external incentive.
470 //
471 // Returns:
472 // - amount: Current required GNS deposit in token units.
473 //
474 GetDepositGnsAmount() int64
475
476 // GetDepositInternalRewardLastCollectTimestamp returns the stored internal
477 // reward collection cursor for a deposit.
478 //
479 // Parameters:
480 // - lpTokenId: LP position NFT identifier owning the internal reward cursor.
481 //
482 // Returns:
483 // - timestamp: Unix-second cursor, which is zero before the first internal collection.
484 // - err: Nil on success, or an error when the deposit does not exist.
485 //
486 GetDepositInternalRewardLastCollectTimestamp(lpTokenId uint64) (int64, error)
487
488 // GetDepositCollectedInternalReward returns cumulative internal reward recorded for a deposit.
489 //
490 // Parameters:
491 // - lpTokenId: LP position NFT identifier whose collection total is requested.
492 //
493 // Returns:
494 // - amount: Cumulative GNS amount recorded as collected for the deposit.
495 // - err: Nil on success, or an error when the deposit does not exist.
496 //
497 GetDepositCollectedInternalReward(lpTokenId uint64) (int64, error)
498
499 // GetDepositCollectedExternalReward returns the cumulative amount recorded
500 // for one deposit/incentive pair.
501 //
502 // Parameters:
503 // - lpTokenId: LP position NFT identifier whose collection total is requested.
504 // - incentiveId: External incentive identifier for the collection total.
505 //
506 // Returns:
507 // - amount: Cumulative gross reward-token amount recorded for that incentive.
508 // - err: Nil on success, or an error when the deposit does not exist.
509 //
510 GetDepositCollectedExternalReward(lpTokenId uint64, incentiveId string) (int64, error)
511
512 // GetDepositLiquidity returns the full-precision liquidity assigned to a deposit.
513 //
514 // Parameters:
515 // - lpTokenId: LP position NFT identifier whose liquidity is requested.
516 //
517 // Returns:
518 // - liquidity: 256-bit liquidity value stored in the deposit.
519 // - err: Nil on success, or an error when the deposit does not exist.
520 //
521 GetDepositLiquidity(lpTokenId uint64) (*u256.Uint, error)
522
523 // GetDepositLiquidityAsString returns the decimal string form of a deposit's liquidity.
524 //
525 // Parameters:
526 // - lpTokenId: LP position NFT identifier whose liquidity is requested.
527 //
528 // Returns:
529 // - liquidity: Decimal representation of the stored 256-bit liquidity.
530 // - err: Nil on success, or an error when the deposit does not exist.
531 //
532 GetDepositLiquidityAsString(lpTokenId uint64) (string, error)
533
534 // GetDepositOwner returns the address recorded as owner of a deposit.
535 //
536 // Parameters:
537 // - lpTokenId: LP position NFT identifier whose owner is requested.
538 //
539 // Returns:
540 // - owner: Address recorded when the position was staked.
541 // - err: Nil on success, or an error when the deposit does not exist.
542 //
543 GetDepositOwner(lpTokenId uint64) (address, error)
544
545 // GetDepositStakeTime returns the Unix-second timestamp when a position was staked.
546 //
547 // Parameters:
548 // - lpTokenId: LP position NFT identifier whose stake time is requested.
549 //
550 // Returns:
551 // - stakeTime: Unix-second timestamp stored in the deposit.
552 // - err: Nil on success, or an error when the deposit does not exist.
553 //
554 GetDepositStakeTime(lpTokenId uint64) (int64, error)
555
556 // GetDepositTargetPoolPath returns the pool path recorded for a deposit.
557 //
558 // Parameters:
559 // - lpTokenId: LP position NFT identifier whose target pool is requested.
560 //
561 // Returns:
562 // - poolPath: Canonical target pool path recorded in the deposit.
563 // - err: Nil on success, or an error when the deposit does not exist.
564 //
565 GetDepositTargetPoolPath(lpTokenId uint64) (string, error)
566
567 // GetDepositTickLower returns the lower concentrated-liquidity tick of a deposit.
568 //
569 // Parameters:
570 // - lpTokenId: LP position NFT identifier whose lower tick is requested.
571 //
572 // Returns:
573 // - tickLower: Signed lower tick stored in the deposit.
574 // - err: Nil on success, or an error when the deposit does not exist.
575 //
576 GetDepositTickLower(lpTokenId uint64) (int32, error)
577
578 // GetDepositTickUpper returns the upper concentrated-liquidity tick of a deposit.
579 //
580 // Parameters:
581 // - lpTokenId: LP position NFT identifier whose upper tick is requested.
582 //
583 // Returns:
584 // - tickUpper: Signed upper tick stored in the deposit.
585 // - err: Nil on success, or an error when the deposit does not exist.
586 //
587 GetDepositTickUpper(lpTokenId uint64) (int32, error)
588
589 // GetDepositWarmUp returns the warm-up records currently attached to a deposit.
590 //
591 // Parameters:
592 // - lpTokenId: LP position NFT identifier whose warm-up records are requested.
593 //
594 // Returns:
595 // - warmups: Warm-up schedule entries stored for the deposit.
596 // - err: Nil on success, or an error when the deposit does not exist.
597 //
598 GetDepositWarmUp(lpTokenId uint64) ([]Warmup, error)
599
600 // GetDepositExternalIncentiveIdList returns external incentive identifiers
601 // currently tracked by a deposit.
602 //
603 // Parameters:
604 // - lpTokenId: LP position NFT identifier whose incentive index is requested.
605 //
606 // Returns:
607 // - incentiveIds: External incentive IDs attached to the deposit.
608 // - err: Nil on success, or an error when the deposit does not exist.
609 //
610 GetDepositExternalIncentiveIdList(lpTokenId uint64) ([]string, error)
611
612 // GetExternalIncentiveByPoolPath returns all stored external incentives targeting a pool.
613 //
614 // Parameters:
615 // - poolPath: Canonical pool path used to filter incentive records.
616 //
617 // Returns:
618 // - incentives: Matching external incentive records, possibly an empty slice.
619 // - err: Nil on success, or an error when a stored record has an invalid type.
620 //
621 GetExternalIncentiveByPoolPath(poolPath string) ([]ExternalIncentive, error)
622
623 // GetIncentiveEndTimestamp returns the Unix-second end time of an incentive.
624 //
625 // Parameters:
626 // - poolPath: Pool path containing the incentive.
627 // - incentiveId: External incentive identifier to inspect.
628 //
629 // Returns:
630 // - endTimestamp: Inclusive Unix-second end bound recorded for the incentive.
631 // - err: Nil on success, or an error when the pool or incentive does not exist.
632 //
633 GetIncentiveEndTimestamp(poolPath string, incentiveId string) (int64, error)
634
635 // GetIncentiveCreator returns the address that created and funded an incentive.
636 //
637 // Parameters:
638 // - poolPath: Pool path containing the incentive.
639 // - incentiveId: External incentive identifier to inspect.
640 //
641 // Returns:
642 // - creator: Address recorded as the incentive creator.
643 // - err: Nil on success, or an error when the pool or incentive does not exist.
644 //
645 GetIncentiveCreator(poolPath string, incentiveId string) (address, error)
646
647 // GetIncentiveRewardAmount returns the remaining reward amount as a 256-bit unsigned value.
648 //
649 // Parameters:
650 // - poolPath: Pool path containing the incentive.
651 // - incentiveId: External incentive identifier to inspect.
652 //
653 // Returns:
654 // - rewardAmount: Remaining reward-token amount represented as a uint256 value.
655 // - err: Nil on success, or an error when the pool or incentive does not exist.
656 //
657 GetIncentiveRewardAmount(poolPath string, incentiveId string) (*u256.Uint, error)
658
659 // GetIncentiveRewardAmountAsString returns the decimal string form of the remaining reward.
660 //
661 // Parameters:
662 // - poolPath: Pool path containing the incentive.
663 // - incentiveId: External incentive identifier to inspect.
664 //
665 // Returns:
666 // - rewardAmount: Decimal representation of the remaining reward-token amount.
667 // - err: Nil on success, or an error when the pool or incentive does not exist.
668 //
669 GetIncentiveRewardAmountAsString(poolPath string, incentiveId string) (string, error)
670
671 // GetIncentiveRewardPerSecondX128 returns the Q128-scaled reward rate of an incentive.
672 //
673 // Parameters:
674 // - poolPath: Pool path containing the incentive.
675 // - incentiveId: External incentive identifier to inspect.
676 //
677 // Returns:
678 // - rewardPerSecondX128: Reward-per-second rate scaled by 2^128 to preserve precision.
679 // - err: Nil on success, or an error when the pool or incentive does not exist.
680 //
681 GetIncentiveRewardPerSecondX128(poolPath string, incentiveId string) (*u256.Uint, error)
682
683 // GetIncentiveRewardToken returns the token path used to pay an incentive.
684 //
685 // Parameters:
686 // - poolPath: Pool path containing the incentive.
687 // - incentiveId: External incentive identifier to inspect.
688 //
689 // Returns:
690 // - rewardToken: Registered reward-token contract path.
691 // - err: Nil on success, or an error when the pool or incentive does not exist.
692 //
693 GetIncentiveRewardToken(poolPath string, incentiveId string) (string, error)
694
695 // GetIncentiveStartTimestamp returns the Unix-second start time of an incentive.
696 //
697 // Parameters:
698 // - poolPath: Pool path containing the incentive.
699 // - incentiveId: External incentive identifier to inspect.
700 //
701 // Returns:
702 // - startTimestamp: Inclusive Unix-second start bound recorded for the incentive.
703 // - err: Nil on success, or an error when the pool or incentive does not exist.
704 //
705 GetIncentiveStartTimestamp(poolPath string, incentiveId string) (int64, error)
706
707 // GetMinimumRewardAmount returns the default minimum reward amount for external incentives.
708 //
709 // Returns:
710 // - amount: Default minimum reward-token amount used when no token-specific override exists.
711 //
712 GetMinimumRewardAmount() int64
713
714 // GetMinimumRewardAmountForToken returns a token-specific minimum, falling
715 // back to the default minimum when no override is configured.
716 //
717 // Parameters:
718 // - tokenPath: Reward-token contract path whose minimum is requested.
719 //
720 // Returns:
721 // - amount: Token-specific minimum when configured, otherwise the default minimum.
722 //
723 GetMinimumRewardAmountForToken(tokenPath string) int64
724
725 // GetPoolStakedLiquidity returns the current total staked liquidity as a decimal string.
726 //
727 // Parameters:
728 // - poolPath: Canonical pool path whose active staked liquidity is requested.
729 //
730 // Returns:
731 // - liquidity: Decimal string for current staked liquidity, or zero when the pool has no value.
732 // - err: Nil on success, or an error when the pool does not exist.
733 //
734 GetPoolStakedLiquidity(poolPath string) (string, error)
735
736 // GetPoolsByTier lists pool paths currently assigned to an internal emission tier.
737 //
738 // Parameters:
739 // - tier: Tier number used to filter pool membership; tier zero returns an empty list.
740 //
741 // Returns:
742 // - poolPaths: Pool paths assigned to the requested tier.
743 // - err: Nil on success, or an error when stored tier membership cannot be decoded.
744 //
745 GetPoolsByTier(tier uint64) ([]string, error)
746
747 // GetPoolReward returns the current per-second GNS reward for a tier.
748 //
749 // Parameters:
750 // - tier: Supported nonzero tier whose reward rate is requested.
751 //
752 // Returns:
753 // - reward: Current tier reward amount per second.
754 // - err: Nil on success, or an invalid-tier error for zero or unsupported tiers.
755 //
756 GetPoolReward(tier uint64) (int64, error)
757
758 // GetPoolTier returns the internal emission tier currently assigned to a pool.
759 //
760 // Parameters:
761 // - poolPath: Canonical pool path whose tier is requested.
762 //
763 // Returns:
764 // - tier: Assigned tier number; zero denotes no internal emission tier.
765 //
766 GetPoolTier(poolPath string) uint64
767
768 // GetPoolTierCount returns the number of pools assigned to a tier.
769 //
770 // Parameters:
771 // - tier: Tier number whose membership count is requested; tier zero has count zero.
772 //
773 // Returns:
774 // - count: Current number of pools in the requested tier.
775 //
776 GetPoolTierCount(tier uint64) uint64
777
778 // GetPoolTierRatio returns the reward ratio configured for a pool's current tier.
779 //
780 // Parameters:
781 // - poolPath: Canonical pool path whose current tier ratio is requested.
782 //
783 // Returns:
784 // - ratio: Current reward ratio for the pool's assigned tier.
785 // - err: Nil on success, or an invalid-tier error when the tier has no ratio.
786 //
787 GetPoolTierRatio(poolPath string) (uint64, error)
788
789 // GetSpecificTokenMinimumRewardAmount looks up only an explicitly configured
790 // token-specific minimum and does not apply the default fallback.
791 //
792 // Parameters:
793 // - tokenPath: Reward-token contract path whose override is requested.
794 //
795 // Returns:
796 // - amount: Configured token-specific minimum, or zero when absent.
797 // - found: True when an explicit override exists; false when the default should be used.
798 //
799 GetSpecificTokenMinimumRewardAmount(tokenPath string) (int64, bool)
800
801 // GetTargetPoolPathByIncentiveId returns the pool path targeted by an incentive.
802 //
803 // Parameters:
804 // - poolPath: Pool path containing the incentive record.
805 // - incentiveId: External incentive identifier to inspect.
806 //
807 // Returns:
808 // - targetPoolPath: Pool path recorded as the incentive target.
809 // - err: Nil on success, or an error when the pool or incentive does not exist.
810 //
811 GetTargetPoolPathByIncentiveId(poolPath string, incentiveId string) (string, error)
812
813 // GetUnstakingFee returns the current reward fee rate in basis points.
814 //
815 // Returns:
816 // - fee: Current unstaking fee, where 10,000 basis points represents 100%.
817 //
818 GetUnstakingFee() uint64
819
820 // GetPendingProtocolFees returns pending protocol-fee amounts keyed by token path.
821 //
822 // Returns:
823 // - fees: Map from reward-token path to amount awaiting protocol-fee settlement.
824 //
825 GetPendingProtocolFees() map[string]int64
826
827 // HasUnstakedPosition reports whether an exit checkpoint with uncollected
828 // rewards exists for a position.
829 //
830 // Parameters:
831 // - positionId: LP position identifier whose exit checkpoint is queried.
832 //
833 // Returns:
834 // - exists: True when an uncollected exit checkpoint is present.
835 //
836 HasUnstakedPosition(positionId uint64) bool
837
838 // GetUnstakedPositionExitTime returns when an exit checkpoint stopped accruing rewards.
839 //
840 // Parameters:
841 // - positionId: LP position identifier whose checkpoint is requested.
842 //
843 // Returns:
844 // - exitTime: Unix-second timestamp at which the position was unstaked.
845 // - err: Nil on success, or an error when no uncollected checkpoint exists.
846 //
847 GetUnstakedPositionExitTime(positionId uint64) (int64, error)
848
849 // GetUnstakedPositionPendingIncentives returns external incentive IDs still
850 // owed by an exit checkpoint.
851 //
852 // Parameters:
853 // - positionId: LP position identifier whose checkpoint is requested.
854 //
855 // Returns:
856 // - incentiveIds: External incentive IDs pending collection for the checkpoint.
857 // - err: Nil on success, or an error when no uncollected checkpoint exists.
858 //
859 GetUnstakedPositionPendingIncentives(positionId uint64) ([]string, error)
860
861 // GetUncollectedIncentiveCount returns the number of exit checkpoints still
862 // carrying an uncollected claim for an incentive.
863 //
864 // Parameters:
865 // - incentiveId: External incentive identifier whose checkpoint count is requested.
866 //
867 // Returns:
868 // - count: Number of uncollected exit-position claims for the incentive.
869 //
870 GetUncollectedIncentiveCount(incentiveId string) int64
871
872 // IsStaked reports whether a live deposit exists for a position.
873 //
874 // Parameters:
875 // - positionId: LP position identifier to query.
876 //
877 // Returns:
878 // - staked: True when the position is present in active deposits.
879 //
880 IsStaked(positionId uint64) bool
881
882 // GetTotalEmissionSent returns cumulative GNS emission sent or accounted for.
883 //
884 // Returns:
885 // - amount: Cumulative internal GNS emission amount recorded by the staker.
886 //
887 GetTotalEmissionSent() int64
888
889 // GetAllowedTokens returns token paths approved for new external incentives.
890 //
891 // Returns:
892 // - tokenPaths: Registered external-incentive token paths currently allowed.
893 //
894 GetAllowedTokens() []string
895
896 // GetDeniedRewardTokens returns token paths denied for new external incentives.
897 //
898 // Returns:
899 // - tokenPaths: Reward-token paths on the operational deny list.
900 //
901 GetDeniedRewardTokens() []string
902
903 // GetWarmupTemplate returns the current warm-up schedule used for new deposits.
904 //
905 // Returns:
906 // - warmups: Ordered warm-up entries defining reward-release ratios and durations.
907 //
908 GetWarmupTemplate() []Warmup
909}
910
911type IStakerStore interface {
912 // HasDepositGnsAmountStoreKey reports whether the configured GNS-deposit key exists.
913 //
914 // Returns:
915 // - exists: True when the depositGnsAmount key is present in persistent storage.
916 //
917 HasDepositGnsAmountStoreKey() bool
918
919 // GetDepositGnsAmount returns the stored GNS deposit required per external incentive.
920 //
921 // Returns:
922 // - amount: Persisted GNS amount in token units; storage read or type failures panic.
923 //
924 GetDepositGnsAmount() int64
925
926 // SetDepositGnsAmount persists the GNS deposit required per external incentive.
927 //
928 // Parameters:
929 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
930 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
931 // - amount: GNS amount in token units to persist.
932 //
933 // Returns:
934 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
935 //
936 SetDepositGnsAmount(_ int, rlm realm, amount int64) error
937
938 // HasMinimumRewardAmountStoreKey reports whether the default minimum-reward key exists.
939 //
940 // Returns:
941 // - exists: True when the minimumRewardAmount key is present in persistent storage.
942 //
943 HasMinimumRewardAmountStoreKey() bool
944
945 // GetMinimumRewardAmount returns the default minimum external-incentive reward.
946 //
947 // Returns:
948 // - amount: Persisted default reward-token minimum; storage read or type failures panic.
949 //
950 GetMinimumRewardAmount() int64
951
952 // SetMinimumRewardAmount persists the default minimum external-incentive reward.
953 //
954 // Parameters:
955 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
956 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
957 // - amount: Default minimum reward-token amount in token units.
958 //
959 // Returns:
960 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
961 //
962 SetMinimumRewardAmount(_ int, rlm realm, amount int64) error
963
964 // HasDepositsStoreKey reports whether the active-deposits tree key exists.
965 //
966 // Returns:
967 // - exists: True when the deposits key is present in persistent storage.
968 //
969 HasDepositsStoreKey() bool
970
971 // GetDeposits returns the persisted active position-deposit tree.
972 //
973 // Returns:
974 // - deposits: B+tree mapping LP position IDs to deposits; storage read or type failures panic.
975 //
976 GetDeposits() *bptree.BPTree
977
978 // SetDeposits persists the active position-deposit tree.
979 //
980 // Parameters:
981 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
982 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
983 // - deposits: B+tree containing active position deposits to persist.
984 //
985 // Returns:
986 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
987 //
988 SetDeposits(_ int, rlm realm, deposits *bptree.BPTree) error
989
990 // HasExternalIncentivesStoreKey reports whether the external-incentives tree key exists.
991 //
992 // Returns:
993 // - exists: True when the externalIncentives key is present in persistent storage.
994 //
995 HasExternalIncentivesStoreKey() bool
996
997 // GetExternalIncentives returns the persisted external-incentive tree.
998 //
999 // Returns:
1000 // - incentives: B+tree mapping incentive IDs to incentive records; storage read or type failures panic.
1001 //
1002 GetExternalIncentives() *bptree.BPTree
1003
1004 // SetExternalIncentives persists the external-incentive tree.
1005 //
1006 // Parameters:
1007 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1008 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1009 // - incentives: B+tree containing external-incentive records to persist.
1010 //
1011 // Returns:
1012 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1013 //
1014 SetExternalIncentives(_ int, rlm realm, incentives *bptree.BPTree) error
1015
1016 // HasTotalEmissionSentStoreKey reports whether the cumulative-emission key exists.
1017 //
1018 // Returns:
1019 // - exists: True when the totalEmissionSent key is present in persistent storage.
1020 //
1021 HasTotalEmissionSentStoreKey() bool
1022
1023 // GetTotalEmissionSent returns the persisted cumulative GNS emission amount.
1024 //
1025 // Returns:
1026 // - amount: Cumulative internal emission in GNS token units; storage read or type failures panic.
1027 //
1028 GetTotalEmissionSent() int64
1029
1030 // SetTotalEmissionSent persists the cumulative GNS emission amount.
1031 //
1032 // Parameters:
1033 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1034 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1035 // - amount: Cumulative GNS amount to persist.
1036 //
1037 // Returns:
1038 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1039 //
1040 SetTotalEmissionSent(_ int, rlm realm, amount int64) error
1041
1042 // HasAllowedTokensStoreKey reports whether the external-incentive allowlist key exists.
1043 //
1044 // Returns:
1045 // - exists: True when the allowedTokens key is present in persistent storage.
1046 //
1047 HasAllowedTokensStoreKey() bool
1048
1049 // GetAllowedTokens returns a copy of token paths allowed for new incentives.
1050 //
1051 // Returns:
1052 // - tokenPaths: Store-owned allowlist copied into a caller-safe slice.
1053 //
1054 GetAllowedTokens() []string
1055
1056 // SetAllowedTokens replaces the external-incentive allowlist.
1057 //
1058 // Parameters:
1059 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1060 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1061 // - tokens: Token contract paths to persist as the new allowlist.
1062 //
1063 // Returns:
1064 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1065 //
1066 SetAllowedTokens(_ int, rlm realm, tokens []string) error
1067
1068 // AddAllowedToken adds a token path to the allowlist when it is not already present.
1069 //
1070 // Parameters:
1071 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1072 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1073 // - tokenPath: Token contract path to add to the allowlist.
1074 //
1075 // Returns:
1076 // - err: Nil when added or already present, ErrSpoofedRealm for a non-current realm, or the KV-store write error.
1077 //
1078 AddAllowedToken(_ int, rlm realm, tokenPath string) error
1079
1080 // RemoveAllowedToken removes a token path from the allowlist when present.
1081 //
1082 // Parameters:
1083 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1084 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1085 // - tokenPath: Token contract path to remove from the allowlist.
1086 //
1087 // Returns:
1088 // - err: Nil when removed or absent, ErrSpoofedRealm for a non-current realm, or the KV-store write error.
1089 //
1090 RemoveAllowedToken(_ int, rlm realm, tokenPath string) error
1091
1092 // HasDeniedRewardTokensStoreKey reports whether the external reward deny-list key exists.
1093 //
1094 // Returns:
1095 // - exists: True when the deniedRewardTokens key is present in persistent storage.
1096 //
1097 HasDeniedRewardTokensStoreKey() bool
1098
1099 // GetDeniedRewardTokens returns a copy of token paths denied for new incentives.
1100 //
1101 // Returns:
1102 // - tokenPaths: Store-owned deny list copied for callers; an uninitialized key yields an empty slice.
1103 //
1104 GetDeniedRewardTokens() []string
1105
1106 // AddDeniedRewardToken adds a token path to the deny list when absent.
1107 //
1108 // Parameters:
1109 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1110 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1111 // - tokenPath: Reward-token contract path to deny for new incentives.
1112 //
1113 // Returns:
1114 // - err: Nil when added or already present, ErrSpoofedRealm for a non-current realm, or the KV-store write error.
1115 //
1116 AddDeniedRewardToken(_ int, rlm realm, tokenPath string) error
1117
1118 // RemoveDeniedRewardToken removes a token path from the deny list when present.
1119 //
1120 // Parameters:
1121 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1122 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1123 // - tokenPath: Reward-token contract path to allow again for new incentives.
1124 //
1125 // Returns:
1126 // - err: Nil when removed or absent, ErrSpoofedRealm for a non-current realm, or the KV-store write error.
1127 //
1128 RemoveDeniedRewardToken(_ int, rlm realm, tokenPath string) error
1129
1130 // HasIncentiveCounterStoreKey reports whether the incentive-counter key exists.
1131 //
1132 // Returns:
1133 // - exists: True when the incentiveCounter key is present in persistent storage.
1134 //
1135 HasIncentiveCounterStoreKey() bool
1136
1137 // GetIncentiveCounter returns the persisted counter used to allocate incentive IDs.
1138 //
1139 // Returns:
1140 // - counter: Incentive-ID counter object; storage read or type failures panic.
1141 //
1142 GetIncentiveCounter() *Counter
1143
1144 // SetIncentiveCounter persists the incentive-ID counter.
1145 //
1146 // Parameters:
1147 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1148 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1149 // - counter: Counter object whose next value will be used for incentive IDs.
1150 //
1151 // Returns:
1152 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1153 //
1154 SetIncentiveCounter(_ int, rlm realm, counter *Counter) error
1155
1156 // NextIncentiveID consumes the next counter value and formats a unique incentive ID.
1157 //
1158 // Parameters:
1159 // - creator: Address that is creating and funding the incentive.
1160 // - timestamp: Unix-second creation timestamp embedded in the identifier.
1161 //
1162 // Returns:
1163 // - incentiveId: Identifier combining creator, timestamp, and the incremented counter index.
1164 //
1165 NextIncentiveID(creator address, timestamp int64) string
1166
1167 // HasTokenSpecificMinimumRewardsStoreKey reports whether token-specific minimums exist.
1168 //
1169 // Returns:
1170 // - exists: True when the tokenSpecificMinimumRewards key is present in persistent storage.
1171 //
1172 HasTokenSpecificMinimumRewardsStoreKey() bool
1173
1174 // GetTokenSpecificMinimumRewards returns configured token-specific reward minimums.
1175 //
1176 // Returns:
1177 // - rewards: Map from token contract path to minimum reward amount; storage read or type failures panic.
1178 //
1179 GetTokenSpecificMinimumRewards() map[string]int64
1180
1181 // SetTokenSpecificMinimumRewards replaces all token-specific minimums.
1182 //
1183 // Parameters:
1184 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1185 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1186 // - rewards: Token-path-to-minimum-amount mapping to persist.
1187 //
1188 // Returns:
1189 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1190 //
1191 SetTokenSpecificMinimumRewards(_ int, rlm realm, rewards map[string]int64) error
1192
1193 // SetTokenSpecificMinimumRewardItem sets one token's minimum reward entry.
1194 //
1195 // Parameters:
1196 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1197 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1198 // - tokenPath: Token contract path whose override is being set.
1199 // - amount: Token-specific minimum reward amount in token units.
1200 //
1201 // Returns:
1202 // - err: Nil when the item is stored, ErrSpoofedRealm for a non-current realm, or the KV-store write error.
1203 //
1204 SetTokenSpecificMinimumRewardItem(_ int, rlm realm, tokenPath string, amount int64) error
1205
1206 // RemoveTokenSpecificMinimumRewardItem removes one token's minimum reward entry.
1207 //
1208 // Parameters:
1209 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1210 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1211 // - tokenPath: Token contract path whose override is being removed.
1212 //
1213 // Returns:
1214 // - err: Nil after rebuilding the mapping without the item, ErrSpoofedRealm for a non-current realm, or the KV-store write error.
1215 //
1216 RemoveTokenSpecificMinimumRewardItem(_ int, rlm realm, tokenPath string) error
1217
1218 // HasUnstakingFeeStoreKey reports whether the unstaking-fee key exists.
1219 //
1220 // Returns:
1221 // - exists: True when the unstakingFee key is present in persistent storage.
1222 //
1223 HasUnstakingFeeStoreKey() bool
1224
1225 // GetUnstakingFee returns the stored reward fee rate in basis points.
1226 //
1227 // Returns:
1228 // - fee: Persisted fee rate, where 10,000 basis points represents 100%.
1229 //
1230 GetUnstakingFee() uint64
1231
1232 // SetUnstakingFee persists the reward fee rate.
1233 //
1234 // Parameters:
1235 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1236 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1237 // - fee: Fee rate in basis points.
1238 //
1239 // Returns:
1240 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1241 //
1242 SetUnstakingFee(_ int, rlm realm, fee uint64) error
1243
1244 // HasPendingProtocolFeesStoreKey reports whether pending protocol fees exist.
1245 //
1246 // Returns:
1247 // - exists: True when the pendingProtocolFees key is present in persistent storage.
1248 //
1249 HasPendingProtocolFeesStoreKey() bool
1250
1251 // GetPendingProtocolFees returns pending protocol-fee amounts by token path.
1252 //
1253 // Returns:
1254 // - fees: Token-path-to-amount map awaiting settlement; storage read or type failures panic.
1255 //
1256 GetPendingProtocolFees() map[string]int64
1257
1258 // SetPendingProtocolFees replaces all pending protocol-fee amounts.
1259 //
1260 // Parameters:
1261 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1262 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1263 // - fees: Token-path-to-amount map copied into realm-owned persistent storage.
1264 //
1265 // Returns:
1266 // - err: Nil when stored, ErrSpoofedRealm or write-permission error when unauthorized, or the KV-store write error.
1267 //
1268 SetPendingProtocolFees(_ int, rlm realm, fees map[string]int64) error
1269
1270 // GetPendingProtocolFee returns the pending amount for one token path.
1271 //
1272 // Parameters:
1273 // - tokenPath: Token contract path whose pending amount is requested.
1274 //
1275 // Returns:
1276 // - amount: Pending amount for the token, or zero when no entry exists.
1277 //
1278 GetPendingProtocolFee(tokenPath string) int64
1279
1280 // SetPendingProtocolFee updates one token's pending protocol-fee amount.
1281 //
1282 // Parameters:
1283 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1284 // - rlm: Propagated current realm context; it must also be authorized for code-realm writes.
1285 // - tokenPath: Token contract path whose pending amount is updated.
1286 // - amount: Pending protocol-fee amount to record for the token.
1287 //
1288 // Returns:
1289 // - err: Nil when updated, ErrSpoofedRealm or write-permission error when unauthorized, or the KV-store write error.
1290 //
1291 SetPendingProtocolFee(_ int, rlm realm, tokenPath string, amount int64) error
1292
1293 // RemovePendingProtocolFee deletes one token's pending protocol-fee entry.
1294 //
1295 // Parameters:
1296 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1297 // - rlm: Propagated current realm context; it must also be authorized for code-realm writes.
1298 // - tokenPath: Token contract path whose pending entry is deleted.
1299 //
1300 // Returns:
1301 // - err: Nil when removed, ErrSpoofedRealm or write-permission error when unauthorized, or the KV-store write error.
1302 //
1303 RemovePendingProtocolFee(_ int, rlm realm, tokenPath string) error
1304
1305 // HasUnstakedPositionsStoreKey reports whether the exit-checkpoint tree key exists.
1306 //
1307 // Returns:
1308 // - exists: True when the unstakedPositions key is present in persistent storage.
1309 //
1310 HasUnstakedPositionsStoreKey() bool
1311
1312 // GetUnstakedPositions returns the persisted exit-checkpoint tree.
1313 //
1314 // Returns:
1315 // - positions: B+tree mapping position IDs to unstaked checkpoints; storage read or type failures panic.
1316 //
1317 GetUnstakedPositions() *bptree.BPTree
1318
1319 // SetUnstakedPositions persists the exit-checkpoint tree.
1320 //
1321 // Parameters:
1322 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1323 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1324 // - positions: B+tree containing unstaked position checkpoints to persist.
1325 //
1326 // Returns:
1327 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1328 //
1329 SetUnstakedPositions(_ int, rlm realm, positions *bptree.BPTree) error
1330
1331 // HasUncollectedIncentiveCountsStoreKey reports whether the incentive-count tree key exists.
1332 //
1333 // Returns:
1334 // - exists: True when the uncollectedIncentiveCounts key is present in persistent storage.
1335 //
1336 HasUncollectedIncentiveCountsStoreKey() bool
1337
1338 // GetUncollectedIncentiveCounts returns the persisted count tree for exit claims.
1339 //
1340 // Returns:
1341 // - counts: B+tree mapping incentive IDs to uncollected checkpoint counts; storage read or type failures panic.
1342 //
1343 GetUncollectedIncentiveCounts() *bptree.BPTree
1344
1345 // SetUncollectedIncentiveCounts persists the exit-claim count tree.
1346 //
1347 // Parameters:
1348 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1349 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1350 // - counts: B+tree containing uncollected incentive counts to persist.
1351 //
1352 // Returns:
1353 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1354 //
1355 SetUncollectedIncentiveCounts(_ int, rlm realm, counts *bptree.BPTree) error
1356 // HasPoolsStoreKey reports whether the pool registry tree key exists.
1357 //
1358 // Returns:
1359 // - exists: True when the pools key is present in persistent storage.
1360 //
1361 HasPoolsStoreKey() bool
1362
1363 // GetPools returns the persisted pool registry tree.
1364 //
1365 // Returns:
1366 // - pools: B+tree mapping canonical pool paths to pool records; storage read or type failures panic.
1367 //
1368 GetPools() *bptree.BPTree
1369
1370 // SetPools persists the pool registry tree.
1371 //
1372 // Parameters:
1373 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1374 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1375 // - pools: B+tree containing pool records to persist.
1376 //
1377 // Returns:
1378 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1379 //
1380 SetPools(_ int, rlm realm, pools *bptree.BPTree) error
1381
1382 // HasPoolTierMembershipsStoreKey reports whether pool-to-tier membership data exists.
1383 //
1384 // Returns:
1385 // - exists: True when the poolTierMemberships key is present in persistent storage.
1386 //
1387 HasPoolTierMembershipsStoreKey() bool
1388
1389 // GetPoolTierMemberships returns the persisted pool-to-tier membership tree.
1390 //
1391 // Returns:
1392 // - memberships: B+tree mapping pool paths to tier numbers; storage read or type failures panic.
1393 //
1394 GetPoolTierMemberships() *bptree.BPTree
1395
1396 // SetPoolTierMemberships persists pool-to-tier membership data.
1397 //
1398 // Parameters:
1399 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1400 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1401 // - memberships: B+tree mapping pool paths to tier numbers.
1402 //
1403 // Returns:
1404 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1405 //
1406 SetPoolTierMemberships(_ int, rlm realm, memberships *bptree.BPTree) error
1407
1408 // HasPoolTierRatioStoreKey reports whether tier reward-ratio data exists.
1409 //
1410 // Returns:
1411 // - exists: True when the poolTierRatio key is present in persistent storage.
1412 //
1413 HasPoolTierRatioStoreKey() bool
1414
1415 // GetPoolTierRatio returns the persisted tier-to-ratio configuration.
1416 //
1417 // Returns:
1418 // - ratio: TierRatio configuration used to calculate pool emission shares; storage read or type failures panic.
1419 //
1420 GetPoolTierRatio() TierRatio
1421
1422 // SetPoolTierRatio persists tier reward-ratio configuration.
1423 //
1424 // Parameters:
1425 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1426 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1427 // - ratio: TierRatio configuration to persist.
1428 //
1429 // Returns:
1430 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1431 //
1432 SetPoolTierRatio(_ int, rlm realm, ratio TierRatio) error
1433
1434 // HasPoolTierCountsStoreKey reports whether tier membership counts exist.
1435 //
1436 // Returns:
1437 // - exists: True when the poolTierCounts key is present in persistent storage.
1438 //
1439 HasPoolTierCountsStoreKey() bool
1440
1441 // GetPoolTierCounts returns the fixed-size array of pool counts by tier.
1442 //
1443 // Returns:
1444 // - counts: Per-tier pool membership counts indexed by AllTierCount; storage read or type failures panic.
1445 //
1446 GetPoolTierCounts() [AllTierCount]uint64
1447
1448 // SetPoolTierCounts persists per-tier pool membership counts.
1449 //
1450 // Parameters:
1451 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1452 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1453 // - counts: Fixed-size per-tier pool membership counts to persist.
1454 //
1455 // Returns:
1456 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1457 //
1458 SetPoolTierCounts(_ int, rlm realm, counts [AllTierCount]uint64) error
1459
1460 // HasPoolTierLastRewardCacheTimestampStoreKey reports whether the reward-cache timestamp exists.
1461 //
1462 // Returns:
1463 // - exists: True when the poolTierLastRewardCacheTimestamp key is present in persistent storage.
1464 //
1465 HasPoolTierLastRewardCacheTimestampStoreKey() bool
1466
1467 // GetPoolTierLastRewardCacheTimestamp returns the last tier reward-cache timestamp.
1468 //
1469 // Returns:
1470 // - timestamp: Unix-second timestamp persisted after tier reward caching; read/type failures panic.
1471 //
1472 GetPoolTierLastRewardCacheTimestamp() int64
1473
1474 // SetPoolTierLastRewardCacheTimestamp persists the tier reward-cache timestamp.
1475 //
1476 // Parameters:
1477 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1478 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1479 // - timestamp: Unix-second timestamp to persist as the last cache boundary.
1480 //
1481 // Returns:
1482 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1483 //
1484 SetPoolTierLastRewardCacheTimestamp(_ int, rlm realm, timestamp int64) error
1485
1486 // HasPoolTierCurrentEmissionStoreKey reports whether the current tier-emission key exists.
1487 //
1488 // Returns:
1489 // - exists: True when the poolTierCurrentEmission key is present in persistent storage.
1490 //
1491 HasPoolTierCurrentEmissionStoreKey() bool
1492
1493 // GetPoolTierCurrentEmission returns the current GNS emission rate cached for tiers.
1494 //
1495 // Returns:
1496 // - emission: Current per-second emission amount; storage read or type failures panic.
1497 //
1498 GetPoolTierCurrentEmission() int64
1499
1500 // SetPoolTierCurrentEmission persists the current tier-emission rate.
1501 //
1502 // Parameters:
1503 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1504 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1505 // - emission: Current per-second GNS emission amount to persist.
1506 //
1507 // Returns:
1508 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1509 //
1510 SetPoolTierCurrentEmission(_ int, rlm realm, emission int64) error
1511
1512 // HasPoolTierGetEmissionStoreKey reports whether the emission-rate callback exists.
1513 //
1514 // Returns:
1515 // - exists: True when the poolTierGetEmission key is present in persistent storage.
1516 //
1517 HasPoolTierGetEmissionStoreKey() bool
1518
1519 // GetPoolTierGetEmission returns the callback used to query current emission.
1520 //
1521 // Returns:
1522 // - getEmission: Callback returning the current emission amount and an error; storage read or type failures panic.
1523 //
1524 GetPoolTierGetEmission() func() (int64, error)
1525
1526 // SetPoolTierGetEmission persists the callback used to query current emission.
1527 //
1528 // Parameters:
1529 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1530 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1531 // - fn: Callback that returns the current per-second emission amount, or an error when unavailable.
1532 //
1533 // Returns:
1534 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1535 //
1536 SetPoolTierGetEmission(_ int, rlm realm, fn func() (int64, error)) error
1537
1538 // HasPoolTierGetHalvingBlocksInRangeStoreKey reports whether the halving-range callback exists.
1539 //
1540 // Returns:
1541 // - exists: True when the poolTierGetHalvingBlocksInRange key is present in persistent storage.
1542 //
1543 HasPoolTierGetHalvingBlocksInRangeStoreKey() bool
1544
1545 // GetPoolTierGetHalvingBlocksInRange returns the callback used to query
1546 // halving timestamps and matching emission amounts for a time range.
1547 //
1548 // Returns:
1549 // - getHalvingBlocksInRange: Callback taking [start,end) timestamps and returning ascending halving timestamps, corresponding emissions, and an error; storage read or type failures panic.
1550 //
1551 GetPoolTierGetHalvingBlocksInRange() func(start, end int64) ([]int64, []int64, error)
1552
1553 // SetPoolTierGetHalvingBlocksInRange persists the halving-range callback.
1554 //
1555 // Parameters:
1556 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1557 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1558 // - fn: Callback taking a [start,end) timestamp interval and returning matching halving timestamps, emission amounts, and an error.
1559 //
1560 // Returns:
1561 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1562 //
1563 SetPoolTierGetHalvingBlocksInRange(_ int, rlm realm, fn func(start, end int64) ([]int64, []int64, error)) error
1564
1565 // HasWarmupTemplateStoreKey reports whether the warm-up template key exists.
1566 //
1567 // Returns:
1568 // - exists: True when the warmupTemplate key is present in persistent storage.
1569 //
1570 HasWarmupTemplateStoreKey() bool
1571
1572 // GetWarmupTemplate returns a copy of the warm-up schedule for new deposits.
1573 //
1574 // Returns:
1575 // - warmups: Caller-safe copy of ordered warm-up ratio and duration entries.
1576 //
1577 GetWarmupTemplate() []Warmup
1578
1579 // SetWarmupTemplate replaces the warm-up schedule for new deposits.
1580 //
1581 // Parameters:
1582 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1583 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1584 // - warmups: Ordered warm-up ratio and duration entries to persist.
1585 //
1586 // Returns:
1587 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1588 //
1589 SetWarmupTemplate(_ int, rlm realm, warmups []Warmup) error
1590
1591 // HasCurrentSwapBatchStoreKey reports whether the current swap-batch key exists.
1592 //
1593 // Returns:
1594 // - exists: True when the currentSwapBatch key is present in persistent storage.
1595 //
1596 HasCurrentSwapBatchStoreKey() bool
1597
1598 // GetCurrentSwapBatch returns the persisted swap-batch processor state.
1599 //
1600 // Returns:
1601 // - batch: Current SwapBatchProcessor pointer; storage read or type failures panic.
1602 //
1603 GetCurrentSwapBatch() *SwapBatchProcessor
1604
1605 // SetCurrentSwapBatch persists the current swap-batch processor state.
1606 //
1607 // Parameters:
1608 // - _: Leading integer discriminator for internal store forwarding; callers pass 0.
1609 // - rlm: Propagated current realm context; a non-current realm is rejected before writing.
1610 // - batch: SwapBatchProcessor state to persist for the current batch.
1611 //
1612 // Returns:
1613 // - err: Nil when stored, ErrSpoofedRealm for a non-current realm, or the underlying KV-store write error.
1614 //
1615 SetCurrentSwapBatch(_ int, rlm realm, batch *SwapBatchProcessor) error
1616}
