# StackSats

StackSats, developed by [Hypertrial](https://www.hypertrail.ai), is a Python package for developing and backtesting Bitcoin DCA ("stacking sats") allocation strategies.

Learn more at [www.stackingsats.org](https://www.stackingsats.org)

It provides:
- A clean strategy interface (`WindowStrategy`)
- Built-in and example strategies
- A rolling-window backtest engine
- Feature precomputation utilities
- Validation checks for leakage, constraints, and win-rate

## Installation

Install core package for local model development:

```bash
pip install stacksats
```

For local development from source:

```bash
pip install -e .
pip install -r requirements-dev.txt
```

Install deployment dependencies only if needed:

```bash
pip install "stacksats[deploy]"
```

## Quick Start (write your own strategy file)

Create `my_strategy.py`:

```python
import numpy as np
import pandas as pd

from stacksats import run_backtest, validate_strategy


class MyStrategy:
    def compute_weights(
        self,
        features_df: pd.DataFrame,
        start_date: pd.Timestamp,
        end_date: pd.Timestamp,
        current_date: pd.Timestamp,
    ) -> pd.Series:
        del current_date
        window = features_df.loc[start_date:end_date]
        if window.empty:
            return pd.Series(dtype=float)

        z = window.get("mvrv_zscore", pd.Series(0.0, index=window.index)).to_numpy()
        ma = window.get("price_vs_ma", pd.Series(0.0, index=window.index)).to_numpy()
        raw = np.exp((-1.2 * z) + (-0.8 * ma))
        w = raw / raw.sum()
        return pd.Series(w, index=window.index)


if __name__ == "__main__":
    strategy = MyStrategy()

    validation = validate_strategy(strategy)
    print(validation.summary())

    result = run_backtest(strategy, strategy_label="my-strategy")
    print(result.summary())
    result.plot(output_dir="output")
    result.to_json("output/backtest_result.json")
```

Run it directly:

```bash
python my_strategy.py
```

For a complete command reference using the included example file, see
[`docs/commands.md`](docs/commands.md).

## Public API

Top-level package exports:

- `run_backtest()`: Run a rolling-window backtest for any strategy
- `validate_strategy()`: Run submission-style validation checks
- `load_data()`: Load BTC market data (with local cache support)
- `precompute_features()`: Build model features from BTC data
- `load_strategy()`: Load a strategy from `module_or_path:ClassName`
- `BacktestResult`: Result object with summary/plot/serialization helpers
- `ValidationResult`: Structured validation output
- `WindowStrategy`, `CallableWindowStrategy`, `MVRVStrategy`

`load_data()` also supports cache controls via optional keyword args:
- `cache_dir` (default `~/.stacksats/cache`, set to `None` to disable local cache)
- `max_age_hours` (default `24`, refresh threshold for cached CoinMetrics CSV)

## Writing a Strategy

Implement `compute_weights()` with this interface:

```python
def compute_weights(
    self,
    features_df: pd.DataFrame,
    start_date: pd.Timestamp,
    end_date: pd.Timestamp,
    current_date: pd.Timestamp,
) -> pd.Series:
    ...
```

Rules your strategy should satisfy:

- Return a weight series indexed by dates in the selected window
- Weights should be non-negative
- Weights should sum to `1.0`
- Avoid forward-looking data usage

### Available Features

Feature columns are generated by `precompute_features()` and typically include:

- `PriceUSD_coinmetrics`
- `price_ma`
- `price_vs_ma`
- `mvrv_zscore`
- `mvrv_gradient`
- `mvrv_percentile`
- `mvrv_acceleration`
- `mvrv_zone`
- `mvrv_volatility`
- `signal_confidence`

## Built-in and Example Strategies

### Built-in

- `MVRVStrategy`: Default strategy from the package model.

### Examples

In `stacksats.strategies.examples`:

- `UniformStrategy`
- `SimpleZScoreStrategy`
- `MomentumStrategy`

These are lightweight templates for custom model development.

## Backtesting

Run the default built-in strategy:

```bash
stacksats-backtest
```

Run a custom strategy class from a file:

```bash
stacksats-backtest --strategy my_strategy.py:MyStrategy --start-date 2020-01-01 --end-date 2025-01-01
```

Use the Python API directly:

```python
from stacksats import MVRVStrategy, run_backtest

result = run_backtest(MVRVStrategy(), strategy_label="default-mvrv")
print(result.summary())
```

## Validation

Validate built-in strategy:

```bash
stacksats-validate --start-date 2020-01-01 --end-date 2025-01-01
```

Validate a custom strategy class:

```bash
stacksats-validate --strategy my_strategy.py:MyStrategy --min-win-rate 50.0
```

## Command Line Tools

Installed scripts:

- `stacksats-backtest`
- `stacksats-export`
- `stacksats-plot-mvrv`
- `stacksats-plot-weights`
- `stacksats-validate`

Custom-strategy flags:

- `stacksats-backtest --strategy module_or_path:ClassName`
- `stacksats-validate --strategy module_or_path:ClassName`
- `stacksats-export --strategy module_or_path:ClassName`

## Advanced: Deployment

Deployment and infrastructure modules are optional:

- `stacksats.export_weights`
- `stacksats.modal_app`

These require deployment extras:

```bash
pip install "stacksats[deploy]"
```

Deploy with built-in strategy:

```bash
modal deploy stacksats/modal_app.py
```

Deploy with custom strategy:

```bash
STACKSATS_STRATEGY=my_strategy.py:MyStrategy modal deploy stacksats/modal_app.py
```

## Development

Run tests:

```bash
pytest tests/ -v
```

Verify documented command examples:

```bash
# Requires ./venv (for example: python -m venv venv && source venv/bin/activate && pip install -e .)
python scripts/test_example_commands.py
```

Run lint:

```bash
ruff check .
```

Release process: see `docs/release.md`.

## Contributors

This project has benefited from contributions by researchers from the following universities:

- Columbia University (Master of Data Science)
- Cornell University (Master of Engineering in Management)
- Georgia Institute of Technology (Master of Science in Analytics)
- London School of Economics (Master of Science in Data Science)
- University of British Columbia (Master of Data Science)
- University of California, Davis (Master of Science in Business Analytics)
- University of California, Irvine (Master of Data Science)
- University of California, San Diego (Master of Quantitative Finance)
