@fitzdoud/valun 0.0.0-stage → 0.3.1

package/src/basis.js

@@ -0,0 +1,243 @@
+// Basis-compatible Schnorr signatures over secp256k1, in plain JavaScript with BigInt (no dependencies).
+//
+// A port of the Python client's basis.py, which mirrors basis_core::schnorr_sign / SchnorrVerifier at Basis 3df7ed93:
+//   signature = a (33-byte compressed point k*G) || z (32 bytes, big-endian)
+//   e = blake2b256(a || message || public_key), read as a big-endian integer
+//   z = k + e*s mod n, retried until e < 2^255 and 0 < z < 2^255 (ErgoScript reads both as signed integers),
+//   verified as z*G == a + e*X.
+// Note message (80 bytes): debt_key(32) || total(8 BE) || timestamp(8 BE) || tracker_nft_id(32),
+// debt_key = blake2b256(issuer_pk || recipient_pk [|| token_id]).
+//
+// A client-side signer, so a participant's key never leaves its machine. Not constant-time (BigInt arithmetic): fine
+// for a local signer in an experiment, not for an exposed signing service.
+
+import {blake2b256} from './blake2b.js';
+import {bigIntToBytes, bytesToBigInt, concatBytes, equalBytes, hexToBytes, toBytes} from './bytes.js';
+import {SignatureError} from './errors.js';
+import {randomBytes as defaultRandomBytes} from './random.js';
+
+export const P = 2n ** 256n - 2n ** 32n - 977n;
+export const N = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141n;
+export const G = Object.freeze([
+  0x79BE667EF9DCBBAC55A06295CE870B07029BFCDB2DCE28D959F2815B16F81798n,
+  0x483ADA7726A3C4655DA4FBFC0E1108A8FD17B448A68554199C47D08FFB10D4B8n,
+]);
+export const HALF = 1n << 255n;
+
+export {blake2b256, SignatureError};
+
+const mod = (a, m = P) => {
+  const r = a % m;
+  return r < 0n ? r + m : r;
+};
+
+function powmod(b, e, m) {
+  let r = 1n;
+  b = mod(b, m);
+  while (e > 0n) {
+    if (e & 1n) r = (r * b) % m;
+    b = (b * b) % m;
+    e >>= 1n;
+  }
+  return r;
+}
+
+function invert(a, m = P) {
+  let [r0, r1] = [mod(a, m), m], [s0, s1] = [1n, 0n];
+  while (r1 !== 0n) {
+    const q = r0 / r1;
+    [r0, r1] = [r1, r0 - q * r1];
+    [s0, s1] = [s1, s0 - q * s1];
+  }
+  if (r0 !== 1n) throw new SignatureError('not invertible');
+  return mod(s0, m);
+}
+
+// ---- secp256k1 arithmetic (Jacobian coordinates; null is the point at infinity) ----
+function double(j) {
+  if (j === null) return null;
+  const [x, y, z] = j;
+  if (y === 0n) return null;
+  const yy = (y * y) % P;
+  const s = (4n * x * yy) % P;
+  const m = (3n * x * x) % P;
+  const x3 = mod(m * m - 2n * s);
+  const y3 = mod(m * (s - x3) - 8n * yy * yy);
+  return [x3, y3, (2n * y * z) % P];
+}
+
+function add(j1, j2) {
+  if (j1 === null) return j2;
+  if (j2 === null) return j1;
+  const [x1, y1, z1] = j1, [x2, y2, z2] = j2;
+  const z1z1 = (z1 * z1) % P, z2z2 = (z2 * z2) % P;
+  const u1 = (x1 * z2z2) % P, u2 = (x2 * z1z1) % P;
+  const s1 = (y1 * z2 * z2z2) % P, s2 = (y2 * z1 * z1z1) % P;
+  if (u1 === u2) return s1 === s2 ? double(j1) : null;
+  const h = mod(u2 - u1), r = mod(s2 - s1);
+  const h2 = (h * h) % P;
+  const h3 = (h * h2) % P, u1h2 = (u1 * h2) % P;
+  const x3 = mod(r * r - h3 - 2n * u1h2);
+  const y3 = mod(r * (u1h2 - x3) - s1 * h3);
+  return [x3, y3, (h * z1 * z2) % P];
+}
+
+function affine(j) {
+  if (j === null || j[2] % P === 0n) return null;
+  const zi = invert(j[2]);
+  const zi2 = (zi * zi) % P;
+  return [(j[0] * zi2) % P, (j[1] * zi2 * zi) % P];
+}
+
+function mul(k, pt) {
+  let acc = null, addend = [pt[0], pt[1], 1n];
+  while (k > 0n) {
+    if (k & 1n) acc = add(acc, addend);
+    addend = double(addend);
+    k >>= 1n;
+  }
+  return acc;   // Jacobian
+}
+
+function compress(pt) {
+  return concatBytes(Uint8Array.of(2 + Number(pt[1] & 1n)), bigIntToBytes(pt[0], 32));
+}
+
+function decompress(b) {
+  if (b.length !== 33 || (b[0] !== 2 && b[0] !== 3)) throw new SignatureError('not a compressed secp256k1 point');
+  const x = bytesToBigInt(b.subarray(1));
+  if (x >= P) throw new SignatureError('point x out of range');
+  const y2 = mod(x * x * x + 7n);
+  let y = powmod(y2, (P + 1n) / 4n, P);
+  if ((y * y) % P !== y2) throw new SignatureError('point is not on the curve');
+  if ((y & 1n) !== BigInt(b[0] & 1)) y = P - y;
+  return [x, y];
+}
+
+// ---- keys ----
+function scalarFrom(secret) {
+  const sk = toBytes(secret, 'secret key');
+  const s = sk.length === 32 ? bytesToBigInt(sk) : 0n;
+  if (!(s > 0n && s < N)) throw new SignatureError('secret key out of range');
+  return s;
+}
+
+/** A uniformly random scalar in [1, n-1] from 32-byte draws (rejection sampling; a draw is rejected with p ~ 2^-128). */
+function randomScalar(randomBytes) {
+  for (;;) {
+    const b = randomBytes(32);
+    if (!(b instanceof Uint8Array) || b.length !== 32) throw new TypeError('randomBytes(32) must return 32 bytes');
+    const k = bytesToBigInt(b);
+    if (k > 0n && k < N) return k;
+  }
+}
+
+/** A new secret key: 32 bytes, uniform in [1, n-1], from the platform CSPRNG (or the `randomBytes` given). */
+export function generateSecret(randomBytes = defaultRandomBytes) {
+  return bigIntToBytes(randomScalar(randomBytes), 32);
+}
+
+/** The 33-byte compressed public key of a 32-byte secret (Uint8Array or hex). */
+export function publicKey(secret) {
+  return compress(affine(mul(scalarFrom(secret), G)));
+}
+
+/** Throws SignatureError unless `pk` is a valid compressed secp256k1 point. */
+export function validatePublicKey(pk) {
+  decompress(toBytes(pk, 'public key'));
+}
+
+// ---- Schnorr (Basis) ----
+function challenge(a, message, pk) {
+  return blake2b256(a, message, pk);
+}
+
+/**
+ * Sign `message` (Uint8Array: the exact bytes, e.g. UTF-8 of a statement or the 80-byte note message) with `secret`.
+ * `pk`, if given, must be the secret's public key. `options.randomBytes` replaces the nonce source (tests only).
+ * Returns the 65-byte signature a || z.
+ */
+export function sign(message, secret, pk = undefined, options = {}) {
+  if (!(message instanceof Uint8Array)) throw new TypeError('message must be a Uint8Array (the exact bytes to sign)');
+  const s = scalarFrom(secret);
+  const own = compress(affine(mul(s, G)));
+  const X = pk === undefined || pk === null ? own : toBytes(pk, 'public key');
+  if (!equalBytes(X, own)) throw new SignatureError('secret does not match public key');
+  const rnd = options.randomBytes || defaultRandomBytes;
+  for (;;) {
+    const k = randomScalar(rnd);
+    const a = compress(affine(mul(k, G)));
+    const eBytes = challenge(a, message, X);
+    const e = bytesToBigInt(eBytes);
+    if (eBytes[0] >= 0x80 || e >= N) continue;           // the contract reads e as a signed integer
+    const z = (k + e * s) % N;
+    if (z === 0n || z >= HALF) continue;                 // same retry rule as basis_core / SigUtils
+    const sig = concatBytes(a, bigIntToBytes(z, 32));
+    if (!verify(sig, message, X)) continue;              // never emit a signature Basis would reject
+    return sig;
+  }
+}
+
+/** True iff `sig` (65 bytes) is a valid Basis Schnorr signature of `message` by public key `pk`. Never throws. */
+export function verify(sig, message, pk) {
+  try {
+    sig = toBytes(sig, 'signature');
+    pk = toBytes(pk, 'public key');
+    if (!(message instanceof Uint8Array)) return false;
+    if (sig.length !== 65 || (sig[0] !== 2 && sig[0] !== 3)) return false;
+    const a = sig.subarray(0, 33), zBytes = sig.subarray(33);
+    if (zBytes.every(x => x === 0) || (zBytes[0] & 0x80)) return false;
+    const xPt = decompress(pk);
+    const aPt = decompress(a);
+    const eBytes = challenge(a, message, pk);
+    const e = bytesToBigInt(eBytes);
+    if ((eBytes[0] & 0x80) || e >= N) return false;
+    const z = bytesToBigInt(zBytes);
+    if (!(z > 0n && z < N)) return false;
+    const left = affine(mul(z, G));
+    const right = affine(add([aPt[0], aPt[1], 1n], mul(e, xPt)));
+    return left !== null && right !== null && left[0] === right[0] && left[1] === right[1];
+  } catch {
+    return false;
+  }
+}
+
+/** verify() over hex inputs: false (never an exception) for anything malformed. */
+export function verifyHex(sigHex, message, pkHex) {
+  if (typeof sigHex !== 'string' || typeof pkHex !== 'string') return false;
+  if (!/^[0-9a-f]{130}$/.test(sigHex) || !/^0[23][0-9a-f]{64}$/.test(pkHex)) return false;
+  return verify(hexToBytes(sigHex), message, hexToBytes(pkHex));
+}
+
+// ---- Basis note messages ----
+const TOKEN_DENOMINATION = /^token:([0-9a-f]{64})$/;
+
+/** Basis debt key: blake2b256(issuer || recipient) for "erg", blake2b256(issuer || recipient || token_id) for "token:<id>". */
+export function debtKey(issuerPk, recipientPk, denomination = 'erg') {
+  const i = toBytes(issuerPk, 'issuer public key'), r = toBytes(recipientPk, 'recipient public key');
+  if (i.length !== 33 || r.length !== 33) throw new SignatureError('public keys must be 33 bytes');
+  if (denomination === 'erg') return blake2b256(i, r);
+  const m = typeof denomination === 'string' ? TOKEN_DENOMINATION.exec(denomination) : null;
+  if (m) return blake2b256(i, r, hexToBytes(m[1]));
+  throw new SignatureError(`unsupported denomination ${JSON.stringify(denomination)}`);
+}
+
+function u64(x, what) {
+  let v;
+  if (typeof x === 'bigint') v = x;
+  else if (typeof x === 'number' && Number.isSafeInteger(x)) v = BigInt(x);
+  else if (typeof x === 'string' && /^(0|[1-9][0-9]*)$/.test(x)) v = BigInt(x);
+  else throw new SignatureError(`bad note fields: ${what} must be an integer`);
+  if (v < 0n || v >= 1n << 64n) throw new SignatureError(`bad note fields: ${what} out of u64 range`);
+  return bigIntToBytes(v, 8);
+}
+
+/**
+ * The 80-byte Basis note message. `total` and `timestamp` (ms) are integers (number, bigint or decimal string) in
+ * [0, 2^64); `trackerNftId` is 32 bytes (or 64 hex).
+ */
+export function noteMessage(issuerPk, recipientPk, total, timestamp, trackerNftId, denomination = 'erg') {
+  const nft = toBytes(trackerNftId, 'tracker_nft_id');
+  if (nft.length !== 32) throw new SignatureError('bad note fields: tracker_nft_id must be 32 bytes');
+  return concatBytes(debtKey(issuerPk, recipientPk, denomination), u64(total, 'total'), u64(timestamp, 'timestamp'), nft);
+}

package/src/blake2b.js

@@ -0,0 +1,137 @@
+// BLAKE2b (RFC 7693) in plain JavaScript: digest length 1..64 bytes set in the parameter block, optional key (0..64
+// bytes). 64-bit words are held as (low, high) pairs of 32-bit integers in Uint32Arrays, as in the RFC's reference
+// structure. BLAKE2b-256 here is BLAKE2b with digest length 32, which is NOT the first 32 bytes of BLAKE2b-512.
+
+// Initialisation vector, as (low, high) 32-bit halves of the eight 64-bit words.
+const IV = new Uint32Array([
+  0xf3bcc908, 0x6a09e667, 0x84caa73b, 0xbb67ae85, 0xfe94f82b, 0x3c6ef372, 0x5f1d36f1, 0xa54ff53a,
+  0xade682d1, 0x510e527f, 0x2b3e6c1f, 0x9b05688c, 0xfb41bd6b, 0x1f83d9ab, 0x137e2179, 0x5be0cd19,
+]);
+
+const SIGMA = [
+  [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15],
+  [14, 10, 4, 8, 9, 15, 13, 6, 1, 12, 0, 2, 11, 7, 5, 3],
+  [11, 8, 12, 0, 5, 2, 15, 13, 10, 14, 3, 6, 7, 1, 9, 4],
+  [7, 9, 3, 1, 13, 12, 11, 14, 2, 6, 5, 10, 4, 0, 15, 8],
+  [9, 0, 5, 7, 2, 4, 10, 15, 14, 1, 11, 12, 6, 8, 3, 13],
+  [2, 12, 6, 10, 0, 11, 8, 3, 4, 13, 7, 5, 15, 14, 1, 9],
+  [12, 5, 1, 15, 14, 13, 4, 10, 0, 7, 6, 3, 9, 2, 8, 11],
+  [13, 11, 7, 14, 12, 1, 3, 9, 5, 0, 15, 4, 8, 6, 2, 10],
+  [6, 15, 14, 9, 11, 3, 0, 8, 12, 2, 13, 7, 1, 4, 10, 5],
+  [10, 2, 8, 4, 7, 6, 1, 5, 15, 11, 9, 14, 3, 12, 13, 0],
+];
+
+// v[a] += v[b]   (64-bit, word indices are pair offsets)
+function add64(v, a, b) {
+  const lo = v[a] + v[b];
+  v[a + 1] = v[a + 1] + v[b + 1] + (lo >= 0x100000000 ? 1 : 0);
+  v[a] = lo;
+}
+
+// v[a] += (lo, hi)
+function add64c(v, a, lo, hi) {
+  const l = v[a] + lo;
+  v[a + 1] = v[a + 1] + hi + (l >= 0x100000000 ? 1 : 0);
+  v[a] = l;
+}
+
+function mix(v, m, a, b, c, d, x, y) {
+  add64(v, a, b);
+  add64c(v, a, m[x], m[x + 1]);
+  // v[d] = (v[d] ^ v[a]) >>> 32
+  let lo = v[d] ^ v[a], hi = v[d + 1] ^ v[a + 1];
+  v[d] = hi; v[d + 1] = lo;
+  add64(v, c, d);
+  // v[b] = (v[b] ^ v[c]) >>> 24
+  lo = v[b] ^ v[c]; hi = v[b + 1] ^ v[c + 1];
+  v[b] = (lo >>> 24) | (hi << 8); v[b + 1] = (hi >>> 24) | (lo << 8);
+  add64(v, a, b);
+  add64c(v, a, m[y], m[y + 1]);
+  // v[d] = (v[d] ^ v[a]) >>> 16
+  lo = v[d] ^ v[a]; hi = v[d + 1] ^ v[a + 1];
+  v[d] = (lo >>> 16) | (hi << 16); v[d + 1] = (hi >>> 16) | (lo << 16);
+  add64(v, c, d);
+  // v[b] = (v[b] ^ v[c]) >>> 63  (= rotate left by 1)
+  lo = v[b] ^ v[c]; hi = v[b + 1] ^ v[c + 1];
+  v[b] = (hi >>> 31) | (lo << 1); v[b + 1] = (lo >>> 31) | (hi << 1);
+}
+
+function compress(ctx, last) {
+  const {h, v, m, b} = ctx;
+  for (let i = 0; i < 16; i++) { v[i] = h[i]; v[i + 16] = IV[i]; }
+  // t is a byte counter < 2^53 (the 128-bit counter's high 64 bits stay 0)
+  v[24] ^= ctx.t >>> 0;
+  v[25] ^= Math.floor(ctx.t / 0x100000000);
+  if (last) { v[28] = ~v[28]; v[29] = ~v[29]; }
+  for (let i = 0; i < 32; i++) m[i] = b[4 * i] | (b[4 * i + 1] << 8) | (b[4 * i + 2] << 16) | (b[4 * i + 3] << 24);
+  for (let r = 0; r < 12; r++) {
+    const s = SIGMA[r % 10];
+    mix(v, m, 0, 8, 16, 24, s[0] * 2, s[1] * 2);
+    mix(v, m, 2, 10, 18, 26, s[2] * 2, s[3] * 2);
+    mix(v, m, 4, 12, 20, 28, s[4] * 2, s[5] * 2);
+    mix(v, m, 6, 14, 22, 30, s[6] * 2, s[7] * 2);
+    mix(v, m, 0, 10, 20, 30, s[8] * 2, s[9] * 2);
+    mix(v, m, 2, 12, 22, 24, s[10] * 2, s[11] * 2);
+    mix(v, m, 4, 14, 16, 26, s[12] * 2, s[13] * 2);
+    mix(v, m, 6, 8, 18, 28, s[14] * 2, s[15] * 2);
+  }
+  for (let i = 0; i < 16; i++) h[i] ^= v[i] ^ v[i + 16];
+}
+
+/** Incremental BLAKE2b. `outLen` 1..64, optional `key` (Uint8Array, 0..64 bytes). */
+export class Blake2b {
+  constructor(outLen = 64, key = undefined) {
+    const keyLen = key ? key.length : 0;
+    if (!Number.isInteger(outLen) || outLen < 1 || outLen > 64) throw new RangeError('BLAKE2b digest length must be 1..64');
+    if (keyLen > 64) throw new RangeError('BLAKE2b key must be at most 64 bytes');
+    this.outLen = outLen;
+    this.h = new Uint32Array(IV);
+    this.h[0] ^= 0x01010000 ^ (keyLen << 8) ^ outLen;   // parameter block: digest length, key length, fanout 1, depth 1
+    this.v = new Uint32Array(32);
+    this.m = new Uint32Array(32);
+    this.b = new Uint8Array(128);
+    this.c = 0;
+    this.t = 0;
+    this.done = false;
+    if (keyLen > 0) {
+      this.update(key);
+      this.c = 128;   // the key block is always a full (zero-padded) block
+    }
+  }
+
+  update(data) {
+    if (this.done) throw new Error('BLAKE2b: update after digest');
+    for (let i = 0; i < data.length; i++) {
+      if (this.c === 128) {
+        this.t += 128;
+        compress(this, false);
+        this.c = 0;
+      }
+      this.b[this.c++] = data[i];
+    }
+    return this;
+  }
+
+  digest() {
+    if (this.done) throw new Error('BLAKE2b: digest called twice');
+    this.done = true;
+    this.t += this.c;
+    this.b.fill(0, this.c);
+    compress(this, true);
+    const out = new Uint8Array(this.outLen);
+    for (let i = 0; i < this.outLen; i++) out[i] = this.h[i >> 2] >>> (8 * (i & 3));
+    return out;
+  }
+}
+
+/** One-shot BLAKE2b of `data` with digest length `outLen` (default 64) and optional key. */
+export function blake2b(data, outLen = 64, key = undefined) {
+  return new Blake2b(outLen, key).update(data).digest();
+}
+
+/** BLAKE2b-256 (digest length 32, unkeyed) over the concatenation of the byte arrays given. */
+export function blake2b256(...parts) {
+  const h = new Blake2b(32);
+  for (const p of parts) h.update(p);
+  return h.digest();
+}

package/src/bytes.js

@@ -0,0 +1,60 @@
+// Byte helpers shared by every module. No dependencies; works in Node, Deno, Bun and browsers.
+
+const HEX = Array.from({length: 256}, (_, i) => i.toString(16).padStart(2, '0'));
+const ENCODER = new TextEncoder();
+
+/** Lowercase hex of a byte array. */
+export function bytesToHex(bytes) {
+  let s = '';
+  for (let i = 0; i < bytes.length; i++) s += HEX[bytes[i]];
+  return s;
+}
+
+/** Bytes of an even-length hex string (upper or lower case, nothing else). Throws TypeError otherwise. */
+export function hexToBytes(hex) {
+  if (typeof hex !== 'string' || hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) {
+    throw new TypeError('expected an even-length hex string');
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = parseInt(hex.substr(i * 2, 2), 16);
+  return out;
+}
+
+/** UTF-8 bytes of a string (a lone surrogate becomes U+FFFD, exactly as Node's Buffer does on the server). */
+export function utf8(text) {
+  return ENCODER.encode(text);
+}
+
+export function concatBytes(...parts) {
+  let n = 0;
+  for (const p of parts) n += p.length;
+  const out = new Uint8Array(n);
+  let o = 0;
+  for (const p of parts) { out.set(p, o); o += p.length; }
+  return out;
+}
+
+export function equalBytes(a, b) {
+  if (a.length !== b.length) return false;
+  let d = 0;
+  for (let i = 0; i < a.length; i++) d |= a[i] ^ b[i];
+  return d === 0;
+}
+
+/** Big-endian unsigned integer of a byte array. */
+export function bytesToBigInt(bytes) {
+  return bytes.length === 0 ? 0n : BigInt('0x' + bytesToHex(bytes));
+}
+
+/** `len` bytes, big-endian, of a non-negative BigInt that fits. */
+export function bigIntToBytes(x, len) {
+  if (typeof x !== 'bigint' || x < 0n || x >= 1n << BigInt(8 * len)) throw new RangeError(`value does not fit in ${len} bytes`);
+  return hexToBytes(x.toString(16).padStart(len * 2, '0'));
+}
+
+/** Accepts a Uint8Array or a hex string and returns bytes (hex strings are decoded). */
+export function toBytes(x, what = 'value') {
+  if (x instanceof Uint8Array) return x;
+  if (typeof x === 'string') return hexToBytes(x);
+  throw new TypeError(`${what} must be a Uint8Array or a hex string`);
+}