Attend to Fred's feedback

docs/design-goals.mdx

@@ -34,9 +34,9 @@ and the practical ones which led to the implementation of [Serenity](https://not
 <Grid>
 <GridBlock symbol="I." title="Permissionless">
 
-It should be possible for anyone to deploy a smart contract for handling orderflow or building blocks. This is inspired by the "open" principle from Strategyproof computing, which states: "Our belief is that an open marketplace will naturally lead to mechanisms with the 'right scope' and 'right complexity'." 
+It should be possible for anyone to deploy any kind of builder solidity contract. This is inspired by the "open" principle from Strategyproof computing, which states: "Our belief is that an open marketplace will naturally lead to mechanisms with the 'right scope' and 'right complexity'." 
 
-We cannot preempt every kind of MEV that will exist, or the range of methods which can be concocted to extract it. Therefore, we aim to enable anyone, anywhere to create and deploy novel contracts in response to unpredictable needs as and when they arise.
+We cannot preempt every kind of MEV that will exist, or the range of methods which can be concocted to extract and distribute it. Therefore, we aim to enable anyone, anywhere to create and deploy novel contracts in response to unpredictable needs. The public nature of these permissionless contracts should help the entire ecosystem remain proactive, as permissionless access should imply a contestable marketplace of designs.
 
 - [Searching for Universality](https://docs.google.com/file/d/1c0Ok4M3CcPjMCh7-vh6ErfhqlJsh1qau/edit?filetype=mspresentation)
 
@@ -56,17 +56,17 @@ We must provide people with the ability to keep their data hidden and only revea
 
 This is inspired by the Serenity design rationale, which states that it should be "possible to build as many classes of applications as possible on top of the protocol". 
 
-We strive for the same generality with SUAVE: it should be possible to use SUAVE to create any kind of application to do with order flow, block building, commitments, instantaneous privacy, any composition of the above, and any other MEV application we have yet to imagine.
+We strive for the same generality with SUAVE: it should be possible to use SUAVE to create any kind of application to do with order flow, block building, commitments, instantaneous privacy, and any other MEV application we have yet to imagine.
 
 - [Information is the new money](https://www.youtube.com/watch?v=vi-rVTFTb6s)
 
 </GridBlock>
 
 <GridBlock symbol="IV." title="Simple">
 
-This is taken from both sources above. Strategyproof computing argues that we ought to "simplify the decisions facing participants in distributed multi-agent systems", and Vitalik points out that simplicity matters "because it (i) minimizes development costs, (ii) reduces risk of unforeseen security issues, and (iii) allows protocol designers to more easily convince users that parameter choices are legitimate". 
+Strategyproof computing argues that we ought to "simplify the decisions facing participants in distributed multi-agent systems", and Vitalik points out that simplicity matters "because it (i) minimizes development costs, (ii) reduces risk of unforeseen security issues, and (iii) allows protocol designers to more easily convince users that parameter choices are legitimate". 
 
-We value simplicity because it enhances flexibility with respect to our dependencies, such that we can readily upgrade SUAVE nodes from SGX to MPC, or deploy better cryptographic solutions like FHE, or introduce some maximally robust and sufficiently decentralized combination of the above.
+Simplicity implies flexibility with respect to dependencies, such that we can upgrade from SGX to MPC, or deploy better cryptographic solutions like FHE, or introduce some maximally robust and sufficiently decentralized combination of the above.
 
 - [Simplicity Matters](https://youtu.be/rI8tNMsozo0)
 

docs/how-to/index.mdx

@@ -12,12 +12,12 @@ SUAVE is focused on delivering the properties you need: low latency, privacy, cr
 ## What can I do with SUAVE?
 
 1. **Deploy more expressive smart contracts.** 
-    - Contracts on SUAVE follow the same rules as on Ethereum, with the added advantage of being able to access additional precompiles we have made available to serve any MEV application. We call this builder solidity.
+    - Contracts on SUAVE follow the same rules as on Ethereum, with the added advantage of being able to access additional precompiles available to serve any MEV application. We call this [builder solidity](/technical-details/builder-solidity).
 
 2. **Enjoy confidential execution**. 
-    - Builder solidity lets you define computation that can occur "off-chain", that is, where the transaction data is not exposed to everyone using SUAVE, but is encrypted to specific actors. This creates a public and transparent marketplace of applications in which we can inspect, collaborate, and compete to produce the most efficient order flow auctions, or block building algorithms etc., while nevertheless protecting the data of the people who use those applications.
+    - Builder solidity lets you request confidential computation, where your transaction data is encrypted to specific actors. Public contracts with verifiable logic just like the EVM, combined with confidential data, means that SUAVE can be seen as an open marketplace for mechanisms we can all inspect, collaborate on, and compete with to produce the most efficient MEV applications, while nevertheless protecting everyone's privacy.
 
-> **You can build new applications that you cannot build on Ethereum in a decentralized way today.**  
+> **SUAVE enables anyone to build and deploy MEV applications, on a decentralized network, which were not possible until today.**  
 
 Initially, we will support applications that require:
 
@@ -29,8 +29,6 @@ Initially, we will support applications that require:
 
 ## What's in the sausage?
 
-In this section, you'll find all of our recipes. 
-
-The tutorials are intended to get you from 0 to 1. These "how to guides" will help you get from 1 to wherever else you want to go. They do not provide history and background explanation: they show you how to do interesting and delicious things. 
+The how to guides in this section are like all of our recipes. Like any good recipe, our guides do not provide history and background explanation: they show you how to do interesting and delicious things. 
 
 1. [How to run SUAVE](/how-to/run-suave), test your node, and participate in the network.

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
 ```
@@ -68,10 +68,10 @@ Step 3: Send backrun
 
 Both the MEVM instance and the Chain instance are now running in separate containers, which means your local SUAVE dev environment is ready to go. If you followed through with Step 4 above, you've also deployed a contract in your local environment and sent some transactions to it.
 
-1. Learn more about the contract you deployed and what those transactions are in our [worked examples](/reference/builder-solidity/worked-examples/mev-share).
-2. Read more about [confidential computation](/reference/confidential-computation/index) and the [APIs we've built to enable it](/reference/confidential-computation/apis).
-3. Dig deeper in the [architecture of the MEVM](/reference/MEVM#architecture).
-4. Browse a full list of the [precompiles](/reference/precompiles) this gives you access to in [builder solidity](/reference/builder-solidity/index).
+1. Learn more about the contract you deployed and what those transactions are in our [worked examples](/technical-details/builder-solidity/worked-examples/mev-share).
+2. Read more about [confidential computation](/technical-details/confidential-computation/index) and the [APIs we've built to enable it](/technical-details/confidential-computation/apis).
+3. Dig deeper in the [architecture of the MEVM](/technical-details/MEVM#architecture).
+4. Browse a full list of the [precompiles](/technical-details/precompiles) this gives you access to in [builder solidity](/technical-details/builder-solidity/index).
 5. If you'd like to examine the Go code responsible for deploying contracts and sending transactions, you can do so [here](https://github.com/flashbots/suave-geth/blob/main/suave/devenv/cmd/main.go).
 
 ### Common problems
@@ -104,15 +104,15 @@ The `docker-compose` version above sets up SUAVE using simple defaults. If you'd
 
 ### What to do
 
-1. Clone the repo and build the adapted geth client first with:
+1. Clone the repo and build SUAVE:
 ```bash
 git clone https://github.com/flashbots/suave-geth.git
 cd suave-geth
 make suave
 ```
 2. Run the MEVM instance first:
 ```bash
-./build/bin/suave --dev --dev.gaslimit 30000000 --datadir suave_dev --http --ws \
+./build/bin/suave --dev --dev.gaslimit 30000000 --datadir suave --http --ws \
 --allow-insecure-unlock --unlock "0xb5feafbdd752ad52afb7e1bd2e40432a485bbb7f" \
 --keystore ./suave/devenv/suave-ex-node/keystore/
 ```

docs/index.mdx

@@ -13,56 +13,70 @@ import GridBlock from "@site/src/components/GridBlock/GridBlock.tsx";
 
 # Welcome to SUAVE
 
-If MEV remains centralized, we cannot realise the promises that crypto offers.
+If MEV only benefits the few, we cannot realise the permissionless, censorship-resistant systems that crypto promises.
 
-SUAVE unifies how we coordinate without forcing any one mechanism onto everyone. SUAVE does not compete with other blockchains: it is intended to aggregate and coordinate all the things that ultimately change the state of other chains.
+SUAVE unifies how we coordinate without forcing any one mechanism onto everyone. SUAVE does not replace other blockchains: it is intended to aggregate and coordinate all the things that ultimately change the state of other chains.
 
-SUAVE is a permissionless and open marketplace for many different mechanisms. SUAVE enables anyone to innovate, design, and deploy new mechanisms, which enables us to (among other things) _decentralize block building_ for all blockchains. Such "MEV applications" can provide a sustainable [defender's advantage](https://vitalik.ca/general/2016/12/29/pos_design.html) against centralizing economic forces both within and beyond crypto.  
+SUAVE is a permissionless and open marketplace for many mechanisms. SUAVE enables anyone to innovate, design, and deploy different applications that mitigate MEV on any other blockchain. Such "MEV applications" can provide a sustainable [defender's advantage](https://vitalik.ca/general/2016/12/29/pos_design.html) against centralizing economic forces both within and beyond crypto.  
 
-Reducing the economic centralization pressure on other networks enables:
+Reducing the economic centralization pressure on other blockchains enables:
 
 <Grid>
   <GridBlock symbol="I." title="Blockchains">
-  to stay decentralized
+  to decentralize power, not just architecture
   </GridBlock>
   <GridBlock symbol="II." title="Block builders">
-  to benefit from cross-domain MEV
+  to decentralize their work and access more orderflow
   </GridBlock>
   <GridBlock symbol="III." title="Validators">
-  to maximize revenue
+  to participate on a level playing field across domains
   </GridBlock>
   <GridBlock symbol="IV." title="Humans">
   to transact fairly, with the best execution.
   </GridBlock>
 </Grid>
 
-SUAVE is _unifying infrastructure_ that allows honest MEV actors to profit more than dishonest ones, aligning our incentives around shared ownership rather than private economies of scale.
+SUAVE is _unifying infrastructure_ in which the incentives for all actors in the transaction supply chain are aligned around shared ownership, rather than private economies of scale.
 
-We must make sure block building - and the power it implies - ends up meaningfully decentralized, because crypto must end up decentralized, because humanity needs decentralization in its financial systems, now more than ever.
+We must make sure block building - and the power it implies - ends up meaningfully decentralized, because decentralization is a means towards the end where crypto helps us realise permissionless, censorship-resistant, and verifiable public systems which are genuinely good for the communities who use them.
 
 ## About this site
 
 This site encourages you to move through a specific flow in order to start building the _future of coordination_. 
 
 1. Begin with **[tutorials](/tutorials/index)**. These are _learning-oriented_. They focus on practical skills, not theoretical knowledge. Our goal with the tutorials is that you enjoy the experience and gain confidence, not that you become an expert.
-2. Grow with the **[how-to guides](/how-to/index)**. These are _task-oriented_. You can think of them like recipes. Following a recipe requires basic competence (hence why we start with tutorials). Recipes do not give you context or history: they will help you do stuff. All the recipes taken together help frame the picture of what SUAVE can enable you to do, in general.
-3. Consult the **[references](/reference/index)**. These are _information-oriented_ and provide you with up-to-date certainty about what interfaces and precompiles SUAVE provides and where to find them. These are our treasure maps, which tell you what you need to know about the territory you're working in, without having to go and constantly check yourself.
-4. Refine your **[understanding](/understand/index)**. These are _discussion-oriented_. These are designed to provide you with insight into the "deep why". Why is it meaningful to work on MEV? The discussions this section invites weave everything together.
+2. Grow with the **[how to guides](/how-to/index)**. These are _task-oriented_. You can think of them like recipes. Following a recipe requires basic competence. Recipes do not give you context or history: they will help you do stuff. All the recipes taken together help frame a general picture of how SUAVE enables you.
+3. Consult the **[technical details](/technical-details/index)**. These are _information-oriented_ and provide you with up-to-date certainty about what interfaces and precompiles SUAVE provides and where to find them. These are our treasure maps, which tell you what you need to know about the territory you're working in, without having to go and constantly check yourself.
+4. Refine your **[understanding of MEV](/understand/index)**. This section is _discussion-oriented_. It does not present "the right way", but rather encourages you to reflect on "the deep why", ideally in dialogue with friends. Why does it matter that we work on MEV?
 
 <AlignItems horizontal="center" vertical="center" sideMargin={0}>
 <div>
   <img alt="Fairier Transformers" src={require('/static/img/diatraxis.png').default} />
 </div>
 </AlignItems>
 
-## About Flashbots
+## Unified, decentralized
+
+After [formalizing the threat posed by MEV](https://arxiv.org/pdf/1904.05234.pdf), and creating [MEV-Geth](https://github.com/flashbots/mev-geth) to begin addressing it, Flashbots has collaborated with many people and organizations to build neutral open-source software like [MEV-Boost](https://github.com/flashbots/mev-boost) and [MEV-Share](https://github.com/flashbots/MEV-Share). Our work has prevented the worst effects of MEV, though many problems remain.
+
+SUAVE is our means of _keeping block building decentralized_ by creating an _open marketplace for mechanisms_ for any kind of MEV application. As an open marketplace for mechanisms, SUAVE can also act as a _shared sequencing layer_ for other blockchains, helping them remain resilient in the face of economic forces that encourage centralization and/or specialization over time.
 
-Our primary focus is to enable a permissionless, transparent, and fair ecosystem for MEV. We achieve this in three ways: _Illuminate the Dark Forest_ of MEV activity, _Democratize Extraction_, and _Distribute Benefits_.
+There are many reasons why we think the market will evolve toward many chains sharing a unified sequencing layer specifically designed to keep power decentralized across the ecosystem:
 
-We focus on:
+1. Block builders who only operate on a single domain will find themselves increasingly disadvantaged due to cross-domain MEV.
+2. There are efficiency gains for users from aggregating and clearing their preferences inside the same auction.
+3. The credible neutrality of an open marketplace in which many parties share their views, strategies, and opinions gives SUAVE an information advantage on centralized builders.
+4. Enabling computation on sensitive data (user orderflow) in a permissionless setting is hard. By solving it once, we can amortize the cost across the ecosystem and provide better solutions more cheaply than any individual participant could.
+5. Because of how fundamental transaction sequencing is in blockchains, only another decentralized system can provide the necessary security and credible neutrality.
 
+To read more about what inspires us, we recommend [this post](https://writings.flashbots.net/the-future-of-mev-is-suave).
+
+## About Flashbots
+
+Our primary focus is to enable a permissionless, transparent, and fair ecosystem for MEV. We achieve this in three ways: _Illuminate the Dark Forest_, _Democratize Extraction_, and _Distribute Benefits_.
+
+- _Research_: open, transparent, and collaborative research to tackle short and long term research questions relevant to MEV.
 - _Product_: engineering products to fulfill our mission.
 - _Coordination_: organizing processes, interfacing with external teams in the ecosystem, and maximizing our impact.
-- _Research_: open, transparent, and collaborative research to tackle short and long term research questions relevant to MEV.
 
-You can interact with Flashbots on [Discord](https://discord.gg/7hvTycdNcK), [Github](https://github.com/flashbots/), and our [Discourse forum](https://collective.flashbots.net/). We have dedicated channels on Discord for each of our efforts and welcome your contributions. Our work is open source and you can follow our progress in each Github repository.
+You can interact with Flashbots on our [Discourse forum](https://collective.flashbots.net/) or in [Discord](https://discord.gg/7hvTycdNcK). Our work is open source and you can follow our progress in each [Github repository](https://github.com/flashbots/).