Skip to content

Commit c6c6dc9

Browse files
dpshadedpshade
committed
docs: enhance router configuration documentation for clarity and structure
- Updated the "Joining a Router Network" section with clearer configuration examples and comments. - Improved formatting and organization of JSON configuration snippets for better readability. - Added detailed comments to explain various configuration parameters and their purposes. - Streamlined the overall documentation for consistency and ease of understanding.
1 parent 93d02a0 commit c6c6dc9

File tree

1 file changed

+137
-98
lines changed

1 file changed

+137
-98
lines changed

‎docs/run/joining-running-a-router.md‎

Lines changed: 137 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -13,22 +13,15 @@ Router networks in HyperBEAM have two distinct roles that are often confused:
1313
| **TEE Node (SNP)** | Recommended | Secure, attested computation (hardware isolation) |
1414
| **Router Registration** | Optional | Registering/joining a router (TEE not required) |
1515

16-
- **You can join or run a router without HB-OS.**
17-
- **If you want to run a TEE node, HB-OS or an equivalent TEE setup is recommended for convenience and security.**
16+
- *You can join or run a router without HB-OS.*
17+
- *If you want to run a TEE node, HB-OS or an equivalent TEE setup is recommended for convenience and security.*
1818

1919
## Configuration Files: config.json vs config.flat
2020

2121
Configuration can be set in either `config.json` (JSON syntax) or `config.flat` (flat syntax). The examples below use JSON for clarity, but you can use either format depending on your deployment. The syntax differs:
2222

2323
- **config.json** uses standard JSON structure (see examples below)
24-
- **config.flat** uses key-value pairs, e.g.:
25-
26-
```flat
27-
operator: trustless
28-
initialized: permanent
29-
snp_trusted: []
30-
# ...and so on
31-
```
24+
- **config.flat** uses key-value pairs
3225

3326
## Joining a Router Network (Worker Node)
3427

@@ -40,55 +33,89 @@ Most users want to **join** an existing router to offer computational services.
4033

4134
Use the following configuration as a template for your worker node:
4235

43-
```json
36+
```jsonc
4437
{
45-
"operator": "trustless",
46-
"initialized": "permanent",
47-
"snp_trusted": [],
48-
"on": {
49-
"request": {
50-
"device": "p4@1.0",
51-
"ledger-device": "lua@5.3a",
52-
"pricing-device": "simple-pay@1.0",
53-
"ledger-path": "/ledger~node-process@1.0",
54-
"module": ""
38+
// ─── Initial Configuration ─────────────────────────────────────────────────
39+
// Lock this configuration so it cannot be changed again
40+
"operator": "trustless",
41+
"initialized": "permanent",
42+
43+
// ─── SNP-Based TEE Attestation Parameters ──────────────────────────────────
44+
// These values let the TEE verify its own environment—and any other VM
45+
// instantiated from the same image—before granting access.
46+
"snp_trusted": [],
47+
48+
// ─── Request/Response Processing Configuration ─────────────────────────────
49+
// Defines how requests and responses are processed through the p4 device
50+
"on": {
51+
"request": {
52+
"device": "p4@1.0",
53+
"ledger-device": "lua@5.3a",
54+
"pricing-device": "simple-pay@1.0",
55+
"ledger-path": "/ledger~node-process@1.0",
56+
"module": "" // Automatically injected
57+
},
58+
"response": {
59+
"device": "p4@1.0",
60+
"ledger-device": "lua@5.3a",
61+
"pricing-device": "simple-pay@1.0",
62+
"ledger-path": "/ledger~node-process@1.0",
63+
"module": "" // Automatically injected
64+
}
5565
},
56-
"response": {
57-
"device": "p4@1.0",
58-
"ledger-device": "lua@5.3a",
59-
"pricing-device": "simple-pay@1.0",
60-
"ledger-path": "/ledger~node-process@1.0",
61-
"module": ""
62-
}
63-
},
64-
"p4_non_chargable_routes": [
65-
{"template": "/.*~node-process@1.0/.*"},
66-
{"template": "/.*~greenzone@1.0/.*"},
67-
{"template": "/.*~router@1.0/.*"},
68-
{"template": "/.*~meta@1.0/.*"},
69-
{"template": "/schedule"},
70-
{"template": "/push"},
71-
{"template": "/~hyperbuddy@1.0/.*"}
72-
],
73-
"node_process_spawn_codec": "ans104@1.0",
74-
"node_processes": {
75-
"ledger": {
76-
"device": "process@1.0",
77-
"execution-device": "lua@5.3a",
78-
"scheduler-device": "scheduler@1.0",
79-
"authority-match": 1,
80-
"admin": "",
81-
"token": "",
82-
"module": "",
83-
"authority": ""
84-
}
85-
},
86-
"router_opts": {
87-
"offered": [ /* ... */ ]
88-
},
89-
"green_zone_peer_location": "",
90-
"green_zone_peer_id": "",
91-
"p4_recipient": ""
66+
67+
// ─── Non-Chargeable Routes Configuration ──────────────────────────────────
68+
// Routes that should not incur charges when accessed through p4
69+
"p4_non_chargable_routes": [
70+
{ "template": "/.*~node-process@1.0/.*" },
71+
{ "template": "/.*~greenzone@1.0/.*" },
72+
{ "template": "/.*~router@1.0/.*" },
73+
{ "template": "/.*~meta@1.0/.*" },
74+
{ "template": "/schedule" },
75+
{ "template": "/push" },
76+
{ "template": "/~hyperbuddy@1.0/.*" }
77+
],
78+
79+
// ─── Node Process Spawn Configuration ─────────────────────────────────────
80+
// Codec used for spawning new node processes
81+
"node_process_spawn_codec": "ans104@1.0",
82+
83+
// ─── Node Process Definitions ─────────────────────────────────────────────
84+
// Configuration for individual node processes
85+
"node_processes": {
86+
"ledger": {
87+
"device": "process@1.0",
88+
"execution-device": "lua@5.3a",
89+
"scheduler-device": "scheduler@1.0",
90+
"authority-match": 1,
91+
"admin": "", // Automatically injected
92+
"token": "", // Automatically injected
93+
"module": "", // Automatically injected
94+
"authority": "" // Automatically injected
95+
}
96+
},
97+
98+
// ─── Router Registration Options ──────────────────────────────────────────
99+
// Configuration for how processes register with the router
100+
"router_opts": {
101+
"offered": [
102+
// {
103+
// "registration-peer": {}, // Automatically injected
104+
// "template": "/*~process@1.0/*", // The routes that the node will register with
105+
// "prefix": "", // Automatically injected
106+
// "price": 4500000 // Registration fee in smallest units
107+
// }
108+
]
109+
},
110+
111+
// ─── Greenzone Registration Options ────────────────────────────────────────
112+
// Configuration for how processes register with the greenzone
113+
"green_zone_peer_location": "", // Automatically injected
114+
"green_zone_peer_id": "", // Automatically injected
115+
116+
// ─── P4 Recipient ──────────────────────────────────────────────────────────
117+
// The Address of the node that will receive the P4 messages
118+
"p4_recipient": "" // Automatically injected
92119
}
93120
```
94121

@@ -101,12 +128,12 @@ Perform the following API calls in order:
101128
- Example:
102129
```javascript
103130
const response = await fetch(`${nodeUrl}/~meta@1.0/info`, {
104-
method: 'POST',
105-
headers: {
106-
'codec-device': 'json@1.0',
107-
'accept-bundle': true
108-
},
109-
body: JSON.stringify(configContent)
131+
method: 'POST',
132+
headers: {
133+
'codec-device': 'json@1.0',
134+
'accept-bundle': true
135+
},
136+
body: JSON.stringify(configContent)
110137
});
111138
```
112139

@@ -145,45 +172,57 @@ If you want to **operate a router** that manages other worker nodes:
145172
146173
### Example Router Configuration (config.json example)
147174
148-
```json
175+
```jsonc
149176
{
150-
"on": {
151-
"request": {
152-
"device": "router@1.0",
153-
"path": "preprocess",
154-
"commit-request": true
155-
}
156-
},
157-
"router_opts": {
158-
"provider": {
159-
"path": "/router~node-process@1.0/compute/routes~message@1.0"
177+
// ─── Router Node Preprocessing Settings ───────────────────────────────────
178+
// Defines the router process and how it preprocesses incoming requests
179+
"on": {
180+
"request": {
181+
"device": "router@1.0",
182+
"path": "preprocess",
183+
"commit-request": true // Enable request commitment for routing
184+
}
160185
},
161-
"registrar": {
162-
"path": "/router~node-process@1.0"
186+
187+
// ─── Route Provider Configuration ─────────────────────────────────────────
188+
// Specifies where to get routing information from the router node process
189+
"router_opts": {
190+
"provider": {
191+
"path": "/router~node-process@1.0/compute/routes~message@1.0"
192+
},
193+
"registrar": {
194+
"path": "/router~node-process@1.0"
195+
},
196+
"registrar-path": "schedule"
163197
},
164-
"registrar-path": "schedule"
165-
},
166-
"relay_allow_commit_request": true,
167-
"node_processes": {
168-
"router": {
169-
"type": "Process",
170-
"device": "process@1.0",
171-
"execution-device": "lua@5.3a",
172-
"scheduler-device": "scheduler@1.0",
173-
"pricing-weight": 9,
174-
"performance-weight": 1,
175-
"score-preference": 4,
176-
"performance-period": 2,
177-
"initial-performance": 1000,
178-
"is-admissible": {
179-
"path": "default",
180-
"default": "false"
181-
},
182-
"module": "",
183-
"trusted-peer": "",
184-
"trusted": ""
198+
199+
// ─── Relay Configuration ──────────────────────────────────────────────────
200+
// Allow the relay to commit requests when forwarding
201+
"relay_allow_commit_request": true,
202+
203+
// ─── Router Node Process Configuration ────────────────────────────────────
204+
// Specifies the Lua-based router logic, weights for scoring, and admission check
205+
"node_processes": {
206+
"router": {
207+
"type": "Process",
208+
"device": "process@1.0",
209+
"execution-device": "lua@5.3a",
210+
"scheduler-device": "scheduler@1.0",
211+
"pricing-weight": 9, // Weight for pricing in routing decisions
212+
"performance-weight": 1, // Weight for performance in routing decisions
213+
"score-preference": 4, // Preference scoring for route selection
214+
"performance-period": 2, // Period for performance measurement
215+
"initial-performance": 1000, // Initial performance score
216+
// Default admission policy (currently set to false)
217+
"is-admissible": {
218+
"path": "default",
219+
"default": "false"
220+
},
221+
"module": "", // Automatically injected
222+
"trusted-peer": "", // Automatically injected
223+
"trusted": "" // Automatically injected
224+
}
185225
}
186-
}
187226
}
188227
```
189228

0 commit comments

Comments
 (0)