book/architecture: RPC handlers and related

books/architecture/src/SUMMARY.md

@@ -70,18 +70,17 @@
         - [🟢 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)
         - [🟢 JSON formatting](rpc/differences/json-formatting.md)
         - [🟢 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)
 
 ---
 

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 |

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`
+> - <https://github.com/Cuprate/cuprate/issues/278>

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).

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.

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 |
+
+`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.

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