@metoncash/sdk-v1 0.1.0

package/dist/prover.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * prover.ts — Build Groth16 proofs for the deposit / withdraw / transfer circuits.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetonSDK = void 0;
+const path = __importStar(require("path"));
+const snarkjs = __importStar(require("snarkjs"));
+const jubjub_1 = require("./jubjub");
+const note_1 = require("./note");
+class MetonSDK {
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    /**
+     * Convenience: derive artifact paths from a build directory laid out as this
+     * repo's `npm run build` / `npm run setup` produce:
+     *   <dir>/<c>/<c>_js/<c>.wasm  and  <dir>/<c>/<c>_final.zkey
+     */
+    static fromBuildDir(dir) {
+        const mk = (c) => ({
+            wasm: path.join(dir, c, `${c}_js`, `${c}.wasm`),
+            zkey: path.join(dir, c, `${c}_final.zkey`),
+        });
+        return new MetonSDK({ deposit: mk("deposit"), withdraw: mk("withdraw"), transfer: mk("transfer") });
+    }
+    prove(art, input) {
+        return snarkjs.groth16.fullProve(input, art.wasm, art.zkey);
+    }
+    /** Deposit a public `amount`, producing a commitment to it. */
+    async deposit(args) {
+        const blinding = args.blinding ?? (0, jubjub_1.randomScalar)(252);
+        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(),
+            blinding: blinding.toString(),
+        });
+        return { proof, publicSignals, commitment: [cx, cy], blinding };
+    }
+    /** Withdraw a public `amount`, proving `balance ≥ amount`. */
+    async withdraw(args) {
+        const newBlind = args.newBlind ?? (0, jubjub_1.randomScalar)(252);
+        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);
+        const { proof, publicSignals } = await this.prove(this.cfg.withdraw, {
+            amount: args.amount.toString(),
+            old_commitment_x: ox.toString(),
+            old_commitment_y: oy.toString(),
+            new_commitment_x: nx.toString(),
+            new_commitment_y: ny.toString(),
+            seqNo: args.seqNo.toString(),
+            account_id: 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. */
+    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.
+        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);
+        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);
+        const { proof, publicSignals } = await this.prove(this.cfg.transfer, {
+            old_sender_cx: ox.toString(),
+            old_sender_cy: oy.toString(),
+            new_sender_cx: snx.toString(),
+            new_sender_cy: sny.toString(),
+            amount_commit_x: amx.toString(),
+            amount_commit_y: amy.toString(),
+            receiver_view_pk_x: pkx.toString(),
+            receiver_view_pk_y: pky.toString(),
+            ephemeral_x: note.Rx.toString(),
+            ephemeral_y: note.Ry.toString(),
+            enc_amount: note.enc_amount.toString(),
+            enc_blind: note.enc_blind.toString(),
+            seqNo: args.seqNo.toString(),
+            account_id: 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(),
+        });
+        return {
+            proof,
+            publicSignals,
+            newSenderCommitment: [snx, sny],
+            amountCommitment: [amx, amy],
+            note,
+            remainder,
+            senderNewBlind,
+            amountBlind,
+            ephScalar,
+        };
+    }
+}
+exports.MetonSDK = MetonSDK;

package/dist/utils/index.d.ts

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

package/dist/utils/index.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openNote = exports.sealNote = exports.viewKeyFromSpend = exports.walletKeysFromSpend = exports.generateWalletKeys = void 0;
+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; } });
+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; } });

package/dist/utils/keys.d.ts

@@ -0,0 +1,23 @@
+/**
+ * utils/keys.ts — wallet key generation.
+ *
+ * Each wallet has a SPEND key (authorizes spends; bound on-chain by address)
+ * and a VIEW key derived one-way from it. `viewSk` decrypts incoming notes and
+ * is safe to share with an auditor — it grants read access, not spend ability.
+ */
+import { Point } from "../jubjub";
+export interface WalletKeys {
+    spendSk: bigint;
+    spendPk: Point;
+    viewSk: bigint;
+    viewPk: Point;
+}
+/** Generate a fresh wallet keypair (random spend secret + derived view key). */
+export declare function generateWalletKeys(): WalletKeys;
+/** Derive the full key set from an existing spend secret. */
+export declare function walletKeysFromSpend(spendSk: bigint): WalletKeys;
+/** Derive just the viewing keypair (read-only; shareable for audit). */
+export declare function viewKeyFromSpend(spendSk: bigint): {
+    viewSk: bigint;
+    viewPk: Point;
+};

package/dist/utils/keys.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * utils/keys.ts — wallet key generation.
+ *
+ * Each wallet has a SPEND key (authorizes spends; bound on-chain by address)
+ * and a VIEW key derived one-way from it. `viewSk` decrypts incoming notes and
+ * is safe to share with an auditor — it grants read access, not spend ability.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateWalletKeys = generateWalletKeys;
+exports.walletKeysFromSpend = walletKeysFromSpend;
+exports.viewKeyFromSpend = viewKeyFromSpend;
+const jubjub_1 = require("../jubjub");
+const note_1 = require("../note");
+/** Generate a fresh wallet keypair (random spend secret + derived view key). */
+function generateWalletKeys() {
+    return walletKeysFromSpend((0, jubjub_1.randomScalar)(252));
+}
+/** Derive the full key set from an existing spend secret. */
+function walletKeysFromSpend(spendSk) {
+    const { skView, pkView } = (0, note_1.deriveViewKey)(spendSk);
+    return { spendSk, spendPk: (0, jubjub_1.derivePub)(spendSk), viewSk: skView, viewPk: pkView };
+}
+/** Derive just the viewing keypair (read-only; shareable for audit). */
+function viewKeyFromSpend(spendSk) {
+    const { skView, pkView } = (0, note_1.deriveViewKey)(spendSk);
+    return { viewSk: skView, viewPk: pkView };
+}

package/dist/utils/note.d.ts

@@ -0,0 +1,30 @@
+/**
+ * utils/note.ts — seal an encrypted note for a recipient.
+ *
+ * "Signing" a note here means producing the sender-side ECDH-sealed payload
+ * (R, enc_amount, enc_blind): a fresh ephemeral key R = k·G, with the amount and
+ * blind masked by a key derived from the ECDH shared secret k·pk_view. Only the
+ * holder of the recipient's viewing secret can open it. There is no separate
+ * signature — authenticity/secrecy come from the ECDH to the recipient's key.
+ */
+import { Point } from "../jubjub";
+import { Note } from "../note";
+/** Minimal note fields needed to open it (the on-chain payload). */
+export type SealedNote = Pick<Note, "Rx" | "Ry" | "enc_amount" | "enc_blind">;
+export interface SealNoteArgs {
+    amount: bigint;
+    amountBlind: bigint;
+    receiverViewPk: Point;
+    /** Ephemeral scalar k. Defaults to fresh randomness — MUST be unique per note. */
+    ephScalar?: bigint;
+}
+/** Seal (encrypt) a note to the recipient's viewing key. */
+export declare function sealNote(args: SealNoteArgs): Note;
+/**
+ * Open a sealed note with the recipient's viewing secret, recovering the
+ * transferred amount and its blinding.
+ */
+export declare function openNote(viewSk: bigint, note: SealedNote): {
+    amount: bigint;
+    amountBlind: bigint;
+};

package/dist/utils/note.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * utils/note.ts — seal an encrypted note for a recipient.
+ *
+ * "Signing" a note here means producing the sender-side ECDH-sealed payload
+ * (R, enc_amount, enc_blind): a fresh ephemeral key R = k·G, with the amount and
+ * blind masked by a key derived from the ECDH shared secret k·pk_view. Only the
+ * holder of the recipient's viewing secret can open it. There is no separate
+ * signature — authenticity/secrecy come from the ECDH to the recipient's key.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sealNote = sealNote;
+exports.openNote = openNote;
+const jubjub_1 = require("../jubjub");
+const note_1 = require("../note");
+/** Seal (encrypt) a note to the recipient's viewing key. */
+function sealNote(args) {
+    const k = args.ephScalar ?? (0, jubjub_1.randomScalar)(252);
+    return (0, note_1.encryptNote)(args.amount, args.amountBlind, args.receiverViewPk[0], args.receiverViewPk[1], k);
+}
+/**
+ * Open a sealed note with the recipient's viewing secret, recovering the
+ * transferred amount and its blinding.
+ */
+function openNote(viewSk, note) {
+    return (0, note_1.decryptNote)(viewSk, note.Rx, note.Ry, note.enc_amount, note.enc_blind);
+}