ReserveGrid OS — SV2 Mining Gateway

Features

Built for operators

Six pillars that make ReserveGrid OS production-ready from day one.

73 reason codes

Every rejection is machine-readable. Operators know why work was rejected and under which policy context.

Transport: Channel setup, frame parsing, protocol violations (4 codes)

Framing: Message size, frame sequence, encoding issues (7 codes)

Auth: Invalid credentials, worker ID format, allowlist mismatch (3 codes)

Channel: Unknown channel_id, channel not open, subscriber role violation (4 codes)

Job: Invalid job_id, unknown job, stale prevhash reference (5 codes)

Share: Difficulty below target, ntime out of range, duplicate nonce (11 codes)

Two-event lifecycle

share_accepted at ACK time, share_forward_result after upstream POST. Joined by share_id with 1:1 invariant.

Event 1: share_accepted: share_id, event_id, timestamp, miner_id, job_id, reason_code, sv2_response

Event 2: share_forward_result: share_id, event_id, timestamp, forwarded, upstream_accepted, upstream_http_status, error_detail

Join key: Both events carry the same share_id for 1:1 correlation. The adapter blocks on channel capacity rather than dropping.

Invariant: Every share_accepted with sv2_response = "success" produces exactly one share_forward_result.

Progressive deployment

Shadow or observe as your entry point, inline when ready. Switch modes with one config key.

Shadow (free, no miners): Evaluate the verifier without touching miner infrastructure. Templates checked against policy, verdicts logged. Zero production risk.

Observe (paid, real traffic): Miners connected via SV2, shares forwarded upstream, verdicts logged but not enforced. Full data plane visibility on production traffic.

Inline (enforcement): Full policy enforcement. No unverified job reaches a miner. Prevhash switching is fail-closed. Where both paths lead.

Migration: Switch modes by changing one TOML key. No binary rebuild, no schema change, no downtime.

Fail-closed prevhash

50ms verdict timeout. 5s stale work hold. Miners disconnected deterministically on expiry.

Dual prevhash buffer: The gateway holds two pending templates simultaneously during block transitions. When a new prevhash arrives, the current template continues serving miners while the replacement is verified. No gap in coverage.

Happy path: Verdict arrives within 50ms. New prevhash + job broadcast immediately. Target: p50 < 50ms, p95 < 150ms, p99 < 300ms.

Timeout path: No verdict within 50ms. Miners hold stale job for up to 5s. After 5s, deterministic disconnect with prevhash_switch_timeout.

Risk model: Zero stale work distributed. Gateway blocks on miner demand rather than dropping shares.

Escape hatch: VELDRA_ALLOW_NO_SHARE_UPSTREAM_READY_INLINE relaxes upstream-ready check if needed during initial deploy.

51 TOML keys, zero magic

ReserveGrid OS is configured via TOML with environment variable overrides. No defaults hide pool behavior.

Core: mode, listen_addr, verifier_addr, upstream_url, upstream_failure_policy, http_api_key

Noise: privkey, pubkey, authorized_keys, handshake_timeout_ms

Timing: prevhash_verdict_timeout_ms, prevhash_stale_hold_ms, upstream_poll_interval_ms, job_broadcast_interval_ms

Share: share_upstream_url, share_upstream_secret, share_forward_queue_size, share_forward_max_in_flight

Auth: mode (allowlist/prefix_map/open), allowlist, prefix_map, max_worker_id_bytes, max_workers_per_channel

Escape hatches: 6 VELDRA_ env vars for relaxing constraints during development and initial deployment

Observability

Prometheus metrics, structured event logs, and Grafana dashboards. See every decision in real time.

Prometheus: /metrics on HTTP API. 30+ metrics covering connections, jobs, shares, verdicts, prevhash latencies.

Event stream: /gateway/events NDJSON endpoint. Real-time share_accepted, share_forward_result, template_verdict events.

CSV export: Share history export via HTTP API. Bulk analysis, compliance audits, performance reporting.

Grafana dashboards: Pre-built dashboards for miner connections, job distribution, prevhash switching health, upstream responsiveness.

Deployment modes

Progressive deployment

Shadow and observe are parallel entry points. Both lead to inline enforcement when you are ready.

Entry point · free

Shadow Mode

Evaluate the verifier without touching miners

mode = "shadow"

or

Entry point · paid

Observe Mode

Monitor real traffic, log verdicts, forward all shares

mode = "observe"

Destination · both paths

Inline Mode

Enforce policy with fail-closed safety

mode = "inline"

Configuration

51 TOML keys, zero magic

ReserveGrid OS is configured via TOML with environment variable overrides. No defaults hide pool behavior.

[gateway]
mode = "inline"                          # shadow, observe, or inline
listen_addr = "0.0.0.0:3333"             # Miner connection address
verifier_addr = "127.0.0.1:5001"         # pool-verifier TCP address
upstream_url = "http://bitcoind:8332"    # Block template source
upstream_failure_policy = "fail_closed"  # fail_closed or permit_all
http_api_key = "your-secret-here"        # Authentication for metrics/events

[timing]
# Prevhash switching
prevhash_verdict_timeout_ms = 50         # Wait time for verdict before timeout
prevhash_stale_hold_ms = 5000            # Hold stale job after timeout

# Polling and broadcast
upstream_poll_interval_ms = 1000         # Check for new templates every 1s
job_broadcast_interval_ms = 100          # Aggregate job broadcasts

# Message timeouts
channel_idle_timeout_ms = 3600000        # Close idle channels after 1 hour
nonce_expire_secs = 60                   # Expire old nonces from dedup filter

[share]
share_upstream_url = "http://pool-backend:9090/shares"
share_upstream_secret = "hmac-key-here"  # HMAC-SHA256 signing key
share_forward_queue_size = 10000         # Max pending shares in queue
share_forward_max_in_flight = 100        # Max concurrent upstream requests
share_batch_interval_ms = 100            # Batch shares before sending
share_forward_timeout_ms = 5000          # Upstream request timeout

[auth]
mode = "prefix_map"                      # allowlist, prefix_map, or open

# Allowlist mode: explicit list of authorized credentials
allowlist = [
  { username = "miner1", password = "secret1" },
  { username = "miner2", password = "secret2" }
]

# Prefix map mode: pattern-based authorization
prefix_map = [
  { prefix = "farm1_", secret = "farm1-key" },
  { prefix = "farm2_", secret = "farm2-key" }
]

max_worker_id_bytes = 512                # Limit worker_name field length
max_workers_per_channel = 1000           # Limit concurrent workers per channel

Security

Operator first

Encrypted transport

Noise NX with fixed keys. No certificate infrastructure, no external dependencies.

Fail-closed logic

Timeouts are deterministic. Stale work is held. Invalid templates trigger rejections with reason codes.

Auditability

Every event is logged with context. Operators can reconstruct decisions offline.

Architecture

Inside the gateway

Every hop from miner handshake to upstream submission is encrypted, verified, and observable.

Noise NX encrypted

HTTP internal

TCP / RPC

Prometheus scrape

Get started

Ready to deploy SV2 with confidence?

Start with shadow or observe. Enforce with inline when ready.

Read the docs See architecture

Confidence through configuration

Built for operators

73 reason codes

Two-event lifecycle

Progressive deployment

Fail-closed prevhash

51 TOML keys, zero magic

Observability

Progressive deployment

51 TOML keys, zero magic

Operator first

Encrypted transport

Fail-closed logic

Auditability

Inside the gateway

Ready to deploy SV2 with confidence?