Update geyser documentations (#5571)

* Update geyser documentations

* Updating geyser readme

* Updating geyser readme for more event notificaiton timings

* Updated geyser doc based on latest changes

* Some feedback from Brennan

docs/src/validator/geyser.md

@@ -168,6 +168,91 @@ The `slot` points to the slot the transaction is executed at.
 For more details, please refer to the Rust documentation in
 [`agave-geyser-plugin-interface`].
 
+# Timing Relationships of Various Plugin Callbacks.
+
+Account update via update_account: As mentioned previously when is_startup is
+false, the account is updated during transaction processing. The account update
+has information about the transaction causing the update in the `txn` field.
+Note, when account update is sent during start up, the txn field is None as
+there is no transaction.
+
+```
+pub struct ReplicaAccountInfoV3<'a> {
+    /// The Pubkey for the account
+    pub pubkey: &'a [u8],
+
+    /// The lamports for the account
+    pub lamports: u64,
+
+    /// The Pubkey of the owner program account
+    pub owner: &'a [u8],
+
+    /// This account's data contains a loaded program (and is now read-only)
+    pub executable: bool,
+
+    /// The epoch at which this account will next owe rent
+    pub rent_epoch: u64,
+
+    /// The data held in this account.
+    pub data: &'a [u8],
+
+    /// A global monotonically increasing atomic number, which can be used
+    /// to tell the order of the account update. For example, when an
+    /// account is updated in the same slot multiple times, the update
+    /// with higher write_version should supersede the one with lower
+    /// write_version.
+    pub write_version: u64,
+
+    /// Reference to transaction causing this account modification
+    pub txn: Option<&'a SanitizedTransaction>,
+}
+```
+
+The updates are sent serially for different accounts via update_slot_status
+in the transaction for a slot. After the accounts notifications are sent, the
+SlotStatus::Processed event is sent.
+
+Starting with Agave 3.0, transaction notifications are sent before
+SlotStatus::Processed. In prior Agave version, even though SlotStatus::Processed
+is sent logically after the transaction events, because there are intermediate
+threads emitting the notitications to the plugin, the plugin can see the
+transaction notifications and the SlotStatus::Processed for a slot in either
+order.
+
+Within a block, transactions are ordered with transaction index. Transactions
+within a block are processed and notified in parallel. A plugin should use the
+transaction index to determine their relative order.
+
+A plugin can use the notify_block_metadata to know the
+executed_transaction_count for a given slot in the following structure:
+
+```
+/// Extending ReplicaBlockInfo by sending RewardsAndNumPartitions.
+#[derive(Clone, Debug)]
+#[repr(C)]
+pub struct ReplicaBlockInfoV4<'a> {
+    pub parent_slot: Slot,
+    pub parent_blockhash: &'a str,
+    pub slot: Slot,
+    pub blockhash: &'a str,
+    pub rewards: &'a RewardsAndNumPartitions,
+    pub block_time: Option<UnixTimestamp>,
+    pub block_height: Option<u64>,
+    pub executed_transaction_count: u64,
+    pub entry_count: u64,
+}
+```
+
+The plugin can associate accounts with transactions via the txn field in the
+ReplicaAccountInfoV3 structure. It can also use ReplicaTransactionInfoV2 in
+the notify_transaction callback to get the account addresses.
+
+The SlotStatus::Confirmed and SlotStatus::Processed events can reach the plugin
+in any order as they are sent asynchronous to each other. A plugin should wait
+for both events to confirm they are processed and confirmed.
+
+The SlotStatus::Rooted is sent after SlotStatus::Processed.
+
 ## Example PostgreSQL Plugin
 
 The [`solana-accountsdb-plugin-postgres`] repository implements a plugin storing

geyser-plugin-interface/src/geyser_plugin_interface.rs

@@ -1,7 +1,7 @@
-/// The interface for Geyser plugins. A plugin must implement
-/// the GeyserPlugin trait to work with the runtime.
-/// In addition, the dynamic library must export a "C" function _create_plugin which
-/// creates the implementation of the plugin.
+//! The interface for Geyser plugins. A plugin must implement
+//! the GeyserPlugin trait to work with the runtime.
+//! In addition, the dynamic library must export a "C" function _create_plugin which
+//! creates the implementation of the plugin.
 use {
     solana_clock::{Slot, UnixTimestamp},
     solana_hash::Hash,
@@ -11,7 +11,6 @@ use {
     std::{any::Any, error, io},
     thiserror::Error,
 };
-
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[repr(C)]
 /// Information about an account being updated