|
1 | 1 | # Adding RPC Endpoints Guide
|
2 | 2 |
|
3 |
| -This guide explains how to navigate the codebase when adding new RPC endpoints to OpenMina, focusing on the files and architectural patterns specific to RPC functionality. |
| 3 | +This guide explains how to navigate the codebase when adding new RPC endpoints |
| 4 | +to OpenMina, focusing on the files and architectural patterns specific to RPC |
| 5 | +functionality. |
4 | 6 |
|
5 | 7 | ## Prerequisites
|
6 | 8 |
|
7 | 9 | Before adding RPC endpoints, understand:
|
8 |
| -- [State Machine Development Guide](state-machine-development-guide.md) - Core Redux patterns |
9 |
| -- [Architecture Walkthrough](architecture-walkthrough.md) - Overall system design |
| 10 | + |
| 11 | +- [State Machine Development Guide](state-machine-development-guide.md) - Core |
| 12 | + Redux patterns |
| 13 | +- [Architecture Walkthrough](architecture-walkthrough.md) - Overall system |
| 14 | + design |
10 | 15 | - [Services](services.md) - Service layer integration
|
11 | 16 |
|
12 | 17 | ## RPC Architecture Overview
|
13 | 18 |
|
14 | 19 | OpenMina's RPC system follows this flow:
|
| 20 | + |
15 | 21 | ```
|
16 | 22 | HTTP Request → RPC Action → RPC Reducer → RPC Effect → Service → Response
|
17 | 23 | ```
|
18 | 24 |
|
19 |
| -The RPC layer uses the same Redux patterns as other components but adds HTTP server integration and service response handling. This guide shows you where to make changes for each step. |
| 25 | +The RPC layer uses the same Redux patterns as other components but adds HTTP |
| 26 | +server integration and service response handling. This guide shows you where to |
| 27 | +make changes for each step. |
20 | 28 |
|
21 | 29 | ## Files to Modify
|
22 | 30 |
|
23 |
| -1. **Request/Response Types** (`node/src/rpc/mod.rs`) - Add to `RpcRequest` enum and define response type alias |
24 |
| -2. **RPC Actions** (`node/src/rpc/rpc_actions.rs`) - Add variant with `rpc_id` field and enabling condition |
25 |
| -3. **RPC Reducer** (`node/src/rpc/rpc_reducer.rs`) - Implement business logic and dispatch effectful action with response data |
26 |
| -4. **Effectful Action** (`node/src/rpc_effectful/rpc_effectful_action.rs`) - Add variant that carries the response data |
27 |
| -5. **Effects** (`node/src/rpc_effectful/rpc_effectful_effects.rs`) - Thin wrapper that calls service respond method |
28 |
| -6. **Service Interface** (`node/src/rpc_effectful/rpc_service.rs`) - Add `respond_*` method to `RpcService` trait |
29 |
| -7. **Service Implementation** (`node/native/src/http_server.rs`) - Implement service method (usually just calls `self.respond`) |
30 |
| -8. **HTTP Routes** (`node/native/src/http_server.rs`) - Add endpoint to `rpc_router` function |
| 31 | +1. **Request/Response Types** (`node/src/rpc/mod.rs`) - Add to `RpcRequest` enum |
| 32 | + and define response type alias |
| 33 | +2. **RPC Actions** (`node/src/rpc/rpc_actions.rs`) - Add variant with `rpc_id` |
| 34 | + field and enabling condition |
| 35 | +3. **RPC Reducer** (`node/src/rpc/rpc_reducer.rs`) - Implement business logic |
| 36 | + and dispatch effectful action with response data |
| 37 | +4. **Effectful Action** (`node/src/rpc_effectful/rpc_effectful_action.rs`) - Add |
| 38 | + variant that carries the response data |
| 39 | +5. **Effects** (`node/src/rpc_effectful/rpc_effectful_effects.rs`) - Thin |
| 40 | + wrapper that calls service respond method |
| 41 | +6. **Service Interface** (`node/src/rpc_effectful/rpc_service.rs`) - Add |
| 42 | + `respond_*` method to `RpcService` trait |
| 43 | +7. **Service Implementation** (`node/native/src/http_server.rs`) - Implement |
| 44 | + service method (usually just calls `self.respond`) |
| 45 | +8. **HTTP Routes** (`node/native/src/http_server.rs`) - Add endpoint to |
| 46 | + `rpc_router` function |
31 | 47 |
|
32 | 48 | ## Reference Examples
|
33 | 49 |
|
34 | 50 | Study these existing endpoints in the codebase to understand the patterns:
|
35 | 51 |
|
36 | 52 | **Simple Endpoints:**
|
| 53 | + |
37 | 54 | - `StatusGet` - Basic node status information
|
38 |
| -- `HeartbeatGet` - Simple health check |
| 55 | +- `HeartbeatGet` - Simple health check |
39 | 56 | - `SyncStatsGet` - Component statistics
|
40 | 57 |
|
41 | 58 | **Parameterized Endpoints:**
|
| 59 | + |
42 | 60 | - `ActionStatsGet` - Takes query parameters
|
43 | 61 | - `LedgerAccountsGet` - Filtered data retrieval
|
44 | 62 |
|
45 | 63 | **Streaming Endpoints:**
|
| 64 | + |
46 | 65 | - Look at WebRTC signaling endpoints for `multishot_request` patterns
|
47 | 66 |
|
48 |
| -Each endpoint follows the same 8-step pattern above. The business logic in effects varies, but the structural pattern is consistent. |
| 67 | +Each endpoint follows the same 8-step pattern above. The business logic in |
| 68 | +effects varies, but the structural pattern is consistent. |
49 | 69 |
|
50 | 70 | ## Key RPC-Specific Patterns
|
51 | 71 |
|
52 | 72 | ### Request/Response Flow
|
| 73 | + |
53 | 74 | - HTTP requests come in via `oneshot_request` or `multishot_request`
|
54 | 75 | - RPC actions include an `rpc_id` field for tracking
|
55 | 76 | - Effects call service `respond_*` methods to send responses back
|
56 | 77 | - The framework handles request state tracking automatically
|
57 | 78 |
|
58 | 79 | ### Service Layer Integration
|
59 |
| -- The `RpcService` trait abstracts over different transport mechanisms (HTTP, WASM) |
| 80 | + |
| 81 | +- The `RpcService` trait abstracts over different transport mechanisms (HTTP, |
| 82 | + WASM) |
60 | 83 | - HTTP implementation is in `node/native/src/http_server.rs`
|
61 | 84 | - WASM bindings are in `node/common/src/service/rpc/sender.rs`
|
62 | 85 |
|
63 | 86 | ### Streaming vs Single Responses
|
| 87 | + |
64 | 88 | - Use `oneshot_request` for endpoints that return one response
|
65 | 89 | - Use `multishot_request` for endpoints that return multiple responses over time
|
66 | 90 | - Most endpoints use `oneshot_request`
|
67 | 91 |
|
68 | 92 | ## WASM Frontend Integration
|
69 | 93 |
|
70 |
| -WASM bindings are in `node/common/src/service/rpc/` organized across multiple helper structs (`State`, `Stats`, `Ledger`, etc.) plus direct methods on `RpcSender`. Check `frontend/src/app/core/services/web-node.service.ts` to see how they're accessed from the frontend (e.g., `webnode.state().peers()`, `webnode.stats().sync()`). |
| 94 | +WASM bindings are in `node/common/src/service/rpc/` organized across multiple |
| 95 | +helper structs (`State`, `Stats`, `Ledger`, etc.) plus direct methods on |
| 96 | +`RpcSender`. Check `frontend/src/app/core/services/web-node.service.ts` to see |
| 97 | +how they're accessed from the frontend (e.g., `webnode.state().peers()`, |
| 98 | +`webnode.stats().sync()`). |
71 | 99 |
|
72 | 100 | ## Testing
|
73 | 101 |
|
74 | 102 | Test RPC endpoints with curl against the HTTP server:
|
| 103 | + |
75 | 104 | ```bash
|
76 | 105 | curl http://localhost:3000/your-endpoint
|
77 | 106 | ```
|
78 | 107 |
|
79 |
| -The RPC layer follows standard OpenMina Redux patterns with the addition of HTTP routing and service response handling. Study existing endpoints to understand the complete flow. |
| 108 | +The RPC layer follows standard OpenMina Redux patterns with the addition of HTTP |
| 109 | +routing and service response handling. Study existing endpoints to understand |
| 110 | +the complete flow. |
0 commit comments