Add docs for notifying transactions via plugin (#22097)
* 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>
This commit is contained in:
parent
972730924b
commit
135af08b8b
|
@ -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>),
|
||||
}
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue