Glossary¶

This glossary defines common terms used throughout the StackSats documentation, covering both Bitcoin-specific concepts and system-specific mechanics.

Bitcoin Terms¶

Sats (Satoshis)¶

The smallest unit of Bitcoin. - 1 Bitcoin (BTC) = 100,000,000 sats - 1 sat = 0.00000001 BTC

Strategies in this framework focus on maximizing the number of sats accumulated per dollar invested.

MVRV (Market Value to Realized Value)¶

A ratio used to assess whether Bitcoin is overvalued or undervalued relative to its "fair value". - Market Value: Current price $\times$ circulating supply. - Realized Value: The sum of the value of all coins at the price they last moved on-chain. This is often considered the aggregate "cost basis" of the network. - Interpretation: - High MVRV (> 3.0) often indicates market tops (price is far above cost basis). - Low MVRV (< 1.0) often indicates market bottoms (price is below cost basis).

Halving¶

An event that occurs approximately every 4 years where the rate of new Bitcoin issuance (block subsidy) is cut in half. This is a key component of Bitcoin's disinflationary monetary policy and often delineates 4-year market cycles.

Block Subsidy¶

The amount of new Bitcoin created in each block (approximately every 10 minutes) and awarded to the miner. This subsidy halves every 210,000 blocks.

System Terms¶

Bitcoin Research Kit (BRK)¶

The upstream Bitcoin analytics project whose canonical merged_metrics*.parquet dataset anchors StackSats' documented data workflow. StackSats supports BRK at the project and data-workflow level, but not as a promise of Rust crate API compatibility. See BRK Data Source for the canonical upstream links and support boundary.

Canonical merged_metrics parquet¶

The canonical Bitcoin analytics dataset used by StackSats is the long-format Bitcoin Research Kit (BRK) merged_metrics*.parquet distribution (day_utc, metric, value). See Merged Metrics Data Guide, Merged Metrics Parquet Schema, Merged Metrics Taxonomy, and BRK Data Source.

Runtime BRK parquet¶

Runtime commands and load_data(...) read a runtime-compatible BRK-wide parquet (for example bitcoin_analytics.parquet) via STACKSATS_ANALYTICS_PARQUET, managed default ~/.stacksats/data/bitcoin_analytics.parquet, or legacy local fallback ./bitcoin_analytics.parquet. This runtime parquet is a StackSats-derived artifact from canonical BRK merged_metrics. For custom DataFrames, use ColumnMapDataProvider or StrategyRunner.from_dataframe(...).

Allocation Span¶

The fixed window of time (default: 365 days) over which a fixed budget must be fully allocated. The model solves for the optimal distribution of capital over this rolling window.

Feasibility Clipping¶

The mechanism by which the framework ensures that a proposed daily weight is valid. It checks: 1. Non-negativity: Weights cannot be negative. 2. Maximum Weight: Access to daily liquidity is capped (default: 10% of total budget). 3. Remaining Budget: The weight cannot exceed the budget remaining for the current allocation span.

Strategy¶

User-defined logic for feature engineering, signals, and allocation intent.

FeatureTimeSeries¶

Validated input to a strategy: a Polars-backed time series with canonical date column and feature columns. Enforces schema (required columns) and time-series invariants (sorted unique dates; optional no-forward-looking check). Passed to the strategy via StrategyContext.features.

WeightTimeSeries¶

Validated output of a strategy: single-window weights, prices, and metadata. Enforces framework invariants (weight sum = 1, min/max daily weight, no forward-looking at export). Use WeightTimeSeriesBatch for multi-window exports.

Locked Prefix¶

The portion of the allocation timeline that is in the past. Once a day passes, its allocation is "locked" and cannot be changed by the strategy. This immutability ensures realistic backtesting and prevents "repainting" of history.

Sats per Dollar (SPD)¶

The primary efficiency metric for accumulation strategies. - Formula: $\text{Total Sats Accumulated} / \text{Total USD Invested}$ - Meaning: It represents the weighted average purchasing power of your capital. A higher SPD means you acquired more Bitcoin for the same amount of dollars compared to a benchmark (like uniform DCA). - Why it matters: In an accumulation strategy, the goal is to lower your average cost basis. Maximizing SPD is mathematically equivalent to minimizing average cost basis.

Run Artifacts¶

Files written by lifecycle commands under:

output/<strategy_id>/<version>/<run_id>/

Common artifacts include backtest_result.json, metrics.json, weights.csv, timeseries_schema.md, and artifacts.json.

Public API¶

Stable interfaces documented in top-level stacksats exports, documented artifact payloads, and the documented CLI subset.

Internal Modules¶

Lower-level implementation modules that may change between releases (for example stacksats.runner, stacksats.strategy_types, stacksats.backtest, stacksats.data.prelude, and stacksats.export_weights). Prefer top-level public API surfaces for long-term integrations.