Skip to content

Commit a39857b

Browse files
tizocdannywillems
authored andcommitted
chore(handover): Format markdown
1 parent 33cf613 commit a39857b

File tree

81 files changed

+4105
-1558
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

81 files changed

+4105
-1558
lines changed

docs/handover/README.md

Lines changed: 156 additions & 50 deletions
Large diffs are not rendered by default.

docs/handover/adding-rpc-endpoints.md

Lines changed: 48 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,79 +1,110 @@
11
# Adding RPC Endpoints Guide
22

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

57
## Prerequisites
68

79
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
1015
- [Services](services.md) - Service layer integration
1116

1217
## RPC Architecture Overview
1318

1419
OpenMina's RPC system follows this flow:
20+
1521
```
1622
HTTP Request → RPC Action → RPC Reducer → RPC Effect → Service → Response
1723
```
1824

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

2129
## Files to Modify
2230

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
3147

3248
## Reference Examples
3349

3450
Study these existing endpoints in the codebase to understand the patterns:
3551

3652
**Simple Endpoints:**
53+
3754
- `StatusGet` - Basic node status information
38-
- `HeartbeatGet` - Simple health check
55+
- `HeartbeatGet` - Simple health check
3956
- `SyncStatsGet` - Component statistics
4057

4158
**Parameterized Endpoints:**
59+
4260
- `ActionStatsGet` - Takes query parameters
4361
- `LedgerAccountsGet` - Filtered data retrieval
4462

4563
**Streaming Endpoints:**
64+
4665
- Look at WebRTC signaling endpoints for `multishot_request` patterns
4766

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

5070
## Key RPC-Specific Patterns
5171

5272
### Request/Response Flow
73+
5374
- HTTP requests come in via `oneshot_request` or `multishot_request`
5475
- RPC actions include an `rpc_id` field for tracking
5576
- Effects call service `respond_*` methods to send responses back
5677
- The framework handles request state tracking automatically
5778

5879
### 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)
6083
- HTTP implementation is in `node/native/src/http_server.rs`
6184
- WASM bindings are in `node/common/src/service/rpc/sender.rs`
6285

6386
### Streaming vs Single Responses
87+
6488
- Use `oneshot_request` for endpoints that return one response
6589
- Use `multishot_request` for endpoints that return multiple responses over time
6690
- Most endpoints use `oneshot_request`
6791

6892
## WASM Frontend Integration
6993

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()`).
7199

72100
## Testing
73101

74102
Test RPC endpoints with curl against the HTTP server:
103+
75104
```bash
76105
curl http://localhost:3000/your-endpoint
77106
```
78107

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

Comments
 (0)