functionalscript 0.2.1 → 0.2.3

package/secp/module.f.mjs

@@ -5,11 +5,22 @@ import * as bi from '../types/bigint/module.f.mjs'
 const { scalar_mul } = bi
 const { prime_field, sqrt } = pf
 
-/** @typedef {readonly[bigint, bigint]} Point2D */
+/**
+ * A 2D point represented as a pair of `bigint` values `[x, y]`.
+ *
+ * @typedef {readonly[bigint, bigint]} Point2D
+ */
 
-/** @typedef {Point2D|null} Point */
+/**
+ * A 2D point on an elliptic curve, represented as a pair of `bigint` values.
+ * `null` represents the point at infinity (`O`).
+ *
+ * @typedef {Point2D|null} Point
+ */
 
 /**
+ * Initialization parameters for an elliptic curve.
+ *
  * @typedef {{
  *  readonly p: bigint
  *  readonly a: readonly[bigint, bigint]
@@ -19,6 +30,8 @@ const { prime_field, sqrt } = pf
  */
 
 /**
+ * Represents an elliptic curve and its associated operations.
+ *
  * @typedef {{
  *  readonly pf: pf.PrimeField
  *  readonly nf: pf.PrimeField
@@ -30,7 +43,28 @@ const { prime_field, sqrt } = pf
  * }} Curve
  */
 
-/** @type {(i: Init) => Curve} */
+/**
+ * Constructs an elliptic curve with the given initialization parameters.
+ *
+ * @example
+ *
+ * ```js
+ * const curveParams = {
+ *     p: 23n,
+ *     a: [0n, 1n],
+ *     g: [1n, 1n],
+ *     n: 19n
+ * };
+ * const curveInstance = curve(curveParams);
+ *
+ * // Access curve operations
+ * const point = curveInstance.add([1n, 1n])([2n, 5n]); // Add two points
+ * const negPoint = curveInstance.neg([1n, 1n]); // Negate a point
+ * const mulPoint = curveInstance.mul([1n, 1n])(3n); // Multiply a point by 3
+ * ```
+ *
+ * @type {(i: Init) => Curve}
+ */
 export const curve = ({ p, a: [a0, a1], n }) => {
     const pf = prime_field(p)
     const { pow2, pow3, sub, add, mul, neg, div } = pf
@@ -95,7 +129,30 @@ export const eq = a => b => {
     return ax === bx && ay === by
 }
 
-/** @type {Init} */
+/**
+ * https://neuromancer.sk/std/secg/secp192r1
+ *
+ * @type {Init}
+ */
+export const secp192r1 = {
+    p: 0xffffffff_ffffffff_ffffffff_fffffffe_ffffffff_ffffffffn,
+    a: [
+        0x64210519_e59c80e7_0fa7e9ab_72243049_feb8deec_c146b9b1n,
+        0xffffffff_ffffffff_ffffffff_fffffffe_ffffffff_fffffffcn
+    ],
+    g: [
+        0x188da80e_b03090f6_7cbf20eb_43a18800_f4ff0afd_82ff1012n,
+        0x07192b95_ffc8da78_631011ed_6b24cdd5_73f977a1_1e794811n
+    ],
+    n: 0xffffffff_ffffffff_ffffffff_99def836_146bc9b1_b4d22831n,
+}
+
+/**
+ * https://en.bitcoin.it/wiki/Secp256k1
+ * https://neuromancer.sk/std/secg/secp256k1
+ *
+ * @type {Init}
+ */
 export const secp256k1 = {
     p: 0xffffffff_ffffffff_ffffffff_ffffffff_ffffffff_ffffffff_fffffffe_fffffc2fn,
     a: [7n, 0n],
@@ -106,16 +163,20 @@ export const secp256k1 = {
     n: 0xffffffff_ffffffff_ffffffff_fffffffe_baaedce6_af48a03b_bfd25e8c_d0364141n,
 }
 
-/** @type {Init} */
-export const secp192r1 = {
-    p: 0xffffffff_ffffffff_ffffffff_fffffffe_ffffffff_ffffffffn,
+/**
+ * https://neuromancer.sk/std/secg/secp256r1
+ *
+ * @type { Init }
+ */
+export const secp256r1 ={
+    p: 0xffffffff_00000001_00000000_00000000_00000000_ffffffff_ffffffff_ffffffffn,
     a: [
-        0x64210519_e59c80e7_0fa7e9ab_72243049_feb8deec_c146b9b1n,
-        0xffffffff_ffffffff_ffffffff_fffffffe_ffffffff_fffffffcn
+        0x5ac635d8_aa3a93e7_b3ebbd55_769886bc_651d06b0_cc53b0f6_3bce3c3e_27d2604bn, //< b
+        0xffffffff_00000001_00000000_00000000_00000000_ffffffff_ffffffff_fffffffcn, //< a
     ],
     g: [
-        0x188da80e_b03090f6_7cbf20eb_43a18800_f4ff0afd_82ff1012n,
-        0x07192b95_ffc8da78_631011ed_6b24cdd5_73f977a1_1e794811n
+        0x6b17d1f2_e12c4247_f8bce6e5_63a440f2_77037d81_2deb33a0_f4a13945_d898c296n, //< x
+        0x4fe342e2_fe1a7f9b_8ee7eb4a_7c0f9e16_2bce3357_6b315ece_cbb64068_37bf51f5n, //< y
     ],
-    n: 0xffffffff_ffffffff_ffffffff_99def836_146bc9b1_b4d22831n,
+    n: 0xffffffff_00000000_ffffffff_ffffffff_bce6faad_a7179e84_f3b9cac2_fc632551n,
 }

package/secp/test.f.mjs

@@ -1,7 +1,21 @@
 import * as _ from './module.f.mjs'
-const { curve, secp256k1, secp192r1, eq } = _
+const { curve, secp256k1, secp192r1, secp256r1, eq } = _
 
 export default {
+    example: () => {
+        /** @type {_.Init} */
+        const curveParams = {
+            p: 23n,
+            a: [0n, 1n],
+            g: [1n, 1n],
+            n: 19n
+        }
+        const c = curve(curveParams)
+        // Access curve operations
+        const point = c.add([1n, 1n])([2n, 5n]); // Add two points
+        const negPoint = c.neg([1n, 1n]); // Negate a point
+        const mulPoint = c.mul([1n, 1n])(3n); // Multiply a point by 3
+    },
     test: () => {
         /** @type {(c: _.Init) => void} */
         const test_curve = c => {
@@ -9,10 +23,10 @@ export default {
             const { mul, neg, pf: { abs }, y: yf, nf: { p: n } } = curve(c)
             /** @type {(p: _.Point) => void} */
             const point_check = p => {
-                if (p === null) { throw 'null' }
+                if (p === null) { throw 'p === null' }
                 const [x, y] = p
                 const ye = yf(x)
-                if (ye === null) { throw 'null' }
+                if (ye === null) { throw 'ye === null' }
                 if (abs(ye) !== abs(y)) { throw 'ye' }
             }
             point_check(g)
@@ -44,5 +58,6 @@ export default {
         }
         test_curve(secp256k1)
         test_curve(secp192r1)
+        test_curve(secp256r1)
     }
 }

package/types/bigint/test.f.mjs

@@ -77,6 +77,11 @@ export default {
             const result = log2(1n << v)
             if (result !== v) { throw result }
         },
+        () => {
+            const v = 0x18945n
+            const result = log2(v)
+            if (result !== 16n) { throw result }
+        }
     ],
     toString2: () => {
         // max for Bun (131_072 Bytes)

package/types/bit_vec/module.f.mjs

@@ -0,0 +1,90 @@
+// @ts-self-types="./module.f.d.mts"
+import { log2 } from '../bigint/module.f.mjs'
+
+/**
+ * A vector of bits represented as a `bigint`.
+ *
+ * @typedef {bigint} Vec
+ */
+
+/**
+ * An empty vector of bits.
+ */
+export const empty = 1n
+
+/**
+ * Calculates the length of the given vector of bits.
+ */
+export const len = log2
+
+/**
+ * Extract an unsigned integer of the given `uintLen` from the given vector.
+ *
+ * @type {(uintLen: bigint) => (v: Vec) => bigint}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = 0b110101n;
+ * const extract3Bits = uint(3n);
+ * const result = extract3Bits(vector); // result is 0b101n (5n)
+ * ```
+ */
+export const uint = uintLen => {
+    const mask = (1n << uintLen) - 1n
+    return data => data & mask
+}
+
+/**
+ * Creates a vector of bits of the given `vecLen` from the given unsigned integer.
+ *
+ * @type {(vecLen: bigint) => (ui: bigint) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const createVector = vec(4n);
+ * const vector = createVector(5n); // vector is 0b10101n
+ * ```
+ */
+export const vec = vecLen => {
+    const stop = 1n << vecLen
+    const mask = stop - 1n
+    return data => (data & mask) | stop
+}
+
+/**
+ * Appends the vector `b` to the back of the vector `a`.
+ *
+ * @type {(a: Vec) => (b: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const vec8 = vec(8n)
+ * const a = vec8(0x345n)
+ * const b = vec8(0x789n)
+ * const ab = appendBack(a)(b) // 0x18945n
+ * ```
+ */
+export const appendBack = a => {
+    const aLen = len(a)
+    return b => a | (b << aLen)
+}
+
+/**
+ * Removes the first `len` bits from the given vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const v = vec(17n)(0x12345n) // v = 0x32345n
+ * const r = removeFront(9n)(v) // r = 0x191n
+ * ```
+ */
+export const removeFront = len => v => {
+    const r = v >> len
+    return r === 0n ? empty : r
+}

package/types/bit_vec/test.f.mjs

@@ -0,0 +1,41 @@
+import { empty, len, appendBack, vec, uint, removeFront } from './module.f.mjs'
+
+export default {
+    uintExample: () => {
+        const vector = 0b110101n;
+        const extract3Bits = uint(3n);
+        const result = extract3Bits(vector); // result is 0b101n (5n)
+        if (result !== 0b101n) { throw result }
+    },
+    vecExample: () => {
+        const createVector = vec(4n);
+        const vector = createVector(5n); // vector is 0b10101n
+        if (vector !== 0b10101n) { throw vector }
+    },
+    length: () => {
+        const i = len(empty)
+        if (i !== 0n) { throw i}
+    },
+    bitset: () => {
+        const v = vec(8n)(0x5FEn)
+        if (v !== 0x1FEn) { throw v }
+        if (len(v) !== 8n) { throw 'len' }
+        const u = uint(8n)(v)
+        if (u !== 0xFEn) { throw v }
+    },
+    appendBack: () => {
+        const vec8 = vec(8n)
+        const a = vec8(0x345n)
+        const b = vec8(0x789n)
+        const ab = appendBack(a)(b)
+        if (ab !== 0x18945n) { throw ab }
+        const s = len(ab)
+        if (s !== 16n) { throw `appendBack: ${s}` }
+    },
+    removeBack: () => {
+        const v = vec(17n)(0x12345n)
+        if (v !== 0x32345n) { throw v.toString(16) }
+        const r = removeFront(9n)(v)
+        if (r !== 0x191n) { throw r.toString(16) }
+    }
+}