cleanup: docs (#5054)

* cleanup: docs

* fix link

* Update docs/content/about-iota/iota-architecture/iota-security.mdx

Co-authored-by: Gino Osahon <[email protected]>

---------

Co-authored-by: Lucas Tortora <[email protected]>
Co-authored-by: Gino Osahon <[email protected]>

docs/content/about-iota/about-iota.mdx

@@ -35,7 +35,7 @@ While the Move compiler catches many development mistakes, smart contracts can s
 
 <MainnetRunsStardust />
 
-The [IOTA Mainnet](https://wiki.iota.org/build/networks-endpoints/#iota) processes production transaction blocks. The IOTA Mainnet's tokens have a real-world value, so we recommend that you use the IOTA Testnet or Devnet to develop your application.
+The [IOTA Mainnet](https://wiki.iota.org/build/networks-endpoints/#iota) is the L1 "production" network of IOTA. The IOTA Mainnet's tokens have a real-world value, so we recommend that you use the IOTA Testnet or Devnet to develop your application.
 
 
 #### IOTA Testnet
@@ -65,16 +65,15 @@ offers a fundamentally different approach at the L1 level.
 
 ### Networks
 
-#### IOTA EVM and Shimmer EVM
+#### IOTA EVM
 
-IOTA EVM and Shimmer EVM are two distinct Layer 2 EVMs
-running on top of the [IOTA Mainnet](./tokenomics/iota-token.mdx).
+IOTA EVM is the distinct Layer 2 EVM running on top of the [IOTA Mainnet](./tokenomics/iota-token.mdx).
 
 #### IOTA EVM Testnet
 
 <NotAvailableOnTestnet/>
 
-IOTA EVM Testnet is the Layer 2 EVM running on top of the IOTA Testnet network. This network is subject to occasional resets (no data retention), usually announced with a one-week grace period.
+IOTA EVM Testnet is the distinct Layer 2 EVM running on top of the IOTA Testnet network. This network is subject to occasional resets (no data retention), usually announced with a one-week grace period.
 
 ## IOTA Tokens
 

docs/content/about-iota/iota-architecture/iota-architecture.mdx

@@ -7,13 +7,13 @@ IOTA shares some similarities with other blockchains but is unique in many ways.
 
 ## Understand IOTA Security
 
-Learn about the mechanisms available to secure on-chain assets, and the assurances IOTA provides regarding asset security. Understand IOTA Security explores the overall IOTA security architecture to ensure the asset types you design leverage IOTA to provide a secure experience for asset holders.
+Learn about the mechanisms available to secure on-chain assets, and the assurances IOTA provides regarding asset security. "Understand IOTA Security" explores the overall IOTA security architecture, to ensure the asset types you design leverage IOTA to provide a secure experience for asset holders.
 
 Go to [Understand IOTA Security](iota-security.mdx).
 
 ## Life of a Transaction
 
-Life of a Transaction details the transitions that all transactions on IOTA go through from creation to finality. This topic also explores some features of the blockchain (like epochs and checkpoints) that play a role in the life of a transaction.
+"Life of a Transaction" details the transitions that all transactions on IOTA go through from creation to finality. This topic also explores some features of the blockchain (like epochs and checkpoints) that play a role in the life of a transaction.
 
 Go to [Life of a Transaction](transaction-lifecycle.mdx).
 
@@ -26,7 +26,7 @@ Go to [Consensus](consensus.mdx).
 
 ## Protocol Upgrades
 
-The IOTA protocol, framework, and execution engine are frequently extended to include new functionality and bug fixes. This functionality is added in the form of new code which is released to validator operators as part of our regular software releases. The IOTA protocol, however, requires that all IOTA validators agree about the results of executing each transaction.
+The IOTA protocol, framework, and execution engine are frequently extended to include new functionality and bug fixes. This functionality is added in the form of new code which is released to validator operators as part of our regular software releases. The IOTA protocol, however, requires a supermajority of validators to agree on those protocol upgrades.
 
 Go to [Protocol Upgrades](protocol-upgrades.mdx).
 

docs/content/about-iota/iota-architecture/iota-security.mdx

@@ -23,15 +23,15 @@ IOTA uses a delegated Proof-of-Stake (dPoS) mechanism to select validators (node
 
 ### Rewards for Validators and Stakers
 
-Validators earn rewards from gas fees and share these rewards with users who staked their tokens to support them. If a validator performs poorly, both they and the users who supported them get lower rewards. Users' staked tokens are safe and can't be taken away by validators or anyone else.
+Validators are incentivized through a constant inflation of 767,000 IOTA tokens per epoch. These tokens are distributed to validators and their delegators according to specific rules, such as the validator's commission rate and total stake. Transaction fees are burned and do not contribute to validator rewards. Users' staked tokens remain safe and cannot be taken away by validators or anyone else.
 
 ### Accountability and Rotation of Validators
 
-Validators must be reliable and behave correctly, or they can be replaced. If validators try to censor transactions or act maliciously, they can be rotated out by the users. Users have a say in how the IOTA network evolves by choosing which validators to support and which protocol to follow.
+Validators must be reliable and behave correctly, or they can be replaced. If validators try to censor transactions or act maliciously, they can be rotated out by the users. Users have a say in how the IOTA network evolves by choosing which validators to support and which protocol to follow via delegation to those validators.
 
 ## Addresses and Keys
 
-To operate on any owned assets on IOTA, you need to hold the corresponding private key. You should keep the key private to guarantee no one can use your assets without your authorization. Even if all the validators agreed to misbehave, they could not access your assets without the private key.
+To operate on any owned assets on IOTA, you need to hold the corresponding private key. You must keep your private key secret to ensure no one can use your assets without your authorization. Even if all validators agree to misbehave, they cannot access your assets without your private key.
 
 Your private key matches a single public address on the IOTA network. You can create any number of addresses on IOTA, each with its own private key. Keep in mind that addresses don't require prior registration; sending any asset to an address will create said address. Since once a transaction reaches finality, it is irreversible; you should always check the recipient address for your transactions.
 
@@ -47,7 +47,7 @@ Move allows for shared assets. Although these shared assets are public in princi
 
 ### Certification and Finalization
 
-When you submit a transaction in IOTA, all the validators must agree that it's valid. Once they agree, they create a _certificate_ to confirm its validity, and this _certificate_ must also be shared with all validators. Even if some validators don't follow the rules, the transaction can still be finalized by the majority of validators who do follow the IOTA protocol. This process uses cryptographic methods to ensure that validators who don't follow the rules can't trick the system into accepting false information and that misbehaving validators can't stop the system from processing transactions.
+When you submit a transaction in IOTA, the validators must agree that it's valid. Once they agree, they create a _certificate_ to confirm its validity, and this _certificate_ must also be shared with all validators. Even if some validators don't follow the rules, the transaction can still be finalized by the supermajority of validators who do follow the IOTA protocol. This process uses cryptographic methods to ensure that validators who don't follow the rules can't trick the system into accepting false information and that misbehaving validators can't stop the system from processing transactions.
 
 ### Gas and Transaction Execution
 
@@ -61,7 +61,7 @@ Users can submit transactions themselves or use third-party services to help. Th
 
 ### Reading Assets and Transaction History
 
-IOTA validators allow users to see all the assets they hold and the history of transactions that created those assets. Validators provide cryptographic proof of every transaction that led to the current state of an asset. You can request this proof and verify it to ensure all transactions were correctly processed and agreed upon by the validators. Services that mirror the state of validators perform these checks regularly to ensure everything is correct.
+IOTA full nodes allow users to see all the assets they hold and the history of transactions that created those assets. Validators provide cryptographic proof of every transaction that led to the current state of an asset. You can request this proof from full nodes and verify it to ensure all transactions were correctly processed and agreed upon by the validators. Services that mirror the state of validators perform these checks regularly to ensure everything is correct.
 
 ### Public Auditability
 

docs/content/about-iota/iota-architecture/transaction-lifecycle.mdx

@@ -18,11 +18,11 @@ import ThemedImage from '@theme/ThemedImage';
 
 2. **Submit to Validators**: The IOTA protocol sends the transaction to every validator. The validators validate the transaction. If valid, the validators sign it and return the signed transaction to the client.
 
-3. **Form a Transaction Certificate**: After collecting responses from a supermajority of validators, the client can form a transaction _certificate_. Unlike consensus-based blockchains, IOTA validators are not burdened by needing to propagate signatures or aggregate _certificate_s; this is the responsibility of the client or gateway.
+3. **Form a Transaction Certificate**: After collecting responses from a supermajority of validators, the client can form a transaction _certificate_. Unlike consensus-based blockchains, IOTA validators are not burdened by needing to propagate signatures or aggregate _certificates_; this is the responsibility of the client or gateway.
 
-4. **Send the Certificate**: The client sends the assembled _certificate_ back to all validators. The validators check its validity and acknowledge receipt. If the transaction involves only owned objects, IOTA can process and execute it immediately without waiting for consensus (**fast path consensus**). All _certificate_s are forwarded to the IOTA DAG-based consensus protocol.
+4. **Send the Certificate**: The client sends the assembled _certificate_ back to all validators. The validators check its validity and acknowledge receipt. If the transaction involves only owned objects, IOTA can process and execute it immediately without waiting for consensus (**fast path consensus**). All _certificates_ are forwarded to the IOTA DAG-based consensus protocol.
 
-5. **Consensus and Execution**: The IOTA DAG-based consensus protocol eventually produces a total order of _certificate_s. Validators check and execute _certificate_s that involve shared objects.
+5. **Consensus and Execution**: The IOTA DAG-based consensus protocol eventually produces a total order of _certificates_. Validators check and execute _certificates_ that involve shared objects.
 
 6. **Effect Certificate**: Clients can gather responses from a supermajority of validators, assemble them into an effect _certificate_, and use it as proof that the transaction is settled.
 
@@ -42,7 +42,7 @@ Your wallet app sends the signed transaction to a full node, which then broadcas
 
 ### Transaction Certification
 
-Validators receive the transaction from the full node. They check if it's valid and lock the involved objects to prevent double-spending. After validation, they send their signature back to the full node. When the full node collects enough validator signatures (a quorum), it creates a transaction _certificate_, which includes the transaction and the validator signatures.
+Validators receive the transaction from the full node. They check if it's valid and lock the involved "owned objects" to prevent double-spending. After validation, they send their signature back to the full node. When the full node collects enough validator signatures (a quorum), it creates a transaction _certificate_, which includes the transaction and the validator signatures.
 
 ### Transaction Finalization
 
@@ -65,7 +65,7 @@ After submission to a full node, the certification process begins. The full node
 * All shared input objects in the transaction exist.
 * The gas payment is sufficient.
 
-If these checks pass, the validator locks the input objects to the transaction, preventing double-spending, and proceeds to sign the transaction and returns the signature to the node. The node needs signatures from a majority of validators to certify the transaction.
+If these checks pass, the validator locks the input objects to the transaction, preventing double-spending, and proceeds to sign the transaction and returns the signature to the node. The node needs signatures from a supermajority of validators to certify the transaction.
 
 The full node collects these signatures in parallel to speed up the process. Once it has enough signatures (a quorum), the transaction is certified, forming a **transaction _certificate_**.
 

docs/content/about-iota/why-move.mdx

@@ -4,16 +4,16 @@ title: Why Move?
 
 While EVM/Solidity is the most famous smart contracts platform, it has some downsides that IOTA Move aims to address:
 
- - **Performance, scaling, and cost**: EVM builds on top of a global shared state, which is practical but doesn't scale well. This results in limitations in throughput, which is directly reflected in the fees you must pay to interact with these networks. The more congested the network, the more expensive it gets. This is worked around with additional extra execution layers (L2s on top of L1s) or rollup solutions, which also have downsides and limitations.
+ - **Performance, scaling, and cost**: EVM builds on top of a global shared state, which is practical but doesn't scale well. This results in limitations in throughput, which is directly reflected in the fees you must pay to interact with these networks. The more congested the network, the more expensive it gets. Other blockchains try to mitigate this with additional extra execution layers (L2s on top of L1s) or rollup solutions, which also have downsides and limitations.
  - **Security:** As the first well-used smart contract language, Solidity did not have much to go by in terms of learnings around secure practices (there was no existing ecosystem yet), and it had to develop over the years with that legacy and backward compatibility in mind. Many of the issues from the past have been mitigated with workarounds. Still, given the nature of things, there are some limitations and annoyances we currently can't get around, like the security issues it has with both the code and infamous design patterns like the `approve()` method in the ERC standards.
- - **Tokens:** Assets like ERC20 tokens and ERC721/1155 NFTs are not part of the EVM and are purely standards for smart contracts deployed on an EVM chain interpreted as tokens by clients. While this works and allows much flexibility, it also has its downsides. Due to the nature of tokens being contracts and the state of your balance being stored with those contracts, it's not trivial to find all tokens in your account without knowing all token contract addresses and manually adding them, unlike the Ethereum balance itself, which is a different kind of token which can be found directly but works differently over an ERC20 token. This makes discovering your assets difficult and adds additional complexity to applications to close the gap between the native asset (ETH) and ERC20 tokens with workarounds like wrapped tokens, which is not ideal.
+ - **Tokens:** Assets like ERC20 tokens and ERC721/1155 NFTs are not part of the EVM and are purely standards for smart contracts deployed on an EVM chain interpreted as tokens by clients. While this works and allows much flexibility, it also has its downsides. Due to the nature of tokens being contracts and the state of your balance being stored within those contracts, it's not trivial to find all tokens in your account without knowing all token contract addresses and manually adding them, unlike the Ethereum balance itself, which is a different kind of token which can be found directly but works differently over an ERC20 token. This makes discovering your assets difficult and adds additional complexity to applications to close the gap between the native asset (ETH) and ERC20 tokens with workarounds like wrapped tokens, which is not ideal.
  - **Developer experience:** Solidity offers a wealth of developer tools and resources, including various libraries and frameworks to choose from, as well as extensive documentation and tutorials. The language, influenced by popular languages like C++ and JavaScript, is easy to learn and get started with. However, Solidity's lack of strictness allows for mistakes that the compiler may not catch, leading to bugs and security issues that are difficult to identify and resolve. Consequently, the developer experience suffers, and the language itself is not as safe to work with as it could be.
 
 IOTA Move is here to learn from these downsides and come up with a better alternative addressing these issues:
 
 * **Performance, scaling, and cost:** Given that IOTA Move is based on the object model (similar to UTXO's) and not a globally shared state, transactions can be executed in parallel, resulting in a much higher (potential) throughput over a traditional blockchain with shared state. This results in a lot less congestion and, thus, lower fees on an actively used network. 
-* **Security:** Move was designed with security in mind. The language itself is based on Rust and is very strict regarding its typing system. You really have to try to make a mistake that the compiler won't catch before deploying. There's no such thing as re-entry, and given the object-based approach of Move, Assets residing in your account can't be touched at all by the smart contract itself without access to your account keys. 
-* **Tokens:** In IOTA Move, there is no difference between the IOTA token (`Coin<IOTA>`) and a custom token (`Coin<YOUR_NAME_HERE>`), not in terms of use or implementation. These objects reside in your own account and can thus easily be found without needing to know a Smart Contract address (this goes for any other type of owned object as well). There's no strange `approve()` functionality, and you keep control over your own owned assets.
+* **Security:** Move was designed with security in mind. The language itself is based on Rust and is very strict regarding its typing system. The Move compiler is designed to catch many common programming errors, such as type mismatches, resource misuse, and violations of ownership or borrowing rules, before deployment. This helps ensure safety and correctness without relying solely on runtime checks. There's no such thing as re-entry, and given the object-based approach of Move, Assets residing in your account can't be touched at all by the smart contract itself without access to your account keys. 
+* **Tokens:** In IOTA Move, there is no difference between the IOTA token (`Coin<IOTA>`) and a custom token (`Coin<YOUR_NAME_HERE>`), not in terms of use or implementation, except that the IOTA token can be used for gas payments. These objects reside in your own account and can thus easily be found without needing to know a Smart Contract address (this goes for any other type of owned object as well). There's no strange `approve()` functionality, and you keep control over your own owned assets.
 * **Developer Experience:** While Move is more challenging to get started with compared to Solidity due to its novelty and less mature developer tooling, the safety of the language and the ease of finding and resolving issues in your code make up for that. With Move, it's not so scary anymore to write complex logic from scratch, given most mistakes (apart from obvious implementation logic, doing things 'as intended') are caught directly by the compiler. This allows for more innovation, fewer value-destroying bugs, and a more excellent developer experience, fueling the next generation of smart contracts.