22
33Lumera Supernode is a companion application for Lumera validators who want to provide cascade, sense, and other services to earn rewards.
44
5- ## Prerequisites
5+ ## gRPC API
66
7- Before installing and running the Lumera Supernode, ensure you have the following prerequisites installed :
7+ The supernode exposes two main gRPC services :
88
9- ### Install Build Essentials
9+ ### SupernodeService
1010
11- ``` bash
12- # Ubuntu/Debian
13- sudo apt update
14- sudo apt install build-essential
15- ```
16-
17- ### Enable CGO
11+ Provides system status and monitoring information.
1812
19- CGO must be enabled for the supernode to compile and run properly. Set the environment variable:
20-
21- ``` bash
22- export CGO_ENABLED=1
13+ ** Service Definition:**
14+ ``` protobuf
15+ service SupernodeService {
16+ rpc GetStatus(StatusRequest) returns (StatusResponse);
17+ }
2318```
2419
25- To make this permanent, add it to your shell profile:
20+ ** StatusResponse includes:**
21+ - ` CPU ` - CPU usage and remaining capacity
22+ - ` Memory ` - Total, used, available memory and usage percentage
23+ - ` ServiceTasks ` - Task information for each active service
24+ - ` available_services ` - List of available service names
2625
27- ``` bash
28- echo ' export CGO_ENABLED=1' >> ~ /.bashrc
29- source ~ /.bashrc
30- ```
31-
32- ## Installation
26+ ### CascadeService
3327
34- ### 1. Download the Binary
28+ Handles cascade operations for data storage and retrieval.
3529
36- Download the latest release from GitHub:
30+ ** Service Definition:**
31+ ``` protobuf
32+ service CascadeService {
33+ rpc Register (stream RegisterRequest) returns (stream RegisterResponse);
34+ rpc Download (DownloadRequest) returns (stream DownloadResponse);
35+ }
36+ ```
3737
38- ### 2. Create Configuration File
38+ ** Register Operation:**
39+ ``` protobuf
40+ message RegisterRequest {
41+ oneof request_type {
42+ DataChunk chunk = 1;
43+ Metadata metadata = 2;
44+ }
45+ }
3946
40- Create a ` config.yml ` file in your base directory (default: ` ~/.supernode/config.yml ` ):
47+ message DataChunk {
48+ bytes data = 1;
49+ }
4150
42- ``` yaml
43- # Supernode Configuration
44- supernode :
45- key_name : " mykey" # The name you'll use when creating your key
46- identity : " " # The address you get back after getting the key
47- ip_address : " 0.0.0.0"
48- port : 4444
51+ message Metadata {
52+ string task_id = 1;
53+ string action_id = 2;
54+ }
4955
50- # Keyring Configuration
51- keyring :
52- backend : " test" # Options: test, file, os
53- dir : " keys"
56+ message RegisterResponse {
57+ SupernodeEventType event_type = 1;
58+ string message = 2;
59+ string tx_hash = 3;
60+ }
61+ ```
5462
55- # P2P Network Configuration
56- p2p :
57- listen_address : " 0.0.0.0"
58- port : 4445
59- data_dir : " data/p2p"
63+ ** Download Operation:**
64+ ``` protobuf
65+ message DownloadRequest {
66+ string action_id = 1;
67+ string signature = 2;
68+ }
6069
61- # Lumera Chain Configuration
62- lumera :
63- grpc_addr : " localhost:9090"
64- chain_id : " lumera"
70+ message DownloadResponse {
71+ oneof response_type {
72+ DownloadEvent event = 1;
73+ DataChunk chunk = 2;
74+ }
75+ }
6576
66- # RaptorQ Configuration
67- raptorq :
68- files_dir : " raptorq_files"
77+ message DownloadEvent {
78+ SupernodeEventType event_type = 1;
79+ string message = 2;
80+ }
6981```
7082
71- ## Initialization and Key Management
83+ ** Event Types:**
84+ - ` ACTION_RETRIEVED ` , ` ACTION_FEE_VERIFIED ` , ` TOP_SUPERNODE_CHECK_PASSED `
85+ - ` METADATA_DECODED ` , ` DATA_HASH_VERIFIED ` , ` INPUT_ENCODED `
86+ - ` SIGNATURE_VERIFIED ` , ` RQID_GENERATED ` , ` RQID_VERIFIED `
87+ - ` ARTEFACTS_STORED ` , ` ACTION_FINALIZED ` , ` ARTEFACTS_DOWNLOADED `
7288
73- ### Initialize a Supernode
89+ ## CLI Commands
7490
75- The easiest way to set up a supernode is to use the ` init` command, which creates a configuration file and sets up keys in one step:
91+ ### Core Commands
92+
93+ #### ` supernode init `
94+ Initialize a new supernode with interactive setup.
7695
7796``` bash
78- supernode init mykey --chain-id lumera
97+ supernode init # Interactive setup
98+ supernode init --force # Override existing installation
99+ supernode init -y # Use defaults, skip prompts
100+ supernode init --keyring-backend test # Specify keyring backend with -y
79101```
80102
81- This will :
82- 1. Create a `config.yml` file in your base directory (default : ` ~/.supernode/config.yml` )
83- 2. Generate a new key with the specified name
84- 3. Update the configuration with the key's address
85- 4. Output the key information, including the mnemonic
103+ ** Features: **
104+ - Creates ` ~/.supernode/config.yml `
105+ - Sets up keyring (test, file, or os backend)
106+ - Key recovery from mnemonic or generates new key
107+ - Network configuration (gRPC address, ports, chain ID)
86108
87- To recover an existing key during initialization :
109+ #### ` supernode start `
110+ Start the supernode service.
88111
89112``` bash
90- supernode init mykey --recover --mnemonic "your mnemonic words here" --chain-id lumera
113+ supernode start # Use default config directory
114+ supernode start -d /path/to/dir # Use custom base directory
91115```
92116
93- Additional options :
94- ` ` ` bash
95- # Use a specific keyring backend
96- supernode init mykey --keyring-backend file --chain-id lumera
117+ ** Initializes:**
118+ - P2P networking service
119+ - gRPC server (default port 4444)
120+ - Cascade service for data operations
121+ - Connection to Lumera validator node
97122
98- # Use a custom keyring directory
99- supernode init mykey --keyring-dir /path/to/keys --chain-id lumera
123+ #### ` supernode version `
124+ Display version information.
100125
101- # Use a custom base directory
102- supernode init -d /path/to/basedir mykey --chain-id lumera
126+ ``` bash
127+ supernode version
103128```
104129
105- # ## Manual Key Management
106-
107- If you prefer to manage keys manually, you can use the following commands :
108-
109- # ### Create a New Key
130+ ### Key Management
110131
111- Create a new key (use the same name you specified in your config) :
132+ #### ` supernode keys list `
133+ List all keys in the keyring with addresses.
112134
113135``` bash
114- supernode keys add mykey
136+ supernode keys list
115137```
116138
117- This will output an address like :
139+ ** Output format: **
118140```
119- lumera15t2e8gjgmuqtj4jzjqfkf3tf5l8vqw69hmrzmr
141+ NAME ADDRESS
142+ ---- -------
143+ mykey (selected) lumera15t2e8gjgmuqtj4jzjqfkf3tf5l8vqw69hmrzmr
144+ backup lumera1abc...xyz
120145```
121146
122- # ### Recover an Existing Key
147+ #### ` supernode keys add <name> `
148+ Create a new key (generates mnemonic).
123149
124- If you have an existing mnemonic phrase :
150+ #### ` supernode keys recover <name> `
151+ Recover key from existing mnemonic phrase.
125152
126- ` ` ` bash
127- supernode keys recover mykey <MNEMONIC> # Use quotes if the mnemonic contains spaces, e.g., "word1 word2 word3"
128- ` ` `
153+ ### Configuration Management
129154
130- # ### List Keys
155+ #### ` supernode config list `
156+ Display current configuration parameters.
131157
132158``` bash
133- supernode keys list
159+ supernode config list
134160```
135161
136- # ### Update Configuration with Your Address
162+ ** Shows:**
163+ - Key Name, Address, Supernode Address/Port
164+ - Keyring Backend, Lumera gRPC Address, Chain ID
137165
138- ⚠️ **IMPORTANT:** After manually generating or recovering a key, you MUST update your `config.yml` with the generated address :
166+ #### ` supernode config update `
167+ Interactive configuration parameter updates.
139168
140- ` ` ` yaml
141- supernode:
142- key_name: "mykey"
143- identity: "lumera15t2e8gjgmuqtj4jzjqfkf3tf5l8vqw69hmrzmr" # Your actual address
144- ip_address: "0.0.0.0"
145- port: 4444
146- # ... rest of config
169+ ``` bash
170+ supernode config update
147171```
148172
149- Note : This step is done automatically when using the `init` command.
173+ ** Updatable parameters:**
174+ - Supernode IP Address and Port
175+ - Lumera gRPC Address and Chain ID
176+ - Key Name (with key selection from keyring)
177+ - Keyring Backend (with key migration)
150178
151- # # Running the Supernode
179+ ### Global Flags
152180
153- # ## Start the Supernode
181+ #### ` --basedir, -d `
182+ Specify custom base directory (default: ` ~/.supernode ` ).
154183
155184``` bash
156- supernode start
157- ` ` `
158-
159- # ## Using Custom Configuration
160-
161- ` ` ` bash
162- # Use specific config file
163- supernode start -c /path/to/config.yml
164-
165- # Use custom base directory
166- supernode start -d /path/to/basedir
185+ supernode start -d /custom/path
186+ supernode config list -d /custom/path
167187```
168188
169189## Configuration Parameters
@@ -182,42 +202,3 @@ supernode start -d /path/to/basedir
182202| ` lumera.grpc_addr ` | gRPC endpoint of Lumera validator node | ** Yes** | - | ` "localhost:9090" ` | Must be accessible from supernode |
183203| ` lumera.chain_id ` | Lumera blockchain chain identifier | ** Yes** | - | ` "lumera" ` | Must match the actual chain ID |
184204| ` raptorq.files_dir ` | Directory to store RaptorQ files | No | ` "raptorq_files" ` | ` "raptorq_files" ` | Relative paths are appended to basedir, absolute paths used as-is |
185-
186- # # Command Line Flags
187-
188- The supernode binary supports the following command-line flags :
189-
190- | Flag | Short | Description | Value Type | Example | Default |
191- |------|-------|-------------|------------|---------|---------|
192- | `--config` | `-c` | Path to configuration file | String | `-c /path/to/config.yml` | `config.yml` in basedir (`~/.supernode/config.yml`) |
193- | `--basedir` | `-d` | Base directory for data storage | String | `-d /custom/path` | `~/.supernode` |
194-
195- # ## Usage Examples
196-
197- ` ` ` bash
198- # Use default config.yml in basedir (~/.supernode/config.yml), with ~/.supernode as basedir
199- supernode start
200-
201- # Use custom config file
202- supernode start -c /etc/supernode/config.yml
203- supernode start --config /etc/supernode/config.yml
204-
205- # Use custom base directory
206- supernode start -d /opt/supernode
207- supernode start --basedir /opt/supernode
208-
209- # Combine flags
210- supernode start -c /etc/supernode/config.yml -d /opt/supernode
211- ` ` `
212-
213- ⚠️ **CRITICAL : Consistent Flag Usage Across Commands**
214-
215- If you use custom flags (`--config` or `--basedir`) for key management operations, you **MUST** use the same flags for ALL subsequent commands, including the `start` command. Otherwise, your configuration will break and keys will not be found.
216-
217- # ## Additional Important Notes:
218-
219- - Make sure you have sufficient balance in your Lumera account to broadcast transactions
220- - The P2P port (4445) should not be changed from the default
221- - Your `key_name` in the config must match the name you used when creating the key
222- - Your `identity` in the config must match the address generated for your key
223- - Ensure your Lumera validator node is running and accessible at the configured gRPC address
0 commit comments