Line data Source code
1 : #ifndef HEADER_fd_src_flamenco_capture_fd_solcap_writer_h
2 : #define HEADER_fd_src_flamenco_capture_fd_solcap_writer_h
3 :
4 : #include "fd_solcap_proto.h"
5 : #include "fd_solcap.pb.h"
6 : #include "../types/fd_types_custom.h"
7 :
8 : /* fd_solcap_writer_t is an opaque handle to a capture writer object.
9 : Currently, it implements writing SOLCAP_V1_BANK files. See below
10 : on how to create and use this class. */
11 :
12 : struct fd_solcap_writer;
13 : typedef struct fd_solcap_writer fd_solcap_writer_t;
14 :
15 : FD_PROTOTYPES_BEGIN
16 :
17 : struct __attribute__((packed)) fd_solana_account_meta {
18 : ulong lamports;
19 : uchar owner[32];
20 : uchar executable;
21 : uchar padding[3];
22 : };
23 : typedef struct fd_solana_account_meta fd_solana_account_meta_t;
24 :
25 : static inline fd_solana_account_meta_t *
26 : fd_solana_account_meta_init( fd_solana_account_meta_t * meta,
27 : ulong lamports,
28 : void const * owner,
29 0 : int exec_bit ) {
30 0 : meta->lamports = lamports;
31 0 : fd_memcpy( meta->owner, owner, sizeof(fd_pubkey_t) );
32 0 : meta->executable = !!exec_bit;
33 0 : return meta;
34 0 : }
35 :
36 : /* fd_solcap_writer_t object lifecycle API ****************************/
37 :
38 : /* fd_solcap_writer_{align,footprint} return align and footprint
39 : requirements for the memory region backing the fd_solcap_writer_t
40 : object. fd_solcap_writer_align returns a power of two.
41 : fd_solcap_writer_footprint returns a non-zero byte count. */
42 :
43 : ulong
44 : fd_solcap_writer_align( void );
45 :
46 : ulong
47 : fd_solcap_writer_footprint( void );
48 :
49 : /* fd_solcap_writer_new creates a new fd_solcap_writer_t object using
50 : the given memory region. mem points to a memory region with matching
51 : align and footprint. Returns a pointer to the writer object within
52 : memory region, assigns ownership of mem to the object, and assigs
53 : ownership of the object to the caller. Returned pointer should not
54 : assumed to be a simple cast of mem. On failure, logs error and
55 : returns NULL. Reasons for failure include mem==NULL or invalid
56 : alignment. */
57 :
58 : fd_solcap_writer_t *
59 : fd_solcap_writer_new( void * mem );
60 :
61 : /* fd_solcap_writer_delete destroys the given fd_solcap_writer_t object
62 : and transfers ownership of the backing memory region to the caller.
63 : If mem is NULL, behaves like a noop and returns NULL. */
64 :
65 : void *
66 : fd_solcap_writer_delete( fd_solcap_writer_t * mem );
67 :
68 : /* fd_solcap_writer_init initializes writer to write to a new stream.
69 : stream is (FILE *) or the platform-specific equivalent. The stream
70 : offset should be positioned to where the capture header is expected
71 : (usually file offset 0). stream access mode should be write and
72 : should support random seeking, read is currently not required.
73 : Returns writer, transfers ownership of stream to writer, and
74 : writes the capture file header to stream on success. On failure,
75 : logs reason and returns NULL and returns stream to the user.
76 : Reasons for failure are stream I/O error. On failure, writer is left
77 : in uninitialized state (safe to retry init), and stream is left in
78 : unspecified state (caller should discard any writes made to stream). s*/
79 :
80 : fd_solcap_writer_t *
81 : fd_solcap_writer_init( fd_solcap_writer_t * writer,
82 : void * stream );
83 :
84 : /* fd_solcap_writer_flush finishes any outstanding writes and yields
85 : ownership of the stream handle back to the caller of init. Always returns
86 : writer for convenience. If an error occurs, writes reason to log. */
87 :
88 : fd_solcap_writer_t *
89 : fd_solcap_writer_flush( fd_solcap_writer_t * writer );
90 :
91 : /* fd_solcap_writer_t user API *****************************************
92 :
93 : Before calling below functions, the object must have been initialized
94 : successfully. Currently, only supports SOLCAP_V1_BANK files. For
95 : every slot, order of operations should be as follows:
96 : - set_slot
97 : - write_account (repeatedly)
98 : - write_bank_preimage
99 : - write_bank_hash */
100 :
101 : /* fd_solcap_writer_set_slot starts a new slot record. Finishes any
102 : previous slot record. slot numbers must be monotonically increasing. */
103 :
104 : void
105 : fd_solcap_writer_set_slot( fd_solcap_writer_t * writer,
106 : ulong slot );
107 :
108 : /* fd_solcap_write_account appends a copy of the given account (key,
109 : meta, data) tuple to the stream. Must only be called for accounts
110 : that are part of the current slot's account delta hash. Order of
111 : accounts is arbitrary. */
112 :
113 : int
114 : fd_solcap_write_account( fd_solcap_writer_t * writer,
115 : void const * key,
116 : fd_solana_account_meta_t const * meta,
117 : void const * data,
118 : ulong data_sz );
119 :
120 : int
121 : fd_solcap_write_account2( fd_solcap_writer_t * writer,
122 : fd_solcap_account_tbl_t const * tbl,
123 : fd_solcap_AccountMeta * meta_pb,
124 : void const * data,
125 : ulong data_sz );
126 :
127 : /* fd_solcap_write_bank_preimage sets additional fields that are part
128 : of the current slot's bank hash preimage. prev_bank_hash is the
129 : bank hash of the previous block. account_delta_hash is the Merkle
130 : root of the changed accounts (these accounts should match the ones
131 : passed to fd_solcap_write_account). poh_hash is the PoH hash of the
132 : current block. TODO what is signature_cnt? */
133 :
134 : int
135 : fd_solcap_write_bank_preimage( fd_solcap_writer_t * writer,
136 : void const * bank_hash,
137 : void const * prev_bank_hash,
138 : void const * account_delta_hash,
139 : void const * accounts_lt_hash_checksum,
140 : void const * poh_hash,
141 : ulong signature_cnt );
142 :
143 : int
144 : fd_solcap_write_bank_preimage2( fd_solcap_writer_t * writer,
145 : fd_solcap_BankPreimage * preimg );
146 :
147 : /* fd_solcap_write_transaction writes the given transaction to the
148 : stream. Must only be called for transactions that are part of the
149 : current slot's transaction hash. */
150 :
151 : int
152 : fd_solcap_write_transaction2( fd_solcap_writer_t * writer,
153 : fd_solcap_Transaction * txn );
154 :
155 : /* Stake Reward related methods */
156 :
157 : int
158 : fd_solcap_writer_stake_rewards_begin(
159 : fd_solcap_writer_t * writer,
160 : ulong payout_epoch,
161 : ulong reward_epoch,
162 : ulong inflation_lamports,
163 : fd_w_u128_t total_points
164 : );
165 :
166 : int
167 : fd_solcap_write_stake_reward_event(
168 : fd_solcap_writer_t * writer,
169 : fd_pubkey_t const * stake_acc_addr,
170 : fd_pubkey_t const * vote_acc_addr,
171 : uint commission,
172 : long vote_rewards,
173 : long stake_rewards,
174 : long new_credits_observed
175 : );
176 :
177 : int
178 : fd_solcap_write_vote_account_payout(
179 : fd_solcap_writer_t * writer,
180 : fd_pubkey_t const * vote_acc_addr,
181 : ulong update_slot,
182 : ulong lamports,
183 : long lamports_delta
184 : );
185 :
186 : int
187 : fd_solcap_write_stake_account_payout(
188 : fd_solcap_writer_t * writer,
189 : fd_pubkey_t const * stake_acc_addr,
190 : ulong update_slot,
191 : ulong lamports,
192 : long lamports_delta,
193 : ulong credits_observed,
194 : long credits_observed_delta,
195 : ulong delegation_stake,
196 : long delegation_stake_delta
197 : );
198 :
199 : /* fd_solcap_write_protobuf writes out an arbitrary protobuf blob.
200 : Uses a 1 MiB large stack buffer. */
201 :
202 : struct pb_msgdesc_s;
203 :
204 : int
205 : fd_solcap_write_protobuf( fd_solcap_writer_t * writer,
206 : void const * msg,
207 : struct pb_msgdesc_s const * desc,
208 : ulong magic );
209 :
210 : FD_PROTOTYPES_END
211 :
212 : #endif /* HEADER_fd_src_flamenco_capture_fd_solcap_writer_h */
|
