fix(build): break circular @/lib/chains → @/lib/spec causing prod TDZ

.github/workflows/hf-publish.yml

@@ -0,0 +1,85 @@
+name: HF dataset publish
+
+# Daily snapshot of the live citable feed pushed to
+# https://huggingface.co/datasets/OpenChainBench/benchmarks.
+#
+# Trigger:
+#   - 00:00 UTC every day (after the daily Prom roll-up is settled).
+#   - workflow_dispatch with an optional `dry_run` flag so we can
+#     validate changes without touching HF.
+#
+# Required secrets:
+#   HF_TOKEN              write-scoped token for the dataset repo.
+#   SLACK_WEBHOOK_URL     optional, incoming-webhook URL for ops alerts.
+#   KAGGLE_USERNAME       optional, owner of the Kaggle mirror dataset.
+#   KAGGLE_KEY            optional, API key paired with KAGGLE_USERNAME.
+#
+# When both KAGGLE_USERNAME and KAGGLE_KEY are set, the publisher mirrors
+# the snapshot to kaggle.com/datasets/openchainbench/benchmarks right
+# after the HF push. A Kaggle-side failure never aborts the run.
+
+on:
+  schedule:
+    - cron: "0 0 * * *"
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Stage parquet locally without pushing to HF"
+        type: boolean
+        default: false
+
+concurrency:
+  group: hf-publish
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    env:
+      HF_TOKEN: ${{ secrets.HF_TOKEN }}
+      SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+      KAGGLE_USERNAME: ${{ secrets.KAGGLE_USERNAME }}
+      KAGGLE_KEY: ${{ secrets.KAGGLE_KEY }}
+      OCB_API: https://openchainbench.com
+      HF_REPO_ID: OpenChainBench/benchmarks
+      KAGGLE_DATASET_ID: openchainbench/benchmarks
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: scripts/hf_publisher/requirements.txt
+
+      - name: Install deps
+        run: pip install -r scripts/hf_publisher/requirements.txt
+
+      - name: Run publisher tests (offline)
+        # Schema/quorum regressions caught here never reach the dataset.
+        run: |
+          cd scripts/hf_publisher
+          python -m unittest test_publish.py -v
+
+      - name: Publish snapshot
+        run: |
+          cd scripts/hf_publisher
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.dry_run }}" = "true" ]; then
+            python publish.py --dry-run
+          else
+            python publish.py
+          fi
+
+      - name: Summary
+        if: always()
+        run: |
+          {
+            echo "## HF publish ${{ job.status }}"
+            echo ""
+            echo "**Repo:** https://huggingface.co/datasets/${HF_REPO_ID}"
+            echo "**Mode:** ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true && 'dry-run' || 'live' }}"
+            echo "**Time:** $(date -u +%FT%TZ)"
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/hf-space-deploy.yml

@@ -0,0 +1,82 @@
+name: HF Space deploy
+
+# Pushes scripts/hf_space/ to the HF Space at
+# https://huggingface.co/spaces/OpenChainBench/leaderboard.
+#
+# Trigger:
+#   - push to main that touches scripts/hf_space/**
+#   - workflow_dispatch for manual redeploys
+#
+# Required secrets:
+#   HF_TOKEN  write-scoped token for the Space repo (same token as the
+#             dataset publisher).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "scripts/hf_space/**"
+      - ".github/workflows/hf-space-deploy.yml"
+  workflow_dispatch:
+
+concurrency:
+  group: hf-space-deploy
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+    env:
+      HF_TOKEN: ${{ secrets.HF_TOKEN }}
+      HF_SPACE_REPO_ID: OpenChainBench/leaderboard
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install huggingface_hub
+        run: pip install "huggingface_hub>=0.26"
+
+      - name: Upload to HF Space
+        env:
+          GIT_SHA: ${{ github.sha }}
+        run: |
+          python - <<'PY'
+          import os
+          from huggingface_hub import HfApi
+
+          token = os.environ["HF_TOKEN"]
+          repo_id = os.environ["HF_SPACE_REPO_ID"]
+          sha = os.environ.get("GIT_SHA", "manual")
+          api = HfApi(token=token)
+          api.create_repo(
+              repo_id=repo_id,
+              repo_type="space",
+              space_sdk="gradio",
+              exist_ok=True,
+              private=False,
+          )
+          info = api.upload_folder(
+              folder_path="scripts/hf_space",
+              repo_id=repo_id,
+              repo_type="space",
+              commit_message=f"deploy from {sha}",
+          )
+          print("uploaded:", getattr(info, "oid", "ok"))
+          PY
+
+      - name: Summary
+        if: always()
+        run: |
+          {
+            echo "## HF Space deploy ${{ job.status }}"
+            echo ""
+            echo "**Space:** https://huggingface.co/spaces/${HF_SPACE_REPO_ID}"
+            echo "**Commit:** ${{ github.sha }}"
+            echo "**Time:** $(date -u +%FT%TZ)"
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/hf-space-keepalive.yml

@@ -0,0 +1,34 @@
+name: HF Space keepalive
+
+# Free HF Spaces fall asleep after a stretch of inactivity, and the
+# first visitor after a sleep waits 30 to 60 seconds for the container
+# to boot. That looks broken from a tweet. A light curl every 4 hours
+# keeps the Space warm without burning meaningful GH Actions minutes
+# (~6 runs per day, a few seconds each).
+
+on:
+  schedule:
+    - cron: "0 */4 * * *"
+  workflow_dispatch:
+
+concurrency:
+  group: hf-space-keepalive
+  cancel-in-progress: false
+
+jobs:
+  ping:
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    steps:
+      - name: Wake leaderboard Space
+        run: |
+          code=$(curl -sLm 60 -o /dev/null -w "%{http_code}" \
+            "https://openchainbench-leaderboard.hf.space")
+          echo "leaderboard: $code"
+          # 200 is a hot hit. 503 means HF is still booting the
+          # container, which is exactly the case we are warming for, so
+          # don't fail the workflow on it.
+          case "$code" in
+            200|302|503) exit 0 ;;
+            *) exit 1 ;;
+          esac

.github/workflows/prod-deploy.yml

@@ -68,6 +68,23 @@ jobs:
             | xargs -P 4 -I{} curl -s -o /dev/null -w "%{http_code} %{time_total}s {}\n" --max-time 120 {} \
             || echo "warm-up failed (non-blocking)"
 
+      # Warm /api/citable explicitly: the aggregator cache is independent
+      # from per-bench caches, and the bench-page warm-up only populates
+      # the latter. Without this step, /api/citable's first hit after
+      # deploy runs 26 parallel Prom queries on a cold function instance,
+      # which has historically produced mostly-placeholder snapshots that
+      # cached for 60s and shipped status=insufficient to LLM agents.
+      - name: Warm citable aggregate
+        run: |
+          base="https://openchainbench.com"
+          # /api/mcp is the docs path under /mcp, the live JSON-RPC
+          # endpoint is /api/mcp/mcp (Streamable HTTP). Warm the real
+          # endpoint so the first agent request after deploy is hot.
+          for ep in /api/citable /api/llm-context /api/mcp/mcp; do
+            code=$(curl -s -o /dev/null -w "%{http_code}" --max-time 120 "$base$ep" || echo "000")
+            echo "$code $base$ep"
+          done
+
       - name: Summary
         run: |
           {

.gitignore

@@ -61,3 +61,9 @@ harnesses/*/script
 harnesses/*/monitor
 harnesses/*/cmd/script/script
 harnesses/*/cmd/monitor/monitor
+
+# Python venvs for the HF publisher and Space (created locally for dry-runs)
+scripts/hf_publisher/.venv/
+scripts/hf_space/.venv/
+**/__pycache__/
+*.pyc

alternatives/alchemy.yml

@@ -5,7 +5,7 @@ description: Multi-chain node + enhanced API provider
 benchmark: aggregator-head-lag
 
 intro: |
-  Alchemy serves RPC endpoints and enhanced data APIs across EVM chains and Solana. For real-time feeds, the metric that matters most is freshness. how long between a transaction landing on chain and the API reflecting it? Below is the live head-lag for each major onchain data provider, measured against a canonical-tip archive node and refreshed every minute. Lower is faster.
+  Alchemy is an EVM-first node and API provider whose surface is shaped by its enhanced endpoints (`alchemy_getAssetTransfers`, NFT API, webhooks, getTokenBalances, the simulation and debug suite, the account-abstraction bundler) rather than by a raw RPC tuned for edge latency. Pricing is metered in compute units, which charges more for an enhanced call than for a plain `eth_call`, so the ceiling shows up first on teams streaming high-cardinality events into a backend rather than on dapp front-ends issuing single reads. Solana coverage exists but sits on a stack built around Ethereum and its L2s. Teams that need a live view of trades on Base, BNB Chain or Solana usually leave Alchemy at the point where the enhanced API list stops mapping to what the product actually reads from chain.
 
 seo_title: Alchemy alternatives. live head-lag benchmark across data providers
 seo_description: Compare Alchemy alternatives on real-time data freshness. Live head-lag against a canonical archive node, refreshed every minute and published openly.

alternatives/bitquery.yml

@@ -5,7 +5,7 @@ description: GraphQL API for blockchain data, multi-chain
 benchmark: network-coverage
 
 intro: |
-  Bitquery is a GraphQL data API covering many chains. If you're sizing alternatives, the first axis is breadth. how many networks does each provider officially support? Below is the live count from each major onchain data provider, scraped from their public supported-networks endpoint and refreshed every six hours.
+  Bitquery is a GraphQL surface on top of indexed onchain data, with the schema as the actual product: queries declare exactly the fields needed across transfers, trades, DEX events and account state, and the indexer fans those out across chains. Pricing is point-based, with each field, filter and join consuming from a monthly point budget rather than from a flat request quota, which means a single dashboard with many panels can hit the ceiling well before request volume looks high. Chain coverage is broad but uneven in depth: some networks expose full DEX trade indexing, others only basic transfers. The team usually compared next is the one whose chain list either covers a long-tail network Bitquery does not, or covers the same network with a flatter pricing model that does not penalise wide GraphQL fragments on a per-field basis.
 
 seo_title: Bitquery alternatives. live network coverage benchmark
 seo_description: Compare Bitquery alternatives on the number of blockchains each major onchain data provider officially supports. Live data, refreshed every six hours.

alternatives/coingecko.yml

@@ -5,7 +5,7 @@ description: Crypto price + market data API, multi-chain
 benchmark: network-coverage
 
 intro: |
-  CoinGecko offers a broad price + market data REST API used across thousands of crypto apps. The first axis people compare alternatives on is breadth. how many blockchains does each provider officially support? Below is the live count from each major onchain data API, scraped directly from their public supported-networks endpoint and refreshed every six hours.
+  CoinGecko is a coin-centric price and market data REST API built around a curated asset list (the `/coins` universe) rather than around on-chain events. Tokens are added through a listing process, prices land on the API after that process completes, and the free tier is famously throttled (around 30 requests per minute on the demo key) which pushes any real product onto a paid plan within days of integration. The on-chain DEX side ships as a separate `/onchain` namespace inherited from GeckoTerminal, with its own quotas. Teams usually leave CoinGecko at one of two points: when the launch cadence of the tokens they care about outpaces the listing pipeline, or when the per-minute cap on the free tier forces a migration before the product is monetised enough to justify the enterprise tier.
 
 seo_title: CoinGecko alternatives. live network coverage benchmark
 seo_description: Compare CoinGecko alternatives on the number of blockchains each major onchain data API officially supports. Live data, refreshed every six hours.

alternatives/etherscan.yml

@@ -5,9 +5,9 @@ description: Block explorer and gas tracker covering Ethereum and Polygon
 benchmark: gas-estimation
 
 intro: |
-  Etherscan is the most-visited block explorer on the web and publishes a gas tracker exposing `SafeGasPrice`, `ProposeGasPrice` and `FastGasPrice` via the v2 API on Ethereum and Polygon (free tier). The tiering was originally designed for the pre-EIP-1559 single-price world and is now mapped onto a priority-fee comparison alongside dedicated oracles. The question every wallet, swap router and bridge UI faces before sending a transaction is which gas oracle actually matches what the next block will charge on the chain their product runs on, rather than what a marketing page claims. This benchmark polls each oracle at its tier-tolerant cadence (Etherscan every 15 seconds with a global rate-gate enforcing at least 6 seconds between any two Etherscan requests across chains, because the no-key limit is 1 req per 5 s per IP shared), buffers the prediction with the predicted block height, and when that block is mined pulls the full block via `eth_getBlockByNumber(.., true)` on the chain's PublicNode RPC. Realized percentiles are computed from actual `maxPriorityFeePerGas` values, and the absolute error per (oracle, tier, chain) lands on both a gauge and a histogram. The ranking metric is the p99 gap over 24 hours, the worst 1 percent of blocks, because typical-minute gaps sit within fractions of a micro-gwei (economically indistinguishable noise) while gas spikes are where a wrong prediction either overpays or misses the block. A covered-rate column shows the share of time each prediction sat at or above the realized p50, the inclusion-side risk an absolute gap cannot show. The cohort competing with Etherscan includes Blocknative (probability-of-inclusion model), PublicNode `eth_feeHistory` (thin wrapper over EIP-1559 reward percentiles) and Owlracle (multi-oracle aggregator).
+  Etherscan is the most-visited block explorer on the web and publishes a gas tracker exposing `SafeGasPrice`, `ProposeGasPrice` and `FastGasPrice` via the v2 API on Ethereum and Polygon (free tier). The tiering was originally designed for the pre-EIP-1559 single-price world and is now mapped onto a priority-fee comparison alongside dedicated oracles. The question every wallet, swap router and bridge UI faces before sending a transaction is which gas oracle actually matches what the next block will charge on the chain their product runs on, rather than what a marketing page claims. This benchmark polls each oracle at its tier-tolerant cadence (Etherscan every 15 seconds with a global rate-gate enforcing at least 6 seconds between any two Etherscan requests across chains, because the no-key limit is 1 req per 5 s per IP shared), buffers the prediction with the predicted block height, and when that block is mined pulls the full block via `eth_getBlockByNumber(.., true)` on the chain's PublicNode RPC. Realized percentiles are computed from actual `maxPriorityFeePerGas` values, and the absolute error per (oracle, tier, chain) lands on both a gauge and a histogram. The ranking metric is the p99 gap over 24 hours, the worst 1 percent of blocks, because typical-minute gaps sit within fractions of a micro-gwei (economically indistinguishable noise) while gas spikes are where a wrong prediction either overpays or misses the block. A covered-rate column shows the share of time each prediction sat at or above the realized p50, the inclusion-side risk an absolute gap cannot show. The cohort competing with Etherscan includes PublicNode `eth_feeHistory` (thin wrapper over EIP-1559 reward percentiles) and Owlracle (multi-oracle aggregator).
 
 seo_title: Etherscan alternatives. Live gas oracle accuracy benchmark
-seo_description: Compare Etherscan against Blocknative, PublicNode feeHistory and Owlracle on gwei gap between predicted and realized priority fee, ranked on p99 over 24h.
+seo_description: Compare Etherscan against PublicNode feeHistory and Owlracle on gwei gap between predicted and realized priority fee, ranked on p99 over 24h.
 
 status: live