Edit PR aptos-labs#5763 belatedly (aptos-labs#5795)

* Edit PR aptos-labs#5763 belatedly

* Move Aptos Blockchain Deep Dive back down in navigation per reviewer feedback

Co-authored-by: Clay Murphy <[email protected]>

developer-docs-site/docs/concepts/blocks.md

@@ -7,7 +7,7 @@ id: "blocks"
 
 Aptos is a per-transaction versioned database. When transactions are executed, the resulting state of each transaction is stored separately and thus allows for more granular data access. This is different from other blockchains where only the resulting state of a block (a group of transactions) is stored.
 
-Blocks are still a fundamental unit within Aptos. Transactions are batched and executed together in a block. In addition, the [proofs](../concepts/txns-states/#proofs) within storage are at the block-level granularity. The number of transactions within a block varies depending on network activity and a configurable maximum block size limit. As the blockchain becomes busier, blocks will likely contain more transactions.
+Blocks are still a fundamental unit within Aptos. Transactions are batched and executed together in a block. In addition, the [proofs](./txns-states.md#proofs) within storage are at the block-level granularity. The number of transactions within a block varies depending on network activity and a configurable maximum block size limit. As the blockchain becomes busier, blocks will likely contain more transactions.
 
 ## System transactions
 

developer-docs-site/docs/concepts/gas-txn-fee.md

@@ -17,18 +17,18 @@ Conceptually, this fee can be thought of as quite similar to how we pay for our
 
 ## Unit of gas
 
-Transactions can range from simple and inexpensive to complicated based upon the amount of computation and fetches from and writes to storage. In the Aptos blockchain, a **unit of gas** represents a basic unit of resource consumption for both
+Transactions can range from simple and inexpensive to complicated based upon the amount of computation and fetches from and writes to storage. In the Aptos blockchain, a **unit of gas** represents a basic unit of resource consumption for both:
 
-- Computation resource, and
-- Storage resource.
+- Computation resource
+- Storage resource
 
 See [How Base Gas Works](./base-gas.md) for a detailed description of gas fee types and available optimizations.
 
 ## Gas price and prioritizing transactions
 
 In the Aptos network, the Aptos governance sets the minimum gas unit price. However, the market determines the actual minimum gas unit price. See [Ethereum Gas Tracker](https://etherscan.io/gastracker), for example, which shows the market price movements of Ethereum gas price.
 
-By specifying a higher gas unit price than the current market price, you can **increase** the priority level for your transaction on the blockchain by paying. While in most cases, this is unnecessary, if the network is under load, this can ensure that your transaction can be processed more quickly.
+By specifying a higher gas unit price than the current market price, you can **increase** the priority level for your transaction on the blockchain by paying a larger processing fee. While in most cases this is unnecessary, if the network is under load this measure can ensure your transaction is processed more quickly. See the `gas_unit_price` entry under [Estimating the gas units via simulation](#estimating-the-gas-units-via-simulation) for details.
 
 :::tip Unit of gas
 👉 A **unit of gas** is a dimensionless number, expressed as an integer. The total gas units consumed by your transaction depends on the complexity of your transaction. The **gas price**, on the other hand, is expressed in terms of Aptos blockchain’s native coin (Octas). Also see [Transactions and States](/concepts/txns-states) for how a transaction submitted to the Aptos blockchain looks like.
@@ -111,5 +111,5 @@ The simulation steps for finding the correct amount of gas for a transaction are
 6. If you feel the need to prioritize or deprioritize your transaction, adjust the `gas_unit_price` of the transaction. Increase the value for higher priority, and decrease the value for lower priority.
 
 ::: tip
-Prioritization is based upon buckets of `gas_unit_price`. The buckets are defined [here](https://github.com/aptos-labs/aptos-core/blob/30b385bf38d3dc8c4e8ee0ff045bc5d0d2f67a85/config/src/config/mempool_config.rs#L8). The current buckets are `[0, 150, 300, 500, 1000, 3000, 5000, 10000, 100000, 1000000]`. Therefore a `gas_unit_price` of 150 and 299 would be priortized nearly the same.
+Prioritization is based upon buckets of `gas_unit_price`. The buckets are defined in [`mempool_config.rs`](https://github.com/aptos-labs/aptos-core/blob/30b385bf38d3dc8c4e8ee0ff045bc5d0d2f67a85/config/src/config/mempool_config.rs#L8). The current buckets are `[0, 150, 300, 500, 1000, 3000, 5000, 10000, 100000, 1000000]`. Therefore, a `gas_unit_price` of 150 and 299 would be priortized nearly the same.
 :::

developer-docs-site/docs/concepts/governance.md

@@ -27,21 +27,21 @@ sources={{
 />
 
 - The  Aptos community can suggest an Aptos Improvement Proposal (AIP) in [GitHub](https://github.com/aptos-foundation/aip).
-- When appropriate, an on-chain proposal can be created for the AIP via the `AptosGovernance` module. 
-- Voters can then vote on this proposal on-chain via the `AptosGovernance` module. If there is sufficient support for a proposal, then it can be resolved.
-- Governance requires a minimal number of votes to be cast by an expiration threshold. However, if sufficient votes, more than 50% of th total supply, are accumulated prior to that threshold, the proposal can be executed **without waiting for the full voting period**.
+- When appropriate, an on-chain proposal can be created for the AIP via the `aptos_governance` module. 
+- Voters can then vote on this proposal on-chain via the `aptos_governance` module. If there is sufficient support for a proposal, then it can be resolved.
+- Governance requires a minimal number of votes to be cast by an expiration threshold. However, if sufficient votes, more than 50% of the total supply, are accumulated prior to that threshold, the proposal can be executed **without waiting for the full voting period**.
 
 ## Who can propose
 
 - To either propose or vote, you must stake but you are not required to run a validator node. However, we recommend that you be a validator with a stake and be a part of the validator set. 
 - To create a proposal, the proposer's backing stake pool must have the minimum required proposer stake. The proposer's stake must be locked up for at least as long as the proposal's voting period. This is to avoid potential spammy proposals. 
-- Proposers can create a proposal by calling [`AptosGovernance::create_proposal`](https://github.com/aptos-labs/aptos-core/blob/27a255ebc662817944435349afc4ec33ea317e64/aptos-move/framework/aptos-framework/sources/aptos_governance.move#L183).
+- Proposers can create a proposal by calling [`aptos_governance::create_proposal`](https://github.com/aptos-labs/aptos-core/blob/27a255ebc662817944435349afc4ec33ea317e64/aptos-move/framework/aptos-framework/sources/aptos_governance.move#L183).
 
 ## Who can vote
 
 - To vote, you must stake, though you are not required to run a validator node. Your voting power is derived from the backing stake pool. 
 - Voting power is calculated based on the current epoch's active stake of the proposer or voter's backing stake pool. In addition, the stake pool's lockup must be at least as long as the proposal's duration.
 
 :::tip
-Each stake pool can only be used to vote on each proposal exactly once.
+Each stake pool can be used to vote on each proposal exactly only one time.
 :::

developer-docs-site/docs/concepts/resources.md

@@ -9,10 +9,10 @@ On Aptos, on-chain state is organized into resources and modules. These are then
 
 ## Resources vs Objects
 
-Resources refer to top-level objects that are stored directly with an account on the blockchain. Both resources and object are instances of structs. Objects can be resources but can also be individual units of state that are stored inside a resource. An example here is how the APT coin is stored: CoinStore is the resource that contains the APT coin while the Coin itself is an object:
+Resources refer to top-level objects that are stored directly with an account on the blockchain. Both resources and objects are instances of structs. Objects can be resources but can also be individual units of state that are stored inside a resource. An example here is how the APT coin is stored: CoinStore is the resource that contains the APT coin, while the Coin itself is an object:
 
 ```rust
-/// A holder of a specific coin types and associated event handles.
+/// A holder of a specific coin type and associated event handles.
 /// These are kept in a single resource to ensure locality of data.
 struct CoinStore<phantom CoinType> has key {
     coin: Coin<CoinType>,
@@ -33,7 +33,7 @@ struct CustomCoinBox<phantom CoinType> has key {
 }
 ```
 
-## Resource and Object Definition
+## Define resources and objects
 
 All objects and resources are defined within a module that is stored at an address. For example `0x1234::coin::Coin<0x1234::coin::SomeCoin>` would be represented as:
 
@@ -52,17 +52,17 @@ In this example, `0x1234` is the address, `coin` is the module, `Coin` is a stru
 ## Dual ownership of objects, including resources
 
 Objects (including resources) on Aptos are owned by both:
-1. The account where the object is stored, and
+1. The account where the object is stored.
 2. The module that defines the object.
 
-Creating a new resource and storing it into an account requires both the owning account's signature and the module's code. But modifying and deleting the resource/object requires only the module's code and the owning account's address. The fields of an object also can be read only directly by the module's code, which can be offered as public utilities for other modules.
+Creating a new resource and storing it into an account requires both the owning account's signature and the module's code. But modifying and deleting the resource/object requires only the module's code and the owning account's address, but not its signature. The fields of an object also can be read only directly by the module's code, which can be offered as public utilities for other modules.
 
 This dual-ownership design is one of the bases of state safety in Aptos Move and enables powerful but safe functionalities to be built around resources and objects.
 
 ## Viewing a resource
 
-Resources are stored within specific accounts. Resources can be located by searching within the owners account for the resource at its full query path inclusive of its address and module. Resources can be viewed on the [Aptos Explorer](https://explorer.aptoslabs.com/) by searching for the owning account or be directly fetched from a fullnode's API. See [Interacting with the blockchain](../guides/interacting-with-the-blockchain.md) for more information.
+Resources are stored within specific accounts. Resources can be located by searching within the owner's account for the resource at its full query path inclusive of its address and module. Resources can be viewed on the [Aptos Explorer](https://explorer.aptoslabs.com/) by searching for the owning account or be directly fetched from a fullnode's API. See [Interacting with the blockchain](../guides/interacting-with-the-blockchain.md) for more information.
 
 ## How resources are stored
 
-It's up to the smart contract developers to decide how and where a specific state is stored. For example, events for depositing a token can be stored in the receiver account where the deposit happens or in the account the token module is deployed at. In general, storing data in individual user accounts enables a higher level of execution efficiency as there would be no state read/write conflicts among transactions, and they can be executed in parallel.
+It's up to the smart contract developers to decide how and where a specific state is stored. For example, events for depositing a token can be stored in the receiver account where the deposit happens or in the account where the token module is deployed. In general, storing data in individual user accounts enables a higher level of execution efficiency as there would be no state read/write conflicts among transactions, and they can be executed in parallel.

developer-docs-site/docs/concepts/staking.md

@@ -8,18 +8,18 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 # Staking
 
 :::tip Consensus
-We strongly recommend that you read the consensus section of [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn#consensus) before proceeding further. 
+We strongly recommend that you read the consensus section of [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn.md#consensus) before proceeding further. 
 :::
 
 In a distributed system like blockchain, executing a transaction is distinct from updating the state of the ledger and persisting the results in storage. An agreement, i.e., consensus, must be reached by a quorum of validators on the ordering of transactions and their execution results before these results are persisted in storage and the state of the ledger is updated. 
 
-Anyone can participate in the Aptos consensus process, if they stake sufficient utility coin, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is proportional to the amount of validator's stake. In exchange, the validator is rewarded proportionally to the amount staked. Hence, the performance of the Blockchain is aligned with the validator's interest, i.e., rewards.  
+Anyone can participate in the Aptos consensus process, if they stake sufficient utility coin, i.e., place their utility coin into escrow. To encourage validators to participate in the consensus process, each validator's vote weight is proportional to the amount of validator's stake. In exchange, the validator is rewarded proportionally to the amount staked. Hence, the performance of the blockchain is aligned with the validator's interest, i.e., rewards.  
 
 :::note 
-Currently slashing is not implemented.
+Currently, slashing is not implemented.
 :::
 
-The current on-chain data can be found [here](https://mainnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::staking_config::StakingConfig). With the configuration set defined in [staking_config.move](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move).
+The current on-chain data can be found in [`staking_config::StakingConfig`](https://mainnet.aptoslabs.com/v1/accounts/0x1/resource/0x1::staking_config::StakingConfig). The configuration set is defined in [`staking_config.move`](https://github.com/aptos-labs/aptos-core/blob/main/aptos-move/framework/aptos-framework/sources/configs/staking_config.move).
 
 The rest of this document presents how staking works on the Aptos blockchain. See [Supporting documentation](#supporting-documentation) at the bottom for related resources.
 
@@ -90,7 +90,7 @@ Throughout the duration of an epoch, the following flow of events occurs several
 
 - A validator leader is selected by a deterministic formula based on the validator reputation determined by validator's performance (including whether the validator has voted in the past or not) and stake. **This leader selection is not done by voting.**
 - The selected leader sends a proposal containing the collected quorum votes of the previous proposal and the leader's proposed order of transactions for the new block. 
-- All the validators from the validator set will vote on the leader's proposal for the new block. Once consensus is reached the block can be finalized. Hence the actual list of votes to achieve consensus is a subset of all the validators in the validator set. This leader validator is rewarded. **Rewards are given only to the leader validators, not to the voter validators.**
+- All the validators from the validator set will vote on the leader's proposal for the new block. Once consensus is reached, the block can be finalized. Hence, the actual list of votes to achieve consensus is a subset of all the validators in the validator set. This leader validator is rewarded. **Rewards are given only to the leader validators, not to the voter validators.**
 - The above flow repeats with the selection of another validator leader and repeating the steps for the next new block. Rewards are given at the end of the epoch. 
 
 ## Validator state and stake state
@@ -121,12 +121,12 @@ sources={{
 />
 
 There are two edge cases to call out:
-1. A validator can be moved from active state directly to the inactive state during an epoch change if their stake drops below the required minimum. This happens during an epoch change.
+1. If a validator's stake drops below the required minimum, that validator can be moved from active state directly to the inactive state during an epoch change. This happens only during an epoch change.
 2. Aptos governance can also directly remove validators from the active set. **Note that governance proposals will always trigger an epoch change.**
 
 ### Stake state
 
-The state of stake has more granularity than that of the validator, additional stake can be added and a portion of stake removed from an active validator.
+The state of stake has more granularity than that of the validator; additional stake can be added and a portion of stake removed from an active validator.
 
 <ThemedImage
 alt="Signed Transaction Flow"
@@ -136,12 +136,12 @@ sources={{
   }}
 />
 
-### Validator Ruleset
+### Validator ruleset
 
 The below ruleset is applicable during the changes of state:
 
-- Voting power can only change (increase or decrease) on epoch boundary.
-- A validator’s consensus key and the validator and validator fullnode network addresses can only change on epoch boundary.
+- Voting power can change (increase or decrease) only on epoch boundary.
+- A validator’s consensus key and the validator and validator fullnode network addresses can change only on epoch boundary.
 - Pending inactive stake cannot be moved into inactive (and thus withdrawable) until before lockup expires.
 - No validators in the active validator set can have their stake below the minimum required stake.
 

developer-docs-site/docs/concepts/txns-states.md

@@ -39,7 +39,7 @@ A transaction that is successfully submitted but ultimately discarded may have n
 The submitter can try to increase the gas cost by a trivial amount to help make progress and adjust for whatever may have been causing the discarding of the transaction further downstream.
 
 :::tip Read more
-See [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn) for a comprehensive description of the Aptos transaction lifecycle.
+See [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn.md) for a comprehensive description of the Aptos transaction lifecycle.
 :::
 
 ### Contents of a Transaction
@@ -77,14 +77,14 @@ See the tutorial on [Your First Transaction](../tutorials/first-transaction.md)
 :::
 
 :::note Transaction generation
-The Aptos REST API supports generating BCS encoded transactions from JSON. This is useful for rapid prototyping, but be cautious using it in Mainnet as this places a lot of trust on the fullnode generating the transaction.
+The Aptos REST API supports generating BCS-encoded transactions from JSON. This is useful for rapid prototyping, but be cautious using it in Mainnet as this places a lot of trust on the fullnode generating the transaction.
 :::
 
 ## States
 
 The Aptos blockchain's ledger state, or global state, represents the state of all accounts in the Aptos blockchain. Each validator node in the blockchain must know the latest version of the global state to execute any transaction.
 
-Anyone can submit a transaction to the Aptos blockchain to modify the ledger state. Upon execution of a transaction, a transaction output is generated. A transaction output contains zero or more operations to manipulate the ledger state, called **write sets**: a vector of resulting events, the amount of gas consumed, and the executed transaction status.
+Anyone can submit a transaction to the Aptos blockchain to modify the ledger state. Upon execution of a transaction, a transaction output is generated. A transaction output contains zero or more operations to manipulate the ledger state called **write sets** emitting a vector of resulting events, the amount of gas consumed, and the executed transaction status.
 
 ### Proofs