diff --git a/README.md b/README.md index d973d9a38..a37202366 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,10 @@ Is P2P software that creates a network of execution providers and bidders. Bidders can broadcast bids to providers and receive commitments from them. A high throughput POA EVM chain settles the bids at the end of a block slot. +## Documentation + +For detailed documentation, visit the [mev-commit docs](https://docs.primev.xyz/). + ## Main Components - [mev-commit client](p2p) - [mev-commit-oracle](oracle) diff --git a/contracts/README.md b/contracts/README.md deleted file mode 100644 index 3a1d97774..000000000 --- a/contracts/README.md +++ /dev/null @@ -1,259 +0,0 @@ -# Contracts - -## Overview - -This repository contains Solidity contracts and tests for handling pre-confirmation commitments and bids. The system uses two separate registries to manage bidders and providers, where both parties must stake ETH to participate. Commitments are verified and stored in a contract. - -### PreConfCommitmentStore - -This is the core contract that handles pre-confirmation commitments. It uses EIP-712 for typed data hashing and signing. Commitments are stored in a mapping, accessible via their hash. - -#### Functions - -- `getBidHash`: Generates a hash of the bid based on the transaction hash, bid amount, and block number. -- `getPreConfHash`: Generates a hash of the pre-confirmation commitment. -- `recoverAddress`: Recovers the signer's address from a message digest and a signature. -- `verifyBid`: Verifies a bid's validity by checking the signer's stake and the bid amount. -- `storeCommitment`: Stores a valid commitment in the contract. -- - -### IBidderRegistry - -This is an interface that must be implemented by the bidder registry contract. It contains methods for registering, staking, and retrieving funds. - -#### Functions - -- `prepay`: Registers a bidder and prepays ETH. -- `getAllowance`: Checks the prepayed amount for a given bidder. -- `depositFunds`: Deposits additional funds into the contract. -- `retrieveFunds`: Retrieves a specific amount of funds for a bidder and sends them to a provider. - -### IProviderRegistry - -This is an interface that must be implemented by the provider registry contract. It contains methods for registering, depositing funds, slashing, and rewarding. - -#### Functions - -- `registerAndStake`: Registers a provider and stakes ETH. -- `checkStake`: Checks the staked amount for a given provider. -- `depositFunds`: Deposits additional funds into the contract. -- `slash`: Slashes a specific amount of staked ETH from a provider and sends it to a bidder. -- `reward`: Rewards a specific amount of ETH to a provider. - -Note: In both IProviderRegistry and IBidderRegistry - some functions are restrictied to be called exclusively by the preconfimration contract. - -### Whitelist - -To enable bridging to native ether, bridging contracts need be able to mint/burn native ether. The `Whitelist` is responsible for managing a whitelist of addresses that can mint/burn native ether. An admin account must be specified on deployment, who is the only address that can mutate the whitelist. - -#### Functions - -- `addToWhitelist`: allows only the admin to add an address to the whitelist. -- `removeFromWhitelist`: allows only the admin to remove an address from the whitelist. -- `isWhitelisted`: returns boolean indicating if an address is whitelisted. -- `mint`: allows whitelisted addresses to mint specific amount of native ether to any account. -- `burn`: allows whitelisted addresses to burn specific amount of native ether from any account. - -## Tests - -The tests in this repository perform the following: - -- Deployment of the `ProviderRegistry`, `BidderRegistry`, and `Whitelist` contracts. -- Registration and staking of bidders and providers. -- Verification of bid hashes and pre-confirmation commitment hashes. -- Recovery of signer addresses. -- Storage of valid commitments. -- Tests basic whitelisting functionality. - -To run the tests, use the following command: - -```bash -npx hardhat test -``` - -## Flow of Actors - -```mermaid -sequenceDiagram - participant Bidder - participant Provider - participant PreConf - participant BidderRegistry - participant ProviderRegistry - participant Oracle - - Bidder->>BidderRegistry: registerAndStake() - activate BidderRegistry - BidderRegistry-->>Bidder: BidderRegistered event - deactivate BidderRegistry - - Provider->>ProviderRegistry: registerAndStake() - activate ProviderRegistry - ProviderRegistry-->>Provider: ProviderRegistered event - deactivate ProviderRegistry - - Provider->>PreConf: storeCommitment() - activate PreConf - PreConf->>ProviderRegistry: checkStake(Provider) - activate ProviderRegistry - ProviderRegistry-->>PreConf: stake - deactivate ProviderRegistry - - PreConf->>BidderRegistry: checkStake(Bidder) - activate BidderRegistry - BidderRegistry-->>PreConf: stake - deactivate BidderRegistry - - PreConf->>PreConf: verifyBidAndCommitment() - PreConf-->>Provider: SignatureVerified event - deactivate PreConf - - alt Reward Case - Oracle->>PreConf: initateReward(commitmentHash) - activate PreConf - PreConf->>BidderRegistry: retrieveFunds(Bidder, amt, Provider) - activate BidderRegistry - BidderRegistry-->>PreConf: FundsRetrieved event - deactivate BidderRegistry - - PreConf-->>Oracle: CommitmentUsed event - deactivate PreConf - - else Slashing Case - Oracle->>PreConf: initiateSlash(commitmentHash) - activate PreConf - PreConf->>ProviderRegistry: slash(amt, Provider, Bidder) - activate ProviderRegistry - ProviderRegistry-->>PreConf: FundsSlashed event - deactivate ProviderRegistry - - PreConf-->>Oracle: CommitmentUsed event - deactivate PreConf - end - -``` - -#### Deploy Scripts using hardhat - -``` -npx hardhat run scripts/deploy.js -``` - -#### Deploy Scripts using forge - -- Install foundryup - -``` -curl -L https://foundry.paradigm.xyz | bash -``` - -- Running foundryup by itself will install the latest (nightly) precompiled binaries: forge, cast, anvil and chisel -``` -foundryup -``` - -- Setup ENV Vars - -``` -export RPC_URL="http://localhost:8545/" -export PRIVATE_KEY=ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 -export CHAIN_ID=17864 -``` - -- Run the deploy script for core contracts - -``` -forge script scripts/DeployScripts.s.sol:DeployScript --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast --chain-id $CHAIN_ID -vvvv --use 0.8.20 -``` - -- Run deploy script for whitelist contract, HYP_ERC20_ADDR denotes the HypERC20.sol contract address to give native mint/burn privileges. - -``` -HYP_ERC20_ADDR=0xBe3dEF3973584FdcC1326634aF188f0d9772D57D forge script scripts/DeployScripts.s.sol:DeployWhitelist --rpc-url $RPC_URL --private-key $PRIVATE_KEY --broadcast --chain-id $CHAIN_ID -vvvv --use 0.8.20 -``` - -#### Note on CREATE2 - -Foundry scripts in this repo use the CREATE2 opcode to deploy for every contract. Meaning deployment on any chain will yield the same contract addresses, given a constant deployer account, contract bytecode, and salt. - -This means the solidity version used for contract compilation affects the addresses those contracts will be deployed to. Solidity 0.8.20 is the canonical version to use. - -It's recommended to use `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266` as the deployer account so that contract addresses will match external facing documentation. In production this address will have proper key management, for now here's the private key: `ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80`. - -The CREATE2 proxy needs to be deployed prior to these contracts. See [this repo](https://github.com/primev/deterministic-deployment-proxy), or this [make command](https://github.com/primev/mev-commit-geth/blob/d29cfe94205e852cc57a8184585ccc895d32a517/geth-poa/Makefile#L48) to deploy. Anvil automatically deploys this proxy to the expected address. - -Using the above private key and compiling with solidity 0.8.20, expected contract addresses are: - -```bash -UserRegistry deployed to: 0xe38B5a8C41f307646F395030992Aa008978E2699 -ProviderRegistry deployed to: 0x7fA45D14358B698Bd85a0a2B03720A6Fe4b566d7 -PreConfCommitmentStore deployed to: 0x8B0F623dCD54cA50CD154B3dDCbB8436E876b019 -Oracle deployed to: 0x628F330Ae673df7D73d943f9590A4d643e4197f6 -Whitelist deployed to: 0x5D1415C0973034d162F5FEcF19B50dA057057e29 -``` - -#### Test Contracts - -``` -forge test -``` - -#### Check Coverage - -``` -forge coverage -``` - -## Local Contract Deployment with Anvil - -### Prerequisites -Ensure Foundry is installed with Anvil, Cast, and Forge. - -### Steps - -1. **Start Anvil**: - Open a terminal and run Anvil to initiate a local Ethereum network simulation: - - ```bash - anvil - ``` - - Anvil will start and display a list of available accounts and their corresponding private keys, pre-funded with Ethereum for testing purposes. - -2. **Note the Private Keys**: - Anvil provides a set of accounts with their private keys. Example output: - - ``` - Available Accounts - ================== - - (0) "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266" (10000 ETH) - (1) "0x70997970C51812dc3A010C7d01b50e0d17dc79C8" (10000 ETH) - ... (more accounts) ... - - Private Keys - ================== - - (0) 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 - (1) 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d - ... (more keys) ... - ``` - -3. **Deploy Your Contract**: - Use one of the provided private keys to deploy your contract using Forge. Example command: - - ```bash - forge create PreConfCommitmentStore --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80 --constructor-args 0xD7a4B4cbA2DAb2dc3E2FCa91ea903Bf49842FD87 0xD7a4B4cbA2DAb2dc3E2FCa91ea903Bf49842FD87 0xD7a4B4cbA2DAb2dc3E2FCa91ea903Bf49842FD87 - ``` - - After executing the command, you should see an output similar to the following: - - ``` - eth_getBlockByNumber - eth_feeHistory - eth_sendRawTransaction - - Transaction: 0x0229f1adf045bfcc554f0ecff57d5a6cff05aecf222479a1a568ac840386dfff - Contract created: 0x5fbdb2315678afecb367f032d93f642f64180aa3 - Gas used: 2733597 - ``` diff --git a/oracle/README.md b/oracle/README.md deleted file mode 100644 index 5f02436b7..000000000 --- a/oracle/README.md +++ /dev/null @@ -1,63 +0,0 @@ -# Oracle -Connects to the Oracle contract to trigger rewards and slashing of commitments. - -# Running -Set the correct values in the .env file -``` -L1_URL=YOUR_INFURA_URL -INTEGREATION_TEST=YOUR_BOOLEAN_VALUE -DB_HOST=YOUR_DB_HOST -ORACLE_PASS=YOUR_DB_PASSWORD -DD_KEY=YOUR_DD_KEY -``` - -Run: -`docker compose up --build` - -## Usage - -The main utility has several flags: - -- contract: This flag is used to specify the contract address of the oracle. The default value is "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9". - -- url: This flag is used to specify the URL of the settlement layer for an RPC connection. The default value is "http://localhost:8545" to be used with anvil. - -- key: This flag is used to specify the private key through which interactions are signed. The default value is "ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80". Make sure the key is funded sufficently. - -- chainID: This flag is used to specify the chain ID of the settlement layer. The default value is 31337. TODO(@ckartik): can get from rpc connection. - -- rateLimit: The time to wait before querying 3rd party services for more data. - -These flags can be overridden by providing new values when running the program. For example: - -`go run main.go -contract=NewContractAddress -url=NewClientURL -key=NewPrivateKey -chainID=NewChainID --rateLimit=5` - - - -## Impelementation - -The core part of this service is the chain tracer, which has the following interface: -```go -type Tracer interface { - GetNextBlockNumber() (NewBlockNumber int64) - RetrieveDetails() (block *BlockDetails, BlockBuilder string, err error) -} -``` - -There are two implementations: -- MockTracer - - This is fed random data and can be changed to custom data for e2e testing -- IncrementingTracer - - This is fed data from Infura (txns in block) and PayloadsDe (builder that won) - -## Open Concerns on Oracle -- We need to have a reliable way of determining the winning builder. - -## Oracle Approach - Trade Off -The current appraoch for the Oracle microservice and on-chain components, is to feed all blocks incrementally on-chain. - -There's an alternative approach, where the Smart-contract only emits an event to request block data, in a sitution where there is a need for some block data. -- This saves on redenduant posting of blockdata, but is an optimization. -- Assuming there's at least 1 pre-confirmation per block, this would be a useless optimization. - -![Oracle Ticketing Alternative Image](./Oracle%20Ticketing%20Alternative.png) diff --git a/p2p/README.md b/p2p/README.md deleted file mode 100644 index 07eaacb6a..000000000 --- a/p2p/README.md +++ /dev/null @@ -1,169 +0,0 @@ -# mev-commit -mev-commit is P2P software that creates a network of execution providers and bidders. Bidders can broadcast bids to providers and receive commitments from them. A high throughput POA EVM chain settles the bids at the end of a block slot. - -# mev-commit software components - - [mev-commit client](https://github.com/primev/mev-commit/tree/main/p2p) - - [mev-commit-geth](https://github.com/primev/mev-commit/tree/main/external/geth) - - [contracts](https://github.com/primev/mev-commit/tree/main/contracts) - - [mev-commit-oracle](https://github.com/primev/mev-commit/tree/main/oracle) - - [mev-commit-bridge](https://github.com/primev/mev-commit/tree/main/external/geth/tree/master/geth-poa) - - curl - -# mev-commit execution requirements -- Software: mev-commit client and curl -- OS: 64-bit Linux, Mac OS X 10.14+ -- CPU: 4+ cores @ 2.8+ GHz -- Memory: 16GB+ RAM -- Network: 1 GBit/sec broadband - -![](node-architecture.png) - -## Single Line Script For Quick Experimentation -The command: -- Installs Foundry: For smart contract development and testing. -- Downloads MEV-Commit Binary: The software included in this Repo, pre-built for your platform. -- Automatic Funding and Initialization: Prepares node for participation in mev-commit network. -- Runs the node with requisite configurations to connect to our running testnet. - -### Bidder Node -```bash -curl -o launchmevcommit https://raw.githubusercontent.com/primev/scripts/main/launchmevcommit && chmod +x launchmevcommit && ./launchmevcommit --node-type bidder -``` - -### Provider Node -```bash -curl -o launchmevcommit https://raw.githubusercontent.com/primev/scripts/main/launchmevcommit && chmod +x launchmevcommit && ./launchmevcommit --node-type provider -``` - -## Quick Build (For docker please skip this instruction) - -* Install [buf](https://buf.build/docs/installation) -``` -buf generate -go build -o mev-commit ./cmd/main.go -``` - -When prompted, read the values of where the Smart-contracts where deployed on the settlement layer and update the configurations in the integrationtest/config/...yml files. - -## Quickstart -- An ECDSA private key is required to create an ethereum address for the node as well as to use for the P2P network. Bidders can add an existing key or create a new key using the `create-key` command. -``` -NAME: - mev-commit create-key - Create a new ECDSA private key and save it to a file - -USAGE: - mev-commit create-key [command options] - -OPTIONS: - --help, -h show help -``` - -- Once the key is available, create a yaml config file. Example config files are available in the [config](https://github.com/primev/mev-commit/tree/main/p2p/config) folder. The important options are defined below: -```yaml -# Path to private key file. -priv_key_file: ~/.mev-commit/keys/nodekey - -# Type of peer. Options are provider and bidder. -peer_type: provider - -# Port used for P2P traffic. If not configured, 13522 is the default. -p2p_port: 13522 - -# Port used for HTTP traffic. If not configured, 13523 is the default. -http_port: 13523 - -# Port used for RPC traffic. If not configured, 13524 is the default. -rpc_port: 13524 - -# Secret for the node. This is used to authorize the nodes. The value doesnt matter as long as it is sufficiently unique. It is signed using the private key. -secret: hello - -# Address of bidder registery -bidder_registry_contract: 0x62197Abd7672925c7606Bdf9931e42baCa6619AD - -# Address of provider registery -provider_registry_contract: 0xeA73E67c2E34C4E02A2f3c5D416F59B76e7617fC - -# Format used for the logs. Options are "text" or "json". -log_fmt: text - -# Log level. Options are "debug", "info", "warn" or "error". -log_level: debug - -# Bootnodes used for bootstrapping the network. -bootnodes: - - /ip4/35.91.118.20/tcp/13522/p2p/16Uiu2HAmAG5z3E8p7o19tEcLdGvYrJYdD1NabRDc6jmizDva5BL3 - -# The default is set to false for development reasons. Change it to true if you wish to accept bids on your provider instance -expose_provider_api: false -``` - -- Once the config file is ready, run `mev-commit start` with the config option. -``` -NAME: - mev-commit start - Start the mev-commit node - -USAGE: - mev-commit start [command options] [arguments...] - -OPTIONS: - --config value path to config file [$MEV_COMMIT_CONFIG] - --help, -h show help -``` - -- After the node is started, check the status of the peers connected to the node using the `/topology` endpoint on the HTTP port (optional). -```json -{ - "self": { - "Addresses": [ - "/ip4/127.0.0.1/tcp/13526", - "/ip4/192.168.1.103/tcp/13526", - "/ip4/192.168.100.5/tcp/18625" - ], - "Ethereum Address": "0x55B3B672DEB14178615F648911e76b7FE1B23e5D", - "Peer Type": "provider", - "Underlay": "16Uiu2HAmBykfyf9A5DnRguHNS1mvSaprzYEkjRf6uafLU4javG4L" - }, - "connected_peers": { - "providers": [ - "0xca61596ccef983eb7cae42340ec553dd89881403" - ] - } -} -``` - -## Building Docker Image - -To simplify the deployment process, you may utilize Docker to create an isolated environment to run mev-commit. - -- Build the Docker Image: - Navigate to the project root directory (where your Dockerfile is located) and run: - - ``` - docker build -t mev-commit:latest . - ``` -- Running with Docker Compose: - - If you want to just spin up the mev-commit p2p nodes, you may use: - ``` - docker-compose up --build - ``` - -- Stopping the Service: - - ``` - docker-compose down - ``` - -## APIs for Bidders & Execution Providers -[Link to Documentation on Bidder and Execution provider API](./pkg/rpc/README.md) -- This includes: - - the payload for the Bidder API - - The required setup for execution providers to process bids into commitments in their personal infra. - - - -## Settlement Layer - -This repository contains a settlement layer under the settlement/geth-poa folder. You can run the entire stack for multiple POA nodes locally from this folder. -See [here](./settlement/geth-poa/README.md#local-run) for instructions on running the Settlment Layer locally.