|
| 1 | +# Dashboard & REST API Integration |
| 2 | + |
| 3 | +c2pool serves a built-in web dashboard and a JSON REST API from the same HTTP |
| 4 | +port (default **8080**, `--web-port`). This document is the reference for |
| 5 | +integrating with that API — feeding an external block explorer, building a |
| 6 | +custom dashboard, or scraping pool metrics. |
| 7 | + |
| 8 | +> The authoritative source for exact response fields is |
| 9 | +> [`src/core/web_server.cpp`](../src/core/web_server.cpp) (the request router) |
| 10 | +> and the `rest_*` handlers behind it. Endpoint descriptions below are stable; |
| 11 | +> response shapes may gain fields over time. |
| 12 | +
|
| 13 | +--- |
| 14 | + |
| 15 | +## Serving basics |
| 16 | + |
| 17 | +- **Base URL:** `http://<host>:8080/` (change the port with `--web-port`, bind |
| 18 | + address with `--http-host`, default `0.0.0.0`). |
| 19 | +- **Dashboard:** the HTML/JS UI is served from `web-static/` (override with |
| 20 | + `--dashboard-dir`). Open `http://localhost:8080/` in a browser. |
| 21 | +- **Format:** read endpoints return `application/json` (the `/web/*` helpers |
| 22 | + back the bundled dashboard and may return HTML/JSON as noted). |
| 23 | +- **Method:** the public stats/read API is `GET`-only. Mutating routes live |
| 24 | + under `/control/*` and `/api/admin/*` and are access-gated (see below). |
| 25 | +- **CORS:** set `--cors-origin <origin>` (YAML `cors_origin`) to emit an |
| 26 | + `Access-Control-Allow-Origin` header for cross-origin dashboards. |
| 27 | +- **Availability:** the dashboard + REST API are served in `integrated`, |
| 28 | + `solo`, and `custodial` modes (not in `sharechain` relay-only mode). |
| 29 | + |
| 30 | +--- |
| 31 | + |
| 32 | +## Node & pool statistics |
| 33 | + |
| 34 | +| Endpoint | Returns | |
| 35 | +|----------|---------| |
| 36 | +| `/local_stats` | Local node stats — peers, hashrates, share counts | |
| 37 | +| `/global_stats` | Pool-wide aggregate statistics | |
| 38 | +| `/p2pool_global_stats` | Sharechain-wide (p2pool-compatible) global stats | |
| 39 | +| `/node_info` | Node identity / build / mode info | |
| 40 | +| `/uptime` | Node uptime | |
| 41 | +| `/rate`, `/local_rate`, `/global_rate` | Hashrate (node / local miners / pool) | |
| 42 | +| `/difficulty`, `/network_difficulty` | Current share difficulty / parent-chain network difficulty | |
| 43 | +| `/fee` | Node operator fee configuration | |
| 44 | +| `/best_share` | Current best share (sharechain tip) summary | |
| 45 | +| `/version_signaling`, `/v36_status` | Share-version signalling tallies and V36 AutoRatchet state | |
| 46 | + |
| 47 | +## Payouts |
| 48 | + |
| 49 | +| Endpoint | Returns | |
| 50 | +|----------|---------| |
| 51 | +| `/current_payouts` | Current PPLNS payout distribution | |
| 52 | +| `/pplns/current` | PPLNS window snapshot | |
| 53 | +| `/pplns/miner/<address>` | PPLNS share/weight for one address | |
| 54 | +| `/miner_payouts/<address>` | Payout history/estimate for one address | |
| 55 | +| `/payout_addr`, `/payout_addrs` | Configured payout address(es) | |
| 56 | + |
| 57 | +## Miners & stratum |
| 58 | + |
| 59 | +| Endpoint | Returns | |
| 60 | +|----------|---------| |
| 61 | +| `/connected_miners` | Currently connected stratum workers | |
| 62 | +| `/stratum_stats` | Per-worker stratum stats (hashrate, difficulty, accepted/rejected) | |
| 63 | +| `/miner_stats/<address>` | Stats for one miner address | |
| 64 | +| `/miner_thresholds` | Minimum viable hashrate and dust range | |
| 65 | +| `/stratum_security` | Stratum connection/security posture | |
| 66 | +| `/users`, `/user_stales`, `/stale_rates` | Per-user list and stale-share rates | |
| 67 | + |
| 68 | +## Blocks & luck |
| 69 | + |
| 70 | +| Endpoint | Returns | |
| 71 | +|----------|---------| |
| 72 | +| `/recent_blocks` | Recently found blocks | |
| 73 | +| `/luck_stats` | Pool luck statistics | |
| 74 | +| `/checkpoint`, `/checkpoints` | SPV header checkpoint(s) in effect | |
| 75 | + |
| 76 | +## Sharechain |
| 77 | + |
| 78 | +| Endpoint | Returns | |
| 79 | +|----------|---------| |
| 80 | +| `/sharechain/stats` | Sharechain state summary | |
| 81 | +| `/sharechain/tip` | Current sharechain tip | |
| 82 | +| `/sharechain/window` | PPLNS window contents (cached, ETag/`304`, rate-limited) | |
| 83 | +| `/sharechain/delta` | Incremental sharechain updates | |
| 84 | +| `/sharechain/stream` | Streaming sharechain updates (for live visualizations) | |
| 85 | +| `/tracker_debug` | Share-tracker debug view | |
| 86 | + |
| 87 | +## Merged mining |
| 88 | + |
| 89 | +| Endpoint | Returns | |
| 90 | +|----------|---------| |
| 91 | +| `/merged_stats` | Merged-mining block statistics | |
| 92 | +| `/current_merged_payouts` | Current merged-mining payout distribution | |
| 93 | +| `/recent_merged_blocks` | Recently found merged (aux) blocks | |
| 94 | +| `/all_merged_blocks`, `/discovered_merged_blocks` | Full / discovered merged-block lists | |
| 95 | +| `/broadcaster_status`, `/merged_broadcaster_status` | Parent- and aux-chain block broadcaster status | |
| 96 | + |
| 97 | +## Peers & network |
| 98 | + |
| 99 | +| Endpoint | Returns | |
| 100 | +|----------|---------| |
| 101 | +| `/peer_list`, `/peer_addresses` | Connected sharechain peers | |
| 102 | +| `/peer_versions`, `/peer_txpool_sizes` | Peer protocol versions / mempool sizes | |
| 103 | +| `/pings` | Peer latency | |
| 104 | +| `/ban_stats` | P2P ban statistics | |
| 105 | +| `/api/coin_peers` | Parent-coin daemon peer info | |
| 106 | +| `/api/node_topology` | Sharechain topology graph | |
| 107 | + |
| 108 | +--- |
| 109 | + |
| 110 | +## Explorer integration (loopback, opt-in) |
| 111 | + |
| 112 | +For feeding an **external block explorer**, c2pool exposes a Bitcoin-RPC-style |
| 113 | +subset under `/api/explorer/`. These are **loopback-only** (127.0.0.1) and |
| 114 | +require `explorer: true` in the config: |
| 115 | + |
| 116 | +| Endpoint | Returns | |
| 117 | +|----------|---------| |
| 118 | +| `/api/explorer/getblockchaininfo` | Parent-chain info | |
| 119 | +| `/api/explorer/getblockhash` | Block hash by height | |
| 120 | +| `/api/explorer/getblock` | Full block JSON by hash or height | |
| 121 | + |
| 122 | +Enable and point the bundled explorer at them: |
| 123 | + |
| 124 | +```yaml |
| 125 | +# config |
| 126 | +explorer: true |
| 127 | +explorer_url: "http://localhost:9090" |
| 128 | +explorer_depth_ltc: 288 # blocks to retain (LTC) |
| 129 | +explorer_depth_doge: 1440 # blocks to retain (DOGE) |
| 130 | +``` |
| 131 | +
|
| 132 | +```bash |
| 133 | +python3 explorer/explorer.py \ |
| 134 | + --ltc-c2pool http://127.0.0.1:8080/api/explorer \ |
| 135 | + --doge-c2pool http://127.0.0.1:8080/api/explorer \ |
| 136 | + --web-port 9090 |
| 137 | +``` |
| 138 | + |
| 139 | +Then browse `http://localhost:9090/`. The explorer shows block details, decoded |
| 140 | +coinbase scripts, and THE commitment proofs for c2pool-found blocks, and links |
| 141 | +out to a public explorer (default Blockchair) for anything outside the stored |
| 142 | +range. |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +## Dashboard customization |
| 147 | + |
| 148 | +Both the dashboard and the explorer are user-editable components: |
| 149 | + |
| 150 | +- **Dashboard:** edit HTML/JS/CSS in `web-static/` (or point `--dashboard-dir` |
| 151 | + at your own directory). The bundled UI consumes the `/web/*` helper endpoints |
| 152 | + (`/web/heads`, `/web/tails`, `/web/graph_data/…`, `/web/share/<hash>`, |
| 153 | + `/web/best_share_hash`, `/web/sync_status`, `/web/currency_info`, …). |
| 154 | +- **Explorer:** modify `explorer/explorer.py`. |
| 155 | +- **External explorer links** default to Blockchair and can be overridden |
| 156 | + per-node: |
| 157 | + |
| 158 | +```yaml |
| 159 | +address_explorer_prefix: "https://your-explorer.example.com/address/" |
| 160 | +block_explorer_prefix: "https://your-explorer.example.com/block/" |
| 161 | +tx_explorer_prefix: "https://your-explorer.example.com/tx/" |
| 162 | +``` |
| 163 | +
|
| 164 | +- **Analytics:** set `--analytics-id G-XXXXXXXXXX` (YAML `analytics_id`) to |
| 165 | + inject a measurement snippet into the dashboard `</head>`. |
| 166 | + |
| 167 | +--- |
| 168 | + |
| 169 | +## Control & admin endpoints |
| 170 | + |
| 171 | +Mutating and administrative routes exist under `/control/*` (e.g. |
| 172 | +`/control/mining/start`, `/stop`, `/restart`, `/ban`, `/unban`) and |
| 173 | +`/api/admin/*` (`/api/admin/pool/…`, `/api/admin/coin/…`). These change node |
| 174 | +state and are **not** part of the read-only integration surface — treat them as |
| 175 | +operator-only and keep them off any public binding. Consult |
| 176 | +`src/core/web_server.cpp` for their exact contracts before wiring automation to |
| 177 | +them. |
0 commit comments