Add docs for notifying transactions via plugin (#22097) (#22178)

* Added documentations for streaming transactions via plugin

* Updated comments for transaction info

* Updated doc on transaction format

* Removed a white space

* Apply suggestions from code review from Tyera

Co-authored-by: Tyera Eulberg <teulberg@gmail.com>

Co-authored-by: Tyera Eulberg <teulberg@gmail.com>
(cherry picked from commit 135af08b8b)

Co-authored-by: Lijun Wang <83639177+lijunwangs@users.noreply.github.com>

accountsdb-plugin-interface/src/accountsdb_plugin_interface.rs

@@ -48,14 +48,26 @@ pub enum ReplicaAccountInfoVersions<'a> {
     V0_0_1(&'a ReplicaAccountInfo<'a>),
 }
 
+/// Information about a transaction
 #[derive(Clone, Debug)]
 pub struct ReplicaTransactionInfo<'a> {
+    /// The first signature of the transaction, used for identifying the transaction.
     pub signature: &'a Signature,
+
+    /// Indicates if the transaction is a simple vote transaction.
     pub is_vote: bool,
+
+    /// The sanitized transaction.
     pub transaction: &'a SanitizedTransaction,
+
+    /// Metadata of the transaction status.
     pub transaction_status_meta: &'a TransactionStatusMeta,
 }
 
+/// A wrapper to future-proof ReplicaTransactionInfo handling.
+/// If there were a change to the structure of ReplicaTransactionInfo,
+/// there would be new enum entry for the newer version, forcing
+/// plugin implementations to handle the change.
 pub enum ReplicaTransactionInfoVersions<'a> {
     V0_0_1(&'a ReplicaTransactionInfo<'a>),
 }

docs/src/developing/plugins/accountsdb_plugin.md

@@ -30,7 +30,8 @@ plugin implementation for the PostgreSQL database.
 
 [`solana-accountsdb-plugin-interface`]: https://docs.rs/solana-accountsdb-plugin-interface
 [`solana-accountsdb-plugin-postgres`]: https://docs.rs/solana-accountsdb-plugin-postgres
-
+[`solana-sdk`]: https://docs.rs/solana-sdk
+[`solana-transaction-status`]: https://docs.rs/solana-transaction-status
 
 ## The Plugin Interface
 
@@ -70,6 +71,21 @@ PostgreSQL plugin below for an example.
 The plugin can implement the `on_unload` method to do any cleanup before the
 plugin is unloaded when the validator is gracefully shutdown.
 
+The plugin framework supports streaming either accounts, transactions or both.
+A plugin uses the following function to indicate if it is interested in receiving
+account data:
+
+```
+fn account_data_notifications_enabled(&self) -> bool
+```
+
+And it uses the following function to indicate if it is interested in receiving
+transaction data:
+
+```
+    fn transaction_notifications_enabled(&self) -> bool
+```
+
 The following method is used for notifying on an account update:
 
 ```
@@ -115,6 +131,38 @@ To ensure data consistency, the plugin implementation can choose to abort
 the validator in case of error persisting to external stores. When the
 validator restarts the account data will be re-transmitted.
 
+The following method is used for notifying transactions:
+
+```
+    fn notify_transaction(
+        &mut self,
+        transaction: ReplicaTransactionInfoVersions,
+        slot: u64,
+    ) -> Result<()>
+```
+
+The `ReplicaTransactionInfoVersionsoVersions` struct
+contains the information about a streamed transaction. It wraps `ReplicaTransactionInfo`
+
+```
+pub struct ReplicaTransactionInfo<'a> {
+    /// The first signature of the transaction, used for identifying the transaction.
+    pub signature: &'a Signature,
+
+    /// Indicates if the transaction is a simple vote transaction.
+    pub is_vote: bool,
+
+    /// The sanitized transaction.
+    pub transaction: &'a SanitizedTransaction,
+
+    /// Metadata of the transaction status.
+    pub transaction_status_meta: &'a TransactionStatusMeta,
+}
+```
+For details of `SanitizedTransaction` and `TransactionStatusMeta `,
+please refer to [`solana-sdk`] and [`solana-transaction-status`]
+
+The `slot` points to the slot the transaction is executed at.
 For more details, please refer to the Rust documentation in
 [`solana-accountsdb-plugin-interface`].
 
@@ -193,6 +241,36 @@ To select all accounts, use the wildcard character (*):
     }
 ```
 
+### Transaction Selection
+
+`transaction_selector`, controls if and what transactions to store.
+If this field is missing, none of the transactions are stored.
+
+For example, one can use the following to select only the transactions
+referencing accounts with particular Base58-encoded Pubkeys,
+
+```
+"transaction_selector" : {
+    "mentions" : \["pubkey-1", "pubkey-2", ..., "pubkey-n"\],
+}
+```
+
+The `mentions` field supports wildcards to select all transaction or
+all 'vote' transactions. For example, to select all transactions:
+
+```
+"transaction_selector" : {
+    "mentions" : \["*"\],
+}
+```
+
+To select all vote transactions:
+
+```
+"transaction_selector" : {
+    "mentions" : \["all_votes"\],
+}
+```
 
 ### Database Setup
 
@@ -273,13 +351,13 @@ psql -U solana -p 5433 -h 10.138.0.9 -w -d solana
 
 #### Create the Schema Objects
 
-Use the [create_schema.sql](https://github.com/solana-labs/solana/blob/7ac43b16d2c766df61ae0a06d7aaf14ba61996ac/accountsdb-plugin-postgres/scripts/create_schema.sql)
+Use the [create_schema.sql](https://github.com/solana-labs/solana/blob/a70eb098f4ae9cd359c1e40bbb7752b3dd61de8d/accountsdb-plugin-postgres/scripts/create_schema.sql)
 to create the objects for storing accounts and slots.
 
 Download the script from github:
 
 ```
-wget https://raw.githubusercontent.com/solana-labs/solana/7ac43b16d2c766df61ae0a06d7aaf14ba61996ac/accountsdb-plugin-postgres/scripts/create_schema.sql
+wget https://raw.githubusercontent.com/solana-labs/solana/a70eb098f4ae9cd359c1e40bbb7752b3dd61de8d/accountsdb-plugin-postgres/scripts/create_schema.sql
 ```
 
 Then run the script:
@@ -294,7 +372,7 @@ argument mentioned above.
 #### Destroy the Schema Objects
 
 To destroy the database objects, created by `create_schema.sql`, use
-[drop_schema.sql](https://github.com/solana-labs/solana/blob/7ac43b16d2c766df61ae0a06d7aaf14ba61996ac/accountsdb-plugin-postgres/scripts/drop_schema.sql).
+[drop_schema.sql](https://github.com/solana-labs/solana/blob/a70eb098f4ae9cd359c1e40bbb7752b3dd61de8d/accountsdb-plugin-postgres/scripts/drop_schema.sql).
 For example,
 
 ```
@@ -346,6 +424,18 @@ delete from account_audit a2 where (pubkey, write_version) in
             where ranked.rnk > 1000)
 ```
 
+### Main Tables
+
+The following are the tables in the Postgres database
+
+| Table         | Description             |
+|:--------------|:------------------------|
+| account       | Account data            |
+| slot          | Slot metadata           |
+| transaction   | Transaction data        |
+| account_audit | Account historical data |
+
+
 ### Performance Considerations
 
 When a validator lacks sufficient compute power, the overhead of saving the