@bsv/sdk 1.0.0

package/src/primitives/JacobianPoint.ts

@@ -0,0 +1,410 @@
+import BasePoint from './BasePoint.js'
+import BigNumber from './BigNumber.js'
+import Point from './Point.js'
+
+/**
+ * The `JacobianPoint` class extends the `BasePoint` class for handling Jacobian coordinates on an Elliptic Curve.
+ * This class defines the properties and the methods needed to work with points in Jacobian coordinates.
+ *
+ * The Jacobian coordinates represent a point (x, y, z) on an Elliptic Curve such that the usual (x, y) coordinates are given by (x/z^2, y/z^3).
+ *
+ * @property x - The `x` coordinate of the point in the Jacobian form.
+ * @property y - The `y` coordinate of the point in the Jacobian form.
+ * @property z - The `z` coordinate of the point in the Jacobian form.
+ * @property zOne - Flag that indicates if the `z` coordinate is one.
+ *
+ * @example
+ * const pointJ = new JacobianPoint('3', '4', '1');
+ */
+export default class JacobianPoint extends BasePoint {
+  x: BigNumber
+  y: BigNumber
+  z: BigNumber
+  zOne: boolean
+
+  /**
+   * Constructs a new `JacobianPoint` instance.
+   *
+   * @param x - If `null`, the x-coordinate will default to the curve's defined 'one' constant.
+   * If `x` is not a BigNumber, `x` will be converted to a `BigNumber` assuming it is a hex string.
+   *
+   * @param y - If `null`, the y-coordinate will default to the curve's defined 'one' constant.
+   * If `y` is not a BigNumber, `y` will be converted to a `BigNumber` assuming it is a hex string.
+   *
+   * @param z - If `null`, the z-coordinate will default to 0.
+   * If `z` is not a BigNumber, `z` will be converted to a `BigNumber` assuming it is a hex string.
+   *
+   * @example
+   * const pointJ1 = new JacobianPoint(null, null, null); // creates point at infinity
+   * const pointJ2 = new JacobianPoint('3', '4', '1'); // creates point (3, 4, 1)
+   */
+  constructor (
+    x: string | BigNumber | null,
+    y: string | BigNumber | null,
+    z: string | BigNumber | null
+  ) {
+    super('jacobian')
+    if (x === null && y === null && z === null) {
+      this.x = this.curve.one
+      this.y = this.curve.one
+      this.z = new BigNumber(0)
+    } else {
+      if (!BigNumber.isBN(x)) {
+        x = new BigNumber(x as string, 16)
+      }
+      this.x = x as BigNumber
+      if (!BigNumber.isBN(y)) {
+        y = new BigNumber(y as string, 16)
+      }
+      this.y = y as BigNumber
+      if (!BigNumber.isBN(z)) {
+        z = new BigNumber(z as string, 16)
+      }
+      this.z = z as BigNumber
+    }
+    if (this.x.red == null) { this.x = this.x.toRed(this.curve.red) }
+    if (this.y.red == null) { this.y = this.y.toRed(this.curve.red) }
+    if (this.z.red == null) { this.z = this.z.toRed(this.curve.red) }
+
+    this.zOne = this.z === this.curve.one
+  }
+
+  /**
+   * Converts the `JacobianPoint` object instance to standard affine `Point` format and returns `Point` type.
+   *
+   * @returns The `Point`(affine) object representing the same point as the original `JacobianPoint`.
+   *
+   * If the initial `JacobianPoint` represents point at infinity, an instance of `Point` at infinity is returned.
+   *
+   * @example
+   * const pointJ = new JacobianPoint('3', '4', '1');
+   * const pointP = pointJ.toP();  // The point in affine coordinates.
+   */
+  toP (): Point {
+    if (this.isInfinity()) {
+      return new Point(null, null)
+    }
+
+    const zinv = this.z.redInvm()
+    const zinv2 = zinv.redSqr()
+    const ax = this.x.redMul(zinv2)
+    const ay = this.y.redMul(zinv2).redMul(zinv)
+
+    return new Point(ax, ay)
+  }
+
+  /**
+   * Negation operation. It returns the additive inverse of the Jacobian point.
+   *
+   * @method neg
+   * @returns Returns a new Jacobian point as the result of the negation.
+   *
+   * @example
+   * const jp = new JacobianPoint(x, y, z)
+   * const result = jp.neg()
+   */
+  neg (): JacobianPoint {
+    return new JacobianPoint(this.x, this.y.redNeg(), this.z)
+  }
+
+  /**
+   * Addition operation in the Jacobian coordinates. It takes a Jacobian point as an argument
+   * and returns a new Jacobian point as a result of the addition. In the special cases,
+   * when either one of the points is the point at infinity, it will return the other point.
+   *
+   * @method add
+   * @param p - The Jacobian point to be added.
+   * @returns Returns a new Jacobian point as the result of the addition.
+   *
+   * @example
+   * const p1 = new JacobianPoint(x1, y1, z1)
+   * const p2 = new JacobianPoint(x2, y2, z2)
+   * const result = p1.add(p2)
+   */
+  add (p: JacobianPoint): JacobianPoint {
+    // O + P = P
+    if (this.isInfinity()) { return p }
+
+    // P + O = P
+    if (p.isInfinity()) { return this }
+
+    // 12M + 4S + 7A
+    const pz2 = p.z.redSqr()
+    const z2 = this.z.redSqr()
+    const u1 = this.x.redMul(pz2)
+    const u2 = p.x.redMul(z2)
+    const s1 = this.y.redMul(pz2.redMul(p.z))
+    const s2 = p.y.redMul(z2.redMul(this.z))
+
+    const h = u1.redSub(u2)
+    const r = s1.redSub(s2)
+    if (h.cmpn(0) === 0) {
+      if (r.cmpn(0) !== 0) {
+        return new JacobianPoint(null, null, null)
+      } else {
+        return this.dbl()
+      }
+    }
+
+    const h2 = h.redSqr()
+    const h3 = h2.redMul(h)
+    const v = u1.redMul(h2)
+
+    const nx = r.redSqr().redIAdd(h3).redISub(v).redISub(v)
+    const ny = r.redMul(v.redISub(nx)).redISub(s1.redMul(h3))
+    const nz = this.z.redMul(p.z).redMul(h)
+
+    return new JacobianPoint(nx, ny, nz)
+  }
+
+  /**
+   * Mixed addition operation. This function combines the standard point addition with
+   * the transformation from the affine to Jacobian coordinates. It first converts
+   * the affine point to Jacobian, and then preforms the addition.
+   *
+   * @method mixedAdd
+   * @param p - The affine point to be added.
+   * @returns Returns the result of the mixed addition as a new Jacobian point.
+   *
+   * @example
+   * const jp = new JacobianPoint(x1, y1, z1)
+   * const ap = new Point(x2, y2)
+   * const result = jp.mixedAdd(ap)
+   */
+  mixedAdd (p: Point): JacobianPoint {
+    // O + P = P
+    if (this.isInfinity()) { return p.toJ() }
+
+    // P + O = P
+    if (p.isInfinity()) { return this }
+
+    // 8M + 3S + 7A
+    const z2 = this.z.redSqr()
+    const u1 = this.x
+    const u2 = p.x.redMul(z2)
+    const s1 = this.y
+    const s2 = p.y.redMul(z2).redMul(this.z)
+
+    const h = u1.redSub(u2)
+    const r = s1.redSub(s2)
+    if (h.cmpn(0) === 0) {
+      if (r.cmpn(0) !== 0) {
+        return new JacobianPoint(null, null, null)
+      } else {
+        return this.dbl()
+      }
+    }
+
+    const h2 = h.redSqr()
+    const h3 = h2.redMul(h)
+    const v = u1.redMul(h2)
+
+    const nx = r.redSqr().redIAdd(h3).redISub(v).redISub(v)
+    const ny = r.redMul(v.redISub(nx)).redISub(s1.redMul(h3))
+    const nz = this.z.redMul(h)
+
+    return new JacobianPoint(nx, ny, nz)
+  }
+
+  /**
+   * Multiple doubling operation. It doubles the Jacobian point as many times as the pow parameter specifies. If pow is 0 or the point is the point at infinity, it will return the point itself.
+   *
+   * @method dblp
+   * @param pow - The number of times the point should be doubled.
+   * @returns Returns a new Jacobian point as the result of multiple doublings.
+   *
+   * @example
+   * const jp = new JacobianPoint(x, y, z)
+   * const result = jp.dblp(3)
+   */
+  dblp (pow: number): JacobianPoint {
+    if (pow === 0) {
+      return this
+    }
+    if (this.isInfinity()) {
+      return this
+    }
+    if (typeof pow === 'undefined') {
+      return this.dbl()
+    }
+
+    /* eslint-disable @typescript-eslint/no-this-alias */
+    let r = this as JacobianPoint
+    for (let i = 0; i < pow; i++) { r = r.dbl() }
+    return r
+  }
+
+  /**
+   * Point doubling operation in the Jacobian coordinates. A special case is when the point is the point at infinity, in this case, this function will return the point itself.
+   *
+   * @method dbl
+   * @returns Returns a new Jacobian point as the result of the doubling.
+   *
+   * @example
+   * const jp = new JacobianPoint(x, y, z)
+   * const result = jp.dbl()
+   */
+  dbl (): JacobianPoint {
+    if (this.isInfinity()) {
+      return this
+    }
+
+    let nx
+    let ny
+    let nz
+    // Z = 1
+    if (this.zOne) {
+      // hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-0.html
+      //     #doubling-mdbl-2007-bl
+      // 1M + 5S + 14A
+
+      // XX = X1^2
+      const xx = this.x.redSqr()
+      // YY = Y1^2
+      const yy = this.y.redSqr()
+      // YYYY = YY^2
+      const yyyy = yy.redSqr()
+      // S = 2 * ((X1 + YY)^2 - XX - YYYY)
+      let s = this.x.redAdd(yy).redSqr().redISub(xx).redISub(yyyy)
+      s = s.redIAdd(s)
+      // M = 3 * XX + a; a = 0
+      const m = xx.redAdd(xx).redIAdd(xx)
+      // T = M ^ 2 - 2*S
+      const t = m.redSqr().redISub(s).redISub(s)
+
+      // 8 * YYYY
+      let yyyy8 = yyyy.redIAdd(yyyy)
+      yyyy8 = yyyy8.redIAdd(yyyy8)
+      yyyy8 = yyyy8.redIAdd(yyyy8)
+
+      // X3 = T
+      nx = t
+      // Y3 = M * (S - T) - 8 * YYYY
+      ny = m.redMul(s.redISub(t)).redISub(yyyy8)
+      // Z3 = 2*Y1
+      nz = this.y.redAdd(this.y)
+    } else {
+      // hyperelliptic.org/EFD/g1p/auto-shortw-jacobian-0.html
+      //     #doubling-dbl-2009-l
+      // 2M + 5S + 13A
+
+      // A = X1^2
+      const a = this.x.redSqr()
+      // B = Y1^2
+      const b = this.y.redSqr()
+      // C = B^2
+      const c = b.redSqr()
+      // D = 2 * ((X1 + B)^2 - A - C)
+      let d = this.x.redAdd(b).redSqr().redISub(a).redISub(c)
+      d = d.redIAdd(d)
+      // E = 3 * A
+      const e = a.redAdd(a).redIAdd(a)
+      // F = E^2
+      const f = e.redSqr()
+
+      // 8 * C
+      let c8 = c.redIAdd(c)
+      c8 = c8.redIAdd(c8)
+      c8 = c8.redIAdd(c8)
+
+      // X3 = F - 2 * D
+      nx = f.redISub(d).redISub(d)
+      // Y3 = E * (D - X3) - 8 * C
+      ny = e.redMul(d.redISub(nx)).redISub(c8)
+      // Z3 = 2 * Y1 * Z1
+      nz = this.y.redMul(this.z)
+      nz = nz.redIAdd(nz)
+    }
+
+    return new JacobianPoint(nx, ny, nz)
+  }
+
+  /**
+   * Equality check operation. It checks whether the affine or Jacobian point is equal to this Jacobian point.
+   *
+   * @method eq
+   * @param p - The affine or Jacobian point to compare with.
+   * @returns Returns true if the points are equal, otherwise returns false.
+   *
+   * @example
+   * const jp1 = new JacobianPoint(x1, y1, z1)
+   * const jp2 = new JacobianPoint(x2, y2, z2)
+   * const areEqual = jp1.eq(jp2)
+   */
+  eq (p: Point | JacobianPoint): boolean {
+    if (p.type === 'affine') { return this.eq((p as Point).toJ()) }
+
+    if (this === p) { return true }
+
+    // x1 * z2^2 == x2 * z1^2
+    const z2 = this.z.redSqr()
+    p = p as JacobianPoint
+    const pz2 = p.z.redSqr()
+    if (this.x.redMul(pz2).redISub(p.x.redMul(z2)).cmpn(0) !== 0) {
+      return false
+    }
+
+    // y1 * z2^3 == y2 * z1^3
+    const z3 = z2.redMul(this.z)
+    const pz3 = pz2.redMul(p.z)
+    return this.y.redMul(pz3).redISub(p.y.redMul(z3)).cmpn(0) === 0
+  }
+
+  /**
+   * Equality check operation in relation to an x coordinate of a point in projective coordinates.
+   * It checks whether the x coordinate of the Jacobian point is equal to the provided x coordinate
+   * of a point in projective coordinates.
+   *
+   * @method eqXToP
+   * @param x - The x coordinate of a point in projective coordinates.
+   * @returns Returns true if the x coordinates are equal, otherwise returns false.
+   *
+   * @example
+   * const jp = new JacobianPoint(x1, y1, z1)
+   * const isXEqual = jp.eqXToP(x2)
+   */
+  eqXToP (x: BigNumber): boolean {
+    const zs = this.z.redSqr()
+    const rx = x.toRed(this.curve.red).redMul(zs)
+    if (this.x.cmp(rx) === 0) { return true }
+
+    const xc = x.clone()
+    const t = this.curve.redN.redMul(zs)
+    for (; ;) {
+      xc.iadd(this.curve.n)
+      if (xc.cmp(this.curve.p) >= 0) { return false }
+
+      rx.redIAdd(t)
+      if (this.x.cmp(rx) === 0) { return true }
+    }
+  }
+
+  /**
+   * Returns the string representation of the JacobianPoint instance.
+   * @method inspect
+   * @returns Returns the string description of the JacobianPoint. If the JacobianPoint represents a point at infinity, the return value of this function is '<EC JPoint Infinity>'. For a normal point, it returns the string description format as '<EC JPoint x: x-coordinate y: y-coordinate z: z-coordinate>'.
+   *
+   * @example
+   * const point = new JacobianPoint('5', '6', '1');
+   * console.log(point.inspect()); // Output: '<EC JPoint x: 5 y: 6 z: 1>'
+   */
+  inspect (): string {
+    if (this.isInfinity()) { return '<EC JPoint Infinity>' }
+    return '<EC JPoint x: ' + this.x.toString(16, 2) +
+      ' y: ' + this.y.toString(16, 2) +
+      ' z: ' + this.z.toString(16, 2) + '>'
+  }
+
+  /**
+   * Checks whether the JacobianPoint instance represents a point at infinity.
+   * @method isInfinity
+   * @returns Returns true if the JacobianPoint's z-coordinate equals to zero (which represents the point at infinity in Jacobian coordinates). Returns false otherwise.
+   *
+   * @example
+   * const point = new JacobianPoint('5', '6', '0');
+   * console.log(point.isInfinity()); // Output: true
+   */
+  isInfinity (): boolean {
+    return this.z.cmpn(0) === 0
+  }
+}

package/src/primitives/K256.ts

@@ -0,0 +1,116 @@
+import Mersenne from './Mersenne.js'
+import BigNumber from './BigNumber.js'
+
+/**
+ * A class representing K-256, a prime number with optimizations, specifically used in the secp256k1 curve.
+ * It extends the functionalities of the Mersenne class.
+ * K-256 prime is represented as 'ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff fffffffe fffffc2f'
+ *
+ * @class K256
+ * @extends {Mersenne}
+ *
+ * @example
+ * const k256 = new K256();
+ */
+export default class K256 extends Mersenne {
+  /**
+   * Constructor for the K256 class.
+   * Creates an instance of K256 using the super constructor from Mersenne.
+   *
+   * @constructor
+   *
+   * @example
+   * const k256 = new K256();
+   */
+  constructor () {
+    super(
+      'k256',
+      'ffffffff ffffffff ffffffff ffffffff ffffffff ffffffff fffffffe fffffc2f'
+    )
+  }
+
+  /**
+   * Splits a BigNumber into a new BigNumber based on specific computation
+   * rules. This method modifies the input and output big numbers.
+   *
+   * @method split
+   * @param input - The BigNumber to be split.
+   * @param output - The BigNumber that results from the split.
+   *
+   * @example
+   * const input = new BigNumber(3456);
+   * const output = new BigNumber(0);
+   * k256.split(input, output);
+   */
+  split (input: BigNumber, output: BigNumber): void {
+    // 256 = 9 * 26 + 22
+    const mask = 0x3fffff
+
+    const outLen = Math.min(input.length, 9)
+    let i = 0
+    for (; i < outLen; i++) {
+      output.words[i] = input.words[i]
+    }
+    output.length = outLen
+
+    if (input.length <= 9) {
+      input.words[0] = 0
+      input.length = 1
+      return
+    }
+
+    // Shift by 9 limbs
+    let prev = input.words[9]
+    output.words[output.length++] = prev & mask
+
+    for (i = 10; i < input.length; i++) {
+      const next = input.words[i] | 0
+      input.words[i - 10] = ((next & mask) << 4) | (prev >>> 22)
+      prev = next
+    }
+    prev >>>= 22
+    input.words[i - 10] = prev
+    if (prev === 0 && input.length > 10) {
+      input.length -= 10
+    } else {
+      input.length -= 9
+    }
+  }
+
+  /**
+   * Multiplies a BigNumber ('num') with the constant 'K' in-place and returns the result.
+   * 'K' is equal to 0x1000003d1 or in decimal representation: [ 64, 977 ].
+   *
+   * @method imulK
+   * @param num - The BigNumber to multiply with K.
+   * @returns Returns the mutated BigNumber after multiplication.
+   *
+   * @example
+   * const number = new BigNumber(12345);
+   * const result = k256.imulK(number);
+   */
+  imulK (num: BigNumber): BigNumber {
+    // K = 0x1000003d1 = [ 0x40, 0x3d1 ]
+    num.words[num.length] = 0
+    num.words[num.length + 1] = 0
+    num.length += 2
+
+    // bounded at: 0x40 * 0x3ffffff + 0x3d0 = 0x100000390
+    let lo = 0
+    for (let i = 0; i < num.length; i++) {
+      const w = num.words[i] | 0
+      lo += w * 0x3d1
+      num.words[i] = lo & 0x3ffffff
+      lo = w * 0x40 + ((lo / 0x4000000) | 0)
+    }
+
+    // Fast length reduction
+    if (num.words[num.length - 1] === 0) {
+      num.length--
+      if (num.words[num.length - 1] === 0) {
+        num.length--
+      }
+    }
+    return num
+  }
+}

package/src/primitives/Mersenne.ts

@@ -0,0 +1,123 @@
+import BigNumber from './BigNumber.js'
+
+/**
+ * A representation of a pseudo-Mersenne prime.
+ * A pseudo-Mersenne prime has the general form 2^n - k, where n and k are integers.
+ *
+ * @class Mersenne
+ *
+ * @property name - The identifier for the Mersenne instance.
+ * @property p - BigNumber equivalent to 2^n - k.
+ * @property k - The constant subtracted from 2^n to derive a pseudo-Mersenne prime.
+ * @property n - The exponent which determines the magnitude of the prime.
+ */
+export default class Mersenne {
+  name: string
+  p: BigNumber
+  k: BigNumber
+  n: number
+  private readonly tmp: BigNumber
+
+  /**
+   * @constructor
+   * @param name - An identifier for the Mersenne instance.
+   * @param p - A string representation of the pseudo-Mersenne prime, expressed in hexadecimal.
+   *
+   * @example
+   * const mersenne = new Mersenne('M31', '7FFFFFFF');
+   */
+  constructor (name: string, p: string) {
+    // P = 2 ^ N - K
+    this.name = name
+    this.p = new BigNumber(p, 16)
+    this.n = this.p.bitLength()
+    this.k = new BigNumber(1).iushln(this.n).isub(this.p)
+
+    this.tmp = this._tmp()
+  }
+
+  /**
+   * Creates a temporary BigNumber structure for computations,
+   * ensuring the appropriate number of words are initially allocated.
+   *
+   * @method _tmp
+   * @returns A BigNumber with scaled size depending on prime magnitude.
+   */
+  private _tmp (): BigNumber {
+    const tmp = new BigNumber()
+    tmp.words = new Array(Math.ceil(this.n / 13))
+    return tmp
+  }
+
+  /**
+   * Reduces an input BigNumber in place, under the assumption that
+   * it is less than the square of the pseudo-Mersenne prime.
+   *
+   * @method ireduce
+   * @param num - The BigNumber to be reduced.
+   * @returns The reduced BigNumber.
+   *
+   * @example
+   * const reduced = mersenne.ireduce(new BigNumber('2345', 16));
+   */
+  ireduce (num: BigNumber): BigNumber {
+    // Assumes that `num` is less than `P^2`
+    // num = HI * (2 ^ N - K) + HI * K + LO = HI * K + LO (mod P)
+    let r = num
+    let rlen
+
+    do {
+      this.split(r, this.tmp)
+      r = this.imulK(r)
+      r = r.iadd(this.tmp)
+      rlen = r.bitLength()
+    } while (rlen > this.n)
+
+    const cmp = rlen < this.n ? -1 : r.ucmp(this.p)
+    if (cmp === 0) {
+      r.words[0] = 0
+      r.length = 1
+    } else if (cmp > 0) {
+      r.isub(this.p)
+    } else {
+      if (r.strip !== undefined) {
+        // r is a BN v4 instance
+        r.strip()
+      } else {
+        // r is a BN v5 instance
+        r.strip()
+      }
+    }
+
+    return r
+  }
+
+  /**
+   * Shifts bits of the input BigNumber to the right, in place,
+   * to meet the magnitude of the pseudo-Mersenne prime.
+   *
+   * @method split
+   * @param input - The BigNumber to be shifted.
+   * @param out - The BigNumber to hold the shifted result.
+   *
+   * @example
+   * mersenne.split(new BigNumber('2345', 16), new BigNumber());
+   */
+  split (input: BigNumber, out: BigNumber): void {
+    input.iushrn(this.n, 0, out)
+  }
+
+  /**
+   * Performs an in-place multiplication of the parameter by constant k.
+   *
+   * @method imulK
+   * @param num - The BigNumber to multiply with k.
+   * @returns The result of the multiplication, in BigNumber format.
+   *
+   * @example
+   * const multiplied = mersenne.imulK(new BigNumber('2345', 16));
+   */
+  imulK (num: BigNumber): BigNumber {
+    return num.imul(this.k)
+  }
+}