fuzz against verystable

Author: jamesob

.github/workflows/tests.yml

@@ -41,6 +41,10 @@ jobs:
           sudo make install
         fi
 
+    - name: Run C tests
+      run: |
+        make test
+
     - name: Run Python tests
       run: |
         cd examples/py

README.md

@@ -3,7 +3,8 @@
 A fast, secure, low-dependency implementation of BIP32
 
 - Depends only on [`libsecp256k1`](https://github.com/bitcoin-core/libsecp256k1) and
-  [`libsodium`](https://github.com/jedisct1/libsodium)
+  [`libsodium`](https://github.com/jedisct1/libsodium) (for SHA256, HMAC-SHA512, and
+  context randomization)
 - No heap allocations (aside from secp context), which allows end users to manage memory securely
 - Implemented in pure C for ease of FFI
 - Extensively tested
@@ -31,17 +32,36 @@ git clone https://github.com/jamesob/cbip32.git && \
   make && sudo make install
 ```
 
+## Performance
+
+The Python bindings for this implementation have been shown to be
+- *~2x* faster than `python-bip32`, an implementation based on `coincurve` which itself
+  wraps libsecp256k1, and
+- *>100x* faster than `verystable`, which is a "dumb" pure Python implementation.
+
+From fuzzing:
+```
+  - Highest target scores [time per derivation]:
+     0.0162932  (label='ours')
+     0.0379755  (label='python-bip32')
+
+  - Highest target scores [time per derivation]:
+     0.00222896  (label='ours')
+     0.315636    (label='verystable')
+```
+
+
 ## Example bindings included
 
-### [Python](./examples/py)
+### Python [(`./examples/py`)](./examples/py)
 
 ```python
 >>> from bindings import derive
 >>> derive('0' * 32, 'm/1/2h').get_public().serialize()
 'xpub69s9RVsS4kfK2VFed2giqFm9gQ4VmCWuWcPHFJ51Rj6dHvBjCicCZm2HR88Z6J5zRYyHkt7W9LPygBc57RCCPp2t1AxCNa1VtvSq4qWYLqK'
 ```
 
-### [Go](./examples/go)
+### Go [(`./examples/go`)](./examples/go)
 
 ```go
 package cbip32

examples/py/test_fuzz_cross_impl.py

@@ -4,16 +4,20 @@
 #     "bip32",
 #     "hypothesis",
 #     "pytest",
+#     "verystable",
 # ]
 # ///
+import sys
 import random
 import logging
 import time
 from contextlib import contextmanager
 
+import bip32 as py_bip32
+from verystable import bip32 as vs_bip32
+
 import pytest
 from hypothesis import given, strategies as st, target, settings
-from bip32 import BIP32
 
 from bindings import derive
 
@@ -32,16 +36,48 @@ def timer(label):
    target(time.perf_counter() - start, label=label)
 
 
-def their_derive(seed_hex_str: str, bip32_path: str) -> str:
-    bip32 = BIP32.from_seed(bytes.fromhex(seed_hex_str))
+def py_derive(seed_hex_str: str, bip32_path: str) -> str:
+    bip32 = py_bip32.BIP32.from_seed(bytes.fromhex(seed_hex_str))
     try:
         return bip32.get_xpriv_from_path(bip32_path)
     except Exception:
         return INVALID_KEY
 
 
-def their_xpub_derive(base58: str, bip32_path: str) -> str:
-    bip32 = BIP32.from_xpub(base58)
+def _path_str_to_ints(bip32_path) -> list[int] | None:
+    if not bip32_path.startswith('m'):
+        return None
+
+    path_ints = []
+    components = filter(None, bip32_path.lstrip('m').split('/'))
+
+    for comp in components:
+        if comp.endswith('h'):
+            path_ints.append(int(comp[:-1]) | vs_bip32.HARDENED_INDEX)
+        else:
+            path_ints.append(int(comp))
+
+    return path_ints
+
+
+def verystable_derive(seed_hex_str: str, bip32_path: str) -> str:
+    bip32 = vs_bip32.BIP32.from_bytes(bytes.fromhex(seed_hex_str), True)
+    path_ints = _path_str_to_ints(bip32_path)
+
+    if path_ints is None:
+        return INVALID_KEY
+    elif not path_ints:
+        return bip32.serialize()
+
+    try:
+        derived, _ = bip32.derive(*path_ints)
+        return derived.serialize()
+    except Exception:
+        return INVALID_KEY
+
+
+def py_xpub_derive(base58: str, bip32_path: str) -> str:
+    bip32 = py_bip32.BIP32.from_xpub(base58)
     try:
         return bip32.get_xpub_from_path(bip32_path)
     except Exception:
@@ -56,38 +92,78 @@ def our_derive(hex_str, path) -> str:
         return INVALID_KEY
 
 
+@st.composite
+def py_compatible_bip32_paths(draw):
+    """
+    Given python-bip32's too-large path issue, clamp the max_values that we can fuzz:
+      https://github.com/darosior/python-bip32/issues/46
+    """
+    MAX_ALLOWED_DEPTH = 255
+    MAX_UNHARDENED_IDX = 2**31 - 1
+
+    depth = draw(st.integers(min_value=0, max_value=(MAX_ALLOWED_DEPTH + 3)))
+    path_parts = ["m"]
+    for _ in range(depth):
+        index = draw(st.integers(min_value=-2, max_value=MAX_UNHARDENED_IDX))
+        hardened = draw(st.booleans())
+        path_parts.append(f"{index}{"h" if hardened else ''}")
+    return "/".join(path_parts)
+
+
 @st.composite
 def bip32_paths(draw):
-    depth = draw(st.integers(min_value=0, max_value=255))
+    """
+    Generate BIP32 paths with some out of bound values.
+    """
+    MAX_ALLOWED_DEPTH = 255
+    MAX_UNHARDENED_IDX = 2**31 - 1
+
+    depth = draw(st.integers(min_value=0, max_value=(MAX_ALLOWED_DEPTH + 3)))
     path_parts = ["m"]
     for _ in range(depth):
-        index = draw(st.integers(min_value=0, max_value=(2**31 - 1)))
+        index = draw(st.integers(min_value=-2, max_value=(MAX_UNHARDENED_IDX + 2)))
         hardened = draw(st.booleans())
         path_parts.append(f"{index}{"h" if hardened else ''}")
     return "/".join(path_parts)
 
 
-@given(seed_hex_str=valid_seeds, bip32_path=bip32_paths())
+@given(seed_hex_str=valid_seeds, bip32_path=py_compatible_bip32_paths())
 @settings(max_examples=2_000)
-def test_impls(seed_hex_str, bip32_path):
+def test_versus_py(seed_hex_str, bip32_path):
+    """Compare implementations of BIP32 on a random seed and path."""
     with timer('ours'):
         ours = our_derive(seed_hex_str, bip32_path)
     with timer('python-bip32'):
-        theirs = their_derive(seed_hex_str, bip32_path)
-    assert ours == theirs
+        pys = py_derive(seed_hex_str, bip32_path)
+
+    assert ours == pys
+
+
+@given(seed_hex_str=valid_seeds, bip32_path=py_compatible_bip32_paths())
+@settings(max_examples=100, deadline=5000)  # verstable is slooooww, so allow 5s tests
+def test_versus_vs(seed_hex_str, bip32_path):
+    """
+    Since the verystable implemention is VERY slow (100x+), limit the number of cases.
+    """
+    with timer('ours'):
+        ours = our_derive(seed_hex_str, bip32_path)
+    with timer('verystable'):
+        vs = verystable_derive(seed_hex_str, bip32_path)
+
+    assert ours == vs
 
 
-@given(bip32_path=bip32_paths())
+@given(bip32_path=py_compatible_bip32_paths())
 @settings(max_examples=200)
 def test_xpub_impls(bip32_path):
     xpub = 'xpub6ASuArnXKPbfEwhqN6e3mwBcDTgzisQN1wXN9BJcM47sSikHjJf3UFHKkNAWbWMiGj7Wf5uMash7SyYq527Hqck2AxYysAA7xmALppuCkwQ'
 
     with timer('ours'):
         ours = our_derive(xpub, bip32_path)
     with timer('python-bip32'):
-        theirs = their_xpub_derive(xpub, bip32_path)
-    assert ours == theirs
+        pys = py_xpub_derive(xpub, bip32_path)
+    assert ours == pys
 
 
 if __name__ == "__main__":
-    pytest.main([__file__, "-v", "--capture=no", "--hypothesis-show-statistics"])
+    pytest.main([__file__, "-v", "--capture=no", "--hypothesis-show-statistics", "-x"] + sys.argv[1:])