From 34dde9f1b7a3c2e14a556365ab38837534f3cd88 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 15 Nov 2024 17:07:56 -0500 Subject: [PATCH 1/5] add SCRATCHPAD.txt --- SCRATCHPAD.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 SCRATCHPAD.txt diff --git a/SCRATCHPAD.txt b/SCRATCHPAD.txt new file mode 100644 index 000000000..cbcddc559 --- /dev/null +++ b/SCRATCHPAD.txt @@ -0,0 +1,13 @@ +RPC stuff that needs to be written in the architecture book: + +## General +- diagram showing full pipeline from input to output with crate responsibilities listed along the line + +## The handler +- {json-rpc, binary, other} handler functions implemented in `cuprated` +- handler -> helper function -> internal component's `Service` + +## Unsupported RPC calls / RPC calls with different behavior +- https://github.com/Cuprate/cuprate/issues/278 +- binary strings -> full JSON: `get_transaction_pool_backlog`, `get_output_distribution` +- not in `monerod` yet: `get_tx_ids_loose` From 3554c9c1d5efd33b3cba03438319c82d3512c295 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Fri, 15 Nov 2024 20:16:54 -0500 Subject: [PATCH 2/5] request strictness --- SCRATCHPAD.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/SCRATCHPAD.txt b/SCRATCHPAD.txt index cbcddc559..a0ad26945 100644 --- a/SCRATCHPAD.txt +++ b/SCRATCHPAD.txt @@ -11,3 +11,14 @@ RPC stuff that needs to be written in the architecture book: - https://github.com/Cuprate/cuprate/issues/278 - binary strings -> full JSON: `get_transaction_pool_backlog`, `get_output_distribution` - not in `monerod` yet: `get_tx_ids_loose` + +## Differences with monerod (Request strictness) +Some of `monerod`'s RPC request types contain fields not for users to provide, +but for internal usage within the RPC handlers and `monerod` itself, some examples: +- + +Unless one of these actually allows something unintentionally bad to happen, this is mostly an unimportant detail. + + +Practically, it means users can provide these fields and `monerod` will deserialize them +and accept them fine, while `cuprated` will not because they are not part of the type. From 6b6e32607f14fe99c14636a214998ec5bbe8b194 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Wed, 25 Dec 2024 18:41:12 -0500 Subject: [PATCH 3/5] changes --- books/architecture/src/appendix/crates.md | 1 - books/architecture/src/rpc/handler/intro.md | 8 +++++- books/architecture/src/rpc/interface.md | 3 +-- books/architecture/src/rpc/intro.md | 27 ++++++++++++++++++++- rpc/interface/README.md | 2 +- 5 files changed, 35 insertions(+), 6 deletions(-) diff --git a/books/architecture/src/appendix/crates.md b/books/architecture/src/appendix/crates.md index 5124180fb..9f9935aa6 100644 --- a/books/architecture/src/appendix/crates.md +++ b/books/architecture/src/appendix/crates.md @@ -52,7 +52,6 @@ cargo doc --open --package cuprate-blockchain | [`cuprate-json-rpc`](https://doc.cuprate.org/cuprate_json_rpc) | [`rpc/json-rpc/`](https://github.com/Cuprate/cuprate/tree/main/rpc/json-rpc) | JSON-RPC 2.0 implementation | [`cuprate-rpc-types`](https://doc.cuprate.org/cuprate_rpc_types) | [`rpc/types/`](https://github.com/Cuprate/cuprate/tree/main/rpc/types) | Monero RPC types and traits | [`cuprate-rpc-interface`](https://doc.cuprate.org/cuprate_rpc_interface) | [`rpc/interface/`](https://github.com/Cuprate/cuprate/tree/main/rpc/interface) | RPC interface & routing -| [`cuprate-rpc-handler`](https://doc.cuprate.org/cuprate_rpc_handler) | [`rpc/handler/`](https://github.com/Cuprate/cuprate/tree/main/rpc/handler) | RPC inner handlers ## ZMQ | Crate | In-tree path | Purpose | diff --git a/books/architecture/src/rpc/handler/intro.md b/books/architecture/src/rpc/handler/intro.md index e664f5bb9..e420a5c7c 100644 --- a/books/architecture/src/rpc/handler/intro.md +++ b/books/architecture/src/rpc/handler/intro.md @@ -1,2 +1,8 @@ # The handler -> TODO: fill after `cuprate-rpc-handler` is created. \ No newline at end of file +The handlers (functions that map requests into responses) are / can be generic with `cuprate-rpc-interface`. + +The main handlers used by Cuprate is implemented in `cuprated` itself, it implements the standard RPC handlers modeled after `monerod`. + +- JSON-RPC handlers: +- Binary handlers: +- Other JSON handlers: \ No newline at end of file diff --git a/books/architecture/src/rpc/interface.md b/books/architecture/src/rpc/interface.md index 3557ffbb1..6992bdd48 100644 --- a/books/architecture/src/rpc/interface.md +++ b/books/architecture/src/rpc/interface.md @@ -29,8 +29,7 @@ async fn json_rpc( ``` and you provide the function body. -The main handler crate is [`cuprate-rpc-handler`](https://doc.cuprate.org/cuprate_rpc_handler). -This crate implements the standard RPC behavior, i.e. it mostly mirrors `monerod`. +The main handler crate is `cuprated` itself, it implements the standard RPC behavior, i.e. it mostly mirrors `monerod`. Although, it's worth noting that other implementations are possible, such as an RPC handler that caches blocks, or an RPC handler that only accepts certain endpoints, or any combination. \ No newline at end of file diff --git a/books/architecture/src/rpc/intro.md b/books/architecture/src/rpc/intro.md index acfc60456..dbdd68d4c 100644 --- a/books/architecture/src/rpc/intro.md +++ b/books/architecture/src/rpc/intro.md @@ -27,4 +27,29 @@ The main components that make up Cuprate's RPC are noted below, alongside the eq | [`cuprate-json-rpc`](https://doc.cuprate.org/cuprate_json_rpc) | [`jsonrpc_structs.h`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/contrib/epee/include/net/jsonrpc_structs.h), [`http_server_handlers_map2.h`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/contrib/epee/include/net/http_server_handlers_map2.h) | JSON-RPC 2.0 implementation | `monerod`'s JSON-RPC 2.0 handling is spread across a few files. The first defines some data structures, the second contains macros that (essentially) implement JSON-RPC 2.0. | [`cuprate-rpc-types`](https://doc.cuprate.org/cuprate_rpc_types) | [`core_rpc_server_commands_defs.h`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/src/rpc/core_rpc_server_commands_defs.h) | RPC request/response type definitions and (de)serialization | | | [`cuprate-rpc-interface`](https://doc.cuprate.org/cuprate_rpc_interface) | [`core_rpc_server.h`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/src/rpc/core_rpc_server.h) | RPC interface, routing, endpoints | | -| [`cuprate-rpc-handler`](https://doc.cuprate.org/cuprate_rpc_handler) | [`core_rpc_server.cpp`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/src/rpc/core_rpc_server.cpp) | RPC request/response handling | These are the "inner handler" functions that turn requests into responses | \ No newline at end of file + +`cuprated` utilizes these crates and contains the actual functions that handle the request -> response mappings. + +## Diagram +A diagram of the crate's responsibilities in `cuprated`'s RPC system. +``` + cuprate-rpc-types + + + cuprate-json-rpc + + + cuprate-rpc-interface + │ │ +┌───────────────────────────┤ ├───────────────────┐ +▼ ▼ ▼ ▼ +CLIENT ─► ROUTE ─► REQUEST ─► HANDLER ─► RESPONSE ─► CLIENT + ▲ ▲ + └───┬───┘ + │ + cuprated's handler functions +``` + +`cuprated` only contains the: +- handler functions (the functions that map requests into responses) +- glue code with the rest of Cuprate to make the above happen + +All the other details are handled in other crates. \ No newline at end of file diff --git a/rpc/interface/README.md b/rpc/interface/README.md index fa5496c10..7e5deab87 100644 --- a/rpc/interface/README.md +++ b/rpc/interface/README.md @@ -21,7 +21,7 @@ This is where your [`RpcHandler`] turns this `Request` into a `Response`. You hand this `Response` back to `cuprate-rpc-interface` and it will take care of sending it back to the client. -The main handler used by Cuprate is implemented in the `cuprate-rpc-handler` crate; +The main handler used by Cuprate is implemented in `cuprated` itself, it implements the standard RPC handlers modeled after `monerod`. # Purpose From 4f8c70f13ebc6f29f9443d77b71cd622cc63b5b6 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Wed, 5 Feb 2025 16:21:09 -0500 Subject: [PATCH 4/5] apply --- books/architecture/src/SUMMARY.md | 7 +++---- .../differences/rpc-calls-with-different-behavior.md | 2 -- books/architecture/src/rpc/differences/rpc-calls.md | 6 ++++++ .../src/rpc/differences/unsupported-rpc-calls.md | 2 -- books/architecture/src/rpc/handler.md | 12 ++++++++++++ books/architecture/src/rpc/handler/intro.md | 8 -------- 6 files changed, 21 insertions(+), 16 deletions(-) delete mode 100644 books/architecture/src/rpc/differences/rpc-calls-with-different-behavior.md create mode 100644 books/architecture/src/rpc/differences/rpc-calls.md delete mode 100644 books/architecture/src/rpc/differences/unsupported-rpc-calls.md create mode 100644 books/architecture/src/rpc/handler.md delete mode 100644 books/architecture/src/rpc/handler/intro.md diff --git a/books/architecture/src/SUMMARY.md b/books/architecture/src/SUMMARY.md index a99d099f4..196b24c1a 100644 --- a/books/architecture/src/SUMMARY.md +++ b/books/architecture/src/SUMMARY.md @@ -70,7 +70,7 @@ - [🟢 Metadata](rpc/types/metadata.md) - [🟡 (De)serialization](rpc/types/deserialization.md) - [🟢 The interface](rpc/interface.md) - - [🔴 The handler](rpc/handler/intro.md) + - [🟢 The handler](rpc/handler.md) - [🔴 The server](rpc/server/intro.md) - [🟢 Differences with `monerod`](rpc/differences/intro.md) - [🟢 JSON field ordering](rpc/differences/json-field-ordering.md) @@ -78,10 +78,9 @@ - [🟢 JSON strictness](rpc/differences/json-strictness.md) - [🟡 JSON-RPC strictness](rpc/differences/json-rpc-strictness.md) - [🟡 HTTP methods](rpc/differences/http-methods.md) - - [🟡 RPC payment](rpc/differences/rpc-payment.md) - [🟢 Custom strings](rpc/differences/custom-strings.md) - - [🔴 Unsupported RPC calls](rpc/differences/unsupported-rpc-calls.md) - - [🔴 RPC calls with different behavior](rpc/differences/rpc-calls-with-different-behavior.md) + - [🟡 RPC payment](rpc/differences/rpc-payment.md) + - [🔴 RPC calls](rpc/differences/rpc-calls.md) --- diff --git a/books/architecture/src/rpc/differences/rpc-calls-with-different-behavior.md b/books/architecture/src/rpc/differences/rpc-calls-with-different-behavior.md deleted file mode 100644 index 6c1cb69df..000000000 --- a/books/architecture/src/rpc/differences/rpc-calls-with-different-behavior.md +++ /dev/null @@ -1,2 +0,0 @@ -# RPC calls with different behavior -> TODO: compile RPC calls with different behavior after handlers are created. \ No newline at end of file diff --git a/books/architecture/src/rpc/differences/rpc-calls.md b/books/architecture/src/rpc/differences/rpc-calls.md new file mode 100644 index 000000000..4b01ac3fe --- /dev/null +++ b/books/architecture/src/rpc/differences/rpc-calls.md @@ -0,0 +1,6 @@ +# RPC calls +> TODO: document unsupported and/or difference behavior RPC calls in User Book and link to it. +> +> - binary strings -> full JSON: `get_transaction_pool_backlog`, `get_output_distribution` +> - not in `monerod` yet: `get_tx_ids_loose` +> - \ No newline at end of file diff --git a/books/architecture/src/rpc/differences/unsupported-rpc-calls.md b/books/architecture/src/rpc/differences/unsupported-rpc-calls.md deleted file mode 100644 index ac0c2df3b..000000000 --- a/books/architecture/src/rpc/differences/unsupported-rpc-calls.md +++ /dev/null @@ -1,2 +0,0 @@ -# Unsupported RPC calls -> TODO: compile unsupported RPC calls after handlers are created. \ No newline at end of file diff --git a/books/architecture/src/rpc/handler.md b/books/architecture/src/rpc/handler.md new file mode 100644 index 000000000..0d74b888a --- /dev/null +++ b/books/architecture/src/rpc/handler.md @@ -0,0 +1,12 @@ +# The handler +The handlers (functions that map requests into responses) are / can be generic with `cuprate-rpc-interface`. + +`cuprated` itself implements the standard RPC handlers modeled after `monerod`, see here: + +- [JSON-RPC](https://github.com/Cuprate/cuprate/tree/main/binaries/cuprated/src/rpc/handlers/json_rpc.rs) +- [Binary](https://github.com/Cuprate/cuprate/tree/main/binaries/cuprated/src/rpc/handlers/bin.rs) +- [Other JSON](https://github.com/Cuprate/cuprate/tree/main/binaries/cuprated/src/rpc/handlers/other_json.rs) + +The main job of the handler function is to do what is necessary to map the request type into the response type. This often requires calling deeper into other parts of the `cuprated` such as the blockchain service. After the necessary data is collected, the response is created and returned. + +In general, the handler functions are 1-1 with RPC calls themselves, e.g. `/get_height` is handled by [`get_height()`](https://github.com/Cuprate/cuprate/blob/e6efdbb437948a3c38938dcbb75f0c37d7e1e9d0/binaries/cuprated/src/rpc/handlers/other_json.rs#L110-L123), although there are some shared internal functions such as [`/get_outs` and `/get_outs.bin`](https://github.com/Cuprate/cuprate/blob/e6efdbb437948a3c38938dcbb75f0c37d7e1e9d0/binaries/cuprated/src/rpc/handlers/shared.rs#L35-L75). \ No newline at end of file diff --git a/books/architecture/src/rpc/handler/intro.md b/books/architecture/src/rpc/handler/intro.md deleted file mode 100644 index e420a5c7c..000000000 --- a/books/architecture/src/rpc/handler/intro.md +++ /dev/null @@ -1,8 +0,0 @@ -# The handler -The handlers (functions that map requests into responses) are / can be generic with `cuprate-rpc-interface`. - -The main handlers used by Cuprate is implemented in `cuprated` itself, it implements the standard RPC handlers modeled after `monerod`. - -- JSON-RPC handlers: -- Binary handlers: -- Other JSON handlers: \ No newline at end of file From 020ba2e22378076c989851a98f5d3464cfead700 Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Wed, 5 Feb 2025 16:34:55 -0500 Subject: [PATCH 5/5] remove scratchpad --- SCRATCHPAD.txt | 24 ------------------------ 1 file changed, 24 deletions(-) delete mode 100644 SCRATCHPAD.txt diff --git a/SCRATCHPAD.txt b/SCRATCHPAD.txt deleted file mode 100644 index a0ad26945..000000000 --- a/SCRATCHPAD.txt +++ /dev/null @@ -1,24 +0,0 @@ -RPC stuff that needs to be written in the architecture book: - -## General -- diagram showing full pipeline from input to output with crate responsibilities listed along the line - -## The handler -- {json-rpc, binary, other} handler functions implemented in `cuprated` -- handler -> helper function -> internal component's `Service` - -## Unsupported RPC calls / RPC calls with different behavior -- https://github.com/Cuprate/cuprate/issues/278 -- binary strings -> full JSON: `get_transaction_pool_backlog`, `get_output_distribution` -- not in `monerod` yet: `get_tx_ids_loose` - -## Differences with monerod (Request strictness) -Some of `monerod`'s RPC request types contain fields not for users to provide, -but for internal usage within the RPC handlers and `monerod` itself, some examples: -- - -Unless one of these actually allows something unintentionally bad to happen, this is mostly an unimportant detail. - - -Practically, it means users can provide these fields and `monerod` will deserialize them -and accept them fine, while `cuprated` will not because they are not part of the type.