/** * Obelysk Privacy SDK * * Complete privacy-preserving functionality for BitSage including: * - ElGamal encryption over STARK curve * - Confidential Swap integration * - STWO proof generation (via Rust node) * - Private SAGE token purchases * * @example * ```typescript * import { ObelyskPrivacy, ConfidentialSwapClient } from '@obelyzk/sdk/privacy'; * * // Initialize privacy client * const privacy = new ObelyskPrivacy(); * * // Generate encryption key pair * const keyPair = privacy.generateKeyPair(); * * // Encrypt an amount * const encrypted = privacy.encrypt(1000000n, keyPair.publicKey); * * // Create a confidential swap order * const swapClient = new ConfidentialSwapClient({ apiUrl: 'https://api.bitsage.network' }); * const order = await swapClient.createPrivateOrder({ * giveAsset: AssetId.SAGE, * wantAsset: AssetId.STRK, * giveAmount: 100000n * 10n ** 18n, * wantAmount: 20000n * 10n ** 18n, * }); * ``` */ /** * STARK field prime: P = 2^251 + 17 * 2^192 + 1 */ declare const FIELD_PRIME: bigint; /** * STARK curve order (number of points on the curve) */ declare const CURVE_ORDER: bigint; /** * Generator point G (STARK curve standard generator) */ declare const GENERATOR_G: { x: bigint; y: bigint; }; /** * Second generator point H (for Pedersen commitments) * Generated as hash_to_curve("OBELYSK_H") */ declare const GENERATOR_H: { x: bigint; y: bigint; }; /** * Elliptic curve point */ interface ECPoint { x: bigint; y: bigint; } /** * ElGamal key pair */ interface ElGamalKeyPair { /** Private key (scalar) */ privateKey: bigint; /** Public key (EC point) */ publicKey: ECPoint; } /** * ElGamal ciphertext: (c1, c2) = (r*G, M + r*PK) */ interface ElGamalCiphertext { /** First component: r*G */ c1: ECPoint; /** Second component: amount*H + r*PK */ c2: ECPoint; } /** * Schnorr encryption proof */ interface EncryptionProof { /** Commitment point */ commitment: ECPoint; /** Fiat-Shamir challenge */ challenge: bigint; /** Response */ response: bigint; /** Range proof hash (for proving amount is in valid range) */ rangeProofHash: bigint; } /** * Asset identifier */ declare enum AssetId { SAGE = 0, USDC = 1, STRK = 2, ETH = 3, BTC = 4 } /** * Confidential order for swaps */ interface ConfidentialOrder { orderId: bigint; maker: string; giveAsset: AssetId; wantAsset: AssetId; encryptedGive: ElGamalCiphertext; encryptedWant: ElGamalCiphertext; rateCommitment: bigint; minFillPct: number; expiresAt: number; } /** * Swap proof bundle */ interface SwapProofBundle { rangeProof: RangeProof; rateProof: RateProof; balanceProof: BalanceProof; } /** * Range proof (proves amount is in [0, 2^numBits)) */ interface RangeProof { bitCommitments: ECPoint[]; challenge: bigint; responses: bigint[]; numBits: number; } /** * Rate compliance proof */ interface RateProof { rateCommitment: ECPoint; challenge: bigint; responseGive: bigint; responseRate: bigint; responseBlinding: bigint; } /** * Balance sufficiency proof */ interface BalanceProof { balanceCommitment: ECPoint; challenge: bigint; response: bigint; } /** * Modular addition: (a + b) mod n */ declare function addMod(a: bigint, b: bigint, n?: bigint): bigint; /** * Modular subtraction: (a - b) mod n */ declare function subMod(a: bigint, b: bigint, n?: bigint): bigint; /** * Modular multiplication: (a * b) mod n */ declare function mulMod(a: bigint, b: bigint, n?: bigint): bigint; /** * Modular exponentiation: base^exp mod n */ declare function powMod(base: bigint, exp: bigint, n?: bigint): bigint; /** * Modular inverse: a^(-1) mod n (using extended Euclidean algorithm) */ declare function invMod(a: bigint, n?: bigint): bigint; /** * Check if a point is the identity (point at infinity) */ declare function isIdentity(p: ECPoint): boolean; /** * Point doubling: 2P */ declare function ecDouble(p: ECPoint): ECPoint; /** * Point addition: P + Q */ declare function ecAdd(p: ECPoint, q: ECPoint): ECPoint; /** * Scalar multiplication: k * P using double-and-add */ declare function ecMul(k: bigint, p: ECPoint): ECPoint; /** * Generate cryptographically secure random bytes */ declare function randomBytes(length: number): Uint8Array; /** * Generate a random scalar in range [1, CURVE_ORDER) */ declare function randomScalar(): bigint; /** * Poseidon hash (simplified - use cairo-rs or starknet.js for production) * This is a placeholder that uses a simpler hash for SDK purposes */ declare function poseidonHash(...inputs: bigint[]): bigint; /** * Obelysk Privacy - ElGamal encryption and proof generation */ declare class ObelyskPrivacy { private apiUrl; private _keyPair?; constructor(config?: { apiUrl?: string; }); /** * Set a key pair from a known private key */ setKeyPair(privateKey: bigint): ElGamalKeyPair; /** * Get the current key pair (generates one if not set) */ getKeyPair(): ElGamalKeyPair; /** * Generate a new ElGamal key pair */ generateKeyPair(): ElGamalKeyPair; /** * Derive public key from private key */ derivePublicKey(privateKey: bigint): ECPoint; /** * Encrypt an amount using ElGamal * * Ciphertext: (r*G, amount*H + r*PK) * - r is random scalar * - G is generator * - H is second generator (for amount encoding) * - PK is recipient public key * * @param amount - Amount to encrypt * @param publicKey - Recipient's public key * @param randomness - Optional randomness (auto-generated if not provided) */ encrypt(amount: bigint, publicKey: ECPoint, randomness?: bigint): ElGamalCiphertext; /** * Decrypt an ElGamal ciphertext * * Decryption: c2 - privateKey * c1 = amount * H * Then solve discrete log to recover amount (only works for small amounts) * * @param ciphertext - Encrypted ciphertext * @param privateKey - Decryption private key * @param maxAmount - Maximum expected amount (for discrete log search) */ decrypt(ciphertext: ElGamalCiphertext, privateKey: bigint, maxAmount?: bigint): bigint | null; /** * Add two ciphertexts homomorphically * Enc(a) + Enc(b) = Enc(a + b) */ homomorphicAdd(ciphertext1: ElGamalCiphertext, ciphertext2: ElGamalCiphertext): ElGamalCiphertext; /** * Scalar multiplication of ciphertext * k * Enc(a) = Enc(k * a) */ homomorphicMul(ciphertext: ElGamalCiphertext, scalar: bigint): ElGamalCiphertext; /** * Create Schnorr encryption proof * Proves knowledge of (amount, randomness) such that ciphertext encrypts amount */ createEncryptionProof(amount: bigint, randomness: bigint, publicKey: ECPoint): EncryptionProof; /** * Verify Schnorr encryption proof */ verifyEncryptionProof(ciphertext: ElGamalCiphertext, proof: EncryptionProof, publicKey: ECPoint): boolean; /** * Create a Pedersen commitment: amount * G + blinding * H */ pedersenCommit(amount: bigint, blinding: bigint): ECPoint; } /** * Configuration for Confidential Swap client */ interface ConfidentialSwapConfig { /** API URL for proof generation */ apiUrl: string; /** Confidential Swap contract address */ contractAddress?: string; /** Starknet RPC URL */ rpcUrl?: string; } /** * Create order request */ interface CreateOrderRequest { giveAsset: AssetId; wantAsset: AssetId; giveAmount: bigint; wantAmount: bigint; expiresIn?: number; } /** * Order creation response */ interface CreateOrderResponse { orderId: bigint; encryptedGive: ElGamalCiphertext; encryptedWant: ElGamalCiphertext; rateCommitment: bigint; proofs: SwapProofBundle; transactionHash?: string; } /** * Confidential Swap Client * * Enables privacy-preserving token swaps using ElGamal encryption and STWO proofs */ declare class ConfidentialSwapClient { private config; private privacy; private keyPair; constructor(config?: Partial); /** * Initialize with a key pair for encryption */ withKeyPair(keyPair: ElGamalKeyPair): this; /** * Generate a new key pair and initialize */ generateKeyPair(): ElGamalKeyPair; /** * Create a private swap order * * @param request - Order details * @returns Order with encrypted amounts and proofs */ createPrivateOrder(request: CreateOrderRequest): Promise; /** * Request STWO proofs from Rust node */ private requestProofs; /** * Parse proof response from API */ private parseProofResponse; /** * Generate proofs locally (fallback) */ private generateLocalProofs; /** * Get encrypted balance for an address */ getEncryptedBalance(address: string, asset: AssetId): Promise; /** * Decrypt a balance using local key */ decryptBalance(encrypted: ElGamalCiphertext, maxAmount?: bigint): bigint | null; /** * Get available orders from the contract */ getAvailableOrders(asset?: AssetId): Promise; /** * Get order by ID */ getOrder(orderId: bigint): Promise; /** * Take an existing order (buyer-side) * * @param orderId - ID of the order to take * @param giveAmount - Amount buyer is paying * @param wantAmount - Amount buyer wants to receive * @returns Take order response with proofs */ takeOrder(orderId: bigint, giveAmount: bigint, wantAmount: bigint): Promise; /** * Get swap history for an address */ getSwapHistory(address: string): Promise; /** * Decrypt a swap to reveal amounts (for your own swaps only) */ decryptSwap(encryptedGive: ElGamalCiphertext, encryptedWant: ElGamalCiphertext, maxAmount?: bigint): { giveAmount: bigint | null; wantAmount: bigint | null; }; } /** * Take order response */ interface TakeOrderResponse { success: boolean; orderId: bigint; matchId: bigint; encryptedGive: ElGamalCiphertext; encryptedWant: ElGamalCiphertext; proofs: SwapProofBundle; transactionHash?: string; error?: string; } /** * Swap history entry */ interface SwapHistoryEntry { orderId: bigint; matchId: bigint; role: 'maker' | 'taker'; giveAsset: AssetId; wantAsset: AssetId; timestamp: number; transactionHash: string; } export { AssetId, type BalanceProof, CURVE_ORDER, type ConfidentialOrder, ConfidentialSwapClient, type ConfidentialSwapConfig, type CreateOrderRequest, type CreateOrderResponse, type ECPoint, type ElGamalCiphertext, type ElGamalKeyPair, type EncryptionProof, FIELD_PRIME, GENERATOR_G, GENERATOR_H, ObelyskPrivacy, type RangeProof, type RateProof, type SwapHistoryEntry, type SwapProofBundle, type TakeOrderResponse, addMod, ObelyskPrivacy as default, ecAdd, ecDouble, ecMul, invMod, isIdentity, mulMod, poseidonHash, powMod, randomBytes, randomScalar, subMod };