Merge pull request #4 from andytudhope/feedback-builder-solidity

Feedback builder solidity

docs/design-goals.mdx

@@ -42,31 +42,33 @@ We cannot preempt every kind of MEV that will exist, or the range of methods whi
 
 </GridBlock>
 
-<GridBlock symbol="II." title="Sufficient">
+<GridBlock symbol="II." title="Private">
 
-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.
+The operation of mechanisms for ordering information and distributing value must be public and verifiable. The data which passes through those mechanisms need not be. Privacy is a human right and, in the context of MEV, it actually enables us to create systems that are more resilient to economic centralization over time, and to malicious manipulation in any given moment. 
 
-- [Information is the new money](https://www.youtube.com/watch?v=vi-rVTFTb6s)
+We must provide people with the ability to keep their data hidden and only reveal it to those whom they trust or wish to interact with.
 
 </GridBlock>
 </Grid>
 
 <Grid>
-<GridBlock symbol="III." title="Simple">
+<GridBlock symbol="III." title="Sufficient">
 
-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". 
+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". 
 
-It is an important principle for most modern technologies.
+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.
 
-- [Simplicity Matters](https://youtu.be/rI8tNMsozo0)
+- [Information is the new money](https://www.youtube.com/watch?v=vi-rVTFTb6s)
 
 </GridBlock>
 
-<GridBlock symbol="IV." title="Modular">
+<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". 
+
+We value simplicity because it enhances flexibility with respect to our dependencies, such that we can readily upgrade MEVM nodes from SGX to MPC, or deploy better cryptographic solutions like FHE, or introduce some maximally robust and sufficiently decentralized combination of the above.
 
-SUAVE is many things to many people, depending on who is looking and how they choose to see. This is by design. We aim for implementations that are flexible with respect to their dependencies, such that we can readily upgrade nodes from SGX to MPC, or deploy better cryptographic solutions like FHE, or introduce some maximally robust and sufficiently decentralized combination of the above. Though not quite the same, this principle is closely related to "Simple", in that it allows us to shift any necessary complexity into contracts and applications, thereby keeping the protocol neutral and transparent.
+- [Simplicity Matters](https://youtu.be/rI8tNMsozo0)
 
 </GridBlock>
 </Grid>

docs/build/index.mdx → docs/how-to/index.mdx

@@ -9,17 +9,15 @@ keywords:
 
 SUAVE uses the **MEVM**, which is a modified EVM with new precompiles for MEV use cases. Using the MEVM, you can program MEV applications as smart contracts within an expressive, familiar, and flexible programming environment - just like the normal EVM. 
 
-The MEVM offers every primitive of the MEV supply chain as a precompile, allowing any centralized MEV infrastructure to be transformed into a smart contract running on SUAVE.
-
 SUAVE is focused on delivering the properties you need: low latency, privacy, credible computation, and composability.
 
 ## What can I do with SUAVE?
 
 1. **Deploy more expressive smart contracts.** 
-    - Smart 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. You can find a list of these precompiles in the [reference section](/reference/precompiles).
+    - 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.
 
 2. **Enjoy confidential execution**. 
-    - Using the precompiles above, smart contracts can define computation that can occur "off-chain", that is, the transaction data is not exposed to everyone using SUAVE, but is encrypted to specific actors. Once the node(s) I have encrypted my data for complete the confidential computation, the result replaces the calldata for on-chain execution. 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 algorithsm etc., while nevertheless protecting the data of the people who use those applications.
+    - 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. Once the node(s) you have encrypted your data for complete the confidential computation, the result replaces the calldata for on-chain execution. 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 algorithsm etc., while nevertheless protecting the data of the people who use those applications.
 
 > **You can build new applications that you cannot build on Ethereum in a decentralized way today.**  
 
@@ -37,6 +35,6 @@ In this section, you'll find all of our recipes.
 
 The [tutorials](/tutorials/index) 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. 
 
-1. How to setup SUAVE and participate in the network.
+1. [How to setup SUAVE](/how-to/setup-suave) and participate in the network.
 2. How to create your own custom peeker ("custom peekers mev-share" Notion page, specifically to engage with design of OFA on SUAVE)
 3. How to build blocks for other networks ("SUAVE Peekers Proof of Concept" Notion page, specifically to engage with block building)

docs/build/suave-setup.mdx → docs/how-to/setup-suave.mdx

@@ -10,6 +10,14 @@ keywords:
 
 # Setup SUAVE
 
+## Our goal
+
+There are two kinds of SUAVE nodes, both participating in the same p2p network. We're going to start them both in this guide. 
+
+1. The "MEVM node" 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 node 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 nodes: one for each domain.
+
+2. The "SUAVE chain node" 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.
+
 ## Docker
 
 ### What you need
@@ -37,9 +45,7 @@ docker-compose up -d
 
 ### What just happened
 
-You just setup SUAVE and it's now running as a daemon process (which happened because of the `-d` flag we used in the `docker-compose` command). Well done!
-
-There are two kinds of SUAVE nodes, both participating in the same p2p network. We start them both in this setup. The "SUAVE Chain node" is a full node and the "MEVM node" is a full node with the ability to run confidential computation and broadcast the results.
+Both SUAVE nodes are now running as a daemon process (because of the `-d` flag in the `docker-compose` command). Well done!
 
 1. Read more about [confidential computation](/reference/confidential-computation) and the [APIs we've built to enable it](/reference/confidential-computation#apis).
 2. Dig deeper in the [architecture of the MEVM](/reference/MEVM#architecture).
@@ -106,29 +112,29 @@ The `docker-compose` version above sets up SUAVE using simple defaults. If you'd
 ```bash
 git clone https://github.com/flashbots/suave-geth.git
 cd suave-geth
-make geth
+make suave
 ```
 2. Run the MEVM node first:
 ```bash
-./build/bin/geth --dev --dev.gaslimit 30000000 --datadir suave_dev --http --ws \
+./build/bin/suave --dev --dev.gaslimit 30000000 --datadir suave_dev --http --ws \
 --allow-insecure-unlock --unlock "0xb5feafbdd752ad52afb7e1bd2e40432a485bbb7f" \
 --keystore ./suave/devenv/suave-ex-node/keystore/
 ```
 3. Press `Enter` when prompted for a password
 4. In a new terminal, run the SUAVE Chain node:
 ```bash
-./build/bin/geth --dev --dev.gaslimit 30000000 --http --http.port 8555 --ws --ws.port 8556 --authrpc.port 8561
+./build/bin/suave --dev --dev.gaslimit 30000000 --http --http.port 8555 --ws --ws.port 8556 --authrpc.port 8561
 ```
 
 ### What to do next
 
-You can now run any `geth` command you like, with an additional `--suave` flag. Start by generating a new account (in another terminal):
+You can now run any SUAVE command you like. Start by generating a new account (in another terminal):
 
 ```bash
-./build/bin/geth --suave account new
+./build/bin/suave --suave account new
 ```
 
 Consult the help page for anything else you need to do:
 ```bash
-./build/bin/geth --suave help
+./build/bin/suave --suave help
 ```

docs/index.mdx

@@ -24,7 +24,7 @@ _Sharing the same sequencing layer_ reduces the economic centralization pressure
   to stay decentralized
   </GridBlock>
   <GridBlock symbol="II." title="Block builders">
-  to capture cross-domain MEV
+  to benefit from cross-domain MEV
   </GridBlock>
   <GridBlock symbol="III." title="Validators">
   to maximize their revenue
@@ -43,7 +43,7 @@ We must make sure block building - and the power it implies - ends up meaningful
 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](/build/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.
+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.
 

docs/reference/MEVM.mdx

@@ -10,12 +10,14 @@ keywords:
 
 # MEVM
 
-SUAVE uses the **MEVM**, which is a modified EVM with new precompiles for MEV use cases. This gives anyone the power to program MEV applications as smart contracts within an expressive, familiar, and flexible programming environment - just like the normal EVM. 
+The MEVM gives anyone the power to program MEV applications in builder solidity: an expressive, familiar, and flexible programming environment for smart contract mechanisms. 
 
-The MEVM offers every primitive of the MEV supply chain as a precompile, allowing any centralized MEV infrastructure to be transformed into a smart contract running on SUAVE.
+The MEVM seeks to offer every primitive of the MEV supply chain as a precompile, allowing any centralized MEV infrastructure to be transformed into a smart contract running on SUAVE.
 
 For a high level description of the goals of the MEVM, we encourage you to read [this post](https://writings.flashbots.net/mevm-suave-centauri-and-beyond). On this page, we'll be diving deep into the technical implementation.
 
+If you'd prefer to learn by running it yourself, please follow [this guide](/how-to/setup-suave).
+
 ## Architecture
 
 Our goal is to give you what you need to write more expressive smart contracts and conduct confidential computation, such that you can build any kind of MEV application.
@@ -75,7 +77,7 @@ func NewRuntimeSuaveExecutionBackend(evm *EVM, caller common.Address) *SuaveExec
 }
 ```
 
-Each of these new APIs - `ConfidentialStoreBackend`, `MempoolBackend`, `OffchainEthBackend` - are available in any solidity smart contract through the use of [precompiles](/reference/precompiles). The precompiles also make use of `callerStack` to specify whether there is confidential computation required, and `confidentialInputs` to specify the inputs to that computation if it is required.
+Each of these new APIs - `ConfidentialStoreBackend`, `MempoolBackend`, `OffchainEthBackend` - are available in [builder solidity](/reference/builder-solidity) through the use of [precompiles](/reference/precompiles). The precompiles also make use of `callerStack` to specify whether there is confidential computation required, and `confidentialInputs` to specify the inputs to that computation if it is required.
 
 ## Notable differences from go-ethereum
 

docs/reference/builder-solidity.mdx

@@ -8,4 +8,39 @@ keywords:
   - solidity
 ---
 
-Still to come next week.
+import Video from "@site/src/components/Video/Video.tsx";
+import AlignItems from "@site/src/components/AlignItems/AlignItems.tsx";
+
+# Builer solidity
+
+Builder solidity is solidity with some additional precompiles intended to support MEV applications. Using these precompiles, builder solidity contracts can define how MEVM nodes run computation, without that computation being done on chain. That is, MEVM nodes can accept encrypted data from users, do stuff with it privately and only reveal the results, not the inputs.
+
+## Why is this cool?
+
+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.
+
+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 MEVM 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.
+
+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.
+
+This is what makes SUAVE an **open and contestable marketplace for mechanisms**, because Flashbots doesn't have to design the perfect auction structures or fair ordering schemes; smart contract designers can do so and compete with each other. As a starting point, we aim would to replicate everything that's in the ecosystem today.
+
+<AlignItems horizontal="center" vertical="center" sideMargin={0}>
+<div>
+  <img alt="Fairier Transformers" src={require('/static/img/tx_supply_chain.png').default} />
+</div>
+</AlignItems>
+
+The result should be an open marketplace for mechanisms which compete for orderflow, and do so by virtue of the guarantees their contracts make about how they will order transaction data sent to them.
+
+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. 
+
+## Further context
+
+We recommend this early research talk from Andrew Miller 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 looking directly at our [list of available precompiles](/reference/precompiles), but the framework he uses in this talk and the background he provides should still prove very useful when writing your own builder solidity contracts.
+
+<Video src="https://www.youtube-nocookie.com/embed/DhsDFKnHPa0?start=545" title="SUAVE smart contract programming model" />
+
+_TODO: I want to incorporate certain aspects of [Andrew's talk](https://flashbots.notion.site/SUAVE-smart-contract-programming-model-TEE-based-smart-contracts-for-block-building-6525d270f391452ba45463de0d51b310) into this page, espeically to do with `view` functions and how those can work in TEE kettles. I think we can leave much of the security and "ideal functionality for cryptographers" out (as the video will remain embedded), but how builder solidity is used requires further description. This will also be helped by examples that appear once I tackle suavecli._