[docs] bring back system-integrators-guide

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

@@ -7,9 +7,10 @@ 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.
 
-However, blocks still exist on Aptos and offer a way to efficiently organize and execute transactions together. Blocks on Aptos can be thought of as *batches* of transactions. The exact number of transactions in a block varies depending on network activity and a configurable maximum block size limit. As the blockchain becomes busier and more optimized, the block size limit will increase, leading to a higher transaction throughput limit.
+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.
 
 ## System transactions
+
 Each Aptos block contains both user transactions and special system transactions to *mark* the beginning and end of the transaction batch. Specifically, there are two system transactions:
 1. `BlockMetadataTransaction` - is inserted at the beginning of the block. A `BlockMetadata` transaction can also mark the end of an [epoch](#epoch) and trigger reward distribution to validators.
 2. `StateCheckpointTransaction` - is appended at the end of the block and is used as a checkpoint milestone.

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

@@ -5,8 +5,6 @@ slug: "gas-txn-fee"
 
 # Gas and Transaction Fees
 
-## Concept
-
 To conduct any transaction with the Aptos blockchain on the mainnet, you are required to pay a processing fee. This fee is derived from transactions with a client application, stake owner, node operator, or voter. The processing fee you are required to pay is based on the computing and storage resources you use on the blockchain to:
 
 1. Process your transactions on the blockchain.
@@ -17,32 +15,26 @@ To conduct any transaction with the Aptos blockchain on the mainnet, you are req
 Conceptually, this fee can be thought of as quite similar to how we pay for our home electric or water utilities.
 :::
 
-### Prioritizing your transaction
-
-You can even bump up your transaction to a higher priority level on the blockchain by paying a larger processing fee. In your transaction, you can commit to paying a gas price that is higher than the market gas price. This is one way you can move your transaction higher in the priority list and have it processed more quickly. 
-
-### Unit of gas
+## Unit of gas
 
-You can make a simple and inexpensive transaction or a complicated transaction that requires the blockchain to perform much computation and distributed storage. In either case, you will be required to spend a processing fee sufficient to complete the transaction. This is where the notion of **gas** becomes clear. Here is how it works:
-
-In the Aptos blockchain a **unit of gas** represents a basic unit of resource consumption. A single unit of gas is a combined representation of:
+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.
 
-When your transaction is executed on the blockchain, instead of separately presenting you an account of each unit of the specific resource consumed, the blockchain simply presents an account of the number of units of gas being consumed by the transaction. 
-
 See [How Base Gas Works](./base-gas.md) for a detailed description of gas fee types and available optimizations.
 
-### Gas price
+## 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.
+
 :::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.
 :::
 
-## Gas and transaction fee on the Aptos blockchain
+## Specifying gas fees within a transaction
 
 When a transaction is submitted to the Aptos blockchain, the transaction must contain the following mandatory gas fields:
 
@@ -90,11 +82,9 @@ If, let's say, you transfer all the money out of your account so that you have n
 
 In a transaction, for example, transaction A, you are transferring 1000 coins from one account to another account. In a second transaction B, with the same gas field values of transaction A, you now transfer 100,000 coins from one account to another one account. Assuming that both the transactions A and B are sent roughly at the same time, then the gas costs for transactions A and B would be near-identical.
 
-## Estimating the gas units
-
-The gas used for a transaction can be estimated by simulating the transaction. When simulating the transaction, the simulation results represent the **exact** amount that is needed at the **exact** state of the blockchain at the time of simulation. These gas units used may change based on the state of the chain.  For this reason, any amount coming out of the simulation is only an estimate, and when setting the max gas amount, it should be increased above by an amount you’re comfortable with.
+## Estimating the gas units via simulation
 
-## Simulating the transaction to estimate the gas
+The gas used for a transaction can be estimated by simulating the transaction. When simulating the transaction, the simulation results represent the **exact** amount that is needed at the **exact** state of the blockchain at the time of simulation. These gas units used may change based on the state of the chain.  For this reason, any amount coming out of the simulation is only an estimate, and when setting the max gas amount, it should include an appropriate amount of headroom based upon your comfort-level and historical behaviors. Setting the max gas amount too low will result in the transaction aborting and the account being charged for whatever gas was consumed.
 
 Transactions can be simulated with the [`SimulateTransaction`](https://fullnode.devnet.aptoslabs.com/v1/spec#/operations/simulate_transaction) API. This API will run the exact transaction that you plan to run.  
 
@@ -118,4 +108,8 @@ The simulation steps for finding the correct amount of gas for a transaction are
 5. At this point you now have your `gas_unit_price` and `max_gas_amount` to submit your transaction as follows:
     1. `gas_unit_price` from the returned simulated transaction.
     2. `max_gas_amount` as the minimum of the `gas_used` * `a safety factor` or the `max_gas_amount` from the transaction.
-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.
+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.
+:::

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

@@ -12,7 +12,7 @@ The Aptos on-chain governance is a process by which the Aptos community members
 - Changes to the blockchain parameters, for example, the epoch duration, and the minimum required and maximum allowed validator stake.
 - Changes to the core blockchain code. 
 - Upgrades to the Aptos Framework modules for fixing bugs or for adding or enhancing the Aptos blockchain functionality.
-- Deploying new framework modules (at the address 0x1).
+- Deploying new framework modules (at the address `0x1` - `0xa`).
 
 ## How a proposal becomes ready to be resolved
 
@@ -26,12 +26,10 @@ sources={{
   }}
 />
 
-- The  Aptos community can suggest an Aptos Improvement Proposal (AIP) in community forums,  channels and discuss them off-chain.
-- When an off-chain AIP acquires sufficient importance, then 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. When the voting period is over, the proposal can be resolved.
-- The proposal contains an early expiration threshold that is set to 50% of the total supply of Aptos Coins. This allows for emergency bug fixes **without waiting for the full voting period**, assuming that the votes of the 50% of the total supply are cast quickly. 
-  - If the number of YES votes exceed this threshold, the proposal is ready to be resolved.
-  - If the number of NO votes exceed this threshold, the proposal is considered failed. 
+- 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**.
 
 ## Who can propose
 
@@ -42,13 +40,8 @@ sources={{
 ## 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. 
-
-  :::tip
-
-  Each stake pool can only be used to vote on each proposal exactly once.
-  :::
-
 - 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.
+:::

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

@@ -15,6 +15,6 @@ Start here to get into the core concepts of the Aptos blockchain.
 - ### [Transactions and States](./txns-states.md)
 - ### [Gas and Transaction Fees](./gas-txn-fee.md)
 - ### [Blocks](./blocks.md)
-- ### [Life of a Transaction](../guides/basics-life-of-txn.md)
+- ### [Aptos Blockchain Deep Dive](../guides/basics-life-of-txn.md)
 - ### [Staking](./staking)
 - ### [Governance](./governance)

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

@@ -5,16 +5,11 @@ id: "resources"
 
 # Resources
 
-On Aptos, smart contract states are sharded by accounts. All on-chain states have to be organized into resources and associated
-with specific accounts. This is different from other blockchains, such as Ethereum, where each smart contract maintains
-their own storage space. Accounts on Aptos can contain associated modules and resources. [Events](./events.md) are stored
-inside resources.
-See [Accounts](./accounts.md) for more details on accounts.
+On Aptos, on-chain state is organized into resources and modules. These are then stored within the individual accounts. This is different from other blockchains, such as Ethereum, where each smart contract maintains their own storage space. Additionally, [event handles](./events.md) are defined within resources. See [Accounts](./accounts.md) for more details on accounts.
 
 ## Resources vs Objects
-Resources refer to top-level objects that are stored directly with an account on the blockchain. 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 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:
 
 ```rust
 /// A holder of a specific coin types and associated event handles.
@@ -30,39 +25,44 @@ struct Coin<phantom CoinType> has store {
 }
 ```
 
-The Coin object can be taken out of CoinStore with the owning account's permission and easily transferred to another CoinStore
-resource. It can also be kept in any other custom resource, if the definition allows, for example:
+The Coin object can be taken out of CoinStore with the owning account's permission and easily transferred to another CoinStore resource. It can also be kept in any other custom resource, if the definition allows, for example:
 
 ```rust
 struct CustomCoinBox<phantom CoinType> has key {
     coin: Coin<CoinType>,
 }
 ```
 
+## Resource and Object Definition
+
+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:
+
+```
+module 0x1234::coin {
+    struct CoinStore<phantom CoinType> has key {
+        coin: Coin<CoinType>,
+    }
+
+    struct SomeCoin { }
+}
+```
+
+In this example, `0x1234` is the address, `coin` is the module, `Coin` is a struct that can be stored as a resource, and `SomeCoin` is a struct that is unlikely to ever be represented as an object. The use of the phantom type allows for there to exist many distinct types of `CoinStore` resources with different `CoinType` parameters.
+
 ## Dual ownership of objects, including resources
+
 Objects (including resources) on Aptos are owned by both:
 1. The account where the object is stored, and
 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. 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. To locate a resource, the owning account must first be identified.
-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 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.
 
 ## 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.
-
-## Parallel processing
-Sharding of state across accounts via resources allows efficient processing of transactions on the Aptos blockchain. The more
-developers neatly organize resources in end user accounts, the more efficiency the network gains collectively. The only trade-off
-of sharding is that it's more difficult when data is needed from multiple different accounts. This problem can be solved through
-[indexing](../guides/indexing.md).
+
+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.