Line data Source code
1 : #ifndef HEADER_fd_src_choreo_votor_ag_pool_h
2 : #define HEADER_fd_src_choreo_votor_ag_pool_h
3 :
4 : #include "ag_votor_base.h"
5 : #include "ag_cert.h"
6 : #include "ag_epoch_info.h"
7 : #include "ag_parent_ready_tracker.h" /* ag_parent_ready_t */
8 : #include "ag_vote.h"
9 :
10 0 : #define AG_POOL_SUCCESS ( 0)
11 0 : #define AG_POOL_ERR_SLOT_TOO_OLD (-1)
12 0 : #define AG_POOL_ERR_SLOT_TOO_NEW (-2)
13 0 : #define AG_POOL_ERR_DUPLICATE (-3)
14 0 : #define AG_POOL_ERR_SLASHABLE (-4)
15 0 : #define AG_POOL_ERR_CERT_VERIFY (-5)
16 :
17 0 : #define AG_POOL_QUORUM_REACHED_FINAL (AG_CERT_KIND_FINAL)
18 0 : #define AG_POOL_QUORUM_REACHED_FAST_FINAL (AG_CERT_KIND_FAST_FINAL)
19 0 : #define AG_POOL_QUORUM_REACHED_NOTAR (AG_CERT_KIND_NOTAR)
20 0 : #define AG_POOL_QUORUM_REACHED_NOTAR_FALLBACK (AG_CERT_KIND_NOTAR_FALLBACK)
21 0 : #define AG_POOL_QUORUM_REACHED_SKIP (AG_CERT_KIND_SKIP)
22 0 : #define AG_POOL_QUORUM_REACHED_SAFE_TO_NOTAR (5)
23 0 : #define AG_POOL_QUORUM_REACHED_SAFE_TO_SKIP (6)
24 :
25 0 : #define AG_POOL_EVENT_PARENT_READY (0) /* Definition 15. PoolEvent::ParentReady */
26 0 : #define AG_POOL_EVENT_SAFE_TO_NOTAR (1) /* Definition 16. PoolEvent::SafeToNotar */
27 0 : #define AG_POOL_EVENT_SAFE_TO_SKIP (2) /* Definition 16. PoolEvent::SafeToSkip */
28 0 : #define AG_POOL_EVENT_CERT_CREATED (3) /* Definition 13. PoolEvent::CertCreated */
29 : #define AG_POOL_EVENT_STANDSTILL (4) /* Section 4.1. PoolEvent::Standstill */
30 :
31 0 : #define AG_POOL_EVENT_IMPLICITLY_SKIPPED (5) /* Firedancer only: for other tiles, never routed to ag_votor */
32 0 : #define AG_POOL_EVENT_IMPLICITLY_FINALIZED (6) /* Firedancer only: for other tiles, never routed to ag_votor */
33 :
34 : typedef struct ag_pool ag_pool_t;
35 :
36 : typedef struct ag_slot_state ag_slot_state_t;
37 : typedef struct ag_slot_states ag_slot_states_t;
38 :
39 : struct ag_pool_event {
40 : int kind;
41 : union {
42 : ag_parent_ready_t parent_ready;
43 : ag_block_id_t safe_to_notar;
44 : ulong safe_to_skip;
45 : ag_cert_t cert_created;
46 : ag_standstill_t standstill;
47 : ulong implicitly_skipped;
48 : ag_block_id_t implicitly_finalized;
49 : };
50 : };
51 : typedef struct ag_pool_event ag_pool_event_t;
52 :
53 : struct ag_pool_metrics {
54 : ulong slot_state_pool_used;
55 : ulong slot_state_pool_free;
56 : ulong finalized_slot;
57 : ulong pool_events_cnt;
58 : ulong bls_verify_cnt;
59 : };
60 : typedef struct ag_pool_metrics ag_pool_metrics_t;
61 :
62 : struct ag_pool_standstill_iter {
63 : ulong finalized;
64 : ulong slot; /* ULONG_MAX when done */
65 : ulong idx;
66 : int is_vote;
67 : union {
68 : ag_cert_t cert;
69 : ag_vote_t vote;
70 : };
71 : };
72 : typedef struct ag_pool_standstill_iter ag_pool_standstill_iter_t;
73 :
74 : FD_PROTOTYPES_BEGIN
75 :
76 : FD_FN_CONST ulong
77 : ag_pool_align( void );
78 :
79 : FD_FN_CONST ulong
80 : ag_pool_footprint( ulong slot_max,
81 : ulong burst );
82 :
83 : void *
84 : ag_pool_new( void * mem,
85 : ulong slot_max,
86 : ulong burst,
87 : ulong seed );
88 :
89 : ag_pool_t *
90 : ag_pool_join( void * mem );
91 :
92 : void *
93 : ag_pool_leave( ag_pool_t const * pool );
94 :
95 : void *
96 : ag_pool_delete( void * mem );
97 :
98 : /* ag_pool_from_snapshot starts the pool at root, a finalized block
99 : that is treated as notarized (Section 2.9). */
100 :
101 : void
102 : ag_pool_from_snapshot( ag_pool_t * self,
103 : ag_block_id_t const * root );
104 :
105 : /* ag_pool_from_genesis starts the pool at the genesis block. Like
106 : ag_pool_from_snapshot, but also makes genesis+1 ParentReady (see
107 : ag_parent_ready_tracker_mark_root). */
108 :
109 : void
110 : ag_pool_from_genesis( ag_pool_t * self,
111 : ag_block_id_t const * genesis );
112 :
113 : void
114 : ag_pool_fini( ag_pool_t * self );
115 :
116 : FD_FN_PURE ag_pool_metrics_t
117 : ag_pool_metrics( ag_pool_t const * self );
118 :
119 : void
120 : ag_pool_advance_epoch( ag_pool_t * self,
121 : ag_epoch_info_t const * epoch_info,
122 : ulong epoch_rank,
123 : ulong epoch_slot );
124 :
125 : /* Replaces our rank in the epoch starting at epoch_slot, for when our
126 : identity changes after the epoch advanced. The epoch's live slot
127 : states then treat the new rank's votes as ours. USHORT_MAX if we
128 : are not ranked in that epoch. */
129 :
130 : void
131 : ag_pool_set_rank( ag_pool_t * self,
132 : ulong epoch_slot,
133 : ulong epoch_rank );
134 :
135 : /* Definition 13. Pool::add_cert
136 :
137 : verified is non-zero for a cert whose signature and stake were already
138 : verified, e.g. by replay. The bounds, duplicate and safety checks
139 : still run. */
140 :
141 : int
142 : ag_pool_add_cert( ag_pool_t * self,
143 : ag_cert_t const * cert,
144 : int verified,
145 : fd_bls_set_t * bad );
146 :
147 : /* Definition 12. Pool::add_vote
148 :
149 : verified is non-zero for a vote whose signature is trusted, e.g. our
150 : own, and skips the G2 subgroup check. */
151 :
152 : int
153 : ag_pool_add_vote( ag_pool_t * self,
154 : ag_vote_t const * vote,
155 : int verified,
156 : fd_bls_set_t * bad,
157 : uchar * quorum_reached );
158 :
159 : /* Definition 16. Pool::add_block */
160 :
161 : int
162 : ag_pool_add_block( ag_pool_t * self,
163 : ag_block_id_t const * block_id,
164 : ag_block_id_t const * parent_id,
165 : fd_bls_set_t * bad );
166 :
167 : /* PoolImpl::slot_state, read-only */
168 :
169 : ag_slot_state_t const *
170 : ag_pool_slot_state( ag_pool_t const * self,
171 : ulong slot );
172 :
173 : ag_slot_states_t const *
174 : ag_pool_slot_states( ag_pool_t const * self );
175 :
176 : /* Section 4.1. Pool::recover_from_standstill */
177 :
178 : ag_pool_standstill_iter_t *
179 : ag_pool_standstill_iter_init( ag_pool_standstill_iter_t * iter,
180 : ag_pool_t const * self );
181 :
182 : ag_pool_standstill_iter_t *
183 : ag_pool_standstill_iter_next( ag_pool_standstill_iter_t * iter,
184 : ag_pool_t const * self );
185 :
186 : FD_FN_PURE int
187 : ag_pool_standstill_iter_done( ag_pool_standstill_iter_t const * iter );
188 :
189 : /* Definition 14. Pool::finalized_slot */
190 :
191 : FD_FN_PURE ulong
192 : ag_pool_finalized_slot( ag_pool_t const * self );
193 :
194 : FD_FN_PURE uchar const *
195 : ag_pool_finalized_block_hash( ag_pool_t const * self );
196 :
197 : FD_FN_PURE ulong
198 : ag_pool_highest_parent_ready( ag_pool_t const * self );
199 :
200 : /* Definition 15. Pool::parents_ready. */
201 :
202 : ulong
203 : ag_pool_parents_ready( ag_pool_t const * self,
204 : ulong slot,
205 : ag_block_id_t * out,
206 : ulong out_max );
207 :
208 : /* Definition 15. Pool::wait_for_parent_ready. */
209 :
210 : ag_block_id_t
211 : ag_pool_wait_for_parent_ready( ag_pool_t * self,
212 : ulong slot );
213 :
214 : int
215 : ag_pool_poll_pool_event( ag_pool_t * self,
216 : ag_pool_event_t * event );
217 :
218 : int
219 : ag_pool_poll_repair_event( ag_pool_t * self,
220 : ag_block_id_t * block );
221 :
222 : FD_PROTOTYPES_END
223 :
224 : #endif
|
