@auditable/privacy-pool-zk-sdk 0.0.2-rc.8 → 0.1.0

package/dist/types.d.ts

@@ -8,13 +8,24 @@ export interface GeneratedCoin {
     coin: CoinData;
     commitment_hex: string;
 }
-export interface SnarkInput {
+/** Pool Merkle tree depth (matches `coin::TREE_DEPTH` / `Transaction` circuit). */
+export declare const POOL_MERKLE_TREE_DEPTH = 20;
+/** Default coin value in stroops (1 XLM); matches Rust `coin::COIN_VALUE`. */
+export declare const COIN_VALUE_STROOPS = 1000000000;
+/**
+ * Merkle path + coin fields for the first withdraw leg (WASM `buildWithdrawMerkleWitness`).
+ * Serde: `withdrawnValue`, `stateRoot`, `stateIndex`, `stateSiblings`.
+ */
+export interface WithdrawMerkleWitness {
+    /** Withdrawn amount in stroops as decimal Fr string; matches `coin.value`. */
     withdrawnValue: string;
+    /** Coin value as decimal field string. */
     value: string;
     nullifier: string;
     secret: string;
     stateRoot: string;
     stateIndex: string;
+    /** Length is always {@link POOL_MERKLE_TREE_DEPTH}; each entry is a decimal field element. */
     stateSiblings: string[];
 }
 export interface StateFile {

package/dist/withdrawal-transaction-input.d.ts

@@ -0,0 +1,91 @@
+import type { WithdrawMerkleWitness } from './types';
+/** Matches `Transaction(20, 2, 2)` in `circuits/main.circom`. */
+export declare const TRANSACTION_TREE_DEPTH = 20;
+export declare const TRANSACTION_N_INS = 2;
+export declare const TRANSACTION_N_OUTS = 2;
+/** BN254 scalar field modulus (ark `Fr`, circom signals). */
+export declare const BN254_SCALAR_MOD = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+/**
+ * BabyJub ECDH in `circuits/encryption.circom` uses `Num2Bits(253)`; scalars must be < 2^253
+ * (matches `libs/cryptography` `scalar_mul_253`).
+ */
+export declare const BN254_BABYJUB_SCALAR_MAX_EXCLUSIVE: bigint;
+export interface WithdrawalProofPublicParams {
+    /** Decimal string, circom `stateRoot`. */
+    stateRoot: string;
+    /** Decimal string, circom `withdrawAddressHi` (Ed25519 key bytes [0..16] as big-endian u128). */
+    withdrawAddressHi: string;
+    /** Decimal string, circom `withdrawAddressLo` (Ed25519 key bytes [16..32] as big-endian u128). */
+    withdrawAddressLo: string;
+    /** Decimal string, circom `privKeyScalar`. */
+    privKeyScalar: string;
+}
+/** Real withdraw leg; coordinates are decimal field strings (same as `CoinData`). */
+export interface WithdrawObject {
+    value: string;
+    nullifier: string;
+    secret: string;
+    /** Depositor ECDH point `[x, y]` as decimal strings. */
+    ephemeralKeys: [string, string];
+    stateSiblings: string[];
+    stateIndex: string;
+}
+export interface DepositObject {
+    value: string;
+    nullifier: string;
+    ephemeralKeyScalar: string;
+    /** Recipient public key `[x, y]` as decimal strings. */
+    recipientPublicKeys: [string, string];
+}
+export type WithdrawSlot = WithdrawObject | 'dummy';
+export type DepositSlot = DepositObject | 'dummy';
+/** Witness calculator input for `circuits/main.circom` `Transaction(20,2,2)`. */
+export interface TransactionWitnessInput {
+    stateRoot: string;
+    withdrawAddressHi: string;
+    withdrawAddressLo: string;
+    privKeyScalar: string;
+    withdrawnValues: [string, string];
+    withdrawnNullifiers: [string, string];
+    withdrawnSecrets: [string, string];
+    ephemeralKeys: [[string, string], [string, string]];
+    stateSiblings: [string[], string[]];
+    stateIndex: [string, string];
+    depositedValues: [string, string];
+    depositedNullifiers: [string, string];
+    depositedEphemeralKeyScalars: [string, string];
+    depositedRecipientPublicKeys: [[string, string], [string, string]];
+}
+export interface WasmEcdhPointFns {
+    ecdhEphemeralPublicKeyFromScalarHex(scalarHex: string): {
+        x: string;
+        y: string;
+    };
+}
+/** 32-byte field coordinate (hex, no 0x) → decimal string mod BN254 scalar field. */
+export declare function coordHexToDecimal(hex: string): string;
+/**
+ * 32-byte big-endian scalar hex → decimal for circom `ephemeralKeyScalar` / ECDH `priv`.
+ * Integer must be < 2^253 (not reduced mod r — values ≥ 2^253 are rejected).
+ */
+export declare function scalarHexToFrDecimal(hex: string): string;
+/**
+ * Stellar G-address Ed25519 payload (32 bytes as 64 hex, optional 0x) → two circom public decimals
+ * (`withdrawAddressHi` / `withdrawAddressLo`). No mod-r; each half fits in 128 bits.
+ */
+export declare function ed25519PubkeyPayloadHexToWithdrawFrDecimals(hex: string): {
+    hi: string;
+    lo: string;
+};
+/** Uniform random `Fr` as decimal (32 random bytes, mod r). For Poseidon-only inputs (e.g. nullifiers). */
+export declare function randomFrDecimal(): string;
+/** Random scalar < 2^253 for BabyJub ECDH / `Num2Bits(253)` (uses {@link generateRandomScalarHex32}). */
+export declare function randomFrDecimal253(): string;
+export declare function buildTransactionWitnessInput(publicParams: WithdrawalProofPublicParams, withdrawSlots: [WithdrawSlot, WithdrawSlot], depositSlots: [DepositSlot, DepositSlot], wasm: WasmEcdhPointFns): TransactionWitnessInput;
+/** `stpl1…` stealth address → `[x, y]` as decimal field strings for `depositedRecipientPublicKeys`. */
+export declare function recipientPublicKeysDecimalFromStealthAddress(stealthAddress: string): [string, string];
+/** First withdraw leg: Merkle witness + depositor ECDH point coordinates (hex). */
+export declare function withdrawObjectFromMerkleWitness(witness: WithdrawMerkleWitness, depositorEphemeralHex: {
+    x: string;
+    y: string;
+}): WithdrawObject;

package/dist/witness.d.ts

@@ -1,2 +1,2 @@
-import type { SnarkInput } from './types';
-export declare function generateWitness(input: SnarkInput, circuitWasm?: BufferSource): Promise<Uint8Array>;
+import type { TransactionWitnessInput } from './withdrawal-transaction-input';
+export declare function generateWitness(input: TransactionWitnessInput, circuitWasm?: BufferSource): Promise<Uint8Array>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auditable/privacy-pool-zk-sdk",
-  "version": "0.0.2-rc.8",
+  "version": "0.1.0",
   "description": "Client SDK for Soroban Privacy Pools - coin generation, withdrawal proofs, and proof serialization",
   "main": "dist/index.mjs",
   "module": "dist/index.mjs",
@@ -19,6 +19,9 @@
   "bin": {
     "client-sdk-cli": "./dist/cli.js"
   },
+  "engines": {
+    "node": ">=19.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/Polynom-Labs/stellar-privacy-layer-contracts"
@@ -35,18 +38,19 @@
     "cli": "node dist/cli.js"
   },
   "dependencies": {
+    "bech32": "^2.0.0",
     "snarkjs": "^0.7.0"
   },
   "devDependencies": {
-    "rollup": "^4.0.0",
     "@rollup/plugin-alias": "^5.0.0",
-    "@rollup/plugin-typescript": "^11.0.0",
-    "@rollup/plugin-node-resolve": "^15.0.0",
     "@rollup/plugin-commonjs": "^25.0.0",
     "@rollup/plugin-json": "^6.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-typescript": "^11.0.0",
+    "@types/node": "^20.0.0",
+    "rollup": "^4.0.0",
     "rollup-plugin-copy": "^3.5.0",
-    "typescript": "^5.0.0",
     "tslib": "^2.6.0",
-    "@types/node": "^20.0.0"
+    "typescript": "^5.0.0"
   }
 }

package/pkg/client_sdk_wasm.d.ts

@@ -0,0 +1,105 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Merkle root, path, and coin field strings for the first withdraw leg (JSON → JSON).
+ */
+export function buildWithdrawMerkleWitness(coin_json: string, state_json: string): string;
+
+/**
+ * Calculate nullifier hash from nullifier decimal string.
+ * Returns hex string (0x...)
+ */
+export function calculateNullifierHash(nullifier_decimal: string): string;
+
+/**
+ * UTF-8 seed → `SHA256` → scalar → BabyJubJub `BASE8 * r` (circom `ECDHEphemeralKey`).
+ * `x` and `y` are lowercase hex (no `0x`). Bech32 / stealth string: TypeScript `encodeStealthAddress`.
+ */
+export function ecdhEphemeralPublicKey(seed: string): any;
+
+/**
+ * 32-byte scalar as 64 hex chars (optional `0x`) → `ecdh_ephemeral_public_key` (no UTF-8 seed hash).
+ */
+export function ecdhEphemeralPublicKeyFromScalarHex(scalar_hex: string): any;
+
+/**
+ * Circuit `ECDH`: `priv * (pub_x, pub_y)` → shared key (`key[0], key[1]` hex).
+ */
+export function ecdhSharedKey(priv_hex: string, pub_x_hex: string, pub_y_hex: string): any;
+
+/**
+ * Generate a new coin with random nullifier, secret, and shared-secret field elements.
+ * `amount` is stroops (u64); JS passes `bigint`.
+ * Returns JSON: { coin: { value, nullifier, secret, commitment }, commitment_hex }
+ */
+export function generateCoin(amount: bigint): any;
+
+/**
+ * `Poseidon₁(scalar)` secret + fixed ECDH shared coords (hex), matching an aligned deposit witness.
+ */
+export function generateCoinForDepositWithSharedHex(scalar_hex: string, shared_x_hex: string, shared_y_hex: string, amount: bigint): any;
+
+/**
+ * `secret` in coin = `Poseidon255(1)(scalar)` per `deposit.circom`; scalar is 32-byte hex (64 chars, optional `0x`).
+ */
+export function generateCoinFromDepositEphemeralScalarHex(scalar_hex: string, amount: bigint): any;
+
+/**
+ * Same as `generateCoin`, but commitment uses the given ECDH shared key (64-char hex coords from `ecdhSharedKey`); shared coords are not stored in `coin` JSON.
+ */
+export function generateCoinWithSharedSecretHex(shared_x_hex: string, shared_y_hex: string, amount: bigint): any;
+
+/**
+ * Convert snarkjs proof JSON to hex bytes for Soroban contract.
+ */
+export function proofToHex(proof_json: string): string;
+
+/**
+ * Convert snarkjs public signals JSON to hex bytes for Soroban contract.
+ */
+export function publicToHex(public_json: string): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly buildWithdrawMerkleWitness: (a: number, b: number, c: number, d: number, e: number) => void;
+    readonly calculateNullifierHash: (a: number, b: number, c: number) => void;
+    readonly ecdhEphemeralPublicKey: (a: number, b: number, c: number) => void;
+    readonly ecdhEphemeralPublicKeyFromScalarHex: (a: number, b: number, c: number) => void;
+    readonly ecdhSharedKey: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly generateCoin: (a: bigint) => number;
+    readonly generateCoinForDepositWithSharedHex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: bigint) => void;
+    readonly generateCoinFromDepositEphemeralScalarHex: (a: number, b: number, c: number, d: bigint) => void;
+    readonly generateCoinWithSharedSecretHex: (a: number, b: number, c: number, d: number, e: number, f: bigint) => void;
+    readonly proofToHex: (a: number, b: number, c: number) => void;
+    readonly publicToHex: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export: (a: number, b: number) => number;
+    readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_export3: (a: number) => void;
+    readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
+    readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;