Merge pull request #5 from andytudhope/suavecli

Keep on Iterating References + Begin SUAVE CLI
flashbots · Sep 15, 2023 · ab305d2 · ab305d2
2 parents b8b1b0a + 07a78b0
commit ab305d2
Show file tree

Hide file tree

Showing 20 changed files with 901 additions and 345 deletions.
diff --git a/docs/design-goals.mdx b/docs/design-goals.mdx
@@ -66,7 +66,7 @@ We strive for the same generality with SUAVE: it should be possible to use SUAVE
 
 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.
+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 Matters](https://youtu.be/rI8tNMsozo0)
 

diff --git a/docs/how-to/extras.mdx b/docs/how-to/extras.mdx
@@ -0,0 +1,91 @@
+# Commands
+
+### Deploy Commands:
+
+1. `deployBlockSenderContract`: Deploys the BlockSender contract to the Suave network. This contract is used to send constructed blocks for execution via the Boost Relay.
+
+2. `deployMevShareContract`: Deploys the MevShare contract to the Suave network. This contract is used for sharing Maximum Extractable Value (MEV) profits with the MevExtractor contract.
+
+### Send Commands:
+
+1. `sendBundle`: Sends a bundle of transactions to specified MEVM contract.
+
+2. `sendMevShareBundle`: Sends a MEVShare bundle to specified MEVM contract.
+
+3. `sendMevShareMatch`: Sends a MEV share match transaction to the Suave network via the Boost Relay for matching MEV share recipients with their corresponding transactions.
+
+4. `sendBuildShareBlock`: Sends a transaction to build a Goerli block using MEV-Share orderflow and sends to specified Goerli relay.
+
+### Demo Helper Commands:
+
+1. `startHintListener`: Starts a hint listener for demo purposes. This command listens for hints emmited from MEV-Share on the Suave Chain.
+
+2. `subscribeBeaconAndBoost`: Subscribes to events from the Beacon Chain and Boost for demo purposes.
+
+3. `startRelayListener`: Starts a relay listener for demo purposes. This command listens for block submisisons and deliveries from the Boost Relay.
+
+### End-to-End (e2e) Test Commands:
+
+1. `testDeployAndShare`: Performs an end-to-end test scenario that includes contract deployment and block sharing.
+
+2. `buildGoerliBlocks`: Performs an end-to-end test scenario for building and sharing blocks on the Goerli network.
+
+
+
+
+
+
+
+
+
+note to self: these code examples come from the README. See if I can work them into all that is in SUAVE cli.
+
+We can go over the above steps again, this time looking at the actual code required for each step:
+
+1. You can create an ordinary EVM transaction like this in Go:
+
+```go
+allowedPeekers := []common.Address{newBlockBidPeeker, newBundleBidPeeker, buildEthBlockPeeker} // express which contracts should have access to your data (by their addresses)
+offchainInnerTx := &types.LegacyTx{
+    Nonce:    suaveAccNonce,
+    To:       &newBundleBidAddress,
+    Value:    nil,
+    Gas:      1000000,
+    GasPrice: 50,
+    Data:     bundleBidAbi.Pack("newBid", targetBlock, allowedPeekers)
+}
+```
+
+2. You can wrap (and sign) the above transaction into the new `OffchainTx` method as below, making sure to include the SUAVE node's public key.
+
+```go
+offchainTx := types.SignTx(types.NewTx(&types.OffchainTx{
+    ExecutionNode: "0x4E2B0c0e428AE1CDE26d5BcF17Ba83f447068E5B",
+    Wrapped:       *types.NewTx(&offchainInnerTx),
+}), suaveSigner, privKey)
+```
+
+3. Request confidential computation by submitting your transaction along with your confidential data to the SUAVE node you chose via `eth_sendRawTransaction`.
+
+```go
+confidentialDataBytes := hexutil.Encode(ethBundle)
+suaveClient.Call("eth_sendRawTransaction", offchainTx, confidentialDataBytes)
+```
+
+4. Once the SUAVE node processes your computation request, the MEVM instance will submit it as `OffchainExecutedTx` to the public mempool. For your reference, the two new types look like this:
+
+```go
+type OffchainTx struct {
+    ExecutionNode common.Address
+    Wrapped  Transaction
+}
+```
+
+```go
+type OffchainExecutedTx struct {
+    ExecutionNode  common.Address
+    Wrapped        Transaction
+    OffchainResult []byte
+    /* SUAVE node's signature fields */
+}
+```
diff --git a/docs/how-to/index.mdx b/docs/how-to/index.mdx
@@ -7,8 +7,6 @@ keywords:
   - practice
 ---
 
-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. 
-
 SUAVE is focused on delivering the properties you need: low latency, privacy, credible computation, and composability.
 
 ## What can I do with SUAVE?
@@ -17,7 +15,7 @@ SUAVE is focused on delivering the properties you need: low latency, privacy, cr
     - 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**. 
-    - 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.
+    - 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.
 
 > **You can build new applications that you cannot build on Ethereum in a decentralized way today.**  
 
@@ -33,8 +31,6 @@ Initially, we will support applications that require:
 
 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. 
+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. 
 
-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)
+1. [How to setup SUAVE](/how-to/setup-suave), test your node, and participate in the network.
diff --git a/docs/how-to/setup-suave.mdx b/docs/how-to/setup-suave.mdx
@@ -12,17 +12,17 @@ keywords:
 
 ## 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. 
+A SUAVE node is really two nodes in a trenchcoat, 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.
+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.
 
-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.
+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.
 
 ## Docker
 
 ### What you need
 
-1. Install Docker. You can find general directions [here](https://docs.docker.com/get-docker/).
+1. Install and start Docker. You can find general directions [here](https://docs.docker.com/get-docker/).
     1. If you're running Ubuntu or Debian, we recommend [this specific guide](https://docs.docker.com/engine/install/ubuntu/#installation-methods).
 2. Make sure you have `docker-compose` installed too. The should just happen when you install Docker.
     1. Check with `docker-compose version` (Docker Engine) or `docker compose version` (Docker Desktop).
@@ -36,20 +36,43 @@ git clone https://github.com/flashbots/suave-geth.git
 ```
 2. Get to the right place in the repo:
 ```bash
-cd suave-geth/suave/devenv/
+cd suave-geth/
 ```
-3. Run SUAVE:
+3. Run SUAVE (depending on your docker setup, you may need to run this as `sudo`):
 ```bash
-docker-compose up -d 
+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:
+```bash
+go run suave/devenv/cmd/main.go
+```
+You should see something like the below printed to your terminal (addresses, txns, and ids will differ):
+```bash
+suave-geth$ go run suave/devenv/cmd/main.go
+Step 0: Create and fund test accounts
+- Funded test account: 0x66d5a8D6B34329c0639071275b3d78D29e11EbC6 (100000000)
+Step 1: Deploy mev-share contract
+- Mev share contract deployed: 0x8f21Fdd6B4f4CacD33151777A46c122797c8BF17
+Step 2: Send bid
+- Bid sent at txn: 0xb49debcdead2b306d6ab6282b88fdad7c8d6a33d87df34b79f56d141eae7c08a
+- Bid id: 30bbc65298f24e67aaf5c95bf5f0686c
+Step 3: Send backrun
+- Backrun sent at txn: 0xcf7880e61e94aaab48c60655c321716ecab6edab752586448b0412e93a969889
+- Backrun bid id: db98b83d02694fc2b13c042ad22c233
 ```
 
 ### What just happened
 
-Both SUAVE nodes are now running as a daemon process (because of the `-d` flag in the `docker-compose` command). Well done!
+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. 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).
-3. Browse a full list of the [precompiles this gives you access to in any smart contract](/reference/precompiles).
+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).
+5. If you'd like to examine the Go code responsible for deploying contracts and sending transactions, you can do so [here].
 
 ### Common problems
 
@@ -71,33 +94,6 @@ Both SUAVE nodes are now running as a daemon process (because of the `-d` flag i
   </div>
 </details>
 
-<details>
-  <summary>2. Using Docker Desktop</summary>
-  <div>
-    <div>
-      If you're using Docker Desktop, it's likely that you need to use <code>docker compose up -d</code> (without the <code>-</code>).
-    </div>
-  </div>
-</details>
-
-<details>
-  <summary>3. Older OS won't shut down</summary>
-  <div>
-    <div>
-      <div>
-        Depending on your OS version and the way you installed Docker, you might have issues switching your new MEVM node off again. If so:<br/>
-        <code>
-        sudo killall containerd-shim
-        </code><br/><br/>
-        Now you should be able to run:<br/>
-        <code>
-        sudo docker-compose down
-        </code>
-      </div>
-    </div>
-  </div>
-</details>
-
 ## Build it yourself
 
 The `docker-compose` version above sets up SUAVE using simple defaults. If you'd like to run the binaries yourself and customise what is happening, read on.
@@ -114,14 +110,14 @@ git clone https://github.com/flashbots/suave-geth.git
 cd suave-geth
 make suave
 ```
-2. Run the MEVM node first:
+2. Run the MEVM instance first:
 ```bash
 ./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:
+4. In a new terminal, run the Chain instance:
 ```bash
 ./build/bin/suave --dev --dev.gaslimit 30000000 --http --http.port 8555 --ws --ws.port 8556 --authrpc.port 8561
 ```