feat: support spec test using test sig scheme

.github/workflows/auto-release.yml

@@ -224,6 +224,9 @@ jobs:
         push: true
         tags: ${{ steps.meta.outputs.tags }}
         labels: ${{ steps.meta.outputs.labels }}
+        build-args: |
+          GIT_COMMIT=${{ github.sha }}
+          GIT_BRANCH=${{ github.ref_name }}
         cache-from: type=gha
         cache-to: type=gha,mode=max
         provenance: false

Dockerfile

@@ -145,6 +145,12 @@ RUN mkdir -p /runtime-libs && \
 # Runtime stage - using scratch for absolute minimal size
 FROM scratch AS runtime
 
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+
+LABEL org.opencontainers.image.revision=$GIT_COMMIT
+LABEL org.opencontainers.image.ref.name=$GIT_BRANCH
+
 # Copy the architecture-specific libraries and loader
 COPY --from=runtime-prep /runtime-libs/ /
 

Dockerfile.prebuilt

@@ -32,6 +32,12 @@ RUN mkdir -p /runtime-libs && \
 # Runtime stage - using scratch for minimal size
 FROM scratch AS runtime
 
+ARG GIT_COMMIT=unknown
+ARG GIT_BRANCH=unknown
+
+LABEL org.opencontainers.image.revision=$GIT_COMMIT
+LABEL org.opencontainers.image.ref.name=$GIT_BRANCH
+
 # Copy the architecture-specific libraries and loader
 COPY --from=runtime-prep /runtime-libs/ /
 

README.md

@@ -75,6 +75,14 @@ zig build -Doptimize=ReleaseFast -Dgit_version="$(git rev-parse --short HEAD)"
 docker build -f Dockerfile.prebuilt -t zeam:local .
 ```
 
+For publishing to a public registry, add OCI labels for better traceability:
+```bash
+docker build -f Dockerfile.prebuilt \
+  --build-arg GIT_COMMIT=$(git rev-parse HEAD) \
+  --build-arg GIT_BRANCH=$(git rev-parse --abbrev-ref HEAD) \
+  -t blockblaz/zeam:latest .
+```
+
 #### Prerequisites
 
  - Zeam requires zig version 0.14.1 to build.

build.zig

@@ -156,6 +156,7 @@ pub fn build(b: *Builder) !void {
     });
     zeam_utils.addImport("datetime", datetime);
     zeam_utils.addImport("yaml", yaml);
+    zeam_utils.addImport("ssz", ssz);
 
     // add zeam-params
     const zeam_params = b.addModule("@zeam/params", .{
@@ -221,6 +222,7 @@ pub fn build(b: *Builder) !void {
     });
     zeam_key_manager.addImport("@zeam/xmss", zeam_xmss);
     zeam_key_manager.addImport("@zeam/types", zeam_types);
+    zeam_key_manager.addImport("@zeam/utils", zeam_utils);
     zeam_key_manager.addImport("@zeam/metrics", zeam_metrics);
     zeam_key_manager.addImport("ssz", ssz);
 
@@ -319,6 +321,7 @@ pub fn build(b: *Builder) !void {
     zeam_spectests.addImport("build_options", build_options_module);
     zeam_spectests.addImport("@zeam/state-transition", zeam_state_transition);
     zeam_spectests.addImport("@zeam/node", zeam_beam_node);
+    zeam_spectests.addImport("@zeam/xmss", zeam_xmss);
 
     // Add the cli executable
     const cli_exe = b.addExecutable(.{
@@ -570,6 +573,10 @@ pub fn build(b: *Builder) !void {
     spectests.root_module.addImport("@zeam/metrics", zeam_metrics);
     spectests.root_module.addImport("@zeam/state-transition", zeam_state_transition);
     spectests.root_module.addImport("ssz", ssz);
+    spectests.root_module.addImport("@zeam/xmss", zeam_xmss);
+
+    spectests.step.dependOn(&build_rust_lib_steps.step);
+    addRustGlueLib(b, spectests, target, prover);
 
     manager_tests.step.dependOn(&build_rust_lib_steps.step);
 
@@ -728,6 +735,7 @@ fn build_zkvm_targets(b: *Builder, main_exe: *Builder.Step, host_target: std.Bui
             .optimize = optimize,
             .root_source_file = b.path("pkgs/utils/src/lib.zig"),
         });
+        zeam_utils.addImport("ssz", ssz);
 
         // add zeam-metrics (core metrics definitions for ZKVM)
         const zeam_metrics = b.addModule("@zeam/metrics", .{

build.zig.zon

@@ -4,8 +4,8 @@
     .version = "0.0.0",
     .dependencies = .{
         .ssz = .{
-            .url = "git+https://github.com/blockblaz/ssz.zig#5ce7322fc45cab4f215021cae2579d1343e05d55",
-            .hash = "ssz-0.0.9-Lfwd61PEAgAUPJfUQiK4R5gRX_lTWOd_qYwNT-KAhRLA",
+            .url = "https://github.com/blockblaz/ssz.zig/archive/0ce92a8f093a321b0d0815eec6c90bd4e745d8e1.tar.gz",
+            .hash = "ssz-0.0.9-Lfwd6wvKAgA3JZjtfbeXeQG6zle1K_K2j6HPmQJJF4an",
         },
         .zigcli = .{
             .url = "git+https://github.com/jiacai2050/zigcli?ref=main#dcbc59d70b4787671c8a4e484ffd2b725aa17af5",

pkgs/api/README.md

@@ -2,11 +2,13 @@
 
 ## Overview
 
-This package provides the HTTP API server for the Zeam node with three main endpoints:
+This package provides the HTTP API server for the Zeam node with five main endpoints:
 
 - Server-Sent Events (SSE) stream for real-time chain events at `/events`
 - Prometheus metrics endpoint at `/metrics`
-- Health check at `/health`
+- Health check at `/lean/v0/health`
+- Finalized checkpoint state at `/lean/v0/states/finalized` (for checkpoint sync)
+- Justified checkpoint information at `/lean/v0/checkpoints/justified`
 
 ## Package Components
 
@@ -31,7 +33,7 @@ Provides real-time chain event streaming via Server-Sent Events:
 
 ### 2. Health Checks
 
-Simple health check endpoint at `/health`.
+Simple health check endpoint at `/lean/v0/health`.
 
 ## Event System
 
@@ -97,14 +99,41 @@ Streams real-time chain events (head, justification, finalization).
 curl -N http://localhost:9667/events
 ```
 
-### `/health`
+### `/lean/v0/health`
 
 Returns node health status.
 
 ```sh
-curl http://localhost:9667/health
+curl http://localhost:9667/lean/v0/health
 ```
 
+### `/lean/v0/states/finalized`
+
+Returns the finalized checkpoint state as SSZ-encoded binary for checkpoint sync.
+
+```sh
+curl http://localhost:9667/lean/v0/states/finalized -o finalized_state.ssz
+```
+
+Returns:
+- **Content-Type**: `application/octet-stream`
+- **Body**: SSZ-encoded `BeamState`
+- **Status 503**: Returned if no finalized state is available yet
+
+### `/lean/v0/checkpoints/justified`
+
+Returns the latest justified checkpoint information as JSON.
+
+```sh
+curl http://localhost:9667/lean/v0/checkpoints/justified
+```
+
+Returns:
+- **Content-Type**: `application/json`
+- **Body**: JSON object with `slot` and `root` fields
+- **Status 503**: Returned if chain is not initialized
+- **Example response**: `{"root":"0x1234...","slot":42}`
+
 ## Usage
 
 ### Initialization
@@ -122,7 +151,9 @@ try api_server.startAPIServer(allocator, apiPort);
 The server exposes:
 - SSE at `/events`
 - Metrics at `/metrics`
-- Health at `/health`
+- Health at `/lean/v0/health`
+- Checkpoint state at `/lean/v0/states/finalized`
+- Justified checkpoint at `/lean/v0/checkpoints/justified`
 
 **Note**: On freestanding targets (ZKVM), the HTTP server is automatically disabled.
 
@@ -179,7 +210,13 @@ curl -N http://localhost:9668/events
 curl http://localhost:9668/metrics
 
 # Health
-curl http://localhost:9668/health
+curl http://localhost:9668/lean/v0/health
+
+# Checkpoint state
+curl http://localhost:9668/lean/v0/states/finalized -o state.ssz
+
+# Justified checkpoint
+curl http://localhost:9668/lean/v0/checkpoints/justified
 ```
 
 ## Visualization with Prometheus & Grafana

pkgs/cli/src/api_server.zig

@@ -11,8 +11,8 @@ const node_lib = @import("@zeam/node");
 const BeamChain = node_lib.chainFactory.BeamChain;
 
 /// API server that runs in a background thread
-/// Handles metrics, SSE events, health checks, and checkpoint state endpoints
-/// chain is optional - if null, the finalized state endpoint will return 503
+/// Handles metrics, SSE events, health checks, checkpoint endpoints, and finalized state
+/// chain is optional - if null, endpoints will return 503
 /// (API server starts before chain initialization, so chain may not be available yet)
 pub fn startAPIServer(allocator: std.mem.Allocator, port: u16, logger_config: *LoggerConfig, chain: ?*BeamChain) !void {
     // Initialize the global event broadcaster for SSE events
@@ -98,15 +98,21 @@ const ApiServer = struct {
         } else if (std.mem.eql(u8, request.head.target, "/metrics")) {
             // Handle metrics request
             self.handleMetrics(&request);
-        } else if (std.mem.eql(u8, request.head.target, "/health")) {
+        } else if (std.mem.eql(u8, request.head.target, "/lean/v0/health")) {
             // Handle health check
             self.handleHealth(&request);
-        } else if (std.mem.eql(u8, request.head.target, "/lean/states/finalized")) {
+        } else if (std.mem.eql(u8, request.head.target, "/lean/v0/states/finalized")) {
             // Handle finalized checkpoint state endpoint
             self.handleFinalizedCheckpointState(&request) catch |err| {
                 self.logger.warn("failed to handle finalized checkpoint state request: {}", .{err});
                 _ = request.respond("Internal Server Error\n", .{ .status = .internal_server_error }) catch {};
             };
+        } else if (std.mem.eql(u8, request.head.target, "/lean/v0/checkpoints/justified")) {
+            // Handle justified checkpoint endpoint
+            self.handleJustifiedCheckpoint(&request) catch |err| {
+                self.logger.warn("failed to handle justified checkpoint request: {}", .{err});
+                _ = request.respond("Internal Server Error\n", .{ .status = .internal_server_error }) catch {};
+            };
         } else {
             _ = request.respond("Not Found\n", .{ .status = .not_found }) catch {};
         }
@@ -140,7 +146,7 @@ const ApiServer = struct {
     }
 
     /// Handle finalized checkpoint state endpoint
-    /// Serves the finalized checkpoint lean state (BeamState) as SSZ octet-stream at /lean/states/finalized
+    /// Serves the finalized checkpoint lean state (BeamState) as SSZ octet-stream at /lean/v0/states/finalized
     fn handleFinalizedCheckpointState(self: *const Self, request: *std.http.Server.Request) !void {
         // Get the chain (may be null if API server started before chain initialization)
         const chain = self.chain orelse {
@@ -180,6 +186,38 @@ const ApiServer = struct {
         };
     }
 
+    /// Handle justified checkpoint endpoint
+    /// Returns checkpoint info as JSON at /lean/v0/checkpoints/justified
+    /// Useful for monitoring consensus progress and fork choice state
+    fn handleJustifiedCheckpoint(self: *const Self, request: *std.http.Server.Request) !void {
+        // Get the chain (may be null if API server started before chain initialization)
+        const chain = self.chain orelse {
+            _ = request.respond("Service Unavailable: Chain not initialized\n", .{ .status = .service_unavailable }) catch {};
+            return;
+        };
+
+        // Get justified checkpoint from chain (chain handles its own locking internally)
+        const justified_checkpoint = chain.getJustifiedCheckpoint();
+
+        // Convert checkpoint to JSON string
+        const json_string = justified_checkpoint.toJsonString(self.allocator) catch |err| {
+            self.logger.err("failed to serialize justified checkpoint to JSON: {}", .{err});
+            _ = request.respond("Internal Server Error: Serialization failed\n", .{ .status = .internal_server_error }) catch {};
+            return;
+        };
+        defer self.allocator.free(json_string);
+
+        // Respond with JSON
+        _ = request.respond(json_string, .{
+            .extra_headers = &.{
+                .{ .name = "content-type", .value = "application/json; charset=utf-8" },
+            },
+        }) catch |err| {
+            self.logger.warn("failed to respond with justified checkpoint: {}", .{err});
+            return err;
+        };
+    }
+
     /// Handle SSE events endpoint
     fn handleSSEEvents(self: *const Self, stream: std.net.Stream) !void {
         // Set SSE headers manually by writing HTTP response

pkgs/cli/src/main.zig

@@ -75,7 +75,7 @@ pub const NodeCommand = struct {
         .override_genesis_time = "Override genesis time in the config.yaml",
         .@"sig-keys-dir" = "Relative path of custom genesis to signature key directory",
         .@"data-dir" = "Path to the data directory",
-        .@"checkpoint-sync-url" = "URL to fetch finalized checkpoint state from for checkpoint sync (e.g., http://localhost:5052/lean/states/finalized)",
+        .@"checkpoint-sync-url" = "URL to fetch finalized checkpoint state from for checkpoint sync (e.g., http://localhost:5052/lean/v0/states/finalized)",
         .help = "Show help information for the node command",
     };
 };

pkgs/cli/src/node.zig

@@ -656,7 +656,7 @@ fn verifyCheckpointState(
 
     // Calculate the block root from the properly constructed block header
     var block_root: types.Root = undefined;
-    try ssz.hashTreeRoot(types.BeamBlockHeader, state_block_header, &block_root, allocator);
+    try zeam_utils.hashTreeRoot(types.BeamBlockHeader, state_block_header, &block_root, allocator);
 
     logger.info("checkpoint state verified: slot={d}, genesis_time={d}, validators={d}, state_root=0x{s}, block_root=0x{s}", .{
         state.slot,
@@ -1201,7 +1201,7 @@ test "compare roots from genGensisBlock and genGenesisState and genStateBlockHea
 
     // Get state root by hashing the state directly
     var state_root_from_genesis: [32]u8 = undefined;
-    try ssz.hashTreeRoot(types.BeamState, genesis_state, &state_root_from_genesis, allocator);
+    try zeam_utils.hashTreeRoot(types.BeamState, genesis_state, &state_root_from_genesis, allocator);
 
     // Generate block header using genStateBlockHeader
     const state_block_header = try genesis_state.genStateBlockHeader(allocator);
@@ -1265,11 +1265,11 @@ test "checkpoint-sync-url parameter is optional" {
         .@"node-id" = "test",
         .validator_config = "test",
         .override_genesis_time = null,
-        .@"checkpoint-sync-url" = "http://localhost:5052/lean/states/finalized",
+        .@"checkpoint-sync-url" = "http://localhost:5052/lean/v0/states/finalized",
     };
 
     try std.testing.expect(node_cmd_with_url.@"checkpoint-sync-url" != null);
-    try std.testing.expectEqualStrings(node_cmd_with_url.@"checkpoint-sync-url".?, "http://localhost:5052/lean/states/finalized");
+    try std.testing.expectEqualStrings(node_cmd_with_url.@"checkpoint-sync-url".?, "http://localhost:5052/lean/v0/states/finalized");
 }
 
 test "NodeOptions checkpoint_sync_url field is optional" {
@@ -1314,6 +1314,6 @@ test "NodeOptions checkpoint_sync_url field is optional" {
     try std.testing.expect(node_options.checkpoint_sync_url == null);
 
     // Test with a URL
-    node_options.checkpoint_sync_url = "http://localhost:5052/lean/states/finalized";
+    node_options.checkpoint_sync_url = "http://localhost:5052/lean/v0/states/finalized";
     try std.testing.expect(node_options.checkpoint_sync_url != null);
 }

pkgs/cli/test/fixtures/README.md

@@ -272,10 +272,10 @@ To enable checkpoint sync, add the `--checkpoint-sync-url` parameter:
   --validator_config genesis_bootnode \
   --override_genesis_time $GENESIS_TIME \
   --data-dir ./data/test_node1 \
-  --checkpoint-sync-url http://localhost:5052/lean/states/finalized
+  --checkpoint-sync-url http://localhost:5052/lean/v0/states/finalized
 ```
 
-The URL should point to a zeam node's checkpoint state endpoint (e.g., `http://localhost:5052/lean/states/finalized` if the source node has metrics enabled on port 5052).
+The URL should point to a zeam node's checkpoint state endpoint (e.g., `http://localhost:5052/lean/v0/states/finalized` if the source node has metrics enabled on port 5052).
 
 ### Checkpoint Sync Server
 
@@ -292,7 +292,7 @@ To serve checkpoint state from a zeam node, enable the metrics server:
   --api-port 5052
 ```
 
-This node will serve the finalized checkpoint state at `http://localhost:5052/lean/states/finalized`.
+This node will serve the finalized checkpoint state at `http://localhost:5052/lean/v0/states/finalized`.
 
 ### Checkpoint Sync Example
 
@@ -318,7 +318,7 @@ This node will serve the finalized checkpoint state at `http://localhost:5052/le
   --validator_config genesis_bootnode \
   --override_genesis_time 1759210782 \
   --data-dir ./data/test_node1 \
-  --checkpoint-sync-url http://localhost:5052/lean/states/finalized
+  --checkpoint-sync-url http://localhost:5052/lean/v0/states/finalized
 ```
 
 **Note:** The `--checkpoint-sync-url` parameter is optional. If not provided, the node will start from genesis as usual.

pkgs/cli/test/integration.zig

@@ -159,9 +159,9 @@ const ZeamRequest = struct {
         return self.makeRequest("/metrics");
     }
 
-    /// Make a request to the /health endpoint and return the response
+    /// Make a request to the /lean/v0/health endpoint and return the response
     fn getHealth(self: ZeamRequest) ![]u8 {
-        return self.makeRequest("/health");
+        return self.makeRequest("/lean/v0/health");
     }
 
     /// Internal helper to make HTTP requests to any endpoint