From 0db6511235b95c57cc513ebfc5604f5b3308a8d5 Mon Sep 17 00:00:00 2001 From: Kartik Chopra Date: Sun, 15 Oct 2023 16:51:40 -0400 Subject: [PATCH 1/4] Adds init documentation for searchers and builders. --- README.md | 3 +++ pkg/rpc/README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+) create mode 100644 pkg/rpc/README.md diff --git a/README.md b/README.md index b85ceb4c..3cf8a242 100644 --- a/README.md +++ b/README.md @@ -138,3 +138,6 @@ To simplify the deployment process, you may utilize Docker to create an isolated ``` docker-compose down ``` + +## APIs for Searcher & Builder +[Link to Documentation on Searcher and Builder API](./pkg/rpc/README.md) \ No newline at end of file diff --git a/pkg/rpc/README.md b/pkg/rpc/README.md new file mode 100644 index 00000000..880b1296 --- /dev/null +++ b/pkg/rpc/README.md @@ -0,0 +1,43 @@ +# RPC APIs + +## Overview + +There's two key RPC APIs this software provides: +- Searcher API +- Builder Internal Operations API + +## Searcher API +- This is the api that takes bids into the mev-commit node that is emulating a searcher. +- The SendBid RPC endpoint will subseqently propegate the Bid after it is signed, to the primev P2P network. + +The format for the request payload is as follows: + +```protobuf +message Bid { + string tx_hash = 1; + int64 amount = 2; + int64 block_number = 3; +}; +``` + +Which is the following in JSON Format: +```javascript +{ + "tx_hash": "", + "amount": , + "block_number": +} +``` + +The response to the searcher API is a stream of commitments, an example response is shown below: +```javascript +{ + "tx_hash": "transaction_hash15", + "amount": "1000", + "block_number": "12345", + "bid_digest": "fb77987f64d8efaa93c659e4365e60ba7b1b3013ee12b4c988e3dbd87b76109d", + "bid_signature": "65cb64450be1c83e48a3de5565c07d10b69a75c6c463af01ffb20849e777861a3fd07e1415c83f31f1e05cc7b430b4073faf988b3b0a469148e02ccba9fd6d9901", + "pre_confirmation_digest": "0f25c2d8adc489d2db535865c70a47ab7eccbbc89ca95b705547c38811712111", + "pre_confirmation_signature": "4838b53968be8a4cd4bceee9a8299885546b7d184cfe6390dcb8afd37fec3c1b08f0ce03935afce5b11b9f425434a4b22d01cb4d4dd5f4e5894c699302dbb3ad01" +} +``` From 615fbcb96a05de4afce1afddc50eb74e983d5f6f Mon Sep 17 00:00:00 2001 From: Kartik Chopra Date: Sun, 15 Oct 2023 17:37:59 -0400 Subject: [PATCH 2/4] Adds toggle for BidProcessor to be set through BuilderAPI and fixes spelling. --- README.md | 6 ++++- cmd/main.go | 36 ++++++++++++++------------ config/builder.yml | 1 + pkg/node/node.go | 30 +++++++++++---------- pkg/preconfirmation/preconfirmation.go | 6 ++--- 5 files changed, 45 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 3cf8a242..0c5f8fe2 100644 --- a/README.md +++ b/README.md @@ -116,6 +116,9 @@ To gather commitments from builders, the builder mev-node must maintain an activ ``` +By Default this service is disabled, and must be enabled by setting the BuilderAPIEmabled flag in the config file to true. + +The file is located at [./config/builder.yaml](./config/builder.yml) and the variable is set to `builder_expose_api: false` by default. ## Building Docker Image @@ -140,4 +143,5 @@ To simplify the deployment process, you may utilize Docker to create an isolated ``` ## APIs for Searcher & Builder -[Link to Documentation on Searcher and Builder API](./pkg/rpc/README.md) \ No newline at end of file +[Link to Documentation on Searcher and Builder API](./pkg/rpc/README.md) + diff --git a/cmd/main.go b/cmd/main.go index 9e8ebf14..21fecb43 100644 --- a/cmd/main.go +++ b/cmd/main.go @@ -90,15 +90,16 @@ func createKey(c *cli.Context) error { } type config struct { - PrivKeyFile string `yaml:"priv_key_file" json:"priv_key_file"` - Secret string `yaml:"secret" json:"secret"` - PeerType string `yaml:"peer_type" json:"peer_type"` - P2PPort int `yaml:"p2p_port" json:"p2p_port"` - HTTPPort int `yaml:"http_port" json:"http_port"` - RPCPort int `yaml:"rpc_port" json:"rpc_port"` - LogFmt string `yaml:"log_fmt" json:"log_fmt"` - LogLevel string `yaml:"log_level" json:"log_level"` - Bootnodes []string `yaml:"bootnodes" json:"bootnodes"` + PrivKeyFile string `yaml:"priv_key_file" json:"priv_key_file"` + Secret string `yaml:"secret" json:"secret"` + PeerType string `yaml:"peer_type" json:"peer_type"` + P2PPort int `yaml:"p2p_port" json:"p2p_port"` + HTTPPort int `yaml:"http_port" json:"http_port"` + RPCPort int `yaml:"rpc_port" json:"rpc_port"` + LogFmt string `yaml:"log_fmt" json:"log_fmt"` + LogLevel string `yaml:"log_level" json:"log_level"` + Bootnodes []string `yaml:"bootnodes" json:"bootnodes"` + BuilderExposeAPI bool `yaml:"builder_expose_api" json:"builder_expose_api"` } func checkConfig(cfg *config) error { @@ -176,14 +177,15 @@ func start(c *cli.Context) error { } nd, err := node.NewNode(&node.Options{ - PrivKey: privKey, - Secret: cfg.Secret, - PeerType: cfg.PeerType, - P2PPort: cfg.P2PPort, - HTTPPort: cfg.HTTPPort, - RPCPort: cfg.RPCPort, - Logger: logger, - Bootnodes: cfg.Bootnodes, + PrivKey: privKey, + Secret: cfg.Secret, + PeerType: cfg.PeerType, + P2PPort: cfg.P2PPort, + HTTPPort: cfg.HTTPPort, + RPCPort: cfg.RPCPort, + Logger: logger, + Bootnodes: cfg.Bootnodes, + BuilderExposeAPI: cfg.BuilderExposeAPI, }) if err != nil { return fmt.Errorf("failed starting node: %w", err) diff --git a/config/builder.yml b/config/builder.yml index 466d9e12..47f78d01 100644 --- a/config/builder.yml +++ b/config/builder.yml @@ -6,5 +6,6 @@ rpc_port: 13524 secret: hello log_fmt: text log_level: debug +builder_expose_api: false bootnodes: - /ip4//tcp/13522/p2p/ diff --git a/pkg/node/node.go b/pkg/node/node.go index f1d30f12..ee24ad14 100644 --- a/pkg/node/node.go +++ b/pkg/node/node.go @@ -28,15 +28,16 @@ import ( ) type Options struct { - Version string - PrivKey *ecdsa.PrivateKey - Secret string - PeerType string - Logger *slog.Logger - P2PPort int - HTTPPort int - RPCPort int - Bootnodes []string + Version string + PrivKey *ecdsa.PrivateKey + Secret string + PeerType string + Logger *slog.Logger + P2PPort int + HTTPPort int + RPCPort int + Bootnodes []string + BuilderExposeAPI bool } type Node struct { @@ -108,16 +109,19 @@ func NewNode(opts *Options) (*Node, error) { switch opts.PeerType { case p2p.PeerTypeBuilder.String(): - builderAPI := builderapi.NewService(opts.Logger.With("component", "builderapi")) - builderapiv1.RegisterBuilderServer(grpcServer, builderAPI) - + var bidProcessor preconfirmation.BidProcessor = noOpBidProcessor{} + if opts.BuilderExposeAPI { + builderAPI := builderapi.NewService(opts.Logger.With("component", "builderapi")) + builderapiv1.RegisterBuilderServer(grpcServer, builderAPI) + bidProcessor = builderAPI + } // TODO(@ckartik): Update noOpBidProcessor to be selected as default in a flag paramater. preconfProto := preconfirmation.New( topo, p2pSvc, preconfSigner, noOpUserStore{}, - noOpBidProcessor{}, + bidProcessor, opts.Logger.With("component", "preconfirmation_protocol"), ) // Only register handler for builder diff --git a/pkg/preconfirmation/preconfirmation.go b/pkg/preconfirmation/preconfirmation.go index dac96a90..9bef0a42 100644 --- a/pkg/preconfirmation/preconfirmation.go +++ b/pkg/preconfirmation/preconfirmation.go @@ -25,7 +25,7 @@ type Preconfirmation struct { topo Topology streamer p2p.Streamer us UserStore - processer BidProcesser + processer BidProcessor logger *slog.Logger } @@ -37,7 +37,7 @@ type UserStore interface { CheckUserRegistred(*common.Address) bool } -type BidProcesser interface { +type BidProcessor interface { ProcessBid(context.Context, *preconfsigner.Bid) (chan builderapiv1.BidResponse_Status, error) } @@ -46,7 +46,7 @@ func New( streamer p2p.Streamer, signer preconfsigner.Signer, us UserStore, - processor BidProcesser, + processor BidProcessor, logger *slog.Logger, ) *Preconfirmation { return &Preconfirmation{ From 6fb906bf079821e026cec5e5f9db8b16577fbf0e Mon Sep 17 00:00:00 2001 From: Kartik Chopra Date: Sun, 15 Oct 2023 17:40:55 -0400 Subject: [PATCH 3/4] Update expose api param name. --- README.md | 2 +- cmd/main.go | 4 ++-- config/builder.yml | 2 +- pkg/node/node.go | 4 ++-- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 0c5f8fe2..3e1e9841 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ To gather commitments from builders, the builder mev-node must maintain an activ By Default this service is disabled, and must be enabled by setting the BuilderAPIEmabled flag in the config file to true. -The file is located at [./config/builder.yaml](./config/builder.yml) and the variable is set to `builder_expose_api: false` by default. +The file is located at [./config/builder.yaml](./config/builder.yml) and the variable is set to `expose_builder_api: false` by default. ## Building Docker Image diff --git a/cmd/main.go b/cmd/main.go index 21fecb43..720abc6b 100644 --- a/cmd/main.go +++ b/cmd/main.go @@ -99,7 +99,7 @@ type config struct { LogFmt string `yaml:"log_fmt" json:"log_fmt"` LogLevel string `yaml:"log_level" json:"log_level"` Bootnodes []string `yaml:"bootnodes" json:"bootnodes"` - BuilderExposeAPI bool `yaml:"builder_expose_api" json:"builder_expose_api"` + ExposeBuilderAPI bool `yaml:"expose_builder_api" json:"expose_builder_api"` } func checkConfig(cfg *config) error { @@ -185,7 +185,7 @@ func start(c *cli.Context) error { RPCPort: cfg.RPCPort, Logger: logger, Bootnodes: cfg.Bootnodes, - BuilderExposeAPI: cfg.BuilderExposeAPI, + ExposeBuilderAPI: cfg.ExposeBuilderAPI, }) if err != nil { return fmt.Errorf("failed starting node: %w", err) diff --git a/config/builder.yml b/config/builder.yml index 47f78d01..0295cfd2 100644 --- a/config/builder.yml +++ b/config/builder.yml @@ -6,6 +6,6 @@ rpc_port: 13524 secret: hello log_fmt: text log_level: debug -builder_expose_api: false +expose_builder_api: false bootnodes: - /ip4//tcp/13522/p2p/ diff --git a/pkg/node/node.go b/pkg/node/node.go index ee24ad14..d1573c92 100644 --- a/pkg/node/node.go +++ b/pkg/node/node.go @@ -37,7 +37,7 @@ type Options struct { HTTPPort int RPCPort int Bootnodes []string - BuilderExposeAPI bool + ExposeBuilderAPI bool } type Node struct { @@ -110,7 +110,7 @@ func NewNode(opts *Options) (*Node, error) { switch opts.PeerType { case p2p.PeerTypeBuilder.String(): var bidProcessor preconfirmation.BidProcessor = noOpBidProcessor{} - if opts.BuilderExposeAPI { + if opts.ExposeBuilderAPI { builderAPI := builderapi.NewService(opts.Logger.With("component", "builderapi")) builderapiv1.RegisterBuilderServer(grpcServer, builderAPI) bidProcessor = builderAPI From d43b34f2ae8283996c4ed952c92018f8a2832305 Mon Sep 17 00:00:00 2001 From: Kartik Chopra Date: Sun, 15 Oct 2023 17:48:38 -0400 Subject: [PATCH 4/4] Adds more documentation refactoring. --- README.md | 22 +++------------------- pkg/rpc/README.md | 19 +++++++++++++++++++ 2 files changed, 22 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 3e1e9841..9b47344b 100644 --- a/README.md +++ b/README.md @@ -102,24 +102,6 @@ By default, the docker setup exposes port `13524`, which is the standard port on } ``` - -## Commitments from Builders -To gather commitments from builders, the builder mev-node must maintain an active service that interfaces with the [GRPC API](https://github.com/primevprotocol/mev-commit/blob/main/rpc/builderapi/v1/builderapi.proto) and interacts with the following functions: - -```protobuf - // ReceiveBids is called by the builder to receive bids from the mev-commit node. - // The mev-commit node will stream bids to the builder. - rpc ReceiveBids(EmptyMessage) returns (stream Bid) {} - // SendProcessedBids is called by the builder to send processed bids to the mev-commit node. - // The builder will stream processed bids to the mev-commit node. - rpc SendProcessedBids(stream BidResponse) returns (EmptyMessage) {} - -``` - -By Default this service is disabled, and must be enabled by setting the BuilderAPIEmabled flag in the config file to true. - -The file is located at [./config/builder.yaml](./config/builder.yml) and the variable is set to `expose_builder_api: false` by default. - ## Building Docker Image To simplify the deployment process, you may utilize Docker to create an isolated environment to run mev-commit. @@ -144,4 +126,6 @@ To simplify the deployment process, you may utilize Docker to create an isolated ## APIs for Searcher & Builder [Link to Documentation on Searcher and Builder API](./pkg/rpc/README.md) - +- This includes: + - the payload for the searcher API + - The required setup for builders to process bids into commitments in their personal infra. \ No newline at end of file diff --git a/pkg/rpc/README.md b/pkg/rpc/README.md index 880b1296..c0789e1a 100644 --- a/pkg/rpc/README.md +++ b/pkg/rpc/README.md @@ -41,3 +41,22 @@ The response to the searcher API is a stream of commitments, an example response "pre_confirmation_signature": "4838b53968be8a4cd4bceee9a8299885546b7d184cfe6390dcb8afd37fec3c1b08f0ce03935afce5b11b9f425434a4b22d01cb4d4dd5f4e5894c699302dbb3ad01" } ``` + + +## Commitments from Builders | Builder API +To gather commitments from builders, the builder mev-node must maintain an active service that interfaces with the [GRPC API](https://github.com/primevprotocol/mev-commit/blob/main/rpc/builderapi/v1/builderapi.proto) and interacts with the following functions: + +```protobuf + // ReceiveBids is called by the builder to receive bids from the mev-commit node. + // The mev-commit node will stream bids to the builder. + rpc ReceiveBids(EmptyMessage) returns (stream Bid) {} + // SendProcessedBids is called by the builder to send processed bids to the mev-commit node. + // The builder will stream processed bids to the mev-commit node. + rpc SendProcessedBids(stream BidResponse) returns (EmptyMessage) {} + +``` + +**By default this service is disabled**, and must be enabled by setting the BuilderAPIEmabled flag in the config file to true. + +The file is located at [./config/builder.yaml](../../config/builder.yml) form the top level of the project and the variable is set to `expose_builder_api: false` by default. +