node-api.md
1 # Node API Reference 2 3 **Version:** 1.0.0 4 **Domain:** nodes 5 **Stability:** stable 6 **Last Updated:** 2026-01-23 7 **Source:** components/nodes.cspec 8 9 ## Overview 10 11 This document describes the API for interacting with Alpha/Delta Network nodes, including REST endpoints, P2P protocol, and node configuration. 12 13 --- 14 15 ## REST API 16 17 ### Alpha Chain API 18 19 **Base URL:** `http://localhost:3030/alpha` 20 21 #### Endpoints 22 23 ##### `GET /block/{height}` 24 25 Get block by height. 26 27 **Inputs:** 28 - `height: u64` - Block height 29 30 **Returns:** 31 - `block` - Block object with transactions and metadata 32 33 **Example:** 34 ```bash 35 curl http://localhost:3030/alpha/block/12345 36 ``` 37 38 --- 39 40 ##### `GET /transaction/{id}` 41 42 Get transaction by ID. 43 44 **Inputs:** 45 - `id: string` - Transaction identifier 46 47 **Returns:** 48 - `transaction` - Transaction object 49 50 **Example:** 51 ```bash 52 curl http://localhost:3030/alpha/transaction/at1abc... 53 ``` 54 55 --- 56 57 ##### `POST /transaction/broadcast` 58 59 Broadcast a transaction to the network. 60 61 **Inputs:** 62 - `tx: transaction` - Signed transaction object 63 64 **Returns:** 65 - `tx_id: string` - Transaction identifier 66 67 **Example:** 68 ```bash 69 curl -X POST http://localhost:3030/alpha/transaction/broadcast \ 70 -H "Content-Type: application/json" \ 71 -d @transaction.json 72 ``` 73 74 --- 75 76 ##### `GET /committee/latest` 77 78 Get the latest committee information. 79 80 **Returns:** 81 - Committee members and voting power distribution 82 83 --- 84 85 ##### `GET /peers/count` 86 87 Get number of connected peers. 88 89 **Returns:** 90 - `count: number` 91 92 --- 93 94 ##### `GET /state/root` 95 96 Get current state root hash. 97 98 **Returns:** 99 - `root: string` - State root hash 100 101 --- 102 103 ##### `GET /governance/proposals` 104 105 Get all active governance proposals (Alpha governors only). 106 107 **Returns:** 108 - Array of `NetworkUpgradeProposal` objects 109 110 **Example:** 111 ```bash 112 curl http://localhost:3030/alpha/governance/proposals 113 ``` 114 115 --- 116 117 ##### `GET /governance/proposal/{id}` 118 119 Get specific governance proposal details. 120 121 **Inputs:** 122 - `id: string` - Proposal identifier 123 124 **Returns:** 125 - `NetworkUpgradeProposal` object 126 127 --- 128 129 ##### `POST /governance/vote` 130 131 Submit a governance vote (governors only). 132 133 **Inputs:** 134 - `proposal_id: string` 135 - `vote: "Yes" | "No" | "Abstain"` 136 - `signature: bytes` 137 138 **Returns:** 139 - Vote confirmation 140 141 **Example:** 142 ```bash 143 curl -X POST http://localhost:3030/alpha/governance/vote \ 144 -H "Content-Type: application/json" \ 145 -d '{"proposal_id": "prop_001", "vote": "Yes", "signature": "..."}' 146 ``` 147 148 --- 149 150 ### Delta Chain API 151 152 **Base URL:** `http://localhost:4030/delta` 153 154 #### Endpoints 155 156 ##### `GET /block/{height}` 157 158 Get block by height. 159 160 **Inputs:** 161 - `height: u64` 162 163 **Returns:** 164 - `block` 165 166 --- 167 168 ##### `GET /transaction/{id}` 169 170 Get transaction by ID. 171 172 **Inputs:** 173 - `id: string` 174 175 **Returns:** 176 - `transaction` 177 178 --- 179 180 ##### `POST /transaction/broadcast` 181 182 Broadcast a transaction. 183 184 **Inputs:** 185 - `tx: transaction` 186 187 **Returns:** 188 - `tx_id: string` 189 190 --- 191 192 ##### `GET /orderbook/{market}` 193 194 Get orderbook for a trading pair. 195 196 **Inputs:** 197 - `market: string` - Trading pair (e.g., "AX/DX") 198 199 **Returns:** 200 - Orderbook with bids and asks 201 202 **Example:** 203 ```bash 204 curl http://localhost:4030/delta/orderbook/AX-DX 205 ``` 206 207 --- 208 209 ##### `GET /positions/{address}` 210 211 Get trading positions for an address. 212 213 **Inputs:** 214 - `address: string` - Delta address 215 216 **Returns:** 217 - Array of open positions 218 219 --- 220 221 ##### `GET /governance/proposals` 222 223 Get Delta governance proposals. 224 225 **Returns:** 226 - Array of proposal objects 227 228 --- 229 230 ## P2P Protocol 231 232 ### Discovery 233 234 **Protocol:** Kademlia DHT 235 236 #### `discover_peers()` 237 238 Discover peers on the network. 239 240 **Returns:** 241 - `peer_list: Array<PeerInfo>` 242 243 ### Gossip 244 245 **Protocol:** PubSub 246 247 #### `broadcast_message(msg: bytes)` 248 249 Broadcast a message to the network. 250 251 **Inputs:** 252 - `msg: bytes` - Message payload 253 254 **Returns:** 255 - `ack_count: number` - Number of peers that acknowledged 256 257 ### Transport 258 259 - **Protocol:** TCP 260 - **Encryption:** Noise encryption 261 262 ### Bootstrap Nodes 263 264 #### Mainnet 265 266 - `validator1.adnet.io:4130` 267 - `validator2.adnet.io:4130` 268 269 #### Testnet 270 271 - `test1.adnet.io:4130` 272 - `test2.adnet.io:4130` 273 274 --- 275 276 ## Node Types 277 278 ### Validator Node (VAL) 279 280 **Interface:** 281 282 ```rust 283 struct ValidatorConfig { 284 cpu: u32, // Core count 285 ram: u64, // Bytes 286 storage: u64, // Bytes 287 network: u32, // Mbps 288 } 289 290 fn start_validator(config: ValidatorConfig) -> Status; 291 fn stop_validator() -> Status; 292 ``` 293 294 **Requirements:** 295 - **CPU:** 32 cores 296 - **RAM:** 128GB 297 - **Storage:** 2TB NVMe 298 - **Network:** 1Gbps 299 300 **Ports:** 301 - Alpha P2P: 4130 302 - Delta P2P: 4131 303 - Alpha API: 3030 304 - Delta API: 4030 305 - Metrics: 9090 306 307 **Keys:** 308 - `validator_key`: BLS12-377 (block signing) 309 - `bls_key`: BLS12-377 (aggregate signatures) 310 311 **Economic Parameters:** 312 - **Max count:** 300 validators 313 - **Stake requirement:** 100,000 AX 314 315 --- 316 317 ### Prover Node (PRV) 318 319 **Interface:** 320 321 ```rust 322 struct ProverConfig { 323 gpu: string, // GPU model 324 vram: u64, // Bytes 325 cuda_cores: u32, // Core count 326 } 327 328 fn start_prover(config: ProverConfig) -> Status; 329 ``` 330 331 **Requirements:** 332 - **GPU:** NVIDIA CUDA (RTX 3090+) 333 - **VRAM:** 24GB+ 334 - **CUDA Cores:** 10,000+ 335 336 **Configuration:** 337 ```toml 338 [prover] 339 cuda_enabled = true 340 cuda_devices = [0, 1] 341 ``` 342 343 **Economic Parameters:** 344 - **Pool size:** 3,000 provers 345 - **Compensation:** 30% of Alpha transaction fees 346 347 --- 348 349 ### Client Node 350 351 **Interface:** 352 353 ```rust 354 fn submit_tx(tx: Transaction) -> TxId; 355 fn query_state(key: string) -> Value; 356 ``` 357 358 **Modes:** 359 - **Full:** Complete state sync 360 - **Light:** Headers only + proofs 361 - **Archive:** Full history 362 363 **Purpose:** Transaction submission and queries 364 365 --- 366 367 ## CLP System (Continuous Liveness Proof) 368 369 **Interface:** 370 371 ```rust 372 struct LivenessProof { 373 validator: Address, 374 epoch: u64, 375 signature: Vec<u8>, 376 } 377 378 // Event 379 event liveness_attested(validator: Address, epoch: u64, uptime: f64); 380 ``` 381 382 **Mechanism:** 383 - **Interval:** Per epoch 384 - **Attestation:** Signed liveness proof 385 - **Broadcast:** To all validators 386 387 **Requirements:** 388 - **Uptime:** >= 95% 389 - **Consensus participation:** >= 99% 390 391 **Failure Consequences:** 392 - During earn-in: Extended period or removal 393 - After full status: Reduced rewards → eventual removal 394 395 --- 396 397 ## Key Management 398 399 **Types:** 400 401 ```rust 402 struct ValidatorKey { 403 algo: "bls12_377", 404 purpose: "block_signing", 405 } 406 407 struct BlsKey { 408 algo: "bls12_377", 409 purpose: "aggregate_signatures", 410 } 411 412 struct ViewKey { 413 algo: "bls12_377", 414 purpose: "decrypt_own_alpha_records", 415 } 416 ``` 417 418 **Storage:** 419 - **Location:** `~/.adnet/keys/` 420 - **Encryption:** AES-256-GCM 421 - **Backup:** Recommended offline 422 423 --- 424 425 ## Deployment Configuration 426 427 **Config file:** `~/.adnet/config.toml` 428 429 ### Sections 430 431 ```toml 432 [node] 433 network = "mainnet" 434 data_dir = "/var/lib/adnet" 435 log_level = "info" 436 437 [validator] 438 enabled = true 439 key_files = ["/path/to/validator.key", "/path/to/bls.key"] 440 441 [consensus] 442 alpha_block_time = "10s" 443 delta_block_time = "2s" 444 445 [network] 446 alpha_p2p_port = 4130 447 delta_p2p_port = 4131 448 bootstrap_peers = ["validator1.adnet.io:4130"] 449 450 [storage] 451 alpha_db_path = "/var/lib/adnet/alpha" 452 delta_db_path = "/var/lib/adnet/delta" 453 cache_size_mb = 4096 454 455 [metrics] 456 enabled = true 457 bind_addr = "0.0.0.0:9090" 458 ``` 459 460 --- 461 462 ## Monitoring Metrics 463 464 **Format:** Prometheus 465 **Endpoint:** `:9090/metrics` 466 467 ### Key Metrics 468 469 | Metric | Type | Description | 470 |--------|------|-------------| 471 | `block_height` | gauge | Current block height | 472 | `peer_count` | gauge | Connected peers | 473 | `mempool_size` | gauge | Transactions in mempool | 474 | `consensus_round` | gauge | Current consensus round | 475 | `proof_queue_depth` | gauge | Proofs waiting to be generated | 476 | `cpu_memory_usage` | gauge | Resource utilization | 477 478 ### Alerts 479 480 Configure alerts for: 481 - `peer_count < threshold` - Network connectivity issue 482 - `block_production_stalled` - Consensus failure 483 - `high_mempool_backlog` - Network congestion 484 - `consensus_timeout_rate` - Performance degradation 485 486 --- 487 488 ## Network Topology 489 490 ### Validator Mesh 491 492 Validators form a fully-connected mesh network for Byzantine fault tolerance. 493 494 ### Prover Connection 495 496 Provers connect to validators for proof generation coordination. 497 498 ### Client Connection 499 500 Clients can connect to any node (validator or dedicated client nodes). 501 502 --- 503 504 ## See Also 505 506 - [AC/DC Installer API](acdc-api.md) 507 - [Validator Operations Guide](../operations/validator-operations.md) 508 - [Prover Setup Guide](../operations/prover-setup.md) 509 - [Network Upgrade Governance](../operations/network-upgrade-governance.md)