Skip to content

Latest commit

 

History

376 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Steem Load Balancer

CI Node.js License: MIT Code style: Prettier PRs welcome Privacy: no telemetry Ask DeepWiki

JavaScript Top language Repo size Last commit Commit activity Stars Watchers Forks Open issues Open PRs

Docker pulls Docker image size Docker stars

Here is the AI-generated documentation by Deep-Wiki.

Overview

The Steem Load Balancer is a Node.js-based application designed to distribute API requests across a list of predefined Steem Blockchain RPC Nodes. It enhances application availability and reliability by routing requests to the most responsive node.

This project was developed by STEEM's Top Witness, @justyy, who also established Two STEEM Load Balancer RPC Nodes, steem.justyy.com (New York) and api.steemyy.com (London), using this project as its foundation.

A similar service, https://steem.senior.workers.dev, is based on CloudFlare Worker which runs at the CloudFlare Edge Network but comes with a daily quota of 100,000 requests.

Another similar service, https://api2.steemyy.com is based on CloudFlare's snippets. This node requires a CloudFlare Paid Plan (Pro+) and it will route to a quickest RPC node. See steem-proxy-cloudflare for more information.

image

Motivation

The primary motivation behind this project is to provide a scalable and reliable Load Balancer Node that can be integrated into applications to improve their availability and performance. Unlike CloudFlare-based solutions, this setup does not have a daily request quota, making it suitable for high-demand applications.

Please note that this can be easily configured to work with other Blockchains such as Hive and Blurt.

Features

  • Load Balancing: Distributes requests across multiple Steem API servers. The jussi_num and status are checked before a node is chosen (See below).
  • Pluggable Routing Strategies: Choose how the upstream node is selected - max_jussi_number, latest_version, lowest_latency, weighted, random or first (see Configuration).
  • Weighted & Sticky Routing: Bias traffic towards higher-capacity nodes with per-node weights, or pin all clients to a single upstream node with sticky routing.
  • Circuit Breaker: Automatically ejects a node after repeated forwarding failures and re-admits it after a cooldown, with automatic fail-open so routing never stalls.
  • Health, Version & Metrics Endpoints: Lightweight /health and /version endpoints plus a Prometheus /metrics scrape endpoint (see API Endpoints).
  • Rate Limiting: Protects against abuse by limiting the number of requests. For example, maximum 600 requests per 10 second window. This can be set in the config.yaml.
  • Configurable Logging: Provides detailed operational logs when enabled and can be disabled for privacy-sensitive deployments.
  • SSL Support: Configurable SSL certificates for secure HTTPS communication. Reject or Ignore the SSL certificates when forwarding the requests via the field rejectUnauthorized in config.yaml

How It Works?

The node first checks whether a previously selected node is still valid (i.e., the cached entry hasn't expired). If it is valid, the request is directly forwarded to that node. Otherwise, the system sends a get_version request to the candidate nodes listed in config.nodes. Among the first config.firstK nodes (default: 1), the node with the highest jussi_num value is selected, cached, and used for subsequent requests.

Better Algorithms?

The Steem blockchain ensures idempotency at the transaction level when the signed content is identical. See Testing Parallel Transfer on STEEM which means that:

We can simplify the load-balancing logics. Just fan out the requests to multiple nodes and return the quickest response.

However, this is against the idea of load balancing. Faning out requests will be putting loads on RPC nodes.

A Healthy Node

A Steem RPC node should return the following to indicate the healthy state. The jussi_num needs to catch up with the latest block height. If the jussi_num is far behind, e.g. the max_jussi_number_diff in config.yaml, then the node will not be considered. Currently, it is set to 500 (roughly 25 minutes of blocks).

{
  "status": "OK",
  "datetime": "2025-02-01T11:06:30.781448",
  "source_commit": "ae6c6c77601436e496a8816ece2cbc6e26fbe3c2",
  "docker_tag": "latest",
  "jussi_num": 92629431
}

Configuration

The configuration for the Steem Load Balancer is specified in the config.yaml file. Here's a breakdown of the configuration options:

Configuration File: config.yaml

nodes:
  - "https://api2.justyy.com"
  - "https://api.justyy.com"
  - "https://api.steemit.com"
  # - "https://api.steemitdev.com"
  # - "https://api.pennsif.net"
  # - "https://api.moecki.online"
  # - "https://api.botsteem.com"
  # - "https://api.steememory.com"
rateLimit:
  windowMs: 10000
  maxRequests: 600
headers:
  "https://api.justyy.com":
    "X-Edge-Key": "${X_EDGE_KEY}"
  "https://api2.justyy.com":
    "X-Edge-Key": "${X_EDGE_KEY}"
version: "${STEEM_LB_VERSION}"
max_age: 3
logging: true
max_payload_size: "5mb"
max_jussi_number_diff: 500
min_blockchain_version: "0.23.0"
logging_max_body_len: 100
retry_count: 3
user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36"
sslCertPath: "${SSL_CERT_PATH}"
sslKeyPath: "${SSL_KEY_PATH}"
rejectUnauthorized: false
timeout: 3000
plimit: 5
port: 9091
cache:
  enabled: ${CACHE_ENABLED}
  ttl: ${CACHE_TTL}
debug: ${DEBUG}
firstK: 2
strategy: "max_jussi_number"  # options: first, random, max_jussi_number, latest_version, lowest_latency, weighted
sticky: false
# weights:
#   "https://api.justyy.com": 3
#   "https://api2.justyy.com": 1
weighted_routing: false
circuitBreaker:
  enabled: true
  failureThreshold: 5
  cooldownMs: 30000

Values written as ${VAR} (for example ${STEEM_LB_VERSION} or ${CACHE_ENABLED}) are substituted from the matching environment variables when the config is loaded. Unquoted placeholders keep their YAML type, so enabled: ${CACHE_ENABLED} with CACHE_ENABLED=true becomes a real boolean, while quoted ones such as version: "${STEEM_LB_VERSION}" stay strings. See setup-env.sh for the defaults.

Configuration Options

  • nodes: An array of API server URLs to which requests will be distributed. You can add or remove nodes as needed.
  • rateLimit: Configuration for rate limiting.
  • windowMs: Time window in milliseconds for the rate limit (e.g., 60000 ms = 1 minute).
  • maxRequests: Maximum number of requests allowed in the time window.
  • version: The version of the Steem Load Balancer.
  • max_age: Cache duration for responses in seconds (GET).
  • logging: Set to false to suppress routine application, health-check, retry, and request-body logs. Fatal startup and server lifecycle messages are still emitted.
  • sslCertPath: Path to the SSL certificate file for HTTPS communication.
  • sslKeyPath: Path to the SSL key file for HTTPS communication.
  • user_agent: User Agent String in the Header to forward.
  • min_blockchain_version: Min blockchain version number e.g. 0.23.0 to decide the validity of a node.
  • max_payload_size: Max payload size.
  • max_jussi_number_diff: The maximum difference of block difference is allowed.
  • logging_max_body_len: Maximum number of request-body characters included in logs.
  • retry_count: Retry count for GET and POST forward requests. There is a 100ms between retries.
  • rejectUnauthorized: Should we ignore SSL errors? Default true.
  • timeout: Max timeout (milliseconds) for fetch to time out.
  • plimit: Max concurrent requests to poke the servers. Reduce this if the server is laggy.
  • cache.enabled: Should we cache the chosen Node?
  • cache.ttl: When cache.enabled, how many seconds before cache expires.
  • debug: When set to debug, more messages are set e.g. in the response header.
  • firstK: Choosing the node which has the max Jussi Number from the first firstK nodes that respond OK. The shipped config uses 2; it falls back to 1 when unset.
  • strategy: The strategy to pick the chosen node. This can be one of:
    • first: the first node that responds OK.
    • random: a random node among those that respond OK.
    • max_jussi_number (default): the node with the highest jussi_num (most up-to-date block height).
    • latest_version: the node running the newest blockchain version.
    • lowest_latency: the node that responded fastest during the health check.
    • weighted: a random node chosen with probability proportional to its configured weights (default 1 each).
  • weights: Optional map of node URL to numeric weight, used by the weighted strategy and weighted routing. Higher weight receives more traffic; set a weight to 0 to drain a node.
  • weighted_routing: When true, the order nodes are probed is biased by their weights even if strategy is not weighted. This mainly matters when plimit is smaller than the number of nodes (otherwise all nodes are probed concurrently and the weighted selection strategy does the real biasing). Default false; the weighted strategy enables it automatically.
  • sticky: When true, all clients share the same chosen upstream node for the cache TTL (minimises node churn). When false (default) each client IP sticks to its own node.
  • circuitBreaker.enabled: Enable the per-node circuit breaker. The code default is false; the shipped config.yaml enables it. It "fails open" (re-admits every node if they would all be ejected) so it never stalls routing.
  • circuitBreaker.failureThreshold: Consecutive forwarding failures before a node is ejected. Default 5.
  • circuitBreaker.cooldownMs: How long (ms) an ejected node stays out before a trial request is allowed. Default 30000.
  • headers: The headers can be specified to pass to the downstream nodes. When proxying requests, the Load Balancer injects a shared-secret header so downstream nodes can identify trusted traffic and apply elevated (or exempt) rate-limit policies.

API Endpoints

Method Path Description
GET / POST / Proxies the request to the chosen Steem RPC node. GET responses are augmented with diagnostic fields (__server__, __stats__, __config__, etc.).
GET /health Lightweight health probe. Returns { status, version, uptime, uptime_seconds, total_requests, nodes, circuit_breaker, timestamp }. Not rate limited, so it is safe for orchestrators (Docker/Kubernetes) and uptime monitors.
GET /version Returns the Load Balancer version: { version }.
GET /metrics Prometheus text-format metrics (request totals, per-node access/error counters, RPS windows, circuit-breaker state). Point a Prometheus scrape job at this path.

Example:

curl -s http://127.0.0.1:9091/health | jq
{
  "status": "OK",
  "version": "2026-01-14",
  "uptime": { "years": 0, "months": 0, "days": 0, "hours": 1, "minutes": 2, "seconds": 3 },
  "uptime_seconds": 3723,
  "total_requests": 1024,
  "nodes": ["https://api2.justyy.com", "https://api.justyy.com", "https://api.steemit.com"],
  "circuit_breaker": {},
  "timestamp": "2026-01-14T11:06:30.781Z"
}

Prometheus metrics:

curl -s http://127.0.0.1:9091/metrics
# HELP steem_lb_requests_total Total proxied requests.
# TYPE steem_lb_requests_total counter
steem_lb_requests_total 1024
# HELP steem_lb_node_access_total Requests routed to each node.
# TYPE steem_lb_node_access_total counter
steem_lb_node_access_total{server="https://api.steemit.com"} 512
# HELP steem_lb_requests_per_second Requests per second over rolling windows.
# TYPE steem_lb_requests_per_second gauge
steem_lb_requests_per_second{window="1min"} 3.2

Installation

Clone the Repository:

git clone https://github.com/doctorlai/steem-load-balancer.git
cd steem-load-balancer

Configure

Update the config.yaml file with your desired nodes, rate limits, and SSL paths.

Build the Docker Image

DOCKER_IMAGE=steem-load-balancer
STEEM_LB_PORT=9091

# Build the Docker image
docker build -t $DOCKER_IMAGE .

Run the Server

docker run --name $DOCKER_IMAGE -p $STEEM_LB_PORT:9091 -v /root/.acme.sh/:/root/.acme.sh/ $DOCKER_IMAGE

image

Build and Run

Use the following utility to build the docker and then start the server.

source ./setup-env.sh
./build.sh
./run.sh

And also, there are stop and restart.

You can pass ./config.yaml to either ./run.sh or ./restart.sh. For example:

./restart.sh ./config.yaml

Prebuilt Docker Image

A latest image is published to Docker Hub by CI on pushes to main, using the dockerhub GitHub environment secrets DOCKERHUB_USER and DOCKERHUB_PASSWORD.

docker pull justyy/steem-load-balancer:latest

Then:

# Run the steem load balancer node with restart policy
STEEM_LB_PORT=443
RETRY_COUNT=3

docker run \
    -e NODE_ENV=production \
    -e SSL_CERT_PATH=$SSL_CERT_PATH \
    -e SSL_KEY_PATH=$SSL_KEY_PATH \
    -e STEEM_LB_VERSION=$STEEM_LB_VERSION \
    -e DEBUG=false \
    --name steem-load-balancer \
    --restart on-failure:$RETRY_COUNT \
    -p $STEEM_LB_PORT:9091 \
    -v /root/.acme.sh/:/root/.acme.sh/ \
    justyy/steem-load-balancer:latest

## or simply
./run.sh # or ./restart.sh

Docker Compose (Optional)

Use Docker Compose to build and run the load balancer:

docker compose up --build -d

This will build and start the steem load balancer.

To view the logs, run:

docker compose logs -f

To restart the Compose service, run:

docker compose down  # Stop the containers
docker compose up -d  # Start the containers in detached mode

Or simply:

docker compose restart steem_lb

Tests

Use the following script i.e. integration-tests.sh to perform a basic integration test - it builds the Docker image, starts the server locally, sends a request, and verifies that the response has a 'status' of 'OK' with a status code of 200.

source ./setup-env.sh
## on success, e1it code is 0.
## on failure, exit code is 1.
./tests/integration-tests.sh

Use integration-tests-docker-compose.sh to test the Steem Load Balancer via Docker Compose.

Unit Tests

Run npm test or npm run test to run the unit tests on the project.

Test Coverage

Run npm run coverage to generate a local report and enforce these global minimums:

Statements Branches Functions Lines
85% 80% 88% 85%

Development

Install dependencies with npm ci, then use the scripts below. Run npm run check before pushing - it mirrors the CI pipeline.

Script Description
npm start Start the load balancer (node src/index.js).
npm run dev Start with auto-reload on file changes (node --watch).
npm run build Validate syntax for all shipped JavaScript files.
npm run build:docker Build the local steem-load-balancer Docker image.
npm test Run the unit test suite (Jest).
npm run test:watch Run tests in watch mode.
npm run test:integration Run the primary Docker integration test.
npm run coverage Run tests, produce coverage, and enforce thresholds.
npm run lint Lint with ESLint (fails on any warning).
npm run lint:fix Lint and auto-fix.
npm run format Check formatting with Prettier.
npm run format:fix Reformat the code with Prettier.
npm run audit Check all dependencies for high-severity vulnerabilities.
npm run check Run lint, formatting, coverage, build, and dependency audit.
npm run ci Run the complete CI validation (npm run check).
npm ci
npm run check

Tools

Tools are placed at ./tools directory.

View the Logs

docker logs -f steem-load-balancer

SSL Configuration

If you have SSL certificates, provide the paths in the config.yaml file. If SSL is not configured or the certificate files are missing, the server will default to HTTP.

Rate Limiting

The rate limiting configuration prevents abuse by restricting the number of requests a user can make within a given time window. Adjust the rateLimit settings in config.yaml as needed.

Logging

Routine logging is enabled unless logging is set to false in config.yaml. When enabled, POST request bodies are truncated to logging_max_body_len characters but may still contain sensitive data; disable logging when request content should not be recorded.

Statistics

On the GET requests, the response JSON will show some additional data including statistics (including Uptime, Access Counters, Error Counters, Not Chosen Counters and Jussi Behind Counters):

See a sample JSON response for sending a GET to the STEEM RPC Load Balancer.

Running without Container

Port 9091 is the port number used in the container. However this can be changed in config.yaml. This is useful if you want to run the node directly e.g:

node src/index.js

Troubleshooting

  • Port 443 is already taken: Ensure no other process is using port 443. Use sudo lsof -i :443 to check. Change the port in the configuration if needed.
  • SSL Certificate Issues: Ensure the SSL certificate and key files are in the correct format and paths are correctly specified.

Choose a "stable" RPC node in your Steem App by using the Load Balancer Node

See this post,

Example: Dynamic RPC Node Selection with Fallback

load_balancing_nodes = [
    "https://api.steemyy.com",
    "https://api2.steemyy.com",
    "https://steem.justyy.com"
]

def node_rotator(nodes):
    """Infinite generator that yields nodes in round-robin."""
    while True:
        for node in nodes:
            yield node

def fetch_from_load_balancer(node):
    """Optional preprocessing, health check, or logging."""
    print(f"Selected node: {node}")
    return node

node_gen = node_rotator(load_balancing_nodes)
node = fetch_from_load_balancer(next(node_gen))

## Replace with your actual app loop condition
while True:
    try:
        # use the node in your API calls
        pass
    except Exception as e:
        print(f"Node error: {e}, switching node...")
        node = fetch_from_load_balancer(next(node_gen))

With this setup, your app will:

  • Always start with a healthy RPC node
  • Automatically switch to a new one if the current node fails
  • This approach provides better stability and resilience compared to relying on a single hardcoded RPC endpoint.

NODE_ENV

Setting NODE_ENV to "production" (by default) or "development".

image

License

This project is licensed under the MIT License.

See the changelog, security policy, support guide, and privacy notice for project policies and release history.

Contributing?

Contribution are absolutely welcome! Please follow the guidance here and CODE OF CONDUCT

Sibling Projects

Support me

If you like this and want to support me in continuous development, you can do the following:

Buy me a Coffee

Releases

Sponsor this project

Packages

Used by

Contributors

Languages