docs: mdbook guide #726
docs: mdbook guide #726
Conversation
Operator installation
chain MMR faq
Mirko-von-Leipzig
force-pushed
the
mirko/docs
branch
from
6f0e345 to
e22ce86
Compare
Mirko-von-Leipzig
force-pushed
the
mirko/docs
branch
from
8cf9bd0 to
c0ec5ee
Compare
|
I've updated the PR with some minor changes. As discussed offline I'll leave this targeting |
.github/workflows/book.yml
Outdated
| # Only run deployment on push to main/next branches, not on PRs | ||
| if: github.event_name == 'push' || github.event_name == 'workflow_run' |
There was a problem hiding this comment.
This means pushes to main and next will overwrite each other. Probably we would want this to only happen on next so that they're always the latest dev docs.
There was a problem hiding this comment.
Looks great! Thank you! I left some comments inline - most are pretty minor.
Once this is ready to merge, I'll create a Github page for the mdBook (similar to how we have it in the miden-vm repo) and then we'll need to update the main readme to link to this book.
There was a problem hiding this comment.
As I mentioned in some other similar reviews, I'd probably remove this file for now.
There was a problem hiding this comment.
Related to the above comment, I'd probably get rid of this check for now.
| ```mermaid | ||
| --- | ||
| title: Infrastructure architecture example | ||
| --- | ||
| graph LR; | ||
|
|
||
| subgraph RPC | ||
| direction RL | ||
| rpc_a[RPC A] | ||
| rpc_b[RPC B] | ||
| rpc_i[......] | ||
| rpc_n[RPC N] | ||
| end | ||
|
|
||
| subgraph internal | ||
| direction TB | ||
| store | ||
| block-producer | ||
| end | ||
|
|
||
| load_balancer[Load Balancer] | ||
|
|
||
| load_balancer ---> RPC | ||
|
|
||
| RPC -- tx ---> block-producer | ||
| RPC -- query --> store | ||
|
|
||
| block-producer -- block --> store | ||
| ``` |
There was a problem hiding this comment.
I think a simple Excalidraw diagram (like we have in the readme) may be better here (we'd have more control of what to show and how). I've attached the source code for the diagrams I have.
| The block-producer is responsible for aggregating received transactions into blocks and submitting them to the store. | ||
|
|
||
| Transactions are placed in a mempool and are periodically sampled to form batches of transactions. These batches are | ||
| proved, and then periodically aggregated into a block. This block is then proved and committed to the store. |
There was a problem hiding this comment.
I think this was written before we merged the relevant PRs, but I'd also mention how proving works (e.g., that batch and block proving can be done via remote provers).
| @@ -0,0 +1,85 @@ | |||
| # Installation | |||
|
|
|||
| We provide Debian packages for official releases for both the node software as well as a basic faucet implementation. | |||
There was a problem hiding this comment.
The mentioning of the faucet comes out a bit "out of the blue". We should probably have a small section somewhere explaining what the faucet is and why it is needed.
| ## Architecture | ||
|
|
||
| The store consists mainly of a gRPC server which answers requests from the RPC and block-producer components, as well as | ||
| new block submissions from the block-producer. | ||
|
|
||
| A lightweight background process performs database query optimisation by analysing database queries and statistics. |
There was a problem hiding this comment.
Not for this PR, but I would maybe add more info about how the store works - e.g., that we have accounts, notes, and nullifiers; that Merkle data structures are currently always in memory (and are re-built on node startup).
There was a problem hiding this comment.
I would mention somewhere in this file that batches/blocks can be proven by remote provers.
| - [Developer](./developer/index.md) | ||
| - [Contributing](./developer/contributing.md) | ||
| - [Navigating the codebase](./developer/codebase.md) | ||
| - [Monitoring](./developer/monitoring.md) | ||
| - [Components](./developer/components.md) | ||
| - [RPC](./developer/rpc.md) | ||
| - [Store](./developer/store.md) | ||
| - [Block producer](./developer/block-producer.md) | ||
| - [Common issues other oddities](./developer/oddities.md) |
There was a problem hiding this comment.
I'm not sure this section needs to go into the unified docs.
There was a problem hiding this comment.
nit: as mentioned in some other PRs, I would probably name this EXPORTED.md.
There was a problem hiding this comment.
As mentioned in the reviews in parallel PRs in other repos: I'd probably simplify this file to only keep the deploy job and make this job similar to what we currently have in miden-vm (unless there is a good reason to deviate).
This PR adds an
mdbookdoc guide for node operators and developers.I've been staring at this for a bit too long; I think I've developed blind spots. Happy with any feedback.
Note: this includes a
mermaid.jsdiagram - I'm not sure its that nice, there are maybe better formats to choose instead.Closes #244