feat(02-04): add block and last_block route handlers and register routes

- routes/block.rs: GET /v0/block/:height with singleflight dedup, X-Upstream-Source header, verbose 502 on all-upstreams-fail
- routes/last_block.rs: GET /v0/last_block/final proxies to fastnear (no cache), updates tip_height AtomicU64
- routes/mod.rs: register /v0/block/:height and /v0/last_block/final alongside existing /healthz and /readyz

Author: andrewklau

apps/block-proxy/src/routes/block.rs

@@ -0,0 +1,69 @@
+use axum::{
+    extract::{Path, State},
+    http::{HeaderValue, StatusCode, header},
+    response::{IntoResponse, Response},
+};
+use serde_json::json;
+
+use crate::state::AppState;
+use crate::upstream::fetch_block_deduped;
+
+/// GET /v0/block/:height
+///
+/// Fetches a block by height using the singleflight dedup + fallback chain.
+/// On success, returns block JSON with `X-Upstream-Source` and `Content-Type` headers.
+/// On failure (all upstreams exhausted), returns 502 with verbose per-source error details.
+pub async fn block_handler(
+    State(state): State<AppState>,
+    Path(height): Path<u64>,
+) -> Response {
+    // height=0 is technically valid in NEAR but often indicates a misconfiguration.
+    // Reject it early with a descriptive 400 to avoid confusing upstream errors.
+    if height == 0 {
+        let body = json!({ "error": "block height must be greater than 0" });
+        return (
+            StatusCode::BAD_REQUEST,
+            [(header::CONTENT_TYPE, "application/json")],
+            axum::Json(body),
+        )
+            .into_response();
+    }
+
+    match fetch_block_deduped(&state, height).await {
+        Ok((bytes, source)) => {
+            // Build response with correct headers.
+            // `bytes::Bytes` can be used directly as an axum response body.
+            let source_header =
+                HeaderValue::from_static(source);
+
+            (
+                StatusCode::OK,
+                [
+                    (header::CONTENT_TYPE, HeaderValue::from_static("application/json")),
+                    (
+                        header::HeaderName::from_static("x-upstream-source"),
+                        source_header,
+                    ),
+                ],
+                bytes,
+            )
+                .into_response()
+        }
+        Err(errors) => {
+            // All upstreams failed — return 502 with verbose per-source error details
+            // (locked decision in CONTEXT.md: verbose upstream error responses).
+            let body = json!({
+                "error": "all upstream sources failed",
+                "height": height,
+                "sources": errors,
+            });
+            tracing::error!(height, error_count = errors.len(), "block request failed: all upstreams exhausted");
+            (
+                StatusCode::BAD_GATEWAY,
+                [(header::CONTENT_TYPE, "application/json")],
+                axum::Json(body),
+            )
+                .into_response()
+        }
+    }
+}

apps/block-proxy/src/routes/last_block.rs

@@ -0,0 +1,70 @@
+use std::sync::atomic::Ordering;
+
+use axum::{
+    extract::State,
+    http::{HeaderValue, StatusCode, header},
+    response::{IntoResponse, Response},
+};
+use serde_json::json;
+
+use crate::state::AppState;
+
+/// GET /v0/last_block/final
+///
+/// Proxies the request to fastnear in real time — this response is NOT cached
+/// (per ENDP-02) because the chain tip changes every ~1 second.
+///
+/// On success, updates `tip_height` AtomicU64 so the background eviction task
+/// knows which blocks are "recent" and eligible for TTL eviction.
+///
+/// Returns the raw fastnear JSON with `X-Upstream-Source: fastnear` header.
+pub async fn last_block_final_handler(State(state): State<AppState>) -> Response {
+    match state.fastnear.fetch_last_block_final().await {
+        Ok(bytes) => {
+            // Attempt to extract the block height from the JSON response to update
+            // tip_height. fastnear's last_block/final response format contains
+            // `block_height` at the top level (for the compact format) or nested
+            // under `block.header.height` (for the full format). Try both.
+            if let Ok(value) = serde_json::from_slice::<serde_json::Value>(&bytes) {
+                let tip = value
+                    .get("block_height")
+                    .and_then(|v| v.as_u64())
+                    .or_else(|| {
+                        value
+                            .get("block")
+                            .and_then(|b| b.get("header"))
+                            .and_then(|h| h.get("height"))
+                            .and_then(|v| v.as_u64())
+                    });
+
+                if let Some(height) = tip {
+                    state.tip_height.store(height, Ordering::Relaxed);
+                    tracing::debug!(height, "tip_height updated from last_block/final");
+                }
+            }
+
+            (
+                StatusCode::OK,
+                [
+                    (header::CONTENT_TYPE, HeaderValue::from_static("application/json")),
+                    (
+                        header::HeaderName::from_static("x-upstream-source"),
+                        HeaderValue::from_static("fastnear"),
+                    ),
+                ],
+                bytes,
+            )
+                .into_response()
+        }
+        Err(e) => {
+            tracing::error!(error = %e, "last_block/final fetch from fastnear failed");
+            let body = json!({ "error": e.to_string() });
+            (
+                StatusCode::BAD_GATEWAY,
+                [(header::CONTENT_TYPE, "application/json")],
+                axum::Json(body),
+            )
+                .into_response()
+        }
+    }
+}

apps/block-proxy/src/routes/mod.rs

@@ -1,4 +1,6 @@
+pub mod block;
 pub mod health;
+pub mod last_block;
 pub mod readyz;
 
 use axum::{Router, http::HeaderName, routing::get};
@@ -10,14 +12,21 @@ use tower_http::{
 
 use crate::state::AppState;
 
-use self::{health::health_handler, readyz::readyz_handler};
+use self::{
+    block::block_handler,
+    health::health_handler,
+    last_block::last_block_final_handler,
+    readyz::readyz_handler,
+};
 
 pub fn build_router(state: AppState) -> Router {
     let x_request_id = HeaderName::from_static("x-request-id");
 
     Router::new()
         .route("/healthz", get(health_handler))
         .route("/readyz", get(readyz_handler))
+        .route("/v0/block/:height", get(block_handler))
+        .route("/v0/last_block/final", get(last_block_final_handler))
         .layer(
             ServiceBuilder::new()
                 .layer(SetRequestIdLayer::new(