jito-distributor-sdk/dist/src/versioning-system.d.ts

TypeScript SDK for JITO Merkle Distributor with production-ready versioning and double-hashing support

import { Connection, PublicKey } from '@solana/web3.js';
import BigNumber from 'bignumber.js';
/**
 * Constants for the versioning system
 */
export declare const VERSIONING_CONSTANTS: {
    readonly MAX_DEPLOYMENTS_PER_USER: 65536;
    readonly USER_FINGERPRINT_BITS: 48;
    readonly SEQUENCE_BITS: 16;
    readonly MERKLE_DISTRIBUTOR_DISCRIMINATOR: "MerkleDistributor";
    readonly MERKLE_DISTRIBUTOR_ACCOUNT_SIZE: 177;
    readonly MAX_RETRY_ATTEMPTS: 3;
    readonly RETRY_DELAY_MS: 500;
};
/**
 * Custom error types for versioning system
 */
export declare class VersioningError extends Error {
    code: string;
    constructor(message: string, code: string);
}
export declare class DeploymentLimitExceededError extends VersioningError {
    constructor(currentCount: number, maxAllowed: number);
}
export declare class RaceConditionError extends VersioningError {
    constructor(version: string);
}
/**
 * Result type for version generation
 */
export interface VersionGenerationResult {
    version: BigNumber;
    sequence: number;
    userFingerprint: BigNumber;
    deploymentCount: number;
}
/**
 * Configuration for the versioning system
 */
export interface VersioningConfig {
    connection: Connection;
    programId: PublicKey;
    mintAddress: PublicKey;
}
/**
 * Deployment result with retry information
 */
export interface DeploymentAttemptResult extends VersionGenerationResult {
    attempt: number;
    retried: boolean;
}
/**
 * Main versioning system class for JITO Merkle Distributor
 */
export declare class DeterministicVersioning {
    private connection;
    private programId;
    private mintAddress;
    constructor(config: VersioningConfig);
    /**
     * Generates a deterministic user fingerprint from wallet public key
     * Takes the first 48 bits of SHA-256 hash of the wallet pubkey
     */
    private generateUserFingerprint;
    /**
     * Queries the blockchain to count existing distributor accounts for a user
     * This gives us the reliable sequence number for next deployment
     */
    getUserDeploymentCount(walletPubkey: PublicKey): Promise<number>;
    /**
     * Generates a deterministic, collision-free version number
     * Format: [48-bit user fingerprint][16-bit sequence number]
     */
    private generateVersionNumber;
    /**
     * Main function: Get the next version number for a user's deployment
     * Combines on-chain sequence tracking with deterministic generation
     */
    getNextVersion(walletPubkey: PublicKey): Promise<VersionGenerationResult>;
    /**
     * Race-condition safe deployment version generation with auto-retry
     * This is the recommended method for UI usage
     */
    getNextVersionWithRetry(walletPubkey: PublicKey): Promise<DeploymentAttemptResult>;
    /**
     * Utility: Verify a version number was generated correctly
     * Useful for debugging and validation
     */
    verifyVersion(walletPubkey: PublicKey, version: BigNumber): Promise<boolean>;
    /**
     * Utility: Decode a version number back to its components
     * Useful for debugging and analytics
     */
    static decodeVersion(version: BigNumber): {
        userFingerprint: BigNumber;
        sequence: number;
    };
    /**
     * Utility: Convert version to little-endian Buffer for Solana
     * Ensures proper endianness for PDA derivation
     */
    static versionToLEBuffer(version: BigNumber): Buffer;
    /**
     * Utility: Get deployment history for a user
     * Returns all versions this user has deployed
     */
    getUserDeploymentHistory(walletPubkey: PublicKey): Promise<BigNumber[]>;
    /**
     * Utility: Estimate collision probability for given user count
     * Returns probability as percentage for easier monitoring
     */
    static estimateCollisionProbability(userCount: number, deploymentsPerUser?: number): {
        probability: number;
        probabilityPercent: string;
        isAcceptable: boolean;
    };
}
/**
 * Simple deterministic versioning utilities (from legacy deterministic-version.ts)
 * Kept for backwards compatibility and simple use cases
 */
/**
 * Generate a simple deterministic version number unique to the deployer's wallet
 * This ensures no collisions with other deployers while being reproducible
 */
export declare function getDeterministicVersion(deployerPubkey: PublicKey, salt?: string): bigint;
/**
 * Generate a deterministic version with custom salt for multiple distributions
 */
export declare function getDistributionVersion(deployerPubkey: PublicKey, distributionName: string): bigint;
/**
 * Generate a time-based deterministic version (changes daily)
 */
export declare function getDailyVersion(deployerPubkey: PublicKey, date?: Date): bigint;
/**
 * Generate a sequential version for the same deployer
 */
export declare function getSequentialVersion(deployerPubkey: PublicKey, sequence: number): bigint;
/**
 * Convenience function for quick version generation with race protection
 * Recommended for React UI usage with JITO Merkle Distributor
 */
export declare function generateNextVersionSafe(connection: Connection, programId: PublicKey, mintAddress: PublicKey, walletPubkey: PublicKey): Promise<DeploymentAttemptResult>;
/**
 * Utility to detect if error is from account collision
 */
export declare function isAccountCollisionError(error: any): boolean;