Further feedback

docs/how-to/run-suave.mdx

@@ -14,7 +14,7 @@ keywords:
 
 A SUAVE node is two nodes in a trenchcoat, both participating in the same p2p network. We're going to start both in this guide. 
 
-1. The "MEVM instance" is a full node that can run confidential computation and broadcast the results. You need to run it in order to _act on information_ you receive (i.e. run confidential computation). You need to run one MEVM instance per domain. Right now, we support Ethereum L1, but more domains will become available as we add the necessary precompiles, like `simulatePolygonBundle` or `buildOptimismBlock` etc. This will mean running many MEVM instances: one for each domain.
+1. The "MEVM instance" is a full node that can run confidential computation and broadcast the results. You need to run it in order to _act on information_ you receive. You need to run one MEVM instance per blockchain you're operating on. Right now, we support Ethereum L1, but more blockchains will become available as we add the necessary precompiles, like `simulatePolygonBundle` or `buildOptimismBlock` etc.
 
 2. The "Chain instance" is also a full node. You need to run it in order to _receive information_ about transactions on any domain that broadcasts to the SUAVE chain. You only need to run one of these, as everyone should broadcast their hints on SUAVE.
 
@@ -45,7 +45,7 @@ make devnet-up
 
 ### Optional testing
 
-4. If you'd like to test your node by deploying a contract and sending it some transactions, you can do so easily by running:
+4. If you'd like to test your node by deploying a contract and sending it some transactions, you can do so by running:
 ```bash
 go run suave/devenv/cmd/main.go
 ```

docs/technical-details/builder-solidity/index.mdx

@@ -12,13 +12,13 @@ import AlignItems from "@site/src/components/AlignItems/AlignItems.tsx";
 
 # Builder solidity
 
-Builder solidity is solidity with some additional precompiles intended to support MEV applications. Using these precompiles, builder solidity contracts can define how SUAVE nodes run computation, without that computation being done on chain. That is, SUAVE nodes can accept encrypted data from users, do stuff with it privately and only reveal the results, not the inputs.
+Builder solidity is a superset of Solidity with additional precompiles to support decentralized MEV applications. Using these precompiles, builder solidity contracts can define how SUAVE nodes run computation, without that computation being done on chain. That is, SUAVE nodes can accept encrypted data from users, do stuff with it privately and only reveal the results, not the inputs.
 
 ## Verifiable logic, private data
 
-Builders have no incentive to share the algorithms by which they currently build blocks, so it is hard for searchers to know whether their bundles will be built in the order they submit them, or manipulated. This means that searchers are more likely to send their bundles to the few builders they trust, or only those who consistently build winning blocks (in order to avoid leaking alpha to everyone). This results in block builder centralization over time.
+Block builders have no incentive to share the algorithms by which they currently build blocks, and searchers currently depend on builders they send their bundles to to ensure the bundles are included. This means that searchers are more likely to send their bundles to just the few builders they do trust, or only those who consistently build winning blocks. This trust-dependency results in block builder centralization over time.
 
-Builders can now use builder solidity to create contracts that specify exactly how they will order bundles (and transactions) sent to them. However, those bundles can be kept confidential: encrypted to the SUAVE node that the builder in question runs. This way, builders can receive bundles and order them in a verifiable and public manner, without ever revealing sensitive transaction data.
+Builders can now use builder solidity to create contracts that specify exactly how they will order bundles (and transactions) sent to them. Those bundles can be kept confidential: encrypted to the SUAVE node that the builder in question runs. This way, builders can receive bundles and order them according to verifiable logic, without ever revealing sensitive transaction data.
 
 Builder solidity is for all kinds of builders though, not just block builders. Builder solidity contracts are a _uniform programming model for implementing every component of the transaction supply chain_, such that we can ensure that any value created is distributed fairly.
 
@@ -28,18 +28,16 @@ Builder solidity is for all kinds of builders though, not just block builders. B
 </div>
 </AlignItems>
 
-By crafting a network in which the interactions between each participant in the chain above can be encoded in builder solidity contracts, SUAVE becomes an **open and contestable marketplace for mechanisms**. This is because Flashbots need not design the perfect auction structures or fair ordering schemes; smart contract designers are now empowered to, using familiar and open source tools. 
+The result should be continuous improvement of mechanisms which compete for order flow, and do so by virtue of the efficiency of their implementation _combined with_ the guarantees their contracts make about how they will distribute value.
 
-The result should be continuous improvement of mechanisms which compete for orderflow, and do so by virtue of the efficiency of their implementation _combined with_ the guarantees their contracts make about how they will distribute value.
-
-This enables us to combine the collective verifiability we expect from public blockchains with the individual privacy we need in order to protect users, defend against malicious MEV, and create provably fair systems which are resilient to economic centralization pressures across time. 
+This enables us to combine the collective verifiability we expect from blockchains with the individual privacy we need in order to protect users, defend against malicious MEV, and create provably fair systems which are resilient to economic centralization pressures across time. 
 
 ## Worked examples
 
-To understand how builder solidity actually works, we recommend that you begin with our **[MEV-Share worked example](/technical-details/builder-solidity/worked-examples/mev-share)**.
+To dive deeper into how builder solidity actually works, we recommend that you begin with our **[MEV-Share worked example](/technical-details/builder-solidity/worked-examples/mev-share)**.
 
 ## Further context
 
 We recommend [this early research talk from Andrew Miller](https://youtu.be/DhsDFKnHPa0?t=344) to get a sense of the ideas from which builder solidity has grown.
 
-Please note that the pseudo code he shows is now outdated and you are better off learning from our [MEV-Share worked example](/technical-details/builder-solidity/worked-examples/mev-share) above, or looking directly at our [list of available precompiles](/technical-details/precompiles). That said, the framework he uses in this talk and the background he provides should still prove very useful when writing your own builder solidity contracts.
+Please note that the pseudo code Andrew shows is now outdated and you are better off learning from our [MEV-Share worked example](/technical-details/builder-solidity/worked-examples/mev-share) above, or looking directly at our [list of available precompiles](/technical-details/precompiles). That said, the framework used in this talk and the background provided should still prove very useful when writing your own builder solidity contracts.

docs/technical-details/builder-solidity/worked-examples/mev-share.mdx

@@ -18,25 +18,24 @@ I want to swap on an decentralized exchange. However, I've heard that I can be e
 
 What do I need to do, and what happens next? We'll describe the steps first in natural language. If you want to [jump straight to code, please do so](#the-code).
 
-1. I take my signed ETH L1 Uniswap tx, and encrypt it using the public key of a specific SUAVE node.
-    1. I decide whether I want all my transaction information in there, or just - for instance - the address of the pool contract I am trading on, but not the direction of the trade. 
-    3. I wrap my L1 transaction in another transaction to the MEVShare.sol on SUAVE.
-2. I send the transaction in (1.ii) to the SUAVE node I encrypted it for.
-3. The SUAVE node sees this transaction, sees that it contains additional data (the encrypted L1 transaction), and passes it to the MEVM running in that node to process confidentially.
+1. I take my signed ETH L1 Uniswap tx, and encrypt it using the public key of a specific SUAVE node. 
+    1. This example assumes you know which SUAVE node to encrypt it for. On the current testnet, only Flashbots is running nodes.
+	2. My L1 transaction becomes the "request record" in another transaction to the MEVShare.sol on SUAVE.
+2. I send the transaction, with the L1 request record, to the SUAVE node I encrypted it for.
+3. The SUAVE node sees this transaction, sees that it contains a request record, and calls the MEVM running in that node to process confidentially.
 
 ### 1. The trade
 
 1. The MEVM enters into the function being called in the MEVShare.sol contract on SUAVE.
     1. This _does not_ permute state: we use view functions to fetch confidential data, and then have the MEVM compute over that data off-chain. 
     3. Once the MEVM has the data, it will use any other combination of precompiles to extract relevant parts of it and simulate the results of any computation done ofer that data.
-    4. These "hint" and "simulations" are stored in the Confidential Data Store of that particular SUAVE node, under a specific "keyspace". The Confidential Data Store, and this notion of "keyspace", enables us to have public mechanisms specified in verifiable contracts which nevertheless collect and compute over private data. For instane:
+    4. These "hint" and "simulations" are stored in the Confidential Data Store of that particular SUAVE node, under a specific "keyspace". The Confidential Data Store, and this notion of "keyspace", enables us to have public mechanisms specified in verifiable contracts which nevertheless collect and compute over private data. For instance:
 		2. When MEVShare.sol tells the MEVM to combine transactions from users looking for protection with transactions from searchers doing backruns, the MEVM can do so without storing any of this data in MEVShare.sol's onchain storage.
 		3. When EthBlockBid.sol tells the MEVM to access matched bids, it can also do, searching in its specific Confidential Data Store, in the same "mevshare" keyspace.
     5. It's subtle but important: the view function being called here will return a _callback to another function_ which is intended to permute the state. If it returned the result - rather than this callback - it would expose all the confidential data when it is sent in the next step.
 2. The callback to a function which does permute states is placed alongside the original transaction sent in (2) above.
     1. We call this triple combination - the encrypted L1 transaction, the transaction I sent which wraps it, and the result from the MEVM - a "SUAVE transaction".
-4. The SUAVE transaction is propagated to the public mempool via an internal p2p method in the MEVM.
-5. Whoever is a proposer picks it up and includes it in the next block. 
+4. The SUAVE transaction is propagated to the public mempool via an internal p2p method in the MEVM, at which point it is included in the next SUAVE block. 
 
 ### 2. The search
 
@@ -47,7 +46,7 @@ Now, say some searcher is monitoring the chain, looking for hints about domains
 3. They craft their backrun on ETH L1, and wrap that backrun transaction into another transaction to the same SUAVE node. 
 4. What happens above is repeated, except that the searcher would call a different function in MEVShare.sol. 
 	1. This function operates similarly to what was described above, except that it expects an additional parameter, which is the id of my original transaction that the searcher wants to backrun.
-	2. It uses the same precompiles, giving it acess to the searcher's backrun transaction, which it simulates and stores as another "hint".
+	2. It uses the same precompiles, giving it access to the searcher's backrun transaction, which it simulates and stores as another "hint".
 	3. Using the additional input param, it then merges my original transaction with the searcher's backrun transaction and stores those in the "mevshare keyspace".
 5. As above, the MEVM returns a _callback to another function_ which is intended to permute the state, all of which is propagated as a SUAVE transaction to the public mempool, so that we also don't reveal the searcher's successful backrun.
 

docs/technical-details/confidential-computation/index.mdx

@@ -15,7 +15,7 @@ import AlignItems from "@site/src/components/AlignItems/AlignItems.tsx"
 
 SUAVE nodes have two modes of operation: regular and confidential (sometimes called off-chain). 
 
-Regular mode is the same as the normal EVM. Confidential mode uses [the MEVM](/technical-details/MEVM), with its [additional APIs](/technical-details/confidential-computation/apis), and the [precompiles](/technical-details/precompiles) available in [builder solidity](/technical-details/builder-solidity/index), to ensure that transaction data provided by users remains private.
+Regular mode is the same as the normal EVM. Confidential mode uses [the MEVM](/technical-details/MEVM), with its [additional APIs](/technical-details/confidential-computation/apis), and the [precompiles](/technical-details/precompiles) available in [builder solidity](/technical-details/builder-solidity/index), to ensure that transaction data provided by users remains private until executed on their blockchain of choice.
 
 Builder solidity uses (and extends) all the tools and patterns you know and love. However, the concept of confidential computation being done off-chain by specific SUAVE nodes is new and worth emphasizing.