Add /hardforks endpoint: join hardfork number to activation block and timestamp

Summary

There is no endpoint that returns Hive's hardforks with both their number and their activation block. The data exists, in two places, and neither carries the other half.

What is already reachable — so this is scoped honestly

Source Gives Missing
database_api.get_hardfork_properties (hived) processed_hardforks — 29 entries, index = HF number, HF0→HF28, with timestamps no activation block
GET /hafbe-api/block-search?operation-types=60&from-block=1&to-block=<head> all 28 hardfork blocks with timestamps, in one call no hardfork number
GET /hafah-api/blocks/{n}/operations?operation-types=60 hardfork_id for that block one call per hardfork

So the gap is precisely the join. Assembling hardfork_num + block + timestamp today means combining two protocols, or ~27 rounds of binary search over block headers. And nothing answers the inverse — which hardfork era does block N belong to?

Proposed

GET /hafbe-api/hardforks
      → [{ hardfork_num, block_num, timestamp }]

GET /hafbe-api/hardforks/{block-num}          (optional, the inverse lookup)
      → the hardfork era containing that block

Why it is cheap

hive.applied_hardforks_view is already populated — verified live, 28 rows, hardfork_num 1→28 with block numbers. hafbe already reads this data internally:

-- db/process_account_stats.sql:20
_hf11_block INT := (SELECT block_num FROM hafd.applied_hardforks WHERE hardfork_num = 11);

The endpoint is that query without the WHERE, joined to hive.blocks_view for the timestamp.

Three implementation notes

  1. Read hive.applied_hardforks_view, not hafd.applied_hardforks. The private table works, but there is an unmerged branch (origin/fix/use-public-haf-views) migrating hafbe onto the public views, and btracker's develop already uses them (db/process_balances.sql:86). A new endpoint should land on the right side of that migration.

  2. HF0 is not in the table. applied_hardforks_view holds HF1–HF28 (28 rows); hived's processed_hardforks array covers HF0–HF28 (29 entries). If the genesis hardfork should appear in the response it has to come from elsewhere or be synthesised — worth deciding deliberately rather than discovering later.

  3. block_num NULL handling. I found zero NULLs on a fully synced node (28/28 populated), so this is not a live concern here — but btracker carries a commit titled "fix: allow NULL hardfork blocks in process_withdrawals" (e456e6a), so it evidently occurs in some state. Prefer a LEFT JOIN to blocks_view over an inner join that would silently drop rows.

A trap this endpoint removes

Reconstructing the timeline by hand via block-search silently truncates:

to-block=100000000  →  27 hardforks
to-block=<head>     →  28 hardforks

No error, no warning — pick a round number and you quietly lose the most recent hardfork. That is a good argument for a canonical endpoint rather than leaving every consumer to assemble it.

Added value

Beyond the timeline itself, this annotates every existing time series. haf_stats charts currently cross hardfork boundaries with no marker, so regime changes — reward-curve changes, the HF24 governance delay, HF25 vote expiry — read as unexplained discontinuities. A block→era lookup lets any chart label them.

Comparable treatment elsewhere: Subscan has a Runtime/Spec-version page listing every upgrade with its activation block and labels blocks with their spec version; Etherscan marks network upgrades on charts.

Verification

Checked before filing: no hardfork endpoint exists in any of the 10 deployed HAF REST modules (all OpenAPI specs read in full); no issue or MR proposing one in hive/haf_block_explorer, hive/balance_tracker, hive/block_explorer_ui, hive/haf_stats, hive/haf, hive/hive; and block_explorer_ui has no hardcoded hardfork table — its only hardfork references are op-formatting (Hardfork ${op.hardfork_id}) and witness hardfork_version_vote fields.

Front-end counterpart filed separately.