@utxopia/sdk 0.1.0-alpha.2 → 0.1.0-alpha.3

package/src/crypto-babyjub.ts

@@ -0,0 +1,385 @@
+/**
+ * Baby Jubjub curve operations for UTXOpia
+ *
+ * Twisted Edwards curve matching circomlib's BabyJubjub:
+ *   a*x^2 + y^2 = 1 + d*x^2*y^2
+ *   a = 168700, d = 168696
+ *
+ * Over BN254 scalar field.
+ * Used for spending keys and in-circuit key derivation via BabyPbk().
+ *
+ * @see https://eips.ethereum.org/EIPS/eip-2494
+ * @see circomlib/circuits/babyjub.circom
+ */
+
+import { sha256 } from "@noble/hashes/sha2.js";
+
+// =============================================================================
+// Field Constants
+// =============================================================================
+
+/** BN254 scalar field prime (Baby Jubjub base field) */
+export const BABYJUB_FIELD_PRIME =
+  21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+
+/** Baby Jubjub curve parameter a */
+export const BABYJUB_A = 168700n;
+
+/** Baby Jubjub curve parameter d */
+export const BABYJUB_D = 168696n;
+
+/**
+ * Baby Jubjub subgroup order (order of BASE8 generator)
+ * = field_prime / 8 (cofactor 8)
+ */
+export const BABYJUB_ORDER =
+  2736030358979909402780800718157159386076813972158567259200215660948447373041n;
+
+/**
+ * Baby Jubjub cofactor
+ */
+export const BABYJUB_COFACTOR = 8n;
+
+/**
+ * Generator point (BASE8) - matches circomlib's BabyPbk() generator
+ * This is the base point of the prime-order subgroup (cofactor-cleared).
+ */
+export const BABYJUB_BASE8: BabyJubPoint = {
+  x: 5299619240641551281634865583518297030282874472190772894086521144482721001553n,
+  y: 16950150798460657717958625567821834550301663161624707787222815936182638968203n,
+};
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Point on the Baby Jubjub curve (affine coordinates) */
+export interface BabyJubPoint {
+  x: bigint;
+  y: bigint;
+}
+
+/** Identity element (point at infinity for twisted Edwards) */
+export const BABYJUB_IDENTITY: BabyJubPoint = { x: 0n, y: 1n };
+
+// =============================================================================
+// Modular Arithmetic
+// =============================================================================
+
+const P = BABYJUB_FIELD_PRIME;
+
+function mod(n: bigint, p: bigint = P): bigint {
+  const result = n % p;
+  return result >= 0n ? result : result + p;
+}
+
+function modInverse(a: bigint, p: bigint = P): bigint {
+  let [old_r, r] = [a, p];
+  let [old_s, s] = [1n, 0n];
+
+  while (r !== 0n) {
+    const q = old_r / r;
+    [old_r, r] = [r, old_r - q * r];
+    [old_s, s] = [s, old_s - q * s];
+  }
+
+  return mod(old_s, p);
+}
+
+// =============================================================================
+// Curve Operations
+// =============================================================================
+
+/**
+ * Check if a point is the identity element
+ */
+export function isIdentity(point: BabyJubPoint): boolean {
+  return point.x === 0n && point.y === 1n;
+}
+
+/**
+ * Verify a point is on the Baby Jubjub curve
+ *
+ * a*x^2 + y^2 = 1 + d*x^2*y^2
+ */
+export function isOnBabyJubCurve(point: BabyJubPoint): boolean {
+  if (isIdentity(point)) return true;
+
+  const { x, y } = point;
+  const x2 = mod(x * x);
+  const y2 = mod(y * y);
+
+  const lhs = mod(BABYJUB_A * x2 + y2);
+  const rhs = mod(1n + BABYJUB_D * x2 * y2);
+
+  return lhs === rhs;
+}
+
+/**
+ * Point addition on Baby Jubjub (twisted Edwards addition law)
+ *
+ * For twisted Edwards: a*x^2 + y^2 = 1 + d*x^2*y^2
+ * x3 = (x1*y2 + y1*x2) / (1 + d*x1*x2*y1*y2)
+ * y3 = (y1*y2 - a*x1*x2) / (1 - d*x1*x2*y1*y2)
+ */
+export function babyJubAdd(p1: BabyJubPoint, p2: BabyJubPoint): BabyJubPoint {
+  const { x: x1, y: y1 } = p1;
+  const { x: x2, y: y2 } = p2;
+
+  const x1x2 = mod(x1 * x2);
+  const y1y2 = mod(y1 * y2);
+  const dx1x2y1y2 = mod(BABYJUB_D * x1x2 * y1y2);
+
+  const x3Num = mod(x1 * y2 + y1 * x2);
+  const x3Den = mod(1n + dx1x2y1y2);
+
+  const y3Num = mod(y1y2 - BABYJUB_A * x1x2);
+  const y3Den = mod(1n - dx1x2y1y2);
+
+  const x3 = mod(x3Num * modInverse(x3Den));
+  const y3 = mod(y3Num * modInverse(y3Den));
+
+  return { x: x3, y: y3 };
+}
+
+/**
+ * Point doubling on Baby Jubjub
+ */
+export function babyJubDouble(point: BabyJubPoint): BabyJubPoint {
+  return babyJubAdd(point, point);
+}
+
+/**
+ * Scalar multiplication using double-and-add (constant-time Montgomery ladder)
+ *
+ * SECURITY: Uses Montgomery ladder for constant-time execution.
+ */
+export function babyJubMul(scalar: bigint, point: BabyJubPoint): BabyJubPoint {
+  scalar = mod(scalar, BABYJUB_ORDER);
+
+  if (scalar === 0n) return BABYJUB_IDENTITY;
+  if (isIdentity(point)) return BABYJUB_IDENTITY;
+
+  // Montgomery ladder
+  let r0 = BABYJUB_IDENTITY;
+  let r1 = point;
+
+  // Process all bits of the scalar
+  const bits = scalar.toString(2).length;
+  for (let i = bits - 1; i >= 0; i--) {
+    const bit = (scalar >> BigInt(i)) & 1n;
+
+    if (bit === 1n) {
+      r0 = babyJubAdd(r0, r1);
+      r1 = babyJubDouble(r1);
+    } else {
+      r1 = babyJubAdd(r0, r1);
+      r0 = babyJubDouble(r0);
+    }
+  }
+
+  return r0;
+}
+
+/**
+ * Negate a point (flip x coordinate for twisted Edwards)
+ */
+export function babyJubNegate(point: BabyJubPoint): BabyJubPoint {
+  if (isIdentity(point)) return point;
+  return {
+    x: mod(-point.x),
+    y: point.y,
+  };
+}
+
+// =============================================================================
+// Compression / Serialization
+// =============================================================================
+
+/**
+ * Compress a Baby Jubjub point to 32 bytes
+ *
+ * Format: y-coordinate with sign of x stored in MSB of last byte
+ * This matches circomlib's pointbits.circom compression.
+ */
+export function babyJubCompress(point: BabyJubPoint): Uint8Array {
+  const bytes = new Uint8Array(32);
+  let y = point.y;
+
+  // Store y in little-endian (matching circomlib convention)
+  let temp = y;
+  for (let i = 0; i < 32; i++) {
+    bytes[i] = Number(temp & 0xffn);
+    temp = temp >> 8n;
+  }
+
+  // Set MSB of last byte to sign of x (1 if x is odd)
+  if ((point.x & 1n) === 1n) {
+    bytes[31] |= 0x80;
+  }
+
+  return bytes;
+}
+
+/**
+ * Decompress a 32-byte representation to a Baby Jubjub point
+ */
+export function babyJubDecompress(bytes: Uint8Array): BabyJubPoint {
+  if (bytes.length !== 32) {
+    throw new Error("Expected 32 bytes for compressed Baby Jubjub point");
+  }
+
+  // Extract sign of x from MSB
+  const xSign = (bytes[31] & 0x80) !== 0;
+
+  // Read y (little-endian), clearing the sign bit
+  const cleanBytes = new Uint8Array(bytes);
+  cleanBytes[31] &= 0x7f;
+
+  let y = 0n;
+  for (let i = 31; i >= 0; i--) {
+    y = (y << 8n) | BigInt(cleanBytes[i]);
+  }
+
+  // Recover x from curve equation: a*x^2 + y^2 = 1 + d*x^2*y^2
+  // x^2 = (1 - y^2) / (a - d*y^2)
+  const y2 = mod(y * y);
+  const num = mod(1n - y2);
+  const den = mod(BABYJUB_A - BABYJUB_D * y2);
+  const x2 = mod(num * modInverse(den));
+
+  // Compute x via Tonelli-Shanks square root
+  let x = modSqrt(x2);
+
+  // Adjust sign of x
+  const xIsOdd = (x & 1n) === 1n;
+  if (xIsOdd !== xSign) {
+    x = mod(-x);
+  }
+
+  const point = { x, y };
+  if (!isOnBabyJubCurve(point)) {
+    throw new Error("Decompressed point is not on the Baby Jubjub curve");
+  }
+
+  return point;
+}
+
+/**
+ * Tonelli-Shanks modular square root
+ */
+function modSqrt(n: bigint): bigint {
+  if (n === 0n) return 0n;
+
+  // For p ≡ 3 (mod 4), sqrt = n^((p+1)/4)
+  // BN254 scalar field: p ≡ 1 (mod 4), so we need full Tonelli-Shanks
+  const p = P;
+
+  // Check if n is a quadratic residue
+  const euler = modPow(n, (p - 1n) / 2n);
+  if (euler !== 1n) {
+    throw new Error("No square root exists (not a quadratic residue)");
+  }
+
+  // Factor out powers of 2 from p-1
+  let Q = p - 1n;
+  let S = 0n;
+  while ((Q & 1n) === 0n) {
+    Q >>= 1n;
+    S++;
+  }
+
+  // Find a non-residue z
+  let z = 2n;
+  while (modPow(z, (p - 1n) / 2n) !== p - 1n) {
+    z++;
+  }
+
+  let M = S;
+  let c = modPow(z, Q);
+  let t = modPow(n, Q);
+  let R = modPow(n, (Q + 1n) / 2n);
+
+  while (true) {
+    if (t === 1n) return R;
+
+    let i = 1n;
+    let temp = mod(t * t);
+    while (temp !== 1n) {
+      temp = mod(temp * temp);
+      i++;
+    }
+
+    const b = modPow(c, 1n << (M - i - 1n));
+    M = i;
+    c = mod(b * b);
+    t = mod(t * c);
+    R = mod(R * b);
+  }
+}
+
+function modPow(base: bigint, exp: bigint): bigint {
+  let result = 1n;
+  base = mod(base);
+
+  while (exp > 0n) {
+    if (exp & 1n) {
+      result = mod(result * base);
+    }
+    exp >>= 1n;
+    base = mod(base * base);
+  }
+
+  return result;
+}
+
+// =============================================================================
+// Key Generation
+// =============================================================================
+
+/**
+ * Generate a random Baby Jubjub keypair
+ */
+export function generateBabyJubKeyPair(): { privKey: bigint; pubKey: BabyJubPoint } {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const privKey = babyJubScalarFromBytes(bytes);
+  const pubKey = babyJubMul(privKey, BABYJUB_BASE8);
+  return { privKey, pubKey };
+}
+
+/**
+ * Derive a Baby Jubjub keypair from a seed (deterministic)
+ */
+export function deriveBabyJubKeyFromSeed(
+  seed: Uint8Array
+): { privKey: bigint; pubKey: BabyJubPoint } {
+  const hash = sha256(seed);
+  const privKey = babyJubScalarFromBytes(hash);
+  const pubKey = babyJubMul(privKey, BABYJUB_BASE8);
+  return { privKey, pubKey };
+}
+
+/**
+ * Derive a scalar from bytes (reduces modulo Baby Jubjub order)
+ */
+export function babyJubScalarFromBytes(bytes: Uint8Array): bigint {
+  let result = 0n;
+  for (let i = 0; i < bytes.length; i++) {
+    result = (result << 8n) | BigInt(bytes[i]);
+  }
+  return mod(result, BABYJUB_ORDER);
+}
+
+/**
+ * Convert a Baby Jubjub scalar to 32 bytes (big-endian)
+ */
+export function babyJubScalarToBytes(scalar: bigint): Uint8Array {
+  const bytes = new Uint8Array(32);
+  let temp = mod(scalar, BABYJUB_ORDER);
+  for (let i = 31; i >= 0; i--) {
+    bytes[i] = Number(temp & 0xffn);
+    temp >>= 8n;
+  }
+  return bytes;
+}

package/src/crypto-ed25519.ts

@@ -0,0 +1,297 @@
+/**
+ * Ed25519/X25519 utilities for UTXOpia viewing keys
+ *
+ * Uses @noble/curves for Ed25519 key generation and X25519 ECDH.
+ * Ed25519 is used for viewing keys (off-chain only, fast and standard).
+ *
+ * Viewing key operations:
+ * - Key generation: Ed25519 keypair
+ * - ECDH: X25519 (Montgomery form of Curve25519)
+ * - Shared secret: 32 bytes from X25519
+ *
+ * @see https://github.com/paulmillr/noble-curves
+ */
+
+import { ed25519 } from "@noble/curves/ed25519.js";
+import { x25519 } from "@noble/curves/ed25519.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+
+// =============================================================================
+// Key Generation
+// =============================================================================
+
+/**
+ * Generate an Ed25519 keypair for viewing key use
+ *
+ * @returns 32-byte private key and 32-byte public key
+ */
+export function ed25519GenerateKeyPair(): { privKey: Uint8Array; pubKey: Uint8Array } {
+  const privKey = ed25519.utils.randomSecretKey();
+  const pubKey = ed25519.getPublicKey(privKey);
+  return { privKey, pubKey };
+}
+
+/**
+ * Derive an Ed25519 keypair deterministically from secret material.
+ *
+ * Used for deposit ephemeral keys, where a random keypair is a liability: the
+ * deposit address commits to the ephemeral pubkey, so losing it makes the coins
+ * unspendable by anyone, forever. Deriving it from the owner's seed means the
+ * seed alone can rebuild every address they were ever handed.
+ *
+ * @param material - secret bytes; hashed, so it need not be uniform
+ */
+export function ed25519KeyPairFromMaterial(material: Uint8Array): {
+  privKey: Uint8Array;
+  pubKey: Uint8Array;
+} {
+  const privKey = sha256(material);
+  return { privKey, pubKey: ed25519.getPublicKey(privKey) };
+}
+
+/**
+ * Derive an Ed25519 public key from a private key
+ *
+ * @param privKey - 32-byte Ed25519 private key
+ * @returns 32-byte Ed25519 public key
+ */
+export function ed25519GetPublicKey(privKey: Uint8Array): Uint8Array {
+  return ed25519.getPublicKey(privKey);
+}
+
+/**
+ * Derive an Ed25519 keypair from a seed (deterministic)
+ *
+ * @param seed - Arbitrary bytes to derive from (will be SHA256'd to 32 bytes)
+ * @returns Ed25519 keypair
+ */
+export function ed25519DeriveKeyFromSeed(seed: Uint8Array): { privKey: Uint8Array; pubKey: Uint8Array } {
+  const privKey = sha256(seed);
+  const pubKey = ed25519.getPublicKey(privKey);
+  return { privKey, pubKey };
+}
+
+// =============================================================================
+// ECDH (X25519)
+// =============================================================================
+
+/**
+ * Convert Ed25519 public key to X25519 (Montgomery form) for ECDH
+ *
+ * Uses the birational map from twisted Edwards to Montgomery form.
+ */
+export function ed25519PubToX25519(edPub: Uint8Array): Uint8Array {
+  return ed25519.utils.toMontgomery(edPub);
+}
+
+/**
+ * Perform X25519 ECDH key exchange
+ *
+ * @param privKey - 32-byte Ed25519 private key (will be converted internally)
+ * @param pubKey - 32-byte Ed25519 public key (will be converted to X25519)
+ * @returns 32-byte shared secret
+ */
+export function x25519Ecdh(privKey: Uint8Array, pubKey: Uint8Array): Uint8Array {
+  // Convert Ed25519 pub to X25519 u-coordinate
+  const x25519Pub = ed25519.utils.toMontgomery(pubKey);
+
+  // Convert Ed25519 private key to X25519 scalar
+  const x25519Priv = ed25519.utils.toMontgomerySecret(privKey);
+
+  return x25519.getSharedSecret(x25519Priv, x25519Pub);
+}
+
+/**
+ * Convert an Ed25519 private key to its X25519 (Montgomery) scalar.
+ *
+ * Uses the same clamped-scalar derivation as `x25519Ecdh` internally.
+ * The returned 32 bytes are a valid X25519 private key suitable for
+ * `x25519.getSharedSecret` or `x25519.getPublicKey`.
+ */
+export function ed25519PrivToX25519(edPriv: Uint8Array): Uint8Array {
+  return ed25519.utils.toMontgomerySecret(edPriv);
+}
+
+/**
+ * Derive an X25519 public key from a raw X25519 private scalar.
+ */
+export function x25519PubFromPriv(x25519Priv: Uint8Array): Uint8Array {
+  return x25519.getPublicKey(x25519Priv);
+}
+
+/**
+ * Perform X25519 ECDH with raw X25519 keys (no Ed25519 conversion).
+ *
+ * @param x25519Priv - 32-byte X25519 private scalar (from `ed25519PrivToX25519` or `x25519PubFromPriv`)
+ * @param x25519Pub  - 32-byte X25519 public key (u-coordinate)
+ * @returns 32-byte shared secret
+ */
+export function x25519EcdhRaw(x25519Priv: Uint8Array, x25519Pub: Uint8Array): Uint8Array {
+  return x25519.getSharedSecret(x25519Priv, x25519Pub);
+}
+
+// =============================================================================
+// Amount Encryption/Decryption
+// =============================================================================
+
+/**
+ * Derive an 8-byte encryption key from X25519 shared secret
+ *
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 8-byte encryption key
+ */
+export function deriveAmountKey(sharedSecret: Uint8Array): Uint8Array {
+  const hash = sha256(sharedSecret);
+  return hash.slice(0, 8);
+}
+
+/**
+ * Encrypt amount with XOR using shared secret
+ *
+ * @param amount - Amount in satoshis
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 8-byte encrypted amount
+ */
+export function encryptAmountEd25519(amount: bigint, sharedSecret: Uint8Array): Uint8Array {
+  const key = deriveAmountKey(sharedSecret);
+  const amountBytes = new Uint8Array(8);
+
+  let temp = amount;
+  for (let i = 0; i < 8; i++) {
+    amountBytes[i] = Number(temp & 0xffn);
+    temp >>= 8n;
+  }
+
+  const encrypted = new Uint8Array(8);
+  for (let i = 0; i < 8; i++) {
+    encrypted[i] = amountBytes[i] ^ key[i];
+  }
+
+  return encrypted;
+}
+
+/**
+ * Decrypt amount with XOR using shared secret
+ *
+ * @param encryptedAmount - 8-byte encrypted amount
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns Decrypted amount in satoshis
+ */
+export function decryptAmountEd25519(encryptedAmount: Uint8Array, sharedSecret: Uint8Array): bigint {
+  const key = deriveAmountKey(sharedSecret);
+
+  const decrypted = new Uint8Array(8);
+  for (let i = 0; i < 8; i++) {
+    decrypted[i] = encryptedAmount[i] ^ key[i];
+  }
+
+  let amount = 0n;
+  for (let i = 7; i >= 0; i--) {
+    amount = (amount << 8n) | BigInt(decrypted[i]);
+  }
+
+  return amount;
+}
+
+// ============================================================================
+// Combined Note Data Encryption (token_id + amount)
+// ============================================================================
+
+/**
+ * Derive a 40-byte keystream for encrypting token_id(32) + amount(8).
+ * Uses two SHA-256 hashes with domain separation to get enough key material.
+ *
+ * keystream[0..32]  = sha256(sharedSecret || 0x00)  — for token_id
+ * keystream[32..40] = sha256(sharedSecret || 0x01)[0..8] — for amount
+ */
+function deriveNoteDataKeystream(sharedSecret: Uint8Array): Uint8Array {
+  const buf0 = new Uint8Array(sharedSecret.length + 1);
+  buf0.set(sharedSecret);
+  buf0[sharedSecret.length] = 0x00;
+
+  const buf1 = new Uint8Array(sharedSecret.length + 1);
+  buf1.set(sharedSecret);
+  buf1[sharedSecret.length] = 0x01;
+
+  const key0 = sha256(buf0); // 32 bytes for token_id
+  const key1 = sha256(buf1); // 32 bytes, take first 8 for amount
+
+  const keystream = new Uint8Array(40);
+  keystream.set(key0, 0);
+  keystream.set(key1.slice(0, 8), 32);
+  return keystream;
+}
+
+/**
+ * Encrypt note data: token_id(32 bytes, big-endian) || amount(8 bytes, LE)
+ *
+ * @param tokenId - Token identifier as bigint
+ * @param amount - Amount in token's native units
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns 40-byte encrypted blob
+ */
+export function encryptNoteData(
+  tokenId: bigint,
+  amount: bigint,
+  sharedSecret: Uint8Array,
+): Uint8Array {
+  const keystream = deriveNoteDataKeystream(sharedSecret);
+  const plaintext = new Uint8Array(40);
+
+  // token_id: 32 bytes big-endian
+  let t = tokenId;
+  for (let i = 31; i >= 0; i--) {
+    plaintext[i] = Number(t & 0xffn);
+    t >>= 8n;
+  }
+
+  // amount: 8 bytes little-endian
+  let a = amount;
+  for (let i = 0; i < 8; i++) {
+    plaintext[32 + i] = Number(a & 0xffn);
+    a >>= 8n;
+  }
+
+  // XOR
+  const encrypted = new Uint8Array(40);
+  for (let i = 0; i < 40; i++) {
+    encrypted[i] = plaintext[i] ^ keystream[i];
+  }
+  return encrypted;
+}
+
+/**
+ * Decrypt note data: extracts token_id and amount from 40-byte encrypted blob.
+ *
+ * @param encryptedData - 40-byte encrypted blob
+ * @param sharedSecret - 32-byte X25519 shared secret
+ * @returns { tokenId, amount }
+ */
+export function decryptNoteData(
+  encryptedData: Uint8Array,
+  sharedSecret: Uint8Array,
+): { tokenId: bigint; amount: bigint } {
+  if (encryptedData.length < 40) {
+    throw new Error(`Expected 40-byte encrypted note data, got ${encryptedData.length}`);
+  }
+
+  const keystream = deriveNoteDataKeystream(sharedSecret);
+  const plaintext = new Uint8Array(40);
+  for (let i = 0; i < 40; i++) {
+    plaintext[i] = encryptedData[i] ^ keystream[i];
+  }
+
+  // token_id: 32 bytes big-endian → bigint
+  let tokenId = 0n;
+  for (let i = 0; i < 32; i++) {
+    tokenId = (tokenId << 8n) | BigInt(plaintext[i]);
+  }
+
+  // amount: 8 bytes little-endian → bigint
+  let amount = 0n;
+  for (let i = 7; i >= 0; i--) {
+    amount = (amount << 8n) | BigInt(plaintext[32 + i]);
+  }
+
+  return { tokenId, amount };
+}