Skip to content

Commit

Permalink
Merge pull request #3 from andytudhope/how-to-setup
Browse files Browse the repository at this point in the history 
How to setup
  • Loading branch information
@andytudhope
andytudhope authored Sep 7, 2023
2 parents e96be13 + 9623b01 commit 3c5e0a4
Show file tree
Hide file tree
Showing 17 changed files with 348 additions and 173 deletions.
21 changes: 10 additions & 11 deletions docs/build/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,9 @@ SUAVE is focused on delivering the properties you need: low latency, privacy, cr
- 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).

2. **Enjoy confidential execution**.
- Using the precompiles above, smart contracts can define computation that can occur "off-chain", that is, in a manner in which the data involved 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.
- 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.

## What's in the sausage?

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.

> **We want to enable you to build new applications that you cannot build on Ethereum in a decentralized way today.**
> **You can build new applications that you cannot build on Ethereum in a decentralized way today.**
Initially, we will support applications that require:

Expand All @@ -37,7 +31,12 @@ Initially, we will support applications that require:
4. **commitments** of various kinds, e.g., shared sequencers for rollups, new kinds of DEXes and bridges
5. **too much gas to do on-chain** because of how much compute they use, e.g., block building.

You will find the following recipes in this section:
## What's in the sausage?

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 create your own custom peeker ("custom peekers mev-share" Notion page, specifically to engage with design of OFA on SUAVE)
2. 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 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)
134 changes: 134 additions & 0 deletions docs/build/suave-setup.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,134 @@
---
title: Setup SUAVE
description: Start running SUAVE and participating in the chain itself
keywords:
- build
- suave
- setup
- practice
---

# Setup SUAVE

## Docker

### What you need

1. Install 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).
3. We do not have high RAM, disk, or bandwidth requirements. This section should work on most consumer laptops.

### What to do

1. Clone suave-geth:
```bash
git clone https://github.com/flashbots/suave-geth.git
```
2. Get to the right place in the repo:
```bash
cd suave-geth/suave/devenv/
```
3. Run SUAVE:
```bash
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.

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).

### Common problems

<details>
<summary>1. Docker not running</summary>
<div>
<div>
<div>
Make sure that Docker is running before trying <code>docker-compose up -d</code>. On most Linux machines, you can do this with:<br/>
<code>
sudo systemctl start docker
</code><br/><br/>
Or just check the current status with:<br/>
<code>
sudo systemctl status docker
</code>
</div>
</div>
</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.

### What you need

1. [Install go](https://go.dev/doc/install).

### What to do

1. Clone the repo and build the adapted geth client first with:
```bash
git clone https://github.com/flashbots/suave-geth.git
cd suave-geth
make geth
```
2. Run the MEVM node first:
```bash
./build/bin/geth --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
```

### 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):

```bash
./build/bin/geth --suave account new
```

Consult the help page for anything else you need to do:
```bash
./build/bin/geth --suave help
```
4 changes: 2 additions & 2 deletions docs/design-goals.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ We cannot preempt every kind of MEV that will exist, or the range of methods whi

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, or any composition of the above. Moreover, given that money is a kind of verifiable record used when quantifying, storing, and communicating information, the sufficiency we aim for ought to enable not just programmable money, but programmable money that is provably fair in different contexts and at different times.
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.

- [Information is the new money](https://www.youtube.com/watch?v=vi-rVTFTb6s)

Expand Down Expand Up @@ -86,7 +86,7 @@ In our ordering here, decentralization is also related to "Defense in depth", th

This is inspired by Strategyproof computing, which states that, "the self-interest of participants in distributed systems should be explicitly addressed by system designers, much as we currently address issues of fault-tolerance and security."

It should be possible to quantify who benefits, and how much they benefit relative to the average payoff (or average value created in similar transactions). We are inspired by the work of Tarun Chitra in this regard.
It should be possible to quantify who benefits, and how much they benefit relative to the average.

- [Towards a Theory of MEV: Uncertainty](https://www.youtube.com/watch?v=WYH7n4M016A&t=14626s)

Expand Down
66 changes: 66 additions & 0 deletions docs/index.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
title: Overview
hide_title: true
description: The home page of the knowledge base
keywords:
- flashbots
- docs
---

import AlignItems from "@site/src/components/AlignItems/AlignItems.tsx";
import Grid from "@site/src/components/Grid/Grid.tsx";
import GridBlock from "@site/src/components/GridBlock/GridBlock.tsx";

# Welcome to SUAVE

If MEV remains centralized, we cannot realise the promises that crypto offers.

SUAVE is our way to _decentralize the block building_ role by creating an open marketplace for mechanisms that innovate on both block building algorithms and order flow auctions. Such "MEV applications" can sustainably eliminate the centralizing forces in block building by creating a shared sequencing layer for anything effected by MEV.

_Sharing the same sequencing layer_ reduces the economic centralization pressure on all of us, enabling:

<Grid>
<GridBlock symbol="I." title="Blockchains">
to stay decentralized
</GridBlock>
<GridBlock symbol="II." title="Block builders">
to capture cross-domain MEV
</GridBlock>
<GridBlock symbol="III." title="Validators">
to maximize their revenue
</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.

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.

## 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](/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.
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.

<AlignItems horizontal="center" vertical="center" sideMargin={0}>
<div>
<img alt="Fairier Transformers" src={require('/static/img/diatraxis.png').default} />
</div>
</AlignItems>

## 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_ of MEV activity, _Democratize Extraction_, and _Distribute Benefits_.

We focus on:

- _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.
61 changes: 1 addition & 60 deletions docs/reference/MEVM.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ graph TB
classDef lightgreen fill:#b3c69f,stroke:#444,stroke-width:2px, color:#333;
```

What do you get from the **SuaveExecutionBackend** that we've married to the EVM through the new runtime? In a nutshell: 3 new API endpoints:
What do you get from the **SuaveExecutionBackend** that we've married to the EVM through the new runtime? In a nutshell: [3 new API endpoints](/reference/confidential-computation#apis):

```go
func NewRuntimeSuaveExecutionBackend(evm *EVM, caller common.Address) *SuaveExecutionBackend {
Expand All @@ -77,65 +77,6 @@ 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.

## Confidential Compute APIs

### ConfidentialStoreBackend

The Confidential Store is an integral part of the SUAVE chain, designed to facilitate secure and privacy-preserving transactions and smart contract interactions. It is a key-value store where users can safely store and retrieve confidential data related to their bids. The Confidential Store restricts access (both read and write) to the allowed peekers of each bid, allowing developers to define the entire data model of their application.

The current implementation of `ConfidentialStoreBackend` is managed by the `LocalConfidentialStore` struct. It provides thread-safe access to the bids' confidential data.

```go
type ConfidentialStoreBackend interface {
Initialize(bid Bid, key string, value []byte) (Bid, error)
Store(bidId BidId, caller common.Address, key string, value []byte) (Bid, error)
Retrieve(bid BidId, caller common.Address, key string) ([]byte, error)
}
```

The `LocalConfidentialStore` provides the following methods:

1. **Initialize**: This method is used to initialize a bid with a given `bid.Id`. If no `bid.Id` is provided, a new one is created. The method is trusted, meaning it is not directly accessible through precompiles.
2. **Store**: This method stores a given value under a specified key in a bid's `dataMap`. Access is restricted only to addresses listed in the bid's `AllowedPeekers`.
3. **Retrieve**: This method retrieves data associated with a given key from a bid's `dataMap`. Similar to the `Store` method, access is restricted only to addresses listed in the bid's `AllowedPeekers`.

Please note that the actual implementation of the Confidential Store will vary depending on future requirements and the privacy mechanisms used.

### MempoolBackend

The SUAVE mempool is a temporary storage pool for transactions waiting to be added to SUAVE. This mempool, `MempoolOnConfidentialStore`, operates on the Confidential Store, hence facilitating the privacy-preserving handling of bid transactions. The `MempoolOnConfidentialStore` is designed to handle SUAVE bids, namely the submission, retrieval, and grouping of bids by decryption condition such as block number and protocol. It provides a secure and efficient mechanism for managing these transactions while preserving their confidentiality.

The current implementation of `MempoolBackend` is managed by the `MempoolOnConfidentialStore` struct, which interacts directly with the `ConfidentialStoreBackend` interface.

```go
type MempoolBackend interface {
SubmitBid(Bid) error
FetchBidById(BidId) (Bid, error)
FetchBidsByProtocolAndBlock(blockNumber uint64, namespace string) []Bid
}
```

The `MempoolOnConfidentialStore` provides the following methods:

1. **SubmitBid**: This method submits a bid to the mempool. The bid is stored in the Confidential Store with its ID as the key. Additionally, the bid is grouped by block number and protocol, which are also stored in the Confidential Store.
2. **FetchBidById**: This method retrieves a bid from the mempool using its ID.
3. **FetchBidsByProtocolAndBlock**: This method fetches all bids from a particular block that match a specified protocol.

The mempool operates on the underlying Confidential Store, thereby maintaining the confidentiality of the bids throughout the transaction process. As such, all data access is subject to the Confidential Store's security controls, ensuring privacy and integrity.

Please note that while this initial implementation provides an idea of the ideal functionality, the final version will most likely incorporate additional features or modifications.

### OffchainEthBackend

// TODO

```go
type OffchainEthBackend interface {
BuildEthBlock(ctx context.Context, args *BuildBlockArgs, txs types.Transactions) (*engine.ExecutionPayloadEnvelope, error)
BuildEthBlockFromBundles(ctx context.Context, args *BuildBlockArgs, bundles []types.SBundle) (*engine.ExecutionPayloadEnvelope, error)
}
```

## Notable differences from go-ethereum

### Changes to RPC methods
Expand Down
Loading

0 comments on commit 3c5e0a4

Please sign in to comment.