Add docs!

banks-client/src/lib.rs

@@ -1,3 +1,10 @@
+//! A client for the ledger state, from the perspective of an arbitrary validator.
+//!
+//! Use start_tcp_client() to create a client and then import BanksClientExt to
+//! access its methods. Additional "*_with_context" methods are also available,
+//! but they are undocumented, may change over time, and are generally more
+//! cumbersome to use.
+
 use async_trait::async_trait;
 use futures::future::join_all;
 use solana_sdk::{
@@ -18,31 +25,67 @@ use tokio_serde::formats::Bincode;
 
 #[async_trait]
 pub trait BanksClientExt {
+    /// Send a transaction and return immediately. The server will resend the
+    /// transaction until either it is accepted by the cluster or the transaction's
+    /// blockhash expires.
     async fn send_transaction(&mut self, transaction: Transaction) -> io::Result<()>;
+
+    /// Return a recent, rooted blockhash from the server. The cluster will only accept
+    /// transactions with a blockhash that has not yet expired. Use the `get_fees`
+    /// method to get both a blockhash and the blockhash's last valid slot.
     async fn get_recent_blockhash(&mut self) -> io::Result<Hash>;
+
+    /// Return the fee parameters associated with a recent, rooted blockhash. The cluster
+    /// will use the transaction's blockhash to look up these same fee parameters and
+    /// use them to calculate the transaction fee.
     async fn get_fees(&mut self) -> io::Result<(FeeCalculator, Hash, Slot)>;
+
+    /// Send a transaction and return after the transaction has been rejected or
+    /// reached the given level of commitment.
     async fn process_transaction_with_commitment(
         &mut self,
         transaction: Transaction,
         commitment: CommitmentLevel,
     ) -> transport::Result<()>;
+
+    /// Send a transaction and return after the transaction has been finalized or rejected.
     async fn process_transaction(&mut self, transaction: Transaction) -> transport::Result<()>;
+
+    /// Return the status of a transaction with a signature matching the transaction's first
+    /// signature. Return None if the transaction is not found, which may be because the
+    /// blockhash was expired or the fee-paying account had insufficient funds to pay the
+    /// transaction fee. Note that servers rarely store the full transaction history. This
+    /// method may return None if the transaction status has been discarded.
     async fn get_transaction_status(
         &mut self,
         signature: Signature,
     ) -> io::Result<Option<TransactionStatus>>;
+
+    /// Same as get_transaction_status, but for multiple transactions.
     async fn get_transaction_statuses(
         &mut self,
         signatures: Vec<Signature>,
     ) -> io::Result<Vec<Option<TransactionStatus>>>;
+
+    /// Return the most recent rooted slot height. All transactions at or below this height
+    /// are said to be finalized. The cluster will not fork to a higher slot height.
     async fn get_root_slot(&mut self) -> io::Result<Slot>;
-    async fn get_account(&mut self, pubkey: Pubkey) -> io::Result<Option<Account>>;
+
+    /// Return the account at the given address at the time of the most recent root slot.
+    /// If the account is not found, None is returned.
+    async fn get_account(&mut self, address: Pubkey) -> io::Result<Option<Account>>;
+
+    /// Return the balance in lamports of an account at the given address at the slot
+    /// corresponding to the given commitment level.
     async fn get_balance_with_commitment(
         &mut self,
-        pubkey: Pubkey,
+        address: Pubkey,
         commitment: CommitmentLevel,
     ) -> io::Result<u64>;
-    async fn get_balance(&mut self, pubkey: Pubkey) -> io::Result<u64>;
+
+    /// Return the balance in lamports of an account at the given address at the time
+    /// of the most recent root slot.
+    async fn get_balance(&mut self, address: Pubkey) -> io::Result<u64>;
 }
 
 #[async_trait]
@@ -87,28 +130,28 @@ impl BanksClientExt for BanksClient {
             .await
     }
 
-    async fn get_account(&mut self, pubkey: Pubkey) -> io::Result<Option<Account>> {
+    async fn get_account(&mut self, address: Pubkey) -> io::Result<Option<Account>> {
         self.get_account_with_commitment_and_context(
             context::current(),
-            pubkey,
+            address,
             CommitmentLevel::default(),
         )
         .await
     }
 
     async fn get_balance_with_commitment(
         &mut self,
-        pubkey: Pubkey,
+        address: Pubkey,
         commitment: CommitmentLevel,
     ) -> io::Result<u64> {
         let account = self
-            .get_account_with_commitment_and_context(context::current(), pubkey, commitment)
+            .get_account_with_commitment_and_context(context::current(), address, commitment)
             .await?;
         Ok(account.map(|x| x.lamports).unwrap_or(0))
     }
 
-    async fn get_balance(&mut self, pubkey: Pubkey) -> io::Result<u64> {
-        self.get_balance_with_commitment(pubkey, CommitmentLevel::default())
+    async fn get_balance(&mut self, address: Pubkey) -> io::Result<u64> {
+        self.get_balance_with_commitment(address, CommitmentLevel::default())
             .await
     }
 

banks-server/src/banks_server.rs

@@ -216,11 +216,11 @@ impl Banks for BanksServer {
     async fn get_account_with_commitment_and_context(
         self,
         _: Context,
-        pubkey: Pubkey,
+        address: Pubkey,
         commitment: CommitmentLevel,
     ) -> Option<Account> {
         let bank = self.bank(commitment);
-        bank.get_account(&pubkey)
+        bank.get_account(&address)
     }
 }
 

sdk/src/commitment_config.rs

@@ -46,11 +46,27 @@ impl CommitmentConfig {
 
 #[derive(Serialize, Deserialize, Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[serde(rename_all = "camelCase")]
+/// An attribute of a slot. It describes how finalized a block is at some point in time. For example, a slot
+/// is said to be at the max level immediately after the cluster recognizes the block at that slot as
+/// finalized. When querying the ledger state, use lower levels of commitment to report progress and higher
+/// levels to ensure state changes will not be rolled back.
 pub enum CommitmentLevel {
+    /// The highest slot having reached max vote lockout, as recognized by a supermajority of the cluster.
     Max,
+
+    /// The highest slot of the heaviest fork. Ledger state at this slot is not derived from a finalized
+    /// block, but if multiple forks are present, is from the fork the validator believes is most likely
+    /// to finalize.
     Recent,
+
+    /// The highest slot having reached max vote lockout.
     Root,
+
+    /// The highest slot having reached 1 confirmation.
     Single,
+
+    /// The highest slot having reached 1 confirmation via gossip votes; may occur before or after Single,
+    /// depending on gossip traffic.
     SingleGossip,
 }
 

transaction-status/src/banks_trait.rs

@@ -24,7 +24,7 @@ pub trait Banks {
         commitment: CommitmentLevel,
     ) -> Option<transaction::Result<()>>;
     async fn get_account_with_commitment_and_context(
-        pubkey: Pubkey,
+        address: Pubkey,
         commitment: CommitmentLevel,
     ) -> Option<Account>;
 }