docs: add ARCHITECTURE, ROADMAP, CITATION, FUNDING, editorconfig (#62)
Five governance + onboarding files that collectively close the "no high-level documentation outside of README" gap. - ARCHITECTURE.md: workspace layout, Indicator trait contract, per-indicator file conventions, numerical-stability notes, cross-crate flow diagram, navigation cheatsheet, deliberate non-goals, performance characteristics, stability commitments. - ROADMAP.md: north star, 0.3 / 0.4 / 0.5 release windows, indicator-wishlist intake rules, explicit non-goals, versioning policy. - CITATION.cff: GitHub-renders as "Cite this repository" button; enables academic adoption. - .github/FUNDING.yml: surfaces Sponsor button on the repo page. - .editorconfig: normalises indent/EOL across IDEs (Rust/Python 4 spaces, JS/TS/JSON/YAML/MD 2 spaces, Makefile tabs). Touches no Rust source, no CI workflows, no behaviour. Additive only. URLs in ROADMAP/CITATION already reference the post-transfer `wickra-lib/wickra` org so the files stay valid once the org migration in PR #59 lands; merge this PR only after #59 to keep main consistent.
This commit is contained in:
kingchenc
@@ -0,0 +1,34 @@
|
|||||||
|
# EditorConfig: https://editorconfig.org
|
||||||
|
# Keeps indentation and line-endings consistent across IDEs.
|
||||||
|
|
||||||
|
root = true
|
||||||
|
|
||||||
|
[*]
|
||||||
|
charset = utf-8
|
||||||
|
end_of_line = lf
|
||||||
|
insert_final_newline = true
|
||||||
|
trim_trailing_whitespace = true
|
||||||
|
indent_style = space
|
||||||
|
|
||||||
|
# Rust + Python + most config files use 4-space indents.
|
||||||
|
[*.{rs,py,toml}]
|
||||||
|
indent_size = 4
|
||||||
|
|
||||||
|
# JS / TS / JSON / YAML / Markdown use 2-space indents per ecosystem conventions.
|
||||||
|
[*.{js,ts,jsx,tsx,json,yml,yaml,md}]
|
||||||
|
indent_size = 2
|
||||||
|
|
||||||
|
# Markdown allows trailing whitespace as a hard line break — keep it intact.
|
||||||
|
[*.md]
|
||||||
|
trim_trailing_whitespace = false
|
||||||
|
|
||||||
|
# Makefiles must use tabs.
|
||||||
|
[Makefile]
|
||||||
|
indent_style = tab
|
||||||
|
|
||||||
|
# Generated files are not authored by humans; leave them alone.
|
||||||
|
[bindings/node/index.{js,d.ts}]
|
||||||
|
indent_style = unset
|
||||||
|
indent_size = unset
|
||||||
|
trim_trailing_whitespace = unset
|
||||||
|
insert_final_newline = unset
|
||||||
@@ -0,0 +1,6 @@
|
|||||||
|
# Funding sources surfaced on the repository "Sponsor" button.
|
||||||
|
# Each platform's value is the username/handle on that platform.
|
||||||
|
# Leave a key empty (e.g. patreon:) to skip a platform.
|
||||||
|
|
||||||
|
github: [kingchenc]
|
||||||
|
custom: ["https://wickra.org/sponsor"]
|
||||||
+321
@@ -0,0 +1,321 @@
|
|||||||
|
# Architecture
|
||||||
|
|
||||||
|
A walkthrough of how Wickra is organised internally — written for new
|
||||||
|
contributors who want to know **where the code lives, why it's split that
|
||||||
|
way, and which invariants they must not break**. Pair it with [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
||||||
|
for the day-to-day workflow.
|
||||||
|
|
||||||
|
## Workspace layout
|
||||||
|
|
||||||
|
Wickra is a Cargo workspace of three Rust crates plus three binding crates.
|
||||||
|
The split is deliberate: every concern that one user might want to disable
|
||||||
|
or replace lives behind a separate crate boundary.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ wickra (facade) │
|
||||||
|
│ re-exports wickra-core::* + wickra-data::* │
|
||||||
|
└──────────────┬──────────────────────────────────┬──────────────────┘
|
||||||
|
│ │
|
||||||
|
┌───────────▼──────────┐ ┌──────────▼─────────┐
|
||||||
|
│ wickra-core │ │ wickra-data │
|
||||||
|
│ indicator engine │ │ i/o + aggregation │
|
||||||
|
│ • 214 indicators │ │ • CSV reader │
|
||||||
|
│ • Indicator trait │ │ • Tick aggregator │
|
||||||
|
│ • BatchExt impl │ │ • Resampler │
|
||||||
|
│ • OHLCV / Candle │ │ • Live feeds │
|
||||||
|
│ no I/O, no deps │ │ optional features │
|
||||||
|
└──────────────────────┘ └────────────────────┘
|
||||||
|
▲
|
||||||
|
│ (every binding wraps the same core)
|
||||||
|
│
|
||||||
|
┌────────────┴───────────┬─────────────────────┐
|
||||||
|
│ │ │
|
||||||
|
┌──▼──────┐ ┌───────▼──────┐ ┌───────▼────────┐
|
||||||
|
│ Python │ │ Node │ │ WASM │
|
||||||
|
│ (PyO3) │ │ (napi-rs) │ │ (wasm-bindgen) │
|
||||||
|
└─────────┘ └──────────────┘ └────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
| Crate | Path | What it owns | Public deps |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `wickra-core` | `crates/wickra-core` | every indicator, the `Indicator` trait, `BatchExt`, `Candle`/`Tick` types, `Error` | `thiserror`, `rayon` (parallel batch) |
|
||||||
|
| `wickra` | `crates/wickra` | thin facade — re-exports everything user-facing from `wickra-core` and `wickra-data` | both internal crates |
|
||||||
|
| `wickra-data` | `crates/wickra-data` | CSV reader, tick aggregator, resampler, live exchange feeds (feature-gated) | `tokio`, `tokio-tungstenite` (live), `serde_json` |
|
||||||
|
| `wickra-python` | `bindings/python` | `_wickra` PyO3 module + Python package | `pyo3`, `numpy`, depends on `wickra-core` |
|
||||||
|
| `wickra-node` | `bindings/node` | NAPI-RS native binding | `napi`, depends on `wickra-core` |
|
||||||
|
| `wickra-wasm` | `bindings/wasm` | WebAssembly binding | `wasm-bindgen`, depends on `wickra-core` |
|
||||||
|
| `wickra-examples` | `examples/rust` | runnable binary examples | depends on `wickra`, `wickra-data` |
|
||||||
|
|
||||||
|
The `fuzz/` directory is **excluded** from the workspace (it has its own
|
||||||
|
`Cargo.toml`) because the libfuzzer-sys harness requires a nightly
|
||||||
|
toolchain, which would otherwise infect the stable workspace lints.
|
||||||
|
|
||||||
|
## The `Indicator` trait
|
||||||
|
|
||||||
|
Every indicator in Wickra implements one trait, defined in
|
||||||
|
`crates/wickra-core/src/traits.rs`:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub trait Indicator {
|
||||||
|
type Input;
|
||||||
|
type Output;
|
||||||
|
|
||||||
|
fn update(&mut self, input: Self::Input) -> Option<Self::Output>;
|
||||||
|
fn reset(&mut self);
|
||||||
|
fn warmup_period(&self) -> usize;
|
||||||
|
fn is_ready(&self) -> bool;
|
||||||
|
fn name(&self) -> &'static str;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Four design choices that are non-negotiable:
|
||||||
|
|
||||||
|
1. **Streaming-first.** `update` is the only computation entry point. Each
|
||||||
|
call must be O(1) amortised — no replays over history, no `clone`s of
|
||||||
|
the input window unless absolutely necessary.
|
||||||
|
2. **`Option<Output>` warmup.** A new indicator returns `None` until it has
|
||||||
|
ingested `warmup_period()` inputs. After that it returns `Some(value)`
|
||||||
|
on every call. The `None` → `Some` transition happens exactly once per
|
||||||
|
`reset()`.
|
||||||
|
3. **Reset is mandatory.** Calling `reset()` returns the indicator to the
|
||||||
|
state of a newly constructed one. Tests verify this for every indicator.
|
||||||
|
4. **No interior mutability across `update` calls.** Indicators may hold
|
||||||
|
`VecDeque` / array state, but no `Cell`/`RefCell`/`Mutex` should be
|
||||||
|
needed — `&mut self` is the only mutation channel.
|
||||||
|
|
||||||
|
### Batch is free
|
||||||
|
|
||||||
|
`BatchExt` is a blanket impl over `Indicator`:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
impl<I: Indicator> BatchExt for I {
|
||||||
|
fn batch<'a>(&mut self, input: &'a [I::Input]) -> Vec<Option<I::Output>>
|
||||||
|
where I::Input: Copy
|
||||||
|
{
|
||||||
|
input.iter().map(|x| self.update(*x)).collect()
|
||||||
|
}
|
||||||
|
fn batch_parallel(...) // rayon-based for multi-asset processing
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Consequence: **every indicator gets batch and parallel-batch for free** as
|
||||||
|
soon as `Indicator` is implemented. Tests verify `batch == streaming`
|
||||||
|
equivalence on every indicator — this is the `batch_equals_streaming` test
|
||||||
|
that appears in every indicator module.
|
||||||
|
|
||||||
|
## Indicator-module convention
|
||||||
|
|
||||||
|
Each indicator lives in its own file under
|
||||||
|
`crates/wickra-core/src/indicators/`. Naming: snake-case of the struct,
|
||||||
|
e.g. `Sma` → `sma.rs`, `MacdIndicator` → `macd.rs`.
|
||||||
|
|
||||||
|
Layout inside an indicator file is uniform:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
//! Doc-comment with the formula and one-line summary.
|
||||||
|
|
||||||
|
use std::collections::VecDeque;
|
||||||
|
use crate::error::{Error, Result};
|
||||||
|
use crate::traits::Indicator;
|
||||||
|
|
||||||
|
/// Public struct + rustdoc with mathematical definition + a runnable example.
|
||||||
|
#[derive(Debug, Clone)]
|
||||||
|
pub struct Foo { /* state fields */ }
|
||||||
|
|
||||||
|
impl Foo {
|
||||||
|
/// Constructor with parameter validation.
|
||||||
|
pub fn new(period: usize, ...) -> Result<Self> { ... }
|
||||||
|
/// Const accessors for configured params.
|
||||||
|
pub const fn period(&self) -> usize { ... }
|
||||||
|
}
|
||||||
|
|
||||||
|
impl Indicator for Foo {
|
||||||
|
type Input = f64; // or (f64, f64), or Candle
|
||||||
|
type Output = f64; // or FooOutput { ... }
|
||||||
|
fn update(...) -> ... { ... }
|
||||||
|
fn reset(...) { ... }
|
||||||
|
fn warmup_period(...) -> usize { ... }
|
||||||
|
fn is_ready(...) -> bool { ... }
|
||||||
|
fn name(...) -> &'static str { "Foo" }
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(test)]
|
||||||
|
mod tests {
|
||||||
|
// mandatory tests (every indicator):
|
||||||
|
// - rejects_invalid_params
|
||||||
|
// - accessors_and_metadata
|
||||||
|
// - reference_value (vs TA-Lib / pandas-ta / hand-calculated)
|
||||||
|
// - ignores_non_finite_input
|
||||||
|
// - reset_clears_state
|
||||||
|
// - batch_equals_streaming
|
||||||
|
// plus indicator-specific edge cases
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The `FAMILIES` constant in `mod.rs` (introduced in PR #60) is the
|
||||||
|
machine-readable index of which family every indicator belongs to. It is
|
||||||
|
the canonical taxonomy; README and Wiki tables should be derived from it.
|
||||||
|
|
||||||
|
## Input types
|
||||||
|
|
||||||
|
| Input | Used for | Examples |
|
||||||
|
|---|---|---|
|
||||||
|
| `f64` | Scalar inputs — usually a price or a return | SMA, EMA, RSI, ROC |
|
||||||
|
| `Candle` | OHLCV bar — `{open, high, low, close, volume, timestamp}` | ATR, Bollinger, Ichimoku, all candlestick patterns |
|
||||||
|
| `(f64, f64)` | Two-series indicators — `(asset, benchmark)` or `(x, y)` | PearsonCorrelation, Beta, Alpha, TreynorRatio |
|
||||||
|
|
||||||
|
The `Candle` type lives in `wickra-core::ohlcv` and is the binding
|
||||||
|
contract across bindings — Python's `Candle` namedtuple, Node's
|
||||||
|
`Candle` object, and WASM's `Candle` JS class all map 1:1.
|
||||||
|
|
||||||
|
## Output types
|
||||||
|
|
||||||
|
Most indicators emit `f64`. Multi-output indicators emit a dedicated
|
||||||
|
struct in the same module, named `FooOutput`:
|
||||||
|
|
||||||
|
```rust
|
||||||
|
pub struct BollingerOutput {
|
||||||
|
pub upper: f64,
|
||||||
|
pub middle: f64,
|
||||||
|
pub lower: f64,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Bindings flatten these into matrix outputs (NumPy 2-D array for Python,
|
||||||
|
typed object arrays for Node/WASM).
|
||||||
|
|
||||||
|
## Numerical-stability notes
|
||||||
|
|
||||||
|
A handful of indicators need care beyond naive accumulation:
|
||||||
|
|
||||||
|
- **Welford's online variance** is used in `StdDev`, `Variance`, `ZScore`,
|
||||||
|
`BollingerBands`, and several others. Standard sum-of-squares is
|
||||||
|
catastrophically lossy for low-variance inputs; Welford's recurrence
|
||||||
|
keeps O(eps) error.
|
||||||
|
- **Kahan summation** is used wherever rolling sums could span > 1e6
|
||||||
|
elements without resetting — currently only Hurst-exponent's R/S
|
||||||
|
chunks. Most rolling sums are bounded by the window size and don't need
|
||||||
|
it.
|
||||||
|
- **Logarithm bases** matter for some indicators (Hurst, MFI). Wickra
|
||||||
|
uses natural log everywhere unless the reference math explicitly
|
||||||
|
requires `log10` or `log2` — and then it documents the choice in the
|
||||||
|
rustdoc.
|
||||||
|
- **NaN / infinity guards.** Every indicator's `update` rejects
|
||||||
|
non-finite input early (returns `None` without state mutation). Tests
|
||||||
|
cover this with `ignores_non_finite_input`.
|
||||||
|
|
||||||
|
## Cross-crate flow
|
||||||
|
|
||||||
|
A typical full-stack call sequence for a Python live-trading example:
|
||||||
|
|
||||||
|
```
|
||||||
|
[ Python: live_trading.py ]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[ binance.AsyncClient WebSocket ] ──── wickra_data live feed ───┐
|
||||||
|
│
|
||||||
|
┌──────────────────┘
|
||||||
|
▼
|
||||||
|
[ Candle struct conversion ]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[ PyRsi.update(close) ]
|
||||||
|
│
|
||||||
|
wraps │
|
||||||
|
▼
|
||||||
|
[ wickra_core::Rsi::update(f64) ] <-- the only place math runs
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[ Option<f64> -> Py<PyFloat> ]
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[ Python user code ]
|
||||||
|
```
|
||||||
|
|
||||||
|
The same call sequence happens identically for Node (via NAPI),
|
||||||
|
WASM (via wasm-bindgen → JS), and Rust (no FFI overhead, just direct
|
||||||
|
calls).
|
||||||
|
|
||||||
|
## What lives where — the navigation cheat sheet
|
||||||
|
|
||||||
|
| You want to … | Look in |
|
||||||
|
|---|---|
|
||||||
|
| add a new indicator | `crates/wickra-core/src/indicators/<name>.rs` + add to `mod.rs` + add to `FAMILIES` + re-export in `lib.rs` |
|
||||||
|
| change the `Indicator` trait surface | `crates/wickra-core/src/traits.rs` — this affects every indicator, treat as breaking |
|
||||||
|
| add a new Candle field | `crates/wickra-core/src/ohlcv.rs` — also propagates to every binding's `Candle` mapping |
|
||||||
|
| add a new exchange / data source | `crates/wickra-data/src/live/<exchange>.rs`, feature-gated under `live-<exchange>` |
|
||||||
|
| expose a new binding | new crate under `bindings/` + macro-driven boilerplate in `bindings/<lang>/src/lib.rs` |
|
||||||
|
| change benchmark coverage | `crates/wickra/benches/indicators.rs` |
|
||||||
|
| add a new fuzz target | `fuzz/fuzz_targets/<name>.rs` + register in `fuzz/Cargo.toml` |
|
||||||
|
| change CI matrix | `.github/workflows/ci.yml` |
|
||||||
|
| change release pipeline | `.github/workflows/release.yml` (irreversible on `v*` tag — test on a throwaway tag first) |
|
||||||
|
|
||||||
|
## What is **deliberately** not in this repo
|
||||||
|
|
||||||
|
- **Backtest framework.** Wickra is an indicator library, not a backtester.
|
||||||
|
Strategy + PnL + fills logic is for the user (see `examples/` for
|
||||||
|
illustrative scripts).
|
||||||
|
- **Multi-exchange aggregation.** Binance is the demo feed; full
|
||||||
|
exchange-agnostic aggregation is `ccxt`'s job. Wickra's
|
||||||
|
`wickra-data::live` is intentionally minimal.
|
||||||
|
- **Order-book / L2 data.** Wickra works on OHLCV bars and ticks, not
|
||||||
|
full depth. Tick-data variants (cumulative delta, single print) are on
|
||||||
|
the roadmap but require new input types.
|
||||||
|
- **Charting / visualization.** Out of scope for the Rust core. The
|
||||||
|
WASM examples include a `lightweight-charts` integration as a
|
||||||
|
starting point, but no charting code lives in the published packages.
|
||||||
|
- **GPU / SIMD optimisation.** Indicators are O(1) per update — the
|
||||||
|
bottleneck is not vector throughput. SIMD would only help large-batch
|
||||||
|
workloads, which already saturate memory bandwidth via the cache-
|
||||||
|
friendly `VecDeque` window.
|
||||||
|
|
||||||
|
## Performance characteristics
|
||||||
|
|
||||||
|
Every indicator is amortised O(1) per `update`. The constant factor
|
||||||
|
varies:
|
||||||
|
|
||||||
|
| Class | Indicators | Per-`update` cost (approx) |
|
||||||
|
|---|---|---|
|
||||||
|
| Simple rolling | SMA, EMA, WMA, Mom | 1-2 floating-point ops |
|
||||||
|
| Recursive smoothers | KAMA, FRAMA, VIDYA, JMA | 5-15 ops |
|
||||||
|
| Window-sort | OmegaRatio, percentile-based VaR | O(period · log period) per update |
|
||||||
|
| Multi-buffer DSP | MAMA, HilbertDominantCycle, EmpiricalModeDecomposition | 30-80 ops |
|
||||||
|
| Multi-component | MacdIndicator, TtmSqueeze, Alligator | sum of components |
|
||||||
|
|
||||||
|
Benchmarks against real BTCUSDT 1-minute data live in
|
||||||
|
`crates/wickra/benches/indicators.rs`. Cross-library comparison vs
|
||||||
|
TA-Lib / pandas-ta / talipp / finta lives in
|
||||||
|
`bindings/python/benchmarks/compare_libraries.py`.
|
||||||
|
|
||||||
|
## Stability commitments
|
||||||
|
|
||||||
|
- **MSRV.** Workspace: Rust 1.86. Node binding: 1.88 (NAPI-RS pins it).
|
||||||
|
- **`Indicator` trait surface.** Breaking changes here are major-version
|
||||||
|
events. Adding a new method with a default impl is minor.
|
||||||
|
- **Indicator removal.** Once an indicator ships in a release, it stays
|
||||||
|
callable. Renames go through a deprecation period of at least one
|
||||||
|
minor version.
|
||||||
|
- **Output structs.** Adding a field to a `FooOutput` is non-breaking
|
||||||
|
because the binding contracts go through serde and accept extra keys.
|
||||||
|
|
||||||
|
## Open questions / known sharp edges
|
||||||
|
|
||||||
|
These are documented for contributors so you don't waste time
|
||||||
|
re-discovering them.
|
||||||
|
|
||||||
|
- **`Rvi`** (Relative Vigor Index) and `RviVolatility` (Relative
|
||||||
|
Volatility Index) are different indicators with the same short
|
||||||
|
acronym — make sure you import the right one.
|
||||||
|
- **Fuzz coverage of pair indicators** uses `indicator_update_pair.rs`,
|
||||||
|
which is small because pair indicators are simpler — but coverage
|
||||||
|
should grow as more pair indicators land.
|
||||||
|
- **`FAMILIES` (from PR #60) is hand-maintained.** Adding a new
|
||||||
|
indicator requires a separate entry in `FAMILIES`. The
|
||||||
|
`total_count_matches_expected` test will fail if you forget.
|
||||||
|
- **WASM does not have automated tests yet.** Smoke-validated only
|
||||||
|
through the manual examples. Adding `wasm-bindgen-test` coverage is
|
||||||
|
on the roadmap.
|
||||||
|
|
||||||
|
For the high-level project goals see [`ROADMAP.md`](ROADMAP.md); for
|
||||||
|
day-to-day contribution mechanics see [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
cff-version: 1.2.0
|
||||||
|
title: Wickra
|
||||||
|
message: >-
|
||||||
|
If you use Wickra in academic work, please cite it using the metadata
|
||||||
|
below.
|
||||||
|
type: software
|
||||||
|
authors:
|
||||||
|
- alias: kingchenc
|
||||||
|
email: wickra.lib@gmail.com
|
||||||
|
repository-code: "https://github.com/wickra-lib/wickra"
|
||||||
|
url: "https://wickra.org"
|
||||||
|
abstract: >-
|
||||||
|
Wickra is a streaming-first technical-analysis library implemented in
|
||||||
|
Rust with bindings for Python, Node.js and WebAssembly. Each indicator
|
||||||
|
is a state machine that updates in constant time per new input, so
|
||||||
|
identical code paths serve live-trading workloads and historical
|
||||||
|
back-testing. The library covers 214 indicators across 16 families
|
||||||
|
(moving averages, momentum, volatility, volume, statistics, Ehlers
|
||||||
|
digital-signal-processing cycles, pivots, DeMark, Ichimoku, candlestick
|
||||||
|
patterns, market profile, and risk/performance metrics).
|
||||||
|
keywords:
|
||||||
|
- technical-analysis
|
||||||
|
- technical-indicators
|
||||||
|
- streaming
|
||||||
|
- algorithmic-trading
|
||||||
|
- quantitative-finance
|
||||||
|
- rust
|
||||||
|
- time-series
|
||||||
|
license: PolyForm-Noncommercial-1.0.0
|
||||||
+203
@@ -0,0 +1,203 @@
|
|||||||
|
# Roadmap
|
||||||
|
|
||||||
|
What Wickra is heading toward, what is explicitly out of scope, and what
|
||||||
|
contributors can expect across the next 0.x versions. Roadmap items are
|
||||||
|
**aspirations, not commitments** — order may shift based on real
|
||||||
|
user-feedback and bug-priority.
|
||||||
|
|
||||||
|
For "what shipped already" see [`CHANGELOG.md`](CHANGELOG.md). For the
|
||||||
|
internal structure that the roadmap items will plug into, see
|
||||||
|
[`ARCHITECTURE.md`](ARCHITECTURE.md).
|
||||||
|
|
||||||
|
## North star
|
||||||
|
|
||||||
|
> A streaming-first technical-analysis core that is the obvious default
|
||||||
|
> for anyone writing a Rust, Python, Node or browser-based trading
|
||||||
|
> system — drop-in fast, drop-in correct, drop-in tested.
|
||||||
|
|
||||||
|
Three measurable proxies for "obvious default":
|
||||||
|
|
||||||
|
1. **Coverage.** Every textbook indicator from TA-Lib, pandas-ta and
|
||||||
|
talipp is in Wickra and produces matching reference values.
|
||||||
|
2. **Performance.** Streaming `update` is the fastest published number
|
||||||
|
across Rust / Python / Node / WASM for any technical indicator.
|
||||||
|
3. **Trust.** Releases are reproducible, signed, SBOM-attached, with a
|
||||||
|
public 100% test/branch coverage badge.
|
||||||
|
|
||||||
|
## 0.3.0 — target window: Q3 2026
|
||||||
|
|
||||||
|
The first release after the org migration to `wickra-lib` lands and the
|
||||||
|
project portal at `wickra.org` is live.
|
||||||
|
|
||||||
|
### Headline goals
|
||||||
|
|
||||||
|
- **WASM has automated tests.** `wasm-bindgen-test` job in CI exercising
|
||||||
|
a representative subset (~30 indicators across all families). Today
|
||||||
|
WASM is only smoke-validated through manual examples.
|
||||||
|
- **Release-pipeline trust.** SBOM (CycloneDX) generated per release,
|
||||||
|
Sigstore cosign signatures attached to every published artifact,
|
||||||
|
npm `--provenance` flag enabled, PyPI Trusted Publishers configured.
|
||||||
|
- **Hosted documentation portal.** `wickra.org` (Cloudflare Pages,
|
||||||
|
VitePress) replaces the GitHub Wiki as the canonical doc surface.
|
||||||
|
Per-indicator deep-dives, quickstarts, FAQ, search.
|
||||||
|
- **End-to-end strategy examples.** 3 runnable examples that wire
|
||||||
|
Wickra indicators into a full mean-reversion / trend-following /
|
||||||
|
breakout strategy with PnL and equity-curve output.
|
||||||
|
- **`ARCHITECTURE.md` + `ROADMAP.md` + `CITATION.cff`** governance
|
||||||
|
baseline (this is it).
|
||||||
|
|
||||||
|
### Stretch goals (might slip to 0.4.0)
|
||||||
|
|
||||||
|
- **Per-binding hosted API reference.** TypeDoc for Node/WASM,
|
||||||
|
Sphinx for Python, both hosted on `wickra.org/api/*`. Rust stays on
|
||||||
|
`docs.rs`.
|
||||||
|
- **Property-tests (`proptest`) for mathematical invariants.** Bound
|
||||||
|
checks on RSI ∈ [0, 100], Bollinger ordering, batch-streaming
|
||||||
|
equivalence on random inputs.
|
||||||
|
- **Nightly long-fuzz workflow.** Each fuzz target gets ~1h overnight,
|
||||||
|
findings auto-converted to issues.
|
||||||
|
|
||||||
|
## 0.4.0 — target window: Q4 2026
|
||||||
|
|
||||||
|
### Indicator catalogue expansion
|
||||||
|
|
||||||
|
The current 214 indicators cover the textbook canon. The next wave is
|
||||||
|
the "stuff people actually ask for but skip because it's painful in
|
||||||
|
other libs":
|
||||||
|
|
||||||
|
- **Anchored indicators.** AnchoredVwap is already in, but anchored
|
||||||
|
variants of common indicators (AnchoredATR, AnchoredVolatility) are
|
||||||
|
on the wishlist for explicit session-based analysis.
|
||||||
|
- **Multi-timeframe (MTF) chaining helpers.** A `Mtf<Indicator>` wrapper
|
||||||
|
that runs an indicator on a different timeframe of the same input
|
||||||
|
stream — solves the most common reason people drop down to ad-hoc
|
||||||
|
buffering code.
|
||||||
|
- **Order-flow primitives** (gated on tick-data ingestion landing in
|
||||||
|
`wickra-data`): CumulativeDelta, BidAskImbalance, VolumeAtPrice.
|
||||||
|
- **Pivot-confirmation patterns.** WilliamsFractals is already in;
|
||||||
|
ZigZag is in. Next: PivotHigh/PivotLow with configurable
|
||||||
|
left/right-bar confirmation, used as a feature for higher-level
|
||||||
|
pattern detectors.
|
||||||
|
- **Harmonic-chart patterns** (Gartley, Bat, Butterfly, Crab, Shark).
|
||||||
|
These need the pivot-detector + ratio-matcher framework first; the
|
||||||
|
candlestick-pattern family from 0.2.8 is the precedent.
|
||||||
|
|
||||||
|
### Live-data layer
|
||||||
|
|
||||||
|
- **Tick-data ingestion.** Extend `wickra-data` from OHLCV-only to
|
||||||
|
also accept raw ticks; the existing `Aggregator` already aggregates
|
||||||
|
ticks into bars but isn't exposed in the public live-feed API yet.
|
||||||
|
- **Generic exchange trait.** `LiveFeed { fn subscribe(...) -> impl
|
||||||
|
Stream<Item = Candle> }` so the Binance adapter is one implementor
|
||||||
|
among many. **Note**: Wickra will not aggregate exchanges itself
|
||||||
|
(use `ccxt` if you need that) — the trait exists so user code can
|
||||||
|
swap feeds without touching indicator code.
|
||||||
|
|
||||||
|
### Performance & reliability
|
||||||
|
|
||||||
|
- **Performance-regression tracking.** `bench.yml` outputs deployed to
|
||||||
|
a `gh-pages` branch, `github-action-benchmark` plot over time,
|
||||||
|
threshold-based alerts on regression.
|
||||||
|
- **Indicator parity test suite.** Every indicator that has a TA-Lib
|
||||||
|
/ pandas-ta / talipp equivalent must pass a golden-value test
|
||||||
|
against that reference. Currently most do but the test names are
|
||||||
|
scattered — consolidate into one `parity_tests` module.
|
||||||
|
|
||||||
|
## 0.5.0 — target window: 2027 H1
|
||||||
|
|
||||||
|
### Possible new bindings
|
||||||
|
|
||||||
|
Open questions, prioritised by demand signals (≈ GitHub stars + issue
|
||||||
|
requests + community polls):
|
||||||
|
|
||||||
|
- **Java / Kotlin** binding via UniFFI — interest from Android-side
|
||||||
|
trading-app developers and the JVM-quant community.
|
||||||
|
- **Go** binding — interest from algorithmic-trading shops running on
|
||||||
|
Linux + Go infra.
|
||||||
|
- **C / C++** header export (`cbindgen`) — drops Wickra into existing
|
||||||
|
C/C++ trading stacks (e.g. older Bloomberg / FIX-protocol shops).
|
||||||
|
- **Swift** — niche but real, iOS / macOS native trading apps.
|
||||||
|
- **.NET** — closes the Windows-native gap that NAPI-Node doesn't fill
|
||||||
|
(some shops are still on .NET Framework).
|
||||||
|
|
||||||
|
None of these are committed — each is a 1-2-month project on its own,
|
||||||
|
and bindings without active maintenance are a liability. Priority will
|
||||||
|
be driven by which language community shows up with PRs.
|
||||||
|
|
||||||
|
### `wickra-data` widening
|
||||||
|
|
||||||
|
- **Historical fetch from > 1 source.** Today only Binance REST/WS.
|
||||||
|
Add Coinbase and Kraken as reference implementations — explicitly
|
||||||
|
not exchange-aggregation, just "here are two more adapters using
|
||||||
|
the trait".
|
||||||
|
|
||||||
|
## Beyond — long-term aspirations
|
||||||
|
|
||||||
|
- **`wickra-backtest` sub-crate** (decision pending). A minimal
|
||||||
|
event-driven backtester wrapping signal generation + position
|
||||||
|
sizing + fees + slippage. Decision factor: do users keep building
|
||||||
|
these ad-hoc from `examples/`? If yes, codifying it saves the
|
||||||
|
ecosystem time. If most users plug Wickra into existing backtesters
|
||||||
|
(vectorbt, backtrader, Lean, Hummingbot), keep Wickra focused.
|
||||||
|
- **`wickra-plot` companion** (low priority). `plotters`-backed Rust
|
||||||
|
rendering of indicator outputs. Mainly useful for static report
|
||||||
|
generation; live charting belongs in the JS/web layer.
|
||||||
|
- **Academic adoption.** Citable `CITATION.cff`; targeting at least
|
||||||
|
one peer-reviewed paper using Wickra as the reference indicator
|
||||||
|
engine.
|
||||||
|
|
||||||
|
## What is explicitly **not** on the roadmap
|
||||||
|
|
||||||
|
These are recurring requests that Wickra will decline so contributors
|
||||||
|
don't waste time on them:
|
||||||
|
|
||||||
|
| Feature | Why declined |
|
||||||
|
|---|---|
|
||||||
|
| Exchange aggregation across N venues | That's `ccxt`'s job. Wickra ships *one* feed implementor (Binance) for tests and demo; users plug their preferred exchange. |
|
||||||
|
| Full backtesting framework (à la Lean, vectorbt) | Scope creep. May land as `wickra-backtest` *if* a clear minimal API surfaces from user demand, but Wickra core stays an indicator library. |
|
||||||
|
| Strategy auto-tuning / hyperparameter search | Wrong abstraction layer — belongs in user-side ML/backtester. |
|
||||||
|
| Order-management / broker integration | Even further out of scope. |
|
||||||
|
| GUI / web-based studio | Marketing-site demos are fine; full IDE is not. |
|
||||||
|
| Indicator implementations that require optional Python deps (e.g. scipy KDE) | Bindings must work on a clean install. Pure-Rust math only. |
|
||||||
|
| Proprietary indicator implementations (e.g. paywalled vendor formulas) | License conflicts + audit burden. |
|
||||||
|
| GPU / CUDA acceleration | O(1) per update means the bottleneck is API overhead, not compute. SIMD-batch is a maybe; GPU adds no value for streaming. |
|
||||||
|
|
||||||
|
## How indicator wishlist requests are handled
|
||||||
|
|
||||||
|
1. **Open an issue** using the `feature_request` template, naming the
|
||||||
|
indicator, citing one of:
|
||||||
|
- TA-Lib reference
|
||||||
|
- pandas-ta reference
|
||||||
|
- peer-reviewed paper
|
||||||
|
- widely-published trading book
|
||||||
|
2. Maintainer triages within ~1 week. Acceptance criteria:
|
||||||
|
- Formula has at least one written reference (no random
|
||||||
|
YouTuber-only indicators)
|
||||||
|
- Implementation can be O(1) streaming
|
||||||
|
- Test vectors are obtainable (from reference lib, hand-computed,
|
||||||
|
or paper-provided)
|
||||||
|
3. Once accepted, the indicator gets added to the next family-batch
|
||||||
|
PR. Family-batches typically ship 5-20 indicators at a time.
|
||||||
|
|
||||||
|
## Versioning
|
||||||
|
|
||||||
|
Wickra follows [SemVer](https://semver.org/). The promise:
|
||||||
|
|
||||||
|
- **0.x.0 (minor):** new indicators, new bindings, new optional features,
|
||||||
|
new optional config knobs. Adding methods to `Indicator` with default
|
||||||
|
impls is minor.
|
||||||
|
- **0.x.y (patch):** bug fixes, performance improvements, doc fixes.
|
||||||
|
- **Major (1.0.0 and later):** changes to the `Indicator` trait
|
||||||
|
signature, removal of indicators, breaking changes to `Candle` /
|
||||||
|
`OHLCV` field order.
|
||||||
|
|
||||||
|
The 1.0 milestone is reserved for when the indicator catalogue is
|
||||||
|
considered "stable enough" and the bindings API has stabilised — likely
|
||||||
|
~2027 once 2-3 more bindings have shipped and stress-tested the trait.
|
||||||
|
|
||||||
|
## Discussion
|
||||||
|
|
||||||
|
For roadmap discussion, open a [Discussions](https://github.com/wickra-lib/wickra/discussions)
|
||||||
|
thread tagged `roadmap`. Specific indicator wishlist items go in
|
||||||
|
[Issues](https://github.com/wickra-lib/wickra/issues) via the
|
||||||
|
`feature_request` template.
|
||||||
Reference in New Issue
Block a user