agave_geyser_plugin_interface/
geyser_plugin_interface.rs

1//! The interface for Geyser plugins. A plugin must implement
2//! the GeyserPlugin trait to work with the runtime.
3//! In addition, the dynamic library must export a "C" function _create_plugin which
4//! creates the implementation of the plugin.
5use {
6    solana_clock::{Slot, UnixTimestamp},
7    solana_hash::Hash,
8    solana_signature::Signature,
9    solana_transaction::{sanitized::SanitizedTransaction, versioned::VersionedTransaction},
10    solana_transaction_status::{Reward, RewardsAndNumPartitions, TransactionStatusMeta},
11    std::{any::Any, error, io},
12    thiserror::Error,
13};
14#[derive(Debug, Clone, PartialEq, Eq)]
15#[repr(C)]
16/// Information about an account being updated
17pub struct ReplicaAccountInfo<'a> {
18    /// The Pubkey for the account
19    pub pubkey: &'a [u8],
20
21    /// The lamports for the account
22    pub lamports: u64,
23
24    /// The Pubkey of the owner program account
25    pub owner: &'a [u8],
26
27    /// This account's data contains a loaded program (and is now read-only)
28    pub executable: bool,
29
30    /// The epoch at which this account will next owe rent
31    pub rent_epoch: u64,
32
33    /// The data held in this account.
34    pub data: &'a [u8],
35
36    /// A global monotonically increasing atomic number, which can be used
37    /// to tell the order of the account update. For example, when an
38    /// account is updated in the same slot multiple times, the update
39    /// with higher write_version should supersede the one with lower
40    /// write_version.
41    pub write_version: u64,
42}
43
44#[derive(Debug, Clone, PartialEq, Eq)]
45#[repr(C)]
46/// Information about an account being updated
47/// (extended with transaction signature doing this update)
48pub struct ReplicaAccountInfoV2<'a> {
49    /// The Pubkey for the account
50    pub pubkey: &'a [u8],
51
52    /// The lamports for the account
53    pub lamports: u64,
54
55    /// The Pubkey of the owner program account
56    pub owner: &'a [u8],
57
58    /// This account's data contains a loaded program (and is now read-only)
59    pub executable: bool,
60
61    /// The epoch at which this account will next owe rent
62    pub rent_epoch: u64,
63
64    /// The data held in this account.
65    pub data: &'a [u8],
66
67    /// A global monotonically increasing atomic number, which can be used
68    /// to tell the order of the account update. For example, when an
69    /// account is updated in the same slot multiple times, the update
70    /// with higher write_version should supersede the one with lower
71    /// write_version.
72    pub write_version: u64,
73
74    /// First signature of the transaction caused this account modification
75    pub txn_signature: Option<&'a Signature>,
76}
77
78#[derive(Debug, Clone, PartialEq, Eq)]
79#[repr(C)]
80/// Information about an account being updated
81/// (extended with reference to transaction doing this update)
82pub struct ReplicaAccountInfoV3<'a> {
83    /// The Pubkey for the account
84    pub pubkey: &'a [u8],
85
86    /// The lamports for the account
87    pub lamports: u64,
88
89    /// The Pubkey of the owner program account
90    pub owner: &'a [u8],
91
92    /// This account's data contains a loaded program (and is now read-only)
93    pub executable: bool,
94
95    /// The epoch at which this account will next owe rent
96    pub rent_epoch: u64,
97
98    /// The data held in this account.
99    pub data: &'a [u8],
100
101    /// A global monotonically increasing atomic number, which can be used
102    /// to tell the order of the account update. For example, when an
103    /// account is updated in the same slot multiple times, the update
104    /// with higher write_version should supersede the one with lower
105    /// write_version.
106    pub write_version: u64,
107
108    /// Reference to transaction causing this account modification
109    pub txn: Option<&'a SanitizedTransaction>,
110}
111
112/// A wrapper to future-proof ReplicaAccountInfo handling.
113/// If there were a change to the structure of ReplicaAccountInfo,
114/// there would be new enum entry for the newer version, forcing
115/// plugin implementations to handle the change.
116#[repr(u32)]
117pub enum ReplicaAccountInfoVersions<'a> {
118    V0_0_1(&'a ReplicaAccountInfo<'a>),
119    V0_0_2(&'a ReplicaAccountInfoV2<'a>),
120    V0_0_3(&'a ReplicaAccountInfoV3<'a>),
121}
122
123/// Information about a transaction
124#[derive(Clone, Debug)]
125#[repr(C)]
126pub struct ReplicaTransactionInfo<'a> {
127    /// The first signature of the transaction, used for identifying the transaction.
128    pub signature: &'a Signature,
129
130    /// Indicates if the transaction is a simple vote transaction.
131    pub is_vote: bool,
132
133    /// The sanitized transaction.
134    pub transaction: &'a SanitizedTransaction,
135
136    /// Metadata of the transaction status.
137    pub transaction_status_meta: &'a TransactionStatusMeta,
138}
139
140/// Information about a transaction, including index in block
141#[derive(Clone, Debug)]
142#[repr(C)]
143pub struct ReplicaTransactionInfoV2<'a> {
144    /// The first signature of the transaction, used for identifying the transaction.
145    pub signature: &'a Signature,
146
147    /// Indicates if the transaction is a simple vote transaction.
148    pub is_vote: bool,
149
150    /// The sanitized transaction.
151    pub transaction: &'a SanitizedTransaction,
152
153    /// Metadata of the transaction status.
154    pub transaction_status_meta: &'a TransactionStatusMeta,
155
156    /// The transaction's index in the block
157    pub index: usize,
158}
159
160/// Information about a transaction, including index in block
161#[derive(Clone, Debug)]
162#[repr(C)]
163pub struct ReplicaTransactionInfoV3<'a> {
164    /// The transaction signature, used for identifying the transaction.
165    pub signature: &'a Signature,
166
167    /// The transaction message hash, used for identifying the transaction.
168    pub message_hash: &'a Hash,
169
170    /// Indicates if the transaction is a simple vote transaction.
171    pub is_vote: bool,
172
173    /// The versioned transaction.
174    pub transaction: &'a VersionedTransaction,
175
176    /// Metadata of the transaction status.
177    pub transaction_status_meta: &'a TransactionStatusMeta,
178
179    /// The transaction's index in the block
180    pub index: usize,
181}
182
183/// A wrapper to future-proof ReplicaTransactionInfo handling.
184/// If there were a change to the structure of ReplicaTransactionInfo,
185/// there would be new enum entry for the newer version, forcing
186/// plugin implementations to handle the change.
187#[repr(u32)]
188pub enum ReplicaTransactionInfoVersions<'a> {
189    V0_0_1(&'a ReplicaTransactionInfo<'a>),
190    V0_0_2(&'a ReplicaTransactionInfoV2<'a>),
191    V0_0_3(&'a ReplicaTransactionInfoV3<'a>),
192}
193
194#[derive(Clone, Debug)]
195#[repr(C)]
196pub struct ReplicaEntryInfo<'a> {
197    /// The slot number of the block containing this Entry
198    pub slot: Slot,
199    /// The Entry's index in the block
200    pub index: usize,
201    /// The number of hashes since the previous Entry
202    pub num_hashes: u64,
203    /// The Entry's SHA-256 hash, generated from the previous Entry's hash with
204    /// `solana_entry::entry::next_hash()`
205    pub hash: &'a [u8],
206    /// The number of executed transactions in the Entry
207    pub executed_transaction_count: u64,
208}
209
210#[derive(Clone, Debug)]
211#[repr(C)]
212pub struct ReplicaEntryInfoV2<'a> {
213    /// The slot number of the block containing this Entry
214    pub slot: Slot,
215    /// The Entry's index in the block
216    pub index: usize,
217    /// The number of hashes since the previous Entry
218    pub num_hashes: u64,
219    /// The Entry's SHA-256 hash, generated from the previous Entry's hash with
220    /// `solana_entry::entry::next_hash()`
221    pub hash: &'a [u8],
222    /// The number of executed transactions in the Entry
223    pub executed_transaction_count: u64,
224    /// The index-in-block of the first executed transaction in this Entry
225    pub starting_transaction_index: usize,
226}
227
228/// A wrapper to future-proof ReplicaEntryInfo handling. To make a change to the structure of
229/// ReplicaEntryInfo, add an new enum variant wrapping a newer version, which will force plugin
230/// implementations to handle the change.
231#[repr(u32)]
232pub enum ReplicaEntryInfoVersions<'a> {
233    V0_0_1(&'a ReplicaEntryInfo<'a>),
234    V0_0_2(&'a ReplicaEntryInfoV2<'a>),
235}
236
237#[derive(Clone, Debug)]
238#[repr(C)]
239pub struct ReplicaBlockInfo<'a> {
240    pub slot: Slot,
241    pub blockhash: &'a str,
242    pub rewards: &'a [Reward],
243    pub block_time: Option<UnixTimestamp>,
244    pub block_height: Option<u64>,
245}
246
247/// Extending ReplicaBlockInfo by sending the executed_transaction_count.
248#[derive(Clone, Debug)]
249#[repr(C)]
250pub struct ReplicaBlockInfoV2<'a> {
251    pub parent_slot: Slot,
252    pub parent_blockhash: &'a str,
253    pub slot: Slot,
254    pub blockhash: &'a str,
255    pub rewards: &'a [Reward],
256    pub block_time: Option<UnixTimestamp>,
257    pub block_height: Option<u64>,
258    pub executed_transaction_count: u64,
259}
260
261/// Extending ReplicaBlockInfo by sending the entries_count.
262#[derive(Clone, Debug)]
263#[repr(C)]
264pub struct ReplicaBlockInfoV3<'a> {
265    pub parent_slot: Slot,
266    pub parent_blockhash: &'a str,
267    pub slot: Slot,
268    pub blockhash: &'a str,
269    pub rewards: &'a [Reward],
270    pub block_time: Option<UnixTimestamp>,
271    pub block_height: Option<u64>,
272    pub executed_transaction_count: u64,
273    pub entry_count: u64,
274}
275
276/// Extending ReplicaBlockInfo by sending RewardsAndNumPartitions.
277#[derive(Clone, Debug)]
278#[repr(C)]
279pub struct ReplicaBlockInfoV4<'a> {
280    pub parent_slot: Slot,
281    pub parent_blockhash: &'a str,
282    pub slot: Slot,
283    pub blockhash: &'a str,
284    pub rewards: &'a RewardsAndNumPartitions,
285    pub block_time: Option<UnixTimestamp>,
286    pub block_height: Option<u64>,
287    pub executed_transaction_count: u64,
288    pub entry_count: u64,
289}
290
291#[repr(u32)]
292pub enum ReplicaBlockInfoVersions<'a> {
293    V0_0_1(&'a ReplicaBlockInfo<'a>),
294    V0_0_2(&'a ReplicaBlockInfoV2<'a>),
295    V0_0_3(&'a ReplicaBlockInfoV3<'a>),
296    V0_0_4(&'a ReplicaBlockInfoV4<'a>),
297}
298
299/// Errors returned by plugin calls
300#[derive(Error, Debug)]
301#[repr(u32)]
302pub enum GeyserPluginError {
303    /// Error opening the configuration file; for example, when the file
304    /// is not found or when the validator process has no permission to read it.
305    #[error("Error opening config file. Error detail: ({0}).")]
306    ConfigFileOpenError(#[from] io::Error),
307
308    /// Error in reading the content of the config file or the content
309    /// is not in the expected format.
310    #[error("Error reading config file. Error message: ({msg})")]
311    ConfigFileReadError { msg: String },
312
313    /// Error when updating the account.
314    #[error("Error updating account. Error message: ({msg})")]
315    AccountsUpdateError { msg: String },
316
317    /// Error when updating the slot status
318    #[error("Error updating slot status. Error message: ({msg})")]
319    SlotStatusUpdateError { msg: String },
320
321    /// Any custom error defined by the plugin.
322    #[error("Plugin-defined custom error. Error message: ({0})")]
323    Custom(Box<dyn error::Error + Send + Sync>),
324
325    /// Error when updating the transaction.
326    #[error("Error updating transaction. Error message: ({msg})")]
327    TransactionUpdateError { msg: String },
328}
329
330/// The current status of a slot
331#[derive(Debug, Clone, PartialEq, Eq)]
332#[repr(u32)]
333pub enum SlotStatus {
334    /// The highest slot of the heaviest fork processed by the node. Ledger state at this slot is
335    /// not derived from a confirmed or finalized block, but if multiple forks are present, is from
336    /// the fork the validator believes is most likely to finalize.
337    Processed,
338
339    /// The highest slot having reached max vote lockout.
340    Rooted,
341
342    /// The highest slot that has been voted on by supermajority of the cluster, ie. is confirmed.
343    Confirmed,
344
345    /// First Shred Received
346    FirstShredReceived,
347
348    /// All shreds for the slot have been received.
349    Completed,
350
351    /// A new bank fork is created with the slot
352    CreatedBank,
353
354    /// A slot is marked dead
355    Dead(String),
356}
357
358impl SlotStatus {
359    pub fn as_str(&self) -> &'static str {
360        match self {
361            SlotStatus::Confirmed => "confirmed",
362            SlotStatus::Processed => "processed",
363            SlotStatus::Rooted => "rooted",
364            SlotStatus::FirstShredReceived => "first_shred_received",
365            SlotStatus::Completed => "completed",
366            SlotStatus::CreatedBank => "created_bank",
367            SlotStatus::Dead(_error) => "dead",
368        }
369    }
370}
371
372pub type Result<T> = std::result::Result<T, GeyserPluginError>;
373
374/// Defines a Geyser plugin, to stream data from the runtime.
375/// Geyser plugins must describe desired behavior for load and unload,
376/// as well as how they will handle streamed data.
377pub trait GeyserPlugin: Any + Send + Sync + std::fmt::Debug {
378    /// The callback to allow the plugin to setup the logging configuration using the logger
379    /// and log level specified by the validator. Will be called first on load/reload, before any other
380    /// callback, and only called once.
381    /// # Examples
382    ///
383    /// ```
384    /// use agave_geyser_plugin_interface::geyser_plugin_interface::{GeyserPlugin,
385    /// GeyserPluginError, Result};
386    ///
387    /// #[derive(Debug)]
388    /// struct SamplePlugin;
389    /// impl GeyserPlugin for SamplePlugin {
390    ///     fn setup_logger(&self, logger: &'static dyn log::Log, level: log::LevelFilter) -> Result<()> {
391    ///        log::set_max_level(level);
392    ///        if let Err(err) = log::set_logger(logger) {
393    ///            return Err(GeyserPluginError::Custom(Box::new(err)));
394    ///        }
395    ///        Ok(())
396    ///     }
397    ///     fn name(&self) -> &'static str {
398    ///         &"sample"
399    ///     }
400    /// }
401    /// ```
402    #[allow(unused_variables)]
403    fn setup_logger(&self, logger: &'static dyn log::Log, level: log::LevelFilter) -> Result<()> {
404        Ok(())
405    }
406
407    fn name(&self) -> &'static str;
408
409    /// The callback called when a plugin is loaded by the system,
410    /// used for doing whatever initialization is required by the plugin.
411    /// The _config_file contains the name of the
412    /// of the config file. The config must be in JSON format and
413    /// include a field "libpath" indicating the full path
414    /// name of the shared library implementing this interface.
415    fn on_load(&mut self, _config_file: &str, _is_reload: bool) -> Result<()> {
416        Ok(())
417    }
418
419    /// The callback called right before a plugin is unloaded by the system
420    /// Used for doing cleanup before unload.
421    fn on_unload(&mut self) {}
422
423    /// Called when an account is updated at a slot.
424    /// When `is_startup` is true, it indicates the account is loaded from
425    /// snapshots when the validator starts up. When `is_startup` is false,
426    /// the account is updated during transaction processing.
427    #[allow(unused_variables)]
428    fn update_account(
429        &self,
430        account: ReplicaAccountInfoVersions,
431        slot: Slot,
432        is_startup: bool,
433    ) -> Result<()> {
434        Ok(())
435    }
436
437    /// Called when all accounts are notified of during startup.
438    fn notify_end_of_startup(&self) -> Result<()> {
439        Ok(())
440    }
441
442    /// Called when a slot status is updated
443    #[allow(unused_variables)]
444    fn update_slot_status(
445        &self,
446        slot: Slot,
447        parent: Option<u64>,
448        status: &SlotStatus,
449    ) -> Result<()> {
450        Ok(())
451    }
452
453    /// Called when a transaction is processed in a slot.
454    #[allow(unused_variables)]
455    fn notify_transaction(
456        &self,
457        transaction: ReplicaTransactionInfoVersions,
458        slot: Slot,
459    ) -> Result<()> {
460        Ok(())
461    }
462
463    /// Called when an entry is executed.
464    #[allow(unused_variables)]
465    fn notify_entry(&self, entry: ReplicaEntryInfoVersions) -> Result<()> {
466        Ok(())
467    }
468
469    /// Called when block's metadata is updated.
470    #[allow(unused_variables)]
471    fn notify_block_metadata(&self, blockinfo: ReplicaBlockInfoVersions) -> Result<()> {
472        Ok(())
473    }
474
475    /// Check if the plugin is interested in account data
476    /// Default is true -- if the plugin is not interested in
477    /// account data, please return false.
478    fn account_data_notifications_enabled(&self) -> bool {
479        true
480    }
481
482    /// Check if the plugin is interested in account data from snapshot
483    /// Default is true -- if the plugin is not interested in
484    /// account data snapshot, please return false because startup would be
485    /// improved significantly.
486    fn account_data_snapshot_notifications_enabled(&self) -> bool {
487        true
488    }
489
490    /// Check if the plugin is interested in transaction data
491    /// Default is false -- if the plugin is interested in
492    /// transaction data, please return true.
493    fn transaction_notifications_enabled(&self) -> bool {
494        false
495    }
496
497    /// Check if the plugin is interested in entry data
498    /// Default is false -- if the plugin is interested in
499    /// entry data, return true.
500    fn entry_notifications_enabled(&self) -> bool {
501        false
502    }
503}
agave_geyser_plugin_interface/geyser_plugin_interface.rs

agave_geyser_plugin_interface/
geyser_plugin_interface.rs
