@metoncash/sdk-v1 0.2.0 → 0.2.1

package/dist/note.js

@@ -1,9 +1,19 @@
 "use strict";
 /**
- * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deriveViewKey = deriveViewKey;
@@ -15,17 +25,39 @@ const mimc_1 = require("./mimc");
 const DOMAIN_AMOUNT = 1n; // keystream block for amount
 const DOMAIN_BLIND = 2n; // keystream block for amount_blind
 const DOMAIN_VIEW = 7n; // viewing-key derivation tag
-/** 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
+ */
 function deriveViewKey(spendSk) {
     let skView = (0, jubjub_1.mod)((0, mimc_1.mimc5perm)(DOMAIN_VIEW, (0, jubjub_1.mod)(spendSk)), jubjub_1.L);
     if (skView === 0n)
         skView = 1n;
     return { skView, pkView: (0, jubjub_1.mul)(jubjub_1.Gx, jubjub_1.Gy, skView) };
 }
-/** 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
+ */
 function encryptNote(amount, amountBlind, receiverViewPkX, receiverViewPkY, ephScalar) {
-    const [Rx, Ry] = (0, jubjub_1.mul)(jubjub_1.Gx, jubjub_1.Gy, ephScalar); // R = k·G
-    const [sx] = (0, jubjub_1.mul)(receiverViewPkX, receiverViewPkY, ephScalar); // shared = k·pk_view
+    const [Rx, Ry] = (0, jubjub_1.mul)(jubjub_1.Gx, jubjub_1.Gy, ephScalar); // R = k*G
+    const [sx] = (0, jubjub_1.mul)(receiverViewPkX, receiverViewPkY, ephScalar); // shared = k*pk_view
     const maskAmount = (0, mimc_1.mimc5perm)(DOMAIN_AMOUNT, sx);
     const maskBlind = (0, mimc_1.mimc5perm)(DOMAIN_BLIND, sx);
     return {
@@ -33,13 +65,32 @@ function encryptNote(amount, amountBlind, receiverViewPkX, receiverViewPkY, ephS
         Ry,
         enc_amount: (0, jubjub_1.mod)(amount + maskAmount),
         enc_blind: (0, jubjub_1.mod)(amountBlind + maskBlind),
-        eph_scalar: ephScalar,
-        shared_x: sx,
     };
 }
-/** 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)
+ */
 function decryptNote(skView, Rx, Ry, encAmount, encBlind) {
-    const [sx] = (0, jubjub_1.mul)(Rx, Ry, skView); // shared = sk_view·R
+    if (Rx < 0n || Rx >= jubjub_1.r || Ry < 0n || Ry >= jubjub_1.r || (0, jubjub_1.isIdentity)(Rx, Ry) || !(0, jubjub_1.isInPrimeSubgroup)(Rx, Ry)) {
+        throw new Error("decryptNote: R is not a valid non-identity Jubjub subgroup point");
+    }
+    const [sx] = (0, jubjub_1.mul)(Rx, Ry, skView); // shared = sk_view*R
     const maskAmount = (0, mimc_1.mimc5perm)(DOMAIN_AMOUNT, sx);
     const maskBlind = (0, mimc_1.mimc5perm)(DOMAIN_BLIND, sx);
     return {
@@ -47,7 +98,17 @@ function decryptNote(skView, Rx, Ry, encAmount, encBlind) {
         amountBlind: (0, jubjub_1.mod)(encBlind + jubjub_1.r - maskBlind),
     };
 }
-/** 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
+ */
 function viewNote(skView, note, amountCommitX, amountCommitY) {
     const { amount, amountBlind } = decryptNote(skView, note.Rx, note.Ry, note.enc_amount, note.enc_blind);
     const [cx, cy] = (0, jubjub_1.commit)(amount, amountBlind);

package/dist/prover.d.ts

@@ -1,65 +1,137 @@
 /**
- * prover.ts — Build Groth16 proofs for the deposit / withdraw / transfer circuits.
+ * prover.ts - Build Groth16 proofs for the deposit / withdraw / transfer circuits.
+ *
+ * Every method validates its arguments, derives the public inputs (commitments,
+ * note) from the caller's secrets, runs snarkjs on the matching circuit and
+ * returns the proof together with every secret the caller must persist to be
+ * able to spend the resulting commitment later (blinding factors, and for a
+ * transfer the note's ephemeral scalar). Losing a blinding factor means losing
+ * the ability to open - and therefore spend - the balance behind it.
+ *
+ * Replay protection: each proof is bound to (accountId, seqNo). `accountId` is
+ * the WALLET contract's address hash (see utils/account.ts, NOT the owner's
+ * address) and `seqNo` must equal the wallet's current sequence number; the
+ * contract rejects anything else, so a proof cannot be replayed or redirected.
  */
 import { Point } from "./jubjub";
 import { Note } from "./note";
-/** A compiled circuit's artifacts: a wasm witness-calculator and a proving key. */
+/**
+ * A compiled circuit's artifacts: a wasm witness-calculator and a proving key.
+ * Either a file path or the file contents in memory (browser bundles).
+ */
 export interface CircuitArtifacts {
     wasm: string | Uint8Array;
     zkey: string | Uint8Array;
 }
+/**
+ * Artifacts for the three circuits. They must come from the same trusted setup
+ * as the verification keys embedded in the on-chain verifiers.
+ */
 export interface MetonConfig {
     deposit: CircuitArtifacts;
     withdraw: CircuitArtifacts;
     transfer: CircuitArtifacts;
 }
+/**
+ * A Groth16 proof as returned by snarkjs. `publicSignals` are decimal strings in
+ * the circuit's `public [...]` order; the contract wrappers serialize both.
+ */
 export interface Proof {
     proof: unknown;
     publicSignals: string[];
 }
+/** Inputs for `MetonSDK.deposit`. */
 export interface DepositArgs {
+    /** public amount to deposit, in [1, 2^64) */
     amount: bigint;
+    /** wallet address hash, see accountIdOf(); values >= r are reduced mod r */
     accountId: bigint;
+    /** the wallet's current seqNo, in [0, 2^32) */
     seqNo: bigint;
+    /** blinding of the new commitment, in [0, 2^252). Default: random. PERSIST IT. */
     blinding?: bigint;
 }
+/** Inputs for `MetonSDK.withdraw`. */
 export interface WithdrawArgs {
+    /** public amount to withdraw, in [1, 2^64) and <= balance */
     amount: bigint;
+    /** the hidden balance behind the current commitment, in [0, 2^64) */
     balance: bigint;
+    /** blinding of the current commitment (the secret persisted from the last op) */
     oldBlind: bigint;
+    /** wallet address hash, see accountIdOf() */
     accountId: bigint;
+    /** the wallet's current seqNo, in [0, 2^32) */
     seqNo: bigint;
+    /** blinding of the remainder commitment, in [0, 2^252). Default: random. PERSIST IT. */
     newBlind?: bigint;
 }
+/** Inputs for `MetonSDK.transfer`. */
 export interface TransferArgs {
+    /** hidden amount to send, in [1, 2^64) and <= senderBalance (0 is rejected) */
     amount: bigint;
+    /** the sender's hidden balance behind its current commitment, in [0, 2^64) */
     senderBalance: bigint;
+    /** blinding of the sender's current commitment */
     senderOldBlind: bigint;
+    /** recipient's viewing public key (pk_view as registered on-chain); must be a
+     *  non-identity prime-order-subgroup point with canonical coordinates */
     receiverViewPk: Point;
+    /** SENDER wallet address hash, see accountIdOf() */
     accountId: bigint;
+    /** the sender wallet's current seqNo, in [0, 2^32) */
     seqNo: bigint;
+    /** blinding of the sender's remainder commitment. Default: random. PERSIST IT. */
     senderNewBlind?: bigint;
+    /** blinding of the amount commitment the receiver gets. Default:
+     *  senderOldBlind - senderNewBlind (mod L), so that old == new (+) amount holds
+     *  as points (homomorphic relation, checkable by any client) */
     amountBlind?: bigint;
+    /** ephemeral scalar k for the note. Default: random. MUST be fresh per note -
+     *  reuse toward the same receiver reuses the one-time pad (see note.ts). */
     ephScalar?: bigint;
 }
+/** Output of `MetonSDK.deposit`. */
 export interface DepositResult extends Proof {
+    /** commit(amount, blinding) - the wallet's commitment after the deposit */
     commitment: Point;
+    /** SECRET: needed to open `commitment` in the next withdraw / transfer */
     blinding: bigint;
 }
+/** Output of `MetonSDK.withdraw`. */
 export interface WithdrawResult extends Proof {
+    /** commit(remainder, newBlind) - the wallet's commitment after the withdraw */
     newCommitment: Point;
+    /** balance - amount, the hidden balance behind `newCommitment` */
     remainder: bigint;
+    /** SECRET: needed to open `newCommitment` next time */
     newBlind: bigint;
 }
+/** Output of `MetonSDK.transfer`. */
 export interface TransferResult extends Proof {
+    /** commit(remainder, senderNewBlind) - the sender's commitment after the transfer */
     newSenderCommitment: Point;
+    /** commit(amount, amountBlind) - the receiver's wallet adds this point to its own
+     *  commitment, so the receiver's opening becomes (balance + amount, blind + amountBlind mod L) */
     amountCommitment: Point;
+    /** the PUBLIC encrypted note that travels with the transfer */
     note: Note;
+    /** senderBalance - amount, the hidden balance behind `newSenderCommitment` */
     remainder: bigint;
+    /** SECRET: needed to open `newSenderCommitment` next time */
     senderNewBlind: bigint;
+    /** the receiver learns this by decrypting the note; the sender may keep it to
+     *  audit its own outgoing payment */
     amountBlind: bigint;
+    /** SECRET: the ephemeral scalar k. Never publish it (it re-derives the masks);
+     *  keep it only if you want to re-open the note without the receiver's key. */
     ephScalar: bigint;
 }
+/**
+ * Proof builder for the three Meton circuits. Stateless apart from the artifact
+ * config; one instance can be shared across wallets. Construct with explicit
+ * artifacts, `fromBuildDir()` or `bundled()`.
+ */
 export declare class MetonSDK {
     private readonly cfg;
     constructor(cfg: MetonConfig);
@@ -72,14 +144,46 @@ export declare class MetonSDK {
     /**
      * Zero-config: use the proving artifacts (wasm + zkey) shipped with this
      * package under `artifacts/` (populated at build time from the repo's `build/`).
-     * These are tied to a specific trusted setup — verify against the on-chain vkey.
+     * These are tied to a specific trusted setup - verify against the on-chain vkey.
      */
     static bundled(): MetonSDK;
     private prove;
-    /** Deposit a public `amount`, producing a commitment to it. */
+    /**
+     * Deposit a public `amount`, producing a commitment to it.
+     *
+     * Proves commitment == commit(amount, blinding) for the deposit circuit. The
+     * Wallet contract ADDS this point to its stored commitment (edwardsAdd), so
+     * the caller's local opening becomes (balance + amount, oldBlind + blinding
+     * mod L); a fresh wallet starts from the identity, i.e. (0, 0).
+     * @returns the proof, the commitment and the blinding to persist
+     * @throws TypeError / RangeError on invalid args (see DepositArgs ranges)
+     */
     deposit(args: DepositArgs): Promise<DepositResult>;
-    /** Withdraw a public `amount`, proving `balance ≥ amount`. */
+    /**
+     * Withdraw a public `amount`, proving `balance >= amount`.
+     *
+     * Proves old == commit(balance, oldBlind), new == commit(balance - amount,
+     * newBlind) and that the remainder is a 64-bit value (no underflow). The
+     * old commitment is derived here and must equal the wallet's stored one, or
+     * the contract rejects the proof.
+     * @returns the proof, the new commitment, the remainder and newBlind to persist
+     * @throws RangeError if amount > balance or any arg is out of range
+     */
     withdraw(args: WithdrawArgs): Promise<WithdrawResult>;
-    /** Private transfer of a hidden `amount` to a receiver's viewing key. */
+    /**
+     * Private transfer of a hidden `amount` to a receiver's viewing key.
+     *
+     * Proves the three commitments open correctly with 64-bit values (sender old,
+     * sender new = remainder, amount), that the note (R, enc_amount, enc_blind)
+     * encrypts exactly (amount, amountBlind) to `receiverViewPk` with k, that
+     * `receiverViewPk` is a subgroup point (via the cofactor witness computed
+     * here) and that R is not the identity. The amount and the blindings stay
+     * private; the receiver learns them by decrypting the note.
+     * @returns the proof, both new commitments, the public note and the secrets
+     *   to persist (senderNewBlind; amountBlind and ephScalar optionally)
+     * @throws RangeError if amount > senderBalance, ephScalar == 0 mod L,
+     *   receiverViewPk is the identity / off-curve / low-order / non-canonical,
+     *   or any arg is out of range
+     */
     transfer(args: TransferArgs): Promise<TransferResult>;
 }

package/dist/prover.js

@@ -1,6 +1,18 @@
 "use strict";
 /**
- * prover.ts — Build Groth16 proofs for the deposit / withdraw / transfer circuits.
+ * prover.ts - Build Groth16 proofs for the deposit / withdraw / transfer circuits.
+ *
+ * Every method validates its arguments, derives the public inputs (commitments,
+ * note) from the caller's secrets, runs snarkjs on the matching circuit and
+ * returns the proof together with every secret the caller must persist to be
+ * able to spend the resulting commitment later (blinding factors, and for a
+ * transfer the note's ephemeral scalar). Losing a blinding factor means losing
+ * the ability to open - and therefore spend - the balance behind it.
+ *
+ * Replay protection: each proof is bound to (accountId, seqNo). `accountId` is
+ * the WALLET contract's address hash (see utils/account.ts, NOT the owner's
+ * address) and `seqNo` must equal the wallet's current sequence number; the
+ * contract rejects anything else, so a proof cannot be replayed or redirected.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -41,6 +53,61 @@ const path = __importStar(require("path"));
 const snarkjs = __importStar(require("snarkjs"));
 const jubjub_1 = require("./jubjub");
 const note_1 = require("./note");
+// -- input validation --
+// The circuits reject out-of-range inputs, but only after a full witness
+// computation and with an opaque "Assert Failed"; the contracts reject some
+// later still. Check the caller's inputs up front with a precise message.
+// Every check here mirrors a constraint that exists elsewhere (circuit or
+// contract); none of them is the security boundary.
+const TWO_32 = 1n << 32n;
+const TWO_64 = 1n << 64n;
+const TWO_252 = 1n << 252n;
+// throws TypeError for a non-bigint, RangeError unless lo <= v < hi
+function checkRange(name, v, lo, hi) {
+    if (typeof v !== "bigint")
+        throw new TypeError(`${name} must be a bigint`);
+    if (v < lo || v >= hi)
+        throw new RangeError(`${name} must be in [${lo}, ${hi}), got ${v}`);
+}
+/** value fields (amounts, balances) are 64-bit; amounts must be > 0 (contracts and
+ *  transfer circuit) */
+const checkValue = (name, v, allowZero = false) => checkRange(name, v, allowZero ? 0n : 1n, TWO_64);
+/** blinding factors are 252-bit scalars (Num2Bits_strict(252) in ScalarMulH) */
+const checkBlind = (name, v) => checkRange(name, v, 0n, TWO_252);
+/** public inputs shared by every circuit. accountId is a field element: the raw
+ *  256-bit address hash is accepted and reduced mod r (as the contract does).
+ *  seqNo is a uint32 on-chain. */
+function checkCommon(args) {
+    checkRange("accountId", args.accountId, 0n, 1n << 256n);
+    checkRange("seqNo", args.seqNo, 0n, TWO_32);
+}
+/** the ephemeral scalar must be a 252-bit scalar that is non-zero mod L (R != identity).
+ *  k = L itself is 252 bits and non-zero but gives R = O, hence the mod-L test;
+ *  the circuit enforces the same via NonZero on R.x. */
+function checkEphScalar(k) {
+    checkRange("ephScalar", k, 1n, TWO_252);
+    if (k % jubjub_1.L === 0n)
+        throw new RangeError("ephScalar must not be 0 mod L (it would make R the identity)");
+}
+/** the receiver key must be a non-identity point of the prime-order subgroup, as the
+ *  circuit requires (AssertInSubgroup + NonZero on pk.x). A low-order key would push
+ *  the ECDH secret into a tiny subgroup; a non-canonical coordinate would never
+ *  match the key the receiver registered. */
+function checkReceiverViewPk(pk) {
+    const [x, y] = pk;
+    checkRange("receiverViewPk.x", x, 0n, jubjub_1.r);
+    checkRange("receiverViewPk.y", y, 0n, jubjub_1.r);
+    if ((0, jubjub_1.isIdentity)(x, y))
+        throw new RangeError("receiverViewPk must not be the identity");
+    if (!(0, jubjub_1.isInPrimeSubgroup)(x, y)) {
+        throw new RangeError("receiverViewPk is not a point of the Jubjub prime-order subgroup (off-curve or low/mixed order)");
+    }
+}
+/**
+ * Proof builder for the three Meton circuits. Stateless apart from the artifact
+ * config; one instance can be shared across wallets. Construct with explicit
+ * artifacts, `fromBuildDir()` or `bundled()`.
+ */
 class MetonSDK {
     constructor(cfg) {
         this.cfg = cfg;
@@ -60,31 +127,61 @@ class MetonSDK {
     /**
      * Zero-config: use the proving artifacts (wasm + zkey) shipped with this
      * package under `artifacts/` (populated at build time from the repo's `build/`).
-     * These are tied to a specific trusted setup — verify against the on-chain vkey.
+     * These are tied to a specific trusted setup - verify against the on-chain vkey.
      */
     static bundled() {
         return MetonSDK.fromBuildDir(path.join(__dirname, "..", "artifacts"));
     }
+    // witness generation + Groth16 proving in one step; input keys are the
+    // circuit's signal names, values decimal strings (snarkjs convention)
     prove(art, input) {
         return snarkjs.groth16.fullProve(input, art.wasm, art.zkey);
     }
-    /** Deposit a public `amount`, producing a commitment to it. */
+    /**
+     * Deposit a public `amount`, producing a commitment to it.
+     *
+     * Proves commitment == commit(amount, blinding) for the deposit circuit. The
+     * Wallet contract ADDS this point to its stored commitment (edwardsAdd), so
+     * the caller's local opening becomes (balance + amount, oldBlind + blinding
+     * mod L); a fresh wallet starts from the identity, i.e. (0, 0).
+     * @returns the proof, the commitment and the blinding to persist
+     * @throws TypeError / RangeError on invalid args (see DepositArgs ranges)
+     */
     async deposit(args) {
         const blinding = args.blinding ?? (0, jubjub_1.randomScalar)(252);
+        checkValue("amount", args.amount);
+        checkBlind("blinding", blinding);
+        checkCommon(args);
         const [cx, cy] = (0, jubjub_1.commit)(args.amount, blinding);
         const { proof, publicSignals } = await this.prove(this.cfg.deposit, {
             amount: args.amount.toString(),
             commitment_x: cx.toString(),
             commitment_y: cy.toString(),
             seqNo: args.seqNo.toString(),
-            account_id: args.accountId.toString(),
+            account_id: (0, jubjub_1.mod)(args.accountId).toString(),
             blinding: blinding.toString(),
         });
         return { proof, publicSignals, commitment: [cx, cy], blinding };
     }
-    /** Withdraw a public `amount`, proving `balance ≥ amount`. */
+    /**
+     * Withdraw a public `amount`, proving `balance >= amount`.
+     *
+     * Proves old == commit(balance, oldBlind), new == commit(balance - amount,
+     * newBlind) and that the remainder is a 64-bit value (no underflow). The
+     * old commitment is derived here and must equal the wallet's stored one, or
+     * the contract rejects the proof.
+     * @returns the proof, the new commitment, the remainder and newBlind to persist
+     * @throws RangeError if amount > balance or any arg is out of range
+     */
     async withdraw(args) {
         const newBlind = args.newBlind ?? (0, jubjub_1.randomScalar)(252);
+        checkValue("amount", args.amount);
+        checkValue("balance", args.balance, true);
+        if (args.amount > args.balance)
+            throw new RangeError(`amount (${args.amount}) exceeds balance (${args.balance})`);
+        checkBlind("oldBlind", args.oldBlind);
+        checkBlind("newBlind", newBlind);
+        checkCommon(args);
         const remainder = args.balance - args.amount;
         const [ox, oy] = (0, jubjub_1.commit)(args.balance, args.oldBlind);
         const [nx, ny] = (0, jubjub_1.commit)(remainder, newBlind);
@@ -95,25 +192,54 @@ class MetonSDK {
             new_commitment_x: nx.toString(),
             new_commitment_y: ny.toString(),
             seqNo: args.seqNo.toString(),
-            account_id: args.accountId.toString(),
+            account_id: (0, jubjub_1.mod)(args.accountId).toString(),
             balance: args.balance.toString(),
             old_blind: args.oldBlind.toString(),
             new_blind: newBlind.toString(),
         });
         return { proof, publicSignals, newCommitment: [nx, ny], remainder, newBlind };
     }
-    /** Private transfer of a hidden `amount` to a receiver's viewing key. */
+    /**
+     * Private transfer of a hidden `amount` to a receiver's viewing key.
+     *
+     * Proves the three commitments open correctly with 64-bit values (sender old,
+     * sender new = remainder, amount), that the note (R, enc_amount, enc_blind)
+     * encrypts exactly (amount, amountBlind) to `receiverViewPk` with k, that
+     * `receiverViewPk` is a subgroup point (via the cofactor witness computed
+     * here) and that R is not the identity. The amount and the blindings stay
+     * private; the receiver learns them by decrypting the note.
+     * @returns the proof, both new commitments, the public note and the secrets
+     *   to persist (senderNewBlind; amountBlind and ephScalar optionally)
+     * @throws RangeError if amount > senderBalance, ephScalar == 0 mod L,
+     *   receiverViewPk is the identity / off-curve / low-order / non-canonical,
+     *   or any arg is out of range
+     */
     async transfer(args) {
         const senderNewBlind = args.senderNewBlind ?? (0, jubjub_1.randomScalar)(252);
-        const remainder = args.senderBalance - args.amount;
-        // Homomorphic relation old == new ⊕ amount holds for amount_blind below.
+        // Keeps old == new (+) amount as points (not required by the contract, but
+        // lets a client re-check the homomorphic relation locally).
         const amountBlind = args.amountBlind ?? (0, jubjub_1.mod)(args.senderOldBlind - senderNewBlind + jubjub_1.L, jubjub_1.L);
         const ephScalar = args.ephScalar ?? (0, jubjub_1.randomScalar)(252);
+        checkValue("amount", args.amount);
+        checkValue("senderBalance", args.senderBalance, true);
+        if (args.amount > args.senderBalance) {
+            throw new RangeError(`amount (${args.amount}) exceeds senderBalance (${args.senderBalance})`);
+        }
+        checkBlind("senderOldBlind", args.senderOldBlind);
+        checkBlind("senderNewBlind", senderNewBlind);
+        checkBlind("amountBlind", amountBlind);
+        checkEphScalar(ephScalar);
+        checkReceiverViewPk(args.receiverViewPk);
+        checkCommon(args);
+        const remainder = args.senderBalance - args.amount;
         const [ox, oy] = (0, jubjub_1.commit)(args.senderBalance, args.senderOldBlind);
         const [snx, sny] = (0, jubjub_1.commit)(remainder, senderNewBlind);
         const [amx, amy] = (0, jubjub_1.commit)(args.amount, amountBlind);
         const [pkx, pky] = args.receiverViewPk;
         const note = (0, note_1.encryptNote)(args.amount, amountBlind, pkx, pky, ephScalar);
+        // cofactor witness for the circuit's subgroup check: Q = [8^-1 mod L]*pk, so [8]*Q = pk
+        // (private input; the circuit re-derives [2]Q, [4]Q, [8]Q itself)
+        const [qx, qy] = (0, jubjub_1.cofactorWitness)(pkx, pky).q;
         const { proof, publicSignals } = await this.prove(this.cfg.transfer, {
             old_sender_cx: ox.toString(),
             old_sender_cy: oy.toString(),
@@ -128,13 +254,15 @@ class MetonSDK {
             enc_amount: note.enc_amount.toString(),
             enc_blind: note.enc_blind.toString(),
             seqNo: args.seqNo.toString(),
-            account_id: args.accountId.toString(),
+            account_id: (0, jubjub_1.mod)(args.accountId).toString(),
             sender_balance: args.senderBalance.toString(),
             sender_old_blind: args.senderOldBlind.toString(),
             sender_new_blind: senderNewBlind.toString(),
             amount: args.amount.toString(),
             amount_blind: amountBlind.toString(),
             eph_scalar: ephScalar.toString(),
+            pk_witness_x: qx.toString(),
+            pk_witness_y: qy.toString(),
         });
         return {
             proof,

package/dist/utils/account.d.ts

@@ -0,0 +1,21 @@
+/**
+ * utils/account.ts - the `account_id` public input.
+ *
+ * Every proof is bound to the Wallet contract it will be verified by:
+ * account_id = hash(cell(wallet address)) mod r, exactly what the contract
+ * computes as `(contract.getAddress() as slice).hash() % JUBJUB_R`. Derive it
+ * from the wallet's address (Minter.getWalletAddress(owner)), NOT the owner's.
+ */
+import { Address } from "@ton/core";
+/**
+ * The `account_id` public input for proofs verified by `walletAddress`.
+ *
+ * Computed as the 256-bit representation hash of a cell holding the serialized
+ * MsgAddressInt, reduced mod r - identical to the contract's slice hash of its
+ * own address. Binding the proof to the wallet (together with seqNo) is what
+ * stops a valid proof from being replayed against another wallet.
+ * @param walletAddress the Wallet CONTRACT address (Minter.getWalletAddress(owner)),
+ *   not the owner's address - a proof built with the owner's address is rejected
+ * @returns a field element in [0, r); pass it as `accountId` to MetonSDK
+ */
+export declare function accountIdOf(walletAddress: Address): bigint;

package/dist/utils/account.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * utils/account.ts - the `account_id` public input.
+ *
+ * Every proof is bound to the Wallet contract it will be verified by:
+ * account_id = hash(cell(wallet address)) mod r, exactly what the contract
+ * computes as `(contract.getAddress() as slice).hash() % JUBJUB_R`. Derive it
+ * from the wallet's address (Minter.getWalletAddress(owner)), NOT the owner's.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accountIdOf = accountIdOf;
+const core_1 = require("@ton/core");
+const jubjub_1 = require("../jubjub");
+/**
+ * The `account_id` public input for proofs verified by `walletAddress`.
+ *
+ * Computed as the 256-bit representation hash of a cell holding the serialized
+ * MsgAddressInt, reduced mod r - identical to the contract's slice hash of its
+ * own address. Binding the proof to the wallet (together with seqNo) is what
+ * stops a valid proof from being replayed against another wallet.
+ * @param walletAddress the Wallet CONTRACT address (Minter.getWalletAddress(owner)),
+ *   not the owner's address - a proof built with the owner's address is rejected
+ * @returns a field element in [0, r); pass it as `accountId` to MetonSDK
+ */
+function accountIdOf(walletAddress) {
+    return BigInt("0x" + (0, core_1.beginCell)().storeAddress(walletAddress).endCell().hash().toString("hex")) % jubjub_1.r;
+}

package/dist/utils/index.d.ts

@@ -1,2 +1,3 @@
-export { WalletKeys, generateWalletKeys, walletKeysFromSpend, viewKeyFromSpend } from "./keys";
+export { WalletKeys, generateWalletKeys, walletKeysFromSpend, viewKeyFromSpend, registerWitness } from "./keys";
 export { SealNoteArgs, SealedNote, sealNote, openNote } from "./note";
+export { accountIdOf } from "./account";

package/dist/utils/index.js

@@ -1,10 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.openNote = exports.sealNote = exports.viewKeyFromSpend = exports.walletKeysFromSpend = exports.generateWalletKeys = void 0;
+exports.accountIdOf = exports.openNote = exports.sealNote = exports.registerWitness = exports.viewKeyFromSpend = exports.walletKeysFromSpend = exports.generateWalletKeys = void 0;
+// utils/index.ts - high-level helpers on top of jubjub.ts / note.ts:
+// key generation + Register witness, note sealing/opening, account_id derivation.
 var keys_1 = require("./keys");
 Object.defineProperty(exports, "generateWalletKeys", { enumerable: true, get: function () { return keys_1.generateWalletKeys; } });
 Object.defineProperty(exports, "walletKeysFromSpend", { enumerable: true, get: function () { return keys_1.walletKeysFromSpend; } });
 Object.defineProperty(exports, "viewKeyFromSpend", { enumerable: true, get: function () { return keys_1.viewKeyFromSpend; } });
+Object.defineProperty(exports, "registerWitness", { enumerable: true, get: function () { return keys_1.registerWitness; } });
 var note_1 = require("./note");
 Object.defineProperty(exports, "sealNote", { enumerable: true, get: function () { return note_1.sealNote; } });
 Object.defineProperty(exports, "openNote", { enumerable: true, get: function () { return note_1.openNote; } });
+var account_1 = require("./account");
+Object.defineProperty(exports, "accountIdOf", { enumerable: true, get: function () { return account_1.accountIdOf; } });