types.gno
27.56 Kb · 679 lines
1package governance
2
3import (
4 rotree "gno.land/p/nt/bptree/rotree/v0"
5 bptree "gno.land/p/nt/bptree/v0"
6)
7
8type IGovernance interface {
9 IGovernanceManager
10 IGovernanceGetter
11 Render(path string) string
12}
13
14type IGovernanceManager interface {
15 // Proposal management
16 // ProposeText creates a non-executable proposal for community discussion.
17 //
18 // Parameters:
19 // - _: Noncrossing implementation-call discriminator; pass 0.
20 // - rlm: Current realm context forwarded unchanged by the governance proxy.
21 // - title: short, non-empty title describing the proposal.
22 // - description: non-empty proposal rationale and discussion text.
23 //
24 // Returns:
25 // - int64: ID assigned to the newly created text proposal.
26 ProposeText(
27 _ int, rlm realm,
28 title string,
29 description string,
30 ) int64
31
32 // ProposeCommunityPoolSpend creates a proposal to transfer registered tokens from the community pool.
33 //
34 // Parameters:
35 // - _: Noncrossing implementation-call discriminator; pass 0.
36 // - rlm: Current realm context forwarded unchanged by the governance proxy.
37 // - title: short title describing the requested disbursement.
38 // - description: rationale and budget details for the disbursement.
39 // - to: recipient address for the community-pool transfer.
40 // - tokenPath: registered token realm path to transfer.
41 // - amount: positive transfer amount in the token's smallest unit.
42 //
43 // Returns:
44 // - int64: ID assigned to the newly created community-pool-spend proposal.
45 ProposeCommunityPoolSpend(
46 _ int, rlm realm,
47 title string,
48 description string,
49 to address,
50 tokenPath string,
51 amount int64,
52 ) int64
53
54 // ProposeParameterChange creates a proposal containing registered parameter-handler executions.
55 //
56 // Parameters:
57 // - _: Noncrossing implementation-call discriminator; pass 0.
58 // - rlm: Current realm context forwarded unchanged by the governance proxy.
59 // - title: short title describing the parameter changes.
60 // - description: rationale and impact details for the changes.
61 // - numToExecute: number of encoded parameter-change executions expected.
62 // - executions: execution messages encoded with the governance execution delimiters.
63 //
64 // Returns:
65 // - int64: ID assigned to the newly created parameter-change proposal.
66 ProposeParameterChange(
67 _ int, rlm realm,
68 title string,
69 description string,
70 numToExecute int64,
71 executions string,
72 ) int64
73
74 // Voting
75 // Vote records the caller's final yes or no vote on a proposal.
76 //
77 // Parameters:
78 // - _: Noncrossing implementation-call discriminator; pass 0.
79 // - rlm: Current realm context forwarded unchanged by the governance proxy.
80 // - proposalId: ID of the proposal to vote on.
81 // - yes: true to cast an affirmative vote, false to cast a negative vote.
82 //
83 // Returns:
84 // - string: caller's applied voting weight formatted as a decimal string.
85 Vote(
86 _ int, rlm realm,
87 proposalId int64,
88 yes bool,
89 ) string
90
91 // Execution
92 // Execute applies an approved executable proposal within its delay and execution window.
93 //
94 // Parameters:
95 // - _: Noncrossing implementation-call discriminator; pass 0.
96 // - rlm: Current realm context forwarded unchanged by the governance proxy.
97 // - proposalId: ID of the proposal to execute.
98 //
99 // Returns:
100 // - int64: ID of the proposal successfully executed.
101 Execute(
102 _ int, rlm realm,
103 proposalId int64,
104 ) int64
105
106 // Cancel marks an upcoming proposal as cancelled at the request of its proposer.
107 //
108 // Parameters:
109 // - _: Noncrossing implementation-call discriminator; pass 0.
110 // - rlm: Current realm context forwarded unchanged by the governance proxy.
111 // - proposalId: ID of the proposal to cancel.
112 //
113 // Returns:
114 // - int64: ID of the proposal successfully cancelled.
115 Cancel(
116 _ int, rlm realm,
117 proposalId int64,
118 ) int64
119
120 // RemoveInactiveProposalFromIndex removes an inactive proposal from the snapshot index.
121 //
122 // Parameters:
123 // - _: Noncrossing implementation-call discriminator; pass 0.
124 // - rlm: Current realm context forwarded unchanged by the governance proxy.
125 // - proposalID: ID of the inactive proposal index entry to remove.
126 RemoveInactiveProposalFromIndex(_ int, rlm realm, proposalID int64)
127
128 // Configuration
129 // Reconfigure validates and stores a new governance configuration version.
130 //
131 // Parameters:
132 // - _: Noncrossing implementation-call discriminator; pass 0.
133 // - rlm: Current realm context forwarded unchanged by the governance proxy.
134 // - votingStartDelay: seconds from proposal creation until voting opens.
135 // - votingPeriod: seconds for which voting remains open.
136 // - votingWeightSmoothingDuration: seconds used to smooth delegation history for voting weight.
137 // - quorum: required approval percentage of total xGNS supply, from 0 through 100.
138 // - proposalCreationThreshold: minimum xGNS amount required to create a proposal.
139 // - executionDelay: seconds required between approval and execution.
140 // - executionWindow: seconds after the delay during which execution is allowed.
141 //
142 // Returns:
143 // - int64: newly stored governance configuration version.
144 Reconfigure(
145 _ int, rlm realm,
146 votingStartDelay int64,
147 votingPeriod int64,
148 votingWeightSmoothingDuration int64,
149 quorum int64,
150 proposalCreationThreshold int64,
151 executionDelay int64,
152 executionWindow int64,
153 ) int64
154}
155
156// IGovernanceGetter provides read-only access to governance data.
157type IGovernanceGetter interface {
158 // Store data getters
159 // GetLatestConfigVersion returns the version number of the current governance configuration.
160 //
161 // Returns:
162 // - int64: current configuration version used for new proposals.
163 GetLatestConfigVersion() int64
164 // GetCurrentProposalID returns the current proposal ID counter value.
165 //
166 // Returns:
167 // - int64: current proposal identifier counter value.
168 GetCurrentProposalID() int64
169 // GetMaxSmoothingPeriod returns the upper bound for the voting-weight smoothing period.
170 //
171 // Returns:
172 // - int64: fixed maximum smoothing duration of 30 days (2,592,000 seconds).
173 GetMaxSmoothingPeriod() int64
174
175 // Config getters
176 // GetLatestConfig returns the current governance configuration.
177 //
178 // Returns:
179 // - Config: latest stored configuration, or a zero configuration when unavailable.
180 // - error: nil when found; otherwise an error indicating that the configuration is unavailable.
181 GetLatestConfig() (Config, error)
182 // GetConfig returns a governance configuration by version.
183 //
184 // Parameters:
185 // - configVersion: configuration version to retrieve.
186 //
187 // Returns:
188 // - Config: configuration stored at the requested version, or a zero configuration when absent.
189 // - error: nil when found; otherwise an error identifying the missing version.
190 GetConfig(configVersion int64) (Config, error)
191
192 // GetProposals returns a read-only view of stored proposals keyed by decimal proposal ID.
193 //
194 // Returns:
195 // - *rotree.ReadOnlyTree: read-only proposal tree with cloned proposal values.
196 GetProposals() *rotree.ReadOnlyTree
197 // ExistsProposal reports whether a proposal is stored for an ID.
198 //
199 // Parameters:
200 // - proposalID: proposal identifier to look up.
201 //
202 // Returns:
203 // - bool: true when a proposal exists for proposalID.
204 ExistsProposal(proposalID int64) bool
205 // GetProposerByProposalId returns the address that created a proposal.
206 //
207 // Parameters:
208 // - proposalId: proposal identifier to look up.
209 //
210 // Returns:
211 // - address: proposer address recorded on the proposal.
212 // - error: nil when found; otherwise an error indicating the proposal is missing.
213 GetProposerByProposalId(proposalId int64) (address, error)
214 // GetProposalTypeByProposalId returns the type discriminator of a proposal.
215 //
216 // Parameters:
217 // - proposalId: proposal identifier to look up.
218 //
219 // Returns:
220 // - ProposalType: proposal type stored on the proposal.
221 // - error: nil when found; otherwise an error indicating the proposal is missing.
222 GetProposalTypeByProposalId(proposalId int64) (ProposalType, error)
223 // GetProposalCreatedAt returns a proposal's creation timestamp.
224 //
225 // Parameters:
226 // - proposalId: proposal identifier to look up.
227 //
228 // Returns:
229 // - int64: creation time as a Unix timestamp in seconds.
230 // - error: nil when found; otherwise an error indicating the proposal is missing.
231 GetProposalCreatedAt(proposalId int64) (int64, error)
232 // GetProposalCreatedHeight returns the block height at which a proposal was created.
233 //
234 // Parameters:
235 // - proposalId: proposal identifier to look up.
236 //
237 // Returns:
238 // - int64: creation block height.
239 // - error: nil when found; otherwise an error indicating the proposal is missing.
240 GetProposalCreatedHeight(proposalId int64) (int64, error)
241 // GetProposalCommunityPoolSpendInfo returns the treasury-transfer payload of a proposal.
242 //
243 // Parameters:
244 // - proposalID: proposal identifier to look up.
245 //
246 // Returns:
247 // - *CommunityPoolSpendInfo: spend payload, or nil when the proposal is absent or another type.
248 // - error: nil for a community-pool-spend proposal; otherwise a not-found or wrong-type error.
249 GetProposalCommunityPoolSpendInfo(proposalID int64) (*CommunityPoolSpendInfo, error)
250 // GetProposalExecutionInfo returns the parameter-execution payload of a proposal.
251 //
252 // Parameters:
253 // - proposalID: proposal identifier to look up.
254 //
255 // Returns:
256 // - *ExecutionInfo: execution payload, or nil when the proposal is absent or another type.
257 // - error: nil for a parameter-change proposal; otherwise a not-found or wrong-type error.
258 GetProposalExecutionInfo(proposalID int64) (*ExecutionInfo, error)
259 // GetYeaByProposalId returns the affirmative vote weight recorded on a proposal.
260 //
261 // Parameters:
262 // - proposalId: proposal identifier to look up.
263 //
264 // Returns:
265 // - int64: total yes-vote weight.
266 // - error: nil when found; otherwise an error indicating the proposal is missing.
267 GetYeaByProposalId(proposalId int64) (int64, error)
268 // GetNayByProposalId returns the negative vote weight recorded on a proposal.
269 //
270 // Parameters:
271 // - proposalId: proposal identifier to look up.
272 //
273 // Returns:
274 // - int64: total no-vote weight.
275 // - error: nil when found; otherwise an error indicating the proposal is missing.
276 GetNayByProposalId(proposalId int64) (int64, error)
277 // GetConfigVersionByProposalId returns the configuration version captured by a proposal.
278 //
279 // Parameters:
280 // - proposalId: proposal identifier to look up.
281 //
282 // Returns:
283 // - int64: configuration version used to create the proposal.
284 // - error: nil when found; otherwise an error indicating the proposal is missing.
285 GetConfigVersionByProposalId(proposalId int64) (int64, error)
286 // GetQuorumAmountByProposalId returns the proposal's stored quorum requirement.
287 //
288 // Parameters:
289 // - proposalId: proposal identifier to look up.
290 //
291 // Returns:
292 // - int64: minimum vote weight required for quorum.
293 // - error: nil when found; otherwise an error indicating the proposal is missing.
294 GetQuorumAmountByProposalId(proposalId int64) (int64, error)
295 // GetTitleByProposalId returns a proposal's title.
296 //
297 // Parameters:
298 // - proposalId: proposal identifier to look up.
299 //
300 // Returns:
301 // - string: title stored in proposal metadata.
302 // - error: nil when found; otherwise an error indicating the proposal is missing.
303 GetTitleByProposalId(proposalId int64) (string, error)
304 // GetDescriptionByProposalId returns a proposal's full description.
305 //
306 // Parameters:
307 // - proposalId: proposal identifier to look up.
308 //
309 // Returns:
310 // - string: description stored in proposal metadata.
311 // - error: nil when found; otherwise an error indicating the proposal is missing.
312 GetDescriptionByProposalId(proposalId int64) (string, error)
313 // GetProposalStatusByProposalId returns the current status string for a proposal.
314 //
315 // Parameters:
316 // - proposalId: proposal identifier to look up.
317 //
318 // Returns:
319 // - string: status computed from the proposal state and current time.
320 // - error: nil when found; otherwise an error indicating the proposal is missing.
321 GetProposalStatusByProposalId(proposalId int64) (string, error)
322
323 // Vote getters
324 // GetVoteStatus returns the quorum and vote tallies stored for a proposal.
325 //
326 // Parameters:
327 // - proposalId: proposal identifier to look up.
328 //
329 // Returns:
330 // - quorum: minimum vote weight required for quorum.
331 // - maxVotingWeight: maximum voting weight captured at proposal creation.
332 // - yesWeight: total affirmative vote weight.
333 // - noWeight: total negative vote weight.
334 // - err: nil when found; otherwise an error indicating the proposal is missing.
335 GetVoteStatus(proposalId int64) (quorum, maxVotingWeight, yesWeight, noWeight int64, err error)
336 // GetVotingInfos returns a read-only view of a proposal's voter records.
337 //
338 // Parameters:
339 // - proposalID: proposal identifier whose voting records should be viewed.
340 //
341 // Returns:
342 // - *rotree.ReadOnlyTree: read-only voter-info tree, or nil when its stored tree is absent.
343 GetVotingInfos(proposalID int64) *rotree.ReadOnlyTree
344 // ExistsVotingInfo reports whether an address has a voting record for a proposal.
345 //
346 // Parameters:
347 // - proposalID: proposal identifier to inspect.
348 // - addr: voter address to look up.
349 //
350 // Returns:
351 // - bool: true when a voting record exists for the proposal and address.
352 ExistsVotingInfo(proposalID int64, addr address) bool
353 // GetVoteWeight returns the recorded voting weight for an address.
354 //
355 // Parameters:
356 // - proposalID: proposal identifier to inspect.
357 // - addr: voter address to look up.
358 //
359 // Returns:
360 // - int64: weight applied to the address's vote.
361 // - error: nil when a voting record exists; otherwise an error identifying the missing record.
362 GetVoteWeight(proposalID int64, addr address) (int64, error)
363 // GetVotedHeight returns the block height at which an address voted.
364 //
365 // Parameters:
366 // - proposalID: proposal identifier to inspect.
367 // - addr: voter address to look up.
368 //
369 // Returns:
370 // - int64: block height recorded for the vote.
371 // - error: nil when a voting record exists; otherwise an error identifying the missing record.
372 GetVotedHeight(proposalID int64, addr address) (int64, error)
373 // GetVotedAt returns the timestamp at which an address voted.
374 //
375 // Parameters:
376 // - proposalID: proposal identifier to inspect.
377 // - addr: voter address to look up.
378 //
379 // Returns:
380 // - int64: vote timestamp as Unix seconds.
381 // - error: nil when a voting record exists; otherwise an error identifying the missing record.
382 GetVotedAt(proposalID int64, addr address) (int64, error)
383
384 // GetUserProposals returns a read-only view of proposal IDs grouped by creator address.
385 //
386 // Returns:
387 // - *rotree.ReadOnlyTree: read-only creator-to-proposal-ID tree with copied ID slices.
388 GetUserProposals() *rotree.ReadOnlyTree
389
390 // Active proposal query
391 // GetOldestActiveProposalSnapshotTime inspects the first timestamp-ordered active-proposal index entry.
392 //
393 // Returns:
394 // - snapshotTime: snapshot timestamp of the oldest active proposal.
395 // - hasActive: true when an active indexed proposal was found; false when the index is empty.
396 // - error: nil on success; otherwise an error when the index entry is missing or needs cleanup.
397 GetOldestActiveProposalSnapshotTime() (int64, bool, error)
398
399 // Voting weight snapshot getters
400 // GetCurrentVotingWeightSnapshot computes the current total voting weight and its smoothed timestamp anchor.
401 //
402 // Returns:
403 // - totalVotingWeight: total delegation weight at the computed snapshot.
404 // - snapshotTime: Unix timestamp used as the snapshot anchor.
405 // - error: nil when the current configuration and snapshot are available; otherwise the lookup error.
406 GetCurrentVotingWeightSnapshot() (int64, int64, error)
407}
408
409type IGovernanceStore interface {
410 // Counter methods
411 // HasConfigCounterStoreKey reports whether the configuration counter key exists.
412 //
413 // Returns:
414 // - bool: true when the configuration counter is present in persistent storage.
415 HasConfigCounterStoreKey() bool
416 // GetConfigCounter returns the persisted configuration-version counter.
417 //
418 // Returns:
419 // - *Counter: stored configuration counter; underlying storage/type failures panic.
420 GetConfigCounter() *Counter
421 // SetConfigCounter persists the configuration-version counter.
422 //
423 // Parameters:
424 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
425 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
426 // - counter: counter value to store.
427 //
428 // Returns:
429 // - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
430 SetConfigCounter(_ int, rlm realm, counter *Counter) error
431
432 // HasProposalCounterStoreKey reports whether the proposal counter key exists.
433 //
434 // Returns:
435 // - bool: true when the proposal counter is present in persistent storage.
436 HasProposalCounterStoreKey() bool
437 // GetProposalCounter returns the persisted proposal-ID counter.
438 //
439 // Returns:
440 // - *Counter: stored proposal counter; underlying storage/type failures panic.
441 GetProposalCounter() *Counter
442 // SetProposalCounter persists the proposal-ID counter.
443 //
444 // Parameters:
445 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
446 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
447 // - counter: counter value to store.
448 //
449 // Returns:
450 // - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
451 SetProposalCounter(_ int, rlm realm, counter *Counter) error
452
453 // Config methods
454 // HasConfigsStoreKey reports whether the configurations tree key exists.
455 //
456 // Returns:
457 // - bool: true when the configurations tree is present in persistent storage.
458 HasConfigsStoreKey() bool
459 // SetConfigs replaces the persisted configuration-version tree.
460 //
461 // Parameters:
462 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
463 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
464 // - configs: configuration-version tree to store.
465 //
466 // Returns:
467 // - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
468 SetConfigs(_ int, rlm realm, configs *bptree.BPTree) error
469 // SetConfig stores one configuration under its version key.
470 //
471 // Parameters:
472 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
473 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
474 // - version: configuration version key.
475 // - config: configuration value to store.
476 //
477 // Returns:
478 // - error: nil when persisted; otherwise a spoofed-realm, missing-tree, or key-value store error.
479 SetConfig(_ int, rlm realm, version int64, config Config) error
480 // GetConfig retrieves one configuration from the persisted version tree.
481 //
482 // Parameters:
483 // - version: configuration version key to look up.
484 //
485 // Returns:
486 // - Config: stored configuration, or its zero value when absent; wrong stored types panic.
487 // - bool: true when a configuration exists for version.
488 GetConfig(version int64) (Config, bool)
489
490 // Proposal methods
491 // HasProposalsStoreKey reports whether the proposals tree key exists.
492 //
493 // Returns:
494 // - bool: true when the proposals tree is present in persistent storage.
495 HasProposalsStoreKey() bool
496 // GetProposals returns the mutable domain-owned proposals tree.
497 //
498 // Returns:
499 // - *bptree.BPTree: stored proposal tree keyed by proposal ID string; storage/type failures panic.
500 GetProposals() *bptree.BPTree
501 // GetProposal retrieves a proposal by numeric ID.
502 //
503 // Parameters:
504 // - proposalID: proposal identifier used as the tree key.
505 //
506 // Returns:
507 // - *Proposal: stored proposal when present and correctly typed.
508 // - bool: true when a valid proposal exists for proposalID.
509 GetProposal(proposalID int64) (*Proposal, bool)
510 // SetProposal stores a proposal under its matching numeric ID.
511 //
512 // Parameters:
513 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
514 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
515 // - proposalID: storage key that must match proposal.ID().
516 // - proposal: proposal value to persist.
517 //
518 // Returns:
519 // - error: nil when persisted; otherwise a spoofed-realm, missing-tree, or ID-mismatch error.
520 SetProposal(_ int, rlm realm, proposalID int64, proposal *Proposal) error
521 // SetProposals replaces the persisted proposals tree.
522 //
523 // Parameters:
524 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
525 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
526 // - proposals: proposal tree to persist.
527 //
528 // Returns:
529 // - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
530 SetProposals(_ int, rlm realm, proposals *bptree.BPTree) error
531
532 // HasActiveProposalsBySnapshotStoreKey reports whether the active-proposal snapshot index exists.
533 //
534 // Returns:
535 // - bool: true when the timestamp-ordered active-proposal index is present.
536 HasActiveProposalsBySnapshotStoreKey() bool
537 // GetActiveProposalsBySnapshot returns the domain-owned active-proposal snapshot index.
538 //
539 // Returns:
540 // - *bptree.BPTree: index keyed by snapshot timestamp and containing proposal IDs; storage/type failures panic.
541 GetActiveProposalsBySnapshot() *bptree.BPTree
542 // SetActiveProposalsBySnapshot replaces the active-proposal snapshot index.
543 //
544 // Parameters:
545 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
546 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
547 // - tree: timestamp-ordered active-proposal index to persist.
548 //
549 // Returns:
550 // - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
551 SetActiveProposalsBySnapshot(_ int, rlm realm, tree *bptree.BPTree) error
552
553 // Proposal voting info methods
554 // HasProposalUserVotingInfosStoreKey reports whether the root voting-info tree exists.
555 //
556 // Returns:
557 // - bool: true when proposal voting-info storage is present.
558 HasProposalUserVotingInfosStoreKey() bool
559 // GetProposalUserVotingInfos returns the root proposal-to-voter-info tree.
560 //
561 // Returns:
562 // - *bptree.BPTree: stored tree containing one voter-info tree per proposal; storage/type failures panic.
563 GetProposalUserVotingInfos() *bptree.BPTree
564 // SetProposalUserVotingInfos replaces the root proposal-to-voter-info tree.
565 //
566 // Parameters:
567 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
568 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
569 // - votingInfos: root proposal-to-voter-info tree to persist.
570 //
571 // Returns:
572 // - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
573 SetProposalUserVotingInfos(_ int, rlm realm, votingInfos *bptree.BPTree) error
574 // GetProposalVotingInfos returns the voter-info tree for one proposal.
575 //
576 // Parameters:
577 // - proposalID: proposal identifier used as the root-tree key.
578 //
579 // Returns:
580 // - *bptree.BPTree: voter-address-to-voting-info tree when present.
581 // - bool: true when the proposal has a correctly typed voter-info tree.
582 GetProposalVotingInfos(proposalID int64) (*bptree.BPTree, bool)
583 // SetProposalVotingInfos stores one proposal's voter-info tree.
584 //
585 // Parameters:
586 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
587 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
588 // - proposalID: proposal identifier used as the root-tree key.
589 // - votingInfos: voter-address-to-voting-info tree to persist.
590 //
591 // Returns:
592 // - error: nil when persisted; otherwise a spoofed-realm, missing-tree, or key-value store error.
593 SetProposalVotingInfos(_ int, rlm realm, proposalID int64, votingInfos *bptree.BPTree) error
594
595 // User proposals methods
596 // HasUserProposalsStoreKey reports whether the user-to-proposal index exists.
597 //
598 // Returns:
599 // - bool: true when user proposal storage is present.
600 HasUserProposalsStoreKey() bool
601 // GetUserProposals returns the domain-owned user-to-proposal index tree.
602 //
603 // Returns:
604 // - *bptree.BPTree: tree mapping user strings to proposal-ID slices; storage/type failures panic.
605 GetUserProposals() *bptree.BPTree
606 // GetUserProposalIDs returns proposal IDs currently indexed for a user.
607 //
608 // Parameters:
609 // - user: user-string key in the user-to-proposals index.
610 //
611 // Returns:
612 // - []int64: proposal IDs indexed for user, or nil when absent; wrong stored types panic.
613 // - bool: true when the user has an index entry.
614 GetUserProposalIDs(user string) ([]int64, bool)
615 // SetUserProposals replaces the persisted user-to-proposal index.
616 //
617 // Parameters:
618 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
619 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
620 // - userProposals: user-to-proposal index tree to persist.
621 //
622 // Returns:
623 // - error: nil when persisted; otherwise a spoofed-realm or key-value store error.
624 SetUserProposals(_ int, rlm realm, userProposals *bptree.BPTree) error
625 // AddUserProposal appends a proposal ID to a user's indexed list.
626 //
627 // Parameters:
628 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
629 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
630 // - user: user-string key whose proposal list is updated.
631 // - proposalID: proposal identifier to append.
632 //
633 // Returns:
634 // - error: nil when persisted; otherwise a spoofed-realm, missing-key, or key-value store error.
635 AddUserProposal(_ int, rlm realm, user string, proposalID int64) error
636 // RemoveUserProposal removes every occurrence of a proposal ID from a user's list.
637 // A missing user entry is treated as an already-complete no-op.
638 //
639 // Parameters:
640 // - _: leading realm-call discriminator for the internal store method; callers pass 0.
641 // - rlm: forwarded realm context for the persistent write; the store validates it as current.
642 // - user: user-string key whose proposal list is updated.
643 // - proposalID: proposal identifier to remove.
644 //
645 // Returns:
646 // - error: nil when removed or already absent; otherwise a spoofed-realm, missing-key, or key-value store error.
647 RemoveUserProposal(_ int, rlm realm, user string, proposalID int64) error
648}
649
650// GovStakerAccessor provides an interface for accessing gov staker functionality.
651// This abstraction allows for easier testing by enabling mock implementations.
652type GovStakerAccessor interface {
653 // GetTotalDelegationAmountAtSnapshot returns the total delegation amount at a specific snapshot time.
654 //
655 // Parameters:
656 // - snapshotTime: Unix timestamp at which delegation history is sampled.
657 //
658 // Returns:
659 // - int64: total delegated amount at snapshotTime.
660 // - bool: true when a snapshot value exists at that timestamp.
661 GetTotalDelegationAmountAtSnapshot(snapshotTime int64) (int64, bool)
662
663 // GetUserDelegationAmountAtSnapshot returns the user delegation amount at a specific snapshot time.
664 //
665 // Parameters:
666 // - userAddr: user address whose delegated amount is sampled.
667 // - snapshotTime: Unix timestamp at which the user's history is sampled.
668 //
669 // Returns:
670 // - int64: user's delegated amount at snapshotTime.
671 // - bool: true when a snapshot value exists for the user and timestamp.
672 GetUserDelegationAmountAtSnapshot(userAddr address, snapshotTime int64) (int64, bool)
673
674 // GetTotalxGnsSupply returns the total xGNS supply used as the quorum base.
675 //
676 // Returns:
677 // - int64: total xGNS supply used as the governance quorum base.
678 GetTotalxGnsSupply() int64
679}
