foxmath 0.6.0__tar.gz → 0.6.2__tar.gz

{foxmath-0.6.0/src/foxmath.egg-info → foxmath-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foxmath
-Version: 0.6.0
+Version: 0.6.2
 Summary: Minimalist CLI for math & cryptography exploration 🦊
 Author-email: Abhrankan Chakrabarti <abhrankan@gmail.com>
 License: MIT
@@ -21,6 +21,8 @@ Dynamic: license-file
 
 **Minimalist CLI for math & cryptography exploration.**
 
+**More about me / other projects:** [abhrankan.netlify.app](https://abhrankan.netlify.app)
+
 One binary. Clean output. Zero footguns. Educational by design.
 
 Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
@@ -30,12 +32,14 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 - Euler/Hermann Machin-like π approximation
 - Elliptic curve point addition (over finite fields), including
   named curves (secp256k1) with on-curve result validation
+- Elliptic curve scalar multiplication k·P (double-and-add), including
+  the point at infinity as a first-class result
 - Chinese Remainder Theorem solver (handles non-coprime moduli)
 - Continued fraction expansion and convergents
 - Challenge/quiz mode — practice problems with scoring, or a
   worksheet mode for self-study
 - Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
-  foxmath-crt, foxmath-cf, foxmath-challenge)
+  foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
 
 ## Installation
@@ -51,6 +55,14 @@ cd foxmath
 pip install -e .
 ```
 
+Check which version you have installed:
+```bash
+foxmath --version
+```
+```
+foxmath 0.6.2
+```
+
 ## Usage Examples
 
 ```bash
@@ -84,6 +96,25 @@ Result point: (89565891926547004231252920425935692360644145829622209833684329913
   ✓ on curve
 ```
 
+```bash
+# Scalar multiplication — same curves, O(log k) double-and-add
+foxmath ecmul --curve toy193 --k 7
+```
+```
+Result point: (66, 24)
+  ✓ on curve
+```
+
+```bash
+# toy193: y² = x³ + x + 5 (mod 193), #E = 193 (prime) — small enough to
+# hand-verify, structured exactly like secp256k1. G = (1, 59).
+# k = 0 or a multiple of the group order lands on the identity:
+foxmath ecmul --curve toy193 --k 193
+```
+```
+Result: point at infinity (identity)
+```
+
 ```bash
 # Chinese Remainder Theorem
 foxmath crt --r 2 3 2 --m 3 5 7
@@ -114,8 +145,18 @@ foxmath challenge --topic legendre --count 2 --seed 1 --reveal
    Answer: -1
 ```
 
+```bash
+# Baby-size discrete log: given G and Q = k·G, recover k.
+# Easy at this scale — the same problem at secp256k1's ~10^77 is why ECDSA works.
+foxmath challenge --topic ecdlp --count 1 --seed 9 --reveal
+```
+```
+1. On y² = x³ + 1x + 5 (mod 193) with G = (1, 59): find k (2 ≤ k ≤ 20) such that k·G = (60, 171)
+   Answer: 16
+```
+
 Drop `--reveal` to answer interactively instead, with scoring at the end.
-`--topic` accepts `legendre`, `crt`, or `mixed` (default).
+`--topic` accepts `legendre`, `crt`, `ecdlp`, or `mixed` (default).
 
 ```bash
 # JSON output

{foxmath-0.6.0 → foxmath-0.6.2}/README.md

@@ -2,6 +2,8 @@
 
 **Minimalist CLI for math & cryptography exploration.**
 
+**More about me / other projects:** [abhrankan.netlify.app](https://abhrankan.netlify.app)
+
 One binary. Clean output. Zero footguns. Educational by design.
 
 Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
@@ -11,12 +13,14 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 - Euler/Hermann Machin-like π approximation
 - Elliptic curve point addition (over finite fields), including
   named curves (secp256k1) with on-curve result validation
+- Elliptic curve scalar multiplication k·P (double-and-add), including
+  the point at infinity as a first-class result
 - Chinese Remainder Theorem solver (handles non-coprime moduli)
 - Continued fraction expansion and convergents
 - Challenge/quiz mode — practice problems with scoring, or a
   worksheet mode for self-study
 - Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
-  foxmath-crt, foxmath-cf, foxmath-challenge)
+  foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
 
 ## Installation
@@ -32,6 +36,14 @@ cd foxmath
 pip install -e .
 ```
 
+Check which version you have installed:
+```bash
+foxmath --version
+```
+```
+foxmath 0.6.2
+```
+
 ## Usage Examples
 
 ```bash
@@ -65,6 +77,25 @@ Result point: (89565891926547004231252920425935692360644145829622209833684329913
   ✓ on curve
 ```
 
+```bash
+# Scalar multiplication — same curves, O(log k) double-and-add
+foxmath ecmul --curve toy193 --k 7
+```
+```
+Result point: (66, 24)
+  ✓ on curve
+```
+
+```bash
+# toy193: y² = x³ + x + 5 (mod 193), #E = 193 (prime) — small enough to
+# hand-verify, structured exactly like secp256k1. G = (1, 59).
+# k = 0 or a multiple of the group order lands on the identity:
+foxmath ecmul --curve toy193 --k 193
+```
+```
+Result: point at infinity (identity)
+```
+
 ```bash
 # Chinese Remainder Theorem
 foxmath crt --r 2 3 2 --m 3 5 7
@@ -95,8 +126,18 @@ foxmath challenge --topic legendre --count 2 --seed 1 --reveal
    Answer: -1
 ```
 
+```bash
+# Baby-size discrete log: given G and Q = k·G, recover k.
+# Easy at this scale — the same problem at secp256k1's ~10^77 is why ECDSA works.
+foxmath challenge --topic ecdlp --count 1 --seed 9 --reveal
+```
+```
+1. On y² = x³ + 1x + 5 (mod 193) with G = (1, 59): find k (2 ≤ k ≤ 20) such that k·G = (60, 171)
+   Answer: 16
+```
+
 Drop `--reveal` to answer interactively instead, with scoring at the end.
-`--topic` accepts `legendre`, `crt`, or `mixed` (default).
+`--topic` accepts `legendre`, `crt`, `ecdlp`, or `mixed` (default).
 
 ```bash
 # JSON output

{foxmath-0.6.0 → foxmath-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "foxmath"
-version = "0.6.0"
+version = "0.6.2"
 description = "Minimalist CLI for math & cryptography exploration 🦊"
 readme = "README.md"
 license = {text = "MIT"}

{foxmath-0.6.0 → foxmath-0.6.2/src/foxmath.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: foxmath
-Version: 0.6.0
+Version: 0.6.2
 Summary: Minimalist CLI for math & cryptography exploration 🦊
 Author-email: Abhrankan Chakrabarti <abhrankan@gmail.com>
 License: MIT
@@ -21,6 +21,8 @@ Dynamic: license-file
 
 **Minimalist CLI for math & cryptography exploration.**
 
+**More about me / other projects:** [abhrankan.netlify.app](https://abhrankan.netlify.app)
+
 One binary. Clean output. Zero footguns. Educational by design.
 
 Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
@@ -30,12 +32,14 @@ Built with curiosity — for students, tinkerers, and crypto/math enthusiasts.
 - Euler/Hermann Machin-like π approximation
 - Elliptic curve point addition (over finite fields), including
   named curves (secp256k1) with on-curve result validation
+- Elliptic curve scalar multiplication k·P (double-and-add), including
+  the point at infinity as a first-class result
 - Chinese Remainder Theorem solver (handles non-coprime moduli)
 - Continued fraction expansion and convergents
 - Challenge/quiz mode — practice problems with scoring, or a
   worksheet mode for self-study
 - Symlink-friendly (foxmath-legendre, foxmath-pi, foxmath-ecadd,
-  foxmath-crt, foxmath-cf, foxmath-challenge)
+  foxmath-ecmul, foxmath-crt, foxmath-cf, foxmath-challenge)
 - JSON output mode
 
 ## Installation
@@ -51,6 +55,14 @@ cd foxmath
 pip install -e .
 ```
 
+Check which version you have installed:
+```bash
+foxmath --version
+```
+```
+foxmath 0.6.2
+```
+
 ## Usage Examples
 
 ```bash
@@ -84,6 +96,25 @@ Result point: (89565891926547004231252920425935692360644145829622209833684329913
   ✓ on curve
 ```
 
+```bash
+# Scalar multiplication — same curves, O(log k) double-and-add
+foxmath ecmul --curve toy193 --k 7
+```
+```
+Result point: (66, 24)
+  ✓ on curve
+```
+
+```bash
+# toy193: y² = x³ + x + 5 (mod 193), #E = 193 (prime) — small enough to
+# hand-verify, structured exactly like secp256k1. G = (1, 59).
+# k = 0 or a multiple of the group order lands on the identity:
+foxmath ecmul --curve toy193 --k 193
+```
+```
+Result: point at infinity (identity)
+```
+
 ```bash
 # Chinese Remainder Theorem
 foxmath crt --r 2 3 2 --m 3 5 7
@@ -114,8 +145,18 @@ foxmath challenge --topic legendre --count 2 --seed 1 --reveal
    Answer: -1
 ```
 
+```bash
+# Baby-size discrete log: given G and Q = k·G, recover k.
+# Easy at this scale — the same problem at secp256k1's ~10^77 is why ECDSA works.
+foxmath challenge --topic ecdlp --count 1 --seed 9 --reveal
+```
+```
+1. On y² = x³ + 1x + 5 (mod 193) with G = (1, 59): find k (2 ≤ k ≤ 20) such that k·G = (60, 171)
+   Answer: 16
+```
+
 Drop `--reveal` to answer interactively instead, with scoring at the end.
-`--topic` accepts `legendre`, `crt`, or `mixed` (default).
+`--topic` accepts `legendre`, `crt`, `ecdlp`, or `mixed` (default).
 
 ```bash
 # JSON output

{foxmath-0.6.0 → foxmath-0.6.2}/tests/test_cli.py

@@ -98,6 +98,12 @@ class TestSymlinkInvocation(unittest.TestCase):
         self.assertEqual(code, 0)
         self.assertIn("Answer:", out)
 
+    def test_ecmul_symlink(self):
+        script = self._make_symlink_script("foxmath-ecmul")
+        code, out, err = run("--curve", "toy193", "--k", "7", script=script)
+        self.assertEqual(code, 0)
+        self.assertIn("Result point: (66, 24)", out)
+
     def test_symlink_with_json(self):
         script = self._make_symlink_script("foxmath-legendre")
         code, out, err = run("2", "7", "--json", script=script)
@@ -140,6 +146,58 @@ class TestNormalUsage(unittest.TestCase):
         self.assertEqual(code, 0)
         self.assertIn("Result point: (14, 2)", out)
 
+    def test_ecmul_readme_example_toy193(self):
+        # Exact usage/output shown in the README.
+        code, out, err = run("ecmul", "--curve", "toy193", "--k", "7")
+        self.assertEqual(code, 0)
+        self.assertIn("Result point: (66, 24)", out)
+        self.assertIn("on curve", out)
+
+    def test_ecmul_readme_example_identity(self):
+        code, out, err = run("ecmul", "--curve", "toy193", "--k", "193")
+        self.assertEqual(code, 0)
+        self.assertIn("point at infinity", out)
+
+    def test_ecmul_secp256k1_matches_known_doubling(self):
+        code, out, err = run("ecmul", "--curve", "secp256k1", "--k", "2")
+        self.assertEqual(code, 0)
+        self.assertIn("89565891926547004231252920425935692360644145829622209833684329913297188986597", out)
+
+    def test_ecmul_json_output(self):
+        code, out, err = run("ecmul", "--curve", "toy193", "--k", "7", "--json")
+        self.assertEqual(code, 0)
+        import json
+        parsed = json.loads(out)
+        self.assertEqual(parsed["result"], [66, 24])
+        self.assertTrue(parsed["result_on_curve"])
+
+    def test_ecmul_json_output_infinity(self):
+        code, out, err = run("ecmul", "--curve", "toy193", "--k", "193", "--json")
+        self.assertEqual(code, 0)
+        import json
+        parsed = json.loads(out)
+        self.assertEqual(parsed["result"], "infinity")
+
+    def test_ecmul_manual_mode_no_curve(self):
+        code, out, err = run("ecmul", "--p", "97", "--x", "3", "--y", "6",
+                              "--a", "2", "--k", "3")
+        self.assertEqual(code, 0)
+        self.assertIn("Result point:", out)
+
+    def test_ecmul_a_override(self):
+        code, out, err = run("ecmul", "--curve", "toy97", "--a", "2", "--k", "3")
+        self.assertEqual(code, 0)
+
+    def test_ecmul_missing_curve_and_incomplete_manual_args_errors(self):
+        code, out, err = run("ecmul", "--k", "5")
+        self.assertEqual(code, 1)
+        self.assertIn("Error", err)
+
+    def test_ecmul_negative_k_errors(self):
+        code, out, err = run("ecmul", "--curve", "toy193", "--k", "-5")
+        self.assertEqual(code, 1)
+        self.assertIn("Error", err)
+
     def test_crt(self):
         code, out, err = run("crt", "--r", "2", "3", "2", "--m", "3", "5", "7")
         self.assertEqual(code, 0)

{foxmath-0.6.0 → foxmath-0.6.2}/tests/test_foxmath.py

@@ -13,7 +13,7 @@ from decimal import Decimal
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..", "src")))
 
 from foxmath.foxmath import (
-    legendre_symbol, euler_hermann_pi_approx, ec_point_add, crt_solve,
+    legendre_symbol, euler_hermann_pi_approx, ec_point_add, ec_mul, crt_solve,
     continued_fraction, cf_convergents, CURVES, is_on_curve,
     generate_problem,
 )
@@ -154,6 +154,103 @@ class TestContinuedFractions(unittest.TestCase):
             self.assertEqual(convs[-1], (expected.numerator, expected.denominator))
 
 
+class TestECMul(unittest.TestCase):
+    """
+    ec_mul (scalar multiplication / double-and-add) had no test coverage
+    at all despite being a documented headline feature -- these tests
+    were added after finding and closing that gap, not in response to
+    any bug (cross-validation below found none).
+    """
+
+    def _naive_mul(self, k, x, y, a, p):
+        # Independent reference: k repeated additions via the
+        # user-facing ec_point_add, rather than ec_mul's own
+        # double-and-add logic.
+        if k == 0:
+            return None
+        result = None
+        point = (x, y)
+        for _ in range(k):
+            if result is None:
+                result = point
+            else:
+                try:
+                    result = ec_point_add(result[0], result[1], point[0], point[1], a, p)
+                except ValueError:
+                    result = None  # hit the point at infinity
+        return result
+
+    def test_matches_naive_repeated_addition_toy97(self):
+        c = CURVES["toy97"]
+        for k in [1, 2, 3, 5, 7, 10, 13, 20]:
+            fast = ec_mul(k, c["gx"], c["gy"], c["a"], c["p"])
+            naive = self._naive_mul(k, c["gx"], c["gy"], c["a"], c["p"])
+            self.assertEqual(fast, naive, f"mismatch at k={k}")
+
+    def test_matches_naive_repeated_addition_toy193(self):
+        c = CURVES["toy193"]
+        for k in [1, 2, 3, 5, 7, 10, 13, 20]:
+            fast = ec_mul(k, c["gx"], c["gy"], c["a"], c["p"])
+            naive = self._naive_mul(k, c["gx"], c["gy"], c["a"], c["p"])
+            self.assertEqual(fast, naive, f"mismatch at k={k}")
+
+    def test_secp256k1_matches_independent_reference_including_large_k(self):
+        # Reference points cross-checked independently against the
+        # `ecdsa` library's SECP256k1.generator * k (same verification
+        # approach the pre-existing doubling test above uses). Values
+        # are baked in rather than imported at test time so this suite
+        # doesn't pick up a runtime dependency on `ecdsa` -- foxmath
+        # itself stays pure stdlib (dependencies = [] in pyproject.toml).
+        c = CURVES["secp256k1"]
+        reference = {
+            1: (55066263022277343669578718895168534326250603453777594175500187360389116729240,
+                32670510020758816978083085130507043184471273380659243275938904335757337482424),
+            2: (89565891926547004231252920425935692360644145829622209833684329913297188986597,
+                12158399299693830322967808612713398636155367887041628176798871954788371653930),
+            3: (112711660439710606056748659173929673102114977341539408544630613555209775888121,
+                25583027980570883691656905877401976406448868254816295069919888960541586679410),
+            7: (41948375291644419605210209193538855353224492619856392092318293986323063962044,
+                48361766907851246668144012348516735800090617714386977531302791340517493990618),
+            100: (107303582290733097924842193972465022053148211775194373671539518313500194639752,
+                  103795966108782717446806684023742168462365449272639790795591544606836007446638),
+            12345: (108607064596551879580190606910245687803607295064141551927605737287325610911759,
+                    6661302038839728943522144359728938428925407345457796456954441906546235843221),
+            # A scalar well beyond anything repeated addition could feasibly verify.
+            2**64 + 17: (5136902638900309784563324385263118307222550852398366895311091889317425008288,
+                         19220983661714808463696268177333916812952649794945216772534518833957341771155),
+        }
+        for k, expected in reference.items():
+            fast = ec_mul(k, c["gx"], c["gy"], c["a"], c["p"])
+            self.assertEqual(fast, expected, f"mismatch at k={k}")
+
+    def test_toy193_has_prime_order_full_cycle(self):
+        # README's documented claim: #E = 193 (prime), so every non-zero
+        # multiple up to 192 should land on a distinct on-curve point,
+        # and k=193 (the order) should land on infinity.
+        c = CURVES["toy193"]
+        seen = set()
+        for k in range(1, 193):
+            pt = ec_mul(k, c["gx"], c["gy"], c["a"], c["p"])
+            self.assertIsNotNone(pt, f"unexpected infinity at k={k}")
+            self.assertTrue(is_on_curve(pt[0], pt[1], c["a"], c["b"], c["p"]))
+            self.assertNotIn(pt, seen, f"duplicate point at k={k} -- order is not 193")
+            seen.add(pt)
+        self.assertEqual(len(seen), 192)
+
+    def test_k_zero_is_infinity(self):
+        c = CURVES["toy193"]
+        self.assertIsNone(ec_mul(0, c["gx"], c["gy"], c["a"], c["p"]))
+
+    def test_k_equal_to_order_is_infinity(self):
+        c = CURVES["toy193"]
+        self.assertIsNone(ec_mul(193, c["gx"], c["gy"], c["a"], c["p"]))
+
+    def test_negative_k_raises(self):
+        c = CURVES["toy193"]
+        with self.assertRaises(ValueError):
+            ec_mul(-5, c["gx"], c["gy"], c["a"], c["p"])
+
+
 class TestNamedCurves(unittest.TestCase):
     def test_secp256k1_generator_is_on_curve(self):
         c = CURVES["secp256k1"]
@@ -193,10 +290,13 @@ class TestChallengeGenerators(unittest.TestCase):
             self.assertEqual(prob["topic"], "crt")
             self.assertIsInstance(prob["answer"], int)
 
-    def test_mixed_topic_produces_both_kinds(self):
+    def test_mixed_topic_produces_all_kinds(self):
+        # mixed draws from every registered generator -- legendre, crt,
+        # and ecdlp (this assertion was stale: it predated ecdlp being
+        # added to _TOPIC_GENERATORS, and only checked for {legendre, crt}).
         rng = random.Random(1)
         topics = {generate_problem("mixed", rng)["topic"] for _ in range(30)}
-        self.assertEqual(topics, {"legendre", "crt"})
+        self.assertEqual(topics, {"legendre", "crt", "ecdlp"})
 
     def test_reproducible_with_same_seed(self):
         p1 = generate_problem("legendre", random.Random(99))