@auditable/privacy-pool-zk-sdk 0.0.2-rc.9 → 0.4.0

package/dist/sdk.d.ts

@@ -1,4 +1,8 @@
-import type { CoinData, GeneratedCoin, SDKOptions, SnarkInput, StateFile, WithdrawResult } from './types';
+import { type DecodedDepositorSharedSecretPreimage, type DecodedEphemeralKey, type EncodedDepositorSharedSecretPreimage, type EncodedEphemeralKey } from './ephemeral-key';
+import { type SharedSecret } from './shared-secret';
+import type { DecodedRecipientSharedSecretPreimage } from './stealth-address';
+import type { CoinData, GeneratedCoin, SDKOptions, StateFile, WithdrawMerkleWitness, WithdrawResult } from './types';
+import { type DepositSlot, type TransactionPublicLegParams, type WithdrawalProofPublicParams, type WithdrawSlot } from './withdrawal-transaction-input';
 export declare class PrivacyPoolSDK {
     private wasm;
     private options;
@@ -18,13 +22,55 @@ export declare class PrivacyPoolSDK {
      */
     static init(options?: SDKOptions): Promise<PrivacyPoolSDK>;
     /**
-     * Generate a new coin with random nullifier and secret.
+     * Uniform 32-byte scalar as lowercase hex (Web Crypto). Same in browser and Node 19+.
      */
-    generateCoin(): GeneratedCoin;
+    static generateRandomScalarHex32(): string;
     /**
-     * Generate withdrawal SNARK input from coin data and state.
+     * Text to sign with a Stellar wallet for stealth derivation (UTF-8). No WASM required.
      */
-    generateWithdrawalInput(coin: CoinData, state: StateFile): SnarkInput;
+    static buildStealthAddressSignMessage(address: string, nonce?: string): string;
+    /**
+     * Generate a new coin with random nullifier, secret, and random shared-secret field elements (dev / self-contained tests).
+     * @param amount Stroops encoded as `bigint` or integer `number` (WASM `u64`).
+     * @param assetHiDecimal / assetLoDecimal Decimal Fr strings for Stellar asset contract id (two limbs).
+     */
+    generateCoin(amount: bigint | number, assetHiDecimal: string, assetLoDecimal: string): GeneratedCoin;
+    /**
+     * Generate a coin with the same commitment shape as on-chain deposit: pass `ecdhSharedKey` output (hex x, y).
+     * @param amount Stroops (`bigint` | `number`).
+     */
+    generateCoinWithSharedSecret(shared: SharedSecret, amount: bigint | number, assetHiDecimal: string, assetLoDecimal: string): GeneratedCoin;
+    /**
+     * Coin for a depositor `ephemeralKeyScalar` (32-byte hex): `coin.secret = Poseidon255(1)(scalar)` as in `deposit.circom`.
+     * @param amount Stroops (`bigint` | `number`).
+     */
+    generateCoinFromDepositEphemeralScalarHex(scalarHex: string, amount: bigint | number, assetHiDecimal: string, assetLoDecimal: string): GeneratedCoin;
+    /**
+     * Aligned deposit coin: `secret = Poseidon₁(scalar)` and ECDH shared key from hex coords (e.g. `ecdhSharedKey(scalar, recipient_x, recipient_y)`).
+     * @param amount Stroops (`bigint` | `number`).
+     */
+    generateCoinForDepositWithSharedHex(scalarHex: string, sharedXHex: string, sharedYHex: string, amount: bigint | number, assetHiDecimal: string, assetLoDecimal: string): GeneratedCoin;
+    /**
+     * Merkle root, path, and coin fields for the first withdraw leg (Rust LeanIMT + Poseidon).
+     */
+    buildWithdrawMerkleWitness(coin: CoinData, state: StateFile): WithdrawMerkleWitness;
+    /**
+     * Full `Transaction(20,2,2)` withdrawal proof: one real withdraw + dummies, using coin/state and depositor ECDH point (hex).
+     *
+     * Optional **partial public withdraw**: spend the full coin commitment `coin.value` (V), send `publicWithdrawStroops` (W) to the
+     * Stellar receiver, and re-deposit the remainder (V−W) as a new private note to `changeRecipientStealthAddress` (same circuit balance).
+     */
+    proveWithdrawal(coin: CoinData, state: StateFile, params: {
+        withdrawAddressHi: string;
+        withdrawAddressLo: string;
+        privKeyScalar: string;
+        ephemeralXHex: string;
+        ephemeralYHex: string;
+        /** If set, public leg amount W (stroops). Must satisfy 0 < W < V. Remainder (V−W) stays in the pool as a new commitment. */
+        publicWithdrawStroops?: bigint;
+        /** Required when `publicWithdrawStroops` is set: stealth recipient for the change note (typically same as deposit). */
+        changeRecipientStealthAddress?: string;
+    }): Promise<WithdrawResult>;
     /**
      * Convert a snarkjs proof JSON to hex bytes for Soroban.
      */
@@ -34,14 +80,38 @@ export declare class PrivacyPoolSDK {
      */
     publicToHex(publicSignals: string[]): string;
     /**
-     * Full withdrawal flow: generate input -> witness -> proof -> serialize.
-     * Returns proof_hex and public_hex ready for Soroban contract call.
+     * BabyJubJub ephemeral point from a 32-byte scalar (hex). For custom {@link WithdrawObject} / tests.
      */
-    prepareWithdrawal(coin: CoinData, state: StateFile): Promise<WithdrawResult>;
+    ecdhEphemeralPublicKeyFromScalarHex(scalarHex: string): {
+        x: string;
+        y: string;
+    };
+    /** Circuit `ECDH`: scalar (32-byte hex) × recipient BabyJub point → shared key hex coords. */
+    ecdhSharedKey(scalarHex: string, recipientPubXHex: string, recipientPubYHex: string): SharedSecret;
+    /**
+     * `Transaction(20,2,2)` proof from high-level legs: maps to witness input (incl. `"dummy"` ECDH via WASM), then Groth16 → Soroban hex.
+     *
+     * @param publicParams Public inputs: `stateRoot`, `withdrawAddressHi` / `withdrawAddressLo`, `privKeyScalar` (decimal field strings).
+     * @param publicLegs Public token legs (`publicWithdrawnAssets`, `publicDepositedAssets`, `publicDeposits`, `publicWithdrawals`).
+     * @param withdraws Exactly two withdraw slots (`WithdrawObject` or `"dummy"`).
+     * @param deposits Exactly two deposit slots (`DepositObject` or `"dummy"`).
+     */
+    proveTransaction(publicParams: WithdrawalProofPublicParams, publicLegs: TransactionPublicLegParams, withdraws: [WithdrawSlot, WithdrawSlot], deposits: [DepositSlot, DepositSlot]): Promise<WithdrawResult>;
     /**
      * Calculate nullifier hash: Poseidon(nullifier)
      * @param nullifier Nullifier decimal string from coin data
      * @returns Hex string (0x...) of the hash bytes
      */
     calculateNullifierHash(nullifier: string): string;
+    /**
+     * Ed25519 signature from signing {@link buildStealthAddressSignMessage}: **128 hex chars** (optional `0x`)
+     * or **base64** (64 raw bytes after decode). `SHA-256(signature bytes)` → scalar → ECDH → `stpl1` Bech32.
+     */
+    generateStealthAddressFromStellarSignature(signature: string): Promise<string>;
+    encodeDecodedEphemeralKey(decoded: DecodedEphemeralKey): EncodedEphemeralKey;
+    decodeDecodedEphemeralKey(encoded: EncodedEphemeralKey): DecodedEphemeralKey;
+    encodeDepositorSharedSecretPreimage(decoded: DecodedDepositorSharedSecretPreimage): EncodedDepositorSharedSecretPreimage;
+    decodeDepositorSharedSecretPreimage(encoded: EncodedDepositorSharedSecretPreimage): DecodedDepositorSharedSecretPreimage;
+    sharedSecretFromDepositorPreimage(preimage: DecodedDepositorSharedSecretPreimage): SharedSecret;
+    sharedSecretFromRecipientPreimage(preimage: DecodedRecipientSharedSecretPreimage): SharedSecret;
 }

package/dist/shared-secret.d.ts

@@ -0,0 +1,24 @@
+import type { DecodedDepositorSharedSecretPreimage, DecodedEphemeralKey } from './ephemeral-key';
+import type { DecodedRecipientSharedSecretPreimage, Hex } from './stealth-address';
+/** ECDH shared key coordinates (`ecdh_shared_key` / circuit `ECDH` output). */
+export interface SharedSecret {
+    x: Hex;
+    y: Hex;
+}
+/** Withdrawer-side material: recipient private scalar ‖ depositor’s ephemeral point. */
+export interface DecodedWithdrawerSharedSecret {
+    recipientScalar: Hex;
+    ephemeralKey: DecodedEphemeralKey;
+}
+export type EcdhSharedKeyFn = (privHex64: string, pubXHex64: string, pubYHex64: string) => {
+    x: string;
+    y: string;
+};
+/**
+ * Depositor: `randomNonceScalar * recipientStealthPoint` (same as circom `ECDH` with depositor scalar).
+ */
+export declare function sharedSecretFromDepositorPreimage(ecdhShared: EcdhSharedKeyFn, preimage: DecodedDepositorSharedSecretPreimage): SharedSecret;
+/**
+ * Recipient: `recipientScalar * ephemeralKey` (same shared point as depositor path when keys match).
+ */
+export declare function sharedSecretFromRecipientPreimage(ecdhShared: EcdhSharedKeyFn, preimage: DecodedRecipientSharedSecretPreimage): SharedSecret;

package/dist/stealth-address.d.ts

@@ -0,0 +1,23 @@
+import type { DecodedEphemeralKey } from './ephemeral-key';
+/** Lowercase hex string (optional `0x` prefix when parsing). */
+export type Hex = string;
+export type StealthAddress = string;
+export interface DecodedStealthAddress {
+    x: Hex;
+    y: Hex;
+}
+/** Withdrawer preimage: recipient scalar ‖ depositor-revealed ephemeral point. */
+export interface DecodedRecipientSharedSecretPreimage {
+    ephemeralKey: DecodedEphemeralKey;
+    recipientScalar: Hex;
+}
+export declare const STEALTH_ADDRESS_HRP: "stpl1";
+/**
+ * Encodes `x || y` as Bech32 (BIP-173) with human-readable part {@link STEALTH_ADDRESS_HRP} (`stpl1`).
+ * `x` and `y` must have the same byte length so decoding can split the payload in half.
+ */
+export declare function encodeStealthAddress(decoded: DecodedStealthAddress): StealthAddress;
+/**
+ * Decodes a `stpl1` Bech32 stealth address into `x` and `y` (each half of the payload, as lowercase hex).
+ */
+export declare function decodeStealthAddress(address: StealthAddress): DecodedStealthAddress;

package/dist/stealth-sign-message.d.ts

@@ -0,0 +1,7 @@
+/** Default nonce when deriving the wallet sign-in message. */
+export declare const DEFAULT_STEALTH_SIGN_NONCE = "main address";
+/**
+ * Plaintext for Stellar wallet message signing (stealth address derivation).
+ * Sign the exact bytes of this string (UTF-8) with the stellar account key.
+ */
+export declare function buildStealthAddressSignMessage(address: string, nonce?: string): string;

package/dist/stealth-signature.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Ed25519 signature as **128 hex chars** (optional `0x`) or **base64** (typically 88 chars for 64 bytes, whitespace ignored).
+ */
+export declare function parseStellarEd25519SignatureRaw(input: string): Uint8Array;
+/** SHA-256 via Web Crypto only (`crypto.subtle`) — works in browsers and Node 19+ (global `crypto`). */
+export declare function sha256(data: Uint8Array): Promise<Uint8Array>;
+/**
+ * Stellar Ed25519 signature (hex or base64) → SHA-256(signature bytes) → scalar → WASM ECDH (no UTF-8 seed hash).
+ */
+export declare function stealthAddressFromStellarSignature(ecdhFromScalarHex: (scalarHex64: string) => {
+    x: string;
+    y: string;
+}, encodeStealth: (decoded: {
+    x: string;
+    y: string;
+}) => string, signature: string): Promise<string>;
+/**
+ * SHA-256(signature) as 32-byte BE integer, truncated to **253 bits** (same effective scalar as
+ * `libs/cryptography` `scalar_mul_253` / circom `Num2Bits(253)`), decimal for `privKeyScalar`.
+ */
+export declare function privKeyScalarDecimalFromStellarSignature(signature: string): Promise<string>;

package/dist/types.d.ts

@@ -3,18 +3,36 @@ export interface CoinData {
     nullifier: string;
     secret: string;
     commitment: string;
+    /** Decimal Fr strings for Stellar asset contract id (`asset[0]`, `asset[1]` in `commitment.circom`). */
+    asset_hi: string;
+    asset_lo: string;
 }
 export interface GeneratedCoin {
     coin: CoinData;
     commitment_hex: string;
+    /** 64-char lowercase hex (no `0x`), Fr big-endian for audit `precommitement`. */
+    precommitement_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;
+    /** `[asset_hi, asset_lo]` decimal Fr strings (Stellar asset contract id). */
+    withdrawnAsset: [string, 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,117 @@
+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;
+/** Must match `Transaction(..., publicNInputs, publicNOutputs)` and contract `get_public_slot_config`. */
+export declare const TRANSACTION_PUBLIC_N_INPUTS = 1;
+export declare const TRANSACTION_PUBLIC_N_OUTPUTS = 1;
+/** 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;
+}
+/** Public accounting legs (`publicWithdrawnAssets`, `publicDepositedAssets`, `publicDeposits`, `publicWithdrawals`). */
+export interface TransactionPublicLegParams {
+    publicWithdrawnAssets: Array<[string, string]>;
+    publicDepositedAssets: Array<[string, string]>;
+    publicDeposits: string[];
+    publicWithdrawals: string[];
+}
+/** All-zero public legs (private-only pool moves). */
+export declare function zeroPublicLegs(): TransactionPublicLegParams;
+/** Real withdraw leg; coordinates are decimal field strings (same as `CoinData`). */
+export interface WithdrawObject {
+    value: string;
+    nullifier: string;
+    secret: string;
+    /** Asset contract id as two decimal Fr strings (`asset[0]`, `asset[1]`). */
+    asset: [string, 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;
+    /** Asset contract id as two decimal Fr strings. */
+    asset: [string, 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,publicNInputs,publicNOutputs)`. */
+export interface TransactionWitnessInput {
+    stateRoot: string;
+    withdrawAddressHi: string;
+    withdrawAddressLo: string;
+    privKeyScalar: string;
+    withdrawnValues: [string, string];
+    withdrawnNullifiers: [string, string];
+    withdrawnSecrets: [string, string];
+    withdrawnAssets: [[string, string], [string, string]];
+    ephemeralKeys: [[string, string], [string, string]];
+    stateSiblings: [string[], string[]];
+    stateIndex: [string, string];
+    depositedValues: [string, string];
+    depositedNullifiers: [string, string];
+    depositedAssets: [[string, string], [string, string]];
+    depositedEphemeralKeyScalars: [string, string];
+    depositedRecipientPublicKeys: [[string, string], [string, string]];
+    publicWithdrawnAssets: Array<[string, string]>;
+    publicDepositedAssets: Array<[string, string]>;
+    publicDeposits: string[];
+    publicWithdrawals: 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;
+};
+/**
+ * Stellar contract id (`C…`) → two circom field decimals for `asset[0]`, `asset[1]` (same 32-byte split as accounts).
+ */
+export declare function stellarContractAddressToAssetFrDecimals(address: string): [string, 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, publicLegs: TransactionPublicLegParams, 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.9",
+  "version": "0.4.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,20 @@
     "cli": "node dist/cli.js"
   },
   "dependencies": {
+    "@stellar/stellar-base": "^13.0.0",
+    "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

@@ -1,62 +1,106 @@
 /* tslint:disable */
 /* eslint-disable */
+
 /**
- * Convert snarkjs public signals JSON to hex bytes for Soroban contract.
+ * Merkle root, path, and coin field strings for the first withdraw leg (JSON → JSON).
  */
-export function publicToHex(public_json: string): string;
+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`.
+ * `asset_hi_decimal` / `asset_lo_decimal` are decimal Fr strings for the Stellar asset contract id (two limbs).
+ * Returns JSON: { coin: { value, nullifier, secret, commitment, asset_hi, asset_lo }, commitment_hex, precommitement_hex }
+ */
+export function generateCoin(amount: bigint, asset_hi_decimal: string, asset_lo_decimal: string): 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, asset_hi_decimal: string, asset_lo_decimal: string): any;
+
 /**
- * Generate withdrawal SNARK input from coin and state JSON strings.
- * Returns JSON string of SnarkInput.
+ * `secret` in coin = `Poseidon255(1)(scalar)` per `deposit.circom`; scalar is 32-byte hex (64 chars, optional `0x`).
  */
-export function generateWithdrawalInput(coin_json: string, state_json: string): string;
+export function generateCoinFromDepositEphemeralScalarHex(scalar_hex: string, amount: bigint, asset_hi_decimal: string, asset_lo_decimal: string): any;
+
 /**
- * Generate a new coin with random nullifier and secret.
- * Returns JSON: { coin: { value, nullifier, secret, commitment }, commitment_hex }
+ * 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 generateCoin(): any;
+export function generateCoinWithSharedSecretHex(shared_x_hex: string, shared_y_hex: string, amount: bigint, asset_hi_decimal: string, asset_lo_decimal: string): 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 calculateNullifierHash: (a: number, b: number, c: number) => void;
-  readonly generateCoin: () => number;
-  readonly generateWithdrawalInput: (a: number, b: number, c: number, d: number, e: number) => void;
-  readonly proofToHex: (a: number, b: number, c: number) => void;
-  readonly publicToHex: (a: number, b: number, c: number) => void;
-  readonly __wbindgen_export_0: (a: number) => void;
-  readonly __wbindgen_export_1: (a: number, b: number) => number;
-  readonly __wbindgen_export_2: (a: number, b: number, c: number, d: number) => number;
-  readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
-  readonly __wbindgen_export_3: (a: number, b: number, c: number) => void;
+    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: number, b: bigint, c: number, d: number, e: number, f: number) => void;
+    readonly generateCoinForDepositWithSharedHex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: bigint, i: number, j: number, k: number, l: number) => void;
+    readonly generateCoinFromDepositEphemeralScalarHex: (a: number, b: number, c: number, d: bigint, e: number, f: number, g: number, h: number) => void;
+    readonly generateCoinWithSharedSecretHex: (a: number, b: number, c: number, d: number, e: number, f: bigint, g: number, h: number, i: number, j: number) => 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}
-*/
+ * 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>}
-*/
+ * 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>;