Docs improvements

SECURITY.md

@@ -71,7 +71,7 @@ Though we don't have an official bug bounty program, we generally offer rewards
 disclose vulnerabilities to us. Bounties are generally awarded for vulnerabilities classified as **high** or
 **critical** severity. Bounty amounts will be determined during the disclosure process, after the severity has been
 assessed.
-We are setting a bug bounty program at the moment. Rewards will be offered in retrospective, once the program is in
+We are setting up a bug bounty program at the moment. Rewards will be offered in retrospect, once the program is in
 place.
 
 > [!WARNING]

app/upgrades/README.md

@@ -1,7 +1,7 @@
 # Babylon Upgrades
 
 This folder contains sub-folders for every babylon upgrade. (Both state
-migrations, and hard forks) It also defines upgrade & hard fork structs,
+migrations and hard forks) It also defines upgrade & hard fork structs,
 that each upgrade implements. These then get included in the application
 app.go to run the upgrade.
 
@@ -27,7 +27,7 @@ type Upgrade struct {
  UpgradeName string
  // Function that creates an upgrade handler
  CreateUpgradeHandler func(mm *module.Manager, configurator module.Configurator, keepers *keepers.AppKeepers) upgradetypes.UpgradeHandler
- // Store upgrades, should be used for any new modules introduced, new modules deleted, or store names renamed.
+ // Store upgrades should be used for any new modules introduced, new modules deleted, or store names renamed.
  StoreUpgrades store.StoreUpgrades
 }
 

client/docs/README.md

@@ -2,12 +2,12 @@
 
 ## Workflows
 
-The following are the most prominent workflows. The diagrams depict cross-module communication, which hopefully helps us build a common picture of the high level interactions of the system.
+The following are the most prominent workflows. The diagrams depict cross-module communication, which hopefully helps us build a common picture of the high-level interactions of the system.
 
 ### Validator Registration and Staking
 
 In order to support regular checkpointing, Babylon has two extensions over the regular Tendermint consensus:
-* the use of epochs, during which the validator set in stable
+* the use of epochs, during which the validator is set in stable
 * the use of BLS keys for signature aggregation
 
 In order to keep changes to the Cosmos SDK to a minimum and maximize code reuse, the `epoching` module _wraps_ the `staking` module: the regular staking transactions are still used, but enveloped in a Babylon transaction that allows us to attach extra data as well as to control when these transactions are executed.
@@ -22,22 +22,22 @@ The next diagram depicts the process of the power transfer that takes place at t
 
 ### Submit Checkpoint
 
-Once the raw checkpoint is available, vigilantes take it and send them to Bitcoin,
+Once the raw checkpoint is available, vigilantes take it and send it to Bitcoin,
 paying the BTC fees, for future rewards on Babylon.
 
 ![Submit Checkpoint](diagrams/submit_checkpoint.png)
 
 ### BTC Light Client
 
-To be able to confirm checkpoints we need to know how deeply embedded they are into the Bitcoin mainchain. This requires an on-chain light client, which relayers feed each bitcoin header they observe.
+To be able to confirm checkpoints we need to know how deeply embedded they are into the Bitcoin mainchain. This requires an on-chain light client, which relayers feed each Bitcoin header they observe.
 
 ![BTC Light Client](diagrams/btc_light_client.png)
 
 ## Database Schema
 
 Even though we use a Key-Value store instead of a Relational Database, the following Entity Relationship Diagram is useful to get a sense of the conceptual data model, including the cardinalities. The grouping shows which module the collections belong to in the design.
 
-Note that some boxes are actually _messages_ and aren't part of the storage schema, they are just there to illustrate where some of the entities are coming from, or to establish a relationship between entities that come to life as a result of a common message, but then live separately without explicit foreign keys between them.
+Note that some boxes are actually _messages_ and aren't part of the storage schema, they are just there to illustrate where some of the entities are coming from or to establish a relationship between entities that come to life as a result of a common message, but then live separately without explicit foreign keys between them.
 
 ![Database Schema](diagrams/database_schema.png)
 

docs/README.md

@@ -1,6 +1,6 @@
 # Babylon Developer Docs
 
-This page contains documentation targeted at individuals that want to contribute to the Babylon repository.
+This page contains documentation targeted at individuals who want to contribute to the Babylon repository.
 
 For user-facing docs, visit the [Babylon documentation page](https://docs.babylonchain.io).
 

docs/architecture.md

@@ -38,7 +38,7 @@ module based on their depth according to the BTC Light Client module.
 ### [Checkpointing](../x/checkpointing)
 
 The checkpointing module is responsible for creating Babylon checkpoints
-to be submitted to Bitcoin and maintaining their confirmation status.
+to be submitted to Bitcoin and for maintaining their confirmation status.
 It collects the validator's
 [BLS signatures](https://en.wikipedia.org/wiki/BLS_digital_signature)
 for each block to be checkpointed and aggregates them
@@ -140,7 +140,7 @@ A standalone program that monitors:
   on the Bitcoin ledger to inform Babylon about them.
 - The execution of BTC Staking slashing transactions in the case
   of a finality provider double voting.
-  In the case of non-execution the monitor extracts the finality provider's
+  In the case of non-execution, the monitor extracts the finality provider's
   private key and executes the slashing.
 - The execution of a selective slashing attack launched
   by a finality provider. In this case,
@@ -205,7 +205,7 @@ inside the Babylon ledger to enable checkpointing and
 propagating checkpoint information to the Babylon smart contract
 deployed within the CZ.
 
-There are different IBC relayer implementations that can achieve
+Different IBC relayer implementations can achieve
 this function. Most notably:
 
 - [Cosmos Relayer](https://github.com/cosmos/relayer):

docs/staking-script.md

@@ -3,7 +3,7 @@
 ## Introduction
 
 Babylon's BTC staking protocol turns Bitcoin into a staking asset with the aim
-to enhance the economic security of the Babylon chain. Bitcoin holders can stake
+of enhancing the economic security of the Babylon chain. Bitcoin holders can stake
 their Bitcoin by locking them using a special transaction on the Bitcoin chain.
 The locked Bitcoin contributes to Babylon chain's economic security and generates
 yields for the Bitcoin stakers.
@@ -17,7 +17,7 @@ The protocol has the following important properties:
    itself (and in case of delegation, its delegatee) is malicious. This implies
    that, even if the Babylon chain is compromised and taken over by malicious
    actors, as long as the BTC staker itself (and the validator it delegates to
-   in case of delegation) is not malicious, its bitcoin stake is secure.
+   in case of delegation) is not malicious, its Bitcoin stake is secure.
 4. The protocol supports fractional slashing, meaning the protocol can be
    configured so that when slashing happens, only a fraction of the staked
    bitcoins are slashed, and the rest is returned to the staker.
@@ -32,14 +32,14 @@ The protocol has the following important properties:
 
 
 In the entire Bitcoin staking process, two parties are involved: one is called
-the Bitcoin Staker, and the other is called the Finality Provider.
+the Bitcoin Staker and the other is called the Finality Provider.
 
 - **Bitcoin Staker**: A Bitcoin Staker is an entity identified by `<StakerPk>`
 in staking scripts. Note that a staking transaction can be funded from
 arbitrary UTXO, including those owned by multisig/MPC/threshold accounts.
 Thus, `<StakerPk>` is not necessarily the address of the source of the fund.
 Rather, it is the controller and beneficiary of the stake after its creation.
-- **Finality Provider**: A Finality Provider is the an entity that votes
+- **Finality Provider**: A Finality Provider is an entity that votes
 in the finality round to provide security assurance to the PoS chain.
 
 The Bitcoin staker can choose a specific Finality Provider to delegate
@@ -50,15 +50,15 @@ transactions using BTC scripts.
 
 ## Preliminary
 
-Babylon interaction with Bitcoin is heavily based on Bitcoin's
+Babylon's interaction with Bitcoin is heavily based on Bitcoin's
 [Taproot upgrade](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki).
 This design choice was made due to the heavy usage of
 [Schnorr signatures](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)
 that were introduced through the Taproot upgrade.
 
 ## Staking Flow
 
-Following diagram shows how different transactions described in following
+The following diagram shows how different transactions described in the following
 paragraphs create and spend different bitcoin outputs:
 
 ```mermaid
@@ -113,8 +113,8 @@ slashable safety.
 
 The requirements for a valid staking transaction are:
 
-- it can contain arbitrary number of inputs
-- it can contain arbitrary number of outputs. One of those outputs must be
+- it can contain an arbitrary number of inputs
+- it can contain an arbitrary number of outputs. One of those outputs must be
   a Taproot output committing to the BTC staking scripts recognized by Babylon.
   Henceforth known as `Staking Output`.
 
@@ -163,7 +163,7 @@ For example, `StakerPK` must never be equal to `FinalityProviderPk`
 The staking output is a taproot output which can only be spent through a script
 spending path.
 The key spending path is disabled by using the "Nothing Up My Sleeve"
-(NUMS) point as internal key. Chosen point is the one described in
+(NUMS) point as internal key. The chosen point is the one described in
 [BIP341](https://github.com/bitcoin/bips/blob/master/bip-0341.mediawiki#constructing-and-spending-taproot-outputs)
 i.e,
 
@@ -187,7 +187,7 @@ Bitcoin blocks. It commits to a script of the form:
 
 where:
 
-- `<StakerPK>` is the BTC staker's public key..
+- `<StakerPK>` is the BTC staker's public key.
 - `<TimelockBlocks>` is the lockup period denoted in Bitcoin blocks. The
   timelock comes into effect after the Bitcoin transaction has been included in a
   mined block. In essence, the script denotes that only the staker can unlock the
@@ -240,40 +240,40 @@ where:
 
 This path can only be executed with the collaboration of the BTC staker,
 finality provider, and covenant committee.
-It is used in following way:
+It is used in the following way:
 
-- for stake to become active, staker must publish pre signed slashing transaction
-- covenant committee validates such transaction, and publish its own signatures.
-- the only signature missing to send slashing transaction is finality provider
-  signature. If finality provider private key leaks due to infractions, anyone can
-  sign slashing transaction and send slashing transaction to Bitcoin network.
+- for a stake to become active, the staker must publish pre signed slashing transaction
+- the covenant committee validates such transactions and publishes its own signatures.
+- the only signature missing to send slashing transactions is the finality provider
+  signature. If the finality provider's private key leaks due to infractions, anyone can
+  sign a slashing transaction and send the slashing transaction to the Bitcoin network.
 
 #### Difference between Unbonding and Slashing Path
 
 The main difference between the unbonding and slashing paths is the existence of
 `FinalityProviderPk` in the slashing path.
 
-This leads to following system wide repercussions:
+This leads to the following system-wide repercussions:
 
-- for staking request to become active, btc staker needs to provide valid
+- for staking request to become active, btc staker needs to provide a valid
   unbonding transaction in this staking request. This staking request will become
-  active only when `CovenantThreshold` signatures will be received by Babylon
+  active only when `CovenantThreshold` signatures are received by Babylon
   chain. Lack of `FinalityProviderPk` in unbonding path, means that after
-  delegation becomes active, staker can send unbonding transaction any time
-  without asking finality provider for permission.
-- existence of `FinalityProviderPk` in slashing path, coupled with the fact that
-  btc staker needs to provide pre-signed slashing transaction which needs to be
-  signed by covenant committee for delegation request to become active, leads to
-  situation in which the only signature missing to send slashing transaction to
-  btc is signature of finality provider.
+  the delegation becomes active, the staker can send unbonding transaction any time
+  without asking the finality provider for permission.
+- the existence of `FinalityProviderPk` in the slashing path, coupled with the fact that
+  btc staker needs to provide a pre-signed slashing transaction which needs to be
+  signed by the covenant committee for delegation request to become active, leads to
+  situation in which the only signature missing to send a slashing transaction to
+  btc is the signature of the finality provider.
 
 ### Unbonding output
 
-Unbonding output is a taproot output which can be only spent through script
+Unbonding output is a taproot output which can be only spent through the script
 spending path. The key spending path is disabled by using "Nothing Up My Sleeve"
-(NUMS) point as internal key. Chosen point is the one described in BIP341 i.e H
+(NUMS) point as an internal key. Chosen point is the one described in BIP341 i.e H
 = lift_x(0x50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0)
-which is point constructed by taking the hash of the standard uncompressed
+which is a point constructed by taking the hash of the standard uncompressed
 encoding of the secp256k1 base point G as X coordinate.
 
 Unbonding output can be spent by two script spending paths.
@@ -290,7 +290,7 @@ Bitcoin blocks. It commits to a script of the form:
 where:
 
 - `<StakerPK>` is btc staker public key
-- `<TimelockBlocks>` is unbonding time. It must be lower or equal 65535, but larger
+- `<TimelockBlocks>` is unbonding time. It must be lower or equal to 65535, but larger
   than `max(MinUnbondingTime, CheckpointFinalizationTimeout)`. `MinUnbondingTime`
   and `CheckpointFinalizationTimeout` are Babylon parameters.
 
@@ -319,5 +319,5 @@ where:
 #### Existence of Slashing path in Unbonding output
 
 The fact that slashing path exists in unbonding output means that even if staker
-is unbonding he can be slashed if finality provider commits infraction during
+is unbonding he can be slashed if the finality provider commits an infraction during
 unbonding time.

docs/transaction-impl-spec.md

@@ -72,7 +72,7 @@ the value in this output is known as `staking_amount`
 - have `OP_RETURN` output which contains: `global_parameters.tag`,
  `version`, `staker_pk`,`finality_provider_pk`, `staking_time`
 - all the values must be valid for the `global_parameters` which are applicable at
-the height in which the staking transaction is included in the BTC ledger.
+the height at which the staking transaction is included in the BTC ledger.
 
 
 #### OP_RETURN output description
@@ -117,8 +117,8 @@ StakingDataPkScript = 0x6a || 0x47 || SerializedStakingData
 ```
 
 where:
-- 0x6a - is byte marker representing OP_RETURN op code
-- 0x47 - is byte marker representing OP_DATA_71 op code, which pushed 71 bytes onto the stack
+- 0x6a - is the byte marker representing the OP_RETURN op code
+- 0x47 - is the byte marker representing the OP_DATA_71 op code, which pushed 71 bytes onto the stack
 
 The final OP_RETURN output will have the following shape:
 ```
@@ -151,11 +151,11 @@ be used as locking time in the `timelock_script`. It must be a valid `uint16` nu
 in the range `global_parameters.min_staking_time <= staking_time <= global_parameters.max_staking_time`.
 It needs to be put in the OP_RETURN output of the staking transaction.
 - `covenant_committee_public_keys` - it can be retrieved from
-`global_parameters.covenant_pks`. It is set of covenant committee public keys which
+`global_parameters.covenant_pks`. It is a set of covenant committee public keys which
 will be put in `unbonding_script` and `slashing_script`.
 - `covenant_committee_quorum` - it can be retrieved from
-`global_parameters.covenant_quorum`. It is quorum of covenant committee
-member required to authorize spending using `unbonding_script` or `slashing_script`
+`global_parameters.covenant_quorum`. It is a quorum of covenant committee
+members required to authorize spending using `unbonding_script` or `slashing_script`
 - `staking_amout` - chosen by the user, it will be placed in `staking_output.value`
 - `btc_network` - btc network on which staking transactions will take place
 
@@ -204,7 +204,7 @@ For the transaction to be considered a valid unbonding transaction, it must:
 - have exactly one input and one output
 - input must be valid a staking output
 - output must be a taproot output. This taproot output must have disabled
-the key spending path, and committed to script tree composed of two scripts:
+the key spending path, and committed to a script tree composed of two scripts:
 the timelock script and the slashing script. This output is henceforth known
 as the `unbonding_output`
 - timelock in the time lock script must be equal to `global_parameters.unbonding_time`
@@ -240,12 +240,12 @@ in `staking_transaction`
 
 ## Spending taproot outputs
 
-To create transactions which spend from taproot outputs, either staking output
+To create transactions that spend from taproot outputs, either staking output
 or unbonding output, providing signatures satisfying the script is not enough.
 
 The spender must also provide:
 - the whole script which is being spent
-- the control block which contains: leaf version, internal public key, and proof of
+- the control block which contains: the leaf version, internal public key, and proof of
 inclusion of the given script in the script tree
 
 Given that creating scripts is deterministic for given data, it is possible to
@@ -311,9 +311,9 @@ or to put them in a PSBT which can be used by bitcoind to create the witness.
 
 ### Creating PSBT to get signature for given taproot path from Bitcoind
 
-To avoid creating signatures/witness manually,
+To avoid creating signatures/witnesses manually,
 Bitcoind's [walletprocesspsbt](https://developer.bitcoin.org/reference/rpc/walletprocesspsbt.html)
-can be used. To use this Bitcoind endpoint to get signature/witness the wallet must
+can be used. To use this Bitcoind endpoint to get the signature/witness the wallet must
 maintain one of the keys used in the script.
 
 Example of creating psbt to sign unbonding transaction using unbonding script from
@@ -364,7 +364,7 @@ func BuildPsbtForSigningUnbondingTransaciton(
 
 ```
 
-Given that to spend through the unbonding script requires more than the
+Given that spending through the unbonding script requires more than the
 staker's signature, the `walletprocesspsbt` endpoint will produce a new psbt
 with the staker signature attached.
 

test/e2e/README.md

@@ -3,15 +3,15 @@
 ### `e2e` Package
 
 The `e2e` package defines an integration testing suite used for full
-end-to-end testing functionality. The package is copy of Osmosis e2e testing
+end-to-end testing functionality. The package is a copy of the Osmosis e2e testing
 approach.
 
 
 ### Wasm contract used for e2e testing
 
-Wasm contract located in `bytecode/babylon_contract.wasm` is compiled from most recent commit `main` branch - https://github.com/babylonchain/babylon-contract
+Wasm contract located in `bytecode/babylon_contract.wasm` is compiled from the most recent commit `main` branch - https://github.com/babylonchain/babylon-contract
 
-This contract uses feature specific to Babylon, through Babylon bindings library.
+This contract uses features specific to Babylon, through the Babylon bindings library.
 
 ### Common Problems