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

solana_client_traits/
lib.rs
