wisdom-sdk/dist/prediction-contract-store.d.ts

Core business logic and data access layer for prediction markets

/**
 * Prediction Contract Store: Direct interface to the Clarity smart contract
 *
 * This module provides function wrappers for interacting with the
 * prediction market contract. It abstracts the complexity of making direct
 * contract calls and provides a cleaner interface for the rest of the application.
 *
 * Includes both read-only functions and functions for state-changing operations.
 *
 * Uses a robust client implementation with:
 * - Multiple API endpoint fallbacks
 * - API key rotation
 * - Automatic retries
 * - Request batching
 */
/**
 * Helper interface for market structure in the contract
 */
interface PredictionMarketInfo {
    creator: string;
    name: string;
    description: string;
    'outcome-names': string[];
    'outcome-pools': number[];
    'total-pool': number;
    'is-open': boolean;
    'is-resolved': boolean;
    'winning-outcome': number;
    resolver?: string;
    'creation-time': number;
    'resolution-time': number;
}
/**
 * Helper interface for prediction receipt information
 */
interface PredictionReceiptInfo {
    'market-id': string;
    'outcome-id': number;
    amount: number;
    predictor?: string;
}
/**
 * Interface for prediction reward quote
 */
interface PredictionRewardQuote {
    dx: string;
    dy: number;
    dk: number;
}
/**
 * Interface for market creation result
 */
interface MarketCreationResult {
    marketId: string;
    creator: string;
    creationTime: number;
}
/**
 * Interface for market resolution request
 */
interface MarketResolutionRequest {
    marketId: string;
    winningOutcomeId: number;
}
/**
 * Interface for prediction transaction result
 */
interface PredictionTransactionResult {
    dx: string;
    dy: number;
    dk: number;
}
/**
 * Interface for signed transaction parameters
 */
interface SignedTransactionParams {
    signature: string;
    nonce: number;
}
/**
 * Interface for batch prediction operation
 */
interface BatchPredictionOperation {
    signet: SignedTransactionParams;
    marketId: string;
    outcomeId: number;
    amount: number;
}
/**
 * Interface for batch claim reward operation
 */
interface BatchClaimOperation {
    signet: SignedTransactionParams;
    receiptId: number;
}
/**
 * Prediction contract store with functions to query and interact with the contract
 */
declare const predictionContractStore: {
    /**
     * Utility functions for managing the metadata cache
     */
    cache: {
        /**
         * Clear all metadata caches
         */
        clearAll(): void;
        /**
         * Clear market info cache for a specific market
         * @param marketId The ID of the market to clear from cache
         */
        clearMarketInfo(marketId: string): void;
        /**
         * Clear receipt info cache for a specific receipt
         * @param receiptId The ID of the receipt to clear from cache
         */
        clearReceiptInfo(receiptId: number): void;
        /**
         * Get cache statistics
         * @returns Object with cache counts
         */
        getStats(): {
            marketInfoCount: number;
            receiptInfoCount: number;
            rewardQuoteCount: number;
            receiptOwnerCount: number;
            cacheExpirationMs: number;
        };
    };
    /**
     * Check if a receipt ID exists on the blockchain by checking if it has an owner
     * @param receiptId The ID of the receipt to check
     * @param skipCache Whether to skip the cache and force a fresh lookup
     * @returns True if the receipt exists and has an owner, false otherwise
     */
    doesReceiptExist(receiptId: number, skipCache?: boolean): Promise<boolean>;
    /**
     * Get the owner of a receipt from the contract
     * @param receiptId The ID of the receipt to check
     * @param skipCache Whether to skip the cache and force a fresh lookup
     * @returns The principal address of the owner, or null if not found or error
     */
    getReceiptOwner(receiptId: number, skipCache?: boolean): Promise<string | null>;
    /**
     * Get information about a specific market from the contract
     * @param marketId The ID of the market to check
     * @param skipCache Whether to skip the cache and force a fresh lookup
     * @returns Market information or null if not found or error
     */
    getMarketInfo(marketId: string, skipCache?: boolean): Promise<PredictionMarketInfo | null>;
    /**
     * Get information about a specific prediction receipt from the contract
     * @param receiptId The ID of the receipt to check
     * @param skipCache Whether to skip the cache and force a fresh lookup
     * @returns Receipt information or null if not found or error
     */
    getReceiptInfo(receiptId: number, skipCache?: boolean): Promise<PredictionReceiptInfo | null>;
    /**
     * Check if a prediction is eligible for reward based on the resolved market
     * This calls the quote-reward function to see if there's any reward available
     *
     * @param receiptId The ID of the receipt to check
     * @param skipCache Whether to skip the cache and force a fresh lookup
     * @returns Object with reward info or null if not found or error
     */
    getRewardQuote(receiptId: number, skipCache?: boolean): Promise<PredictionRewardQuote | null>;
    /**
     * Check if a prediction has won in a resolved market
     *
     * @param receiptId The ID of the receipt to check
     * @param skipCache Whether to skip the cache and force a fresh lookup
     * @returns Boolean indicating if the prediction is a winner (with reward > 0)
     */
    isPredictionWinner(receiptId: number, skipCache?: boolean): Promise<boolean>;
    /**
     * Get the status of a prediction based on market resolution and outcome
     * This combines multiple contract calls to determine the full status
     *
     * @param receiptId The ID of the receipt to check
     * @param skipCache Whether to skip the cache and force a fresh lookup
     * @returns 'unresolved' | 'won' | 'lost' | 'redeemed' | null (if error or not found)
     */
    getPredictionStatus(receiptId: number, skipCache?: boolean): Promise<"unresolved" | "won" | "lost" | "redeemed" | null>;
    /**
     * Get predictions that should be marked as won or lost based on market resolution
     * This checks for receipts with 'pending' status in custody but that should be 'won' or 'lost'
     * based on the blockchain state
     *
     * @param pendingIds List of receipt IDs that are currently 'pending' in custody
     * @param skipCache Whether to skip the cache and force a fresh lookup for all predictions
     * @returns Object containing arrays of 'won' and 'lost' IDs
     */
    getStatusUpdatesForPendingPredictions(pendingIds: number[], skipCache?: boolean): Promise<{
        won: number[];
        lost: number[];
        errors: number[];
    }>;
    /**
     * Create a new prediction market on the blockchain
     * @param marketId Unique identifier for the market (max 64 ASCII chars)
     * @param name Name of the market (max 64 ASCII chars)
     * @param description Description of the market (max 128 ASCII chars)
     * @param outcomeNames List of possible outcome names (max 16 outcomes, each max 32 chars)
     * @param senderKey Private key of the sender (defaults to contract config)
     * @returns Result of the transaction with market creation details
     */
    createMarket(marketId: string, name: string, description: string, outcomeNames: string[], senderKey?: string): Promise<{
        success: boolean;
        result?: MarketCreationResult;
        txid?: string;
        error?: string;
    }>;
    /**
     * Close a market (no more predictions allowed)
     * @param marketId The ID of the market to close
     * @param senderKey Private key of the sender (must be admin or deployer)
     * @returns Result of the transaction
     */
    closeMarket(marketId: string, senderKey?: string): Promise<{
        success: boolean;
        txid?: string;
        error?: string;
    }>;
    /**
     * Resolve a market by setting the winning outcome
     * @param marketId The ID of the market to resolve
     * @param winningOutcomeId The ID of the winning outcome
     * @param senderKey Private key of the sender (must be admin or deployer)
     * @returns Result of the transaction
     */
    resolveMarket(marketId: string, winningOutcomeId: number, senderKey?: string): Promise<{
        success: boolean;
        txid?: string;
        error?: string;
    }>;
    /**
     * Make a prediction on a market outcome (direct transaction)
     * @param marketId The ID of the market
     * @param outcomeId The ID of the outcome being predicted
     * @param amount The amount to stake on this prediction
     * @param senderKey Private key of the sender
     * @returns Result of the transaction with prediction details
     */
    makePrediction(marketId: string, outcomeId: number, amount: number, senderKey: string): Promise<{
        success: boolean;
        result?: PredictionTransactionResult;
        txid?: string;
        error?: string;
    }>;
    /**
     * Make a prediction using a signed transaction
     * @param signet Signature and nonce for the transaction
     * @param marketId The ID of the market
     * @param outcomeId The ID of the outcome being predicted
     * @param amount The amount to stake on this prediction
     * @param senderKey Private key for sending the transaction (admin key)
     * @returns Result of the transaction with prediction details
     */
    signedPredict(signet: SignedTransactionParams, marketId: string, outcomeId: number, amount: number, senderKey?: string): Promise<{
        success: boolean;
        result?: PredictionTransactionResult;
        txid?: string;
        error?: string;
    }>;
    /**
     * Claim a reward for a winning prediction
     * @param receiptId The ID of the winning prediction receipt
     * @param senderKey Private key of the receipt owner
     * @returns Result of the transaction with reward details
     */
    claimReward(receiptId: number, senderKey: string): Promise<{
        success: boolean;
        result?: PredictionTransactionResult;
        txid?: string;
        error?: string;
    }>;
    /**
     * Claim a reward using a signed transaction
     * @param signet Signature and nonce for the transaction
     * @param receiptId The ID of the winning prediction receipt
     * @param senderKey Private key for sending the transaction (admin key)
     * @returns Result of the transaction with reward details
     */
    signedClaimReward(signet: SignedTransactionParams, receiptId: number, senderKey?: string): Promise<{
        success: boolean;
        result?: PredictionTransactionResult;
        txid?: string;
        error?: string;
    }>;
    /**
     * Process a batch of prediction operations in a single transaction
     * @param operations Array of prediction operations to execute
     * @param senderKey Private key for sending the transaction (admin key)
     * @returns Result of the batch operation
     */
    batchPredict(operations: BatchPredictionOperation[], senderKey?: string): Promise<{
        success: boolean;
        results?: boolean[];
        txid?: string;
        error?: string;
    }>;
    /**
     * Process a batch of claim reward operations in a single transaction
     * @param operations Array of claim reward operations to execute
     * @param senderKey Private key for sending the transaction (admin key)
     * @param waitForStatus Whether to wait for transaction status to be confirmed
     * @returns Result of the batch operation
     */
    batchClaimReward(operations: BatchClaimOperation[], senderKey?: string, waitForStatus?: boolean): Promise<{
        success: boolean;
        results?: boolean[];
        txid?: string;
        error?: string;
        status?: string;
    }>;
    /**
     * Add an admin to the contract
     * @param adminAddress The principal address to add as admin
     * @param senderKey Private key of the contract deployer (required)
     * @returns Result of the transaction
     */
    addAdmin(adminAddress: string, senderKey?: string): Promise<{
        success: boolean;
        txid?: string;
        error?: string;
    }>;
    /**
     * Remove an admin from the contract
     * @param adminAddress The principal address to remove as admin
     * @param senderKey Private key of the contract deployer (required)
     * @returns Result of the transaction
     */
    removeAdmin(adminAddress: string, senderKey?: string): Promise<{
        success: boolean;
        txid?: string;
        error?: string;
    }>;
};

export { type BatchClaimOperation, type BatchPredictionOperation, type MarketCreationResult, type MarketResolutionRequest, type PredictionMarketInfo, type PredictionReceiptInfo, type PredictionRewardQuote, type PredictionTransactionResult, type SignedTransactionParams, predictionContractStore };