Line data Source code
1 : #ifndef HEADER_fd_src_flamenco_stakes_fd_top_votes_h
2 : #define HEADER_fd_src_flamenco_stakes_fd_top_votes_h
3 :
4 : #include "../../util/fd_util_base.h"
5 : #include "../types/fd_types_custom.h"
6 :
7 : /* With the introduction of VAT, the set of vote accounts that receive
8 : epoch rewards, participate in clock calculation, and are eligible for
9 : becoming leader becomes the top 2000 staked validators.
10 : fd_top_votes_t allows for efficiently populating and querying the
11 : set of top staked validators. This data structure is intended to be
12 : CoW-able and maintained by the banks.
13 :
14 : Under the hood, fd_top_votes_t uses a heap, map, and pool to track
15 : the top set of vote accounts as they are being added. The map allows
16 : for O(1) lookup of a vote account by its public key.
17 :
18 : An important tiebreaking rule is that if the minimum stake value has
19 : a tie, all accounts with that stake value will be excluded from the
20 : top voters set. */
21 :
22 : struct fd_top_votes;
23 : typedef struct fd_top_votes fd_top_votes_t;
24 :
25 288 : #define FD_TOP_VOTES_ALIGN (128UL)
26 :
27 : /* FD_TOP_VOTES_MAX_FOOTPRINT is the footprint of the fd_top_votes_t
28 : structure when the max number of vote accounts is
29 : FD_RUNTIME_MAX_VOTE_ACCOUNTS_VAT (2000). */
30 :
31 0 : #define FD_TOP_VOTES_MAX_FOOTPRINT (194432UL)
32 :
33 : FD_PROTOTYPES_BEGIN
34 :
35 : /* fd_top_votes_align returns the alignment of the fd_top_votes_t
36 : structure. */
37 :
38 : ulong
39 : fd_top_votes_align( void );
40 :
41 : /* fd_top_votes_footprint returns the footprint of the fd_top_votes_t
42 : structure given a max number of vote accounts. */
43 :
44 : ulong
45 : fd_top_votes_footprint( ulong vote_accounts_max );
46 :
47 : /* fd_top_votes_new creates a new fd_top_votes_t structure given a
48 : memory buffer, a max number of vote accounts, and a seed. */
49 :
50 : void *
51 : fd_top_votes_new( void * mem,
52 : ushort vote_accounts_max,
53 : ulong seed );
54 :
55 : /* fd_top_votes_join joins a fd_top_votes_t structure from a memory
56 : region that has been previously initialized with fd_top_votes_new.
57 : Returns a pointer to the fd_top_votes_t structure. */
58 :
59 : fd_top_votes_t *
60 : fd_top_votes_join( void * mem );
61 :
62 : /* fd_top_votes_init is a runtime initialization function for a
63 : fd_top_votes_t structure given a pointer to the structure. */
64 :
65 : void
66 : fd_top_votes_init( fd_top_votes_t * top_votes );
67 :
68 :
69 : /* fd_top_votes_insert inserts a new vote account into the top votes set
70 : given a vote account, node account, last vote slot, last vote
71 : timestamp, and a stake. The node account, last vote slot, and last
72 : vote timestamp are just metadata for the structure. If the vote
73 : account isn't in the top max_vote_accounts in terms of stake, it is
74 : ignored and is treated as a no-op. If the vote account ties the
75 : minimum stake and the struct is full, all elements with that stake
76 : are removed. */
77 :
78 : void
79 : fd_top_votes_insert( fd_top_votes_t * top_votes,
80 : fd_pubkey_t const * pubkey,
81 : fd_pubkey_t const * node_account,
82 : ulong stake,
83 : ulong last_vote_slot,
84 : long last_vote_timestamp );
85 :
86 :
87 : /* fd_top_votes_update updates the last vote timestamp and slot for a
88 : given vote account in the top votes set. If the vote account is not
89 : in the top votes set, the update is ignored and is treated as a
90 : no-op. */
91 :
92 : void
93 : fd_top_votes_update( fd_top_votes_t * top_votes,
94 : fd_pubkey_t const * pubkey,
95 : ulong last_vote_slot,
96 : long last_vote_timestamp );
97 :
98 : /* fd_top_votes_invalidate invalidates a vote account in the top votes
99 : set. This would be done in the case a vote account is withdrawn or
100 : becomes invalid. An account that is invalid, will not be returned by
101 : fd_top_votes_query. */
102 :
103 : void
104 : fd_top_votes_invalidate( fd_top_votes_t * top_votes,
105 : fd_pubkey_t const * pubkey );
106 :
107 : /* fd_top_votes_query queries a fd_top_votes_t structure given a
108 : vote account and returns 1 if the vote account is in the top voters
109 : set and 0 otherwise. If the vote account is in the top voters set,
110 : the node account, stake, last vote slot, and last vote timestamp are
111 : all optionally returned via parameter pointers. */
112 :
113 : int
114 : fd_top_votes_query( fd_top_votes_t const * top_votes,
115 : fd_pubkey_t const * pubkey,
116 : fd_pubkey_t * node_account_out_opt,
117 : ulong * stake_out_opt,
118 : ulong * last_vote_slot_out_opt,
119 : long * last_vote_timestamp_out_opt );
120 :
121 : #define FD_TOP_VOTES_ITER_FOOTPRINT (16UL)
122 : #define FD_TOP_VOTES_ITER_ALIGN (8UL)
123 : struct map_iter;
124 : typedef struct map_iter fd_top_votes_iter_t;
125 :
126 : /* A caller can iterate through the entries in the top votes set. The
127 : iterator is initialized by a call to fd_top_votes_iter_init. The
128 : caller is responsible for managing the memory for the iterator.
129 : It is safe to call fd_top_votes_iter_next if the result of
130 : fd_top_votes_iter_done() == 0. It is safe to call
131 : fd_top_votes_iter_ele() to get the current entry if there is a valid
132 : initialized iterator.
133 :
134 : Example use:
135 : uchar __attribute__((aligned(FD_TOP_VOTES_ITER_ALIGN))) iter_mem[ FD_TOP_VOTES_ITER_FOOTPRINT ];
136 : for( fd_top_votes_iter_t * iter = fd_top_votes_iter_init( top_votes, iter_mem );
137 : !fd_top_votes_iter_done( top_votes, iter );
138 : fd_top_votes_iter_next( top_votes, iter ) ) {
139 : fd_top_votes_iter_ele( top_votes, iter, &pubkey, &node_account, &stake, &last_vote_slot, &last_vote_timestamp );
140 : } */
141 :
142 : fd_top_votes_iter_t *
143 : fd_top_votes_iter_init( fd_top_votes_t const * top_votes,
144 : uchar iter_mem[ static FD_TOP_VOTES_ITER_FOOTPRINT ] );
145 :
146 : int
147 : fd_top_votes_iter_done( fd_top_votes_t const * top_votes,
148 : fd_top_votes_iter_t * iter );
149 :
150 : void
151 : fd_top_votes_iter_next( fd_top_votes_t const * top_votes,
152 : fd_top_votes_iter_t * iter );
153 :
154 : void
155 : fd_top_votes_iter_ele( fd_top_votes_t const * top_votes,
156 : fd_top_votes_iter_t * iter,
157 : fd_pubkey_t * pubkey_out,
158 : fd_pubkey_t * node_account_out_opt,
159 : ulong * stake_out_opt,
160 : ulong * last_vote_slot_out_opt,
161 : long * last_vote_timestamp_out_opt );
162 :
163 : FD_PROTOTYPES_END
164 :
165 : #endif
|
