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_signature::Signature,
8    solana_transaction::sanitized::SanitizedTransaction,
9    solana_transaction_status::{Reward, RewardsAndNumPartitions, TransactionStatusMeta},
10    std::{any::Any, error, io},
11    thiserror::Error,
12};
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/// A wrapper to future-proof ReplicaTransactionInfo handling.
161/// If there were a change to the structure of ReplicaTransactionInfo,
162/// there would be new enum entry for the newer version, forcing
163/// plugin implementations to handle the change.
164#[repr(u32)]
165pub enum ReplicaTransactionInfoVersions<'a> {
166    V0_0_1(&'a ReplicaTransactionInfo<'a>),
167    V0_0_2(&'a ReplicaTransactionInfoV2<'a>),
168}
169
170#[derive(Clone, Debug)]
171#[repr(C)]
172pub struct ReplicaEntryInfo<'a> {
173    /// The slot number of the block containing this Entry
174    pub slot: Slot,
175    /// The Entry's index in the block
176    pub index: usize,
177    /// The number of hashes since the previous Entry
178    pub num_hashes: u64,
179    /// The Entry's SHA-256 hash, generated from the previous Entry's hash with
180    /// `solana_entry::entry::next_hash()`
181    pub hash: &'a [u8],
182    /// The number of executed transactions in the Entry
183    pub executed_transaction_count: u64,
184}
185
186#[derive(Clone, Debug)]
187#[repr(C)]
188pub struct ReplicaEntryInfoV2<'a> {
189    /// The slot number of the block containing this Entry
190    pub slot: Slot,
191    /// The Entry's index in the block
192    pub index: usize,
193    /// The number of hashes since the previous Entry
194    pub num_hashes: u64,
195    /// The Entry's SHA-256 hash, generated from the previous Entry's hash with
196    /// `solana_entry::entry::next_hash()`
197    pub hash: &'a [u8],
198    /// The number of executed transactions in the Entry
199    pub executed_transaction_count: u64,
200    /// The index-in-block of the first executed transaction in this Entry
201    pub starting_transaction_index: usize,
202}
203
204/// A wrapper to future-proof ReplicaEntryInfo handling. To make a change to the structure of
205/// ReplicaEntryInfo, add an new enum variant wrapping a newer version, which will force plugin
206/// implementations to handle the change.
207#[repr(u32)]
208pub enum ReplicaEntryInfoVersions<'a> {
209    V0_0_1(&'a ReplicaEntryInfo<'a>),
210    V0_0_2(&'a ReplicaEntryInfoV2<'a>),
211}
212
213#[derive(Clone, Debug)]
214#[repr(C)]
215pub struct ReplicaBlockInfo<'a> {
216    pub slot: Slot,
217    pub blockhash: &'a str,
218    pub rewards: &'a [Reward],
219    pub block_time: Option<UnixTimestamp>,
220    pub block_height: Option<u64>,
221}
222
223/// Extending ReplicaBlockInfo by sending the executed_transaction_count.
224#[derive(Clone, Debug)]
225#[repr(C)]
226pub struct ReplicaBlockInfoV2<'a> {
227    pub parent_slot: Slot,
228    pub parent_blockhash: &'a str,
229    pub slot: Slot,
230    pub blockhash: &'a str,
231    pub rewards: &'a [Reward],
232    pub block_time: Option<UnixTimestamp>,
233    pub block_height: Option<u64>,
234    pub executed_transaction_count: u64,
235}
236
237/// Extending ReplicaBlockInfo by sending the entries_count.
238#[derive(Clone, Debug)]
239#[repr(C)]
240pub struct ReplicaBlockInfoV3<'a> {
241    pub parent_slot: Slot,
242    pub parent_blockhash: &'a str,
243    pub slot: Slot,
244    pub blockhash: &'a str,
245    pub rewards: &'a [Reward],
246    pub block_time: Option<UnixTimestamp>,
247    pub block_height: Option<u64>,
248    pub executed_transaction_count: u64,
249    pub entry_count: u64,
250}
251
252/// Extending ReplicaBlockInfo by sending RewardsAndNumPartitions.
253#[derive(Clone, Debug)]
254#[repr(C)]
255pub struct ReplicaBlockInfoV4<'a> {
256    pub parent_slot: Slot,
257    pub parent_blockhash: &'a str,
258    pub slot: Slot,
259    pub blockhash: &'a str,
260    pub rewards: &'a RewardsAndNumPartitions,
261    pub block_time: Option<UnixTimestamp>,
262    pub block_height: Option<u64>,
263    pub executed_transaction_count: u64,
264    pub entry_count: u64,
265}
266
267#[repr(u32)]
268pub enum ReplicaBlockInfoVersions<'a> {
269    V0_0_1(&'a ReplicaBlockInfo<'a>),
270    V0_0_2(&'a ReplicaBlockInfoV2<'a>),
271    V0_0_3(&'a ReplicaBlockInfoV3<'a>),
272    V0_0_4(&'a ReplicaBlockInfoV4<'a>),
273}
274
275/// Errors returned by plugin calls
276#[derive(Error, Debug)]
277#[repr(u32)]
278pub enum GeyserPluginError {
279    /// Error opening the configuration file; for example, when the file
280    /// is not found or when the validator process has no permission to read it.
281    #[error("Error opening config file. Error detail: ({0}).")]
282    ConfigFileOpenError(#[from] io::Error),
283
284    /// Error in reading the content of the config file or the content
285    /// is not in the expected format.
286    #[error("Error reading config file. Error message: ({msg})")]
287    ConfigFileReadError { msg: String },
288
289    /// Error when updating the account.
290    #[error("Error updating account. Error message: ({msg})")]
291    AccountsUpdateError { msg: String },
292
293    /// Error when updating the slot status
294    #[error("Error updating slot status. Error message: ({msg})")]
295    SlotStatusUpdateError { msg: String },
296
297    /// Any custom error defined by the plugin.
298    #[error("Plugin-defined custom error. Error message: ({0})")]
299    Custom(Box<dyn error::Error + Send + Sync>),
300
301    /// Error when updating the transaction.
302    #[error("Error updating transaction. Error message: ({msg})")]
303    TransactionUpdateError { msg: String },
304}
305
306/// The current status of a slot
307#[derive(Debug, Clone, PartialEq, Eq)]
308#[repr(u32)]
309pub enum SlotStatus {
310    /// The highest slot of the heaviest fork processed by the node. Ledger state at this slot is
311    /// not derived from a confirmed or finalized block, but if multiple forks are present, is from
312    /// the fork the validator believes is most likely to finalize.
313    Processed,
314
315    /// The highest slot having reached max vote lockout.
316    Rooted,
317
318    /// The highest slot that has been voted on by supermajority of the cluster, ie. is confirmed.
319    Confirmed,
320
321    /// First Shred Received
322    FirstShredReceived,
323
324    /// All shreds for the slot have been received.
325    Completed,
326
327    /// A new bank fork is created with the slot
328    CreatedBank,
329
330    /// A slot is marked dead
331    Dead(String),
332}
333
334impl SlotStatus {
335    pub fn as_str(&self) -> &'static str {
336        match self {
337            SlotStatus::Confirmed => "confirmed",
338            SlotStatus::Processed => "processed",
339            SlotStatus::Rooted => "rooted",
340            SlotStatus::FirstShredReceived => "first_shred_received",
341            SlotStatus::Completed => "completed",
342            SlotStatus::CreatedBank => "created_bank",
343            SlotStatus::Dead(_error) => "dead",
344        }
345    }
346}
347
348pub type Result<T> = std::result::Result<T, GeyserPluginError>;
349
350/// Defines a Geyser plugin, to stream data from the runtime.
351/// Geyser plugins must describe desired behavior for load and unload,
352/// as well as how they will handle streamed data.
353pub trait GeyserPlugin: Any + Send + Sync + std::fmt::Debug {
354    /// The callback to allow the plugin to setup the logging configuration using the logger
355    /// and log level specified by the validator. Will be called first on load/reload, before any other
356    /// callback, and only called once.
357    /// # Examples
358    ///
359    /// ```
360    /// use agave_geyser_plugin_interface::geyser_plugin_interface::{GeyserPlugin,
361    /// GeyserPluginError, Result};
362    ///
363    /// #[derive(Debug)]
364    /// struct SamplePlugin;
365    /// impl GeyserPlugin for SamplePlugin {
366    ///     fn setup_logger(&self, logger: &'static dyn log::Log, level: log::LevelFilter) -> Result<()> {
367    ///        log::set_max_level(level);
368    ///        if let Err(err) = log::set_logger(logger) {
369    ///            return Err(GeyserPluginError::Custom(Box::new(err)));
370    ///        }
371    ///        Ok(())
372    ///     }
373    ///     fn name(&self) -> &'static str {
374    ///         &"sample"
375    ///     }
376    /// }
377    /// ```
378    #[allow(unused_variables)]
379    fn setup_logger(&self, logger: &'static dyn log::Log, level: log::LevelFilter) -> Result<()> {
380        Ok(())
381    }
382
383    fn name(&self) -> &'static str;
384
385    /// The callback called when a plugin is loaded by the system,
386    /// used for doing whatever initialization is required by the plugin.
387    /// The _config_file contains the name of the
388    /// of the config file. The config must be in JSON format and
389    /// include a field "libpath" indicating the full path
390    /// name of the shared library implementing this interface.
391    fn on_load(&mut self, _config_file: &str, _is_reload: bool) -> Result<()> {
392        Ok(())
393    }
394
395    /// The callback called right before a plugin is unloaded by the system
396    /// Used for doing cleanup before unload.
397    fn on_unload(&mut self) {}
398
399    /// Called when an account is updated at a slot.
400    /// When `is_startup` is true, it indicates the account is loaded from
401    /// snapshots when the validator starts up. When `is_startup` is false,
402    /// the account is updated during transaction processing.
403    #[allow(unused_variables)]
404    fn update_account(
405        &self,
406        account: ReplicaAccountInfoVersions,
407        slot: Slot,
408        is_startup: bool,
409    ) -> Result<()> {
410        Ok(())
411    }
412
413    /// Called when all accounts are notified of during startup.
414    fn notify_end_of_startup(&self) -> Result<()> {
415        Ok(())
416    }
417
418    /// Called when a slot status is updated
419    #[allow(unused_variables)]
420    fn update_slot_status(
421        &self,
422        slot: Slot,
423        parent: Option<u64>,
424        status: &SlotStatus,
425    ) -> Result<()> {
426        Ok(())
427    }
428
429    /// Called when a transaction is processed in a slot.
430    #[allow(unused_variables)]
431    fn notify_transaction(
432        &self,
433        transaction: ReplicaTransactionInfoVersions,
434        slot: Slot,
435    ) -> Result<()> {
436        Ok(())
437    }
438
439    /// Called when an entry is executed.
440    #[allow(unused_variables)]
441    fn notify_entry(&self, entry: ReplicaEntryInfoVersions) -> Result<()> {
442        Ok(())
443    }
444
445    /// Called when block's metadata is updated.
446    #[allow(unused_variables)]
447    fn notify_block_metadata(&self, blockinfo: ReplicaBlockInfoVersions) -> Result<()> {
448        Ok(())
449    }
450
451    /// Check if the plugin is interested in account data
452    /// Default is true -- if the plugin is not interested in
453    /// account data, please return false.
454    fn account_data_notifications_enabled(&self) -> bool {
455        true
456    }
457
458    /// Check if the plugin is interested in account data from snapshot
459    /// Default is true -- if the plugin is not interested in
460    /// account data snapshot, please return false because startup would be
461    /// improved significantly.
462    fn account_data_snapshot_notifications_enabled(&self) -> bool {
463        true
464    }
465
466    /// Check if the plugin is interested in transaction data
467    /// Default is false -- if the plugin is interested in
468    /// transaction data, please return true.
469    fn transaction_notifications_enabled(&self) -> bool {
470        false
471    }
472
473    /// Check if the plugin is interested in entry data
474    /// Default is false -- if the plugin is interested in
475    /// entry data, return true.
476    fn entry_notifications_enabled(&self) -> bool {
477        false
478    }
479}
agave_geyser_plugin_interface/geyser_plugin_interface.rs

agave_geyser_plugin_interface/
geyser_plugin_interface.rs
