governance-server
JSON

API catalog

Every endpoint this service serves. Limits and timeouts shown are this server's current settings. The same list is at /api/catalog. How it all fits together: architecture overview.

JSON-RPC for pools

POST /rpc (or POST /) on the public listener. No login: limits apply per client (one IPv4 address or one IPv6 /64). JSON-RPC 1.0 and 2.0; replies use the request's version. Batches up to 16 requests.

JSON-RPC getblocktemplate

The current block template from the CUSF enforcer, with the BIP300/301 commitments already in the coinbase. Always the coinbasetxn form: replace the one spendable output with your payouts and keep every other output. Use max(curtime, mintime) as the block time.

ParameterTypeRequiredMeaning
rulesarraynoAccepted for compatibility, e.g. ["segwit"]. Everyone gets the same template.
longpollidstringnoFrom a previous template. Waits until the template changes (up to 30 s), then returns it. Not rate-limited; at most 8 open per client.
modestringno"template" (default) or "proposal" (BIP23: with "data", checks a block against the enforcer's tip).

Returns: A BIP22 template object. Without longpollid: 60 calls/min per client, burst 10.

curl -s https://gbt.bip300.xyz/rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblocktemplate","params":[{"rules":["segwit"]}]}'
JSON-RPC submitblock

Submit a solved block. Forwarded to the enforcer (and to bitcoind too when bitcoind.also_submit is on), matched to the template it was built from, and recorded.

ParameterTypeRequiredMeaning
hexdatastringyesThe serialized block, hex.

Returns: null when accepted, otherwise a BIP22 reject reason string. 30 calls/min per client, burst 10.

curl -s https://gbt.bip300.xyz/rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"submitblock","params":["<block hex>"]}'

Service

Public listener. Open.

GET /healthz open

Whether a template can be served right now. Safe to poll: it never calls the enforcer.

Returns: 200 "ok template=<id> height=<n>", or 503 with the reason.

curl -si https://gbt.bip300.xyz/healthz

Mining overview

Public listener, next to /rpc. Open.

GET /api/mining open

Everything on the Mining overview page (/): network numbers, this server's getblocktemplate URL, the public pool list from the pool registry, and resource links.

Returns: MiningData object. pools is null until the registry has been fetched.

curl -s https://gbt.bip300.xyz/api/mining
GET /api/network open

Network numbers from this server's node, recomputed every few seconds: height, last block, hashrate over 24 h and over the current retarget window, difficulty, blocks and transactions over 24 h, transactions per second over the last hour, mempool, next retarget and the expected difficulty change, last block's reward. Rates are in H/s, times in unix seconds, amounts in satoshis.

Returns: NetworkStats object, or null before the first refresh.

curl -s https://gbt.bip300.xyz/api/network

Dashboard JSON

Same listener as /rpc. Open (no login).

GET /api/overview open

Chain tip, current template, upstream health and latency, BMM accepts in the current template, recent clients (addresses shortened).

Returns: OverviewData object.

curl -s https://gbt.bip300.xyz/api/overview
GET /api/templates open

Template history, newest first. Repeat polls with the same content are folded into one row.

ParameterTypeRequiredMeaning
heightintegernoOnly templates for this block height.
pageintegerno1-based page, 50 rows per page.

Returns: { page, page_size, total, templates: [...] }

curl -s https://gbt.bip300.xyz/api/templates?page=1
GET /api/templates/{id}

One template: decoded coinbase outputs, raw coinbase hex, transactions, and the diff against the previous template.

ParameterTypeRequiredMeaning
idstringyesTemplate id (16 hex characters), from /api/templates.

Returns: Template detail object, or 404.

curl -s https://gbt.bip300.xyz/api/templates/<id>
GET /api/sidechains open

Latest sidechain snapshot: each slot's status, ack progress, CTIP, withdrawal bundles and votes, recent BMM commitments, live bids.

Returns: SidechainSnapshot object, or null before the first snapshot.

curl -s https://gbt.bip300.xyz/api/sidechains
GET /api/submissions open

Every submitblock, newest first, with result, matched template and latency. Client addresses shortened.

ParameterTypeRequiredMeaning
pageintegerno1-based page, 50 rows per page.

Returns: { page, page_size, total, submissions: [...] }

curl -s https://gbt.bip300.xyz/api/submissions?page=1
GET /api/catalog open

This catalog.

Returns: Catalog object.

curl -s https://gbt.bip300.xyz/api/catalog

Operations

Same listener as /rpc. Open (no login).

GET /metrics open

Prometheus metrics, prefixed govsrv_: upstream latency and errors, template changes by trigger, long-poll waiters, getblocktemplate calls, refusals by limit, submit results.

Returns: Prometheus text format.

curl -s https://gbt.bip300.xyz/metrics

JSON-RPC errors

Codes follow Bitcoin Core where one exists, so pool software reacts as it would to bitcoind. Errors from the enforcer itself are passed through unchanged.

CodeMeaning
-9Enforcer unavailable, or its template is too old. There is no fallback template.
-8Invalid parameter (e.g. unknown mode, missing block hex).
-22Block could not be decoded.
-32005Refused by a per-client limit. The message says which one.
-32600Invalid request (e.g. missing method, empty batch).
-32601Method not found. Only getblocktemplate and submitblock are served.
-32700Body is not valid JSON.