From 9c5c60a114ef74e68dcc65b4700140d7b5cb04ac Mon Sep 17 00:00:00 2001 From: arya2 Date: Thu, 22 Dec 2022 20:02:35 -0500 Subject: [PATCH 1/5] Updates design overview page of book with: - a simplified graph of service dependencies in design overview - links to notable blog posts - removals of some out-of-date text also corrects issue/pr refs in an rfc --- book/book.toml | 1 + .../src/dev/diagrams/service-dependencies.svg | 115 ++++++++++++++++++ book/src/dev/overview.md | 12 +- .../dev/rfcs/0001-pipelinable-block-lookup.md | 5 +- book/theme/css/custom.css | 10 ++ 5 files changed, 138 insertions(+), 5 deletions(-) create mode 100644 book/src/dev/diagrams/service-dependencies.svg create mode 100644 book/theme/css/custom.css diff --git a/book/book.toml b/book/book.toml index 1356c961dc2..340da4f7c96 100644 --- a/book/book.toml +++ b/book/book.toml @@ -14,3 +14,4 @@ command = "mdbook-mermaid" [output.html] additional-js = ["mermaid.min.js", "mermaid-init.js"] +additional-css = ["theme/css/custom.css"] diff --git a/book/src/dev/diagrams/service-dependencies.svg b/book/src/dev/diagrams/service-dependencies.svg new file mode 100644 index 00000000000..ebf60d11176 --- /dev/null +++ b/book/src/dev/diagrams/service-dependencies.svg @@ -0,0 +1,115 @@ + + +services + + + +state + +state + + + +transaction_verifier + +transaction_verifier + + + +state->transaction_verifier + + + + + +mempool + +mempool + + + +state->mempool + + + + + +chain_verifier + +chain_verifier + + + +state->chain_verifier + + + + + +transaction_verifier->mempool + + + + + +transaction_verifier->chain_verifier + + + + + +inbound + +inbound + + + +mempool->inbound + + + + + +chain_verifier->inbound + + + + + +syncer + +syncer + + + +chain_verifier->syncer + + + + + +peer_set + +peer_set + + + +inbound->peer_set + + + + + +peer_set->mempool + + + + + +peer_set->syncer + + + + + \ No newline at end of file diff --git a/book/src/dev/overview.md b/book/src/dev/overview.md index 8ad85403391..0b825b41cad 100644 --- a/book/src/dev/overview.md +++ b/book/src/dev/overview.md @@ -1,6 +1,6 @@ # Design Overview -This document sketches the future design for Zebra. +This document sketches the design for Zebra. ## Desiderata @@ -34,6 +34,15 @@ The following are general desiderata for Zebra: lightweight applications like light wallets. Those applications should use a light client protocol. +## Notable Blog Posts +- [A New Network Stack For Zcash](https://www.zfnd.org/blog/a-new-network-stack-for-zcash) +- [Composable Futures-based Batch Verification](https://www.zfnd.org/blog/futures-batch-verification) +- [Decoding Bitcoin Messages with Tokio Codecs](https://www.zfnd.org/blog/decoding-bitcoin-messages-with-tokio-codecs) + +## Service Dependencies + +![Service Dependencies](diagrams/service-dependencies.svg) + ## Architecture Unlike `zcashd`, which originated as a Bitcoin Core fork and inherited its @@ -278,7 +287,6 @@ verify blocks or transactions, and add them to the relevant state. #### Internal Dependencies - `zebra-chain` for data structure definitions -- `zebra-network` possibly? for definitions of network messages? #### Responsible for diff --git a/book/src/dev/rfcs/0001-pipelinable-block-lookup.md b/book/src/dev/rfcs/0001-pipelinable-block-lookup.md index 94ce707abd3..0c7ad66bde1 100644 --- a/book/src/dev/rfcs/0001-pipelinable-block-lookup.md +++ b/book/src/dev/rfcs/0001-pipelinable-block-lookup.md @@ -1,8 +1,7 @@ - Feature Name: Pipelinable Block Syncing and Lookup - Start Date: 2020-07-02 -- Design PR: [rust-lang/rfcs#0000](https://github.com/rust-lang/rfcs/pull/0000) -- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000) - +- Design PR: [ZcashFoundation/zebra#583](https://github.com/ZcashFoundation/zebra/pull/583) +- Zebra Issue: [ZcashFoundation/zebra#504](https://github.com/ZcashFoundation/zebra/issues/504) # Summary [summary]: #summary diff --git a/book/theme/css/custom.css b/book/theme/css/custom.css new file mode 100644 index 00000000000..908dbd4602d --- /dev/null +++ b/book/theme/css/custom.css @@ -0,0 +1,10 @@ +img[src = "diagrams/service-dependencies.svg"] { + display: block; + margin: 0px auto; +} + +html.navy img[src = "diagrams/service-dependencies.svg"], +html.ayu img[src = "diagrams/service-dependencies.svg"], +html.coal img[src = "diagrams/service-dependencies.svg"] { + filter: invert(1); +} \ No newline at end of file From f2520bfd023164bdd81c667f7ea49e9dce122919 Mon Sep 17 00:00:00 2001 From: arya2 Date: Wed, 4 Jan 2023 19:22:46 -0500 Subject: [PATCH 2/5] Updates service dependencies diagram --- .../src/dev/diagrams/service-dependencies.svg | 239 ++++++++++++------ book/src/dev/overview.md | 2 + 2 files changed, 163 insertions(+), 78 deletions(-) diff --git a/book/src/dev/diagrams/service-dependencies.svg b/book/src/dev/diagrams/service-dependencies.svg index ebf60d11176..b8fdc9a249c 100644 --- a/book/src/dev/diagrams/service-dependencies.svg +++ b/book/src/dev/diagrams/service-dependencies.svg @@ -1,115 +1,198 @@ - + --> + services - - + -state - -state +transaction_verifier + +transaction_verifier - + -transaction_verifier - -transaction_verifier +state + +state - + -state->transaction_verifier - - +transaction_verifier->state + + mempool - -mempool + +mempool - + + +mempool->transaction_verifier + + + + -state->mempool - - +mempool->state + + + + + +peer_set + +peer_set + + + +mempool->peer_set + + chain_verifier - -chain_verifier + +chain_verifier - + -state->chain_verifier - - +chain_verifier->state + + - - -transaction_verifier->mempool - - + + +checkpoint_verifier + +checkpoint_verifier - - -transaction_verifier->chain_verifier - - + + +chain_verifier->checkpoint_verifier + + + + + +block_verifier + +block_verifier + + + +chain_verifier->block_verifier + + inbound - -inbound - - - -mempool->inbound - - - - - -chain_verifier->inbound - - + +inbound - - -syncer - -syncer + + +inbound->state + + - + -chain_verifier->syncer - - +inbound->mempool + + - - -peer_set - -peer_set + + +inbound->chain_verifier + + - + inbound->peer_set - - + + - - -peer_set->mempool - - + + +rpc_server + +rpc_server - - -peer_set->syncer - - + + +rpc_server->state + + + + + +rpc_server->mempool + + + + + +rpc_server->chain_verifier + + + + + +syncer + +syncer + + + +rpc_server->syncer + + + + + +rpc_server->peer_set + + + + + +checkpoint_verifier->state + + + + + +syncer->chain_verifier + + + + + +syncer->peer_set + + + + + +peer_set->inbound + + + + + +block_verifier->transaction_verifier + + + + + +block_verifier->state + + \ No newline at end of file diff --git a/book/src/dev/overview.md b/book/src/dev/overview.md index 0b825b41cad..13aaf9d3e46 100644 --- a/book/src/dev/overview.md +++ b/book/src/dev/overview.md @@ -41,6 +41,8 @@ The following are general desiderata for Zebra: ## Service Dependencies +Note: dotted lines are for "getblocktemplate-rpcs" feature + ![Service Dependencies](diagrams/service-dependencies.svg) ## Architecture From 63cee81e84769719568356cf8d17f5c7d7cc87b3 Mon Sep 17 00:00:00 2001 From: Arya Date: Wed, 4 Jan 2023 19:24:31 -0500 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: teor --- book/src/dev/overview.md | 2 ++ book/src/dev/rfcs/0001-pipelinable-block-lookup.md | 1 + 2 files changed, 3 insertions(+) diff --git a/book/src/dev/overview.md b/book/src/dev/overview.md index 13aaf9d3e46..ec7b0a63197 100644 --- a/book/src/dev/overview.md +++ b/book/src/dev/overview.md @@ -289,6 +289,8 @@ verify blocks or transactions, and add them to the relevant state. #### Internal Dependencies - `zebra-chain` for data structure definitions +- `zebra-node-services` for shared request type definitions +- `zebra-utils` for developer and power user tools #### Responsible for diff --git a/book/src/dev/rfcs/0001-pipelinable-block-lookup.md b/book/src/dev/rfcs/0001-pipelinable-block-lookup.md index 0c7ad66bde1..0dc24a22042 100644 --- a/book/src/dev/rfcs/0001-pipelinable-block-lookup.md +++ b/book/src/dev/rfcs/0001-pipelinable-block-lookup.md @@ -2,6 +2,7 @@ - Start Date: 2020-07-02 - Design PR: [ZcashFoundation/zebra#583](https://github.com/ZcashFoundation/zebra/pull/583) - Zebra Issue: [ZcashFoundation/zebra#504](https://github.com/ZcashFoundation/zebra/issues/504) + # Summary [summary]: #summary From f601bf39b515a6ecb0cd26286b6cdfac193cd444 Mon Sep 17 00:00:00 2001 From: arya2 Date: Fri, 6 Jan 2023 17:04:26 -0500 Subject: [PATCH 4/5] updates diagram and adds doc links --- .../src/dev/diagrams/service-dependencies.svg | 274 ++++++++---------- book/src/dev/overview.md | 31 +- book/theme/css/custom.css | 13 +- 3 files changed, 164 insertions(+), 154 deletions(-) diff --git a/book/src/dev/diagrams/service-dependencies.svg b/book/src/dev/diagrams/service-dependencies.svg index b8fdc9a249c..3ebd62bdf56 100644 --- a/book/src/dev/diagrams/service-dependencies.svg +++ b/book/src/dev/diagrams/service-dependencies.svg @@ -1,198 +1,174 @@ - - + + + + + + services - + transaction_verifier - -transaction_verifier - + +transaction_verifier + - + state - -state - + +state + -transaction_verifier->state - - +transaction_verifier->state + + - + mempool - -mempool - + +mempool + - -mempool->transaction_verifier - - + +mempool->transaction_verifier + + -mempool->state - - +mempool->state + + - + peer_set - -peer_set - + +peer_set + - -mempool->peer_set - - - - - -chain_verifier - -chain_verifier - - - -chain_verifier->state - - - - - -checkpoint_verifier - -checkpoint_verifier - - - -chain_verifier->checkpoint_verifier - - - - - -block_verifier - -block_verifier - - - -chain_verifier->block_verifier - - + +mempool->peer_set + + - + inbound - -inbound - + +inbound + - -inbound->state - - + +inbound->state + + - -inbound->mempool - - + +inbound->mempool + + + + +chain_verifier + +chain_verifier + - -inbound->chain_verifier - - - - - -inbound->peer_set - - + +inbound->chain_verifier + + - + rpc_server - -rpc_server - + +rpc_server + - -rpc_server->state - - + +rpc_server->state + + - -rpc_server->mempool - - + +rpc_server->mempool + + - -rpc_server->chain_verifier - - - - - -syncer - -syncer + +rpc_server->chain_verifier + + - - -rpc_server->syncer - - + + +checkpoint_verifier + +checkpoint_verifier + + + +chain_verifier->checkpoint_verifier + + - - -rpc_server->peer_set - - + + +block_verifier + +block_verifier + + + +chain_verifier->block_verifier + + - -checkpoint_verifier->state - - + +checkpoint_verifier->state + + + + +syncer + +syncer + - -syncer->chain_verifier - - + +syncer->chain_verifier + + - -syncer->peer_set - - - - - -peer_set->inbound - - + +syncer->peer_set + + - -block_verifier->transaction_verifier - - + +block_verifier->transaction_verifier + + - -block_verifier->state - - + +block_verifier->state + + \ No newline at end of file diff --git a/book/src/dev/overview.md b/book/src/dev/overview.md index ec7b0a63197..f224b1a953a 100644 --- a/book/src/dev/overview.md +++ b/book/src/dev/overview.md @@ -43,7 +43,36 @@ The following are general desiderata for Zebra: Note: dotted lines are for "getblocktemplate-rpcs" feature -![Service Dependencies](diagrams/service-dependencies.svg) +
+{{#include diagrams/service-dependencies.svg}} +
+ + ## Architecture diff --git a/book/theme/css/custom.css b/book/theme/css/custom.css index 908dbd4602d..495c0d89ad7 100644 --- a/book/theme/css/custom.css +++ b/book/theme/css/custom.css @@ -1,10 +1,15 @@ -img[src = "diagrams/service-dependencies.svg"] { +#service-dep-diagram { display: block; margin: 0px auto; } -html.navy img[src = "diagrams/service-dependencies.svg"], -html.ayu img[src = "diagrams/service-dependencies.svg"], -html.coal img[src = "diagrams/service-dependencies.svg"] { +#service-dep-diagram a:hover { + text-decoration: none; + filter: drop-shadow(0 0 4px #000); +} + +html.navy #service-dep-diagram, +html.ayu #service-dep-diagram, +html.coal #service-dep-diagram { filter: invert(1); } \ No newline at end of file From ca8fd7e650cd60a7c7e4d2c4ae6744ef28ccdc2d Mon Sep 17 00:00:00 2001 From: arya2 Date: Fri, 6 Jan 2023 18:03:57 -0500 Subject: [PATCH 5/5] uses opacity to indicate clickability instead of drop shadow --- book/theme/css/custom.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/book/theme/css/custom.css b/book/theme/css/custom.css index 495c0d89ad7..62fb70f38ea 100644 --- a/book/theme/css/custom.css +++ b/book/theme/css/custom.css @@ -5,7 +5,7 @@ #service-dep-diagram a:hover { text-decoration: none; - filter: drop-shadow(0 0 4px #000); + opacity: 0.65; } html.navy #service-dep-diagram,