solana_client_traits/
lib.rs

1//! Defines traits for blocking (synchronous) and non-blocking (asynchronous)
2//! communication with a Solana server as well as a trait that encompasses both.
3//!
4//! //! Synchronous implementations are expected to create transactions, sign them, and send
5//! them with multiple retries, updating blockhashes and resigning as-needed.
6//!
7//! Asynchronous implementations are expected to create transactions, sign them, and send
8//! them but without waiting to see if the server accepted it.
9
10use {
11    solana_account::Account,
12    solana_commitment_config::CommitmentConfig,
13    solana_epoch_info::EpochInfo,
14    solana_hash::Hash,
15    solana_instruction::Instruction,
16    solana_keypair::Keypair,
17    solana_message::Message,
18    solana_pubkey::Pubkey,
19    solana_signature::Signature,
20    solana_signer::{signers::Signers, Signer},
21    solana_system_interface::instruction::transfer,
22    solana_transaction::{versioned::VersionedTransaction, Transaction},
23    solana_transaction_error::{TransactionResult, TransportResult as Result},
24};
25
26pub trait Client: SyncClient + AsyncClient {
27    fn tpu_addr(&self) -> String;
28}
29
30pub trait SyncClient {
31    /// Create a transaction from the given message, and send it to the
32    /// server, retrying as-needed.
33    fn send_and_confirm_message<T: Signers + ?Sized>(
34        &self,
35        keypairs: &T,
36        message: Message,
37    ) -> Result<Signature>;
38
39    /// Create a transaction from a single instruction that only requires
40    /// a single signer. Then send it to the server, retrying as-needed.
41    fn send_and_confirm_instruction(
42        &self,
43        keypair: &Keypair,
44        instruction: Instruction,
45    ) -> Result<Signature>;
46
47    /// Transfer lamports from `keypair` to `pubkey`, retrying until the
48    /// transfer completes or produces and error.
49    fn transfer_and_confirm(
50        &self,
51        lamports: u64,
52        keypair: &Keypair,
53        pubkey: &Pubkey,
54    ) -> Result<Signature>;
55
56    /// Get an account or None if not found.
57    fn get_account_data(&self, pubkey: &Pubkey) -> Result<Option<Vec<u8>>>;
58
59    /// Get an account or None if not found.
60    fn get_account(&self, pubkey: &Pubkey) -> Result<Option<Account>>;
61
62    /// Get an account or None if not found. Uses explicit commitment configuration.
63    fn get_account_with_commitment(
64        &self,
65        pubkey: &Pubkey,
66        commitment_config: CommitmentConfig,
67    ) -> Result<Option<Account>>;
68
69    /// Get account balance or 0 if not found.
70    fn get_balance(&self, pubkey: &Pubkey) -> Result<u64>;
71
72    /// Get account balance or 0 if not found. Uses explicit commitment configuration.
73    fn get_balance_with_commitment(
74        &self,
75        pubkey: &Pubkey,
76        commitment_config: CommitmentConfig,
77    ) -> Result<u64>;
78
79    fn get_minimum_balance_for_rent_exemption(&self, data_len: usize) -> Result<u64>;
80
81    /// Get signature status.
82    fn get_signature_status(&self, signature: &Signature) -> Result<Option<TransactionResult<()>>>;
83
84    /// Get signature status. Uses explicit commitment configuration.
85    fn get_signature_status_with_commitment(
86        &self,
87        signature: &Signature,
88        commitment_config: CommitmentConfig,
89    ) -> Result<Option<TransactionResult<()>>>;
90
91    /// Get last known slot
92    fn get_slot(&self) -> Result<u64>;
93
94    /// Get last known slot. Uses explicit commitment configuration.
95    fn get_slot_with_commitment(&self, commitment_config: CommitmentConfig) -> Result<u64>;
96
97    /// Get transaction count
98    fn get_transaction_count(&self) -> Result<u64>;
99
100    /// Get transaction count. Uses explicit commitment configuration.
101    fn get_transaction_count_with_commitment(
102        &self,
103        commitment_config: CommitmentConfig,
104    ) -> Result<u64>;
105
106    fn get_epoch_info(&self) -> Result<EpochInfo>;
107
108    /// Poll until the signature has been confirmed by at least `min_confirmed_blocks`
109    fn poll_for_signature_confirmation(
110        &self,
111        signature: &Signature,
112        min_confirmed_blocks: usize,
113    ) -> Result<usize>;
114
115    /// Poll to confirm a transaction.
116    fn poll_for_signature(&self, signature: &Signature) -> Result<()>;
117
118    /// Get last known blockhash
119    fn get_latest_blockhash(&self) -> Result<Hash>;
120
121    /// Get latest blockhash with last valid block height. Uses explicit commitment configuration.
122    fn get_latest_blockhash_with_commitment(
123        &self,
124        commitment_config: CommitmentConfig,
125    ) -> Result<(Hash, u64)>;
126
127    /// Check if the blockhash is valid
128    fn is_blockhash_valid(&self, blockhash: &Hash, commitment: CommitmentConfig) -> Result<bool>;
129
130    /// Calculate the fee for a `Message`
131    fn get_fee_for_message(&self, message: &Message) -> Result<u64>;
132}
133
134pub trait AsyncClient {
135    /// Send a signed transaction, but don't wait to see if the server accepted it.
136    fn async_send_transaction(&self, transaction: Transaction) -> Result<Signature> {
137        self.async_send_versioned_transaction(transaction.into())
138    }
139
140    /// Send a batch of signed transactions without confirmation.
141    fn async_send_batch(&self, transactions: Vec<Transaction>) -> Result<()> {
142        let transactions = transactions.into_iter().map(Into::into).collect();
143        self.async_send_versioned_transaction_batch(transactions)
144    }
145
146    /// Send a signed versioned transaction, but don't wait to see if the server accepted it.
147    fn async_send_versioned_transaction(
148        &self,
149        transaction: VersionedTransaction,
150    ) -> Result<Signature>;
151
152    /// Send a batch of signed versioned transactions without confirmation.
153    fn async_send_versioned_transaction_batch(
154        &self,
155        transactions: Vec<VersionedTransaction>,
156    ) -> Result<()> {
157        for t in transactions {
158            self.async_send_versioned_transaction(t)?;
159        }
160        Ok(())
161    }
162
163    /// Create a transaction from the given message, and send it to the
164    /// server, but don't wait for to see if the server accepted it.
165    fn async_send_message<T: Signers + ?Sized>(
166        &self,
167        keypairs: &T,
168        message: Message,
169        recent_blockhash: Hash,
170    ) -> Result<Signature> {
171        let transaction = Transaction::new(keypairs, message, recent_blockhash);
172        self.async_send_transaction(transaction)
173    }
174
175    /// Create a transaction from a single instruction that only requires
176    /// a single signer. Then send it to the server, but don't wait for a reply.
177    fn async_send_instruction(
178        &self,
179        keypair: &Keypair,
180        instruction: Instruction,
181        recent_blockhash: Hash,
182    ) -> Result<Signature> {
183        let message = Message::new(&[instruction], Some(&keypair.pubkey()));
184        self.async_send_message(&[keypair], message, recent_blockhash)
185    }
186
187    /// Attempt to transfer lamports from `keypair` to `pubkey`, but don't wait to confirm.
188    fn async_transfer(
189        &self,
190        lamports: u64,
191        keypair: &Keypair,
192        pubkey: &Pubkey,
193        recent_blockhash: Hash,
194    ) -> Result<Signature> {
195        let transfer_instruction = transfer(&keypair.pubkey(), pubkey, lamports);
196        self.async_send_instruction(keypair, transfer_instruction, recent_blockhash)
197    }
198}
solana_client_traits/lib.rs

solana_client_traits/
lib.rs
