Skip to content

ReserveGrid OS v0.2.0

Choose a tag to compare

View all tags
@LeavesJ LeavesJ released this 23 Feb 03:42
v0.2.0
ca936ef

ReserveGrid OS v0.2.0 — Credibility

Scope

v0.2.0 is a protocol-line release bundling pool-verifier hardening and policy correctness, rg-protocol alignment, and a completed template-manager. Protocol version is treated as an explicit compatibility boundary. No Arc<Mutex> fallback implementation in this release.

Pool verifier hardening and policy correctness

Runtime and filesystem

  • Ensure data/ exists before any verdict log load or append (created in main.rs prior to log operations).

HTTP export endpoints and UX

  • Add bounded exports to prevent accidental huge responses:
    • /verdicts/log?tail=... hard capped at 50,000 lines
    • /verdicts.csv?limit=... hard capped
  • Document shell quoting requirements for query params in terminals such as zsh.
  • CSV generation hygiene: avoid embedding \n inside a writeln! format string to prevent double newlines.

Mempool client

  • Reuse a single reqwest::Client via OnceLock rather than creating a new client per request.
  • Centralize timeouts in the client builder and remove redundant per-request timeout code.
  • Accept extra JSON fields (e.g., timestamp) via #[serde(default)] without breaking parsing.
  • Fix mempool tiering input: verifier now accepts tx_count from template-manager /mempool JSON (previously only count), preventing silent tier lock to low and restoring correct dynamic fee-tier behavior.

Policy engine correctness

  • CoinbaseZero consistency: rejection is optional and relaxed:
    • Reject coinbase_value == 0 only for non-empty templates and only when reject_coinbase_zero is enabled.
  • Remove mismatch where main.rs rejected coinbase zero unconditionally even when policy disabled it.
  • Ensure empty-template rejection runs before CoinbaseZero so the true reason is not masked.

Degraded mode for mempool dependency

  • Remove the unknown_mempool_tier TOML FeeTier idea (awkward deserialization, poor policy UX).
  • Add unknown_mempool_as_high: bool (default true) as the degraded-mode knob.
  • Tier selection on mempool failure:
    • Missing mempool selects High if unknown_mempool_as_high = true, else Mid
    • No silent Low-tier fallback

Policy TOML format unification

  • Standardize on canonical wrapper: a top-level [policy] table with flat keys plus [policy.safety].
  • Policy loader parses the wrapper consistently and rejects protocol mismatches (policy.protocol_version must equal PROTOCOL_VERSION).
  • TOML loaders explicitly parse wrapped schemas ([policy], [manager]) with clearer validation and protocol enforcement.

Init policy wizard

  • “0 means unlimited” for max_tx_count: convert 0 to u32::MAX so validation passes and semantics match the prompt.
  • Wizard writes canonical wrapper output ([policy] ...) by serializing { policy: cfg }.
  • Wizard writes to config/policy.toml and ensures config/ exists.
  • Wizard includes toggles for unknown_mempool_as_high and reject_coinbase_zero, and retains reject_empty_templates.

State and logging hygiene

  • Replace full PolicyConfig debug dumps with a safe concise summary.
  • Default policy text renders as real TOML, not debug output.

Dependency sanity

  • Confirm reqwest features are correct (json, rustls-tls).
  • Track cleanup: avoid tokio full features and trim to only what is used.

100% traceable rejects and stats determinism

  • Every reject yields a stable machine-readable reason_code plus human reason_detail.
  • LoggedVerdict carries reason_code and reason_detail; legacy reason is set to the stable code when available.
  • Stats bucketing prefers reason_code, then falls back to reason, then ok, preventing splintered metrics.
  • TCP verdict path routes evaluation through a single policy evaluation function, mapping local reasons to rg-protocol wire reasons plus policy context.

Reason-code contract and docs alignment

  • Canonical reason codes: standardize TemplateVerdict.reason_code to stable snake_case aligned to rg_protocol::VerdictReason; UI and exports prefer reason_code over legacy reason.
  • Policy UX: tiered floors (min_avg_fee_lo/mid/hi) are the fee-floor inputs for dynamic tiers; examples/docs were updated accordingly.

rg-protocol alignment

  • Protocol version updated for v0.2.0 and treated as an explicit compatibility boundary.
  • TemplateVerdict includes stable reason coding and detail fields for operator-grade observability and downstream aggregation.
  • Evaluation mapping aligns verifier reasons to the wire representation with associated policy context.

Template manager (main.rs completed)

Async template sources

  • Introduce async TemplateSource via async_trait.
  • Isolate bitcoind RPC calls with spawn_blocking and use async backoff (tokio::time::sleep).

Stable template identity and dedupe

  • Add TemplateFingerprint built from height, prevhash, tx count, total fees, and an order-independent txid hash.
  • Derive template_id from the fingerprint via a stable hash, preventing duplicates across restarts and eliminating fake “new templates” from tx reordering.

Coinbase value correctness

  • If getblocktemplate returns coinbase_value == 0, template-manager computes a fallback as block subsidy + total fees and logs a warning to avoid downstream CoinbaseZero spam.

Hang prevention and bounded IO

  • Add timeouts around verifier connect and the send/receive path.
  • Bound writer write, newline write, and flush with timeouts.
  • Bound verifier response read to prevent indefinite stalls.

Single instance lock

  • Bind HTTP listener before starting the manager loop; if bind fails, exit immediately to prevent duplicate zombie managers.

HTTP observability

  • Expose /health, /templates, /mempool.
  • In-memory logs guarded by RwLock, with template log capped at 500 entries.

Shared bitcoind RPC client

  • Single shared Arc<Client> built once and reused for template polling and mempool snapshots.

Stratum mode correctness and latency

  • Stratum NDJSON parsing trims lines, skips empties, and logs the offending line on parse errors.
  • Real async delivery uses rx.recv().await.
  • Manager loop sleeps only on bitcoind backend; Stratum templates are not delayed by poll_secs.

Dev UX and demo tooling

  • Regtest reliability: dev-regtest.sh uses a dedicated datadir, kills only bitcoind instances bound to that datadir, waits for RPC readiness, fails-fast on port conflicts, and uses -named RPC calls where applicable.
  • RPC single source of truth: dev-bitcoin-cli.sh is authoritative (includes demo datadir and RPC creds).
  • Deterministic demo loop: dev-demo-phases.sh adds health gating, balance checks, clearer phase labeling, and optional finite run control.
  • Traffic generator: dev-traffic.sh uses -named sendtoaddress with explicit fee_rate, adds spendable balance checks, and exposes tuning knobs.
  • Stratum hygiene: dev-stratum.sh aligns with v0.2.0 policy env conventions, adds readiness gates, and fails-fast on port conflicts.
  • Documentation: update docs/ runbook to v0.2.0 (flat [policy] schema, env vars, regtest + Stratum workflows, reason_code/reason_detail semantics).
  • Demo note: demo scripts space sends/mining to avoid ancestor-limit failures (too many unconfirmed ancestors, error -6).

Repo policy files

  • Consolidate policy TOMLs to the v0.2.0 [policy] schema and bump protocol_version to match the compatibility boundary.
  • Refresh demo profiles (showcase/open/strict) to be schema-complete and aligned with updated demo scripts, including explicit unknown_mempool_as_high and reject_coinbase_zero where applicable.
Assets 2
Loading