Merge pull request #57 from primevprotocol/ckartik/update-readme-with…

…-new-dataformats Update Readme and Adds Config param for Builder API
primev · Oct 16, 2023 · 1a64640 · 1a64640
2 parents 3bd1d29 + d43b34f
commit 1a64640
Show file tree

Hide file tree

Showing 6 changed files with 108 additions and 48 deletions.
diff --git a/README.md b/README.md
@@ -102,21 +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) {}
-
-```
-
-
 ## Building Docker Image
 
 To simplify the deployment process, you may utilize Docker to create an isolated environment to run mev-commit.
@@ -138,3 +123,9 @@ 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)
+- This includes: 
+   - the payload for the searcher API
+   - The required setup for builders to process bids into commitments in their personal infra.
diff --git 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"`
+	ExposeBuilderAPI bool     `yaml:"expose_builder_api" json:"expose_builder_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,
+		ExposeBuilderAPI: cfg.ExposeBuilderAPI,
 	})
 	if err != nil {
 		return fmt.Errorf("failed starting node: %w", err)

diff --git a/config/builder.yml b/config/builder.yml
@@ -6,5 +6,6 @@ rpc_port: 13524
 secret: hello
 log_fmt: text
 log_level: debug
+expose_builder_api: false
 bootnodes:
   - /ip4/<localhost>/tcp/13522/p2p/<p2p_ID>
diff --git 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
+	ExposeBuilderAPI 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.ExposeBuilderAPI {
+			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
@@ -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{

diff --git a/pkg/rpc/README.md b/pkg/rpc/README.md
@@ -0,0 +1,62 @@
+# 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": "<string transaction hash>",
+  "amount": <integer amount of bid in wei>,
+  "block_number": <the block number formated as a base 10 integer>
+}
+```
+
+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"
+}
+```
+
+
+## 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.
+