fix(block-proxy): add FASTNEAR_API_KEY support (#1364)

fix(block-proxy): add FASTNEAR_API_KEY support and clarify NEAR Lake env defaults

Add optional FASTNEAR_API_KEY env var that appends ?apiKey= query param
to fastnear upstream requests when set. Clarify in .env.example that
NEAR_LAKE_BUCKET and NEAR_LAKE_REGION are auto-derived from NETWORK.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: andrewklau

apps/block-proxy/.env.example

@@ -17,6 +17,7 @@
 # --- fastnear (enabled by default, no config needed) ---
 # FASTNEAR_ENABLED=true
 # FASTNEAR_URL=https://mainnet.neardata.xyz
+# FASTNEAR_API_KEY=
 
 # --- S3/MinIO (disabled by default, set these if you have a local block store) ---
 # S3_ENABLED=false
@@ -26,10 +27,14 @@
 # S3_ACCESS_KEY=
 # S3_SECRET_KEY=
 
-# --- NEAR Lake (disabled by default, requires credentials) ---
+# --- NEAR Lake (disabled by default, requires AWS credentials) ---
+# Bucket and region are auto-derived from NETWORK:
+#   mainnet → near-lake-data-mainnet, eu-central-1
+#   testnet → near-lake-data-testnet, eu-central-1
+# Only NEAR_LAKE_ENABLED + credentials are needed to enable.
 # 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=
+# NEAR_LAKE_BUCKET=              # optional override (auto-derived from NETWORK)
+# NEAR_LAKE_REGION=eu-central-1  # optional override
 # UPSTREAM_TIMEOUT_SECS=7

apps/block-proxy/src/config.ts

@@ -8,6 +8,7 @@ const env = cleanEnv(process.env, {
   CACHE_DIR: str({ default: '/app/cache' }),
   CACHE_ENABLED: bool({ default: true }),
   CACHE_TTL_SECS: num({ default: 3600 }),
+  FASTNEAR_API_KEY: str({ default: '' }),
   FASTNEAR_ENABLED: bool({ default: true }),
   FASTNEAR_URL: str({ default: '' }),
   LOG_LEVEL: str({ default: 'info' }),
@@ -60,6 +61,7 @@ const config = {
   cacheDir: env.CACHE_DIR,
   cacheEnabled: env.CACHE_ENABLED,
   cacheTtlSecs: env.CACHE_TTL_SECS,
+  fastnearApiKey: env.FASTNEAR_API_KEY,
   fastnearBaseUrl: deriveFastnearUrl(env.NETWORK, env.FASTNEAR_URL),
   fastnearEnabled: env.FASTNEAR_ENABLED,
   logLevel: env.LOG_LEVEL,
@@ -89,6 +91,7 @@ export function logConfigSummary(): void {
       cacheDir: config.cacheDir,
       cacheEnabled: config.cacheEnabled,
       cacheTtlSecs: config.cacheTtlSecs,
+      fastnearApiKey: mask(config.fastnearApiKey),
       fastnearEnabled: config.fastnearEnabled,
       fastnearUrl: config.fastnearBaseUrl,
       nearLakeAccessKey: mask(config.nearLakeAccessKey),

apps/block-proxy/src/upstream/fastnear.ts

@@ -5,16 +5,23 @@ import type { Config } from '#config';
 const MAX_BODY_SIZE = 100 * 1024 * 1024; // 100 MB
 
 export class FastnearUpstream {
+  private apiKey: string;
   private baseUrl: string;
   private timeoutMs: number;
 
   constructor(config: Config) {
+    this.apiKey = config.fastnearApiKey;
     this.baseUrl = config.fastnearBaseUrl;
     this.timeoutMs = config.upstreamTimeoutMs;
   }
 
+  private buildUrl(path: string): string {
+    const url = `${this.baseUrl}${path}`;
+    return this.apiKey ? `${url}?apiKey=${this.apiKey}` : url;
+  }
+
   async fetch(height: number): Promise<Buffer> {
-    const url = `${this.baseUrl}/v0/block/${height}`;
+    const url = this.buildUrl(`/v0/block/${height}`);
     const start = Date.now();
 
     const response = await globalThis
@@ -67,7 +74,7 @@ export class FastnearUpstream {
   }
 
   async fetchLastBlockFinal(): Promise<Buffer> {
-    const url = `${this.baseUrl}/v0/last_block/final`;
+    const url = this.buildUrl('/v0/last_block/final');
     const start = Date.now();
 
     const response = await globalThis