[comments] fix comments

programs/validator-bonds/src/checks.rs

@@ -112,7 +112,7 @@ pub fn check_stake_valid_delegation(
     }
 }
 
-/// the StakeAccount.delegation could be used but we want to verify
+/// the StakeAccount.delegation could be used, but we want to verify
 /// the state of the stake account that is generally expected for the protocol
 pub fn get_delegation(stake_account: &StakeAccount) -> Result<Option<Delegation>> {
     let stake_state = stake_account.deref();

programs/validator-bonds/src/instructions/bond/configure_bond_with_mint.rs

@@ -7,7 +7,7 @@ use anchor_lang::prelude::*;
 use anchor_spl::token::Mint;
 use anchor_spl::token::{burn, Burn, Token, TokenAccount};
 
-/// Change parameters of validator bond account with token burn
+/// Change parameters of validator bond account with token burning
 #[derive(Accounts)]
 pub struct ConfigureBondWithMint<'info> {
     pub config: Account<'info, Config>,

programs/validator-bonds/src/instructions/bond/fund_bond.rs

@@ -10,10 +10,10 @@ use anchor_lang::prelude::*;
 use anchor_lang::solana_program::stake::state::StakeAuthorize;
 use anchor_spl::stake::{authorize, Authorize, Stake, StakeAccount};
 
-/// Funding stake account to the validator bond record.
-// This operation can be done in same way with manually changing the widhtrawer and staker
-// authorities of the stake account to the bonds withdrawer authority address.
-// While this transaction ensures the stake account is in state that is considered as properly funded.
+/// Funds the stake account to the validator bond record.
+// The same operation can be performed by manually changing the withdrawer and staker
+// authorities of the stake account to match the bond's withdrawer authority address.
+// This transaction ensures the stake account is in a state considered properly funded.
 #[derive(Accounts)]
 pub struct FundBond<'info> {
     pub config: Account<'info, Config>,
@@ -31,7 +31,7 @@ pub struct FundBond<'info> {
     pub bond: Account<'info, Bond>,
 
     /// CHECK: PDA
-    /// new owner of the stake account, it's bonds withdrawer authority
+    /// new owner of the stake_account, it's the bonds withdrawer authority
     #[account(
         seeds = [
             b"bonds_authority",
@@ -59,7 +59,7 @@ impl<'info> FundBond<'info> {
     pub fn process(&mut self) -> Result<()> {
         require!(!self.config.paused, ErrorCode::ProgramIsPaused);
 
-        // when the stake account is already "owned" by the bonds program, let's just return OK
+        // when the stake account is already "owned" by the bonds program, return OK
         if check_stake_is_initialized_with_withdrawer_authority(
             &self.stake_account,
             &self.bonds_withdrawer_authority.key(),

programs/validator-bonds/src/instructions/bond/init_bond.rs

@@ -18,7 +18,7 @@ pub struct InitBondArgs {
 /// Creates new validator bond account based on the validator vote address
 #[derive(Accounts)]
 pub struct InitBond<'info> {
-    /// the config root account under which the bond is created
+    /// the config account under which the bond is created
     pub config: Account<'info, Config>,
 
     /// CHECK: deserialization of the vote account in the code
@@ -27,8 +27,8 @@ pub struct InitBond<'info> {
     )]
     pub vote_account: UncheckedAccount<'info>,
 
-    /// when validator identity signs the instruction then configuration arguments are applied
-    /// otherwise it's a permission-less operation that uses default init bond setup
+    /// permission-ed: the validator identity signs the instruction, InitBondArgs applied
+    /// permission-less: no signature, default init bond configuration
     pub validator_identity: Option<Signer<'info>>,
 
     #[account(

programs/validator-bonds/src/instructions/bond/mint_bond.rs

@@ -20,7 +20,8 @@ use anchor_spl::{
     token::{mint_to, Mint, MintTo, Token, TokenAccount},
 };
 
-/// Minting bond SPL token that can be used for configuring the bond account (see configure_mint_bond.rs)
+/// Minting a bond SPL token that can be used for configuring the bond account.
+// see configure_mint_bond.rs
 #[derive(Accounts)]
 pub struct MintBond<'info> {
     pub config: Account<'info, Config>,
@@ -49,7 +50,7 @@ pub struct MintBond<'info> {
     )]
     pub mint: Account<'info, Mint>,
 
-    /// CHECK: authority is checked to be related to the vote account in the code
+    /// CHECK: verified to be associated with the vote account in the code
     pub destination_authority: UncheckedAccount<'info>,
 
     #[account(
@@ -66,7 +67,7 @@ pub struct MintBond<'info> {
     )]
     pub vote_account: UncheckedAccount<'info>,
 
-    /// CHECK: New metadata account to be possibly created
+    /// CHECK: new token metadata to be possibly created
     #[account(mut)]
     pub metadata: UncheckedAccount<'info>,
 

programs/validator-bonds/src/instructions/config/configure_config.rs

@@ -16,7 +16,6 @@ pub struct ConfigureConfigArgs {
 /// Configures bond program with the config root account params
 #[derive(Accounts)]
 pub struct ConfigureConfig<'info> {
-    /// config root account that will be configured
     #[account(
         mut,
         has_one = admin_authority @ ErrorCode::InvalidAdminAuthority,

programs/validator-bonds/src/instructions/config/init_config.rs

@@ -15,15 +15,14 @@ pub struct InitConfigArgs {
 /// Creates a new config root account that configures the bonds program
 #[derive(Accounts)]
 pub struct InitConfig<'info> {
-    /// config root account to init
     #[account(
         init,
         payer = rent_payer,
         space = 8 + std::mem::size_of::<Config>()
     )]
     pub config: Account<'info, Config>,
 
-    /// rent exempt payer for the config (root) account
+    /// rent exempt payer for the config account
     #[account(
         mut,
         owner = system_program_id

programs/validator-bonds/src/instructions/settlement/claim_settlement.rs

@@ -30,10 +30,11 @@ pub struct ClaimSettlementArgs {
     pub claim: u64,
 }
 
+/// Claims a settlement by withdrawing settlement funded stake account
 #[derive(Accounts)]
 #[instruction(params: ClaimSettlementArgs)]
 pub struct ClaimSettlement<'info> {
-    /// the config root account under which the settlement was created
+    /// the config account under which the settlement was created
     pub config: Box<Account<'info, Config>>,
 
     #[account(
@@ -61,7 +62,7 @@ pub struct ClaimSettlement<'info> {
     )]
     pub settlement: Account<'info, Settlement>,
 
-    /// deduplication, one merkle tree record cannot be claimed twice
+    /// deduplication, merkle tree record cannot be claimed twice
     #[account(
         init,
         payer = rent_payer,
@@ -75,7 +76,7 @@ pub struct ClaimSettlement<'info> {
     )]
     pub settlement_claim: Account<'info, SettlementClaim>,
 
-    /// a stake account which will be withdrawn
+    /// a stake account that will be withdrawn
     #[account(mut)]
     pub stake_account_from: Box<Account<'info, StakeAccount>>,
 
@@ -87,7 +88,7 @@ pub struct ClaimSettlement<'info> {
     pub stake_account_to: Box<Account<'info, StakeAccount>>,
 
     /// CHECK: PDA
-    /// authority that manages (owns == being withdrawer authority) all stakes account under the bonds program
+    /// authority that manages (owns == by being withdrawer authority) all stakes account under the bonds program
     #[account(
         seeds = [
             b"bonds_authority",
@@ -97,8 +98,8 @@ pub struct ClaimSettlement<'info> {
     )]
     pub bonds_withdrawer_authority: UncheckedAccount<'info>,
 
-    /// On claiming it's created a claim account that confirms the claim has happened
-    /// when the settlement withdrawal window expires the claim account is closed and rent gets back
+    /// upon claiming, a claim account is created to confirm the occurrence of the claim
+    /// when the settlement withdrawal window expires, the claim account is closed, and the rent is refunded here
     #[account(
         mut,
         owner = system_program_id
@@ -197,7 +198,7 @@ impl<'info> ClaimSettlement<'info> {
 
         // The provided stake account must be sufficiently large to cover the claim while remaining valid.
         // It is the SDK's responsibility to merge stake accounts if necessary.
-        // - The invariant is that the stake account will always be rent-exempt + of minimum size.
+        // - The invariant is that the stake account will always be rent-exempt and of minimum size.
         //   This must be ensured by the fund_settlement instruction.
         if self.stake_account_from.get_lamports()
             < claim + minimal_size_stake_account(&stake_from_meta, &self.config)

programs/validator-bonds/src/instructions/settlement/close_settlement.rs

@@ -65,8 +65,8 @@ pub struct CloseSettlement<'info> {
     pub split_rent_collector: UncheckedAccount<'info>,
 
     /// CHECK: deserialization in code only when needed
-    /// The stake account funded to the settlement and credited to the bond's validator vote account.
-    /// The lamports are utilized to pay back the rent exempt of the split_stake_account, which can be created upon funding the settlement.
+    /// The stake account is funded to the settlement and credited to the bond's validator vote account.
+    /// The lamports are utilized to pay back the rent exemption of the split_stake_account, which can be created upon funding the settlement.
     #[account(mut)]
     pub split_rent_refund_account: UncheckedAccount<'info>,
 

programs/validator-bonds/src/instructions/settlement/fund_settlement.rs

@@ -22,9 +22,9 @@ use anchor_spl::stake::{
     authorize, deactivate_stake, Authorize, DeactivateStake, Stake, StakeAccount,
 };
 
-/// Funding settlement by providing stake account delegated to particular validator vote account based on the merkle proof.
-/// The settlement has been previously created by operator to fulfil some protected event (e.g., slashing)
-/// Currently permission-ed.
+/// Funding the settlement by providing a stake account delegated to a particular validator vote account based on the Merkle proof.
+/// The settlement has been previously created by the operator to fulfill some protected event (e.g., slashing).
+/// Permission-ed to operator authority.
 #[derive(Accounts)]
 pub struct FundSettlement<'info> {
     #[account(
@@ -58,16 +58,15 @@ pub struct FundSettlement<'info> {
     pub settlement: Account<'info, Settlement>,
 
     /// operator signer authority is allowed to fund the settlement account
-    /// (making this operation permission-ed, at least for the first version of the contract)
     pub operator_authority: Signer<'info>,
 
     /// stake account to be funded into the settlement
     #[account(mut)]
     pub stake_account: Account<'info, StakeAccount>,
 
     /// CHECK: PDA
-    /// settlement stake authority to differentiate deposited and funded stake accounts
-    /// deposited has got bonds_withdrawer_authority, whilst funded has got the settlement authority
+    /// the settlement stake authority differentiates between deposited and funded stake accounts
+    /// deposited accounts have the bonds_withdrawer_authority, while funded accounts have the settlement_staker_authority
     #[account(
         seeds = [
             b"settlement_authority",
@@ -88,10 +87,10 @@ pub struct FundSettlement<'info> {
     )]
     pub bonds_withdrawer_authority: UncheckedAccount<'info>,
 
-    /// an account that does not exist, it will be initialized as a stake account (the signature needed)
-    /// the split_stake_account is needed when the provided stake_account is consists of more lamports
-    /// than the amount needed to fund the settlement, the left-over lamports from the stake account is split
-    /// into the new split_stake_account; when the split_stake_account is not needed, the rent payer is refunded
+    /// if an account that does not exist is provided, it will be initialized as a stake account (with the necessary signature)
+    /// the split_stake_account is required when the provided stake_account contains more lamports than necessary to fund the settlement
+    /// in this case, the excess lamports from the stake account are split into the new split_stake_account,
+    /// if the split_stake_account is not needed, the rent payer is refunded back within tx
     #[account(
         init,
         payer = split_stake_rent_payer,
@@ -100,9 +99,9 @@ pub struct FundSettlement<'info> {
     )]
     pub split_stake_account: Account<'info, StakeAccount>,
 
-    /// rent exempt payer of the split_stake_account creation
-    /// if the split_stake_account is not needed (no left-over lamports on funding) then rent payer is refunded
-    /// it the split_stake_account is needed to spill out over funding of the settlement
+    /// the rent exempt payer of the split_stake_account creation
+    /// if the split_stake_account is not needed (no leftover lamports on funding), then the rent payer is refunded
+    /// if the split_stake_account is needed to spill out over funding of the settlement,
     ///     then the rent payer is refunded when the settlement is closed
     #[account(
         mut,
@@ -145,8 +144,9 @@ impl<'info> FundSettlement<'info> {
             &self.bonds_withdrawer_authority.key(),
             "stake_account",
         )?;
-        // provided stake account must NOT have been used to fund settlement (but must be owned by bonds program)
-        // funded to bond account -> staker == bonds withdrawer authority, funded to settlement -> staker == settlement staker authority
+        // the provided stake account must NOT have been used to fund settlement (but must be owned by the bonds program)
+        // when funded to the bond account, the staker must be equal to the bonds withdrawer authority
+        // when funded to the settlement, the staker must be equal to the settlement staker authority
         require_keys_eq!(
             stake_meta.authorized.staker,
             self.bonds_withdrawer_authority.key(),
@@ -174,7 +174,7 @@ impl<'info> FundSettlement<'info> {
             && amount_available - amount_needed >= stake_account_min_size + split_stake_rent_exempt;
 
         let (funding_amount, is_split) =
-            // no split needed or possible, whole stake account funded, still amout funded is substracted off the min size
+            // no split needed or possible, whole stake account funded, still amount funded is subtracted off the min size
             // as after claiming the stake will be capable to exist
             if amount_available <= amount_needed || !left_over_splittable  {
                 let lamports_to_fund = self.stake_account.get_lamports() - stake_account_min_size;
@@ -247,8 +247,7 @@ impl<'info> FundSettlement<'info> {
                 self.stake_account.key()
             );
         }
-        // moving stake account from bond authority to settlement authority
-        // to differentiate settlement funded and settlement non-funded stake accounts
+        // funding, i.e., moving stake account from bond authority to settlement authority
         authorize(
             CpiContext::new_with_signer(
                 self.stake_program.to_account_info(),

programs/validator-bonds/src/instructions/settlement/init_settlement.rs

@@ -21,7 +21,8 @@ pub struct InitSettlementArgs {
     pub epoch: u64,
 }
 
-/// Creates settlement account for the bond, only operator authority can create the account
+/// Creates settlement account for the bond.
+/// Permission-ed for operator authority.
 #[derive(Accounts)]
 #[instruction(params: InitSettlementArgs)]
 pub struct InitSettlement<'info> {

programs/validator-bonds/src/instructions/stake/merge_stake.rs

@@ -18,7 +18,7 @@ pub struct MergeStakeArgs {
 
 #[derive(Accounts)]
 pub struct MergeStake<'info> {
-    /// the config root account under which the bond was created
+    /// the config account under which the bond was created
     pub config: Account<'info, Config>,
 
     #[account(
@@ -71,7 +71,7 @@ impl<'info> MergeStake<'info> {
                 .with_pubkeys((source_meta.authorized.staker, self.staker_authority.key())));
         }
 
-        // withdrawer authorities must belongs to the bonds program (bonds program ownership)
+        // withdrawer authorities must belong to the bonds program (bonds program ownership)
         let (bonds_withdrawer_authority, _) = find_bonds_withdrawer_authority(&self.config.key());
         if source_meta.authorized.withdrawer != bonds_withdrawer_authority
             || destination_meta.authorized.withdrawer != bonds_withdrawer_authority

programs/validator-bonds/src/instructions/stake/reset_stake.rs

@@ -13,11 +13,11 @@ use anchor_lang::solana_program::vote::program::ID as vote_program_id;
 use anchor_lang::solana_program::{stake, stake::state::StakeAuthorize, sysvar::stake_history};
 use anchor_spl::stake::{authorize, Authorize, Stake, StakeAccount};
 
-/// Resetting stake authority of a funded stake account belonging to removed settlement.
-/// I.e., for provided stake account it changes the stake authority from settlement stake authority to bonds withdrawer authority.
+/// Resetting the stake authority of a funded stake account belonging to a removed settlement.
+/// I.e., for the provided stake account, it changes the stake authority from the settlement stake authority to the bonds withdrawer authority.
 #[derive(Accounts)]
 pub struct ResetStake<'info> {
-    /// the config root account under which the bond was created
+    /// the config account under which the bond was created
     pub config: Account<'info, Config>,
 
     #[account(

programs/validator-bonds/src/instructions/stake/withdraw_stake.rs

@@ -13,10 +13,10 @@ use anchor_spl::stake::{withdraw, Stake, StakeAccount, Withdraw};
 use std::ops::Deref;
 
 /// Withdrawing funded stake account belonging to removed settlement that has not been delegated (it's in Initialized state).
-/// Such a stake account is considered belonging to operator of the config account.
+/// Such a stake account is considered belonging to the operator of the config account.
 #[derive(Accounts)]
 pub struct WithdrawStake<'info> {
-    /// the config root account under which the bond was created
+    /// the config account under which the bond was created
     #[account(
         has_one = operator_authority @ ErrorCode::InvalidOperatorAuthority,
     )]

programs/validator-bonds/src/instructions/withdraw/cancel_withdraw_request.rs

@@ -7,8 +7,9 @@ use crate::state::withdraw_request::WithdrawRequest;
 use anchor_lang::prelude::*;
 use anchor_lang::solana_program::vote::program::ID as vote_program_id;
 
-/// Cancelling validator bond withdraw request.
-/// Only one withdraw request per bond. Cancelling makes a way for a new request with new amount.
+/// Cancelling a validator bond withdrawal request.
+/// Only one withdrawal request per bond is permitted.
+/// Cancelling makes way for a new request with a new amount.
 #[derive(Accounts)]
 pub struct CancelWithdrawRequest<'info> {
     pub config: Account<'info, Config>,

programs/validator-bonds/src/instructions/withdraw/claim_withdraw_request.rs

@@ -18,8 +18,9 @@ use anchor_lang::solana_program::{
 };
 use anchor_spl::stake::{authorize, Authorize, Stake, StakeAccount};
 
-/// Withdrawing funds from a bond account, to proceed the withdrawal one must create a withdraw request first.
-/// Withdrawal takes StakeAccount that associated with bonds program and changes owner back to validator vote withdrawer.
+/// Withdrawing funds from a bond account requires creating a withdrawal request first.
+/// The withdrawal process involves taking a StakeAccount associated with the bonds program
+/// and changing its owner (withdrawer and staker authorities) back to the validator vote withdrawer.
 #[derive(Accounts)]
 pub struct ClaimWithdrawRequest<'info> {
     /// the config root configuration account

programs/validator-bonds/src/instructions/withdraw/init_withdraw_request.rs

@@ -13,10 +13,10 @@ pub struct InitWithdrawRequestArgs {
     pub amount: u64,
 }
 
-/// Creates a withdrawal request of bond funds for a validator vote account
+/// Creates a withdrawal request when validator wants to withdraw the bond
 #[derive(Accounts)]
 pub struct InitWithdrawRequest<'info> {
-    /// the config root account under which the bond was created
+    /// the config account under which the bond was created
     pub config: Account<'info, Config>,
 
     #[account(

programs/validator-bonds/src/state/bond.rs

@@ -7,8 +7,8 @@ use anchor_lang::prelude::*;
 #[account]
 #[derive(Debug)]
 pub struct Bond {
-    /// Contract root config address. Validator bond is created for this config as PDA
-    /// but saving the address here for easier access with getProgramAccounts call
+    /// Program root config address. Validator bond is created for this config as PDA
+    // saving the address here for easier access with getProgramAccounts call
     pub config: Pubkey,
     /// Validator vote address that this bond account is crated for
     /// INVARIANTS: