fix: docs

Author: alok

docs/.nojekyll

@@ -0,0 +1,40 @@
+# mev-commit
+
+## Summary
+Introducing mev-commit, a peer-to-peer (P2P) networking software that serves as a conduit for real-time communication with execution providers. mev-commit enables MEV actors to join and utilize a P2P network for the exchange of execution bids and commitments, enriching the transaction execution experience by allowing for granular specification of execution needs and receiving real-time commitments.
+
+## Actors
+**Providers**
+
+Providers of execution services (**Block builders, Rollup Sequencers)**
+
+**Users**
+
+Users of execution services (**MEV searchers, AA bundlers, L2s, and other blockspace consumers)**
+
+## Network Topology
+
+The network topology we will be releasing is as follows:
+![](topology.png)
+
+Users will connect to providers, each of these nodes will have access to a bootnode for network startup. Providers will also be able to run gateway nodes to allow users to send bids directly to an RPC endpoint under a provider URL.
+
+## Bids and Privacy
+
+mev-commit is inherently pseudonymous, allowing any Ethereum address to submit a bid for transaction execution, including bids for transactions that belong to others. Bids use the transaction hash identifier for universal provider pickup and are visible to network actors. Bids are processed by both network providers and Primev chain validators, ensuring verifiable commitments and seamless reward settlements.
+
+## Commitments and Privacy
+
+Commitments are commitment signatures from providers in response to bids. mev-commit provides a standard commitment method and a private commitment method for providers to choose from. Private commitments are encrypted and can only be read by the bidder until after the block slot ends and they’re revealed. Providers can also maintain their pseudonymity with commitments, using alternate addresses to obfuscate their identity as known block provider or sequencers.
+
+For more on commitment privacy
+
+## Settlement Layer
+
+Bids and commitments will settle on a specialized Ethereum fork based on the OP stack. Initially centralized, the settlement layer operates as a high-throughput chain to expedite the settlement process. As governance processes are initiated, this chain will become a federated rollup to providers on the network to assume the Sequencer role in turns. A rollup sequencer maintains the state of bids and commitments, acting as a network peer and handles fund settlements, rewards, or slashes.
+
+## Network Flows
+
+Diagram depicting **the flow of bids, commitments, and funds**
+
+![](flow.png)

docs/README.md

@@ -0,0 +1,6 @@
+<!-- docs/_sidebar.md -->
+
+* [Home](/)
+* [Quickstart](quickstart.md "Quickstart")
+* [API clients](api-clients.md "API clients")
+* [Debugging](debugging.md "Debugging")

docs/_sidebar.md

@@ -0,0 +1,92 @@
+# API clients
+
+The mev-commit node provides two key APIs. The execution providers need to use the **Provider API** whereas the users need to use the **User API** based on their role in the network.
+
+## Providers
+
+Execution providers will use the `provider` role of the mev-commit software to run their nodes. This will allow users to send bids to them to include in the blocks that they build. They will use the **Provider RPC API** to receive signed bids that are being propogated in the network. Once they get a bid, they need to communicate with the mev-commit node whether the bid has been **Accepted** or **Rejected**. If accepted, the mev-commit node will send a signed pre-confirmation to the users.
+
+The API is implemented using gRPC framework. This allows two types of operations:
+
+### RPC API
+
+Users can find the protobuf file in the [repository](https://github.com/primevprotocol/mev-commit/blob/main/rpc/providerapi/v1/providerapi.proto). This can be used to generate the client for the RPC in the language of your choice. The go client is already generated in the repository. For other languagues, please follow the instructions in the [grpc documentation](https://grpc.io/docs/languages/) to generate them.
+
+There are two main APIs
+```proto
+  // ReceiveBids is called by the execution provider to receive bids from the mev-commit node.
+  // The mev-commit node will stream bids to the execution provider.
+  rpc ReceiveBids(EmptyMessage) returns (stream Bid) {}
+  // SendProcessedBids is called by the provider to send processed bids to the mev-commit node.
+  // The execution provider will stream processed bids to the mev-commit node.
+  rpc SendProcessedBids(stream BidResponse) returns (EmptyMessage) {}
+```
+
+The message definitions are as follows:
+```proto
+message Bid {
+  string txn_hash = 1;
+  int64 bid_amt = 2;
+  int64 block_number = 3;
+  bytes bid_hash = 4;
+};
+
+message BidResponse {
+  bytes bid_hash = 1;
+  enum Status {
+    STATUS_UNSPECIFIED = 0;
+    STATUS_ACCEPTED = 1;
+    STATUS_REJECTED = 2;
+  }
+  Status status = 2;
+};
+
+```
+
+### HTTP API
+
+The same API is also available on the HTTP port configured on the node. Please go through the [API docs](api/provider.html) to understand the usage.
+
+An [example client](https://github.com/primevprotocol/mev-commit/tree/main/examples/provideremulator) is implemented in the repository. This is mainly to demostrate how to write the client integrated in the provider's environment. The client blindly accepts each bid that it receives, however the provider needs to implement custom logic here to make the decision.
+
+## Users
+
+Users will use the `user` role of the mev-commit software to run their nodes. With this role, the node provides the **User API** to submit bids to the network. The mev-commit node will sign the bid before it sends it to different providers that are accepting bids. On the response, users will get pre-confirmations from the providers if the bid is accepted. This is a streaming response and users are expected to keep the connection alive till all the preconfirmations are received by the node.
+
+The API is implemented using gRPC framework. This allows two types of operations:
+
+### RPC API
+
+Users can find the protobuf file in the [repository](https://github.com/primevprotocol/mev-commit/blob/main/rpc/userapi/v1/userapi.proto). This can be used to generate the client for the RPC in the language of your choice. The go client is already generated in the repository. For other languagues, please follow the instructions in the [grpc documentation](https://grpc.io/docs/languages/) to generate them.
+
+The API available is:
+```proto
+  rpc SendBid(Bid) returns (stream PreConfirmation)
+```
+
+The message definitions are as follows:
+```proto
+message Bid {
+  string tx_hash = 1;
+  int64 amount = 2;
+  int64 block_number = 3;
+};
+
+message PreConfirmation {
+  string tx_hash = 1;
+  int64 amount = 2;
+  int64 block_number = 3;
+  string bid_digest = 4;
+  string bid_signature = 5;
+  string pre_confirmation_digest = 6;
+  string pre_confirmation_signature = 7;
+};
+```
+
+### HTTP API
+
+The same API is also available on the HTTP port configured on the node. Please go through the [API docs](api/user.html) to understand the usage.
+
+An [example CLI application](https://github.com/primevprotocol/mev-commit/tree/main/examples/usercli) is implemented in the repository. This is mainly to demostrate how to integrate with the RPC API.
+
+

docs/api-clients.md

@@ -0,0 +1,34 @@
+# Debugging
+
+The mev-commit node is still in active development. As a result there is some debugging instrumentation available on the node. In the normal use-cases, the users might not need this, but they can always use this to get more information on the inner-workings of the node. These tools can be accessed on the HTTP API endpoint.
+
+## Network topology
+
+The topology of the network as seen by the mev-commit node can be obtained on the `/topology` endpoint of the node. This should show the no. of nodes connected and their roles. This would be mainly used to check if the node has sufficient connectivity with the network.
+
+```json
+{
+  "self": {
+    "Addresses": [
+      "/ip4/127.0.0.1/tcp/13522",
+      "/ip4/172.28.0.4/tcp/13522"
+    ],
+    "Ethereum Address": "0xB61545548948E9299Ce6eb4C01F2C31FcE6c9E83",
+    "Peer Type": "user",
+    "Underlay": "16Uiu2HAmNMdhYW6KdECZSNoCseM4cwKbV72BgCYZMz9SbMmxWScM"
+  },
+  "connected_peers": {
+    "providers": [
+      "0x6c27a32189016bde0d4a506805aa2b6c46295e8a"
+    ]
+  }
+}
+```
+
+## Prometheus metrics
+
+The node also emits a bunch of prometheus metrics. These can be potentially used to write dashboards that will help show different stats of the node. The node uses `libp2p` networking library. The `libp2p` default metrics are also available on the `/metrics` endpoint.
+
+## Pprof endpoints
+
+The pprof endpoints are also accessible on the node on the `/debug/pprof` endpoint. These are mainly used to observe how the node is performing for eg. the memory, CPU usage on the nodes. These are useful only for users who already know how to use them. Explaining them is beyond the scope of this documentation.

docs/api/provider.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Document</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Description">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'mev-commit',
+      repo: 'primevprotocol/mev-commit',
+      logo: 'https://avatars.githubusercontent.com/u/121584070?v=4',
+      loadSidebar: true,
+      noCompileLinks: ['/api/.*'],
+      subMaxLevel: 2
+    }
+  </script>
+  <!-- Docsify v4 -->
+  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+</body>
+</html>

docs/api/user.html

@@ -0,0 +1,94 @@
+# Quickstart
+
+## Using the CLI
+
+mev-commit software is a CLI program that needs to be run by the users in their own environments. The CLI has two commands mainly. You can run the main command with `-h`/`--help` option to see the available commands.
+
+```
+❯ mev-commit -h
+NAME:
+   mev-commit - Entry point for mev-commit
+
+USAGE:
+   mev-commit [global options] command [command options] [arguments...]
+
+VERSION:
+   "v1.0.0-alpha-a834960"
+
+COMMANDS:
+   start       Start the mev-commit node
+   create-key  Create a new ECDSA private key and save it to a file
+   help, h     Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --help, -h     show help
+   --version, -v  print the version
+```
+
+Users can use any existing ECDSA private key or create one using the `create-key` command. This key is used to derive the ethereum address of the node taking part in the network.
+
+```
+❯ mev-commit create-key -h
+NAME:
+   mev-commit create-key - Create a new ECDSA private key and save it to a file
+
+USAGE:
+   mev-commit create-key [command options] <output_file>
+
+OPTIONS:
+   --help, -h  show help
+```
+
+In order to run a node, users need to create a configuration file in the YAML format. Example config files can be found in the [config](https://github.com/primevprotocol/mev-commit/tree/main/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 user.
+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 API. 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
+
+# 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
+```
+
+Place this config file in some folder. It is advised to create a new `.mev-commit` folder in the home directory and place it there. Once this is done, users can start the node using the `start` command.
+
+```
+❯ mev-commit start -h
+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
+```
+
+## Docker
+
+Optionally users can use the docker images to run the client in their docker environment. You need to make sure the node is able to communicate with provider/user nodes.