feat: derivatives funding & open-interest indicators (part 1 of 3) (#126)

* feat(derivatives): DerivativesTick input type + InvalidDerivatives error

* feat(derivatives): FundingRate indicator (core)

* feat(derivatives): FundingRateMean indicator (core)

* feat(derivatives): FundingRateZScore indicator (core)

* feat(derivatives): FundingBasis indicator (core)

* feat(derivatives): OpenInterestDelta indicator (core)

* feat(derivatives): Python, Node and WASM bindings for funding & OI-delta indicators

* test(derivatives): Python and Node tests for funding & OI-delta indicators

* bench(derivatives): synthetic-tick bench + derivatives fuzz target

* docs(derivatives): README family row + counter 232->237, CHANGELOG entry

bindings/python/tests/test_input_validation.py

@@ -238,3 +238,23 @@ def test_footprint_non_positive_tick_raises():
         ta.Footprint(0.0)
     with pytest.raises(ValueError):
         ta.Footprint(-1.0)
+
+
+def test_funding_rate_mean_zero_window_raises():
+    with pytest.raises(ValueError):
+        ta.FundingRateMean(0)
+
+
+def test_funding_rate_zscore_zero_window_raises():
+    with pytest.raises(ValueError):
+        ta.FundingRateZScore(0)
+
+
+def test_funding_basis_non_positive_index_raises():
+    with pytest.raises(ValueError):
+        ta.FundingBasis().update(100.0, 0.0)
+
+
+def test_funding_rate_non_finite_raises():
+    with pytest.raises(ValueError):
+        ta.FundingRate().update(float("nan"))

bindings/python/tests/test_known_values.py

@@ -946,3 +946,36 @@ def test_kyles_lambda_recovers_constant_impact():
         mids.append(mid)
     out = ta.KylesLambda(6).batch(price, size, is_buy, mids)
     assert out[-1] == pytest.approx(0.5, abs=1e-9)
+
+
+def test_funding_rate_reference_values():
+    assert ta.FundingRate().update(0.0001) == pytest.approx(0.0001)
+    assert ta.FundingRate().update(-0.0003) == pytest.approx(-0.0003)
+
+
+def test_funding_rate_mean_reference_value():
+    frm = ta.FundingRateMean(2)
+    assert frm.update(0.001) is None  # warming up
+    # Window [0.001, 0.003] -> mean 0.002.
+    assert frm.update(0.003) == pytest.approx(0.002)
+
+
+def test_funding_rate_zscore_reference_value():
+    z = ta.FundingRateZScore(2)
+    assert z.update(0.001) is None  # warming up
+    # Window [0.001, 0.003]: mean 0.002, population stddev 0.001 -> +1.
+    assert z.update(0.003) == pytest.approx(1.0, abs=1e-9)
+
+
+def test_funding_basis_reference_value():
+    # mark 100.5 vs index 100.0 -> (100.5 - 100.0) / 100.0 = 0.005.
+    assert ta.FundingBasis().update(100.5, 100.0) == pytest.approx(0.005)
+    # A discount reads negative.
+    assert ta.FundingBasis().update(99.5, 100.0) == pytest.approx(-0.005)
+
+
+def test_open_interest_delta_reference_value():
+    oid = ta.OpenInterestDelta()
+    assert oid.update(1000.0) is None  # seeds the previous OI
+    assert oid.update(1250.0) == pytest.approx(250.0)
+    assert oid.update(1100.0) == pytest.approx(-150.0)

bindings/python/tests/test_new_indicators.py

@@ -1952,3 +1952,45 @@ def test_footprint_streaming_equals_batch():
     for i in range(n):
         streamed = streamer.update(price[i], size[i], is_buy[i])
         assert np.array_equal(streamed, batch[i])
+
+
+def test_funding_indicators_streaming_equals_batch():
+    n = 40
+    rate = np.array([0.0001 * math.sin(i * 0.3) for i in range(n)], dtype=np.float64)
+    for make in (
+        ta.FundingRate,
+        lambda: ta.FundingRateMean(5),
+        lambda: ta.FundingRateZScore(5),
+    ):
+        batch = make().batch(rate)
+        streamer = make()
+        streamed = np.array(
+            [streamer.update(rate[i]) for i in range(n)], dtype=np.float64
+        )
+        assert batch.shape == (n,)
+        assert _eq_nan(batch, streamed)
+
+
+def test_funding_basis_streaming_equals_batch():
+    n = 40
+    index = np.array([100.0 + 0.5 * math.sin(i * 0.2) for i in range(n)], dtype=np.float64)
+    mark = np.array(
+        [index[i] + 0.1 * math.cos(i * 0.3) for i in range(n)], dtype=np.float64
+    )
+    batch = ta.FundingBasis().batch(mark, index)
+    streamer = ta.FundingBasis()
+    streamed = np.array(
+        [streamer.update(mark[i], index[i]) for i in range(n)], dtype=np.float64
+    )
+    assert batch.shape == (n,)
+    assert _eq_nan(batch, streamed)
+
+
+def test_open_interest_delta_streaming_equals_batch():
+    n = 40
+    oi = np.array([1000.0 + 50.0 * math.sin(i * 0.25) for i in range(n)], dtype=np.float64)
+    batch = ta.OpenInterestDelta().batch(oi)
+    streamer = ta.OpenInterestDelta()
+    streamed = np.array([streamer.update(oi[i]) for i in range(n)], dtype=np.float64)
+    assert batch.shape == (n,)
+    assert _eq_nan(batch, streamed)