├── .gitignore
├── README.md
├── assets
├── CCR.png
├── OFA-example-flow.svg
├── OFA_And_Block_Flow.svg
├── architecture.svg
├── block-building-flow.svg
├── ccRequest-signature-flow.png
├── confidential_data_store.svg
├── future_roadmap_draft.png
├── rigil-architecture.svg
└── tx-flow.svg
└── specs
├── rigil
├── README.md
├── bridge.md
├── confidential-data-store.md
├── glossary.md
├── kettle.md
├── mevm.md
├── precompiles.md
└── suave-chain.md
├── sirrah
└── README.md
└── toliman
├── README.md
├── bridge.md
├── confidential-data-store.md
├── glossary.md
├── kettle.md
├── mevm.md
├── precompiles.md
└── suave-chain.md
/.gitignore:
--------------------------------------------------------------------------------
1 | .DS_Store
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 | # ☀️ SUAVE Protocol Specifications
3 |
4 |
5 |
6 | [](./specs/rigil/)
7 | [](https://suave.flashbots.net/)
8 | [](https://collective.flashbots.net/)
9 |
10 | This repository hosts the current SUAVE protocol specifications. For SUAPP developers please check out our [developer docs](https://suave.flashbots.net/).
11 |
12 | Discussions about design rationale and proposed changes can be brought up and discussed on the [Flashbots forum](https://collective.flashbots.net/). Solidified, agreed-upon changes to the spec can be made through pull requests.
13 |
14 |
15 |
16 | ⚠️ The SUAVE protocol is still in alpha state, and [the code](https://github.com/flashbots/suave-geth) is the most up-to-date protocol spec. The goal of these notes is to gradually evolve into an implementation-agnostic specification. ⚠️
17 |
18 |
19 |
20 |
• [MEVM](./specs/rigil/mevm.md)
• [Precompiles](./specs/rigil/precompiles.md)
• [Confidential Data Store](./specs/rigil/confidential-data-store.md)
• [Bridge](./specs/rigil/bridge.md)
• [Kettle](./specs/rigil/kettle.md) |
43 | | [**Toliman**](./specs/toliman/) | [Big Bang](/assets/future_roadmap_draft.png) | `33626250` | • [SUAVE chain](./specs/toliman/suave-chain.md)
• [MEVM](./specs/toliman/mevm.md)
• [Precompiles](./specs/toliman/precompiles.md)
• [Confidential Data Store](./specs/toliman/confidential-data-store.md)
• [Bridge](./specs/toliman/bridge.md)
• [Kettle](./specs/toliman/kettle.md) |
44 | | [**Sirrah**](./specs/sirrah/) | [Proto-Collision](/assets/future_roadmap_draft.png) | | |
45 |
46 | ## Roadmap
47 |
48 | **Centauri* is focused on exploration and developer experience, serving as a spec for the secure instantiation. The plan is a progression of three testnets in the direction of increasing functionality and scalability.*
49 |
50 | **Andromeda* is the secure instantiation using SGX and cryptography, focusing on privacy with trust minimization. The plan is a progression of three milestones in the direction of better hardening and trust minimization.*
51 |
52 | **Proto-Collisions* are plans to sync up between these two development tracks. They represents points where parts of Centauri testnets can be run in secure and trust minimized fashion. Permissioned components from Proto-Collisions, if self-contained, could be used with Ethereum mainnet.*
53 |
54 | **Collision* is where the entirety of the SUAVE protocol can be safely deployed for use with Ethereum mainnet in a trust minimized and permissionless fashion.*
55 |
56 | 
57 |
58 | ---
59 |
60 | # Contributing
61 |
62 | You are welcome to open PRs and issues. We invite you to discuss your ideas in the [Flashbots Forum](https://collective.flashbots.net/) for greater visibility and to avoid doing work that is unlikely to be widely accepted and merged into the core specs.
63 |
64 |
65 |
66 | For creating tables of contents, we use the ["Markdown All in One" VS code extension](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one). This extension comes with a lot of keyboard shortcuts, which may override the ones you are already using. You can disable keyboard shortcuts for this extension by going to "Settings -> Keyboard Shortcuts" (cmd+K cmd+S) and searching for `markdown.ext` (see [#22](https://github.com/flashbots/suave-specs/pull/22) for more details).
67 |
68 | However, we don't need the ToCs and some other content (like this paragraph) rendered in the documentation frontend. Therefore, please add the `
` to any content that should not appear in the FE.
69 |
70 |
12 |
13 | [](https://suave.flashbots.net/)
14 | [](https://collective.flashbots.net/)
15 |
16 | This repository hosts the current SUAVE Rigil testnet specifications and design docs.
17 |
18 |
19 |
20 | ⚠️ The SUAVE protocol is still in a state where [the code](https://github.com/flashbots/suave-geth) is the most up-to-date protocol spec and [open questions](#open-questions) are being researched. The goal of these notes is to gradually evolve into an implementation-agnostic specification. ⚠️
21 |
22 |
23 |
24 | ---
25 |
26 | **Table of Contents**
27 |
28 |
29 |
30 | - [Specs](#specs)
31 | - [About SUAVE](#about-suave)
32 | - [Rigil Overview](#rigil-overview)
33 | - [Users](#users)
34 | - [Rigil Design Goals](#rigil-design-goals)
35 | - [Design Decisions](#design-decisions)
36 | - [Glossary](#glossary)
37 | - [Architecture](#architecture)
38 | - [Open Questions](#open-questions)
39 | - [Example Flows](#example-flows)
40 | - [High Level - OFA + Block Builder](#high-level---ofa--block-builder)
41 | - [Confidential Compute Request Flow](#confidential-compute-request-flow)
42 | - [OFA Example](#ofa-example)
43 | - [Block Building Example](#block-building-example)
44 |
45 |
46 |
47 | ---
48 |
49 | ## Specs
50 |
51 | We recommend that you read the specs in the following order:
52 |
53 | - [Suave Chain](./suave-chain.md)
54 | - [MEVM](./mevm.md)
55 | - [Precompiles](./precompiles.md)
56 | - [Confidential Data Store](./confidential-data-store.md)
57 | - [Kettle](./kettle.md)
58 | - [Bridge](./bridge.md)
59 |
60 | ---
61 |
62 | ## About SUAVE
63 |
64 | SUAVE - Single Unifying Auction for Value Expression - is a platform for building MEV applications such as OFAs, block builders, and intent executors in a decentralized and private way. SUAVE does not replace other blockchains: it is intended to aggregate and coordinate all the things that ultimately change the state of other chains.
65 |
66 | Read more about SUAVE:
67 | - https://writings.flashbots.net/the-future-of-mev-is-suave
68 | - https://writings.flashbots.net/mevm-suave-centauri-and-beyond
69 |
70 |
71 | ---
72 |
73 | ## Rigil Overview
74 |
75 |
8 |
9 |
10 |
11 | # Bridge
12 |
13 |
14 |
15 | SUAVE uses a simple and highly trusted bridge with the Goerli Ethereum network to transfer assets for gas and MEV applications.
16 |
17 | The current bridge implementation is meant to enable rapid prototyping. It is not meant for production / mainnet usage.
18 |
19 | ## Components
20 |
21 | The bridge code consists of two components:
22 | 1. onchain `GasBridge` contract
23 | 2. offchain `relayerClient`
24 |
25 | An implementation of a `GasBridge` smart contract and the trusted `relayerClient` backend can be found [here](https://github.com/flashbots/suave-bridge/blob/master/contracts/GasBridge.sol) and [here](https://github.com/flashbots/suave-bridge/blob/master/internal/bridge.go) respectively.
26 |
27 | The `GasBridge` solidity is responsible for emitting events that the `relayerClient` uses as a signal to mint on the SUAVE chain. The `relayerClient` backend initializes and manages a bridge between two Ethereum chains (rootchain and sidechain) for monitoring and relaying events. The `relayerClient` code includes functions for tracking events, handling transactions, and managing event states.
28 |
29 | ```solidity
30 | interface GasBridge {
31 | event GasEvent(address indexed sender, uint256 indexed id, uint256 amount);
32 |
33 | function transfer() external payable
34 | }
35 | ```
36 |
37 | ```go
38 | type relayerClient interface {
39 | SendTransaction(ctx context.Context, event *GasEvent) (string, error)
40 | TransactionReceipt(ctx context.Context, hash common.Hash) (*types.Receipt, error)
41 | }
42 | ```
43 |
--------------------------------------------------------------------------------
/specs/rigil/confidential-data-store.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Confidential Data Store
3 | description: This essential component of the SUAVE protocol serves as a secure and privacy-focused storage system.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/rigil/confidential-data-store.md"
5 | ---
6 |
7 |
8 |
9 | # Confidential Data Store
10 |
11 |
12 |
13 | **Table of Contents**
14 |
15 |
16 |
17 | - [Overview](#overview)
18 | - [Core Functionality](#core-functionality)
19 | - [Architecture](#architecture)
20 | - [Engine](#engine)
21 | - [Store](#store)
22 | - [Transport](#transport)
23 | - [Data Management](#data-management)
24 | - [Initialization \& Access Control](#initialization--access-control)
25 | - [Security and Confidentiality](#security-and-confidentiality)
26 |
27 |
28 |
29 |
30 | ## Overview
31 |
32 |
33 |
34 | This document provides the technical specification for the Confidential Data Store, a privacy-centric networked storage system specifically tailored to enable programmable privacy in SUAPPs.
35 |
36 | ## Core Functionality
37 |
38 | 1. **Confidential Data Input**:
39 | SUAPPs define the shape and operations performed on user data, which is put into the confidential data store. Users send data to SUAPPs and, ultimately, the confidential data store through confidential compute requests.
40 |
41 | 2. **Confidential Data Transfer**:
42 | Once Kettles successfully carry out confidential compute requests, the results are disseminated to other Kettles using a dedicated transport protocol.
43 |
44 | 3. **Data Modeling**:
45 | The confidential data store adopts a straightforward key-value storage paradigm. This allows flexibility in accommodating various data types:
46 | - Transactions, UserOps, and EIP 712 signed messages.
47 | - Bundles, simulation results, and intermediate values.
48 | - Partial and full blocks.
49 | - Other extensible data entities.
50 |
51 | 4. **Access Control**:
52 | To enable programmable privacy, only contracts bearing the correct permissions, termed 'peekers', are permitted to get and put data.
53 |
54 |
55 | ## Architecture
56 |
57 | The Confidential Data Store consists of three main components: Engine, Storage, and Transport. The Engine is the main orchestrating component responsible for managing calls to Storage, as well as sending and receiving synchronization messages over the Transport. The MEVM is able to directly interact with the Confidential Store Engine through precompiles.
58 |
59 | 
60 |
61 | ### Engine
62 |
63 | The `ConfidentialStoreEngine` is the central component in the Confidential Data Store's architecture and is responsible for coordinating data storage operations and data synchronization across the network. Integrated with the MEVM, it facilitates storage interactions via precompiled contracts. The code snippet below outlines its composition in our current [suave-geth](https://github.com/flashbots/suave-geth/tree/main) reference implementation:
64 |
65 | ```go
66 | type ConfidentialStoreEngine struct {
67 | ctx context.Context
68 | cancel context.CancelFunc
69 |
70 | storage ConfidentialStorageBackend
71 | transportTopic StoreTransportTopic
72 |
73 | daSigner DASigner
74 | chainSigner ChainSigner
75 |
76 | storeUUID uuid.UUID
77 | localAddresses map[common.Address]struct{}
78 | }
79 | ```
80 |
81 | ### Store
82 | `ConfidentialStorageBackend` is the interface that a storage backend for the Confidential Storage Engine must implement.
83 |
84 | ```go
85 | type ConfidentialStorageBackend interface {
86 | InitRecord(record suave.DataRecord) error
87 | Store(record suave.DataRecord, caller common.Address, key string, value []byte) (suave.DataRecord, error)
88 | Retrieve(record suave.DataRecord, caller common.Address, key string) ([]byte, error)
89 | FetchRecordByID(suave.DataId) (suave.DataRecord, error)
90 | FetchRecordsByProtocolAndBlock(blockNumber uint64, namespace string) []suave.DataRecord
91 | Stop() error
92 | }
93 | ```
94 |
95 | *Implementation Note: in our [suave-geth](https://github.com/flashbots/suave-geth/tree/main) reference implementation, we provide two `ConfidentialStorageBackend`: the LocalConfidentialStore, storing data in memory in a simple dictionary; and RedisStoreBackend, storing data in Redis. Redis was chosen to allow for fast iteration, but is not meant to be a long term solution.*
96 |
97 | ### Transport
98 |
99 | `StoreTransportTopic` is the interface that must be implemented by a transport engine for the Confidential Storage Engine.
100 |
101 | ```go
102 | type StoreTransportTopic interface {
103 | node.Lifecycle
104 | Subscribe() (<-chan DAMessage, context.CancelFunc)
105 | Publish(DAMessage)
106 | }
107 | ```
108 |
109 | *Implementation Note: in our [suave-geth](https://github.com/flashbots/suave-geth/tree/main) reference implementation, we provide an implementation using a shared Redis PubSub in RedisPubSubTransport, as well as a crude synchronization protocol. Note that Redis transport only synchronizes the current state; there is no initial synchronization - a newly connected node will not have access to old data for now. This synchronization protocol will be defined in upcoming specifications.*
110 |
111 |
112 | ## Data Management
113 |
114 | Data Management is at the heart of the Confidential Data Store, ensuring data is stored, retrieved, and maintained securely and efficiently.
115 |
116 | ### Initialization & Access Control
117 |
118 | The Confidential Data Store ensures that only legitimate entities can store data, and only authorized parties can retrieve it.
119 |
120 | - *Data Registration*: When initializing, it's vital to ensure that only valid data is registered in the system. Data must satisfy specific criteria, such as proper formatting, authentication, and non-duplication. Still, these requirements do not restrict *what* type of data gets put in, merely that it should follow a high-level format.
121 |
122 | - *Access Permissions*: A robust access control mechanism restricts data access. Only contracts with appropriate permissions (peekers) can access stored data. This mechanism is currently context-based, and the specific access control mechanism is laid out in the [MEVM](./mevm.md)
123 |
124 | ## Security and Confidentiality
125 |
126 | Ensuring the confidentiality of the stored data is paramount. Current implementations are still works in progress, and data should not be considered secure. Future iterations will delve deeper into encryption methodologies, access controls, and auditing mechanisms to fortify data privacy further.
127 |
128 |
129 |
130 |
131 |
132 |
133 |
134 |
135 |
136 |
137 |
138 |
--------------------------------------------------------------------------------
/specs/rigil/glossary.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Glossary
3 | description: Important SUAVE terms.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/rigil/glossary.md"
5 | ---
6 |
7 | # Glossary
8 |
9 | | Term | Description |
10 | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11 | | **Builder solidity** | solidity with access to precompiles that help facilitate the processing of transactions and intents. |
12 | | **Confidential Compute Request (CCR)** | a user request to Suave that contains (1) SUAPP information such as to and calldata, (2) confidential inputs, and (3) a list of SUAPPs and Kettles allowed to operate on confidential inputs. [[🔗spec](./kettle.md#confidential-compute-process)]. |
13 | | **Confidential Data Store** | stores confidential data for SUAPPs (L1 transactions, EIP 712 signed messages, userOps, private keys, and more). [[🔗spec](./confidential-data-store.md)]. |
14 | | **Developer** | creates smart contracts on SUAVE Chain that define rules for SUAPPs. |
15 | | **Domains** | [a system with a globally shared state that is mutated by various players through actions](https://arxiv.org/abs/2112.01472) (e.g. “transactions”) that execute in a shared execution environment. |
16 | | **Domain-Specific Services** | provides functionality to interact with target domains (i.e. for Goerli or Arbitrum, simulate transactions, build bundles, build blocks, …). [[🔗spec](./kettle.md#domain-specific-services)]. |
17 | | **Intent** | refers to “what” the desired outcome of an action on a blockchain should be as opposed to transactions which specify “how” an action should be performed. |
18 | | **Intent Executor** | actor who is responsible for taking consolidated user intents and executing them on a domain. |
19 | | **Kettle** | accepts and processes confidential compute requests and maintains the SUAVE chain; the logical unit of the SUAVE network and main protocol actor. [[🔗spec](kettle.md)]. |
20 | | **MEVM** | modified EVM with a set of precompiles to interact with APIs for Confidential Data Store, Domain-Specific Services, and more. [[🔗spec](./mevm.md)]. |
21 | | **OFA** | an application that receives transactions and either facilitates an auction on top of it or routes it elsewhere. |
22 | | **Peekers** | contracts with the correct permissions - granted by users in CCRs - to get and put data in the Confidential Data Store. |
23 | | **Precompiles** | purpose-built functions with extended capabilities that can be called from Builder Solidity. [[🔗spec](./precompiles.md)]. |
24 | | **Rigil Testnet** | The current test network. Naming convention follows the stars in the Alpha Centauri system. |
25 | | **Relay** | actor in the [mev-boost protocol](https://github.com/flashbots/mev-boost) that is responsible for validating blocks and offering them to validators upon request. |
26 | | **RPC** | Endpoint to receive user transactions, which moves confidential input to the Confidential Data Store, and passes the compute request to MEVM. |
27 | | **SUAPP** | SUAVE application, smart contracts on SUAVE chain with rules for confidential computation and functions to submit to target domains (i.e. chains). |
28 | | **SUAVE Chain** | a fork of Ethereum designed to facilitate credible, confidential execution in MEV use cases. Main purpose is to reach (and maintain) consensus about smart contract code. [[🔗spec](./suave-chain.md)]. |
29 | | **SUAVE transaction** | the transaction object that is broadcast on the SUAVE Chain. Contains the result of a CCR in its calldata + the signature of the Kettle(s) which computed said result. |
30 | | **Solver** | actor who takes many user token trades as input and competes to provide a solution to the mathematically optimal way to route all trades. |
31 | | **User** | humans or computers interacting with SUAPPs, primarily through sending confidential compute requests (CCR) to Kettles. |
32 |
--------------------------------------------------------------------------------
/specs/rigil/kettle.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Kettle
3 | description: SUAVE Kettles contain all necessary components to accept, process, and route confidential compute requests and results.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/rigil/kettle.md"
5 | ---
6 |
7 |
8 |
9 | # Kettle
10 |
11 |
12 |
13 | **Table of Contents**
14 |
15 |
16 |
17 | - [Overview](#overview)
18 | - [Prerequisites](#prerequisites)
19 | - [Kettle Responsibilities](#kettle-responsibilities)
20 | - [Becoming a Kettle](#becoming-a-kettle)
21 | - [Kettle Identification](#kettle-identification)
22 | - [Kettle Architecture](#kettle-architecture)
23 | - [RPC](#rpc)
24 | - [SUAVE PoA Chain](#suave-poa-chain)
25 | - [MEVM](#mevm)
26 | - [Confidential Data Store](#confidential-data-store)
27 | - [Domain-Specific Services](#domain-specific-services)
28 | - [Containers](#containers)
29 | - [Confidential Compute Record](#confidential-compute-record)
30 | - [Confidential Compute Request](#confidential-compute-request)
31 | - [Suave Transaction](#suave-transaction)
32 | - [Honest Kettle](#honest-kettle)
33 | - [Confidential Computation](#confidential-computation)
34 | - [Confidential Compute Process](#confidential-compute-process)
35 | - [Suave JSON-RPC](#suave-json-rpc)
36 | - [eth\_sendRawTransaction](#eth_sendrawtransaction)
37 | - [eth\_call](#eth_call)
38 | - [eth\_executionAddress](#eth_executionaddress)
39 |
40 |
41 |
42 | ## Overview
43 |
44 |
45 |
46 | This document provides the technical specification for the SUAVE Kettle, one of the primary protocol actors in the SUAVE protocol. The Kettle contains all necessary components to accept, process, and route confidential compute requests and results. Below, the expected behavior of an "honest Kettle" for the Rigil testnet version of the SUAVE protocol is outlined.
47 |
48 | ## Prerequisites
49 |
50 | All terminology, functions, and protocol mechanics defined in [SUAVE chain](./suave-chain.md), [Confidential Data Store](./confidential-data-store.md), and [MEVM](./mevm.md) are prerequisites for this document and used throughout. Please see the [Rigil overview](../../README.md) before continuing and use it as a reference.
51 |
52 | ## Kettle Responsibilities
53 |
54 | A Kettle has several primary responsibilities within the SUAVE network:
55 |
56 | 1. **Handling Confidential Compute Requests:**
57 | - Process `ConfidentialComputeRequest` received from users or other network nodes.
58 | - Execute transactions in confidential mode, providing access to the usual confidential APIs.
59 | - Create a `SuaveTransaction` using the confidential computation request and result.
60 | - Sign and submit the transaction into the SUAVE mempool.
61 |
62 | 2. **Maintaining the Confidential Data Store:**
63 | - Store and retrieve confidential data used in all SUAPPs.
64 | - Restrict access to stored data based on the allowed peekers and stores of each bid.
65 | - Ensure synchronization of confidential data across the network.
66 |
67 | 3. **Propagating Confidential Compute Requests and Results:**
68 | - Forward bundles and blocks emitted from confidential computation to block builders and relays.
69 | - Broadcast the results of confidential computations to the appropriate parties within the SUAVE network.
70 | - Ensure the propagation of results adheres to the confidentiality and privacy requirements of the SUAVE protocol.
71 |
72 | ## Becoming a Kettle
73 |
74 | Currently, Kettles are not permissioned, but participation in the confidential data store synchronization protocol is. To join the network, you must run the entire Kettle software stack and connect to the existing network via bootnode or known peer. Eventually, Kettles will be associated with an onchain registry.
75 |
76 | ### Kettle Identification
77 |
78 | A unique identifier in the form of an Ethereum-compatible public key must be generated for each Kettle to ensure proper tracking and verification of Confidential Computation, as well as responsibility assignment within the network.
79 |
80 | ## Kettle Architecture
81 |
82 | SUAVE Kettles house all components necessary to perform confidential computation and result routing. Below is a high-level architectural diagram followed by descriptions of the main components.
83 |
84 | 
85 |
86 | ### RPC
87 |
88 | This component is similar to RPCs in any Ethereum or blockchain client and is responsible for mapping user's requests to their appropriate functionality.
89 |
90 | ### SUAVE PoA Chain
91 |
92 | The SUAVE chain maintains consensus about smart contract code for SUAPPs. Additionally, it can also be used to store and broadcast data for better censorship guarantees.
93 |
94 | Kettles must keep a lively copy of the SUAVE chain state to process Confidential Compute Requests, but these liveliness requirements are currently not defined in the Rigil Kettle.
95 |
96 | For more details see the [🔗 SUAVE chain](./suave-chain.md) spec.
97 |
98 | ### MEVM
99 |
100 | The MEVM is a new interpreter and a set of precompiles to interact with APIs for the Confidential Data Store and domain-specific services.
101 |
102 | For more details see the [🔗 MEVM](./mevm.md) spec.
103 |
104 | ### Confidential Data Store
105 |
106 | The Confidential Store is a secure and privacy-focused storage system, exposing a key-value store for safeguarding confidential compute and orderflow-related data. Only those with appropriate permissions (peekers) can access the stored data, thus ensuring privacy and control.
107 |
108 | For more details, see the [🔗 Confidential Data Store](./confidential-data-store.md) spec.
109 |
110 | ### Domain-Specific Services
111 |
112 | Domain-Specific Services allow Kettles to scale horizontally by hosting nodes for other domains in separate processes that can be queried at confidential compute time. Kettles currently are not responsible for publicly committing to their domain-specific services, so support for a specific domain is done on Kettle-by-Kettle basis. If a Kettle attempts to process your confidential compute request for a domain it does not support, it will simply return a failure on the computation and will not propagate the failure to the rest of the network so other Kettles can still attempt to process.
113 |
114 | For more details on supporting the needed APIs to enable a domain, see below [🔗 SUAVE Execution API](#suave-json-rpc) spec.
115 |
116 | ## Containers
117 |
118 | The core data types used inside the Kettle.
119 |
120 | ### Confidential Compute Record
121 |
122 | This type serves as a record of computation. It's part of both the [Confidential Compute Request](#confidential-compute-request) and [Suave Transaction](#suave-transaction).
123 |
124 | ```go
125 | type ConfidentialComputeRecord struct {
126 | Nonce uint64
127 | GasPrice *big.Int
128 | Gas uint64
129 | To *common.Address
130 | Value *big.Int
131 | Data []byte
132 |
133 | KettleAddress common.Address
134 | ConfidentialInputsHash common.Hash
135 |
136 | ChainID *big.Int
137 | V, R, S *big.Int
138 | }
139 | ```
140 |
141 |
142 | ### Confidential Compute Request
143 |
144 | This type enables users to request the MEVM to compute over their data via the `eth_sendRawTransaction` method. After processing, the request's `ConfidentialComputeRecord` is embedded into `SuaveTransaction.ConfidentialComputeRequest` and serves as an onchain record of computation.
145 |
146 | ```go
147 | type ConfidentialComputeRequest struct {
148 | ConfidentialComputeRecord
149 | ConfidentialInputs []byte
150 | }
151 | ```
152 |
153 | A Kettle's signature is used as the integrity guarantee for the computation's results. Eventually, this can include arbitrary proofs such as zero-knowledge proofs.
154 |
155 | ### Suave Transaction
156 |
157 | The final home of compute results and intentionally leaked data from confidential compute requests is a SUAVE transaction; see [🔗 SUAVE chain](./suave-chain.md) specs for more details
158 |
159 | ```go
160 | type SuaveTransaction struct {
161 | ConfidentialComputeRequest ConfidentialComputeRecord
162 | ConfidentialComputeResult []byte
163 |
164 | // Kettle's signature
165 | ChainID *big.Int
166 | V *big.Int
167 | R *big.Int
168 | S *big.Int
169 | }
170 | ```
171 |
172 |
173 | ## Honest Kettle
174 |
175 | At present, the protocol relies on the honesty of Kettles, akin to the reliance on honest block builders and relays. An honest Kettle performs the duties above of:
176 |
177 | - **Handling Confidential Compute Requests**
178 | - **Maintaining Confidential Data Privacy**
179 | - **Maintaining the Confidential Data Store**
180 | - **Propagating Confidential Compute Results**
181 |
182 | On the Rigil testnet, Kettles do not live inside Trusted Execution Environments. Because of this, a malicious Kettle could alter its source code to censor Confidential Compute Requests and their results.
183 |
184 | ## Confidential Computation
185 |
186 | To successfully process a request for confidential computation, Kettles must engage the Confidential Compute Process.
187 |
188 | ### Confidential Compute Process
189 |
190 | Confidential compute is defined by the use of an [offchain function call](https://docs.soliditylang.org/en/latest/contracts.html#view-functions), signified in solidity via the `view` modifier.
191 |
192 | These view functions are used with plaintext access to decrypted data to perform confidential computation on the decrypted data. Results and a signature of integrity are propagated along with the initial request. The confidential data is propagated separately via the confidential data store, but other Kettles do not need the underlying data as they will trust any valid signature attesting to the computation's integrity.
193 |
194 | 
195 |
196 | This sequence diagram represents the interactions between various components when processing a Confidential Compute Request (CCR). Here's a description of the flow depicted in the diagram:
197 |
198 | - *Starting Point*: The process initiates with a "Confidential Compute Request" directed towards the JsonRPC.
199 |
200 | - *MEVM Execution*: Upon receiving the request, the Json RPC triggers the MEVM (Modified Ethereum Virtual Machine) to run. MEVM execution can use multiple APIs depending on the context, with two possible paths:
201 |
202 | - Request to an External Domain: The MEVM can make API requests to external domains via Domain-Specific Services.
203 | - Request to the Confidential Datastore: The MEVM can make API requests directly to the "Confidential Datastore" to fetch or store data.
204 |
205 | - *Suave Chain Interaction*: Eventually, after processing the request, depending on the SUAPP, the MEVM takes the results and sends a SUAVE transaction.
206 |
207 | - *Transaction Hash Output*: Following the Suave transaction, a transaction hash is produced and returned to the request's originator, precisely like in the Ethereum process.
208 |
209 | ## Suave JSON-RPC
210 |
211 | SUAVE JSON-RPC can be seen as a super set of Ethereum JSON-RPC. This means the [Ethereum JSON-RPC standard](https://geth.ethereum.org/docs/interacting-with-geth/rpc) remains the same when interacting with the SUAVE chain. Some methods in the `eth_` namespace are overloaded to support the confidential compute requests.
212 |
213 | ### eth_sendRawTransaction
214 |
215 | Creates new message call transaction or a contract creation for a signed `ConfidentialComputeRequest`.
216 |
217 | ### eth_call
218 |
219 | Executes a new message call immediately without creating a transaction on the blockchain. It follows the same format as the default `eth_call` with two extra parameters:
220 |
221 | **Parameters**
222 |
223 | - `IsConfidential`: Set to true to execute as a confidential request and access the `MEVM` methods.
224 | - `ExecutionAddress`: `address` - (optional) The execution address that performs the execution.
225 |
226 | ### eth_executionAddress
227 |
228 | Returns the list of available addresses in the Kettle to execute a confidential compute request. Kettle owners can register multiple addresses to sign transactions with from their Kettle. Users can pick which address the Kettle must use to sign their transactions.
229 |
--------------------------------------------------------------------------------
/specs/rigil/mevm.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: MEVM
3 | description: The MEVM modifies the EVM by adding a new runtime, interpreter, and execution backend to enable anyone to create MEV applications.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/rigil/mevm.md"
5 | ---
6 |
7 |
8 |
9 | # MEVM
10 |
11 |
12 |
13 |
14 |
15 | - [Overview](#overview)
16 | - [Modified Interpreter](#modified-interpreter)
17 | - [Confidential Data Store APIs](#confidential-data-store-apis)
18 | - [`suavex` namespace](#suavex-namespace)
19 | - [Precompile Call Authorization](#precompile-call-authorization)
20 | - [Security and Confidentiality](#security-and-confidentiality)
21 |
22 |
23 |
24 | ---
25 |
26 | ## Overview
27 |
28 |
29 |
30 | This document provides the technical specification for the MEVM, a modified version of the Ethereum Virtual Machine (EVM). The MEVM is a set of precompiles to interact with APIs; two of these API services are the Confidential Data Store and the SUAVE Execution (SUAVEX) namespace. There may be other API endpoints in the future.
31 |
32 | ## Modified Interpreter
33 |
34 | Under the hood, the MEVM is a modified EVM Interpreter which is able to use a new runtime called the `SuaveExecutionBackend`.
35 |
36 | ```mermaid
37 | graph TB
38 | A[EVM]-->|1|B((StateDB))
39 | A-->|2|C((Context))
40 | A-->|3|D((chainConfig))
41 | A-->|4|E((Config))
42 | A-->|5|F((interpreter))
43 | D-->|6|R[ChainRules]
44 | E-->|7|S[Tracer]
45 | A-->|8|T[NewRuntime]
46 | T-->|9|Z((Runtime))
47 | Z-->|10|F
48 | A-->|11|U[NewRuntimeSuaveExecutionBackend]
49 | U-->|12|V((SuaveExecutionBackend))
50 | V-->|13|F
51 | class A,B,C,D,E,F yellow
52 | class G,H,I,J,K,L,M,N,O red
53 | class P,Q green
54 | class R blue
55 | class S orange
56 | class T,U purple
57 | class Z,V lightgreen
58 | classDef yellow fill:#f5cf58,stroke:#444,stroke-width:2px, color:#333;
59 | classDef red fill:#d98686,stroke:#444,stroke-width:2px, color:#333;
60 | classDef green fill:#82a682,stroke:#444,stroke-width:2px, color:#333;
61 | classDef blue fill:#9abedc,stroke:#444,stroke-width:2px, color:#333;
62 | classDef orange fill:#f3b983,stroke:#444,stroke-width:2px, color:#333;
63 | classDef purple fill:#ab92b5,stroke:#444,stroke-width:2px, color:#333;
64 | classDef lightgreen fill:#b3c69f,stroke:#444,stroke-width:2px, color:#333;
65 | ```
66 |
67 | The `SuaveExecutionBackend` is responsible for exposing the APIs that precompiles can hook into.
68 |
69 | ```go
70 | type SuaveExecutionBackend struct {
71 | ConfidentialStore ConfidentialStore
72 | ConfidentialEthBackend suave.ConfidentialEthBackend
73 | }
74 | ```
75 |
76 | #### Confidential Data Store APIs
77 |
78 | For more information on the capabilities exposed by the Confidential Data Store, see its related [🔗 spec](./confidential-data-store.md). The interface exposed to precompiles:
79 |
80 | ```go
81 | type ConfidentialStorageBackend interface {
82 | InitRecord(record suave.DataRecord) error
83 | Store(record suave.DataRecord, caller common.Address, key string, value []byte) (suave.DataRecord, error)
84 | Retrieve(record suave.DataRecord, caller common.Address, key string) ([]byte, error)
85 | FetchRecordByID(suave.DataId) (suave.DataRecord, error)
86 | FetchRecordsByProtocolAndBlock(blockNumber uint64, namespace string) []suave.DataRecord
87 | Stop() error
88 | }
89 | ```
90 |
91 | #### `suavex` namespace
92 |
93 | The `suavex` namespace is used internally by the MEVM to enable functionality like block building and external API calls via MEVM precompiles. We take this approach to make upstream updates and maintenance easier. Current endpoints include:
94 |
95 | `suavex_buildEthBlockFromBundles` - takes an array of bundles and transactions, calculates state root and related fields, and returns a valid Ethereum L1 block.
96 |
97 | ```go
98 | BuildEthBlockFromBundles(ctx context.Context, buildArgs *types.BuildBlockArgs, bundles []types.SBundle) (*engine.ExecutionPayloadEnvelope, error)
99 | ```
100 |
101 | `suavex_buildEthBlock` - takes an array of transactions, calculates state root and related fields, and returns a valid Ethereum L1 block.
102 |
103 | ```go
104 | BuildEthBlock(ctx context.Context, buildArgs *types.BuildBlockArgs, txs types.Transactions) (*engine.ExecutionPayloadEnvelope, error)
105 | ```
106 |
107 | Domain specific services which seek to be used by SUAVE must implement the methods in this namespace. More details will be expanded in future iterations.
108 |
109 |
110 | ## Precompile Call Authorization
111 | `checkIsPrecompileCallAllowed` implements the access control functionality. It validates whether a precompile and associated callers are authorized to access specific data. Key security functionality is as follows:
112 |
113 | 1. **Universal Access**: If a `ConfidentialComputeRequest` allows "any peeker", the function searches the `CallerStack` for a caller different from the precompile, granting access upon finding one.
114 |
115 | 2. **Restricted Access and Validation**:
116 | - The function checks if the precompile is explicitly authorized to access the data record.
117 | - It then validates each caller in the `CallerStack` against the `AllowedPeekers` list. If an authorized caller is found, access is granted.
118 |
119 | 3. **Error Handling**:
120 | - Access is denied, with an error returned, if no authorized caller is found or if the precompile lacks authorization and is not a special case (like confStore addresses).
121 |
122 |
123 | ## Security and Confidentiality
124 |
125 | `checkIsPrecompileCallAllowed` ensures that either the precompile or one of its callers must be authorized for access, enhancing security by strict validation of permissions. This approach is necessary for maintaining data integrity and preventing unauthorized access, but ultimately not entirely sufficient for total confidentiality. Future iterations will delve deeper into encryption methodologies, access controls, and auditing mechanisms to fortify data privacy further, as well as Trusted Execution Environment to ensure access control is maintained.
126 |
--------------------------------------------------------------------------------
/specs/rigil/precompiles.md:
--------------------------------------------------------------------------------
1 | ---
2 | ---
3 |
4 | title: Precompiles
5 | description: Precompile are MEVM contracts that are implemented in native code instead of bytecode.
6 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/rigil/precompiles.md"
7 |
8 | ---
9 |
10 |
11 |
12 | # Precompiles
13 |
14 | - [Overview](#overview)
15 | - [Available Precompiles](#available-precompiles)
16 | - [`IsConfidential`](#isconfidential)
17 | - [`buildEthBlock`](#buildEthBlock)
18 | - [`buildEthBlockTo`](#buildEthBlockTo)
19 | - [`confidentialInputs`](#confidentialInputs)
20 | - [`confidentialRetrieve`](#confidentialRetrieve)
21 | - [`confidentialStore`](#confidentialStore)
22 | - [`contextGet`](#contextGet)
23 | - [`doHTTPRequest`](#doHTTPRequest)
24 | - [`ethcall`](#ethcall)
25 | - [`extractHint`](#extractHint)
26 | - [`fetchDataRecords`](#fetchDataRecords)
27 | - [`fillMevShareBundle`](#fillMevShareBundle)
28 | - [`newBuilder`](#newBuilder)
29 | - [`newDataRecord`](#newDataRecord)
30 | - [`privateKeyGen`](#privateKeyGen)
31 | - [`randomBytes`](#randomBytes)
32 | - [`signEthTransaction`](#signEthTransaction)
33 | - [`signMessage`](#signMessage)
34 | - [`simulateBundle`](#simulateBundle)
35 | - [`simulateTransaction`](#simulateTransaction)
36 | - [`submitBundleJsonRPC`](#submitBundleJsonRPC)
37 | - [`submitEthBlockToRelay`](#submitEthBlockToRelay)
38 | - [Precompiles Governance](#precompiles-governance)
39 |
40 | ---
41 |
42 | ## Overview
43 |
44 |
45 |
46 | Precompile are MEVM contracts that are implemented in native code instead of bytecode. Precompiles additionally can communicate with internal APIs. Currently the MEVM supports all existing Ethereum Precompiles up to Dencun, and introduces four new classes of precompiles:
47 |
48 | 1. offchain computation that is too expensive in solidity
49 | 2. calls to API methods to interact with the Confidential Data Store
50 | 3. calls to `suavex` API Methods to interact with Domain-Specific Services
51 | 4. calls to retrieve context for the confidential compute requests
52 |
53 | ## Available Precompiles
54 |
55 | A list of available precompiles in Rigil are as follows:
56 |
57 | ### `IsConfidential`
58 |
59 | Address: `0x0000000000000000000000000000000042010000`
60 |
61 | Determines if the current execution mode is regular (onchain) or confidential. Outputs a boolean value.
62 |
63 | ```solidity
64 | function isConfidential() internal view returns (bool b)
65 | ```
66 |
67 | ### `buildEthBlock`
68 |
69 | Address: `0x0000000000000000000000000000000042100001`
70 |
71 | Constructs an Ethereum block based on the provided data records. No blobs are returned.
72 |
73 | ```solidity
74 | function buildEthBlock(BuildBlockArgs memory blockArgs, DataId dataId, string memory relayUrl) internal view returns (bytes memory, bytes memory)
75 | ```
76 |
77 | Inputs:
78 |
79 | - `blockArgs` (BuildBlockArgs): Arguments to build the block
80 | - `dataId` (DataId): ID of the data record with mev-share bundle data
81 | - `relayUrl` (string): If specified the built block will be submitted to the relay
82 |
83 | Outputs:
84 |
85 | - `blockBid` (bytes): Block Bid encoded in JSON
86 | - `executionPayload` (bytes): Execution payload encoded in JSON
87 |
88 | ### `buildEthBlockTo`
89 |
90 | Address: `0x0000000000000000000000000000000042100006`
91 |
92 | Constructs an Ethereum block based on the provided data records. No blobs are returned.
93 |
94 | ```solidity
95 | function buildEthBlockTo(string memory executionNodeURL, BuildBlockArgs memory blockArgs, DataId dataId, string memory relayUrl) internal view returns (bytes memory, bytes memory)
96 | ```
97 |
98 | Inputs:
99 |
100 | - `executionNodeURL` (string): URL (or service name) of the execution node
101 | - `blockArgs` (BuildBlockArgs): Arguments to build the block
102 | - `dataId` (DataId): ID of the data record with mev-share bundle data
103 | - `relayUrl` (string): If specified the built block will be submitted to the relay
104 |
105 | Outputs:
106 |
107 | - `blockBid` (bytes): Block Bid encoded in JSON
108 | - `executionPayload` (bytes): Execution payload encoded in JSON
109 |
110 | ### `confidentialInputs`
111 |
112 | Address: `0x0000000000000000000000000000000042010001`
113 |
114 | Provides the confidential inputs associated with a confidential computation request. Outputs are in bytes format.
115 |
116 | ```solidity
117 | function confidentialInputs() internal view returns (bytes memory)
118 | ```
119 |
120 | Outputs:
121 |
122 | - `confindentialData` (bytes): Confidential inputs
123 |
124 | ### `confidentialRetrieve`
125 |
126 | Address: `0x0000000000000000000000000000000042020001`
127 |
128 | Retrieves data from the confidential store. Also mandates the caller's presence in the `AllowedPeekers` list.
129 |
130 | ```solidity
131 | function confidentialRetrieve(DataId dataId, string memory key) internal view returns (bytes memory)
132 | ```
133 |
134 | Inputs:
135 |
136 | - `dataId` (DataId): ID of the data record to retrieve
137 | - `key` (string): Key slot of the data to retrieve
138 |
139 | Outputs:
140 |
141 | - `value` (bytes): Value of the data
142 |
143 | ### `confidentialStore`
144 |
145 | Address: `0x0000000000000000000000000000000042020000`
146 |
147 | Stores data in the confidential store. Requires the caller to be part of the `AllowedPeekers` for the associated data record.
148 |
149 | ```solidity
150 | function confidentialStore(DataId dataId, string memory key, bytes memory value) internal view returns ()
151 | ```
152 |
153 | Inputs:
154 |
155 | - `dataId` (DataId): ID of the data record to store
156 | - `key` (string): Key slot of the data to store
157 | - `value` (bytes): Value of the data to store
158 |
159 | ### `contextGet`
160 |
161 | Address: `0x0000000000000000000000000000000053300003`
162 |
163 | Retrieves a value from the context
164 |
165 | ```solidity
166 | function contextGet(string memory key) internal view returns (bytes memory)
167 | ```
168 |
169 | Inputs:
170 |
171 | - `key` (string): Key of the value to retrieve
172 |
173 | Outputs:
174 |
175 | - `value` (bytes): Value of the key
176 |
177 | ### `doHTTPRequest`
178 |
179 | Address: `0x0000000000000000000000000000000043200002`
180 |
181 | Performs an HTTP request and returns the response. `request` is the request to perform.
182 |
183 | ```solidity
184 | function doHTTPRequest(HttpRequest memory request) internal view returns (bytes memory)
185 | ```
186 |
187 | Inputs:
188 |
189 | - `request` (HttpRequest): Request to perform
190 |
191 | Outputs:
192 |
193 | - `httpResponse` (bytes): Body of the response
194 |
195 | ### `ethcall`
196 |
197 | Address: `0x0000000000000000000000000000000042100003`
198 |
199 | Uses the `eth_call` JSON RPC method to let you simulate a function call and return the response.
200 |
201 | ```solidity
202 | function ethcall(address contractAddr, bytes memory input1) internal view returns (bytes memory)
203 | ```
204 |
205 | Inputs:
206 |
207 | - `contractAddr` (address): Address of the contract to call
208 | - `input1` (bytes): Data to send to the contract
209 |
210 | Outputs:
211 |
212 | - `callOutput` (bytes): Output of the contract call
213 |
214 | ### `extractHint`
215 |
216 | Address: `0x0000000000000000000000000000000042100037`
217 |
218 | Interprets the bundle data and extracts hints, such as the `To` address and calldata.
219 |
220 | ```solidity
221 | function extractHint(bytes memory bundleData) internal view returns (bytes memory)
222 | ```
223 |
224 | Inputs:
225 |
226 | - `bundleData` (bytes): Bundle object encoded in JSON
227 |
228 | Outputs:
229 |
230 | - `hints` (bytes): List of hints encoded in JSON
231 |
232 | ### `fetchDataRecords`
233 |
234 | Address: `0x0000000000000000000000000000000042030001`
235 |
236 | Retrieves all data records correlating with a specified decryption condition and namespace
237 |
238 | ```solidity
239 | function fetchDataRecords(uint64 cond, string memory namespace) internal view returns (DataRecord[] memory)
240 | ```
241 |
242 | Inputs:
243 |
244 | - `cond` (uint64): Filter for the decryption condition
245 | - `namespace` (string): Filter for the namespace of the data records
246 |
247 | Outputs:
248 |
249 | - `dataRecords` (DataRecord[]): List of data records that match the filter
250 |
251 | ### `fillMevShareBundle`
252 |
253 | Address: `0x0000000000000000000000000000000043200001`
254 |
255 | Joins the user's transaction and with the backrun, and returns encoded mev-share bundle. The bundle is ready to be sent via `SubmitBundleJsonRPC`.
256 |
257 | ```solidity
258 | function fillMevShareBundle(DataId dataId) internal view returns (bytes memory)
259 | ```
260 |
261 | Inputs:
262 |
263 | - `dataId` (DataId): ID of the data record with mev-share bundle data
264 |
265 | Outputs:
266 |
267 | - `encodedBundle` (bytes): Mev-Share bundle encoded in JSON
268 |
269 | ### `newBuilder`
270 |
271 | Address: `0x0000000000000000000000000000000053200001`
272 |
273 | Initializes a new remote builder session
274 |
275 | ```solidity
276 | function newBuilder() internal view returns (string memory)
277 | ```
278 |
279 | Outputs:
280 |
281 | - `sessionid` (string): ID of the remote builder session
282 |
283 | ### `newDataRecord`
284 |
285 | Address: `0x0000000000000000000000000000000042030000`
286 |
287 | Initializes data records within the ConfidentialStore. Prior to storing data, all data records should undergo initialization via this precompile.
288 |
289 | ```solidity
290 | function newDataRecord(uint64 decryptionCondition, address[] memory allowedPeekers, address[] memory allowedStores, string memory dataType) internal view returns (DataRecord memory)
291 | ```
292 |
293 | Inputs:
294 |
295 | - `decryptionCondition` (uint64): Up to which block this data record is valid. Used during `fillMevShareBundle` precompie.
296 | - `allowedPeekers` (address[]): Addresses which can get data
297 | - `allowedStores` (address[]): Addresses can set data
298 | - `dataType` (string): Namespace of the data
299 |
300 | Outputs:
301 |
302 | - `dataRecord` (DataRecord): Data record that was created
303 |
304 | ### `privateKeyGen`
305 |
306 | Address: `0x0000000000000000000000000000000053200003`
307 |
308 | Generates a private key in ECDA secp256k1 format
309 |
310 | ```solidity
311 | function privateKeyGen(CryptoSignature crypto) internal view returns (string memory)
312 | ```
313 |
314 | Inputs:
315 |
316 | - `crypto` (CryptoSignature): Type of the private key to generate
317 |
318 | Outputs:
319 |
320 | - `privateKey` (string): Hex encoded string of the ECDSA private key. Exactly as a signMessage precompile wants.
321 |
322 | ### `randomBytes`
323 |
324 | Address: `0x000000000000000000000000000000007770000b`
325 |
326 | Generates a number of random bytes, given by the argument numBytes.
327 |
328 | ```solidity
329 | function randomBytes(uint8 numBytes) internal view returns (bytes memory)
330 | ```
331 |
332 | Inputs:
333 |
334 | - `numBytes` (uint8): Number of random bytes to generate
335 |
336 | Outputs:
337 |
338 | - `value` (bytes): Randomly-generated bytes
339 |
340 | ### `signEthTransaction`
341 |
342 | Address: `0x0000000000000000000000000000000040100001`
343 |
344 | Signs an Ethereum Transaction, 1559 or Legacy, and returns raw signed transaction bytes. `txn` is binary encoding of the transaction.
345 |
346 | ```solidity
347 | function signEthTransaction(bytes memory txn, string memory chainId, string memory signingKey) internal view returns (bytes memory)
348 | ```
349 |
350 | Inputs:
351 |
352 | - `txn` (bytes): Transaction to sign (RLP encoded)
353 | - `chainId` (string): Id of the chain to sign for (hex encoded, with 0x prefix)
354 | - `signingKey` (string): Hex encoded string of the ECDSA private key (without 0x prefix)
355 |
356 | Outputs:
357 |
358 | - `signedTxn` (bytes): Signed transaction encoded in RLP
359 |
360 | ### `signMessage`
361 |
362 | Address: `0x0000000000000000000000000000000040100003`
363 |
364 | Signs a message and returns the signature.
365 |
366 | ```solidity
367 | function signMessage(bytes memory digest, CryptoSignature crypto, string memory signingKey) internal view returns (bytes memory)
368 | ```
369 |
370 | Inputs:
371 |
372 | - `digest` (bytes): Message to sign
373 | - `crypto` (CryptoSignature): Type of the private key to generate
374 | - `signingKey` (string): Hex encoded string of the ECDSA private key
375 |
376 | Outputs:
377 |
378 | - `signature` (bytes): Signature of the message with the private key
379 |
380 | ### `simulateBundle`
381 |
382 | Address: `0x0000000000000000000000000000000042100000`
383 |
384 | Performs a simulation of the bundle by building a block that includes it.
385 |
386 | ```solidity
387 | function simulateBundle(bytes memory bundleData) internal view returns (uint64)
388 | ```
389 |
390 | Inputs:
391 |
392 | - `bundleData` (bytes): Bundle encoded in JSON
393 |
394 | Outputs:
395 |
396 | - `effectiveGasPrice` (uint64): Effective Gas Price of the resultant block
397 |
398 | ### `simulateTransaction`
399 |
400 | Address: `0x0000000000000000000000000000000053200002`
401 |
402 | Simulates a transaction on a remote builder session
403 |
404 | ```solidity
405 | function simulateTransaction(string memory sessionid, bytes memory txn) internal view returns (SimulateTransactionResult memory)
406 | ```
407 |
408 | Inputs:
409 |
410 | - `sessionid` (string): ID of the remote builder session
411 | - `txn` (bytes): Txn to simulate encoded in RLP
412 |
413 | Outputs:
414 |
415 | - `simulationResult` (SimulateTransactionResult): Result of the simulation
416 |
417 | ### `submitBundleJsonRPC`
418 |
419 | Address: `0x0000000000000000000000000000000043000001`
420 |
421 | Submits bytes as JSONRPC message to the specified URL with the specified method. As this call is intended for bundles, it also signs the params and adds `X-Flashbots-Signature` header, as usual with bundles. Regular eth bundles don't need any processing to be sent.
422 |
423 | ```solidity
424 | function submitBundleJsonRPC(string memory url, string memory method, bytes memory params) internal view returns (bytes memory)
425 | ```
426 |
427 | Inputs:
428 |
429 | - `url` (string): URL to send the request to
430 | - `method` (string): JSONRPC method to call
431 | - `params` (bytes): JSONRPC input params encoded in RLP
432 |
433 | Outputs:
434 |
435 | - `errorMessage` (bytes): Error message if any
436 |
437 | ### `submitEthBlockToRelay`
438 |
439 | Address: `0x0000000000000000000000000000000042100002`
440 |
441 | Submits a given builderBid to a mev-boost relay.
442 |
443 | ```solidity
444 | function submitEthBlockToRelay(string memory relayUrl, bytes memory builderBid) internal view returns (bytes memory)
445 | ```
446 |
447 | Inputs:
448 |
449 | - `relayUrl` (string): URL of the relay to submit to
450 | - `builderBid` (bytes): Block bid to submit encoded in JSON
451 |
452 | Outputs:
453 |
454 | - `blockBid` (bytes): Error message if any
455 |
456 | ## Precompiles Governance
457 |
458 | The governance process for adding precompiles is in it's early stages but is as follows:
459 |
460 | - Discuss the idea in a [forum post](https://collective.flashbots.net/c/suave/27)
461 | - Open a PR and provide implementation
462 | - Feedback and review
463 | - Possibly merge and deploy in the next network upgrade, or sooner, depending on the precompile
464 |
--------------------------------------------------------------------------------
/specs/rigil/suave-chain.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Suave Chain
3 | description: The primary purpose of the SUAVE chain is to reach (and maintain) consensus about smart contract code for SUAPPs, as well as be a global information leak broadcast system.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/rigil/suave-chain.md"
5 | ---
6 |
7 |
8 |
9 | # Suave Chain
10 |
11 |
12 |
13 | **Table of Contents**
14 |
15 |
16 |
17 | - [Overview](#overview)
18 | - [Configuration](#configuration)
19 | - [Network Parameters](#network-parameters)
20 | - [Genesis Settings](#genesis-settings)
21 | - [Consensus Mechanism: Proof-of-Authority (Clique)](#consensus-mechanism-proof-of-authority-clique)
22 | - [Geth Version](#geth-version)
23 | - [Suave Transaction](#suave-transaction)
24 | - [Suave Transaction Types](#suave-transaction-types)
25 | - [TransactionRequest Serialization \& Signing](#transactionrequest-serialization--signing)
26 | - [Node Requirements and Setup](#node-requirements-and-setup)
27 | - [Gas and Transaction Fees](#gas-and-transaction-fees)
28 | - [Security Considerations](#security-considerations)
29 |
30 |
31 |
32 | ---
33 |
34 | ## Overview
35 |
36 |
37 |
38 | This document outlines the specifications for the SUAVE Rigil chain.
39 |
40 | In the context of the SUAVE protocol, the primary purpose of the SUAVE chain is to reach (and maintain) consensus about smart contract code for use cases such as order flow auctions, solvers, block builders, etc. Additionally, the SUAVE chain can also be used to store and broadcast data for better censorship guarantees.
41 |
42 | In the initial phases of development, the SUAVE chain runs a proof-of-authority consensus protocol called Clique, over a network of permissioned nodes. We do so to experiment and iterate quickly during protocol development. This will change in later testnets.
43 |
44 | ## Configuration
45 |
46 | ### Network Parameters
47 |
48 | - **Network ID**: `16813125`
49 | - **Chain ID**: `16813125`
50 |
51 | ### Genesis Settings
52 |
53 | | Name | Value | Unit |
54 | | ---------------- | -------- | -------- |
55 | | `PERIOD` | 4 | `block` |
56 | | `EPOCH` | 30000 | `block` |
57 | | `BLOCK_TIME` | 3 | `second` |
58 | | `GAS_LIMIT` | 30000000 | `gas` |
59 | | `NUM_VALIDATORS` | 5 | Nodes |
60 |
61 |
62 | ## Consensus Mechanism: Proof-of-Authority (Clique)
63 |
64 | Clique, an Ethereum-based Proof-of-Authority consensus protocol defined [here](https://eips.ethereum.org/EIPS/eip-225#:~:text=A%20PoA%20scheme%20is%20based,the%20list%20of%20trusted%20signers), restricts block minting to a predefined list of trusted signers. Because of this, every block header a client sees can be checked against the list of trusted signers.
65 |
66 |
67 | ### Geth Version
68 |
69 | Suave-geth is based on geth v1.12.0 ([`e501b3`](https://github.com/flashbots/suave-geth/commit/e501b3b05db8e169f67dc78b7b59bc352b3c638d)).
70 |
71 | ---
72 |
73 | ## Suave Transaction
74 |
75 | The SUAVE protocol adds a new transaction type to the base Ethereum protocol called a `SuaveTransaction`. The purpose of this new transaction type is to process fees for offchain computation and to support the new data primitives associated with confidential compute.
76 |
77 | Blocks on the SUAVE chain consist of lists of SUAVE transactions. This new transaction type facilitates and captures key information involved in Confidential Compute Requests and their subsequent results. Any `ConfidentialComputeRequest`, signed by the user, specifies an `KettleAddress`. SUAVE transactions are valid if and only if they are signed by the `KettleAddress` specified by the user in the original `ConfidentialComputeRequest`, which is included as the `ConfidentialComputeRecord`.
78 |
79 | ```go
80 | type SuaveTransaction struct {
81 | ConfidentialComputeRequest ConfidentialComputeRecord
82 | ConfidentialComputeResult []byte
83 |
84 | // Kettle's signature
85 | ChainID *big.Int
86 | V *big.Int
87 | R *big.Int
88 | S *big.Int
89 | }
90 | ```
91 |
92 | ### Suave Transaction Types
93 |
94 | `SuaveTransaction` is the primary transaction type which is returned when requesting transactions from endpoints like `eth_getTransactionByHash` or `eth_getBlockByNumber`, but SUAVE introduces two other important message types: `ConfidentialComputeRequest` and `ConfidentialComputeRecord`. All new types are detailed in the following table:
95 |
96 | | Name | EIP-2718 Tx Type | Description |
97 | | -------------------------- | ---------------- | --------------------------------------------------------------------------------------- |
98 | | SuaveTransaction | `0x50` | SUAVE transaction; product of executed ConfidentialComputeRequest |
99 | | ConfidentialComputeRequest | `0x43` | Sent by users to interact with SUAVE smart contracts using confidential inputs |
100 | | ConfidentialComputeRecord | `0x42` | Artifact of ConfidentialComputeRequest; represents record that is stored on SUAVE chain |
101 |
102 | ## TransactionRequest Serialization & Signing
103 |
104 | Messages sent by users of SUAVE can take on two forms:
105 | 1. Standard (legacy) Ethereum transaction
106 | 2. `ConfidentialComputeRequest`
107 |
108 | Standard transactions are used to transfer SUAVE-ETH and deploy smart contracts to SUAVE chain. ConfidentialComputeRequests are a new [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) message type, used to interact with SUAVE smart contracts. Note that 'ConfidentialComputeRequests' are **not** classified as 'transactions' since 'transaction' implies changes to the state of a database/blockchain. Kettles do not provide persistent storage guarantees and are instead intended to convert inputs to outputs (like transactions targeted at blockchains).
109 |
110 | All transactions are encoded with the [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) RLP-encoding scheme (with [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) allowed), but `ConfidentialComputeRequest` takes on a special signature scheme that deviates slightly from the traditional method.
111 |
112 | 
113 |
114 | ConfidentialComputeRequests adopt this unique signing scheme to keep `confidentialInputs` off-chain. The ConfidentialComputeRecord, which is signed by the sender, contains only the _hash_ of `confidentialInputs`. This record is stored on the SUAVE chain, making verification of `confidentialInputs` possible without exposing the actual data on-chain.
115 |
116 | In javascript, a `ConfidentialComputeRequest` has the following structure:
117 |
118 | ```js
119 | const cRequest = {
120 | confidentialInputs: '0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000fd7b22626c6f636b4e756d626572223a22307830222c22747873223a5b2230786638363538303064383235323038393461646263653931303332643333396338336463653834316336346566643261393232383165653664383230336538383038343032303131386164613038376337386234353663653762343234386237313565353164326465656236343031363032343832333735663130663037396663666637373934383830653731613035373366336364343133396437323037643165316235623263323365353438623061316361336533373034343739656334653939316362356130623661323930225d2c2270657263656e74223a31307d000000',
121 | kettleAddress: '0xb5feafbdd752ad52afb7e1bd2e40432a485bbb7f',
122 | to: '0x8f21Fdd6B4f4CacD33151777A46c122797c8BF17',
123 | gasPrice: 10000000000n,
124 | gas: 420000n,
125 | type: '0x43',
126 | chainId: 16813125,
127 | data: '0x236eb5a70000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000010000000000000000000000008f21fdd6b4f4cacd33151777a46c122797c8bf170000000000000000000000000000000000000000000000000000000000000000',
128 | }
129 | ```
130 |
131 | Note: new fields: `confidentialInputs` and `kettleAddress`.
132 |
133 | To serialize, sign, and send this request, the client must first RLP-encode the request as a `ConfidentialComputeRecord` and sign its hash.
134 |
135 | Note: the following is pseudo-code. `rlp`, `keccak256`, and `wallet.sign` implementations may differ.
136 |
137 | ```js
138 | const {
139 | nonce,
140 | gasPrice,
141 | gas,
142 | to,
143 | value,
144 | data,
145 | kettleAddress,
146 | confidentialInputs,
147 | chainId,
148 | } = cRequest
149 | const rlpRecord = rlp('0x42', [
150 | kettleAddress,
151 | keccak256(confidentialInputs),
152 | nonce,
153 | gasPrice,
154 | gas,
155 | to,
156 | value,
157 | data,
158 | ])
159 | const {v, r, s} = wallet.sign(keccak256(rlpRecord))
160 | cRecord = {...cRecord, v, r, s}
161 | ```
162 |
163 | Then, the final request is re-encoded with RLP as follows:
164 |
165 | ```js
166 | // assume (v, r, s) have been added to cRecord
167 | const tx = rlp('0x43', [
168 | cRecord.nonce,
169 | cRecord.gasPrice,
170 | cRecord.gas,
171 | cRecord.to,
172 | cRecord.value,
173 | cRecord.data,
174 | cRecord.kettleAddress,
175 | keccak256(cRequest.confidentialInputs),
176 | cRecord.chainId,
177 | cRecord.v === 27n ? '0x' : '0x1', // yParity
178 | cRecord.r,
179 | cRecord.s,
180 | ],
181 | confidentialInputs
182 | )
183 | ```
184 |
185 | This is then sent to SUAVE via `eth_sendRawTransaction`:
186 |
187 | ```js
188 | wallet.request('eth_sendRawTransaction', [tx])
189 | ```
190 |
191 | ## Node Requirements and Setup
192 |
193 | - **Hardware**:
194 | - Minimum 8GB RAM, four cores, 50GB SSD (How big do we expect the chain to grow?)
195 | - These requirements will eventually incorporate Trusted Execution Environments (TEEs).
196 | - **Software**: [suave-geth](https://github.com/flashbots/suave-geth/)
197 | - **Setup Steps**:
198 | 1. Clone suave-geth
199 | 2. Start the devnet: `make devnet-up`
200 | 3. Create transactions: `go run suave/devenv/cmd/main.go`
201 |
202 | ---
203 |
204 | ## Gas and Transaction Fees
205 |
206 | The SUAVE chain employs the same gas pricing mechanism as Ethereum pre-Cancun hardfork (no blob transactions) where gas prices adjust based on network demand. Nodes currently track Confidential Compute Request gas usage but only charge a small flat fee for it, and there is no cap for offchain compute.
207 |
208 | Currently, SUAVE transactions can only be expressed as Legacy transaction types, but they will get converted into EIP-1559 base fee model under the hood.
209 |
210 | ---
211 |
212 | ## Security Considerations
213 |
214 | - **Security Risk**: The protocol is unaudited. The protocol currently does not make any guarantees about the confidentiality of data in the network outside of a best effort.
215 | - **DoS Risk**: Nodes have not yet been reviewed, and there may be DoS vectors at this early stage.
216 | - **Secure Key Management**: Storing private keys on Suave is experimental and should be considered insecure.
217 |
218 | If you find a security vulnerability in SUAVE, please email us at security@flashbots.net.
219 |
--------------------------------------------------------------------------------
/specs/sirrah/README.md:
--------------------------------------------------------------------------------
1 | # ☀️ Coming Soon
2 |
3 | ⚡️🤖
--------------------------------------------------------------------------------
/specs/toliman/README.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Toliman Testnet
3 | description: Toliman is the second testnet for SUAVE. It is a sandbox and foundation for building MEV applications in a decentralized and private manner, focused on developers.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/toliman/README.md"
5 | ---
6 |
7 |
8 |
9 | # SUAVE Toliman Testnet
10 |
11 |
12 |
13 | [](https://suave.flashbots.net/)
14 | [](https://collective.flashbots.net/)
15 |
16 | This repository hosts the current SUAVE Toliman testnet specifications and design docs.
17 |
18 |
19 |
20 | ⚠️ The SUAVE protocol is still in a state where [the code](https://github.com/flashbots/suave-geth) is the most up-to-date protocol spec and [open questions](#open-questions) are being researched. The goal of these notes is to gradually evolve into an implementation-agnostic specification. ⚠️
21 |
22 |
23 |
24 | ---
25 |
26 | **Table of Contents**
27 |
28 |
29 |
30 | - [Specs](#specs)
31 | - [About SUAVE](#about-suave)
32 | - [Toliman Overview](#toliman-overview)
33 | - [Users](#users)
34 | - [Toliman Design Goals](#toliman-design-goals)
35 | - [Design Decisions](#design-decisions)
36 | - [Glossary](#glossary)
37 | - [Architecture](#architecture)
38 | - [Open Questions](#open-questions)
39 | - [Example Flows](#example-flows)
40 | - [High Level - OFA + Block Builder](#high-level---ofa--block-builder)
41 | - [Confidential Compute Request Flow](#confidential-compute-request-flow)
42 | - [OFA Example](#ofa-example)
43 | - [Block Building Example](#block-building-example)
44 |
45 |
46 |
47 | ---
48 |
49 | ## Specs
50 |
51 | We recommend that you read the specs in the following order:
52 |
53 | - [Suave Chain](./suave-chain.md)
54 | - [MEVM](./mevm.md)
55 | - [Precompiles](./precompiles.md)
56 | - [Confidential Data Store](./confidential-data-store.md)
57 | - [Kettle](./kettle.md)
58 | - [Bridge](./bridge.md)
59 |
60 | ---
61 |
62 | ## About SUAVE
63 |
64 | SUAVE - Single Unifying Auction for Value Expression - is a platform for building MEV applications such as OFAs, block builders, and intent executors in a decentralized and private way. SUAVE does not replace other blockchains: it is intended to aggregate and coordinate all the things that ultimately change the state of other chains.
65 |
66 | Read more about SUAVE:
67 | - https://writings.flashbots.net/the-future-of-mev-is-suave
68 | - https://writings.flashbots.net/mevm-suave-centauri-and-beyond
69 |
70 |
71 | ---
72 |
73 | ## Toliman Overview
74 |
75 |
8 |
9 |
10 |
11 | # Bridge
12 |
13 |
14 |
15 | SUAVE uses a simple and highly trusted bridge with the Holesky Ethereum network to transfer assets for gas and MEV applications.
16 |
17 | The current bridge implementation is meant to enable rapid prototyping. It is not meant for production / mainnet usage.
18 |
19 | ## Components
20 |
21 | The bridge code consists of two components:
22 | 1. onchain `GasBridge` contract
23 | 2. offchain `relayerClient`
24 |
25 | An implementation of a `GasBridge` smart contract and the trusted `relayerClient` backend can be found [here](https://github.com/flashbots/suave-bridge/blob/master/contracts/GasBridge.sol) and [here](https://github.com/flashbots/suave-bridge/blob/master/internal/bridge.go) respectively.
26 |
27 | The `GasBridge` solidity is responsible for emitting events that the `relayerClient` uses as a signal to mint on the SUAVE chain. The `relayerClient` backend initializes and manages a bridge between two Ethereum chains (rootchain and sidechain) for monitoring and relaying events. The `relayerClient` code includes functions for tracking events, handling transactions, and managing event states.
28 |
29 | ```solidity
30 | interface GasBridge {
31 | event GasEvent(address indexed sender, uint256 indexed id, uint256 amount);
32 |
33 | function transfer() external payable
34 | }
35 | ```
36 |
37 | ```go
38 | type relayerClient interface {
39 | SendTransaction(ctx context.Context, event *GasEvent) (string, error)
40 | TransactionReceipt(ctx context.Context, hash common.Hash) (*types.Receipt, error)
41 | }
42 | ```
43 |
--------------------------------------------------------------------------------
/specs/toliman/confidential-data-store.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Confidential Data Store
3 | description: This essential component of the SUAVE protocol serves as a secure and privacy-focused storage system.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/toliman/confidential-data-store.md"
5 | ---
6 |
7 |
8 |
9 | # Confidential Data Store
10 |
11 |
12 |
13 | **Table of Contents**
14 |
15 |
16 |
17 | - [Overview](#overview)
18 | - [Core Functionality](#core-functionality)
19 | - [Architecture](#architecture)
20 | - [Engine](#engine)
21 | - [Store](#store)
22 | - [Transport](#transport)
23 | - [Data Management](#data-management)
24 | - [Initialization \& Access Control](#initialization--access-control)
25 | - [Security and Confidentiality](#security-and-confidentiality)
26 |
27 |
28 |
29 |
30 | ## Overview
31 |
32 |
33 |
34 | This document provides the technical specification for the the Confidential Data Store, a privacy-centric networked storage system specifically tailored to enable programmable privacy in SUAPPs.
35 |
36 | ## Core Functionality
37 |
38 | 1. **Confidential Data Input**:
39 | SUAPPs define the shape and operations performed on user data, which is put into the confidential data store. Users send data to SUAPPs and, ultimately, the confidential data store through confidential compute requests.
40 |
41 | 2. **Confidential Data Transfer**:
42 | Once Kettles successfully carry out confidential compute requests, the results are disseminated to other Kettles using a dedicated transport protocol.
43 |
44 | 3. **Data Modeling**:
45 | The confidential data store adopts a straightforward key-value storage paradigm. This allows flexibility in accommodating various data types:
46 | - Transactions, UserOps, and EIP 712 signed messages.
47 | - Bundles, simulation results, and intermediate values.
48 | - Partial and full blocks.
49 | - Other extensible data entities.
50 |
51 | 4. **Access Control**:
52 | To enable programmable privacy, only contracts bearing the correct permissions, termed 'peekers', are permitted to get and put data.
53 |
54 |
55 | ## Architecture
56 |
57 | The Confidential Data Store consists of three main components: Engine, Storage, and Transport. The Engine is the main orchestrating component responsible for managing calls to Storage, as well as sending and receiving synchronization messages over the Transport. The MEVM is able to directly interact with the Confidential Store Engine through precompiles.
58 |
59 | 
60 |
61 | ### Engine
62 |
63 | The `ConfidentialStoreEngine` is the central component in the Confidential Data Store's architecture and is responsible for coordinating data storage operations and data synchronization across the network. Integrated with the MEVM, it facilitates storage interactions via precompiled contracts. The code snippet below outlines its composition in our current [suave-geth](https://github.com/flashbots/suave-geth/tree/main) reference implementation:
64 |
65 | ```go
66 | type ConfidentialStoreEngine struct {
67 | ctx context.Context
68 | cancel context.CancelFunc
69 |
70 | storage ConfidentialStorageBackend
71 | transportTopic StoreTransportTopic
72 |
73 | daSigner DASigner
74 | chainSigner ChainSigner
75 |
76 | storeUUID uuid.UUID
77 | localAddresses map[common.Address]struct{}
78 | }
79 | ```
80 |
81 | ### Store
82 | `ConfidentialStorageBackend` is the interface that a storage backend for the Confidential Storage Engine must implement.
83 |
84 | ```go
85 | type ConfidentialStorageBackend interface {
86 | InitRecord(record suave.DataRecord) error
87 | Store(record suave.DataRecord, caller common.Address, key string, value []byte) (suave.DataRecord, error)
88 | Retrieve(record suave.DataRecord, caller common.Address, key string) ([]byte, error)
89 | FetchRecordByID(suave.DataId) (suave.DataRecord, error)
90 | FetchRecordsByProtocolAndBlock(blockNumber uint64, namespace string) []suave.DataRecord
91 | Stop() error
92 | }
93 | ```
94 |
95 | *Implementation Note: in our [suave-geth](https://github.com/flashbots/suave-geth/tree/main) reference implementation, we provide two `ConfidentialStorageBackend`: the LocalConfidentialStore, storing data in memory in a simple dictionary; and RedisStoreBackend, storing data in Redis. Redis was chosen to allow for fast iteration, but is not meant to be a long term solution.*
96 |
97 | ### Transport
98 |
99 | `StoreTransportTopic` is the interface that must be implemented by a transport engine for the Confidential Storage Engine.
100 |
101 | ```go
102 | type StoreTransportTopic interface {
103 | node.Lifecycle
104 | Subscribe() (<-chan DAMessage, context.CancelFunc)
105 | Publish(DAMessage)
106 | }
107 | ```
108 |
109 | *Implementation Note: in our [suave-geth](https://github.com/flashbots/suave-geth/tree/main) reference implementation, we provide an implementation using a shared Redis PubSub in RedisPubSubTransport, as well as a crude synchronization protocol. Note that Redis transport only synchronizes the current state; there is no initial synchronization - a newly connected node will not have access to old data for now. This synchronization protocol will be defined in upcoming specifications.*
110 |
111 |
112 | ## Data Management
113 |
114 | Data Management is at the heart of the Confidential Data Store, ensuring data is stored, retrieved, and maintained securely and efficiently.
115 |
116 | ### Initialization & Access Control
117 |
118 | The Confidential Data Store ensures that only legitimate entities can store data, and only authorized parties can retrieve it.
119 |
120 | - *Data Registration*: When initializing, it's vital to ensure that only valid data is registered in the system. Data must satisfy specific criteria, such as proper formatting, authentication, and non-duplication. Still, these requirements do not restrict *what* type of data gets put in, merely that it should follow a high-level format.
121 |
122 | - *Access Permissions*: A robust access control mechanism restricts data access. Only contracts with appropriate permissions (peekers) can access stored data. This mechanism is currently context-based, and the specific access control mechanism is laid out in the [MEVM](./mevm.md)
123 |
124 | ## Security and Confidentiality
125 |
126 | Ensuring the confidentiality of the stored data is paramount. Current implementations are still works in progress, and data should not be considered secure. Future iterations will delve deeper into encryption methodologies, access controls, and auditing mechanisms to fortify data privacy further.
127 |
128 |
129 |
130 |
131 |
132 |
133 |
134 |
135 |
136 |
137 |
138 |
--------------------------------------------------------------------------------
/specs/toliman/glossary.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Glossary
3 | description: Important SUAVE terms.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/toliman/glossary.md"
5 | ---
6 |
7 | # Glossary
8 |
9 | | Term | Description |
10 | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11 | | **Builder solidity** | solidity with access to precompiles that help facilitate the processing of transactions and intents. |
12 | | **Confidential Compute Request (CCR)** | a user request to Suave that contains (1) SUAPP information such as to and calldata, (2) confidential inputs, and (3) a list of SUAPPs and Kettles allowed to operate on confidential inputs. [[🔗spec](./kettle.md#confidential-compute-process)]. |
13 | | **Confidential Data Store** | stores confidential data for SUAPPs (L1 transactions, EIP 712 signed messages, userOps, private keys, and more). [[🔗spec](./confidential-data-store.md)]. |
14 | | **Developer** | creates smart contracts on SUAVE Chain that define rules for SUAPPs. |
15 | | **Domains** | [a system with a globally shared state that is mutated by various players through actions](https://arxiv.org/abs/2112.01472) (e.g. “transactions”) that execute in a shared execution environment. |
16 | | **Domain-Specific Services** | provides functionality to interact with target domains (i.e. for Goerli or Arbitrum, simulate transactions, build bundles, build blocks, …). [[🔗spec](./kettle.md#domain-specific-services)]. |
17 | | **Intent** | refers to “what” the desired outcome of an action on a blockchain should be as opposed to transactions which specify “how” an action should be performed. |
18 | | **Intent Executor** | actor who is responsible for taking consolidated user intents and executing them on a domain. |
19 | | **Kettle** | accepts and processes confidential compute requests and maintains the SUAVE chain; the logical unit of the SUAVE network and main protocol actor. [[🔗spec](kettle.md)]. |
20 | | **MEVM** | modified EVM with a set of precompiles to interact with APIs for Confidential Data Store, Domain-Specific Services, and more. [[🔗spec](./mevm.md)]. |
21 | | **OFA** | an application that receives transactions and either facilitates an auction on top of it or routes it elsewhere. |
22 | | **Peekers** | contracts with the correct permissions - granted by users in CCRs - to get and put data in the Confidential Data Store. |
23 | | **Precompiles** | purpose-built functions with extended capabilities that can be called from Builder Solidity. [[🔗spec](./precompiles.md)]. |
24 | | **Toliman Testnet** | The current test network. Naming convention follows the stars in the Alpha Centauri system. |
25 | | **Relay** | actor in the [mev-boost protocol](https://github.com/flashbots/mev-boost) that is responsible for validating blocks and offering them to validators upon request. |
26 | | **RPC** | Endpoint to receive user transactions, which moves confidential input to the Confidential Data Store, and passes the compute request to MEVM. |
27 | | **SUAPP** | SUAVE application, smart contracts on SUAVE chain with rules for confidential computation and functions to submit to target domains (i.e. chains). |
28 | | **SUAVE Chain** | a fork of Ethereum designed to facilitate credible, confidential execution in MEV use cases. Main purpose is to reach (and maintain) consensus about smart contract code. [[🔗spec](./suave-chain.md)]. |
29 | | **SUAVE transaction** | the transaction object that is broadcast on the SUAVE Chain. Contains the result of a CCR in its calldata + the signature of the Kettle(s) which computed said result. |
30 | | **Solver** | actor who takes many user token trades as input and competes to provide a solution to the mathematically optimal way to route all trades. |
31 | | **User** | humans or computers interacting with SUAPPs, primarily through sending confidential compute requests (CCR) to Kettles. |
32 |
--------------------------------------------------------------------------------
/specs/toliman/kettle.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Kettle
3 | description: SUAVE Kettles contain all necessary components to accept, process, and route confidential compute requests and results.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/toliman/kettle.md"
5 | ---
6 |
7 |
8 |
9 | # Kettle
10 |
11 |
12 |
13 | **Table of Contents**
14 |
15 |
16 |
17 | - [Overview](#overview)
18 | - [Prerequisites](#prerequisites)
19 | - [Kettle Responsibilities](#kettle-responsibilities)
20 | - [Becoming a Kettle](#becoming-a-kettle)
21 | - [Kettle Identification](#kettle-identification)
22 | - [Kettle Architecture](#kettle-architecture)
23 | - [RPC](#rpc)
24 | - [SUAVE PoA Chain](#suave-poa-chain)
25 | - [MEVM](#mevm)
26 | - [Confidential Data Store](#confidential-data-store)
27 | - [Domain-Specific Services](#domain-specific-services)
28 | - [Containers](#containers)
29 | - [Confidential Compute Record](#confidential-compute-record)
30 | - [Confidential Compute Request](#confidential-compute-request)
31 | - [Suave Transaction](#suave-transaction)
32 | - [Honest Kettle](#honest-kettle)
33 | - [Confidential Computation](#confidential-computation)
34 | - [Confidential Compute Process](#confidential-compute-process)
35 | - [Suave JSON-RPC](#suave-json-rpc)
36 | - [eth\_sendRawTransaction](#eth_sendrawtransaction)
37 | - [eth\_call](#eth_call)
38 | - [eth\_executionAddress](#eth_executionaddress)
39 |
40 |
41 |
42 | ## Overview
43 |
44 |
45 |
46 | This document provides the technical specification for the SUAVE Kettle, one of the primary protocol actors in the SUAVE protocol. The Kettle contains all necessary components to accept, process, and route confidential compute requests and results. Below, the expected behavior of an "honest Kettle" for the Toliman testnet version of the SUAVE protocol is outlined.
47 |
48 | ## Prerequisites
49 |
50 | All terminology, functions, and protocol mechanics defined in [SUAVE chain](./suave-chain.md), [Confidential Data Store](./confidential-data-store.md), and [MEVM](./mevm.md) are prerequisites for this document and used throughout. Please see the [Toliman overview](../../README.md) before continuing and use it as a reference.
51 |
52 | ## Kettle Responsibilities
53 |
54 | A Kettle has several primary responsibilities within the SUAVE network:
55 |
56 | 1. **Handling Confidential Compute Requests:**
57 | - Process `ConfidentialComputeRequest` received from users or other network nodes.
58 | - Execute transactions in confidential mode, providing access to the usual confidential APIs.
59 | - Create a `SuaveTransaction` using the confidential computation request and result.
60 | - Sign and submit the transaction into the SUAVE mempool.
61 |
62 | 2. **Maintaining the Confidential Data Store:**
63 | - Store and retrieve confidential data used in all SUAPPs.
64 | - Restrict access to stored data based on the allowed peekers and stores of each bid.
65 | - Ensure synchronization of confidential data across the network.
66 |
67 | 3. **Propagating Confidential Compute Requests and Results:**
68 | - Forward bundles and blocks emitted from confidential computation to block builders and relays.
69 | - Broadcast the results of confidential computations to the appropriate parties within the SUAVE network.
70 | - Ensure the propagation of results adheres to the confidentiality and privacy requirements of the SUAVE protocol.
71 |
72 | ## Becoming a Kettle
73 |
74 | Currently, Kettles are not permissioned, but participation in the confidential data store synchronization protocol is. To join the network, you must run the entire Kettle software stack and connect to the existing network via bootnode or known peer. Eventually, Kettles will be associated with an onchain registry.
75 |
76 | ### Kettle Identification
77 |
78 | A unique identifier in the form of an Ethereum-compatible public key must be generated for each Kettle to ensure proper tracking and verification of Confidential Computation, as well as responsibility assignment within the network.
79 |
80 | ## Kettle Architecture
81 |
82 | SUAVE Kettles house all components necessary to perform confidential computation and result routing. Below is a high-level architectural diagram followed by descriptions of the main components.
83 |
84 | 
85 |
86 | ### RPC
87 |
88 | This component is similar to RPCs in any Ethereum or blockchain client and is responsible for mapping user's requests to their appropriate functionality.
89 |
90 | ### SUAVE PoA Chain
91 |
92 | The SUAVE chain maintains consensus about smart contract code for SUAPPs. Additionally, it can also be used to store and broadcast data for better censorship guarantees.
93 |
94 | Kettles must keep a lively copy of the SUAVE chain state to process Confidential Compute Requests, but these liveliness requirements are currently not defined in the Toliman Kettle.
95 |
96 | For more details see the [🔗 SUAVE chain](./suave-chain.md) spec.
97 |
98 | ### MEVM
99 |
100 | The MEVM is a new interpreter and a set of precompiles to interact with APIs for the Confidential Data Store and domain-specific services.
101 |
102 | For more details see the [🔗 MEVM](./mevm.md) spec.
103 |
104 | ### Confidential Data Store
105 |
106 | The Confidential Store is a secure and privacy-focused storage system, exposing a key-value store for safeguarding confidential compute and orderflow-related data. Only those with appropriate permissions (peekers) can access the stored data, thus ensuring privacy and control.
107 |
108 | For more details, see the [🔗 Confidential Data Store](./confidential-data-store.md) spec.
109 |
110 | ### Domain-Specific Services
111 |
112 | Domain-Specific Services allow Kettles to scale horizontally by hosting nodes for other domains in separate processes that can be queried at confidential compute time. Kettles currently are not responsible for publicly committing to their domain-specific services, so support for a specific domain is done on Kettle-by-Kettle basis. If a Kettle attempts to process your confidential compute request for a domain it does not support, it will simply return a failure on the computation and will not propagate the failure to the rest of the network so other Kettles can still attempt to process.
113 |
114 | For more details on supporting the needed APIs to enable a domain, see below [🔗 SUAVE Execution API](#suave-json-rpc) spec.
115 |
116 | ## Containers
117 |
118 | The core data types used inside the Kettle.
119 |
120 | ### Confidential Compute Record
121 |
122 | This type serves as a record of computation. It's part of both the [Confidential Compute Request](#confidential-compute-request) and [Suave Transaction](#suave-transaction).
123 |
124 | ```go
125 | type ConfidentialComputeRecord struct {
126 | Nonce uint64
127 | GasPrice *big.Int
128 | Gas uint64
129 | To *common.Address
130 | Value *big.Int
131 | Data []byte
132 |
133 | KettleAddress common.Address
134 | ConfidentialInputsHash common.Hash
135 |
136 | ChainID *big.Int
137 | V, R, S *big.Int
138 | }
139 | ```
140 |
141 |
142 | ### Confidential Compute Request
143 |
144 | This type enables users to request the MEVM to compute over their data via the `eth_sendRawTransaction` method. After processing, the request's `ConfidentialComputeRecord` is embedded into `SuaveTransaction.ConfidentialComputeRequest` and serves as an onchain record of computation.
145 |
146 | ```go
147 | type ConfidentialComputeRequest struct {
148 | ConfidentialComputeRecord
149 | ConfidentialInputs []byte
150 | }
151 | ```
152 |
153 | A Kettle's signature is used as the integrity guarantee for the computation's results. Eventually, this can include arbitrary proofs such as zero-knowledge proofs.
154 |
155 | ### Suave Transaction
156 |
157 | The final home of compute results and intentionally leaked data from confidential compute requests is a SUAVE transaction; see [🔗 SUAVE chain](./suave-chain.md) specs for more details
158 |
159 | ```go
160 | type SuaveTransaction struct {
161 | ConfidentialComputeRequest ConfidentialComputeRecord
162 | ConfidentialComputeResult []byte
163 |
164 | // Kettle's signature
165 | ChainID *big.Int
166 | V *big.Int
167 | R *big.Int
168 | S *big.Int
169 | }
170 | ```
171 |
172 |
173 | ## Honest Kettle
174 |
175 | At present, the protocol relies on the honesty of Kettles, akin to the reliance on honest block builders and relays. An honest Kettle performs the duties above of:
176 |
177 | - **Handling Confidential Compute Requests**
178 | - **Maintaining Confidential Data Privacy**
179 | - **Maintaining the Confidential Data Store**
180 | - **Propagating Confidential Compute Results**
181 |
182 | On the Toliman testnet, Kettles do not live inside Trusted Execution Environments. Because of this, a malicious Kettle could alter its source code to censor Confidential Compute Requests and their results.
183 |
184 | ## Confidential Computation
185 |
186 | To successfully process a request for confidential computation, Kettles must engage the Confidential Compute Process.
187 |
188 | ### Confidential Compute Process
189 |
190 | Confidential compute is defined by the use of an [offchain function call](https://docs.soliditylang.org/en/latest/contracts.html#view-functions), signified in solidity via the `view` modifier.
191 |
192 | These view functions are used with plaintext access to decrypted data to perform confidential computation on the decrypted data. Results and a signature of integrity are propagated along with the initial request. The confidential data is propagated separately via the confidential data store, but other Kettles do not need the underlying data as they will trust any valid signature attesting to the computation's integrity.
193 |
194 | 
195 |
196 | This sequence diagram represents the interactions between various components when processing a Confidential Compute Request (CCR). Here's a description of the flow depicted in the diagram:
197 |
198 | - *Starting Point*: The process initiates with a "Confidential Compute Request" directed towards the JsonRPC.
199 |
200 | - *MEVM Execution*: Upon receiving the request, the Json RPC triggers the MEVM (Modified Ethereum Virtual Machine) to run. MEVM execution can use multiple APIs depending on the context, with two possible paths:
201 |
202 | - Request to an External Domain: The MEVM can make API requests to external domains via Domain-Specific Services.
203 | - Request to the Confidential Datastore: The MEVM can make API requests directly to the "Confidential Datastore" to fetch or store data.
204 |
205 | - *Suave Chain Interaction*: Eventually, after processing the request, depending on the SUAPP, the MEVM takes the results and sends a SUAVE transaction.
206 |
207 | - *Transaction Hash Output*: Following the Suave transaction, a transaction hash is produced and returned to the request's originator, precisely like in the Ethereum process.
208 |
209 | ## Suave JSON-RPC
210 |
211 | SUAVE JSON-RPC can be seen as a super set of Ethereum JSON-RPC. This means the [Ethereum JSON-RPC standard](https://geth.ethereum.org/docs/interacting-with-geth/rpc) remains the same when interacting with the SUAVE chain. Some methods in the `eth_` namespace are overloaded to support the confidential compute requests.
212 |
213 | ### eth_sendRawTransaction
214 |
215 | Creates new message call transaction or a contract creation for a signed `ConfidentialComputeRequest`.
216 |
217 | ### eth_call
218 |
219 | Executes a new message call immediately without creating a transaction on the blockchain. It follows the same format as the default `eth_call` with two extra parameters:
220 |
221 | **Parameters**
222 |
223 | - `IsConfidential`: Set to true to execute as a confidential request and access the `MEVM` methods.
224 | - `ExecutionAddress`: `address` - (optional) The execution address that performs the execution.
225 |
226 | ### eth_executionAddress
227 |
228 | Returns the list of available addresses in the Kettle to execute a confidential compute request. Kettle owners can register multiple addresses to sign transactions with from their Kettle. Users can pick which address the Kettle must use to sign their transactions.
229 |
--------------------------------------------------------------------------------
/specs/toliman/mevm.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: MEVM
3 | description: The MEVM modifies the EVM by adding a new runtime, interpreter, and execution backend to enable anyone to create MEV applications.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/toliman/mevm.md"
5 | ---
6 |
7 |
8 |
9 | # MEVM
10 |
11 |
12 |
13 |
14 |
15 | - [Overview](#overview)
16 | - [Modified Interpreter](#modified-interpreter)
17 | - [Confidential Data Store APIs](#confidential-data-store-apis)
18 | - [`suavex` namespace](#suavex-namespace)
19 | - [Precompile Call Authorization](#precompile-call-authorization)
20 | - [Security and Confidentiality](#security-and-confidentiality)
21 |
22 |
23 |
24 | ---
25 |
26 | ## Overview
27 |
28 |
29 |
30 | This document provides the technical specification for the MEVM, a modified version of the Ethereum Virtual Machine (EVM). The MEVM is a set of precompiles to interact with APIs; two of these API services are the Confidential Data Store and the SUAVE Execution (SUAVEX) namespace. There may be other API endpoints in the future.
31 |
32 | ## Modified Interpreter
33 |
34 | Under the hood, the MEVM is a modified EVM Interpreter which is able to use a new runtime called the `SuaveExecutionBackend`.
35 |
36 | ```mermaid
37 | graph TB
38 | A[EVM]-->|1|B((StateDB))
39 | A-->|2|C((Context))
40 | A-->|3|D((chainConfig))
41 | A-->|4|E((Config))
42 | A-->|5|F((interpreter))
43 | D-->|6|R[ChainRules]
44 | E-->|7|S[Tracer]
45 | A-->|8|T[NewRuntime]
46 | T-->|9|Z((Runtime))
47 | Z-->|10|F
48 | A-->|11|U[NewRuntimeSuaveExecutionBackend]
49 | U-->|12|V((SuaveExecutionBackend))
50 | V-->|13|F
51 | class A,B,C,D,E,F yellow
52 | class G,H,I,J,K,L,M,N,O red
53 | class P,Q green
54 | class R blue
55 | class S orange
56 | class T,U purple
57 | class Z,V lightgreen
58 | classDef yellow fill:#f5cf58,stroke:#444,stroke-width:2px, color:#333;
59 | classDef red fill:#d98686,stroke:#444,stroke-width:2px, color:#333;
60 | classDef green fill:#82a682,stroke:#444,stroke-width:2px, color:#333;
61 | classDef blue fill:#9abedc,stroke:#444,stroke-width:2px, color:#333;
62 | classDef orange fill:#f3b983,stroke:#444,stroke-width:2px, color:#333;
63 | classDef purple fill:#ab92b5,stroke:#444,stroke-width:2px, color:#333;
64 | classDef lightgreen fill:#b3c69f,stroke:#444,stroke-width:2px, color:#333;
65 | ```
66 |
67 | The `SuaveExecutionBackend` is responsible for exposing the APIs that precompiles can hook into.
68 |
69 | ```go
70 | type SuaveExecutionBackend struct {
71 | ConfidentialStore ConfidentialStore
72 | ConfidentialEthBackend suave.ConfidentialEthBackend
73 | }
74 | ```
75 |
76 | #### Confidential Data Store APIs
77 |
78 | For more information on the capabilities exposed by the Confidential Data Store, see its related [🔗 spec](./confidential-data-store.md). The interface exposed to precompiles:
79 |
80 | ```go
81 | type ConfidentialStorageBackend interface {
82 | InitRecord(record suave.DataRecord) error
83 | Store(record suave.DataRecord, caller common.Address, key string, value []byte) (suave.DataRecord, error)
84 | Retrieve(record suave.DataRecord, caller common.Address, key string) ([]byte, error)
85 | FetchRecordByID(suave.DataId) (suave.DataRecord, error)
86 | FetchRecordsByProtocolAndBlock(blockNumber uint64, namespace string) []suave.DataRecord
87 | Stop() error
88 | }
89 | ```
90 |
91 | #### `suavex` namespace
92 |
93 | The `suavex` namespace is used internally by the MEVM to enable functionality like block building and external API calls via MEVM precompiles. We take this approach to make upstream updates and maintenance easier. Current endpoints include:
94 |
95 | `suavex_buildEthBlockFromBundles` - takes an array of bundles and transactions, calculates state root and related fields, and returns a valid Ethereum L1 block.
96 |
97 | ```go
98 | BuildEthBlockFromBundles(ctx context.Context, buildArgs *types.BuildBlockArgs, bundles []types.SBundle) (*engine.ExecutionPayloadEnvelope, error)
99 | ```
100 |
101 | `suavex_buildEthBlock` - takes an array of transactions, calculates state root and related fields, and returns a valid Ethereum L1 block.
102 |
103 | ```go
104 | BuildEthBlock(ctx context.Context, buildArgs *types.BuildBlockArgs, txs types.Transactions) (*engine.ExecutionPayloadEnvelope, error)
105 | ```
106 |
107 | Domain specific services which seek to be used by SUAVE must implement the methods in this namespace. More details will be expanded in future iterations.
108 |
109 |
110 | ## Precompile Call Authorization
111 | `checkIsPrecompileCallAllowed` implements the access control functionality. It validates whether a precompile and associated callers are authorized to access specific data. Key security functionality is as follows:
112 |
113 | 1. **Universal Access**: If a `ConfidentialComputeRequest` allows "any peeker", the function searches the `CallerStack` for a caller different from the precompile, granting access upon finding one.
114 |
115 | 2. **Restricted Access and Validation**:
116 | - The function checks if the precompile is explicitly authorized to access the data record.
117 | - It then validates each caller in the `CallerStack` against the `AllowedPeekers` list. If an authorized caller is found, access is granted.
118 |
119 | 3. **Error Handling**:
120 | - Access is denied, with an error returned, if no authorized caller is found or if the precompile lacks authorization and is not a special case (like confStore addresses).
121 |
122 |
123 | ## Security and Confidentiality
124 |
125 | `checkIsPrecompileCallAllowed` ensures that either the precompile or one of its callers must be authorized for access, enhancing security by strict validation of permissions. This approach is necessary for maintaining data integrity and preventing unauthorized access, but ultimately not entirely sufficient for total confidentiality. Future iterations will delve deeper into encryption methodologies, access controls, and auditing mechanisms to fortify data privacy further, as well as Trusted Execution Environment to ensure access control is maintained.
126 |
--------------------------------------------------------------------------------
/specs/toliman/precompiles.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Precompiles
3 | description: Precompile are MEVM contracts that are implemented in native code instead of bytecode.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/toliman/precompiles.md"
5 | ---
6 |
7 |
8 | # Precompiles
9 |
10 |
11 |
12 |
13 | - [Overview](#overview)
14 | - [Available Precompiles](#available-precompiles)
15 | - [`IsConfidential`](#isconfidential)
16 | - [`buildEthBlock`](#buildEthBlock)
17 | - [`buildEthBlockTo`](#buildEthBlockTo)
18 | - [`confidentialInputs`](#confidentialInputs)
19 | - [`confidentialRetrieve`](#confidentialRetrieve)
20 | - [`confidentialStore`](#confidentialStore)
21 | - [`contextGet`](#contextGet)
22 | - [`doHTTPRequest`](#doHTTPRequest)
23 | - [`ethcall`](#ethcall)
24 | - [`extractHint`](#extractHint)
25 | - [`fetchDataRecords`](#fetchDataRecords)
26 | - [`fillMevShareBundle`](#fillMevShareBundle)
27 | - [`newBuilder`](#newBuilder)
28 | - [`newDataRecord`](#newDataRecord)
29 | - [`privateKeyGen`](#privateKeyGen)
30 | - [`randomBytes`](#randomBytes)
31 | - [`signEthTransaction`](#signEthTransaction)
32 | - [`signMessage`](#signMessage)
33 | - [`simulateBundle`](#simulateBundle)
34 | - [`simulateTransaction`](#simulateTransaction)
35 | - [`submitBundleJsonRPC`](#submitBundleJsonRPC)
36 | - [`submitEthBlockToRelay`](#submitEthBlockToRelay)
37 | - [Precompiles Governance](#precompiles-governance)
38 |
39 | ---
40 |
41 | ## Overview
42 |
43 |
44 |
45 | Precompile are MEVM contracts that are implemented in native code instead of bytecode. Precompiles additionally can communicate with internal APIs. Currently the MEVM supports all existing Ethereum Precompiles up to Dencun, and introduces four new classes of precompiles:
46 |
47 | 1. offchain computation that is too expensive in solidity
48 | 2. calls to API methods to interact with the Confidential Data Store
49 | 3. calls to `suavex` API Methods to interact with Domain-Specific Services
50 | 4. calls to retrieve context for the confidential compute requests
51 |
52 | ## Available Precompiles
53 |
54 | A list of available precompiles in Toliman are as follows:
55 |
56 | ### `IsConfidential`
57 |
58 | Address: `0x0000000000000000000000000000000042010000`
59 |
60 | Determines if the current execution mode is regular (onchain) or confidential. Outputs a boolean value.
61 |
62 | ```solidity
63 | function isConfidential() internal view returns (bool b)
64 | ```
65 |
66 | ### `buildEthBlock`
67 |
68 | Address: `0x0000000000000000000000000000000042100001`
69 |
70 | Constructs an Ethereum block based on the provided data records. No blobs are returned.
71 |
72 | ```solidity
73 | function buildEthBlock(BuildBlockArgs memory blockArgs, DataId dataId, string memory relayUrl) internal view returns (bytes memory, bytes memory)
74 | ```
75 |
76 | Inputs:
77 |
78 | - `blockArgs` (BuildBlockArgs): Arguments to build the block
79 | - `dataId` (DataId): ID of the data record with mev-share bundle data
80 | - `relayUrl` (string): If specified the built block will be submitted to the relay
81 |
82 | Outputs:
83 |
84 | - `blockBid` (bytes): Block Bid encoded in JSON
85 | - `executionPayload` (bytes): Execution payload encoded in JSON
86 |
87 | ### `buildEthBlockTo`
88 |
89 | Address: `0x0000000000000000000000000000000042100006`
90 |
91 | Constructs an Ethereum block based on the provided data records. No blobs are returned.
92 |
93 | ```solidity
94 | function buildEthBlockTo(string memory executionNodeURL, BuildBlockArgs memory blockArgs, DataId dataId, string memory relayUrl) internal view returns (bytes memory, bytes memory)
95 | ```
96 |
97 | Inputs:
98 |
99 | - `executionNodeURL` (string): URL (or service name) of the execution node
100 | - `blockArgs` (BuildBlockArgs): Arguments to build the block
101 | - `dataId` (DataId): ID of the data record with mev-share bundle data
102 | - `relayUrl` (string): If specified the built block will be submitted to the relay
103 |
104 | Outputs:
105 |
106 | - `blockBid` (bytes): Block Bid encoded in JSON
107 | - `executionPayload` (bytes): Execution payload encoded in JSON
108 |
109 | ### `confidentialInputs`
110 |
111 | Address: `0x0000000000000000000000000000000042010001`
112 |
113 | Provides the confidential inputs associated with a confidential computation request. Outputs are in bytes format.
114 |
115 | ```solidity
116 | function confidentialInputs() internal view returns (bytes memory)
117 | ```
118 |
119 | Outputs:
120 |
121 | - `confindentialData` (bytes): Confidential inputs
122 |
123 | ### `confidentialRetrieve`
124 |
125 | Address: `0x0000000000000000000000000000000042020001`
126 |
127 | Retrieves data from the confidential store. Also mandates the caller's presence in the `AllowedPeekers` list.
128 |
129 | ```solidity
130 | function confidentialRetrieve(DataId dataId, string memory key) internal view returns (bytes memory)
131 | ```
132 |
133 | Inputs:
134 |
135 | - `dataId` (DataId): ID of the data record to retrieve
136 | - `key` (string): Key slot of the data to retrieve
137 |
138 | Outputs:
139 |
140 | - `value` (bytes): Value of the data
141 |
142 | ### `confidentialStore`
143 |
144 | Address: `0x0000000000000000000000000000000042020000`
145 |
146 | Stores data in the confidential store. Requires the caller to be part of the `AllowedPeekers` for the associated data record.
147 |
148 | ```solidity
149 | function confidentialStore(DataId dataId, string memory key, bytes memory value) internal view returns ()
150 | ```
151 |
152 | Inputs:
153 |
154 | - `dataId` (DataId): ID of the data record to store
155 | - `key` (string): Key slot of the data to store
156 | - `value` (bytes): Value of the data to store
157 |
158 | ### `contextGet`
159 |
160 | Address: `0x0000000000000000000000000000000053300003`
161 |
162 | Retrieves a value from the context
163 |
164 | ```solidity
165 | function contextGet(string memory key) internal view returns (bytes memory)
166 | ```
167 |
168 | Inputs:
169 |
170 | - `key` (string): Key of the value to retrieve
171 |
172 | Outputs:
173 |
174 | - `value` (bytes): Value of the key
175 |
176 | ### `doHTTPRequest`
177 |
178 | Address: `0x0000000000000000000000000000000043200002`
179 |
180 | Performs an HTTP request and returns the response. `request` is the request to perform.
181 |
182 | ```solidity
183 | function doHTTPRequest(HttpRequest memory request) internal view returns (bytes memory)
184 | ```
185 |
186 | Inputs:
187 |
188 | - `request` (HttpRequest): Request to perform
189 |
190 | Outputs:
191 |
192 | - `httpResponse` (bytes): Body of the response
193 |
194 | ### `ethcall`
195 |
196 | Address: `0x0000000000000000000000000000000042100003`
197 |
198 | Uses the `eth_call` JSON RPC method to let you simulate a function call and return the response.
199 |
200 | ```solidity
201 | function ethcall(address contractAddr, bytes memory input1) internal view returns (bytes memory)
202 | ```
203 |
204 | Inputs:
205 |
206 | - `contractAddr` (address): Address of the contract to call
207 | - `input1` (bytes): Data to send to the contract
208 |
209 | Outputs:
210 |
211 | - `callOutput` (bytes): Output of the contract call
212 |
213 | ### `extractHint`
214 |
215 | Address: `0x0000000000000000000000000000000042100037`
216 |
217 | Interprets the bundle data and extracts hints, such as the `To` address and calldata.
218 |
219 | ```solidity
220 | function extractHint(bytes memory bundleData) internal view returns (bytes memory)
221 | ```
222 |
223 | Inputs:
224 |
225 | - `bundleData` (bytes): Bundle object encoded in JSON
226 |
227 | Outputs:
228 |
229 | - `hints` (bytes): List of hints encoded in JSON
230 |
231 | ### `fetchDataRecords`
232 |
233 | Address: `0x0000000000000000000000000000000042030001`
234 |
235 | Retrieves all data records correlating with a specified decryption condition and namespace
236 |
237 | ```solidity
238 | function fetchDataRecords(uint64 cond, string memory namespace) internal view returns (DataRecord[] memory)
239 | ```
240 |
241 | Inputs:
242 |
243 | - `cond` (uint64): Filter for the decryption condition
244 | - `namespace` (string): Filter for the namespace of the data records
245 |
246 | Outputs:
247 |
248 | - `dataRecords` (DataRecord[]): List of data records that match the filter
249 |
250 | ### `fillMevShareBundle`
251 |
252 | Address: `0x0000000000000000000000000000000043200001`
253 |
254 | Joins the user's transaction and with the backrun, and returns encoded mev-share bundle. The bundle is ready to be sent via `SubmitBundleJsonRPC`.
255 |
256 | ```solidity
257 | function fillMevShareBundle(DataId dataId) internal view returns (bytes memory)
258 | ```
259 |
260 | Inputs:
261 |
262 | - `dataId` (DataId): ID of the data record with mev-share bundle data
263 |
264 | Outputs:
265 |
266 | - `encodedBundle` (bytes): Mev-Share bundle encoded in JSON
267 |
268 | ### `newBuilder`
269 |
270 | Address: `0x0000000000000000000000000000000053200001`
271 |
272 | Initializes a new remote builder session
273 |
274 | ```solidity
275 | function newBuilder() internal view returns (string memory)
276 | ```
277 |
278 | Outputs:
279 |
280 | - `sessionid` (string): ID of the remote builder session
281 |
282 | ### `newDataRecord`
283 |
284 | Address: `0x0000000000000000000000000000000042030000`
285 |
286 | Initializes data records within the ConfidentialStore. Prior to storing data, all data records should undergo initialization via this precompile.
287 |
288 | ```solidity
289 | function newDataRecord(uint64 decryptionCondition, address[] memory allowedPeekers, address[] memory allowedStores, string memory dataType) internal view returns (DataRecord memory)
290 | ```
291 |
292 | Inputs:
293 |
294 | - `decryptionCondition` (uint64): Up to which block this data record is valid. Used during `fillMevShareBundle` precompie.
295 | - `allowedPeekers` (address[]): Addresses which can get data
296 | - `allowedStores` (address[]): Addresses can set data
297 | - `dataType` (string): Namespace of the data
298 |
299 | Outputs:
300 |
301 | - `dataRecord` (DataRecord): Data record that was created
302 |
303 | ### `privateKeyGen`
304 |
305 | Address: `0x0000000000000000000000000000000053200003`
306 |
307 | Generates a private key in ECDA secp256k1 format
308 |
309 | ```solidity
310 | function privateKeyGen(CryptoSignature crypto) internal view returns (string memory)
311 | ```
312 |
313 | Inputs:
314 |
315 | - `crypto` (CryptoSignature): Type of the private key to generate
316 |
317 | Outputs:
318 |
319 | - `privateKey` (string): Hex encoded string of the ECDSA private key. Exactly as a signMessage precompile wants.
320 |
321 | ### `randomBytes`
322 |
323 | Address: `0x000000000000000000000000000000007770000b`
324 |
325 | Generates a number of random bytes, given by the argument numBytes.
326 |
327 | ```solidity
328 | function randomBytes(uint8 numBytes) internal view returns (bytes memory)
329 | ```
330 |
331 | Inputs:
332 |
333 | - `numBytes` (uint8): Number of random bytes to generate
334 |
335 | Outputs:
336 |
337 | - `value` (bytes): Randomly-generated bytes
338 |
339 | ### `signEthTransaction`
340 |
341 | Address: `0x0000000000000000000000000000000040100001`
342 |
343 | Signs an Ethereum Transaction, 1559 or Legacy, and returns raw signed transaction bytes. `txn` is binary encoding of the transaction.
344 |
345 | ```solidity
346 | function signEthTransaction(bytes memory txn, string memory chainId, string memory signingKey) internal view returns (bytes memory)
347 | ```
348 |
349 | Inputs:
350 |
351 | - `txn` (bytes): Transaction to sign (RLP encoded)
352 | - `chainId` (string): Id of the chain to sign for (hex encoded, with 0x prefix)
353 | - `signingKey` (string): Hex encoded string of the ECDSA private key (without 0x prefix)
354 |
355 | Outputs:
356 |
357 | - `signedTxn` (bytes): Signed transaction encoded in RLP
358 |
359 | ### `signMessage`
360 |
361 | Address: `0x0000000000000000000000000000000040100003`
362 |
363 | Signs a message and returns the signature.
364 |
365 | ```solidity
366 | function signMessage(bytes memory digest, CryptoSignature crypto, string memory signingKey) internal view returns (bytes memory)
367 | ```
368 |
369 | Inputs:
370 |
371 | - `digest` (bytes): Message to sign
372 | - `crypto` (CryptoSignature): Type of the private key to generate
373 | - `signingKey` (string): Hex encoded string of the ECDSA private key
374 |
375 | Outputs:
376 |
377 | - `signature` (bytes): Signature of the message with the private key
378 |
379 | ### `simulateBundle`
380 |
381 | Address: `0x0000000000000000000000000000000042100000`
382 |
383 | Performs a simulation of the bundle by building a block that includes it.
384 |
385 | ```solidity
386 | function simulateBundle(bytes memory bundleData) internal view returns (uint64)
387 | ```
388 |
389 | Inputs:
390 |
391 | - `bundleData` (bytes): Bundle encoded in JSON
392 |
393 | Outputs:
394 |
395 | - `effectiveGasPrice` (uint64): Effective Gas Price of the resultant block
396 |
397 | ### `simulateTransaction`
398 |
399 | Address: `0x0000000000000000000000000000000053200002`
400 |
401 | Simulates a transaction on a remote builder session
402 |
403 | ```solidity
404 | function simulateTransaction(string memory sessionid, bytes memory txn) internal view returns (SimulateTransactionResult memory)
405 | ```
406 |
407 | Inputs:
408 |
409 | - `sessionid` (string): ID of the remote builder session
410 | - `txn` (bytes): Txn to simulate encoded in RLP
411 |
412 | Outputs:
413 |
414 | - `simulationResult` (SimulateTransactionResult): Result of the simulation
415 |
416 | ### `submitBundleJsonRPC`
417 |
418 | Address: `0x0000000000000000000000000000000043000001`
419 |
420 | Submits bytes as JSONRPC message to the specified URL with the specified method. As this call is intended for bundles, it also signs the params and adds `X-Flashbots-Signature` header, as usual with bundles. Regular eth bundles don't need any processing to be sent.
421 |
422 | ```solidity
423 | function submitBundleJsonRPC(string memory url, string memory method, bytes memory params) internal view returns (bytes memory)
424 | ```
425 |
426 | Inputs:
427 |
428 | - `url` (string): URL to send the request to
429 | - `method` (string): JSONRPC method to call
430 | - `params` (bytes): JSONRPC input params encoded in RLP
431 |
432 | Outputs:
433 |
434 | - `errorMessage` (bytes): Error message if any
435 |
436 | ### `submitEthBlockToRelay`
437 |
438 | Address: `0x0000000000000000000000000000000042100002`
439 |
440 | Submits a given builderBid to a mev-boost relay.
441 |
442 | ```solidity
443 | function submitEthBlockToRelay(string memory relayUrl, bytes memory builderBid) internal view returns (bytes memory)
444 | ```
445 |
446 | Inputs:
447 |
448 | - `relayUrl` (string): URL of the relay to submit to
449 | - `builderBid` (bytes): Block bid to submit encoded in JSON
450 |
451 | Outputs:
452 |
453 | - `blockBid` (bytes): Error message if any
454 |
455 | ## Precompiles Governance
456 |
457 | The governance process for adding precompiles is in it's early stages but is as follows:
458 |
459 | - Discuss the idea in a [forum post](https://collective.flashbots.net/c/suave/27)
460 | - Open a PR and provide implementation
461 | - Feedback and review
462 | - Possibly merge and deploy in the next network upgrade, or sooner, depending on the precompile
--------------------------------------------------------------------------------
/specs/toliman/suave-chain.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Suave Chain
3 | description: The primary purpose of the SUAVE chain is to reach (and maintain) consensus about smart contract code for SUAPPs, as well as be a global information leak broadcast system.
4 | custom_edit_url: "https://github.com/flashbots/suave-specs/edit/main/specs/toliman/suave-chain.md"
5 | ---
6 |
7 |
8 |
9 | # Suave Chain
10 |
11 |
12 |
13 | **Table of Contents**
14 |
15 |
16 |
17 | - [Overview](#overview)
18 | - [Configuration](#configuration)
19 | - [Network Parameters](#network-parameters)
20 | - [Genesis Settings](#genesis-settings)
21 | - [Consensus Mechanism: Proof-of-Authority (Clique)](#consensus-mechanism-proof-of-authority-clique)
22 | - [Geth Version](#geth-version)
23 | - [Suave Transaction](#suave-transaction)
24 | - [Suave Transaction Types](#suave-transaction-types)
25 | - [TransactionRequest Serialization \& Signing](#transactionrequest-serialization--signing)
26 | - [Node Requirements and Setup](#node-requirements-and-setup)
27 | - [Gas and Transaction Fees](#gas-and-transaction-fees)
28 | - [Security Considerations](#security-considerations)
29 |
30 |
31 |
32 | ---
33 |
34 | ## Overview
35 |
36 |
37 |
38 | This document outlines the specifications for the SUAVE Toliman chain.
39 |
40 | In the context of the SUAVE protocol, the primary purpose of the SUAVE chain is to reach (and maintain) consensus about smart contract code for use cases such as order flow auctions, solvers, block builders, etc. Additionally, the SUAVE chain can also be used to store and broadcast data for better censorship guarantees.
41 |
42 | In the initial phases of development, the SUAVE chain runs a proof-of-authority consensus protocol called Clique, over a network of permissioned nodes. We do so to experiment and iterate quickly during protocol development. This will change in later testnets.
43 |
44 | ## Configuration
45 |
46 | ### Network Parameters
47 |
48 | - **Chain ID**: `33626250`
49 |
50 | ### Genesis Settings
51 |
52 | | Name | Value | Unit |
53 | | ---------------- | -------- | -------- |
54 | | `PERIOD` | 4 | `block` |
55 | | `EPOCH` | 30000 | `block` |
56 | | `BLOCK_TIME` | 3 | `second` |
57 | | `GAS_LIMIT` | 30000000 | `gas` |
58 | | `NUM_VALIDATORS` | 5 | Nodes |
59 |
60 |
61 | ## Consensus Mechanism: Proof-of-Authority (Clique)
62 |
63 | Clique, an Ethereum-based Proof-of-Authority consensus protocol defined [here](https://eips.ethereum.org/EIPS/eip-225#:~:text=A%20PoA%20scheme%20is%20based,the%20list%20of%20trusted%20signers), restricts block minting to a predefined list of trusted signers. Because of this, every block header a client sees can be checked against the list of trusted signers.
64 |
65 |
66 | ### Geth Version
67 |
68 | Suave-geth is based on geth v1.12.0 ([`e501b3`](https://github.com/flashbots/suave-geth/commit/e501b3b05db8e169f67dc78b7b59bc352b3c638d)).
69 |
70 | ---
71 |
72 | ## Suave Transaction
73 |
74 | The SUAVE protocol adds a new transaction type to the base Ethereum protocol called a `SuaveTransaction`. The purpose of this new transaction type is to process fees for offchain computation and to support the new data primitives associated with confidential compute.
75 |
76 | Blocks on the SUAVE chain consist of lists of SUAVE transactions. This new transaction type facilitates and captures key information involved in Confidential Compute Requests and their subsequent results. Any `ConfidentialComputeRequest`, signed by the user, specifies an `KettleAddress`. SUAVE transactions are valid if and only if they are signed by the `KettleAddress` specified by the user in the original `ConfidentialComputeRequest`, which is included as the `ConfidentialComputeRecord`.
77 |
78 | ```go
79 | type SuaveTransaction struct {
80 | ConfidentialComputeRequest ConfidentialComputeRecord
81 | ConfidentialComputeResult []byte
82 |
83 | // Kettle's signature
84 | ChainID *big.Int
85 | V *big.Int
86 | R *big.Int
87 | S *big.Int
88 | }
89 | ```
90 |
91 | ### Suave Transaction Types
92 |
93 | `SuaveTransaction` is the primary transaction type which is returned when requesting transactions from endpoints like `eth_getTransactionByHash` or `eth_getBlockByNumber`, but SUAVE introduces two other important message types: `ConfidentialComputeRequest` and `ConfidentialComputeRecord`. All new types are detailed in the following table:
94 |
95 | | Name | EIP-2718 Tx Type | Description |
96 | | -------------------------- | ---------------- | --------------------------------------------------------------------------------------- |
97 | | SuaveTransaction | `0x50` | SUAVE transaction; product of executed ConfidentialComputeRequest |
98 | | ConfidentialComputeRequest | `0x43` | Sent by users to interact with SUAVE smart contracts using confidential inputs |
99 | | ConfidentialComputeRecord | `0x42` | Artifact of ConfidentialComputeRequest; represents record that is stored on SUAVE chain |
100 |
101 | ## TransactionRequest Serialization & Signing
102 |
103 | Messages sent by users of SUAVE can take on two forms:
104 | 1. Standard (legacy) Ethereum transaction
105 | 2. `ConfidentialComputeRequest`
106 |
107 | Standard transactions are used to transfer SUAVE-ETH and deploy smart contracts to SUAVE chain. ConfidentialComputeRequests are a new [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) message type, used to interact with SUAVE smart contracts. Note that 'ConfidentialComputeRequests' are **not** classified as 'transactions' since 'transaction' implies changes to the state of a database/blockchain. Kettles do not provide persistent storage guarantees and are instead intended to convert inputs to outputs (like transactions targeted at blockchains).
108 |
109 | All transactions are encoded with the [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) RLP-encoding scheme (with [EIP-2930](https://eips.ethereum.org/EIPS/eip-2930) allowed), but `ConfidentialComputeRequest` takes on a special signature scheme that deviates slightly from the traditional method.
110 |
111 | 
112 |
113 | ConfidentialComputeRequests adopt this unique signing scheme to keep `confidentialInputs` off-chain. The ConfidentialComputeRecord, which is signed by the sender, contains only the _hash_ of `confidentialInputs`. This record is stored on the SUAVE chain, making verification of `confidentialInputs` possible without exposing the actual data on-chain.
114 |
115 | In javascript, a `ConfidentialComputeRequest` has the following structure:
116 |
117 | ```js
118 | const cRequest = {
119 | confidentialInputs: '0x000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000fd7b22626c6f636b4e756d626572223a22307830222c22747873223a5b2230786638363538303064383235323038393461646263653931303332643333396338336463653834316336346566643261393232383165653664383230336538383038343032303131386164613038376337386234353663653762343234386237313565353164326465656236343031363032343832333735663130663037396663666637373934383830653731613035373366336364343133396437323037643165316235623263323365353438623061316361336533373034343739656334653939316362356130623661323930225d2c2270657263656e74223a31307d000000',
120 | kettleAddress: '0xb5feafbdd752ad52afb7e1bd2e40432a485bbb7f',
121 | to: '0x8f21Fdd6B4f4CacD33151777A46c122797c8BF17',
122 | gasPrice: 10000000000n,
123 | gas: 420000n,
124 | type: '0x43',
125 | chainId: 16813125,
126 | data: '0x236eb5a70000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000010000000000000000000000008f21fdd6b4f4cacd33151777a46c122797c8bf170000000000000000000000000000000000000000000000000000000000000000',
127 | }
128 | ```
129 |
130 | Note: new fields: `confidentialInputs` and `kettleAddress`.
131 |
132 | To serialize, sign, and send this request, the client must first RLP-encode the request as a `ConfidentialComputeRecord` and sign its hash.
133 |
134 | Note: the following is pseudo-code. `rlp`, `keccak256`, and `wallet.sign` implementations may differ.
135 |
136 | ```js
137 | const {
138 | nonce,
139 | gasPrice,
140 | gas,
141 | to,
142 | value,
143 | data,
144 | kettleAddress,
145 | confidentialInputs,
146 | chainId,
147 | } = cRequest
148 | const rlpRecord = rlp('0x42', [
149 | kettleAddress,
150 | keccak256(confidentialInputs),
151 | nonce,
152 | gasPrice,
153 | gas,
154 | to,
155 | value,
156 | data,
157 | ])
158 | const {v, r, s} = wallet.sign(keccak256(rlpRecord))
159 | cRecord = {...cRecord, v, r, s}
160 | ```
161 |
162 | Then, the final request is re-encoded with RLP as follows:
163 |
164 | ```js
165 | // assume (v, r, s) have been added to cRecord
166 | const tx = rlp('0x43', [
167 | cRecord.nonce,
168 | cRecord.gasPrice,
169 | cRecord.gas,
170 | cRecord.to,
171 | cRecord.value,
172 | cRecord.data,
173 | cRecord.kettleAddress,
174 | keccak256(cRequest.confidentialInputs),
175 | cRecord.chainId,
176 | cRecord.v === 27n ? '0x' : '0x1', // yParity
177 | cRecord.r,
178 | cRecord.s,
179 | ],
180 | confidentialInputs
181 | )
182 | ```
183 |
184 | This is then sent to SUAVE via `eth_sendRawTransaction`:
185 |
186 | ```js
187 | wallet.request('eth_sendRawTransaction', [tx])
188 | ```
189 |
190 | ## Node Requirements and Setup
191 |
192 | - **Hardware**:
193 | - Minimum 8GB RAM, four cores, 50GB SSD (How big do we expect the chain to grow?)
194 | - These requirements will eventually incorporate Trusted Execution Environments (TEEs).
195 | - **Software**: [suave-geth](https://github.com/flashbots/suave-geth/)
196 | - **Setup Steps**:
197 | 1. Clone suave-geth
198 | 2. Start the devnet: `make devnet-up`
199 | 3. Create transactions: `go run suave/devenv/cmd/main.go`
200 |
201 | ---
202 |
203 | ## Gas and Transaction Fees
204 |
205 | The SUAVE chain employs the same gas pricing mechanism as Ethereum pre-Cancun hardfork (no blob transactions) where gas prices adjust based on network demand. Nodes currently track Confidential Compute Request gas usage but only charge a small flat fee for it, and there is no cap for offchain compute.
206 |
207 | Currently, SUAVE transactions can only be expressed as Legacy transaction types, but they will get converted into EIP-1559 base fee model under the hood.
208 |
209 | ---
210 |
211 | ## Security Considerations
212 |
213 | - **Security Risk**: The protocol is unaudited. The protocol currently does not make any guarantees about the confidentiality of data in the network outside of a best effort.
214 | - **DoS Risk**: Nodes have not yet been reviewed, and there may be DoS vectors at this early stage.
215 | - **Secure Key Management**: Storing private keys on Suave is experimental and should be considered insecure.
216 |
217 | If you find a security vulnerability in SUAVE, please email us at security@flashbots.net.
218 |
--------------------------------------------------------------------------------