diff --git a/docs/how-to/create-contracts/deploy-custom.mdx b/docs/how-to/create-contracts/deploy-custom.mdx index a3f26dda..86d83c39 100644 --- a/docs/how-to/create-contracts/deploy-custom.mdx +++ b/docs/how-to/create-contracts/deploy-custom.mdx @@ -22,14 +22,14 @@ This focus of this first guide **how to to deploy custom contracts**. The follow We have a number of example contracts already written in [`suave/sol/standard_peekers`](https://github.com/flashbots/suave-geth/tree/main/suave/sol/standard_peekers) to give you inspiration. -Create a new file in that directory called `test.sol`: +Create a new file in that directory called `OnlyConfidential.sol`: ```solidity pragma solidity ^0.8.8; import "../libraries/Suave.sol"; -contract onlyConfidential { +contract OnlyConfidential { event SimResultEvent( uint64 egp @@ -45,7 +45,7 @@ contract onlyConfidential { // note: because of confidential execution, // you will not see your input as input to the function - function helloWorld() external view { + function helloWorld() external { // 0. ensure confidential execution require(Suave.isConfidential()); @@ -73,29 +73,21 @@ This contract uses three new [precompiles](/technical/specs/rigil/precompiles): There are currently 3 steps required to deploy a custom contract. This will change! -1. Use Remix or your other favourite tool to generate the abi and bytecode, then paste this into the `suave/artifacts` folder. -2. Extend the `suave/e2e/contracts.go` file with the name and location of your contract, ABI, and bytecode. -3. Edit the [contract deployment code](/how-to/send-transactions#2-deploy-a-contract) from the previous guide. +1. Generate the necessary artifacts. This can be done by running: -Using the contract above as an example, create a new folder called `test.sol` in the `suave/artifacts` directory. Create a file in you new folder called `onlyConfidential.json` and structure it like this: - -```json -{ - "abi": [""], - "deployedBytecode": "", - "bytecode": "" -} +```bash +suave/scripts/contracts.sh build ``` -Extend `suave/e2e/contracts.go` by adding to the `var` block which declares all the contracts: +2. Extend the `suave/e2e/contracts.go` by adding to the `var` block which declares all the contracts: ```go -OnlyConfidentialContract = newArtifact("test.sol/onlyConfidential.json") +OnlyConfidentialContract = newArtifact("OnlyConfidential.sol/OnlyConfidential.json") ``` > **Make sure to capitalize `OnlyConfidentialContract` so that it is exported from this file.** -Edit [`suave/devenv/cmd/deploy.go`](/how-to/send-transactions#2-deploy-a-contract) from the previous guide to look like this: +3. Edit the [contract deployment code](/how-to/send-transactions#2-deploy-a-contract) from the previous guide to look like this: ```go package main diff --git a/docs/how-to/create-contracts/ofa.mdx b/docs/how-to/create-contracts/ofa.mdx index e7e03292..4ce7830f 100644 --- a/docs/how-to/create-contracts/ofa.mdx +++ b/docs/how-to/create-contracts/ofa.mdx @@ -43,8 +43,8 @@ Suave.Bid memory bid = Suave.newBid( bidAllowedStores, "mevshare:v0:unmatchedBundles" ); -Suave.confidentialStore(bid.id, "mevshare:v0:ethBundles", bundleData); -Suave.confidentialStore(bid.id, "mevshare:v0:ethBundleSimResults", abi.encode(egp)); +Suave.confidentialStoreStore(bid.id, "mevshare:v0:ethBundles", bundleData); +Suave.confidentialStoreStore(bid.id, "mevshare:v0:ethBundleSimResults", abi.encode(egp)); ``` The term "bid" is an artefact of earlier versions of suave-geth. Here, it is a general data identifier used when operating on confidential data. @@ -56,19 +56,19 @@ Any searcher can listen for these events and use them to try and match backrun t When the confidential compute request comes from a searcher looking to backrun a transaction (using the `newMatch` function), the MEV-Share SUAPP also merges the bids involved and stores those merged bids: ```solidity -Suave.confidentialStore(bid.id, "mevshare:v0:mergedBids", abi.encode(bids)); +Suave.confidentialStoreStore(bid.id, "mevshare:v0:mergedBids", abi.encode(bids)); ``` It is the `mergedBids` values in the mevshare keyspace that the block building SUAPP (i.e. the `EthBlockBidContract`) then fetches data from when looking to create a block and send it to an offchain relay. This happens with the `confidentialRetrieve` precompile: ```solidity -Suave.confidentialRetrieve(allShareMatchBids[j].id, "mevshare:v0:mergedBids"), (Suave.BidId[]) +Suave.confidentialStoreRetrieve(allShareMatchBids[j].id, "mevshare:v0:mergedBids"), (Suave.BidId[]) ``` or when it orders the merged bids by their effective gas price: ```solidity -Suave.confidentialRetrieve(allBids[i].id, "mevshare:v0:ethBundleSimResults") +Suave.confidentialStoreRetrieve(allBids[i].id, "mevshare:v0:ethBundleSimResults") ``` [All the code is here](https://github.com/flashbots/suave-geth/blob/main/suave/sol/standard_peekers/bids.sol#L65) if you want to run it yourself and develop your own picture of the total data flow in SUAVE. diff --git a/docs/how-to/run-suave/build-yourself.mdx b/docs/how-to/run-suave/build-yourself.mdx new file mode 100644 index 00000000..ac6367a9 --- /dev/null +++ b/docs/how-to/run-suave/build-yourself.mdx @@ -0,0 +1,90 @@ +--- +title: Build SUAVE yourself +description: Start running SUAVE and participating in the chain itself +keywords: + - build + - suave + - local + - binaries +--- + +If you'd like to run the suave-geth binaries yourself, this is the guide for you. + +### What you need + +1. [Install go](https://go.dev/doc/install). + +### What to do + +1. Clone the repo and build SUAVE: +```bash +git clone https://github.com/flashbots/suave-geth.git +cd suave-geth +make suave +``` +2. Run this command: +```bash +./build/bin/suave --suave.dev +``` + +### What to do next + +In another terminal, you can run: + +```bash +go run suave/devenv/cmd/main.go +``` + +The output should be roughly similar to the below (addresses, txns, and ids will differ): + +```bash +suave-geth$ go run suave/devenv/cmd/main.go +Step 0: Create and fund test accounts +- Funded test account: 0x66d5a8D6B34329c0639071275b3d78D29e11EbC6 (100000000) +Step 1: Deploy mev-share contract +- Mev share contract deployed: 0x8f21Fdd6B4f4CacD33151777A46c122797c8BF17 +Step 2: Send bid +- Bid sent at txn: 0xb49debcdead2b306d6ab6282b88fdad7c8d6a33d87df34b79f56d141eae7c08a +- Bid id: 30bbc65298f24e67aaf5c95bf5f0686c +Step 3: Send backrun +- Backrun sent at txn: 0xcf7880e61e94aaab48c60655c321716ecab6edab752586448b0412e93a969889 +- Backrun bid id: db98b83d02694fc2b13c042ad22c233 +``` + +#### Using the console + +You can also run any familiar Geth command you like. Start by generating a new account: + +```bash +./build/bin/suave --suave account new +``` + +If the `--datadir` flag is not set, a geth client stores data in the `$HOME/.ethereum` directory. Depending on the chain you use, it creates a subdirectory. For example, if you run Sepolia, geth creates `$HOME/.ethereum/sepolia/`. So, if you use the `--suave` flag, your data ends up in `$HOME/.ethereum/suave/...`. + +You can attach to the usual Geth javascript console to get any interactive data you need with: + +```bash +./build/bin/suave attach /tmp/geth.ipc +``` + +From within the console, you can run: + +```bash +eth.accounts[0] +``` + +Which should return `"0xb5feafbdd752ad52afb7e1bd2e40432a485bbb7f"` which is the account we unlocked when starting the MEVM. + +```bash +eth.getBalance(eth.accounts[0]) +``` + +Should return a really large number `1.1579...e+77`. If you try `eth.getBalance("")` instead, you should see `0`. + +If you try: + +```bash +web3.eth.blockNumber +``` + +It should tell you the block height of your local network. \ No newline at end of file diff --git a/docs/how-to/run-suave/index.mdx b/docs/how-to/run-suave/index.mdx new file mode 100644 index 00000000..44f117a3 --- /dev/null +++ b/docs/how-to/run-suave/index.mdx @@ -0,0 +1,26 @@ +--- +title: Run SUAVE Locally +description: Start running SUAVE and participating in the chain itself +keywords: + - build + - suave + - setup + - practice +--- + +# Run SUAVE Locally + +Our first goal is to start a "Kettle". Kettles house all components necessary to perform confidential compute and are the main protocol actor in the SUAVE protocol. + +The Rigil Testnet can be represented as below. We'll be running all the stuff within the purple square. + +![Rigil architecture](/assets/rigil-architecture.svg) + +You can read more about exactly what a Kettle contains in [architecture section of the Technical Specs](/technical/specs/rigil/#architecture). + +## Get Started + +There are two different approaches you can take to local setup: + +1. [Use Docker](/how-to/run-suave/with-docker), or +2. [Build and run the binaries yourself](/how-to/run-suave/build-yourself). \ No newline at end of file diff --git a/docs/how-to/run-suave.mdx b/docs/how-to/run-suave/with-docker.mdx similarity index 68% rename from docs/how-to/run-suave.mdx rename to docs/how-to/run-suave/with-docker.mdx index 683c5306..e79c9f1f 100644 --- a/docs/how-to/run-suave.mdx +++ b/docs/how-to/run-suave/with-docker.mdx @@ -1,20 +1,14 @@ --- -title: Run SUAVE Locally +title: Run SUAVE with Docker description: Start running SUAVE and participating in the chain itself keywords: - build - suave - - setup - - practice + - local + - docker --- -# Run SUAVE Locally - -Our goal in this guide is to get SUAVE running locally. - -You can read more about exactly what you'll be running in the [architecture section of the Technical Specs](/technical/specs/rigil/#architecture). - -## Docker +If you'd like to run SUAVE in Docker, this is the guide for you. ### What you need @@ -57,7 +51,7 @@ make devnet-up -### Optional testing +### Testing transactions 4. Test your node by deploying a contract and sending it some transactions: ```bash @@ -151,73 +145,4 @@ make devnet-down - - -## Build it yourself - -If you'd like to run the suave-geth binaries yourself, read on. - -### What you need - -1. [Install go](https://go.dev/doc/install). - -### What to do - -1. Clone the repo and build SUAVE: -```bash -git clone https://github.com/flashbots/suave-geth.git -cd suave-geth -make suave -``` -2. Run this command: -```bash -./build/bin/suave --suave.dev -``` - -### What to do next - -In another terminal, you can run: - -```bash -go run suave/devenv/cmd/main.go -``` - -The output should be roughly similar to the one printed above (addresses, txns, and ids will differ). - -You can also run any familiar Geth command you like. Start by generating a new account: - -```bash -./build/bin/suave --suave account new -``` - -If the `--datadir` flag is not set, a geth client stores data in the `$HOME/.ethereum` directory. Depending on the chain you use, it creates a subdirectory. For example, if you run Sepolia, geth creates `$HOME/.ethereum/sepolia/`. So, if you use the `--suave` flag, your data ends up in `$HOME/.ethereum/suave/...`. - -#### Using the console - -You can attach to the usual Geth javascript console to get any interactive data you need with: - -```bash -./build/bin/suave attach /tmp/geth.ipc -``` - -From within the console, you can run: - -```bash -eth.accounts[0] -``` - -Which should return `"0xb5feafbdd752ad52afb7e1bd2e40432a485bbb7f"` which is the account we unlocked when starting the MEVM. - -```bash -eth.getBalance(eth.accounts[0]) -``` - -Should return a really large number `1.1579...e+77`. If you try `eth.getBalance("")` instead, you should see `0`. - -If you try: - -```bash -web3.eth.blockNumber -``` - -It should tell you the block height of your local network. \ No newline at end of file + \ No newline at end of file diff --git a/docs/how-to/send-transactions.mdx b/docs/how-to/send-transactions.mdx index 7c92c8f9..481f3c47 100644 --- a/docs/how-to/send-transactions.mdx +++ b/docs/how-to/send-transactions.mdx @@ -34,8 +34,6 @@ Creates a new message call transaction or a contract creation for any signed `Co Executes a new message call immediately without creating a transaction on the block chain. It follows the same format as the default `eth_call` with two extra parameters: -*Parameters* - - `IsConfidential`: Set to true to execute as a confidential request and access the [`MEVM`](/technical/specs/rigil/precompiles) methods. - `ExecutionAddress`: `address` - (optional) The execution address that performs the execution. diff --git a/docs/index.mdx b/docs/index.mdx index f14a6185..dcbbc5b9 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -30,11 +30,15 @@ Here are all the key terms you'll find in these docs. The names and descriptions | --- | --- | | SUAPP | SUAVE application. For now, a smart contract that uses SUAVE precompiles. Frontend optional. | | Rigil Testnet | The current test network. Naming convention follows the stars in the Alpha Centauri system. | +| SUVE Chain | a fork of Ethereum designed to facilitate credible, confidential execution in MEV use cases. | | Kettle | The main logical actor in the SUAVE protocol. We don't call it a "node" because it's at least two nodes (and some other services) in a trenchcoat. | -| MEVM | Modified EVM, where the modifications specifically enable credible offchain computation. | +| MEVM | Modified EVM, where the modifications enable credible, confidential computation. | | Precompile | A convenient way to enable direct execution of predefined functions in the EVM, meant to enable more interesting SUAPPs. | -| Confidential Compute Request (CCR) | The initial object users send to a Kettle, via an RPC. Made up of an ordinary transaction + confidential inputs + pubkey of Kettle(s) that can decrypt it. | +| Confidential Compute Request (CCR) | A user request to Suave that contains (1) information such as `to` address and `calldata`, (2) confidential inputs, and (3) a list of SUAPPs and Kettles allowed to operate on confidential inputs. | | 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. | | SUAVE Chain | A fork of Ethereum, currently running Clique PoA consensus for rapid iteration. Main purpose is to reach (and maintain) consensus about smart contract code. | -| Confidential Data Store | A secure and privacy-focused key-value storage system. | -| Bid | An artefact from early development, which is now just a Data Identifier used when operating on confidential data. For instance, a SUAVE transaction can emit logs on chain which reference the `bidId` from a CCR without revealing the confidential inputs to that CCR. | \ No newline at end of file +| Confidential Data Store | A privacy-centric networked storage system specifically tailored to enable programmable privacy in SUAPPs. | +| Bid | An artefact from early development, which is now just a Data Identifier used when operating on confidential data. For instance, a SUAVE transaction can emit logs on chain which reference the `bidId` from a CCR without revealing the confidential inputs to that CCR. | +| Peekers | Contracts with the correct permissions - granted by users in CCRs - to get and put data in the Confidential Data Store | +| Builder solidity | solidity with access to precompiles that help facilitate the processing of transactions and intents. | +| RPC | Remote Procedure Call which, in Rigil, receives user transactions, moves confidential inputs to the Confidential Data Store, and passes CCRs to MEVM. | \ No newline at end of file diff --git a/docs/sidebars.js b/docs/sidebars.js index 2afdadcd..41d469ff 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -15,7 +15,14 @@ module.exports = { collapsed: false, link: { type: 'doc', id: 'how-to/index' }, items: [ - 'how-to/run-suave', 'how-to/send-transactions', + { + type: 'category', + label: 'Run SUAVE Locally', + link: { type: 'doc', id: 'how-to/run-suave/index' }, + items: [ + 'how-to/run-suave/with-docker', 'how-to/run-suave/build-yourself' + ] + }, 'how-to/send-transactions', { type: 'category', label: 'Create Contracts', diff --git a/docs/technical b/docs/technical index 668f4d22..a09c368b 160000 --- a/docs/technical +++ b/docs/technical @@ -1 +1 @@ -Subproject commit 668f4d22d7078ed5b2f01146e6ddd3008ed93450 +Subproject commit a09c368bea449777fd5485004afab846979ac4fd