diff --git a/accountsdb-plugin-interface/src/accountsdb_plugin_interface.rs b/accountsdb-plugin-interface/src/accountsdb_plugin_interface.rs index 0f4fffb70e..e767d864a2 100644 --- a/accountsdb-plugin-interface/src/accountsdb_plugin_interface.rs +++ b/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>), } diff --git a/docs/src/developing/plugins/accountsdb_plugin.md b/docs/src/developing/plugins/accountsdb_plugin.md index fd12af4265..124d3551bb 100644 --- a/docs/src/developing/plugins/accountsdb_plugin.md +++ b/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