BAM writer service: Track BAM metrics (#31)

#### API
- Added new endpoint bam_epoch_metrics
- Returns bam metric info such as `bam_total_stake_weight`,
`available_bam_delegation_stake`, `eligible_bam_validator_count`
- Modified the endpoint `validators` to add new fields
`jito_pool_eligible`, `jito_pool_directed_stake_target`

#### Bam Writer Service
- Service for BAM delegation calculations, tracking network-wide BAM
validator participation and computing available JitoSOL delegation based
on [JIP-28
specifications](https://forum.jito.network/t/jip-28-accelerate-bam-adoption/904).

Author: aoikurokawa

.github/workflows/build-container-images.yaml

@@ -3,15 +3,16 @@ on:
   workflow_dispatch:
     inputs:
       service_config:
-        description: 'Service configuration'
+        description: "Service configuration"
         required: true
-        default: 'api'
+        default: "api"
         type: choice
         options:
           - api
           - cranker
           - writer-service
           - steward-writer-service
+          - bam-writer-service
 
 env:
   REGISTRY: ghcr.io
@@ -57,6 +58,11 @@ jobs:
               echo "service=steward-writer-service" >> $GITHUB_OUTPUT
               echo "image_name=${{ github.repository }}/kobe-steward-writer-service" >> $GITHUB_OUTPUT
               ;;
+            "bam-writer-service")
+              echo "target=bam-writer-service" >> $GITHUB_OUTPUT
+              echo "service=bam-writer-service" >> $GITHUB_OUTPUT
+              echo "image_name=${{ github.repository }}/kobe-bam-writer-service" >> $GITHUB_OUTPUT
+              ;;
           esac
 
       - name: Extract metadata
@@ -79,4 +85,4 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-to: type=gha,mode=max

.github/workflows/test.yaml

@@ -29,4 +29,3 @@ jobs:
         with:
           command: test
           args: --lib
-

Cargo.lock

@@ -2,6 +2,7 @@
 resolver = "2"
 members = [
     "api",
+    "bam-writer-service",
     "core",
     "cranker",
     "cranker/cli",
@@ -39,7 +40,7 @@ http = { version = "0.2.1" }
 itertools = "0.5.9"
 jito-priority-fee-distribution = { features = ["no-entrypoint"], git = "https://github.com/jito-foundation/jito-programs", branch = "master" }
 jito-priority-fee-distribution-sdk = { git = "https://github.com/jito-foundation/jito-programs", branch = "master" }
-jito-steward = { features = ["no-entrypoint"], git = "https://github.com/jito-foundation/stakenet", rev = "d724a42b49c0cd32791afbd2a362dd63364a7a9a" }
+jito-steward = { package = "jito-steward", git = "https://github.com/jito-foundation/stakenet", rev = "6d35e58013cf7442dce287a1f45013085cb24967", features = ["no-entrypoint"] }
 jito-tip-distribution = { features = ["no-entrypoint"], git = "https://github.com/jito-foundation/jito-programs", branch = "master" }
 jito-tip-distribution-sdk = { git = "https://github.com/jito-foundation/jito-programs", branch = "master" }
 kobe-core = { path = "core", version = "1.0.0" }
@@ -83,7 +84,7 @@ spl-pod = "0.5.1"
 spl-stake-pool = { features = ["no-entrypoint"], version = "2.0.2" }
 spl-stake-pool-cli = { path = "cranker/cli", version = "1.0.0" }
 spl-token = { version = "4.0", features = ["no-entrypoint"] }
-stakenet-sdk = { package = "stakenet-sdk", git = "https://github.com/jito-foundation/stakenet", rev = "d724a42b49c0cd32791afbd2a362dd63364a7a9a" }
+stakenet-sdk = { package = "stakenet-sdk", git = "https://github.com/jito-foundation/stakenet", rev = "6d35e58013cf7442dce287a1f45013085cb24967" }
 thiserror = "1.0.37"
 tokio = { version = "1.36.0", features = ["full"] }
 tokio-retry = "0.3.0"
@@ -92,4 +93,4 @@ tower-http = { version = "0.4.0", features = ["cors", "trace"] }
 tracing = { version = "0.1.37" }
 tracing-core = "0.1.32"
 tracing-subscriber = { version = "0.3.17", features = ["env-filter"] }
-validator-history = { package = "validator-history", git = "https://github.com/jito-foundation/stakenet", rev = "d724a42b49c0cd32791afbd2a362dd63364a7a9a", features = ["no-entrypoint"] }
+validator-history = { package = "validator-history", git = "https://github.com/jito-foundation/stakenet", rev = "6d35e58013cf7442dce287a1f45013085cb24967", features = ["no-entrypoint"] }

Cargo.toml

@@ -47,3 +47,10 @@ ENV APP="kobe-steward-writer-service"
 WORKDIR /app
 COPY --from=builder /home/root/app/${APP} ./
 ENTRYPOINT ./$APP listen
+
+FROM debian:bookworm-slim as bam-writer-service
+RUN apt-get update && apt-get install -y libssl3 ca-certificates procps && rm -rf /var/lib/apt/lists/*
+ENV APP="kobe-bam-writer-service"
+WORKDIR /app
+COPY --from=builder /home/root/app/${APP} ./
+ENTRYPOINT ./$APP run

Dockerfile

@@ -10,31 +10,32 @@ Named after both the premium grade of Kobe beef and in honor of basketball legen
 ## Architecture Overview
 
 ```
-                       ┌───────────────────────────────────────────────────────┐
-                       │                    Solana Network                     │
-                       │                    (Blockchain)                       │
-                       └───────────────────────────────────────────────────────┘
-                         ▲             │                         │
-                         │             │  (read on-chain data)   │
-                         │             ▼                         ▼
-             (write      │      ┌──────────────────┐    ┌──────────────────┐
-          transactions)  │      │  Kobe Writer     │    │ Steward Writer   │
-                         │      │   Service        │    │    Service       │
-                         │      │ (Data Collection)│    │ (Steward Events) │
-                         │      └──────────────────┘    └──────────────────┘
-                         │             │                        │
-                         │             ▼ (write to db)          ▼ (write to db)
-          ┌──────────────────┐   ┌─────────────────────────────────────────────┐
-          │  Kobe Cranker    │   │              MongoDB                        │
-          │ (Pool Management)│   │            (Database)                       │
-          └──────────────────┘   └─────────────────────────────────────────────┘
-                                                   │
-                                                   │ (read from db + on-chain)
-                                                   ▼
-                                         ┌─────────────────┐
-                                         │   Kobe API      │
-                                         │  (Data Access)  │
-                                         └─────────────────┘
+       ┌────────────────────────────────────────────────────────────────────────────────────────┐   ┌─────────────┐
+       │                                  Solana Network                                        │   │   BAM API   │
+       │                                   (Blockchain)                                         │   │             │
+       └────────────────────────────────────────────────────────────────────────────────────────┘   └─────────────┘
+                      ▲             │                         │                        │                   │
+                      │             │  (read on-chain data)   │ (read on-chain data)   │                   │  (read bam data)
+                      │             ▼                         ▼                        ▼                   ▼
+          (write      │      ┌──────────────────┐    ┌──────────────────┐    ┌────────────────────────────────────┐
+       transactions)  │      │  Kobe Writer     │    │ Steward Writer   │    │             BAM Writer             │
+                      │      │   Service        │    │    Service       │    │              Service               │
+                      │      │ (Data Collection)│    │ (Steward Events) │    │                                    │
+                      │      └──────────────────┘    └──────────────────┘    └────────────────────────────────────┘
+                      │             │                        │                           │                 ▲
+                      │             ▼ (write to db)          ▼ (write to db)             ▼ (write to db)   │
+       ┌──────────────────┐   ┌──────────────────────────────────────────────────────────────────────┐     │
+       │  Kobe Cranker    │   │                            MongoDB                                   │     │
+       │ (Pool Management)│   │                           (Database)                                 │     │
+       └──────────────────┘   └──────────────────────────────────────────────────────────────────────┘     │  (read validators data)
+                                                │                                                          │
+                                                │ (read from db + on-chain)                                │
+                                                ▼                                                          │
+                                      ┌─────────────────┐                                                  │
+                                      │   Kobe API      │                                                  │
+                                      │  (Data Access)  │ ──────────────────────────────────────────────────
+                                      │                 │
+                                      └─────────────────┘
 ```
 
 ## JitoSOL APY Calculation
@@ -254,7 +255,24 @@ Therefore, users may see different APY values between real-time calculations and
 - Risk management actions
 - Stake rebalancing operations
 
-**Use Cases:** Steward transparency, audit trails, performance analysis, regulatory compliance
+---
+
+### [Kobe BAM Writer Service](./bam-writer-service/README.md)
+**Specialized monitoring** service for Block Assembly Marketplace (BAM) delegation calculations, tracking network-wide BAM validator participation and computing available JitoSOL delegation based on JIP-28 specifications.
+
+**Capabilities:**
+- Real-time BAM validator stake tracking
+- JIP-28 tier-based delegation calculations
+- Network stakeweight monitoring
+- Epoch-based metrics collection and storage
+
+**Key Features:**
+- Automated epoch threshold detection (default: 90% epoch progress)
+- Integration with BAM API for validator discovery
+- Dynamic delegation allocation based on network participation tiers
+- Historical BAM metrics persistence in MongoDB
+
+**Use Cases:** Powers BAM delegation strategy, provides transparency into automated stake allocation decisions, enables historical analysis of BAM adoption trends
 
 ## Quick Start
 
@@ -310,7 +328,14 @@ RUST_LOG=info cargo r -p kobe-cranker -- \
 #### Start Data Collection
 
 ```bash
-cargo r --bin kobe-writer-service -- live
+RUST_LOG=info cargo r --bin kobe-writer-service -- \
+   --rpc-url "" \
+   --mongo-connection-uri "mongodb://localhost:27017/kobe" \
+   --mongo-db-name "validators" \
+   --solana-cluster "testnet" \
+   --jito-steward-program-id "Stewardf95sJbmtcZsyagb2dg4Mo8eVQho8gpECvLx8" \
+   --steward-config-pubkey "5pZmpk3ktweGZW9xFknpEHhQoWeAKTzSGwnCUyVdiye" \
+   live
 ```
 
 #### Start Steward Monitoring
@@ -325,6 +350,19 @@ RUST_LOG=info cargo r -p kobe-steward-writer-service -- \
     listen
 ```
 
+#### Run BAM writer service
+
+```bash
+RUST_LOG=info cargo r -p kobe-bam-writer-service -- \
+    --mongo-connection-uri "mongodb://localhost:27017/kobe" \
+    --mongo-db-name "validators" \
+    --rpc-url "https://api.mainnet-beta.solana.com/" \
+    --bam-api-base-url "" \
+    --epoch-progress-threshold "0.8" \
+    --poll-interval-secs "60" \
+    run
+```
+
 ## Contributing
 
 1. Fork the repository

README.md

@@ -16,7 +16,8 @@ use env_logger::{Builder, Target};
 use kobe_api::{
     error::{handle_error, ApiError},
     resolvers::query_resolver::{
-        daily_mev_rewards_cacheable_wrapper, get_validator_histories_wrapper,
+        daily_mev_rewards_cacheable_wrapper, get_bam_epoch_metric_wrapper,
+        get_bam_validators_wrapper, get_validator_histories_wrapper,
         jito_stake_over_time_ratio_cacheable_wrapper, jitosol_ratio_cacheable_wrapper,
         jitosol_validators_cacheable_wrapper, mev_commission_average_over_time_cacheable_wrapper,
         mev_rewards_cacheable_wrapper, preferred_withdraw_validator_list_cacheable_wrapper,
@@ -25,6 +26,8 @@ use kobe_api::{
         validator_rewards_cacheable_wrapper, validators_cacheable_wrapper, QueryResolver,
     },
     schemas::{
+        bam_epoch_metric::BamEpochMetricRequest,
+        bam_validator::BamValidatorsRequest,
         jitosol_ratio::JitoSolRatioRequest,
         mev_rewards::{MevRewardsRequest, StakerRewardsRequest, ValidatorRewardsRequest},
         preferred_withdraw::PreferredWithdrawRequest,
@@ -196,6 +199,20 @@ async fn get_validator_histories(
     get_validator_histories_wrapper(resolver, vote_account, epoch_query).await
 }
 
+async fn get_bam_epoch_metric_handler(
+    resolver: Extension<QueryResolver>,
+    Query(epoch_query): Query<BamEpochMetricRequest>,
+) -> impl IntoResponse {
+    get_bam_epoch_metric_wrapper(resolver, epoch_query.epoch).await
+}
+
+async fn get_bam_validators_handler(
+    resolver: Extension<QueryResolver>,
+    Query(epoch_query): Query<BamValidatorsRequest>,
+) -> impl IntoResponse {
+    get_bam_validators_wrapper(resolver, epoch_query.epoch).await
+}
+
 async fn preferred_withdraw_validator_list_handler(
     resolver: Extension<QueryResolver>,
     request: Query<PreferredWithdrawRequest>,
@@ -348,6 +365,11 @@ async fn run_server(args: &Args) {
             "/api/v1/validator_history/:vote_account",
             get(get_validator_histories),
         )
+        .route(
+            "/api/v1/bam_epoch_metric",
+            get(get_bam_epoch_metric_handler),
+        )
+        .route("/api/v1/bam_validators", get(get_bam_validators_handler))
         .route(
             "/api/v1/preferred_withdraw_validator_list",
             get(preferred_withdraw_validator_list_handler),