feat(block-proxy): add block-proxy

.github/workflows/workflow-build.yaml

@@ -27,6 +27,7 @@ jobs:
             indexer-contract,
             explorer-selector,
             aggregates,
+            block-proxy,
           ]
       fail-fast: false
     steps:

apps/block-proxy/.env.example

@@ -0,0 +1,35 @@
+# block-proxy environment configuration
+#
+# All variables have safe defaults. Zero config = fastnear-only proxy.
+# Enable S3 or NEAR Lake by setting their _ENABLED flags and credentials.
+
+# --- Core ---
+# PORT=3000
+# ADMIN_PORT=3001
+# NETWORK=mainnet
+# LOG_LEVEL=info
+
+# --- Cache ---
+# CACHE_ENABLED=true
+# CACHE_DIR=/app/cache
+# CACHE_TTL_SECS=3600
+
+# --- fastnear (enabled by default, no config needed) ---
+# FASTNEAR_ENABLED=true
+# FASTNEAR_URL=https://mainnet.neardata.xyz
+
+# --- S3/MinIO (disabled by default, set these if you have a local block store) ---
+# S3_ENABLED=false
+# S3_ENDPOINT=http://minio:9000
+# S3_BUCKET=blocks
+# S3_REGION=us-east-1
+# S3_ACCESS_KEY=
+# S3_SECRET_KEY=
+
+# --- NEAR Lake (disabled by default, requires credentials) ---
+# NEAR_LAKE_ENABLED=false
+# NEAR_LAKE_BUCKET=near-lake-data-mainnet
+# NEAR_LAKE_REGION=eu-central-1
+# NEAR_LAKE_ACCESS_KEY=
+# NEAR_LAKE_SECRET_KEY=
+# UPSTREAM_TIMEOUT_SECS=7

apps/block-proxy/.eslintrc.cjs

@@ -0,0 +1,5 @@
+module.exports = {
+  extends: ['custom-node'],
+  ignorePatterns: ['dist'],
+  root: true,
+};

apps/block-proxy/Dockerfile

@@ -0,0 +1,25 @@
+FROM node:22-alpine AS base
+
+FROM --platform=$BUILDPLATFORM base AS builder
+WORKDIR /app
+RUN yarn global add turbo
+COPY . .
+RUN turbo prune block-proxy --docker
+
+FROM --platform=$BUILDPLATFORM base AS installer
+WORKDIR /app
+COPY .gitignore .gitignore
+COPY --from=builder /app/out/json/ .
+COPY --from=builder /app/out/yarn.lock ./yarn.lock
+RUN yarn --immutable
+COPY --from=builder /app/out/full/ .
+COPY turbo.json turbo.json
+RUN yarn turbo run build --filter=block-proxy...
+
+FROM base AS runner
+ENV NODE_ENV production
+USER node
+WORKDIR /app
+COPY --chown=node:node --from=installer /app .
+EXPOSE 3000 3001
+CMD ["node", "apps/block-proxy/dist/index.js"]

apps/block-proxy/README.md

@@ -0,0 +1,135 @@
+# block-proxy
+
+Caching reverse proxy for NEAR block data. Sits between indexers and upstream block sources (fastnear/neardata, S3/MinIO, NEAR Lake), providing:
+
+- **Local disk cache** with sharded storage and TTL-based eviction
+- **Singleflight dedup** — concurrent requests for the same block height are collapsed into one upstream fetch
+- **Fallback chain** — cache → S3/MinIO → fastnear → NEAR Lake, with per-source metrics
+- **Prometheus metrics** and JSON stats on a separate admin port
+
+## Quick Start
+
+The proxy is URL-compatible with neardata.xyz — any client that fetches `/v0/block/{height}` or `/v0/last_block/final` can point at the proxy instead.
+
+```bash
+# Minimal config — fastnear-only proxy, no S3/NEAR Lake
+FASTNEAR_ENABLED=true S3_ENABLED=false NEAR_LAKE_ENABLED=false node dist/index.js
+```
+
+All env vars have safe defaults. With zero config, the proxy starts on port 3000 serving mainnet blocks via fastnear.
+
+## API
+
+### Data Plane (default port 3000)
+
+| Method | Path                   | Description                                                          |
+| ------ | ---------------------- | -------------------------------------------------------------------- |
+| GET    | `/v0/block/:height`    | Fetch block by height. Returns JSON with `X-Upstream-Source` header. |
+| GET    | `/v0/last_block/final` | Latest finalized block (proxied from fastnear, never cached).        |
+| GET    | `/healthz`             | Health check — always returns 200.                                   |
+| GET    | `/readyz`              | Readiness — returns 200 when ready, 503 during startup.              |
+
+### Admin Plane (default port 3001)
+
+| Method | Path       | Description                                                   |
+| ------ | ---------- | ------------------------------------------------------------- |
+| GET    | `/metrics` | Prometheus metrics (text/plain).                              |
+| GET    | `/stats`   | JSON stats snapshot with hit rates, latencies, dedup savings. |
+
+## Environment Variables
+
+### Core
+
+| Variable     | Default   | Description                                             |
+| ------------ | --------- | ------------------------------------------------------- |
+| `PORT`       | `3000`    | Data server listen port                                 |
+| `ADMIN_PORT` | `3001`    | Admin server listen port                                |
+| `NETWORK`    | `mainnet` | `mainnet` or `testnet` — controls default upstream URLs |
+| `LOG_LEVEL`  | `info`    | Log level (debug, info, warn, error)                    |
+
+### Cache
+
+| Variable            | Default      | Description                                  |
+| ------------------- | ------------ | -------------------------------------------- |
+| `CACHE_ENABLED`     | `true`       | Enable local disk cache                      |
+| `CACHE_DIR`         | `/app/cache` | Cache directory path                         |
+| `CACHE_TTL_SECS`    | `3600`       | TTL for cached block eviction (seconds)      |
+| `CACHE_COMPRESSION` | `false`      | Reserved for future zstd compression support |
+
+### Upstream: fastnear (neardata.xyz)
+
+| Variable           | Default                  | Description                |
+| ------------------ | ------------------------ | -------------------------- |
+| `FASTNEAR_ENABLED` | `true`                   | Enable fastnear upstream   |
+| `FASTNEAR_URL`     | _(derived from NETWORK)_ | Override fastnear base URL |
+
+### Upstream: S3/MinIO
+
+| Variable        | Default                 | Description              |
+| --------------- | ----------------------- | ------------------------ |
+| `S3_ENABLED`    | `false`                 | Enable S3/MinIO upstream |
+| `S3_ENDPOINT`   | _(required if enabled)_ | S3/MinIO endpoint URL    |
+| `S3_BUCKET`     | _(required if enabled)_ | Bucket name              |
+| `S3_REGION`     | `us-east-1`             | S3 region                |
+| `S3_ACCESS_KEY` | _(required if enabled)_ | Access key               |
+| `S3_SECRET_KEY` | _(required if enabled)_ | Secret key               |
+
+### Upstream: NEAR Lake
+
+| Variable                | Default                  | Description                          |
+| ----------------------- | ------------------------ | ------------------------------------ |
+| `NEAR_LAKE_ENABLED`     | `false`                  | Enable NEAR Lake upstream            |
+| `NEAR_LAKE_BUCKET`      | _(derived from NETWORK)_ | Override NEAR Lake S3 bucket         |
+| `NEAR_LAKE_REGION`      | `eu-central-1`           | NEAR Lake S3 region                  |
+| `UPSTREAM_TIMEOUT_SECS` | `7`                      | Per-source request timeout (seconds) |
+
+## Architecture
+
+```
+                    ┌──────────────┐
+  indexers ───────► │  block-proxy │
+                    │  :3000       │
+                    └──────┬───────┘
+                           │
+              ┌────────────┼────────────┐
+              ▼            ▼            ▼
+         ┌────────┐  ┌──────────┐  ┌──────────┐
+         │ cache  │  │ S3/MinIO │  │ fastnear  │
+         │ (disk) │  │          │  │ neardata  │
+         └────────┘  └──────────┘  └──────────┘
+                                        │
+                                   ┌────┘
+                                   ▼
+                              ┌──────────┐
+                              │NEAR Lake │
+                              │  (S3)    │
+                              └──────────┘
+```
+
+Fallback order: cache → S3 → fastnear → NEAR Lake. On any upstream hit, the block is written to cache in the background.
+
+### Singleflight Dedup
+
+When multiple indexers request the same block simultaneously, only one upstream fetch is made. All other requests wait for the leader's result. This prevents upstream stampede.
+
+### Cache Eviction
+
+Every 60 seconds, the eviction loop scans the cache directory and removes any cached block file older than `CACHE_TTL_SECS`.
+
+## Docker
+
+```bash
+docker build -f apps/block-proxy/Dockerfile -t block-proxy .
+docker run -p 3000:3000 -p 3001:3001 block-proxy
+```
+
+## Connecting Indexers
+
+Since block-proxy is URL-compatible with neardata.xyz, any indexer using `nb-neardata` can point to it:
+
+```bash
+# In your indexer's env
+NEARDATA_URL=http://localhost:3000
+```
+
+The `nb-neardata` package accepts an optional `url` field that overrides the default neardata.xyz endpoint.

apps/block-proxy/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "block-proxy",
+  "version": "0.2.0",
+  "author": "NearBlocks",
+  "license": "Business Source License 1.1",
+  "type": "module",
+  "imports": {
+    "#*": [
+      "./dist/*.js"
+    ]
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "yarn clean && tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx watch --env-file=.env src/index.ts",
+    "lint": "tsc --noEmit && eslint ./ --fix",
+    "lint:check": "tsc --noEmit && eslint ./"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.749.0",
+    "envalid": "8.0.0",
+    "express": "4.21.2",
+    "prom-client": "15.1.3",
+    "uuid": "11.0.3"
+  },
+  "devDependencies": {
+    "@types/express": "~4.17",
+    "@types/node": "~20.8",
+    "nb-logger": "*",
+    "nb-tsconfig": "*",
+    "rimraf": "~5.0",
+    "tsx": "~4.21",
+    "typescript": "~5.2"
+  }
+}

apps/block-proxy/src/admin.ts

@@ -0,0 +1,29 @@
+import express from 'express';
+
+import { register } from '#metrics';
+import type { AppState } from '#state';
+
+export function createAdminServer(state: AppState): express.Express {
+  const app = express();
+
+  // GET /metrics — Prometheus text format
+  app.get('/metrics', async (_req, res) => {
+    res
+      .set('content-type', register.contentType)
+      .send(await register.metrics());
+  });
+
+  // GET /stats — JSON stats snapshot
+  app.get('/stats', (_req, res) => {
+    const tipHeight = state.tipHeight;
+    const uptimeSecs = Math.floor((Date.now() - state.startTime) / 1000);
+    const snapshot = state.stats.snapshot(tipHeight, uptimeSecs, {
+      fastnear: state.fastnearEnabled,
+      nearLake: state.nearLakeEnabled,
+      s3: state.s3Enabled,
+    });
+    res.json(snapshot);
+  });
+
+  return app;
+}