wickra-synth 0.2.0

---

Deterministic synthetic market microstructure — OHLCV, order book, trades and funding from a single seed, byte-identical across ten languages.

▶ Live demos: the backtester compiled to WebAssembly, an equity curve building bar by bar — backtest-live.wickra.org; one StrategySpec side by side in Python, Rust, JS and Go — playground.wickra.org; all 514 indicators of the core over a real Binance feed — live.wickra.org. Zero backend, all of them.

Part of the Wickra ecosystem: the same data-driven core and ten-language binding surface also power wickra-exchange, wickra-backtest, wickra-terminal and 20 more — see the full list.

Wickra Synth is one data-driven core, wickra-synth-core: a serde GenSpec describes a market regime, a fixed portable PRNG (SplitMix64 seeding xoshiro256++) drives it, and the core emits OHLCV candles plus order-book snapshots, trades and funding samples — realistic synthetic microstructure for tests, training and demos. Because the RNG lives only in the Rust core and is portable-deterministic, a given seed yields the byte-for-byte identical stream on every platform and through every language binding. The output mirrors the JSON shapes of the rest of the ecosystem, so it drops straight into backtests, screeners and RL environments.

Because the spec is data, not code, the exact same generation crosses the C ABI and WASM unchanged. The core is exposed as a JSON-over-C-ABI data API (Synth::command_json) in Rust, Python, Node.js, WASM, C, C++, C#, Go, Java and R, so a developer in any language draws the same synthetic market.

use wickra_synth_core::{generate, GenSpec};

// A spec is data: a seed, a length, and the regimes the price path walks
// through. Nothing else is random, so the same seed draws the same market
// on every platform and through every binding.
let spec = GenSpec::from_json(spec_json)?;
let out = generate(&spec)?;
println!("{} candles, {} trades", out.candles.len(), out.trades.len());

// Replaying the seed replays the bytes -- that is the whole contract.
assert_eq!(generate(&spec)?, out);

The same generation from the command line:

cargo install wickra-synth
wickra-synth --seed 42 --bars 20 --format json

Status

0.2.0 — the current release. The core, the reference CLI, the ten-language binding surface, the golden corpus and the full CI matrix are in place; the generation model and command protocol are pinned by golden tests.

Documentation

• ARCHITECTURE.md — workspace layout and the core-only-randomness design.
• GENSPEC.md — the input specification, its fields and every validation rule.
• PROTOCOL.md — the command_json boundary all ten bindings forward to.
• REGIMES.md — the trend / range / crash / vol price-path formulas.
• MICROSTRUCTURE.md — order book, trades and funding.
• DETERMINISM.md — the PRNG and the fixed draw-order contract.
• Cookbook.md — practical recipes.

Quickstart

cargo install wickra-synth
wickra-synth --seed 42 --bars 20 --format json

Twenty bars of OHLCV, an order book, trades and funding, from nothing but the number 42 — and the same twenty bars on every platform and in every one of the ten languages below. The spec that shaped them is JSON, so the same seed and spec reproduce the same market from any binding.

Use in any language

Every binding forwards the same command_json string to the Rust core, so all ten draw byte-identical synthetic markets for a given seed.

from wickra_synth import Synth
import json

synth = Synth('{"seed":42,"bars":20,"start_price":100.0,'
              '"regimes":[{"kind":"trend","len":20,"drift":0.002,"vol":0.01}],'
              '"microstructure":{"book_depth":5,"spread_bps":4.0,"trade_rate":8.0}}')
out = json.loads(synth.command('{"cmd":"generate"}'))
print(len(out["candles"]))  # 20

Runnable examples for all ten languages — each printing the same first three candles — live in examples/.

Project layout

crates/synth-core     the engine: GenSpec, the PRNG, the walk, the microstructure
crates/synth-cli      wickra-synth, the reference consumer
crates/synth-bench    criterion benchmarks
bindings/c            the C ABI hub (cdylib + staticlib) plus the C++ hull
bindings/python       PyO3 / maturin, abi3-py39
bindings/node         napi-rs, per-platform npm packages
bindings/wasm         wasm-bindgen
bindings/csharp       P/Invoke over the hub
bindings/go           cgo over the hub
bindings/java         Foreign Function & Memory API over the hub
bindings/r            .Call glue over the hub
golden/               specs + blessed outputs, the cross-language contract
examples/             one runnable example per language
fuzz/                 cargo-fuzz targets for parse, generate, PRNG and FFI
docs/                 the deep dives; see docs/README.md

Six of the ten reaches go through one C ABI (bindings/c), which is why there is exactly one place a marshalling bug can live rather than six.

Building everything from source

The core and the CLI need only cargo:

cargo build --workspace
cargo test  --workspace

The bindings each need their own toolchain, and the six that go through the C ABI need it built first:

cargo build --release -p wickra-synth-c          # the hub the six link against

cd bindings/python && maturin develop --release  # Python
cd bindings/node   && npm install && npx napi build --platform --release
cd bindings/wasm   && wasm-pack build --target nodejs
dotnet build bindings/csharp/WickraSynth -c Release
mvn -f bindings/java package
R CMD INSTALL bindings/r                         # WKSYNTH_INC/WKSYNTH_LIB, see below
cmake -S examples/c -B examples/c/build && cmake --build examples/c/build

The R binding downloads a matching prebuilt C ABI by default. To build it against the one in your tree instead, set WKSYNTH_INC to bindings/c/include and WKSYNTH_LIB to target/release.

Testing

cargo test --workspace --all-features
cargo test --workspace --no-default-features

Beyond the unit tests, four suites are worth knowing about:

• Golden — every binding replays golden/specs and must reproduce golden/expected byte for byte. That is the cross-language guarantee, and it is checked in all ten reaches, not asserted in the README.
• RNG vectors — fixed SplitMix64 and xoshiro256++ reference values. If these move, every seed in the world moves with them.
• Stream equals batch — the reassembled event stream equals the batch output, so the two paths cannot drift apart.
• Property tests — random specs stay finite and well formed, and the same seed gives the same bytes.

Per-binding commands are in CONTRIBUTING.md; the scripts/check_*.py family holds the version, licence, link and binding-surface invariants that no compiler checks.

Requirements

The core needs nothing but a Rust toolchain — no system libraries, no BLAS, no Python at build time. Each binding adds only its own runtime:

Reach	Floor	Where it is declared
Rust (workspace)	1.86	Cargo.toml, rust-version
Rust (Node binding build)	1.88	bindings/node/Cargo.toml — napi-build needs it
Python	3.9	bindings/python/pyproject.toml, requires-python (abi3)
Node.js	22	bindings/node/package.json, engines.node
.NET	8.0	bindings/csharp/WickraSynth/WickraSynth.csproj
Go	1.23	bindings/go/go.mod
Java	22	bindings/java/pom.xml — the Foreign Function & Memory API
R	4.1	bindings/r/DESCRIPTION, Depends

scripts/check_version_sync.py holds these numbers against the manifests, so a floor that moves in one place and not the other is a failing check rather than a support question.

Benchmarks

Per-generation throughput is tracked in BENCHMARKS.md and measured by the synth-bench crate (cargo bench -p synth-bench). A shallow book with light trade flow generates roughly 4.3 million candles per second; the microstructure, not the price walk, is what the time goes on.

Ecosystem

Wickra Synth is one repository in a family that shares a core and a ten-language binding surface:

• wickra — 514 streaming indicators, the core everything else is built on.
• wickra-backtest — a streaming-native backtester where backtest and live are the same code path.
• wickra-screener — scan thousands of symbols against data-driven conditions.
• wickra-exchange — one typed API over the ten largest crypto exchanges.
• wickra-terminal — a streaming trading terminal over the same core.

Synth is the one that needs no market data at all: it is where the others get a reproducible market to test against. The full list is at github.com/wickra-lib.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md and THREAT_MODEL.md. Note the PRNG is a fast non-cryptographic generator for reproducible simulation — it is not suitable for any security or cryptographic purpose.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option. Use it, fork it, modify it, redistribute it — commercially or not — file issues, send pull requests; all welcome.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Disclaimer

wickra-synth generates synthetic market data for testing, training and demonstration. It is not real market data and is not financial advice; it comes with no warranty.

---

Built on Wickra. If it saved you time, the cheapest way to say thanks is to ⭐ the repo.