cometbft icon indicating copy to clipboard operation
cometbft copied to clipboard

Consolidate existing mempool specs and documentation

Open cason opened this issue 2 years ago • 3 comments

At its current state, the repository does not really contain specific documentation about the mempool.

In the specification, the item mempool on spec/README.md points to spec/p2p/legacy-docs/messages/mempool.md, which documents the channel and the message used by the mempool reactor.

In the documentation, the docs/core/mempool.md entry is not very helpful as well in terms of documentation. While the mempool is mentioned in other locations, this is the only document that specifically refers to the mempool.

The goal of this issue are therefore two:

  1. Enumerate the existing content regarding the mempool (list of pending transactions) and the mempool protocol (that exchanges transactions between nodes)
  2. Create a location in the repository collecting the summary of the existing documentation, with pointers to the content enumerated in 1.

This issue should be seen as a (weak) dependency for the refactor/improvements proposed in https://github.com/cometbft/cometbft/issues/1048

Definition of Done

  • We have a spec/mempool directory in the repository with some basic content about this component/protocol of CometBFT
  • We populate this directory with the existing content, or links to the existing content, regarding the mempool, including recent specification/documentation efforts hosted elsewhere

cason avatar Jul 03 '23 13:07 cason

Some scattered documents related to the mempool:

  • Overview: https://github.com/cometbft/knowledge-base/blob/main/protocols/mempool-overview.md
    • There's a PR that updates and extends this document: https://github.com/cometbft/knowledge-base/pull/9/files
  • Diagram of v0 implementation: https://github.com/cometbft/knowledge-base/blob/main/protocols/mempool/v0/mempool-v0.md
  • RFC-103: https://github.com/cometbft/cometbft/blob/main/docs/rfc/rfc-103-incoming-txs-when-catching-up.md
  • Quint specs (2): https://github.com/cometbft/knowledge-base/tree/main/quint/mempool

hvanz avatar Jul 03 '23 14:07 hvanz

Some info on the field ids: mempoolIDs in the mempool reactor: https://github.com/cometbft/cometbft/pull/1043#discussion_r1251606701

hvanz avatar Jul 04 '23 07:07 hvanz

@hvanz, can we solve this issue? Like moving the stable content to this repository? Do you mind take it over?

cason avatar Feb 21 '24 08:02 cason

Closing as spec/mempool now contains specs of all the mempool components (recently #4318 has added specs for the gossip protocols).

hvanz avatar Dec 20 '24 22:12 hvanz