@obelyzk/sdk 0.5.0

package/dist/obelysk/index.d.ts

@@ -0,0 +1,567 @@
+import { RpcProvider, Account } from 'starknet';
+import ObelyskPrivacy, { ecAdd as ecAdd$1, ecMul as ecMul$1, randomScalar as randomScalar$1, invMod, ECPoint } from '../privacy/index.js';
+export { CURVE_ORDER, ElGamalCiphertext, ElGamalKeyPair, FIELD_PRIME, GENERATOR_G, GENERATOR_H } from '../privacy/index.js';
+
+interface DepositParams {
+    /** Token symbol (eth, strk, usdc, wbtc, sage) */
+    token: string;
+    /** Human-readable amount (e.g. "1.5") */
+    amount: string;
+}
+interface DepositResult {
+    /** Transaction hash */
+    txHash: string;
+    /** Note data (SAVE THIS — needed for withdrawal) */
+    note: PrivacyNote;
+    /** Commitment hash (on-chain identifier) */
+    commitmentHash: string;
+}
+interface WithdrawParams {
+    /** The note from a previous deposit */
+    note: PrivacyNote;
+    /** Recipient address (can be different from depositor for anonymity) */
+    recipient: string;
+    /** Merkle proof (array of sibling hashes from leaf to root) */
+    merkleProof: string[];
+    /** Leaf index in the Merkle tree */
+    leafIndex: number;
+}
+interface WithdrawResult {
+    txHash: string;
+    amount: string;
+    token: string;
+}
+/** Serializable privacy note — MUST be saved by the user */
+interface PrivacyNote {
+    /** Token symbol */
+    token: string;
+    /** Amount in wei (bigint as string) */
+    amount: string;
+    /** Pedersen blinding factor (bigint as string) */
+    blinding: string;
+    /** Nullifier secret (bigint as string) */
+    nullifierSecret: string;
+    /** Commitment point x (bigint as string) */
+    commitmentX: string;
+    /** Commitment point y (bigint as string) */
+    commitmentY: string;
+    /** Poseidon hash of commitment (felt252 hex) */
+    commitmentHash: string;
+    /** Leaf index in Merkle tree (set after deposit confirms) */
+    leafIndex?: number;
+    /** Deposit transaction hash */
+    depositTxHash?: string;
+    /** Timestamp */
+    createdAt: number;
+}
+declare class PrivacyPoolClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    /**
+     * Deposit tokens into a privacy pool.
+     *
+     * Creates a Pedersen commitment and range proof, then calls the
+     * privacy pool contract's deposit function.
+     *
+     * @returns DepositResult with the note (SAVE THIS for withdrawal)
+     */
+    deposit(params: DepositParams): Promise<DepositResult>;
+    /**
+     * Withdraw tokens from a privacy pool.
+     *
+     * Requires the original note, a Merkle proof of inclusion,
+     * and the leaf index. The recipient can be any address.
+     */
+    withdraw(params: WithdrawParams): Promise<WithdrawResult>;
+    /**
+     * Read the current global deposit Merkle root of a privacy pool.
+     */
+    getMerkleRoot(token: string): Promise<string>;
+    /**
+     * Get pool stats: (total_deposits, total_withdrawals, total_deposited_amount, total_withdrawn_amount)
+     */
+    getPoolStats(token: string): Promise<{
+        totalDeposits: number;
+        totalWithdrawals: number;
+        totalDeposited: bigint;
+        totalWithdrawn: bigint;
+    }>;
+    /**
+     * Get the current leaf count (number of deposits) in a privacy pool.
+     */
+    getLeafCount(token: string): Promise<number>;
+    /**
+     * Check if a nullifier has been used (prevents double-withdrawal).
+     */
+    isNullifierUsed(token: string, nullifier: string): Promise<boolean>;
+    /**
+     * Check if a deposit commitment is valid.
+     */
+    isDepositValid(token: string, commitment: string): Promise<boolean>;
+    /**
+     * Get fee info for a privacy pool (bps, recipient, accumulated).
+     */
+    getFeeInfo(token: string): Promise<{
+        feeBps: number;
+        feeRecipient: string;
+        accumulated: bigint;
+    }>;
+    /**
+     * Fetch a Merkle proof for a given leaf index from on-chain data.
+     * Reconstructs the tree from deposit events.
+     */
+    fetchMerkleProof(token: string, leafIndex: number): Promise<{
+        proof: string[];
+        root: string;
+    }>;
+}
+
+interface DarkPoolDepositParams {
+    token: string;
+    amount: string;
+}
+interface CommitOrderParams {
+    /** Trading pair e.g. "SAGE/STRK" */
+    pair: string;
+    /** Order side */
+    side: 'buy' | 'sell';
+    /** Price in 18-decimal fixed point (human-readable string) */
+    price: string;
+    /** Amount in token decimals (human-readable string) */
+    amount: string;
+}
+interface RevealOrderParams {
+    /** Order data from commitOrder result */
+    orderData: DarkPoolOrderData;
+}
+interface DarkPoolOrderData {
+    orderId: string;
+    pair: string;
+    side: 'buy' | 'sell';
+    price: string;
+    amount: string;
+    salt: string;
+    amountBlinding: string;
+    commitHash: string;
+    epoch: number;
+}
+interface EpochInfo {
+    epoch: number;
+    phase: 'Commit' | 'Reveal' | 'Settle' | 'Closed';
+    blocksRemaining: number;
+}
+declare class DarkPoolClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get darkPoolAddress();
+    /**
+     * Deposit tokens into the DarkPool for trading.
+     *
+     * Encrypts the amount using ElGamal and generates an AE hint
+     * for O(1) balance decryption.
+     */
+    deposit(params: DarkPoolDepositParams): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Commit an order in the current commit phase.
+     *
+     * Returns order data that must be saved for the reveal phase.
+     */
+    commitOrder(params: CommitOrderParams): Promise<DarkPoolOrderData>;
+    /**
+     * Reveal a previously committed order in the reveal phase.
+     */
+    revealOrder(params: RevealOrderParams): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Get current epoch info from the contract.
+     */
+    getEpochInfo(): Promise<EpochInfo>;
+    /**
+     * Get the total number of orders ever placed.
+     */
+    getOrderCount(): Promise<number>;
+    /**
+     * Get order IDs for a given epoch.
+     */
+    getEpochOrders(epochId: number): Promise<string[]>;
+    /**
+     * Get supported trading pairs.
+     */
+    getSupportedPairs(): Promise<Array<{
+        giveAsset: string;
+        wantAsset: string;
+    }>>;
+    /**
+     * Get fee info (bps, recipient). Returns null if fee module not yet active.
+     */
+    getFeeInfo(): Promise<{
+        feeBps: number;
+        feeRecipient: string;
+    } | null>;
+    /**
+     * Withdraw tokens from the DarkPool.
+     */
+    withdraw(params: {
+        token: string;
+        amount: string;
+    }): Promise<{
+        txHash: string;
+    }>;
+}
+
+interface StealthSendParams {
+    /** Recipient's Starknet address (must be registered in StealthRegistry) */
+    to: string;
+    /** Token symbol */
+    token: string;
+    /** Human-readable amount */
+    amount: string;
+}
+interface StealthMetaAddress {
+    spendPublicKey: {
+        x: bigint;
+        y: bigint;
+    };
+    viewPublicKey: {
+        x: bigint;
+        y: bigint;
+    };
+}
+declare class StealthClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get registryAddress();
+    /**
+     * Look up a recipient's stealth meta-address from the registry.
+     */
+    lookupRecipient(address: string): Promise<StealthMetaAddress | null>;
+    /**
+     * Send tokens to a stealth address.
+     *
+     * Generates ephemeral key, derives stealth address via ECDH,
+     * sends tokens + publishes ephemeral pubkey on-chain.
+     */
+    send(params: StealthSendParams): Promise<{
+        txHash: string;
+        stealthAddress: string;
+        ephemeralPubKey: {
+            x: string;
+            y: string;
+        };
+    }>;
+    /**
+     * Check if an address has a registered stealth meta-address.
+     */
+    hasMetaAddress(address: string): Promise<boolean>;
+    /**
+     * Get the total number of stealth payment announcements.
+     */
+    getAnnouncementCount(): Promise<number>;
+    /**
+     * Get the total number of registered workers/recipients.
+     */
+    getRegisteredCount(): Promise<number>;
+    /**
+     * Check if a stealth payment announcement has been claimed.
+     */
+    isClaimed(announcementIndex: number): Promise<boolean>;
+    /**
+     * Register your stealth meta-address in the registry.
+     */
+    register(spendPubKey: {
+        x: bigint;
+        y: bigint;
+    }, viewPubKey: {
+        x: bigint;
+        y: bigint;
+    }): Promise<{
+        txHash: string;
+    }>;
+}
+
+/** Modular reduction (always positive) */
+declare function mod(a: bigint, m: bigint): bigint;
+/** Modular inverse via extended Euclidean algorithm */
+declare const modInverse: typeof invMod;
+/** EC point addition on STARK curve */
+declare const ecAdd: typeof ecAdd$1;
+/** EC scalar multiplication on STARK curve */
+declare const ecMul: typeof ecMul$1;
+/** Cryptographically secure random scalar in [1, CURVE_ORDER) */
+declare const randomScalar: typeof randomScalar$1;
+/** Pedersen commitment: C = value * G + blinding * H */
+declare function pedersenCommit(value: bigint, blinding: bigint): ECPoint;
+/** ElGamal encrypt: (r*G, amount*H + r*PK) */
+declare function elgamalEncrypt(amount: bigint, publicKey: ECPoint): {
+    c1: ECPoint;
+    c2: ECPoint;
+    randomness: bigint;
+};
+/** Schnorr proof of knowledge of r such that c1 = r*G */
+declare function createEncryptionProof(r: bigint, c1: ECPoint): {
+    commitment: ECPoint;
+    challenge: bigint;
+    response: bigint;
+};
+/** Generate AE hint for O(1) decryption */
+declare function createAEHint(amount: bigint, sharedSecret: bigint): {
+    encryptedAmount: bigint;
+    mac: bigint;
+};
+/** Hash for commitment (Poseidon of point coordinates) */
+declare function commitmentToHash(point: ECPoint): string;
+/** Derive nullifier from secret */
+declare function deriveNullifier(nullifierSecret: bigint, commitmentHash: string): string;
+
+interface TransferParams {
+    /** Recipient's Starknet address */
+    to: string;
+    /** Recipient's ElGamal public key */
+    recipientPublicKey: ECPoint;
+    /** Amount (human-readable) */
+    amount: string;
+    /** Token symbol */
+    token: string;
+}
+declare class ConfidentialTransferClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get contractAddress();
+    /**
+     * Send a confidential transfer with ElGamal encrypted amount.
+     *
+     * Generates encryption proof (Schnorr) to prove the ciphertext is well-formed.
+     */
+    transfer(params: TransferParams): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Read your encrypted balance from the contract.
+     */
+    getEncryptedBalance(address: string, token: string): Promise<{
+        c1: ECPoint;
+        c2: ECPoint;
+    } | null>;
+}
+
+type GpuTier = 'Consumer' | 'Professional' | 'DataCenter' | 'H100';
+interface WorkerStake {
+    amount: bigint;
+    gpuTier: GpuTier;
+    stakedAt: number;
+    isActive: boolean;
+    successCount: number;
+    failCount: number;
+}
+interface StakingConfig {
+    minStakeConsumer: bigint;
+    minStakeProfessional: bigint;
+    minStakeDataCenter: bigint;
+    minStakeH100: bigint;
+    cooldownPeriod: number;
+    slashPercent: number;
+    rewardRateBps: number;
+}
+declare class ProverStakingClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get contractAddress();
+    /**
+     * Get a worker's current stake info.
+     */
+    getStake(workerAddress: string): Promise<WorkerStake>;
+    /**
+     * Check if a worker is eligible (staked enough, not in cooldown).
+     */
+    isEligible(workerAddress: string): Promise<boolean>;
+    /**
+     * Get minimum stake required for a GPU tier.
+     */
+    getMinStake(tier: GpuTier): Promise<bigint>;
+    /**
+     * Get total SAGE staked across all workers.
+     */
+    getTotalStaked(): Promise<bigint>;
+    /**
+     * Get total SAGE slashed.
+     */
+    getTotalSlashed(): Promise<bigint>;
+    /**
+     * Get staking configuration.
+     */
+    getConfig(): Promise<StakingConfig>;
+    /**
+     * Stake SAGE tokens to become a prover.
+     */
+    stake(amount: string, tier: GpuTier): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Request unstaking (starts cooldown period).
+     */
+    requestUnstake(amount: string): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Complete unstaking after cooldown period.
+     */
+    completeUnstake(): Promise<{
+        txHash: string;
+    }>;
+    /**
+     * Claim accumulated staking rewards.
+     */
+    claimRewards(): Promise<{
+        txHash: string;
+    }>;
+}
+
+/**
+ * Privacy Router Client
+ *
+ * Read-only views into the Obelysk Privacy Router — the core private
+ * balance, transfer, and audit infrastructure.
+ */
+
+interface PrivateAccount {
+    publicKey: ECPoint;
+    encryptedBalance: {
+        c1: ECPoint;
+        c2: ECPoint;
+    };
+    registered: boolean;
+}
+declare class PrivacyRouterClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get contractAddress();
+    /**
+     * Get a registered private account's info.
+     */
+    getAccount(address: string): Promise<PrivateAccount | null>;
+    /** Check if a nullifier has been spent. */
+    isNullifierUsed(nullifier: string): Promise<boolean>;
+    /** Get the current nullifier tree root. */
+    getNullifierTreeRoot(): Promise<string>;
+    /** Get the current epoch of the privacy router. */
+    getCurrentEpoch(): Promise<number>;
+    /** Get total nullifier count. */
+    getNullifierCount(): Promise<number>;
+    /** Check if an asset ID is supported. */
+    isAssetSupported(assetId: number): Promise<boolean>;
+    /** Get the token address for an asset ID. */
+    getAssetToken(assetId: number): Promise<string>;
+    /** Get the number of auditors. */
+    getAuditorCount(): Promise<number>;
+    /** Check if an address is a registered auditor. */
+    isAuditor(address: string): Promise<boolean>;
+    /** Get the audit approval threshold. */
+    getAuditThreshold(): Promise<number>;
+    /** Get the large transfer threshold. */
+    getLargeTransferThreshold(): Promise<bigint>;
+    /** Check if the Lean IMT is active. */
+    isLeanIMTActive(): Promise<boolean>;
+    /** Get pending audit/disclosure request count. */
+    getPendingRequestCount(): Promise<number>;
+}
+
+/**
+ * Shielded Swap Router Client
+ *
+ * Read swap router state (pools, fees, swap count).
+ * Actual swaps require withdrawal proofs and are executed via the full
+ * privacy pool → swap → re-deposit flow.
+ */
+
+declare class ShieldedSwapClient {
+    private readonly obelysk;
+    constructor(obelysk: ObelyskClient);
+    private get contractAddress();
+    /** Get total number of shielded swaps executed. */
+    getSwapCount(): Promise<number>;
+    /** Get the privacy pool address registered for a token. */
+    getPool(tokenAddress: string): Promise<string | null>;
+    /** Get the Ekubo core address (AMM integration). */
+    getEkuboCore(): Promise<string>;
+    /** Get swap fee info (bps, recipient). Returns null if not active. */
+    getSwapFeeInfo(): Promise<{
+        feeBps: number;
+        feeRecipient: string;
+    } | null>;
+    /** Get contract owner. */
+    getOwner(): Promise<string>;
+}
+
+/**
+ * Obelysk Protocol Contract Addresses & Token Registry
+ *
+ * All addresses inlined for npm consumers — no external JSON dependency.
+ */
+type ObelyskNetwork = 'sepolia' | 'mainnet';
+declare function getRpcUrl(network: ObelyskNetwork): string;
+declare function getContracts(network: ObelyskNetwork): Record<string, any>;
+declare const MAINNET_TOKENS: Record<string, string>;
+declare const MAINNET_PRIVACY_POOLS: Record<string, string>;
+/** Token decimals */
+declare const TOKEN_DECIMALS: Record<string, number>;
+/** DarkPool asset IDs (felt252) */
+declare const DARKPOOL_ASSET_IDS: Record<string, string>;
+/** VM31 asset IDs */
+declare const VM31_ASSET_IDS: Record<string, number>;
+/** Parse token amount to bigint */
+declare function parseAmount(amount: string | number, token: string): bigint;
+/** Format bigint to human-readable string */
+declare function formatAmount(amount: bigint, token: string): string;
+
+/**
+ * Main Obelysk Protocol Client
+ *
+ * Orchestrates all protocol operations: privacy pools, dark pool,
+ * stealth payments, confidential transfers, staking, router, and swaps.
+ */
+
+interface ObelyskConfig {
+    /** Network to connect to */
+    network: ObelyskNetwork;
+    /** starknet.js Account (for signing transactions) */
+    account?: Account;
+    /** Optional custom RPC URL (strongly recommended — default public RPCs have limits) */
+    rpcUrl?: string;
+    /** Optional privacy key pair (hex private key). If omitted, generated fresh. */
+    privacyPrivateKey?: string;
+}
+declare class ObelyskClient {
+    readonly network: ObelyskNetwork;
+    readonly provider: RpcProvider;
+    readonly account?: Account;
+    readonly privacy: ObelyskPrivacy;
+    readonly contracts: Record<string, string>;
+    readonly tokens: Record<string, string>;
+    readonly privacyPools: Record<string, string>;
+    /** Privacy Pool operations (deposit/withdraw shielded tokens) */
+    readonly privacyPool: PrivacyPoolClient;
+    /** DarkPool batch auction trading */
+    readonly darkPool: DarkPoolClient;
+    /** Stealth address payments */
+    readonly stealth: StealthClient;
+    /** Confidential peer-to-peer transfers */
+    readonly confidentialTransfer: ConfidentialTransferClient;
+    /** SAGE prover staking (stake/unstake/rewards) */
+    readonly staking: ProverStakingClient;
+    /** Privacy Router (private balances, nullifiers, auditing) */
+    readonly router: PrivacyRouterClient;
+    /** Shielded swap router (privacy-preserving AMM swaps) */
+    readonly swap: ShieldedSwapClient;
+    constructor(config: ObelyskConfig);
+    /** Get token address by symbol */
+    getTokenAddress(symbol: string): string;
+    /** Get privacy pool address for a token */
+    getPrivacyPoolAddress(symbol: string): string;
+    /** Require an account is set */
+    requireAccount(): Account;
+}
+
+export { type CommitOrderParams, ConfidentialTransferClient, DARKPOOL_ASSET_IDS, DarkPoolClient, type DarkPoolDepositParams, type DarkPoolOrderData, type DepositParams, type DepositResult, ECPoint, type EpochInfo, type GpuTier, MAINNET_PRIVACY_POOLS, MAINNET_TOKENS, ObelyskClient, type ObelyskConfig, type ObelyskNetwork, ObelyskPrivacy, type PrivacyNote, PrivacyPoolClient, PrivacyRouterClient, type PrivateAccount, ProverStakingClient, type RevealOrderParams, ShieldedSwapClient, type StakingConfig, StealthClient, type StealthMetaAddress, type StealthSendParams, TOKEN_DECIMALS, type TransferParams, VM31_ASSET_IDS, type WithdrawParams, type WithdrawResult, type WorkerStake, commitmentToHash, createAEHint, createEncryptionProof, deriveNullifier, ecAdd, ecMul, elgamalEncrypt, formatAmount, getContracts, getRpcUrl, mod, modInverse, parseAmount, pedersenCommit, randomScalar };