@metoncash/sdk-v1 0.2.0 → 0.2.1

package/README.md

@@ -15,7 +15,7 @@ npm install snarkjs
 ## Usage
 
 ```ts
-import { MetonSDK, deriveViewKey, randomScalar } from "meton-cash/sdk-v1";
+import { MetonSDK, deriveViewKey, randomScalar } from "@metoncash/sdk-v1";
 
 // Point at a build directory laid out as <dir>/<c>/<c>_js/<c>.wasm + <dir>/<c>/<c>_final.zkey
 const sdk = MetonSDK.fromBuildDir("./build");
@@ -45,6 +45,28 @@ const t = await sdk.transfer({
 });
 // → { proof, publicSignals, newSenderCommitment, amountCommitment, note,
 //     remainder, senderNewBlind, amountBlind, ephScalar }
+//   note = { Rx, Ry, enc_amount, enc_blind } is the PUBLIC on-chain payload;
+//   ephScalar (and the blinds) are secrets — persist them, never publish them.
+```
+
+Inputs are validated before any proving (64-bit amounts, `amount ≤ balance`, 252-bit
+blinds, `accountId` in `[0, 2²⁵⁶)` — reduced mod `r` like the contract does — receiver
+key on-curve and in the prime-order subgroup, …) and rejected with a `RangeError` naming
+the field.
+
+`accountId` is the wallet contract's address hash: `accountIdOf(await minter.getWalletAddress(owner))`.
+
+## Registering a wallet
+
+```ts
+import { generateWalletKeys, registerWitness } from "@metoncash/sdk-v1";
+
+const keys = generateWalletKeys();
+await minter.sendRegister(sender, toNano("0.1"), {
+  queryId: 0n,
+  publicViewKey: { $: "Point", x: keys.viewPk[0], y: keys.viewPk[1] },
+  witness: registerWitness(keys.viewPk),   // proves the key is in the prime-order subgroup
+});
 ```
 
 `proof` + `publicSignals` are the snarkjs Groth16 outputs. Every result also returns the **secrets you must persist** (blindings,
@@ -53,7 +75,7 @@ note) to keep your local opening of the commitment spendable.
 ## Receiving / auditing
 
 ```ts
-import { viewNote } from "meton-cash/sdk-v1";
+import { viewNote } from "@metoncash/sdk-v1";
 
 // recipient (or a granted auditor) holding sk_view:
 const seen = viewNote(recv.skView, note, amountCommitment[0], amountCommitment[1]);
@@ -63,14 +85,15 @@ const seen = viewNote(recv.skView, note, amountCommitment[0], amountCommitment[1
 ## What's exported
 
 - **Prover:** `MetonSDK` (`deposit`, `withdraw`, `transfer`, `fromBuildDir`).
-- **Keys / notes:** `deriveViewKey`, `derivePub`, `encryptNote`, `decryptNote`, `viewNote`.
-- **Curve / commitments:** `commit`, `add`, `mul`, `mod`, `randomScalar`, `Point`, `Gx/Gy/Hx/Hy`, `r`, `d`, `L`.
+- **Keys / notes:** `generateWalletKeys`, `deriveViewKey`, `derivePub`, `registerWitness`, `accountIdOf`, `encryptNote`, `decryptNote`, `viewNote`, `sealNote` (returns `{ note, ephScalar }`), `openNote`.
+- **Curve / commitments:** `commit`, `add`, `mul`, `mod`, `randomScalar`, `isOnCurve`, `isInPrimeSubgroup`, `cofactorWitness`, `Point`, `Gx/Gy/Hx/Hy`, `r`, `d`, `L`.
 - **Hash:** `mimc5perm`. **Constants:** `CONSTANTS`.
 
 ## Notes
 
 - **Defaults:** `blinding`, `newBlind`, `senderNewBlind`, `ephScalar` default to fresh
-  randomness; `amountBlind` defaults to `oldBlind − newBlind (mod L)` (the homomorphic
-  relation the contract checks). The **ephemeral scalar must be fresh per transfer** —
-  reuse leaks amounts.
-- Proving is CPU-heavy (transfer ≈ 30k constraints); run it off the UI thread / in a worker.
+  randomness; `amountBlind` defaults to `oldBlind − newBlind (mod L)` so that
+  `old == new ⊕ amount` also holds as points (handy for local checks; the contract does
+  not require it — value conservation is proven inside the circuit). The **ephemeral
+  scalar must be fresh per transfer** — reuse leaks amounts.
+- Proving is CPU-heavy (transfer ≈ 40k constraints); run it off the UI thread / in a worker.

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { CONSTANTS } from "./constants";
-export { Point, r, d, L, Gx, Gy, Hx, Hy, mod, modpow, modinv, add, mul, commit, derivePub, randomScalar, } from "./jubjub";
+export { Point, r, d, L, Gx, Gy, Hx, Hy, mod, modpow, modinv, add, mul, commit, derivePub, randomScalar, isOnCurve, isIdentity, isInPrimeSubgroup, cofactorWitness, } from "./jubjub";
 export { mimc5perm } from "./mimc";
 export { Note, deriveViewKey, encryptNote, decryptNote, viewNote } from "./note";
 export { MetonSDK, CircuitArtifacts, MetonConfig, Proof, DepositArgs, WithdrawArgs, TransferArgs, DepositResult, WithdrawResult, TransferResult, } from "./prover";
-export { WalletKeys, generateWalletKeys, walletKeysFromSpend, viewKeyFromSpend, SealNoteArgs, SealedNote, sealNote, openNote, } from "./utils";
+export { WalletKeys, generateWalletKeys, walletKeysFromSpend, viewKeyFromSpend, SealNoteArgs, SealedNote, sealNote, openNote, accountIdOf, registerWitness, } from "./utils";
 export { Wallet, Minter, Factory } from "./wrappers";
+export type { SubgroupWitness, CellRef, Register } from "./wrappers/Minter.gen";

package/dist/index.js

@@ -1,6 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Factory = exports.Minter = exports.Wallet = exports.openNote = exports.sealNote = exports.viewKeyFromSpend = exports.walletKeysFromSpend = exports.generateWalletKeys = exports.MetonSDK = exports.viewNote = exports.decryptNote = exports.encryptNote = exports.deriveViewKey = exports.mimc5perm = exports.randomScalar = exports.derivePub = exports.commit = exports.mul = exports.add = exports.modinv = exports.modpow = exports.mod = exports.Hy = exports.Hx = exports.Gy = exports.Gx = exports.L = exports.d = exports.r = exports.CONSTANTS = void 0;
+exports.Factory = exports.Minter = exports.Wallet = exports.registerWitness = exports.accountIdOf = exports.openNote = exports.sealNote = exports.viewKeyFromSpend = exports.walletKeysFromSpend = exports.generateWalletKeys = exports.MetonSDK = exports.viewNote = exports.decryptNote = exports.encryptNote = exports.deriveViewKey = exports.mimc5perm = exports.cofactorWitness = exports.isInPrimeSubgroup = exports.isIdentity = exports.isOnCurve = exports.randomScalar = exports.derivePub = exports.commit = exports.mul = exports.add = exports.modinv = exports.modpow = exports.mod = exports.Hy = exports.Hx = exports.Gy = exports.Gx = exports.L = exports.d = exports.r = exports.CONSTANTS = void 0;
+// index.ts - public surface of @metoncash/sdk-v1.
+//
+//   constants   generated curve / MiMC parameters shared with circuits and contracts
+//   jubjub      field + curve arithmetic, Pedersen commitments, subgroup checks
+//   mimc        the MiMC-5 permutation used for note masks and view-key derivation
+//   note        ECDH note encryption / decryption and view-key derivation
+//   prover      MetonSDK - Groth16 proof building for deposit / withdraw / transfer
+//   utils       wallet keys, Register witness, sealNote/openNote, accountIdOf
+//   wrappers    generated contract wrappers (Wallet, Minter, Factory)
+//
+// Typical flow: generateWalletKeys -> Minter.Register(viewPk, registerWitness(viewPk))
+// -> accountIdOf(walletAddress) -> MetonSDK.deposit/transfer/withdraw -> the receiver
+// opens incoming notes with viewNote(viewSk, note, amountCommitment).
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "CONSTANTS", { enumerable: true, get: function () { return constants_1.CONSTANTS; } });
 var jubjub_1 = require("./jubjub");
@@ -19,6 +32,10 @@ Object.defineProperty(exports, "mul", { enumerable: true, get: function () { ret
 Object.defineProperty(exports, "commit", { enumerable: true, get: function () { return jubjub_1.commit; } });
 Object.defineProperty(exports, "derivePub", { enumerable: true, get: function () { return jubjub_1.derivePub; } });
 Object.defineProperty(exports, "randomScalar", { enumerable: true, get: function () { return jubjub_1.randomScalar; } });
+Object.defineProperty(exports, "isOnCurve", { enumerable: true, get: function () { return jubjub_1.isOnCurve; } });
+Object.defineProperty(exports, "isIdentity", { enumerable: true, get: function () { return jubjub_1.isIdentity; } });
+Object.defineProperty(exports, "isInPrimeSubgroup", { enumerable: true, get: function () { return jubjub_1.isInPrimeSubgroup; } });
+Object.defineProperty(exports, "cofactorWitness", { enumerable: true, get: function () { return jubjub_1.cofactorWitness; } });
 var mimc_1 = require("./mimc");
 Object.defineProperty(exports, "mimc5perm", { enumerable: true, get: function () { return mimc_1.mimc5perm; } });
 var note_1 = require("./note");
@@ -34,7 +51,9 @@ Object.defineProperty(exports, "walletKeysFromSpend", { enumerable: true, get: f
 Object.defineProperty(exports, "viewKeyFromSpend", { enumerable: true, get: function () { return utils_1.viewKeyFromSpend; } });
 Object.defineProperty(exports, "sealNote", { enumerable: true, get: function () { return utils_1.sealNote; } });
 Object.defineProperty(exports, "openNote", { enumerable: true, get: function () { return utils_1.openNote; } });
-// Contract wrappers — deploy/init Wallet, Minter, Factory through the SDK.
+Object.defineProperty(exports, "accountIdOf", { enumerable: true, get: function () { return utils_1.accountIdOf; } });
+Object.defineProperty(exports, "registerWitness", { enumerable: true, get: function () { return utils_1.registerWitness; } });
+// Contract wrappers - deploy/init Wallet, Minter, Factory through the SDK.
 var wrappers_1 = require("./wrappers");
 Object.defineProperty(exports, "Wallet", { enumerable: true, get: function () { return wrappers_1.Wallet; } });
 Object.defineProperty(exports, "Minter", { enumerable: true, get: function () { return wrappers_1.Minter; } });

package/dist/jubjub.d.ts

@@ -1,25 +1,129 @@
 /**
- * jubjub.ts — Jubjub twisted-Edwards curve arithmetic (a = -1) over the
+ * jubjub.ts - Jubjub twisted-Edwards curve arithmetic (a = -1) over the
  * BLS12-381 scalar field. Mirrors circuits/lib for off-chain input building.
+ *
+ * Curve: -x^2 + y^2 = 1 + d*x^2*y^2 over F_r. The group has order 8*L (cofactor
+ * 8, prime L); G and H generate the order-L subgroup and are the same points the
+ * circuits (generated_constants.circom) and the contracts (twEdwards.tolk) use.
+ *
+ * Everything here is plain bigint arithmetic and NOT constant-time. It is
+ * intended for a client that already holds the secrets it operates on; do not
+ * run it in a context where timing is observable by an adversary.
  */
+/** An affine Jubjub point [x, y]; the identity is [0, 1]. */
 export type Point = [bigint, bigint];
+/** The BLS12-381 scalar field modulus r (the coordinate field of Jubjub). */
 export declare const r: bigint;
+/** Twisted-Edwards curve coefficient d (a is fixed to -1). */
 export declare const d: bigint;
+/** Prime order of the Jubjub subgroup generated by G and H (252 bits). */
 export declare const L: bigint;
+/** x of the value generator G (Pedersen: value*G + blinding*H). */
 export declare const Gx: bigint;
+/** y of the value generator G. */
 export declare const Gy: bigint;
+/** x of the blinding generator H (nothing-up-my-sleeve, independent of G). */
 export declare const Hx: bigint;
+/** y of the blinding generator H. */
 export declare const Hy: bigint;
+/**
+ * Least non-negative residue of `a` modulo `m` (default: the field modulus r).
+ * Unlike `%`, the result is never negative.
+ */
 export declare const mod: (a: bigint, m?: bigint) => bigint;
+/**
+ * Modular exponentiation `base^exp mod m` by square-and-multiply.
+ * @param base any integer (reduced mod m first)
+ * @param exp non-negative exponent
+ * @param m modulus, default r
+ */
 export declare function modpow(base: bigint, exp: bigint, m?: bigint): bigint;
+/**
+ * Modular inverse by Fermat: `a^(m-2) mod m`. Only valid for PRIME `m` (r or L)
+ * and `a != 0 mod m`; for a == 0 it silently returns 0.
+ */
 export declare const modinv: (a: bigint, m?: bigint) => bigint;
-/** Complete twisted-Edwards addition (a = -1). */
+/**
+ * Complete twisted-Edwards addition (a = -1): (x1, y1) (+) (x2, y2).
+ * The formula is complete on Jubjub (d is a non-square), so it is correct for
+ * every pair of curve points, including doubling and adding the identity;
+ * the denominators are never zero. Coordinates need not be reduced.
+ * @returns the sum, reduced mod r
+ */
 export declare function add(x1: bigint, y1: bigint, x2: bigint, y2: bigint): Point;
-/** Scalar multiplication: out = scalar · (x, y). */
+/**
+ * Scalar multiplication: out = s * (x, y) by double-and-add.
+ *
+ * `s` is reduced mod L first, so the result is only meaningful for points of the
+ * order-L subgroup (for a torsion point, [s]P and [s mod L]P differ). Two
+ * consequences: [L]*P == identity always holds here and CANNOT be used as a
+ * subgroup test (see isInPrimeSubgroup), and negative or over-sized scalars
+ * are accepted. Not constant-time.
+ */
 export declare function mul(x: bigint, y: bigint, s: bigint): Point;
-/** Pedersen commitment: value·G + blinding·H. */
+/**
+ * Pedersen commitment: value*G (+) blinding*H.
+ *
+ * Matches PedersenCommit in circuits/lib/pedersen.circom. Homomorphic:
+ * commit(a, b1) (+) commit(c, b2) == commit(a + c, b1 + b2 mod L), which is what
+ * lets a client re-check old == new (+) amount after a transfer.
+ * @param value token amount; the circuits bound it to 64 bits, this helper does not
+ * @param blinding blinding factor; effectively taken mod L
+ */
 export declare function commit(value: bigint, blinding: bigint): Point;
-/** Public key for a secret scalar: pk = sk · G. */
+/**
+ * Public key for a secret scalar: pk = sk * G. Always a subgroup point; it is
+ * the identity iff sk == 0 mod L (deriveViewKey / randomScalar never yield that).
+ */
 export declare function derivePub(sk: bigint): Point;
-/** Uniform random scalar in [1, 2^maxBits) reduced into the subgroup. */
+/**
+ * Uniform random scalar in [1, L) (L is 252 bits, so it also fits `maxBits` >= 252).
+ * 64 random bytes are reduced mod L: with 512 input bits the modulo bias is
+ * < 2^-260, whereas reducing 256 bits mod the 252-bit L skews residues by ~6%.
+ *
+ * Uses crypto.randomBytes (CSPRNG). This is the source for every secret the SDK
+ * generates: spend keys, blinding factors and the per-note ephemeral scalar k.
+ * @param maxBits if < 252 the result is truncated to its low `maxBits` bits
+ *   (result in [1, 2^maxBits)); >= 252 is a no-op since L < 2^252
+ * @returns a scalar that is never 0 (0 is mapped to 1)
+ */
 export declare function randomScalar(maxBits?: number): bigint;
+/**
+ * Twisted-Edwards membership: -x^2 + y^2 == 1 + d*x^2*y^2 (coordinates reduced
+ * mod r first). On-curve alone says nothing about the subgroup: Jubjub has
+ * cofactor 8, so use isInPrimeSubgroup for anything that will be multiplied by
+ * a secret scalar.
+ */
+export declare function isOnCurve(x: bigint, y: bigint): boolean;
+/** True iff (x, y) is the group identity (0, 1), after reduction mod r. */
+export declare const isIdentity: (x: bigint, y: bigint) => boolean;
+/**
+ * Cofactor witness for a prime-order-subgroup point P: Q = [8^-1 mod L]*P, [2]Q, [4]Q.
+ * The contract (Register) and the circuit (transfer) verify [8]*Q == P instead of
+ * running a 252-step [L]*P ladder. Only meaningful for a subgroup point - for any
+ * other on-curve point [8]*Q != P (see isInPrimeSubgroup).
+ *
+ * The verifiers check q on-curve, q2 == q (+) q, q4 == q2 (+) q2 and
+ * P == q4 (+) q4; the Minter uses verifySum (division-free), the circuit
+ * AssertInSubgroup. Since the Edwards law is complete each sum is unique, so
+ * the chain pins [8]Q. Neither verifier re-derives Q, it must be supplied.
+ * @param x,y the point P; NOT validated here (callers validate first)
+ * @returns q (the Register/transfer witness) plus its doublings q2, q4
+ */
+export declare function cofactorWitness(x: bigint, y: bigint): {
+    q: Point;
+    q2: Point;
+    q4: Point;
+};
+/**
+ * True iff (x, y) is on-curve AND in the prime-order subgroup. Jubjub has cofactor 8:
+ * the group is Z/8 x Z/L, so [8]*(any curve point) lies in the order-L subgroup and
+ * [8]*([8^-1 mod L]*P) == P holds exactly when P has no torsion component.
+ * (mul() reduces scalars mod L, so [L]*P == O cannot be used as the test.)
+ *
+ * The identity IS a subgroup point and passes; callers that need a non-trivial
+ * key (decryptNote, registerWitness, the transfer prover) check isIdentity too.
+ * Coordinates are reduced mod r, so non-canonical inputs (x + r) also pass;
+ * callers that store or compare points check canonical range separately.
+ */
+export declare function isInPrimeSubgroup(x: bigint, y: bigint): boolean;

package/dist/jubjub.js

@@ -1,7 +1,15 @@
 "use strict";
 /**
- * jubjub.ts — Jubjub twisted-Edwards curve arithmetic (a = -1) over the
+ * jubjub.ts - Jubjub twisted-Edwards curve arithmetic (a = -1) over the
  * BLS12-381 scalar field. Mirrors circuits/lib for off-chain input building.
+ *
+ * Curve: -x^2 + y^2 = 1 + d*x^2*y^2 over F_r. The group has order 8*L (cofactor
+ * 8, prime L); G and H generate the order-L subgroup and are the same points the
+ * circuits (generated_constants.circom) and the contracts (twEdwards.tolk) use.
+ *
+ * Everything here is plain bigint arithmetic and NOT constant-time. It is
+ * intended for a client that already holds the secrets it operates on; do not
+ * run it in a context where timing is observable by an adversary.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -37,24 +45,44 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.modinv = exports.mod = exports.Hy = exports.Hx = exports.Gy = exports.Gx = exports.L = exports.d = exports.r = void 0;
+exports.isIdentity = exports.modinv = exports.mod = exports.Hy = exports.Hx = exports.Gy = exports.Gx = exports.L = exports.d = exports.r = void 0;
 exports.modpow = modpow;
 exports.add = add;
 exports.mul = mul;
 exports.commit = commit;
 exports.derivePub = derivePub;
 exports.randomScalar = randomScalar;
+exports.isOnCurve = isOnCurve;
+exports.cofactorWitness = cofactorWitness;
+exports.isInPrimeSubgroup = isInPrimeSubgroup;
 const crypto = __importStar(require("crypto"));
 const constants_1 = require("./constants");
+/** The BLS12-381 scalar field modulus r (the coordinate field of Jubjub). */
 exports.r = BigInt(constants_1.CONSTANTS.FIELD_ORDER);
+/** Twisted-Edwards curve coefficient d (a is fixed to -1). */
 exports.d = BigInt(constants_1.CONSTANTS.JUBJUB_D);
+/** Prime order of the Jubjub subgroup generated by G and H (252 bits). */
 exports.L = BigInt(constants_1.CONSTANTS.JUBJUB_L);
+/** x of the value generator G (Pedersen: value*G + blinding*H). */
 exports.Gx = BigInt(constants_1.CONSTANTS.GEN_Gx);
+/** y of the value generator G. */
 exports.Gy = BigInt(constants_1.CONSTANTS.GEN_Gy);
+/** x of the blinding generator H (nothing-up-my-sleeve, independent of G). */
 exports.Hx = BigInt(constants_1.CONSTANTS.GEN_Hx);
+/** y of the blinding generator H. */
 exports.Hy = BigInt(constants_1.CONSTANTS.GEN_Hy);
+/**
+ * Least non-negative residue of `a` modulo `m` (default: the field modulus r).
+ * Unlike `%`, the result is never negative.
+ */
 const mod = (a, m = exports.r) => ((a % m) + m) % m;
 exports.mod = mod;
+/**
+ * Modular exponentiation `base^exp mod m` by square-and-multiply.
+ * @param base any integer (reduced mod m first)
+ * @param exp non-negative exponent
+ * @param m modulus, default r
+ */
 function modpow(base, exp, m = exports.r) {
     base = (0, exports.mod)(base, m);
     let result = 1n;
@@ -66,9 +94,19 @@ function modpow(base, exp, m = exports.r) {
     }
     return result;
 }
+/**
+ * Modular inverse by Fermat: `a^(m-2) mod m`. Only valid for PRIME `m` (r or L)
+ * and `a != 0 mod m`; for a == 0 it silently returns 0.
+ */
 const modinv = (a, m = exports.r) => modpow((0, exports.mod)(a, m), m - 2n, m);
 exports.modinv = modinv;
-/** Complete twisted-Edwards addition (a = -1). */
+/**
+ * Complete twisted-Edwards addition (a = -1): (x1, y1) (+) (x2, y2).
+ * The formula is complete on Jubjub (d is a non-square), so it is correct for
+ * every pair of curve points, including doubling and adding the identity;
+ * the denominators are never zero. Coordinates need not be reduced.
+ * @returns the sum, reduced mod r
+ */
 function add(x1, y1, x2, y2) {
     const x1x2 = (0, exports.mod)(x1 * x2);
     const y1y2 = (0, exports.mod)(y1 * y2);
@@ -81,7 +119,15 @@ function add(x1, y1, x2, y2) {
     const yden = (0, exports.mod)(1n + exports.r - dx);
     return [(0, exports.mod)(xnum * (0, exports.modinv)(xden)), (0, exports.mod)(ynum * (0, exports.modinv)(yden))];
 }
-/** Scalar multiplication: out = scalar · (x, y). */
+/**
+ * Scalar multiplication: out = s * (x, y) by double-and-add.
+ *
+ * `s` is reduced mod L first, so the result is only meaningful for points of the
+ * order-L subgroup (for a torsion point, [s]P and [s mod L]P differ). Two
+ * consequences: [L]*P == identity always holds here and CANNOT be used as a
+ * subgroup test (see isInPrimeSubgroup), and negative or over-sized scalars
+ * are accepted. Not constant-time.
+ */
 function mul(x, y, s) {
     s = (0, exports.mod)(s, exports.L);
     let rx = 0n;
@@ -96,21 +142,42 @@ function mul(x, y, s) {
     }
     return [rx, ry];
 }
-/** Pedersen commitment: value·G + blinding·H. */
+/**
+ * Pedersen commitment: value*G (+) blinding*H.
+ *
+ * Matches PedersenCommit in circuits/lib/pedersen.circom. Homomorphic:
+ * commit(a, b1) (+) commit(c, b2) == commit(a + c, b1 + b2 mod L), which is what
+ * lets a client re-check old == new (+) amount after a transfer.
+ * @param value token amount; the circuits bound it to 64 bits, this helper does not
+ * @param blinding blinding factor; effectively taken mod L
+ */
 function commit(value, blinding) {
     const [ax, ay] = mul(exports.Gx, exports.Gy, value);
     const [bx, by] = mul(exports.Hx, exports.Hy, blinding);
     return add(ax, ay, bx, by);
 }
-/** Public key for a secret scalar: pk = sk · G. */
+/**
+ * Public key for a secret scalar: pk = sk * G. Always a subgroup point; it is
+ * the identity iff sk == 0 mod L (deriveViewKey / randomScalar never yield that).
+ */
 function derivePub(sk) {
     return mul(exports.Gx, exports.Gy, sk);
 }
-/** Uniform random scalar in [1, 2^maxBits) reduced into the subgroup. */
+/**
+ * Uniform random scalar in [1, L) (L is 252 bits, so it also fits `maxBits` >= 252).
+ * 64 random bytes are reduced mod L: with 512 input bits the modulo bias is
+ * < 2^-260, whereas reducing 256 bits mod the 252-bit L skews residues by ~6%.
+ *
+ * Uses crypto.randomBytes (CSPRNG). This is the source for every secret the SDK
+ * generates: spend keys, blinding factors and the per-note ephemeral scalar k.
+ * @param maxBits if < 252 the result is truncated to its low `maxBits` bits
+ *   (result in [1, 2^maxBits)); >= 252 is a no-op since L < 2^252
+ * @returns a scalar that is never 0 (0 is mapped to 1)
+ */
 function randomScalar(maxBits = 252) {
-    const bytes = crypto.randomBytes(32);
+    const bytes = crypto.randomBytes(64);
     let s = 0n;
-    for (let i = 0; i < 32; i++)
+    for (let i = 0; i < 64; i++)
         s = (s << 8n) | BigInt(bytes[i]);
     s = (0, exports.mod)(s, exports.L);
     const mask = (1n << BigInt(maxBits)) - 1n;
@@ -119,3 +186,58 @@ function randomScalar(maxBits = 252) {
         s = 1n;
     return s;
 }
+/**
+ * Twisted-Edwards membership: -x^2 + y^2 == 1 + d*x^2*y^2 (coordinates reduced
+ * mod r first). On-curve alone says nothing about the subgroup: Jubjub has
+ * cofactor 8, so use isInPrimeSubgroup for anything that will be multiplied by
+ * a secret scalar.
+ */
+function isOnCurve(x, y) {
+    x = (0, exports.mod)(x);
+    y = (0, exports.mod)(y);
+    const x2 = (0, exports.mod)(x * x);
+    const y2 = (0, exports.mod)(y * y);
+    return (0, exports.mod)(y2 - x2 - (0, exports.mod)(exports.d * (0, exports.mod)(x2 * y2))) === 1n;
+}
+/** True iff (x, y) is the group identity (0, 1), after reduction mod r. */
+const isIdentity = (x, y) => (0, exports.mod)(x) === 0n && (0, exports.mod)(y) === 1n;
+exports.isIdentity = isIdentity;
+// 8^-1 mod L: multiplying a subgroup point by it "undoes" the cofactor.
+const INV8 = (0, exports.modinv)(8n, exports.L);
+/**
+ * Cofactor witness for a prime-order-subgroup point P: Q = [8^-1 mod L]*P, [2]Q, [4]Q.
+ * The contract (Register) and the circuit (transfer) verify [8]*Q == P instead of
+ * running a 252-step [L]*P ladder. Only meaningful for a subgroup point - for any
+ * other on-curve point [8]*Q != P (see isInPrimeSubgroup).
+ *
+ * The verifiers check q on-curve, q2 == q (+) q, q4 == q2 (+) q2 and
+ * P == q4 (+) q4; the Minter uses verifySum (division-free), the circuit
+ * AssertInSubgroup. Since the Edwards law is complete each sum is unique, so
+ * the chain pins [8]Q. Neither verifier re-derives Q, it must be supplied.
+ * @param x,y the point P; NOT validated here (callers validate first)
+ * @returns q (the Register/transfer witness) plus its doublings q2, q4
+ */
+function cofactorWitness(x, y) {
+    const q = mul(x, y, INV8);
+    const q2 = add(q[0], q[1], q[0], q[1]);
+    const q4 = add(q2[0], q2[1], q2[0], q2[1]);
+    return { q, q2, q4 };
+}
+/**
+ * True iff (x, y) is on-curve AND in the prime-order subgroup. Jubjub has cofactor 8:
+ * the group is Z/8 x Z/L, so [8]*(any curve point) lies in the order-L subgroup and
+ * [8]*([8^-1 mod L]*P) == P holds exactly when P has no torsion component.
+ * (mul() reduces scalars mod L, so [L]*P == O cannot be used as the test.)
+ *
+ * The identity IS a subgroup point and passes; callers that need a non-trivial
+ * key (decryptNote, registerWitness, the transfer prover) check isIdentity too.
+ * Coordinates are reduced mod r, so non-canonical inputs (x + r) also pass;
+ * callers that store or compare points check canonical range separately.
+ */
+function isInPrimeSubgroup(x, y) {
+    if (!isOnCurve(x, y))
+        return false;
+    const { q4 } = cofactorWitness(x, y);
+    const [ex, ey] = add(q4[0], q4[1], q4[0], q4[1]);
+    return ex === (0, exports.mod)(x) && ey === (0, exports.mod)(y);
+}

package/dist/mimc.d.ts

@@ -1,4 +1,19 @@
 /**
- * mimc.ts — MiMC-5 permutation over the BLS12-381 scalar field.
+ * mimc.ts - MiMC-5 permutation over the BLS12-381 scalar field.
+ *
+ * Bit-for-bit the same function as MiMC5Perm in circuits/lib/mimc.circom:
+ * 110 rounds of x -> (x + key + c_i)^5, output = final state + key. The round
+ * constants come from the generated constants table shared with the circuit.
+ */
+/**
+ * Keyed MiMC-5 permutation: `out = MiMC(input, key)`.
+ *
+ * Used as a PRF with the SECRET in `key` and a small public domain tag in
+ * `input` (note keystream: key = ECDH shared x, input = 1 / 2; view-key
+ * derivation: key = spend secret, input = 7). Keep that orientation: with
+ * key = 0 the function degenerates to a keyless public permutation.
+ * @param input any integer, reduced mod r
+ * @param key any integer, reduced mod r
+ * @returns a field element in [0, r)
  */
 export declare function mimc5perm(input: bigint, key: bigint): bigint;

package/dist/mimc.js

@@ -1,6 +1,10 @@
 "use strict";
 /**
- * mimc.ts — MiMC-5 permutation over the BLS12-381 scalar field.
+ * mimc.ts - MiMC-5 permutation over the BLS12-381 scalar field.
+ *
+ * Bit-for-bit the same function as MiMC5Perm in circuits/lib/mimc.circom:
+ * 110 rounds of x -> (x + key + c_i)^5, output = final state + key. The round
+ * constants come from the generated constants table shared with the circuit.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mimc5perm = mimc5perm;
@@ -8,6 +12,17 @@ const constants_1 = require("./constants");
 const jubjub_1 = require("./jubjub");
 const ROUNDS = constants_1.CONSTANTS.MIMC_ROUNDS;
 const RC = constants_1.CONSTANTS.MIMC_C.map((c) => BigInt(c));
+/**
+ * Keyed MiMC-5 permutation: `out = MiMC(input, key)`.
+ *
+ * Used as a PRF with the SECRET in `key` and a small public domain tag in
+ * `input` (note keystream: key = ECDH shared x, input = 1 / 2; view-key
+ * derivation: key = spend secret, input = 7). Keep that orientation: with
+ * key = 0 the function degenerates to a keyless public permutation.
+ * @param input any integer, reduced mod r
+ * @param key any integer, reduced mod r
+ * @returns a field element in [0, r)
+ */
 function mimc5perm(input, key) {
     let st = (0, jubjub_1.mod)(input);
     key = (0, jubjub_1.mod)(key);

package/dist/note.d.ts

@@ -1,31 +1,98 @@
 /**
- * note.ts — ECDH encrypted note + view/spend key derivation.
+ * note.ts - ECDH encrypted note + view/spend key derivation.
  *
  * Notes are encrypted to the receiver's VIEWING key (`pk_view`). Holding
  * `sk_view` lets the receiver (or a granted auditor) read amounts but not spend.
+ *
+ * Scheme (mirrors circuits/lib/encrypted_note.circom, which proves the sender
+ * formed the note this way):
+ *   R          = k*G                       (ephemeral key, published)
+ *   shared     = k*pk_view == sk_view*R    (ECDH)
+ *   mask_i     = MiMC(DOMAIN_i, key = shared.x)
+ *   enc_amount = amount + mask_1,  enc_blind = amount_blind + mask_2   (mod r)
+ * The masks are a one-time pad keyed by shared.x: k MUST be fresh per note.
+ * Reusing k toward the same receiver reuses the pad and leaks the difference
+ * of the two plaintexts. The circuit cannot enforce freshness across proofs.
  */
 import { Point } from "./jubjub";
+/**
+ * The on-chain note payload - everything here is PUBLIC (it travels in the
+ * InternalTransfer message). The ephemeral scalar k is deliberately not part of
+ * it; `MetonSDK.transfer()` returns it separately as `ephScalar`.
+ */
 export interface Note {
+    /** x of the ephemeral key R = k*G */
     Rx: bigint;
+    /** y of the ephemeral key R = k*G */
     Ry: bigint;
+    /** amount + MiMC(1, shared.x) mod r */
     enc_amount: bigint;
+    /** amount_blind + MiMC(2, shared.x) mod r */
     enc_blind: bigint;
-    eph_scalar: bigint;
-    shared_x: bigint;
 }
-/** Derive a viewing keypair one-way from the spend secret. */
+/**
+ * Derive a viewing keypair one-way from the spend secret:
+ * sk_view = MiMC(DOMAIN_VIEW = 7, key = spendSk) mod L, pk_view = sk_view*G.
+ *
+ * One-way, so `skView` can be handed to an auditor without exposing `spendSk`.
+ * Deterministic: the same spend secret always yields the same view key, which is
+ * what makes the (immutable) on-chain `Register` recoverable from the seed.
+ * @param spendSk root secret (any integer; reduced mod r before hashing)
+ * @returns skView in [1, L) (0 is mapped to 1 so pkView is never the identity)
+ *   and pkView, always a prime-order-subgroup point
+ */
 export declare function deriveViewKey(spendSk: bigint): {
     skView: bigint;
     pkView: Point;
 };
-/** Encrypt (amount, amount_blind) to a receiver viewing key with ephemeral k. */
+/**
+ * Encrypt (amount, amount_blind) to a receiver viewing key with ephemeral k.
+ *
+ * Performs NO validation: the receiver key is not checked for subgroup
+ * membership and k is not checked against 0 mod L. Use `MetonSDK.transfer()`
+ * or `sealNote()` for the validated path; the transfer circuit rejects a
+ * low-order key or an identity R anyway, but only after witness generation.
+ * @param amount token amount (64-bit in the circuit)
+ * @param amountBlind blinding of the amount commitment (252-bit scalar)
+ * @param receiverViewPkX,receiverViewPkY the recipient's pk_view (subgroup point)
+ * @param ephScalar k - MUST be fresh, uniformly random per note (see file header)
+ * @returns the public note; k itself is a secret the caller may keep or discard
+ */
 export declare function encryptNote(amount: bigint, amountBlind: bigint, receiverViewPkX: bigint, receiverViewPkY: bigint, ephScalar: bigint): Note;
-/** Decrypt a note with a viewing secret (sk_view). */
+/**
+ * Decrypt a note with a viewing secret (sk_view).
+ *
+ * R is validated first: it must be a non-identity point of the prime-order
+ * subgroup. An honest note always is (the circuit proves R = k*G, k != 0 mod L);
+ * anything else is malformed, and multiplying sk_view into a low-order point
+ * would leak bits of the viewing key.
+ *
+ * Decryption cannot fail otherwise: a wrong key or a note addressed to someone
+ * else yields garbage, not an error. Use `viewNote` to check the result against
+ * the on-chain amount commitment.
+ * @param skView the recipient's viewing secret (or an auditor's copy of it)
+ * @param Rx,Ry the note's ephemeral key, canonical coordinates in [0, r)
+ * @param encAmount,encBlind the masked values from the note
+ * @returns amount and amountBlind as field elements; an honest note gives
+ *   amount < 2^64 and amountBlind < 2^252
+ * @throws Error if R is out of range, the identity, off-curve or not in the
+ *   prime-order subgroup (malformed note; a proven note never is)
+ */
 export declare function decryptNote(skView: bigint, Rx: bigint, Ry: bigint, encAmount: bigint, encBlind: bigint): {
     amount: bigint;
     amountBlind: bigint;
 };
-/** Decrypt AND verify the note opens the on-chain amount_commit point. */
+/**
+ * Decrypt AND verify the note opens the on-chain amount_commit point.
+ *
+ * `valid` is true iff commit(amount, amountBlind) equals (amountCommitX,
+ * amountCommitY) exactly (canonical coordinates). Since the transfer proof binds
+ * the encrypted values to that commitment, `valid == false` means the note was
+ * decrypted with the wrong viewing key or paired with the wrong commitment,
+ * not that the sender cheated. Callers that credit a balance from a note MUST
+ * check `valid`.
+ * @throws Error from decryptNote on a malformed R
+ */
 export declare function viewNote(skView: bigint, note: {
     Rx: bigint;
     Ry: bigint;