@obelyzk/sdk 0.5.0

package/dist/privacy/index.d.ts

@@ -0,0 +1,408 @@
+/**
+ * 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 '@bitsage/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<ConfidentialSwapConfig>);
+    /**
+     * 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<CreateOrderResponse>;
+    /**
+     * 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<ElGamalCiphertext | null>;
+    /**
+     * Decrypt a balance using local key
+     */
+    decryptBalance(encrypted: ElGamalCiphertext, maxAmount?: bigint): bigint | null;
+    /**
+     * Get available orders from the contract
+     */
+    getAvailableOrders(asset?: AssetId): Promise<ConfidentialOrder[]>;
+    /**
+     * Get order by ID
+     */
+    getOrder(orderId: bigint): Promise<ConfidentialOrder | null>;
+    /**
+     * 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<TakeOrderResponse>;
+    /**
+     * Get swap history for an address
+     */
+    getSwapHistory(address: string): Promise<SwapHistoryEntry[]>;
+    /**
+     * 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 };