@rougechain/sdk 1.3.0 → 1.3.1

package/dist/index.d.ts

@@ -0,0 +1,1131 @@
+interface WalletKeys {
+    publicKey: string;
+    privateKey: string;
+    mnemonic?: string;
+}
+interface ApiResponse<T = unknown> {
+    success: boolean;
+    error?: string;
+    data?: T;
+}
+type TransactionType = "transfer" | "create_token" | "swap" | "create_pool" | "add_liquidity" | "remove_liquidity" | "stake" | "unstake" | "faucet" | "nft_create_collection" | "nft_mint" | "nft_batch_mint" | "nft_transfer" | "nft_burn" | "nft_lock" | "nft_freeze_collection" | "bridge_withdraw" | "update_token_metadata" | "claim_token_metadata" | "approve" | "transfer_from" | "shield" | "shielded_transfer" | "unshield" | "contract_deploy" | "contract_call";
+interface TransactionPayload {
+    type: TransactionType;
+    from: string;
+    to?: string;
+    amount?: number;
+    fee?: number;
+    token?: string;
+    tokenSymbol?: string;
+    evmAddress?: string;
+    timestamp: number;
+    nonce: string;
+    token_name?: string;
+    token_symbol?: string;
+    initial_supply?: number;
+    token_in?: string;
+    token_out?: string;
+    amount_in?: number;
+    min_amount_out?: number;
+    pool_id?: string;
+    token_a?: string;
+    token_b?: string;
+    amount_a?: number;
+    amount_b?: number;
+    lp_amount?: number;
+    symbol?: string;
+    name?: string;
+    collectionId?: string;
+    description?: string;
+    image?: string;
+    maxSupply?: number;
+    royaltyBps?: number;
+    tokenId?: number;
+    metadataUri?: string;
+    attributes?: unknown;
+    locked?: boolean;
+    frozen?: boolean;
+    salePrice?: number;
+    names?: string[];
+    uris?: string[];
+    batchAttributes?: unknown[];
+    website?: string;
+    twitter?: string;
+    discord?: string;
+    publicMint?: boolean;
+    mintPrice?: number;
+    tokenGateSymbol?: string;
+    tokenGateAmount?: number;
+    discountPct?: number;
+    spender?: string;
+    owner?: string;
+}
+interface SignedTransaction {
+    payload: TransactionPayload;
+    signature: string;
+    public_key: string;
+}
+interface BlockHeader {
+    version: number;
+    chain_id: string;
+    height: number;
+    time: number;
+    prev_hash: string;
+    tx_hash: string;
+    proposer_pub_key: string;
+}
+interface Transaction {
+    version: number;
+    tx_type: string;
+    from_pub_key: string;
+    target_pub_key?: string | null;
+    amount: number;
+    fee: number;
+    sig: string;
+    token_name?: string | null;
+    token_symbol?: string | null;
+    token_decimals?: number | null;
+    token_total_supply?: number | null;
+    pool_id?: string | null;
+    token_a_symbol?: string | null;
+    token_b_symbol?: string | null;
+    amount_a?: number | null;
+    amount_b?: number | null;
+    min_amount_out?: number | null;
+    swap_path?: string[] | null;
+    lp_amount?: number | null;
+    faucet?: boolean;
+    signed_payload?: string | null;
+}
+interface Block {
+    version: number;
+    header: BlockHeader;
+    txs: Transaction[];
+    proposer_sig: string;
+    hash: string;
+}
+interface NodeStats {
+    height: number;
+    peers: number;
+    network_height: number;
+    mining: boolean;
+    total_fees: number;
+    last_block_fees: number;
+    finalized_height: number;
+    ws_clients: number;
+    /** Current EIP-1559 base fee (XRGE) */
+    base_fee: number;
+    /** Total fees burned via EIP-1559 mechanism */
+    total_fees_burned: number;
+}
+interface TokenMetadata {
+    symbol: string;
+    name: string;
+    creator: string;
+    image?: string;
+    description?: string;
+    website?: string;
+    twitter?: string;
+    discord?: string;
+    created_at: number;
+    updated_at: number;
+}
+interface TokenHolder {
+    address: string;
+    balance: number;
+}
+interface BalanceResponse {
+    balance: number;
+    token_balances: Record<string, number>;
+    lp_balances: Record<string, number>;
+}
+interface LiquidityPool {
+    pool_id: string;
+    token_a_symbol: string;
+    token_b_symbol: string;
+    reserve_a: number;
+    reserve_b: number;
+    total_lp: number;
+    fee_rate: number;
+    created_at: number;
+}
+interface SwapQuote {
+    amount_out: number;
+    price_impact: number;
+    path: string[];
+}
+interface PoolEvent {
+    event_type: string;
+    pool_id: string;
+    actor: string;
+    token_a_amount?: number;
+    token_b_amount?: number;
+    lp_amount?: number;
+    timestamp: number;
+}
+interface PoolStats {
+    pool_id: string;
+    volume_24h: number;
+    trades_24h: number;
+    tvl: number;
+}
+interface PriceSnapshot {
+    pool_id: string;
+    timestamp: number;
+    block_height: number;
+    reserve_a: number;
+    reserve_b: number;
+    price_a_in_b: number;
+    price_b_in_a: number;
+}
+interface NftCollection {
+    collection_id: string;
+    symbol: string;
+    name: string;
+    creator: string;
+    description?: string;
+    image?: string;
+    max_supply?: number;
+    minted: number;
+    royalty_bps: number;
+    royalty_recipient: string;
+    frozen: boolean;
+    created_at: number;
+    public_mint?: boolean;
+    mint_price?: number;
+    token_gate_symbol?: string;
+    token_gate_amount?: number;
+    discount_pct?: number;
+}
+interface NftToken {
+    collection_id: string;
+    token_id: number;
+    owner: string;
+    creator: string;
+    name: string;
+    metadata_uri?: string;
+    attributes?: unknown;
+    locked: boolean;
+    minted_at: number;
+    transferred_at: number;
+}
+interface Validator {
+    public_key: string;
+    stake: number;
+    status: string;
+    jailed_until: number;
+    uptime: number;
+}
+interface BridgeConfig {
+    enabled: boolean;
+    custodyAddress?: string;
+    chainId: number;
+    supportedTokens?: string[];
+}
+interface BridgeWithdrawal {
+    tx_id: string;
+    from_pub_key: string;
+    evm_address: string;
+    amount_units: number;
+    status: string;
+    created_at: number;
+}
+interface XrgeBridgeConfig {
+    enabled: boolean;
+    vaultAddress?: string;
+    tokenAddress?: string;
+    chainId: number;
+}
+interface NameEntry {
+    name: string;
+    wallet_id: string;
+    registered_at: string;
+}
+interface ResolvedName {
+    entry?: NameEntry;
+    wallet?: {
+        id: string;
+        display_name: string;
+        signing_public_key: string;
+        encryption_public_key: string;
+    };
+}
+interface MailMessage {
+    id: string;
+    from: string;
+    to: string;
+    subject: string;
+    body: string;
+    encrypted_subject?: string;
+    encrypted_body?: string;
+    attachment_encrypted?: string;
+    attachmentEncrypted?: string;
+    has_attachment?: boolean;
+    hasAttachment?: boolean;
+    reply_to_id?: string;
+    replyToId?: string;
+    signature?: string;
+    contentSignature?: string;
+    read: boolean;
+    folder: "inbox" | "sent" | "trash";
+    created_at: number;
+    createdAt?: string;
+    fromWalletId?: string;
+    from_wallet_id?: string;
+    toWalletIds?: string[];
+    to_wallet_ids?: string[];
+    subjectEncrypted?: string;
+    subject_encrypted?: string;
+    bodyEncrypted?: string;
+    body_encrypted?: string;
+}
+interface SendMailParams {
+    from: string;
+    to: string;
+    subject?: string;
+    body?: string;
+    encrypted_subject: string;
+    encrypted_body: string;
+    encrypted_attachment?: string;
+    content_signature?: string;
+    reply_to_id?: string;
+}
+interface MessengerWallet {
+    id: string;
+    displayName: string;
+    signingPublicKey: string;
+    encryptionPublicKey: string;
+    created_at: number;
+}
+interface MessengerConversation {
+    id: string;
+    participants: string[];
+    created_at: number;
+    last_message_at?: string;
+    last_sender_id?: string;
+    last_message_preview?: string;
+    unread_count?: number;
+}
+interface MessengerMessage {
+    id: string;
+    conversation_id: string;
+    sender_wallet_id: string;
+    /** @deprecated Use sender_wallet_id */
+    sender?: string;
+    encrypted_content: string;
+    signature: string;
+    self_destruct: boolean;
+    destruct_after_seconds?: number;
+    created_at: number | string;
+    is_read: boolean;
+    read_at?: string;
+    message_type: string;
+    spoiler: boolean;
+    /** Legacy — some old messages may have these */
+    media_type?: string;
+    media_data?: string;
+}
+interface TransferParams {
+    to: string;
+    amount: number;
+    fee?: number;
+    token?: string;
+}
+interface CreateTokenParams {
+    name: string;
+    symbol: string;
+    totalSupply: number;
+    fee?: number;
+    /** Token logo — URL or data URI (base64). Stored on-chain in token metadata. */
+    image?: string;
+    /** Whether this token supports ongoing minting by the creator */
+    mintable?: boolean;
+    /** Maximum supply cap (only applies if mintable is true) */
+    maxSupply?: number;
+}
+interface MintTokenParams {
+    symbol: string;
+    amount: number;
+    fee?: number;
+}
+interface FeeInfo {
+    success: boolean;
+    base_fee: number;
+    priority_fee_suggestion: number;
+    total_fee_suggestion: number;
+    total_fees_burned: number;
+    target_txs_per_block: number;
+    fee_floor: number;
+}
+interface VoteMessage {
+    vote_type: string;
+    height: number;
+    round: number;
+    block_hash: string;
+    voter_pub_key: string;
+    signature: string;
+}
+interface FinalityProof {
+    height: number;
+    block_hash: string;
+    total_stake: number;
+    voting_stake: number;
+    quorum_threshold: number;
+    precommit_votes: VoteMessage[];
+    created_at: number;
+}
+interface WsSubscribeMessage {
+    subscribe?: string[];
+    unsubscribe?: string[];
+}
+interface SwapParams {
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: number;
+    minAmountOut: number;
+}
+interface CreatePoolParams {
+    tokenA: string;
+    tokenB: string;
+    amountA: number;
+    amountB: number;
+}
+interface AddLiquidityParams {
+    poolId: string;
+    amountA: number;
+    amountB: number;
+}
+interface RemoveLiquidityParams {
+    poolId: string;
+    lpAmount: number;
+}
+interface StakeParams {
+    amount: number;
+    fee?: number;
+}
+interface CreateNftCollectionParams {
+    symbol: string;
+    name: string;
+    maxSupply?: number;
+    royaltyBps?: number;
+    image?: string;
+    description?: string;
+    publicMint?: boolean;
+    mintPrice?: number;
+    tokenGateSymbol?: string;
+    tokenGateAmount?: number;
+    discountPct?: number;
+}
+interface MintNftParams {
+    collectionId: string;
+    name: string;
+    metadataUri?: string;
+    attributes?: unknown;
+}
+interface BatchMintNftParams {
+    collectionId: string;
+    names: string[];
+    uris?: string[];
+    batchAttributes?: unknown[];
+}
+interface TransferNftParams {
+    collectionId: string;
+    tokenId: number;
+    to: string;
+    salePrice?: number;
+}
+interface BurnNftParams {
+    collectionId: string;
+    tokenId: number;
+}
+interface LockNftParams {
+    collectionId: string;
+    tokenId: number;
+    locked: boolean;
+}
+interface FreezeCollectionParams {
+    collectionId: string;
+    frozen: boolean;
+}
+interface BridgeWithdrawParams {
+    amount: number;
+    evmAddress: string;
+    fee?: number;
+    tokenSymbol?: string;
+}
+interface BridgeClaimParams {
+    evmTxHash: string;
+    evmAddress: string;
+    evmSignature: string;
+    recipientPubkey: string;
+    token?: "ETH" | "USDC";
+}
+interface XrgeBridgeClaimParams {
+    evmTxHash: string;
+    evmAddress: string;
+    amount: string;
+    recipientPubkey: string;
+}
+interface XrgeBridgeWithdrawParams {
+    amount: number;
+    evmAddress: string;
+}
+interface SwapQuoteParams {
+    poolId: string;
+    tokenIn: string;
+    tokenOut: string;
+    amountIn: number;
+}
+interface TokenMetadataUpdateParams {
+    symbol: string;
+    image?: string;
+    description?: string;
+    website?: string;
+    twitter?: string;
+    discord?: string;
+}
+interface ApproveParams {
+    spender: string;
+    tokenSymbol: string;
+    amount: number;
+}
+interface TransferFromParams {
+    owner: string;
+    to: string;
+    tokenSymbol: string;
+    amount: number;
+}
+interface ShieldParams {
+    /** Amount to shield (integer XRGE) */
+    amount: number;
+}
+interface ShieldedTransferParams {
+    /** Nullifiers of consumed input notes (hex) */
+    nullifiers: string[];
+    /** Commitments for output notes (hex) */
+    outputCommitments: string[];
+    /** STARK proof bytes (hex) */
+    proof: string;
+    /** Fee paid from the shielded pool */
+    shieldedFee?: number;
+}
+interface UnshieldParams {
+    /** Nullifiers of consumed notes (hex) */
+    nullifiers: string[];
+    /** Amount to unshield (integer XRGE) */
+    amount: number;
+    /** STARK proof bytes (hex) */
+    proof: string;
+}
+interface ShieldedStats {
+    success: boolean;
+    commitment_count: number;
+    nullifier_count: number;
+    active_notes: number;
+}
+interface RollupStatus {
+    pending_transfers: number;
+    completed_batches: number;
+    next_batch_id: number;
+    max_batch_size: number;
+    batch_timeout_secs: number;
+    current_state_root: string;
+    accounts_tracked: number;
+}
+interface RollupBatchResult {
+    batch_id: number;
+    transfer_count: number;
+    total_fees: number;
+    pre_state_root: string;
+    post_state_root: string;
+    proof_size_bytes: number;
+    proof_time_ms: number;
+    verified: boolean;
+}
+interface RollupSubmitParams {
+    sender: string;
+    receiver: string;
+    amount: number;
+    fee?: number;
+}
+interface RollupSubmitResult {
+    success: boolean;
+    queued: boolean;
+    batch_completed: boolean;
+    batch?: RollupBatchResult;
+    pending_transfers?: number;
+    max_batch_size?: number;
+}
+interface ContractMetadata {
+    address: string;
+    deployer: string;
+    codeHash: string;
+    createdAt: number;
+    wasmSize: number;
+}
+interface ContractEvent {
+    contractAddr: string;
+    topic: string;
+    data: string;
+    blockHeight: number;
+    txHash: string;
+}
+interface ContractCallResult {
+    success: boolean;
+    returnData?: unknown;
+    gasUsed: number;
+    events: ContractEvent[];
+    error?: string;
+}
+interface DeployContractParams {
+    /** Base64-encoded WASM bytecode */
+    wasm: string;
+    /** Deployer's public key */
+    deployer: string;
+    /** Nonce for deterministic address */
+    nonce?: number;
+}
+interface CallContractParams {
+    /** Contract address (hex) */
+    contractAddr: string;
+    /** Method name to call */
+    method: string;
+    /** Caller's public key */
+    caller?: string;
+    /** JSON arguments */
+    args?: unknown;
+    /** Gas limit (default 10M) */
+    gasLimit?: number;
+}
+
+/**
+ * Client-side shielded transaction crypto primitives.
+ *
+ * Mirrors the Rust commitment.rs exactly:
+ *   commitment = SHA-256("ROUGECHAIN_COMMITMENT_V1" || value || pubkey || randomness)
+ *   nullifier  = SHA-256("ROUGECHAIN_NULLIFIER_V1"  || randomness || commitment)
+ */
+/** Generate 32 bytes of cryptographically secure randomness (hex-encoded). */
+declare function generateRandomness(): string;
+/**
+ * Compute a shielded note commitment.
+ *
+ * @param value       - Note value in XRGE (integer)
+ * @param ownerPubKey - Owner's ML-DSA-65 public key (hex)
+ * @param randomness  - 32-byte blinding factor (hex)
+ * @returns 32-byte commitment hash (hex)
+ */
+declare function computeCommitment(value: number, ownerPubKey: string, randomness: string): string;
+/**
+ * Compute a nullifier for a shielded note.
+ *
+ * @param randomness - The note's blinding factor (hex)
+ * @param commitment - The note's commitment hash (hex)
+ * @returns 32-byte nullifier hash (hex)
+ */
+declare function computeNullifier(randomness: string, commitment: string): string;
+/** A shielded note — kept locally by the owner (never sent to chain). */
+interface ShieldedNote {
+    commitment: string;
+    nullifier: string;
+    value: number;
+    randomness: string;
+    ownerPubKey: string;
+}
+/**
+ * Create a new shielded note for a given value.
+ *
+ * @param value       - XRGE amount (integer)
+ * @param ownerPubKey - Owner's public key (hex)
+ * @returns A ShieldedNote with all derived fields
+ */
+declare function createShieldedNote(value: number, ownerPubKey: string): ShieldedNote;
+
+type FetchFn = typeof globalThis.fetch;
+interface RougeChainOptions {
+    /** Custom fetch implementation (defaults to globalThis.fetch) */
+    fetch?: FetchFn;
+    /** Optional API key for authenticated endpoints */
+    apiKey?: string;
+}
+declare class RougeChain {
+    /** @internal */ readonly baseUrl: string;
+    /** @internal */ readonly fetchFn: FetchFn;
+    /** @internal */ readonly headers: Record<string, string>;
+    readonly nft: NftClient;
+    readonly dex: DexClient;
+    readonly bridge: BridgeClient;
+    readonly mail: MailClient;
+    readonly messenger: MessengerClient;
+    readonly shielded: ShieldedClient;
+    readonly social: SocialClient;
+    constructor(baseUrl: string, options?: RougeChainOptions);
+    /** @internal */
+    get<T = unknown>(path: string): Promise<T>;
+    /** @internal */
+    post<T = unknown>(path: string, body: unknown): Promise<T>;
+    /** @internal */
+    submitTx(endpoint: string, signedTx: SignedTransaction): Promise<ApiResponse>;
+    getStats(): Promise<NodeStats>;
+    getHealth(): Promise<{
+        status: string;
+        chain_id: string;
+        height: number;
+    }>;
+    getBlocks(opts?: {
+        limit?: number;
+    }): Promise<Block[]>;
+    getBlocksSummary(range?: "1h" | "24h" | "7d"): Promise<unknown>;
+    getBalance(publicKey: string): Promise<BalanceResponse>;
+    getTokenBalance(publicKey: string, token: string): Promise<number>;
+    getTransactions(opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+    getTokens(): Promise<TokenMetadata[]>;
+    getTokenMetadata(symbol: string): Promise<TokenMetadata>;
+    getTokenHolders(symbol: string): Promise<TokenHolder[]>;
+    getTokenTransactions(symbol: string): Promise<unknown>;
+    getValidators(): Promise<Validator[]>;
+    getValidatorStats(): Promise<unknown>;
+    getFinality(): Promise<{
+        finalized_height: number;
+        tip_height: number;
+        total_stake: number;
+        finalized_stake: number;
+    }>;
+    /** Get current EIP-1559 fee information including base fee and suggestions. */
+    getFeeInfo(): Promise<FeeInfo>;
+    /**
+     * Get a BFT finality proof for a specific block height.
+     * Returns the aggregated precommit votes that prove ≥2/3 validator stake agreed.
+     */
+    getFinalityProof(height: number): Promise<{
+        success: boolean;
+        proof?: FinalityProof;
+        error?: string;
+    }>;
+    getPeers(): Promise<string[]>;
+    getBurnedTokens(): Promise<{
+        burned: Record<string, number>;
+        total_xrge_burned: number;
+    }>;
+    /**
+     * Resolve a rouge1… address to its public key, or a public key to its rouge1 address.
+     * Uses the persistent on-chain address index for O(1) lookups.
+     */
+    resolveAddress(input: string): Promise<{
+        success: boolean;
+        address?: string;
+        publicKey?: string;
+        balance?: number;
+        error?: string;
+    }>;
+    /** Get the current sequential nonce for an account. */
+    getNonce(publicKey: string): Promise<{
+        nonce: number;
+        next_nonce: number;
+    }>;
+    /** Register an Expo push token — signed by wallet to prove ownership. */
+    registerPushToken(wallet: WalletKeys, pushToken: string, platform?: string): Promise<ApiResponse>;
+    /** Unregister push notifications — signed by wallet to prove ownership. */
+    unregisterPushToken(wallet: WalletKeys): Promise<ApiResponse>;
+    transfer(wallet: WalletKeys, params: TransferParams): Promise<ApiResponse>;
+    createToken(wallet: WalletKeys, params: CreateTokenParams): Promise<ApiResponse>;
+    stake(wallet: WalletKeys, params: StakeParams): Promise<ApiResponse>;
+    unstake(wallet: WalletKeys, params: StakeParams): Promise<ApiResponse>;
+    faucet(wallet: WalletKeys): Promise<ApiResponse>;
+    burn(wallet: WalletKeys, amount: number, fee?: number, token?: string): Promise<ApiResponse>;
+    updateTokenMetadata(wallet: WalletKeys, params: TokenMetadataUpdateParams): Promise<ApiResponse>;
+    claimTokenMetadata(wallet: WalletKeys, tokenSymbol: string): Promise<ApiResponse>;
+    /**
+     * Mint additional tokens for a mintable token (creator only).
+     * The token must have been created with `mintable: true`.
+     */
+    mintTokens(wallet: WalletKeys, params: MintTokenParams): Promise<ApiResponse>;
+    /**
+     * Connect to the node's WebSocket and optionally subscribe to specific topics.
+     * Topics: "blocks", "transactions", "stats", "account:<pubkey>", "token:<symbol>"
+     *
+     * @example
+     * const ws = client.connectWebSocket(["blocks", "account:abc123"]);
+     * ws.onmessage = (e) => console.log(JSON.parse(e.data));
+     */
+    connectWebSocket(topics?: string[]): WebSocket;
+    /** Get the current rollup accumulator status. */
+    getRollupStatus(): Promise<RollupStatus>;
+    /** Submit a transfer into the rollup batch accumulator. */
+    submitRollupTransfer(params: RollupSubmitParams): Promise<RollupSubmitResult>;
+    /** Get the result of a completed rollup batch by ID. */
+    getRollupBatch(batchId: number): Promise<RollupBatchResult>;
+}
+declare class NftClient {
+    private readonly rc;
+    constructor(rc: RougeChain);
+    getCollections(): Promise<NftCollection[]>;
+    getCollection(collectionId: string): Promise<NftCollection>;
+    /**
+     * Poll until a collection exists on-chain (i.e. the create tx has been mined).
+     * Useful after `createCollection` since the tx goes to the mempool first.
+     * @returns the collection once found, or throws after the timeout.
+     */
+    waitForCollection(collectionId: string, opts?: {
+        timeoutMs?: number;
+        pollMs?: number;
+    }): Promise<NftCollection>;
+    getTokens(collectionId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        tokens: NftToken[];
+        total: number;
+    }>;
+    getToken(collectionId: string, tokenId: number): Promise<NftToken>;
+    getByOwner(pubkey: string): Promise<NftToken[]>;
+    createCollection(wallet: WalletKeys, params: CreateNftCollectionParams): Promise<ApiResponse>;
+    mint(wallet: WalletKeys, params: MintNftParams): Promise<ApiResponse>;
+    batchMint(wallet: WalletKeys, params: BatchMintNftParams): Promise<ApiResponse>;
+    transfer(wallet: WalletKeys, params: TransferNftParams): Promise<ApiResponse>;
+    burn(wallet: WalletKeys, params: BurnNftParams): Promise<ApiResponse>;
+    lock(wallet: WalletKeys, params: LockNftParams): Promise<ApiResponse>;
+    freezeCollection(wallet: WalletKeys, params: FreezeCollectionParams): Promise<ApiResponse>;
+}
+declare class DexClient {
+    private readonly rc;
+    constructor(rc: RougeChain);
+    getPools(): Promise<LiquidityPool[]>;
+    getPool(poolId: string): Promise<LiquidityPool>;
+    getPoolEvents(poolId: string): Promise<PoolEvent[]>;
+    getPriceHistory(poolId: string): Promise<PriceSnapshot[]>;
+    getPoolStats(poolId: string): Promise<PoolStats>;
+    quote(params: SwapQuoteParams): Promise<SwapQuote>;
+    swap(wallet: WalletKeys, params: SwapParams): Promise<ApiResponse>;
+    createPool(wallet: WalletKeys, params: CreatePoolParams): Promise<ApiResponse>;
+    addLiquidity(wallet: WalletKeys, params: AddLiquidityParams): Promise<ApiResponse>;
+    removeLiquidity(wallet: WalletKeys, params: RemoveLiquidityParams): Promise<ApiResponse>;
+}
+declare class BridgeClient {
+    private readonly rc;
+    constructor(rc: RougeChain);
+    getConfig(): Promise<BridgeConfig>;
+    getWithdrawals(): Promise<BridgeWithdrawal[]>;
+    /** Withdraw qETH/qUSDC — signed client-side, private key never sent to server */
+    withdraw(wallet: WalletKeys, params: BridgeWithdrawParams): Promise<ApiResponse>;
+    /** Claim qETH or qUSDC after depositing on Base Sepolia */
+    claim(params: BridgeClaimParams): Promise<ApiResponse>;
+    getXrgeConfig(): Promise<XrgeBridgeConfig>;
+    claimXrge(params: XrgeBridgeClaimParams): Promise<ApiResponse>;
+    withdrawXrge(wallet: WalletKeys, params: XrgeBridgeWithdrawParams): Promise<ApiResponse>;
+    getXrgeWithdrawals(): Promise<BridgeWithdrawal[]>;
+}
+declare class MailClient {
+    private readonly rc;
+    constructor(rc: RougeChain);
+    registerName(wallet: WalletKeys, name: string, walletId: string): Promise<ApiResponse>;
+    resolveName(name: string): Promise<ResolvedName | null>;
+    reverseLookup(walletId: string): Promise<string | null>;
+    releaseName(wallet: WalletKeys, name: string): Promise<ApiResponse>;
+    send(wallet: WalletKeys, params: SendMailParams): Promise<ApiResponse>;
+    getInbox(wallet: WalletKeys): Promise<MailMessage[]>;
+    getSent(wallet: WalletKeys): Promise<MailMessage[]>;
+    getTrash(wallet: WalletKeys): Promise<MailMessage[]>;
+    getMessage(wallet: WalletKeys, messageId: string): Promise<MailMessage | null>;
+    move(wallet: WalletKeys, messageId: string, folder: string): Promise<ApiResponse>;
+    markRead(wallet: WalletKeys, messageId: string): Promise<ApiResponse>;
+    delete(wallet: WalletKeys, messageId: string): Promise<ApiResponse>;
+}
+declare class MessengerClient {
+    private readonly rc;
+    constructor(rc: RougeChain);
+    getWallets(): Promise<MessengerWallet[]>;
+    registerWallet(wallet: WalletKeys, opts: {
+        id: string;
+        displayName: string;
+        signingPublicKey: string;
+        encryptionPublicKey: string;
+        discoverable?: boolean;
+    }): Promise<ApiResponse>;
+    getConversations(wallet: WalletKeys): Promise<MessengerConversation[]>;
+    createConversation(wallet: WalletKeys, participantIds: string[], opts?: {
+        name?: string;
+        isGroup?: boolean;
+    }): Promise<ApiResponse>;
+    getMessages(wallet: WalletKeys, conversationId: string): Promise<MessengerMessage[]>;
+    sendMessage(wallet: WalletKeys, conversationId: string, encryptedContent: string, opts?: {
+        contentSignature?: string;
+        messageType?: string;
+        selfDestruct?: boolean;
+        destructAfterSeconds?: number;
+        spoiler?: boolean;
+    }): Promise<ApiResponse>;
+    deleteMessage(wallet: WalletKeys, messageId: string, conversationId: string): Promise<ApiResponse>;
+    deleteConversation(wallet: WalletKeys, conversationId: string): Promise<ApiResponse>;
+    markRead(wallet: WalletKeys, messageId: string, conversationId: string): Promise<ApiResponse>;
+}
+declare class ShieldedClient {
+    private readonly rc;
+    constructor(rc: RougeChain);
+    getStats(): Promise<ShieldedStats>;
+    isNullifierSpent(nullifierHex: string): Promise<{
+        spent: boolean;
+    }>;
+    /**
+     * Shield public XRGE into a private note.
+     * Creates the commitment client-side, submits to the chain.
+     *
+     * @returns The ShieldedNote (keep this locally — it's the only way to spend the note)
+     */
+    shield(wallet: WalletKeys, params: ShieldParams): Promise<ApiResponse & {
+        note?: ShieldedNote;
+    }>;
+    /**
+     * Transfer between shielded notes (private → private).
+     * Requires a pre-generated STARK proof.
+     */
+    transfer(wallet: WalletKeys, params: ShieldedTransferParams): Promise<ApiResponse>;
+    /**
+     * Unshield a private note back to public XRGE.
+     * Requires a STARK proof of note ownership.
+     */
+    unshield(wallet: WalletKeys, params: UnshieldParams): Promise<ApiResponse>;
+    /** Deploy a WASM smart contract */
+    deployContract(params: {
+        wasm: string;
+        deployer: string;
+        nonce?: number;
+    }): Promise<ApiResponse>;
+    /** Call a WASM smart contract method (mutating) */
+    callContract(params: {
+        contractAddr: string;
+        method: string;
+        caller?: string;
+        args?: unknown;
+        gasLimit?: number;
+    }): Promise<ApiResponse>;
+    /** Get contract metadata */
+    getContract(addr: string): Promise<ApiResponse>;
+    /** Read contract storage. Omit key for full state dump. */
+    getContractState(addr: string, key?: string): Promise<ApiResponse>;
+    /** Get contract events */
+    getContractEvents(addr: string, limit?: number): Promise<ApiResponse>;
+    /** List all deployed contracts */
+    listContracts(): Promise<ApiResponse>;
+}
+interface TrackStats {
+    plays: number;
+    likes: number;
+    commentCount: number;
+    liked: boolean;
+}
+interface ArtistStats {
+    followers: number;
+    following: number;
+    isFollowing: boolean;
+}
+interface SocialComment {
+    id: string;
+    track_id: string;
+    wallet_pubkey: string;
+    body: string;
+    timestamp: string;
+}
+interface SocialPost {
+    id: string;
+    author_pubkey: string;
+    body: string;
+    reply_to_id: string | null;
+    created_at: string;
+}
+interface PostStats {
+    likes: number;
+    reposts: number;
+    replies: number;
+    liked: boolean;
+    reposted: boolean;
+}
+declare class SocialClient {
+    private readonly rc;
+    constructor(rc: RougeChain);
+    recordPlay(wallet: WalletKeys, trackId: string): Promise<ApiResponse>;
+    toggleLike(wallet: WalletKeys, trackId: string): Promise<ApiResponse & {
+        liked?: boolean;
+        likes?: number;
+    }>;
+    postComment(wallet: WalletKeys, trackId: string, body: string): Promise<ApiResponse & {
+        comment?: SocialComment;
+    }>;
+    deleteComment(wallet: WalletKeys, commentId: string): Promise<ApiResponse>;
+    toggleFollow(wallet: WalletKeys, artistPubkey: string): Promise<ApiResponse & {
+        following?: boolean;
+        followers?: number;
+    }>;
+    getTrackStats(trackId: string, viewerPubkey?: string): Promise<TrackStats>;
+    getComments(trackId: string, limit?: number, offset?: number): Promise<SocialComment[]>;
+    getArtistStats(pubkey: string, viewerPubkey?: string): Promise<ArtistStats>;
+    getUserLikes(pubkey: string): Promise<string[]>;
+    getUserFollowing(pubkey: string): Promise<string[]>;
+    createPost(wallet: WalletKeys, body: string, replyToId?: string): Promise<ApiResponse & {
+        post?: SocialPost;
+    }>;
+    deletePost(wallet: WalletKeys, postId: string): Promise<ApiResponse>;
+    toggleRepost(wallet: WalletKeys, postId: string): Promise<ApiResponse & {
+        reposted?: boolean;
+        reposts?: number;
+    }>;
+    getPost(postId: string, viewerPubkey?: string): Promise<{
+        post: SocialPost;
+        stats: PostStats;
+    } | null>;
+    getPostStats(postId: string, viewerPubkey?: string): Promise<PostStats>;
+    getPostReplies(postId: string, limit?: number, offset?: number): Promise<SocialPost[]>;
+    getUserPosts(pubkey: string, limit?: number, offset?: number): Promise<{
+        posts: SocialPost[];
+        total: number;
+    }>;
+    getGlobalTimeline(limit?: number, offset?: number): Promise<SocialPost[]>;
+    getFollowingFeed(wallet: WalletKeys, limit?: number, offset?: number): Promise<SocialPost[]>;
+    hideTrack(wallet: WalletKeys, trackId: string, hidden?: boolean): Promise<ApiResponse & {
+        hidden?: boolean;
+    }>;
+    getHiddenTracks(pubkey: string): Promise<string[]>;
+}
+
+declare class Wallet implements WalletKeys {
+    readonly publicKey: string;
+    readonly privateKey: string;
+    readonly mnemonic?: string;
+    private constructor();
+    /**
+     * Generate a new ML-DSA-65 keypair with a BIP-39 mnemonic.
+     * The mnemonic is stored on the wallet for backup/recovery.
+     * @param strength 256 = 24 words (default, post-quantum safe), 128 = 12 words
+     */
+    static generate(strength?: 128 | 256): Wallet;
+    /**
+     * Generate a wallet using pure random entropy (no mnemonic).
+     * Keys cannot be recovered from a seed phrase.
+     */
+    static generateRandom(): Wallet;
+    /**
+     * Restore a wallet from a BIP-39 mnemonic seed phrase.
+     * @param mnemonic 12 or 24 word BIP-39 mnemonic
+     * @param passphrase Optional BIP-39 passphrase (25th word)
+     */
+    static fromMnemonic(mnemonic: string, passphrase?: string): Wallet;
+    /**
+     * Restore a wallet from existing hex-encoded keys.
+     */
+    static fromKeys(publicKey: string, privateKey: string): Wallet;
+    /**
+     * Export keys as a plain object (for serialization/storage).
+     */
+    toJSON(): WalletKeys;
+    /**
+     * Derive the compact Bech32m address from the public key.
+     * Returns a ~63-character `rouge1...` string.
+     */
+    address(): Promise<string>;
+    /**
+     * Verify that the keypair is valid by signing and verifying a test message.
+     */
+    verify(): boolean;
+}
+
+/**
+ * BIP-39 Mnemonic Seed Phrase Support for RougeChain
+ *
+ * Derivation path:
+ *   Mnemonic (12/24 words)
+ *     → PBKDF2 (standard BIP-39) → 512-bit seed
+ *     → HKDF-SHA256(seed, info="rougechain-ml-dsa-65-v1") → 32-byte ML-DSA seed
+ *     → ml_dsa65.keygen(seed) → deterministic keypair
+ *
+ * The domain separator ensures the same mnemonic produces different keys
+ * than Ethereum/Solana wallets, preventing cross-chain key reuse.
+ */
+/**
+ * Generate a new BIP-39 mnemonic phrase.
+ * @param strength 128 = 12 words (default), 256 = 24 words
+ */
+declare function generateMnemonic(strength?: 128 | 256): string;
+/**
+ * Validate a BIP-39 mnemonic phrase.
+ */
+declare function validateMnemonic(mnemonic: string): boolean;
+/**
+ * Derive a 32-byte ML-DSA-65 seed from a BIP-39 mnemonic.
+ *
+ * mnemonic → PBKDF2 → 512-bit BIP-39 seed → HKDF-SHA256 → 32-byte ML-DSA seed
+ *
+ * @param mnemonic  BIP-39 mnemonic (12 or 24 words)
+ * @param passphrase  Optional BIP-39 passphrase (25th word)
+ * @returns 32-byte seed suitable for ml_dsa65.keygen()
+ */
+declare function mnemonicToMLDSASeed(mnemonic: string, passphrase?: string): Uint8Array;
+/**
+ * Generate an ML-DSA-65 keypair from a BIP-39 mnemonic.
+ *
+ * Same mnemonic + passphrase always yields the same keypair.
+ *
+ * @param mnemonic  BIP-39 mnemonic (12 or 24 words)
+ * @param passphrase  Optional BIP-39 passphrase (25th word)
+ * @returns { publicKey, secretKey } as hex strings
+ */
+declare function keypairFromMnemonic(mnemonic: string, passphrase?: string): {
+    publicKey: string;
+    secretKey: string;
+};
+
+declare const BURN_ADDRESS = "XRGE_BURN_0x000000000000000000000000000000000000000000000000000000000000DEAD";
+declare function serializePayload(payload: TransactionPayload): Uint8Array;
+declare function signTransaction(payload: TransactionPayload, privateKey: string, publicKey: string): SignedTransaction;
+declare function verifyTransaction(signedTx: SignedTransaction): boolean;
+declare function isBurnAddress(address: string): boolean;
+declare function createSignedTokenMetadataUpdate(wallet: WalletKeys, tokenSymbol: string, metadata: {
+    image?: string;
+    description?: string;
+    website?: string;
+    twitter?: string;
+    discord?: string;
+}): SignedTransaction;
+declare function createSignedTokenMetadataClaim(wallet: WalletKeys, tokenSymbol: string): SignedTransaction;
+declare function createSignedTokenApproval(wallet: WalletKeys, spender: string, tokenSymbol: string, amount: number): SignedTransaction;
+declare function createSignedTokenTransferFrom(wallet: WalletKeys, owner: string, to: string, tokenSymbol: string, amount: number): SignedTransaction;
+declare function createSignedBridgeWithdraw(wallet: WalletKeys, amount: number, evmAddress: string, tokenSymbol?: string, fee?: number): SignedTransaction;
+declare function createSignedShield(wallet: WalletKeys, amount: number, commitment: string): SignedTransaction;
+declare function createSignedShieldedTransfer(wallet: WalletKeys, nullifiers: string[], outputCommitments: string[], proof: string, shieldedFee?: number): SignedTransaction;
+declare function createSignedUnshield(wallet: WalletKeys, nullifiers: string[], amount: number, proof: string): SignedTransaction;
+declare function signRequest(wallet: WalletKeys, payload: Record<string, unknown>): SignedTransaction;
+
+declare function hexToBytes(hex: string): Uint8Array;
+declare function bytesToHex(bytes: Uint8Array): string;
+declare function generateNonce(): string;
+
+/**
+ * RougeChain Bech32m Address Utilities for SDK
+ *
+ * Derives compact, human-readable addresses from PQC public keys:
+ *   address = bech32m("rouge", SHA-256(raw_pubkey_bytes))
+ *
+ * Result: ~63-char address like "rouge1q8f3x7k2m4n9p..."
+ * Matches the Rust implementation in core/crypto/src/lib.rs exactly.
+ */
+/**
+ * Derive a compact Bech32m address from an ML-DSA-65 public key (hex).
+ * Returns a ~63-character string like "rouge1q8f3x7k2m4n9p..."
+ */
+declare function pubkeyToAddress(publicKeyHex: string): Promise<string>;
+/**
+ * Decode a Bech32m address back to its 32-byte SHA-256 hash (hex).
+ */
+declare function addressToHash(address: string): string;
+/**
+ * Check if a string is a valid RougeChain Bech32m address.
+ */
+declare function isRougeAddress(input: string): boolean;
+/**
+ * Format an address for compact display: "rouge1q8f3...k9m2"
+ */
+declare function formatAddress(address: string, prefixLen?: number, suffixLen?: number): string;
+
+export { type AddLiquidityParams, type ApiResponse, type ApproveParams, type ArtistStats, BURN_ADDRESS, type BalanceResponse, type BatchMintNftParams, type Block, type BlockHeader, type BridgeClaimParams, type BridgeConfig, type BridgeWithdrawParams, type BridgeWithdrawal, type BurnNftParams, type CallContractParams, type ContractCallResult, type ContractEvent, type ContractMetadata, type CreateNftCollectionParams, type CreatePoolParams, type CreateTokenParams, type DeployContractParams, type FeeInfo, type FinalityProof, type FreezeCollectionParams, type LiquidityPool, type LockNftParams, type MailMessage, type MessengerConversation, type MessengerMessage, type MessengerWallet, type MintNftParams, type MintTokenParams, type NameEntry, type NftCollection, type NftToken, type NodeStats, type PoolEvent, type PoolStats, type PostStats, type PriceSnapshot, type RemoveLiquidityParams, type ResolvedName, type RollupBatchResult, type RollupStatus, type RollupSubmitParams, type RollupSubmitResult, RougeChain, type RougeChainOptions, type SendMailParams, type ShieldParams, type ShieldedNote, type ShieldedStats, type ShieldedTransferParams, type SignedTransaction, type SocialComment, type SocialPost, type StakeParams, type SwapParams, type SwapQuote, type SwapQuoteParams, type TokenHolder, type TokenMetadata, type TokenMetadataUpdateParams, type TrackStats, type Transaction, type TransactionPayload, type TransactionType, type TransferFromParams, type TransferNftParams, type TransferParams, type UnshieldParams, type Validator, type VoteMessage, Wallet, type WalletKeys, type WsSubscribeMessage, type XrgeBridgeClaimParams, type XrgeBridgeConfig, type XrgeBridgeWithdrawParams, addressToHash, bytesToHex, computeCommitment, computeNullifier, createShieldedNote, createSignedBridgeWithdraw, createSignedShield, createSignedShieldedTransfer, createSignedTokenApproval, createSignedTokenMetadataClaim, createSignedTokenMetadataUpdate, createSignedTokenTransferFrom, createSignedUnshield, formatAddress, generateMnemonic, generateNonce, generateRandomness, hexToBytes, isBurnAddress, isRougeAddress, keypairFromMnemonic, mnemonicToMLDSASeed, pubkeyToAddress, serializePayload, signRequest, signTransaction, validateMnemonic, verifyTransaction };