@arcanetech/stellar-privacy-pool-zk-sdk 0.9.1-rc.0

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

@@ -0,0 +1,162 @@
+import type { TransactionAuditParams } from './transaction-audit';
+import type { WithdrawMerkleWitness } from './types';
+/** Matches `Transaction(20, 2, 2, publicNInputs, publicNOutputs, 4, 12, 6)` 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;
+export declare const TRANSACTION_N_AUDIT_SLOTS = 4;
+export declare const NOTE_AUDIT_LEN = 12;
+export declare const NOTE_OUTPUT_LEN = 6;
+/** 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 `escrowRecipientHi`. */
+    escrowRecipientHi?: string;
+    /** Decimal string, circom `escrowRecipientLo`. */
+    escrowRecipientLo?: string;
+    /** Decimal string, circom `sweepOutputOwnerPubX`. Zero off-sweep. */
+    sweepOutputOwnerPubX?: string;
+    /** Decimal string, circom `sweepOutputOwnerPubY`. Zero off-sweep. */
+    sweepOutputOwnerPubY?: string;
+    /** Decimal string, default owner scalar copied onto dummy withdraw slots. */
+    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(publicNInputs?: number, publicNOutputs?: number): TransactionPublicLegParams;
+export declare function padPublicLegs(legs: TransactionPublicLegParams, publicNInputs: number, publicNOutputs: number): 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];
+    /** BN254 Fr decimal; `0` for dummy slots. */
+    applicationId: string;
+    /** Owner BabyJubJub public key `[x, y]` as decimal strings. */
+    ownerPub: [string, string];
+    /** Per-input owner scalar. */
+    privKeyScalar: string;
+    paddingRandom: string;
+    escrowNonce: string;
+    recipientStellar: [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];
+    /** BN254 Fr decimal; `0` for dummy slots. */
+    applicationId: string;
+    /** Recipient public key `[x, y]` as decimal strings. */
+    recipientPublicKeys: [string, string];
+    escrowNonce?: string;
+    recipientStellar?: [string, string];
+}
+export type WithdrawSlot = WithdrawObject | 'dummy';
+export type DepositSlot = DepositObject | 'dummy';
+/** Witness calculator input for a `Transaction(20, nIns, nOuts, …)` instantiation. */
+export interface TransactionWitnessInput {
+    stateRoot: string;
+    withdrawAddressHi: string;
+    withdrawAddressLo: string;
+    escrowRecipientHi: string;
+    escrowRecipientLo: string;
+    sweepOutputOwnerPubX: string;
+    sweepOutputOwnerPubY: string;
+    privKeyScalars: string[];
+    ownerPubs: Array<[string, string]>;
+    paddingRandoms: string[];
+    withdrawnValues: string[];
+    withdrawnNullifiers: string[];
+    withdrawnSecrets: string[];
+    withdrawnAssets: Array<[string, string]>;
+    withdrawnEscrowNonces: string[];
+    inputRecipientStellar: Array<[string, string]>;
+    stateSiblings: string[][];
+    stateIndex: string[];
+    depositedValues: string[];
+    depositedNullifiers: string[];
+    depositedAssets: Array<[string, string]>;
+    depositedEphemeralKeyScalars: string[];
+    depositedRecipientPublicKeys: Array<[string, string]>;
+    depositedEscrowNonces: string[];
+    outputRecipientStellar: Array<[string, string]>;
+    publicWithdrawnAssets: Array<[string, string]>;
+    publicDepositedAssets: Array<[string, string]>;
+    publicDeposits: string[];
+    publicWithdrawals: string[];
+    inputApplicationIds: string[];
+    outputApplicationIds: string[];
+    auditEphemeralScalar: string;
+    noteAuditPublicKey: [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;
+};
+/**
+ * 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 resolveDepositsForWitness(depositSlots: [DepositSlot, DepositSlot], wasm: WasmEcdhPointFns): [DepositObject, DepositObject];
+export declare function padWithdrawSlots(slots: WithdrawSlot[], nIns: number): WithdrawSlot[];
+export declare function padDepositSlots(slots: DepositSlot[], nOuts: number): DepositSlot[];
+export declare function buildTransactionWitnessInput(publicParams: WithdrawalProofPublicParams, publicLegs: TransactionPublicLegParams, withdrawSlots: WithdrawSlot[], depositSlots: DepositSlot[], audit: TransactionAuditParams, wasm: WasmEcdhPointFns, dims?: {
+    nIns?: number;
+    nOuts?: number;
+    publicNInputs?: number;
+    publicNOutputs?: number;
+}): 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 + owner public key (hex) and matching scalar. */
+export declare function withdrawObjectFromMerkleWitness(witness: WithdrawMerkleWitness, ownerPubHex: {
+    x: string;
+    y: string;
+}, applicationId: string, privKeyScalar: string): WithdrawObject;

package/dist/witness.d.ts

@@ -0,0 +1,3 @@
+import type { TransactionWitnessInput } from './withdrawal-transaction-input';
+/** @deprecated Witness generation is in the main SDK WASM (`proveGroth16`). */
+export declare function generateWitness(_input: TransactionWitnessInput, _circuitWasm?: BufferSource, _wasmFileName?: string): Promise<Uint8Array>;

package/dist/zk-artifact-url.d.ts

@@ -0,0 +1,4 @@
+export declare const ZK_ARTIFACT_GITHUB_REPO = "Polynom-Labs/stellar-privacy-layer-contracts";
+export declare const ZK_SDK_PACKAGE_VERSION = "__ZK_SDK_PACKAGE_VERSION__";
+export declare function defaultZkArtifactBaseUrl(version?: string): string;
+export declare function trimArtifactBaseUrl(value: string): string;

package/dist/zk-layout.d.ts

@@ -0,0 +1,84 @@
+/** Off-chain ZK layout table. Must stay byte-identical to `libs/zk::ZkLayoutParams`. */
+export declare const LEGACY_ZK_NONCE = 0n;
+export declare const COMMITMENT_V2_ZK_NONCE = 2n;
+export declare const BINDING_ZK_NONCE = 3n;
+export declare const SIX_BY_SIX_ZK_NONCE = 6n;
+export declare const SIX_BY_SIX_BINDING_ZK_NONCE = 7n;
+export declare const LEGACY_PUBLIC_INPUT_PREFIX_LEN = 5;
+export declare const V2_PUBLIC_INPUT_PREFIX_LEN = 7;
+export declare const NOTE_AUDIT_LEN = 12;
+export declare const NOTE_OUTPUT_LEN = 6;
+export type CircuitProfileName = '2x2' | '6x6';
+export declare enum BundledZkCircuit {
+    TwoByTwo = "2x2",
+    SixBySix = "6x6"
+}
+export interface ZkCircuitLayoutFields {
+    nIns: number;
+    nOuts: number;
+    publicNInputs: number;
+    publicNOutputs: number;
+}
+export type BundledZkCircuitConfig = ZkCircuitLayoutFields & {
+    circuit: BundledZkCircuit;
+};
+export type DevZkCircuitConfig = ZkCircuitLayoutFields & {
+    circuitGraph: BufferSource;
+    r1cs: BufferSource;
+    provingKey: BufferSource;
+    zkey?: BufferSource;
+};
+export type ZkCircuitConfig = BundledZkCircuitConfig | DevZkCircuitConfig;
+export declare function isDevZkCircuitConfig(config: ZkCircuitConfig): config is DevZkCircuitConfig;
+export declare const DEFAULT_ZK_CONFIG_NONCE = 3n;
+export declare const DEFAULT_ZK_CIRCUITS: Record<string, BundledZkCircuitConfig>;
+export declare function layoutFromCircuitConfig(config: ZkCircuitConfig): ZkLayoutParams;
+export declare function resolveZkCircuitConfig(zkCircuits: Record<string, ZkCircuitConfig> | undefined, zkConfigNonce: bigint | undefined): {
+    nonce: bigint;
+    config: ZkCircuitConfig;
+};
+export declare function bundledCircuitFileNames(circuit: BundledZkCircuit): {
+    graphFileName: string;
+    r1csFileName: string;
+    provingKeyFileName: string;
+    verificationKeyFileName: string;
+    zkeyFileName: string;
+};
+export interface ZkLayoutParams {
+    nIns: number;
+    nOuts: number;
+    publicNInputs: number;
+    publicNOutputs: number;
+    nAuditSlots: number;
+    noteAuditLen: number;
+    noteOutputLen: number;
+    publicInputPrefixLen: number;
+    auditOffset: number;
+    outputNoteOffset: number;
+}
+export interface CircuitProfile {
+    name: CircuitProfileName;
+    nonce: bigint;
+    layout: ZkLayoutParams;
+    wasmFileName: string;
+    zkeyFileName: string;
+}
+export declare function zkLayoutFromShape(nIns: number, nOuts: number, publicNInputs: number, publicNOutputs: number, nAuditSlots: number, noteAuditLen: number, noteOutputLen: number, publicInputPrefixLen?: number): ZkLayoutParams;
+export declare function zkLayoutFromShapeBinding(nIns: number, nOuts: number, publicNInputs: number, publicNOutputs: number, nAuditSlots: number, noteAuditLen: number, noteOutputLen: number): ZkLayoutParams;
+export declare function ciphertextsInPublicSignals(layout: ZkLayoutParams): boolean;
+export declare function ciphertextFieldCount(layout: ZkLayoutParams): number;
+export declare function auditEphemeralPublicKeyCount(layout: ZkLayoutParams): number;
+export declare function indexAuditEphemeralPublicKeys(layout: ZkLayoutParams): number;
+export declare function indexAuditTags(layout: ZkLayoutParams): number;
+export declare function indexOutputNoteTags(layout: ZkLayoutParams): number;
+export declare function publicOutputsLen(layout: ZkLayoutParams): number;
+export declare function totalPublicSignals(layout: ZkLayoutParams): number;
+export declare function stateRootIndex(layout: ZkLayoutParams): number;
+export declare function legacyOwnerBoundLayout(): ZkLayoutParams;
+export declare function standardLayout(): ZkLayoutParams;
+export declare function sixBySixLayout(): ZkLayoutParams;
+export declare function standardBindingLayout(): ZkLayoutParams;
+export declare function sixBySixBindingLayout(): ZkLayoutParams;
+export declare function layoutForKnownNonce(nonce: bigint): ZkLayoutParams;
+export declare function circuitProfileFromName(name: string): CircuitProfile;
+export declare function circuitProfileFromNonce(nonce: bigint): CircuitProfile;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "version": "0.9.1-rc.0",
+  "name": "@arcanetech/stellar-privacy-pool-zk-sdk",
+  "description": "Client SDK for Soroban Privacy Pools - coin generation, withdrawal proofs, and proof serialization",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./sdk.wasm": "./pkg/client_sdk_wasm_bg.wasm",
+    "./pkg/client_sdk_wasm.js": "./pkg/client_sdk_wasm.js"
+  },
+  "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"
+  },
+  "files": [
+    "dist/",
+    "pkg/"
+  ],
+  "scripts": {
+    "build:wasm": "cd crate && wasm-pack build --target web --out-dir ../pkg",
+    "build:ts": "rollup -c",
+    "build": "rollup -c",
+    "cli": "node dist/cli.js",
+    "test:kyt": "node test/kyt-flow-atomic.mjs && node test/kyt-public-leg-context.mjs && node test/kyt-passage-id-auth.mjs && node test/derived-escrow-key.mjs && node test/spend-scalar-domain.mjs && node test/eighteen-decimal-value.mjs && node test/zk-artifact-url.mjs && node test/no-onboarding-exports.mjs && node test/owner-bound-witness-check.mjs && node test/six-by-six-layout.mjs && node test/six-by-six-witness-proof.mjs",
+    "test:output-note": "node test/output-note-encryption.mjs"
+  },
+  "dependencies": {
+    "@noble/hashes": "^2.2.0",
+    "@stellar/stellar-sdk": "^16.0.1",
+    "bech32": "^2.0.0",
+    "circomlibjs": "^0.1.7",
+    "ffjavascript": "^0.3.0"
+  },
+  "devDependencies": {
+    "@rollup/plugin-alias": "^5.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",
+    "tslib": "^2.6.0",
+    "typescript": "^5.0.0"
+  }
+}

package/pkg/client_sdk_wasm.d.ts

@@ -0,0 +1,120 @@
+/* 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 owner-bound nullifier hash from nullifier and spend-scalar decimal strings.
+ * Returns hex string (0x...)
+ */
+export function calculateNullifierHash(nullifier_decimal: string, priv_key_scalar_decimal: string): string;
+
+/**
+ * `R = Poseidon255(2)(hi, lo)`; `scalar` is the raw Poseidon hash when it is
+ * already in `(0, BabyJub subgroup order)`. Out-of-range hashes fail so the
+ * caller can rejection-sample a new nonce.
+ */
+export function derivedEscrowKey(nonce_decimal: string, recipient_hi_decimal: string, recipient_lo_decimal: string): any;
+
+/**
+ * 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 owner public-key field elements.
+ * `amount_decimal` is an arbitrary-precision decimal field element (never JS `number`).
+ * `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_decimal: string, asset_hi_decimal: string, asset_lo_decimal: string, application_id_decimal: string): any;
+
+/**
+ * `Poseidon₁(scalar)` secret + recipient owner public key (hex), matching an aligned deposit witness.
+ */
+export function generateCoinForDepositWithOwnerPubHex(scalar_hex: string, owner_x_hex: string, owner_y_hex: string, amount_decimal: string, asset_hi_decimal: string, asset_lo_decimal: string, application_id_decimal: string): 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_decimal: string, asset_hi_decimal: string, asset_lo_decimal: string, application_id_decimal: string): any;
+
+/**
+ * Same as `generateCoin`, but commitment uses the given owner public key (64-char hex coords).
+ */
+export function generateCoinWithOwnerPubHex(owner_x_hex: string, owner_y_hex: string, amount_decimal: string, asset_hi_decimal: string, asset_lo_decimal: string, application_id_decimal: string): any;
+
+/**
+ * Convert snarkjs proof JSON to hex bytes for Soroban contract.
+ */
+export function proofToHex(proof_json: string): string;
+
+/**
+ * Graph witness + arkworks Groth16 prove. Returns `{ proof_hex, public_hex }`.
+ */
+export function proveGroth16(graph: Uint8Array, proving_key: Uint8Array, r1cs: Uint8Array, inputs_json: string): any;
+
+/**
+ * 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, d: number, e: number) => void;
+    readonly derivedEscrowKey: (a: number, b: number, c: number, d: number, e: number, f: number, g: 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: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly generateCoinForDepositWithOwnerPubHex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number) => void;
+    readonly generateCoinFromDepositEphemeralScalarHex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
+    readonly generateCoinWithOwnerPubHex: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number) => void;
+    readonly proofToHex: (a: number, b: number, c: number) => void;
+    readonly proveGroth16: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: 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>;