Add Accountsdb plugin documentations (#21746)

accountsdb-plugin-interface/Cargo.toml

@@ -7,7 +7,7 @@ version = "1.9.0"
 repository = "https://github.com/solana-labs/solana"
 license = "Apache-2.0"
 homepage = "https://solana.com/"
-documentation = "https://docs.rs/solana-validator"
+documentation = "https://docs.rs/solana-accountsdb-plugin-interface"
 
 [dependencies]
 log = "0.4.11"

accountsdb-plugin-interface/src/accountsdb_plugin_interface.rs

@@ -12,16 +12,38 @@ use {
 impl Eq for ReplicaAccountInfo<'_> {}
 
 #[derive(Clone, PartialEq, Debug)]
+/// Information about an account being updated
 pub struct ReplicaAccountInfo<'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,
 }
 
+/// A wrapper to future-proof ReplicaAccountInfo handling.
+/// If there were a change to the structure of ReplicaAccountInfo,
+/// there would be new enum entry for the newer version, forcing
+/// plugin implementations to handle the change.
 pub enum ReplicaAccountInfoVersions<'a> {
     V0_0_1(&'a ReplicaAccountInfo<'a>),
 }
@@ -38,28 +60,44 @@ pub enum ReplicaTransactionInfoVersions<'a> {
     V0_0_1(&'a ReplicaTransactionInfo<'a>),
 }
 
+/// Errors returned by plugin calls
 #[derive(Error, Debug)]
 pub enum AccountsDbPluginError {
+    /// Error opening the configuration file; for example, when the file
+    /// is not found or when the validator process has no permission to read it.
     #[error("Error opening config file. Error detail: ({0}).")]
     ConfigFileOpenError(#[from] io::Error),
 
+    /// Error in reading the content of the config file or the content
+    /// is not in the expected format.
     #[error("Error reading config file. Error message: ({msg})")]
     ConfigFileReadError { msg: String },
 
+    /// Error when updating the account.
     #[error("Error updating account. Error message: ({msg})")]
     AccountsUpdateError { msg: String },
 
+    /// Error when updating the slot status
     #[error("Error updating slot status. Error message: ({msg})")]
     SlotStatusUpdateError { msg: String },
 
+    /// Any custom error defined by the plugin.
     #[error("Plugin-defined custom error. Error message: ({0})")]
     Custom(Box<dyn error::Error + Send + Sync>),
 }
 
+/// The current status of a slot
 #[derive(Debug, Clone)]
 pub enum SlotStatus {
+    /// The highest slot of the heaviest fork processed by the node. Ledger state at this slot is
+    /// not derived from a confirmed or finalized block, but if multiple forks are present, is from
+    /// the fork the validator believes is most likely to finalize.
     Processed,
+
+    /// The highest slot having reached max vote lockout.
     Rooted,
+
+    /// The highest slot that has been voted on by supermajority of the cluster, ie. is confirmed.
     Confirmed,
 }
 
@@ -75,6 +113,9 @@ impl SlotStatus {
 
 pub type Result<T> = std::result::Result<T, AccountsDbPluginError>;
 
+/// Defines an AccountsDb plugin, to stream data from the runtime.
+/// AccountsDb plugins must describe desired behavior for load and unload,
+/// as well as how they will handle streamed data.
 pub trait AccountsDbPlugin: Any + Send + Sync + std::fmt::Debug {
     fn name(&self) -> &'static str;
 
@@ -93,6 +134,9 @@ pub trait AccountsDbPlugin: Any + Send + Sync + std::fmt::Debug {
     fn on_unload(&mut self) {}
 
     /// Called when an account is updated at a slot.
+    /// When `is_startup` is true, it indicates the account is loaded from
+    /// snapshots when the validator starts up. When `is_startup` is false,
+    /// the account is updated during transaction processing.
     #[allow(unused_variables)]
     fn update_account(
         &mut self,

docs/sidebars.js

@@ -91,6 +91,7 @@ module.exports = {
       },
       "developing/test-validator",
       "developing/backwards-compatibility",
+      "developing/plugins/accountsdb_plugin"
     ],
     Integrating: ["integrations/exchange"],
     Validating: [