solana-web3-on-steroids 1.0.2

package/dist/transaction/SteroidTransaction.js

@@ -0,0 +1,275 @@
+import { Connection, TransactionExpiredBlockheightExceededError, } from '@solana/web3.js';
+import { TransactionState, DEFAULT_CONFIG } from '../types/SteroidWalletTypes.js';
+/**
+ * Enhanced transaction handling with state management, automatic retries,
+ * blockhash refresh, and multi-node confirmation.
+ */
+export class SteroidTransaction {
+    connection;
+    transactionStates = new Map();
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Sends a transaction with continuous re-broadcasting and multi-node monitoring.
+     * Includes automatic blockhash refresh and comprehensive error handling.
+     */
+    async sendAndConfirm(transaction, options = {}) {
+        const mergedOptions = {
+            skipPreflight: false,
+            preflightCommitment: 'processed',
+            ...DEFAULT_CONFIG.TRANSACTION,
+            ...options,
+        };
+        const { timeoutSeconds, retryInterval, skipPreflight, preflightCommitment, confirmationCommitment, maxBlockhashAge, enableLogging, confirmationNodes, } = mergedOptions;
+        const stateId = this.generateStateId();
+        const state = {
+            state: TransactionState.PENDING,
+            attempts: 0,
+            startTime: Date.now(),
+        };
+        this.transactionStates.set(stateId, state);
+        try {
+            // 1. Simulation with detailed error parsing
+            if (!skipPreflight) {
+                this.updateState(stateId, TransactionState.PENDING);
+                await this.simulateTransaction(transaction, preflightCommitment, enableLogging);
+                this.updateState(stateId, TransactionState.SIMULATED);
+            }
+            // 2. Initial blockhash setup if needed
+            let blockhashContext;
+            if (this.isLegacyTransaction(transaction)) {
+                blockhashContext = await this.getFreshBlockhash(enableLogging);
+                transaction.recentBlockhash = blockhashContext.blockhash;
+                transaction.lastValidBlockHeight = blockhashContext.lastValidBlockHeight;
+            }
+            const rawTransaction = this.serializeTransaction(transaction);
+            const startTime = Date.now();
+            let signature = '';
+            let lastBlockhashRefresh = Date.now();
+            // 3. Send and retry loop with blockhash refresh
+            while (Date.now() - startTime < timeoutSeconds * 1000) {
+                try {
+                    state.attempts++;
+                    state.lastAttemptTime = Date.now();
+                    // Check if blockhash is too old and refresh if needed
+                    const ageSeconds = (Date.now() - lastBlockhashRefresh) / 1000;
+                    if (ageSeconds > maxBlockhashAge && this.isLegacyTransaction(transaction)) {
+                        this.log('info', `Blockhash age ${ageSeconds.toFixed(1)}s exceeds max ${maxBlockhashAge}s, refreshing...`, enableLogging);
+                        blockhashContext = await this.getFreshBlockhash(enableLogging);
+                        transaction.recentBlockhash = blockhashContext.blockhash;
+                        transaction.lastValidBlockHeight = blockhashContext.lastValidBlockHeight;
+                        // Re-serialize with new blockhash
+                        // Note: This assumes the transaction is re-signed by the caller if needed
+                        lastBlockhashRefresh = Date.now();
+                    }
+                    // Broadcast transaction
+                    signature = await this.connection.sendRawTransaction(rawTransaction, {
+                        skipPreflight: true,
+                        maxRetries: 0, // We handle retries ourselves
+                    });
+                    this.updateState(stateId, TransactionState.SENT, signature);
+                    this.log('info', `Transaction sent: ${signature} (attempt ${state.attempts})`, enableLogging);
+                    // 4. Multi-node confirmation check
+                    const confirmed = await this.pollForConfirmation(signature, confirmationCommitment, confirmationNodes, enableLogging);
+                    if (confirmed) {
+                        this.updateState(stateId, TransactionState.CONFIRMED, signature);
+                        state.confirmedAt = Date.now();
+                        const duration = ((state.confirmedAt - state.startTime) / 1000).toFixed(2);
+                        this.log('info', `Transaction confirmed in ${duration}s after ${state.attempts} attempts`, enableLogging);
+                        return signature;
+                    }
+                    this.log('warn', `Transaction not yet confirmed, will retry in ${retryInterval}ms...`, enableLogging);
+                }
+                catch (error) {
+                    // Handle blockhash expiration
+                    if (this.isBlockhashExpiredError(error)) {
+                        this.log('warn', 'Blockhash expired or invalid, will refresh on next attempt', enableLogging);
+                        lastBlockhashRefresh = 0; // Force refresh on next iteration
+                    }
+                    else {
+                        this.log('warn', `Broadcast attempt failed: ${error.message}`, enableLogging);
+                    }
+                }
+                await this.sleep(retryInterval);
+            }
+            // Timeout reached
+            const errorMsg = `Transaction not confirmed within ${timeoutSeconds}s after ${state.attempts} attempts`;
+            this.updateState(stateId, TransactionState.EXPIRED, signature, errorMsg);
+            throw new Error(`[SteroidTransaction] ${errorMsg}. Last signature: ${signature || 'none'}`);
+        }
+        catch (error) {
+            this.updateState(stateId, TransactionState.FAILED, state.signature, error.message);
+            throw error;
+        }
+    }
+    /**
+     * Simulates a transaction and provides detailed error information.
+     */
+    async simulateTransaction(transaction, commitment, enableLogging) {
+        try {
+            const simulation = await this.connection.simulateTransaction(transaction, {
+                commitment,
+                replaceRecentBlockhash: true,
+            });
+            if (simulation.value.err) {
+                const errorDetails = this.parseSimulationError(simulation.value);
+                this.log('error', `Simulation failed: ${errorDetails}`, enableLogging);
+                throw new Error(`[SteroidTransaction] Simulation failed: ${errorDetails}`);
+            }
+            if (simulation.value.logs) {
+                this.log('info', `Simulation succeeded. Logs count: ${simulation.value.logs.length}`, enableLogging);
+            }
+        }
+        catch (error) {
+            if (error.message?.includes('Simulation failed'))
+                throw error;
+            throw new Error(`[SteroidTransaction] Simulation error: ${error.message}`);
+        }
+    }
+    /**
+     * Polls multiple RPC endpoints for signature status to bypass node lag.
+     */
+    async pollForConfirmation(signature, commitment, nodesToCheck, enableLogging) {
+        const endpoints = this.connection.getEndpoints();
+        const endpointsToCheck = endpoints.slice(0, Math.min(nodesToCheck, endpoints.length));
+        this.log('info', `Checking confirmation across ${endpointsToCheck.length} nodes...`, enableLogging);
+        const checks = endpointsToCheck.map(async (url) => {
+            try {
+                const tempConn = new Connection(url, { commitment });
+                const status = await tempConn.getSignatureStatus(signature);
+                if (status.value?.err) {
+                    throw new Error(`Transaction failed on ${url}: ${JSON.stringify(status.value.err)}`);
+                }
+                const isConfirmed = status.value?.confirmationStatus === 'confirmed' ||
+                    status.value?.confirmationStatus === 'finalized';
+                if (isConfirmed && status.value) {
+                    this.log('info', `Transaction confirmed on ${url} (${status.value.confirmationStatus})`, enableLogging);
+                    return true;
+                }
+                return false;
+            }
+            catch (error) {
+                this.log('warn', `Confirmation check failed for ${url}: ${error.message}`, enableLogging);
+                return false;
+            }
+        });
+        const results = await Promise.allSettled(checks);
+        // Fail-fast if any node reports a definitive transaction error
+        for (const result of results) {
+            if (result.status === 'rejected' && result.reason?.message?.includes('Transaction failed')) {
+                throw result.reason;
+            }
+        }
+        return results.some((r) => r.status === 'fulfilled' && r.value === true);
+    }
+    /**
+     * Get fresh blockhash with retry logic.
+     */
+    async getFreshBlockhash(enableLogging) {
+        try {
+            const { blockhash, lastValidBlockHeight } = await this.connection.getLatestBlockhash('confirmed');
+            this.log('info', `Fetched fresh blockhash: ${blockhash.slice(0, 8)}...`, enableLogging);
+            return { blockhash, lastValidBlockHeight };
+        }
+        catch (error) {
+            throw new Error(`[SteroidTransaction] Failed to get blockhash: ${error.message}`);
+        }
+    }
+    /**
+     * Parse simulation errors into human-readable format.
+     */
+    parseSimulationError(simulationValue) {
+        const logs = simulationValue.logs || [];
+        const errorLog = logs.find((l) => l.includes('Error:') || l.includes('failed') || l.includes('custom program error'));
+        if (errorLog)
+            return errorLog;
+        if (simulationValue.err) {
+            if (typeof simulationValue.err === 'string')
+                return simulationValue.err;
+            if (simulationValue.err.InstructionError) {
+                const [index, error] = simulationValue.err.InstructionError;
+                return `Instruction ${index} failed: ${JSON.stringify(error)}`;
+            }
+            return JSON.stringify(simulationValue.err);
+        }
+        return 'Unknown simulation error';
+    }
+    isBlockhashExpiredError(error) {
+        return (error instanceof TransactionExpiredBlockheightExceededError ||
+            error.message?.includes('block height exceeded') ||
+            error.message?.includes('blockhash not found'));
+    }
+    /**
+     * Type guard for legacy transactions.
+     */
+    isLegacyTransaction(transaction) {
+        return 'recentBlockhash' in transaction;
+    }
+    /**
+     * Serialize transaction to bytes.
+     */
+    serializeTransaction(transaction) {
+        if (this.isLegacyTransaction(transaction)) {
+            return transaction.serialize();
+        }
+        return Buffer.from(transaction.serialize());
+    }
+    generateStateId() {
+        return `tx_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+    }
+    updateState(stateId, state, signature, error) {
+        const existing = this.transactionStates.get(stateId);
+        if (existing) {
+            existing.state = state;
+            if (signature)
+                existing.signature = signature;
+            if (error)
+                existing.error = error;
+        }
+    }
+    log(level, message, enabled) {
+        if (!enabled)
+            return;
+        const prefix = '[SteroidTransaction]';
+        const formattedMessage = `${prefix} ${message}`;
+        switch (level) {
+            case 'info':
+                console.log(formattedMessage);
+                break;
+            case 'warn':
+                console.warn(formattedMessage);
+                break;
+            case 'error':
+                console.error(formattedMessage);
+                break;
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    /**
+     * Get the current state of a transaction.
+     */
+    getTransactionState(stateId) {
+        return this.transactionStates.get(stateId);
+    }
+    /**
+     * Get all transaction states (useful for debugging).
+     */
+    getAllTransactionStates() {
+        return new Map(this.transactionStates);
+    }
+    /**
+     * Clear old transaction states (cleanup).
+     */
+    clearOldStates(olderThanMs = 3600000) {
+        const now = Date.now();
+        for (const [id, state] of this.transactionStates.entries()) {
+            if (now - state.startTime > olderThanMs) {
+                this.transactionStates.delete(id);
+            }
+        }
+    }
+}
+//# sourceMappingURL=SteroidTransaction.js.map

package/dist/transaction/SteroidTransaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SteroidTransaction.js","sourceRoot":"","sources":["../../src/transaction/SteroidTransaction.ts"],"names":[],"mappings":"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"}

package/dist/types/SteroidWalletTypes.d.ts

@@ -0,0 +1,185 @@
+import type { Connection, ConnectionConfig, Commitment, PublicKey, Transaction, VersionedTransaction, TransactionSignature, SendOptions, BlockhashWithExpiryBlockHeight, SignatureStatus } from '@solana/web3.js';
+export type { Connection, ConnectionConfig, Commitment, PublicKey, Transaction, VersionedTransaction, TransactionSignature, SendOptions, BlockhashWithExpiryBlockHeight, SignatureStatus, };
+export interface SteroidConnectionConfig extends ConnectionConfig {
+    fallbacks?: string[];
+    maxRetries?: number;
+    retryDelay?: number;
+    healthCheckInterval?: number;
+    requestTimeout?: number;
+    enableLogging?: boolean;
+}
+export interface RPCHealth {
+    url: string;
+    healthy: boolean;
+    lastChecked: number;
+    latency?: number;
+}
+export interface FailoverStats {
+    count: number;
+    lastTime: number;
+}
+export interface SteroidSendOptions extends SendOptions {
+    timeoutSeconds?: number;
+    retryInterval?: number;
+    confirmationCommitment?: Commitment;
+    maxBlockhashAge?: number;
+    enableLogging?: boolean;
+    confirmationNodes?: number;
+}
+export declare enum TransactionState {
+    PENDING = "PENDING",
+    SIMULATED = "SIMULATED",
+    SIGNED = "SIGNED",
+    SENT = "SENT",
+    CONFIRMED = "CONFIRMED",
+    FINALIZED = "FINALIZED",
+    FAILED = "FAILED",
+    EXPIRED = "EXPIRED"
+}
+export interface TransactionStateInfo {
+    state: TransactionState;
+    signature?: string;
+    error?: string;
+    attempts: number;
+    startTime: number;
+    lastAttemptTime?: number;
+    confirmedAt?: number;
+}
+export interface WalletInterface {
+    publicKey: PublicKey | null;
+    signTransaction<T extends Transaction | VersionedTransaction>(transaction: T): Promise<T>;
+    signAllTransactions<T extends Transaction | VersionedTransaction>(transactions: T[]): Promise<T[]>;
+    signMessage?(message: Uint8Array): Promise<Uint8Array>;
+}
+export declare enum WalletErrorType {
+    NOT_CONNECTED = "NOT_CONNECTED",
+    USER_REJECTED = "USER_REJECTED",
+    NETWORK_MISMATCH = "NETWORK_MISMATCH",
+    SIGNING_FAILED = "SIGNING_FAILED",
+    UNSUPPORTED_OPERATION = "UNSUPPORTED_OPERATION",
+    UNKNOWN = "UNKNOWN"
+}
+export interface SteroidWalletConfig {
+    validateNetwork?: boolean;
+    expectedGenesisHash?: string;
+    enableLogging?: boolean;
+    autoRefreshBlockhash?: boolean;
+    maxBlockhashAge?: number;
+}
+export interface NetworkInfo {
+    genesisHash?: string;
+    validated: boolean;
+}
+/**
+ * Client Types
+ */
+export interface SteroidClientConfig {
+    connection?: SteroidConnectionConfig;
+    wallet?: SteroidWalletConfig;
+    enableLogging?: boolean;
+}
+export interface ClientStats {
+    activeEndpoint: string;
+    allEndpoints: string[];
+    failoverStats: FailoverStats;
+    healthStatus: RPCHealth[];
+}
+/**
+ * Network Types
+ */
+export type NetworkType = 'mainnet-beta' | 'devnet' | 'testnet';
+/**
+ * Utility Types
+ */
+export type AnyTransaction = Transaction | VersionedTransaction;
+export type SignedTransaction<T extends AnyTransaction = AnyTransaction> = T;
+export type TransactionResult = {
+    signature: TransactionSignature;
+    confirmedAt: number;
+    attempts: number;
+};
+export type ErrorHandler = (error: Error) => void | Promise<void>;
+export type TransactionCallback = (signature: TransactionSignature, state: TransactionStateInfo) => void | Promise<void>;
+/**
+ * Type guards
+ */
+export declare function isLegacyTransaction(transaction: AnyTransaction): transaction is Transaction;
+export declare function isVersionedTransaction(transaction: AnyTransaction): transaction is VersionedTransaction;
+/**
+ * Helper types for improved DX
+ */
+export type WithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Event types for potential event emitter implementation
+ */
+export interface SteroidEvents {
+    'transaction:pending': {
+        signature?: string;
+    };
+    'transaction:simulated': {
+        signature?: string;
+    };
+    'transaction:sent': {
+        signature: string;
+    };
+    'transaction:confirmed': {
+        signature: string;
+        attempts: number;
+    };
+    'transaction:failed': {
+        signature?: string;
+        error: Error;
+    };
+    'connection:failover': {
+        from: string;
+        to: string;
+    };
+    'connection:health-check': {
+        health: RPCHealth[];
+    };
+    'wallet:connected': {
+        publicKey: PublicKey;
+    };
+    'wallet:disconnected': {};
+}
+/**
+ * Constants
+ */
+export declare const DEFAULT_CONFIG: {
+    readonly CONNECTION: {
+        readonly maxRetries: 5;
+        readonly retryDelay: 500;
+        readonly healthCheckInterval: 30000;
+        readonly requestTimeout: 30000;
+        readonly enableLogging: false;
+    };
+    readonly TRANSACTION: {
+        readonly timeoutSeconds: 60;
+        readonly retryInterval: 2000;
+        readonly confirmationCommitment: Commitment;
+        readonly maxBlockhashAge: 60;
+        readonly confirmationNodes: 3;
+        readonly enableLogging: false;
+    };
+    readonly WALLET: {
+        readonly validateNetwork: true;
+        readonly enableLogging: false;
+        readonly autoRefreshBlockhash: true;
+        readonly maxBlockhashAge: 60;
+    };
+};
+/**
+ * Export type for package consumers
+ */
+export interface SteroidWalletPackage {
+    SteroidClient: any;
+    SteroidConnection: any;
+    SteroidTransaction: any;
+    SteroidWallet: any;
+    WalletError: any;
+    createSteroidClient: any;
+}

package/dist/types/SteroidWalletTypes.js

@@ -0,0 +1,56 @@
+export var TransactionState;
+(function (TransactionState) {
+    TransactionState["PENDING"] = "PENDING";
+    TransactionState["SIMULATED"] = "SIMULATED";
+    TransactionState["SIGNED"] = "SIGNED";
+    TransactionState["SENT"] = "SENT";
+    TransactionState["CONFIRMED"] = "CONFIRMED";
+    TransactionState["FINALIZED"] = "FINALIZED";
+    TransactionState["FAILED"] = "FAILED";
+    TransactionState["EXPIRED"] = "EXPIRED";
+})(TransactionState || (TransactionState = {}));
+export var WalletErrorType;
+(function (WalletErrorType) {
+    WalletErrorType["NOT_CONNECTED"] = "NOT_CONNECTED";
+    WalletErrorType["USER_REJECTED"] = "USER_REJECTED";
+    WalletErrorType["NETWORK_MISMATCH"] = "NETWORK_MISMATCH";
+    WalletErrorType["SIGNING_FAILED"] = "SIGNING_FAILED";
+    WalletErrorType["UNSUPPORTED_OPERATION"] = "UNSUPPORTED_OPERATION";
+    WalletErrorType["UNKNOWN"] = "UNKNOWN";
+})(WalletErrorType || (WalletErrorType = {}));
+/**
+ * Type guards
+ */
+export function isLegacyTransaction(transaction) {
+    return 'recentBlockhash' in transaction;
+}
+export function isVersionedTransaction(transaction) {
+    return 'version' in transaction;
+}
+/**
+ * Constants
+ */
+export const DEFAULT_CONFIG = {
+    CONNECTION: {
+        maxRetries: 5,
+        retryDelay: 500,
+        healthCheckInterval: 30000,
+        requestTimeout: 30000,
+        enableLogging: false,
+    },
+    TRANSACTION: {
+        timeoutSeconds: 60,
+        retryInterval: 2000,
+        confirmationCommitment: 'confirmed',
+        maxBlockhashAge: 60,
+        confirmationNodes: 3,
+        enableLogging: false,
+    },
+    WALLET: {
+        validateNetwork: true,
+        enableLogging: false,
+        autoRefreshBlockhash: true,
+        maxBlockhashAge: 60,
+    },
+};
+//# sourceMappingURL=SteroidWalletTypes.js.map

package/dist/types/SteroidWalletTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SteroidWalletTypes.js","sourceRoot":"","sources":["../../src/types/SteroidWalletTypes.ts"],"names":[],"mappings":"AA2DA,MAAM,CAAN,IAAY,gBASX;AATD,WAAY,gBAAgB;IAC1B,uCAAmB,CAAA;IACnB,2CAAuB,CAAA;IACvB,qCAAiB,CAAA;IACjB,iCAAa,CAAA;IACb,2CAAuB,CAAA;IACvB,2CAAuB,CAAA;IACvB,qCAAiB,CAAA;IACjB,uCAAmB,CAAA;AACrB,CAAC,EATW,gBAAgB,KAAhB,gBAAgB,QAS3B;AAqBD,MAAM,CAAN,IAAY,eAOX;AAPD,WAAY,eAAe;IACzB,kDAA+B,CAAA;IAC/B,kDAA+B,CAAA;IAC/B,wDAAqC,CAAA;IACrC,oDAAiC,CAAA;IACjC,kEAA+C,CAAA;IAC/C,sCAAmB,CAAA;AACrB,CAAC,EAPW,eAAe,KAAf,eAAe,QAO1B;AAwDD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,WAA2B;IAE3B,OAAO,iBAAiB,IAAI,WAAW,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,WAA2B;IAE3B,OAAO,SAAS,IAAI,WAAW,CAAC;AAClC,CAAC;AA4BD;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU,EAAE;QACV,UAAU,EAAE,CAAC;QACb,UAAU,EAAE,GAAG;QACf,mBAAmB,EAAE,KAAK;QAC1B,cAAc,EAAE,KAAK;QACrB,aAAa,EAAE,KAAK;KACrB;IACD,WAAW,EAAE;QACX,cAAc,EAAE,EAAE;QAClB,aAAa,EAAE,IAAI;QACnB,sBAAsB,EAAE,WAAyB;QACjD,eAAe,EAAE,EAAE;QACnB,iBAAiB,EAAE,CAAC;QACpB,aAAa,EAAE,KAAK;KACrB;IACD,MAAM,EAAE;QACN,eAAe,EAAE,IAAI;QACrB,aAAa,EAAE,KAAK;QACpB,oBAAoB,EAAE,IAAI;QAC1B,eAAe,EAAE,EAAE;KACpB;CACO,CAAC"}

package/dist/wallet/SteroidWallet.d.ts

@@ -0,0 +1,85 @@
+import { PublicKey, Transaction, VersionedTransaction, TransactionSignature } from '@solana/web3.js';
+import { SteroidConnection } from '../connection/SteroidConnection.js';
+import { WalletInterface, WalletErrorType, SteroidWalletConfig, SteroidSendOptions } from '../types/SteroidWalletTypes.js';
+export declare class WalletError extends Error {
+    type: WalletErrorType;
+    originalError?: any | undefined;
+    constructor(type: WalletErrorType, message: string, originalError?: any | undefined);
+}
+/**
+ * SteroidWallet wraps any Solana wallet adapter and provides:
+ * - Normalized error handling across different wallet implementations
+ * - Network consistency validation
+ * - Automatic transaction retry and confirmation
+ * - Graceful degradation for missing wallet features
+ */
+export declare class SteroidWallet {
+    private wallet;
+    private connection;
+    private txEngine;
+    private config;
+    private networkValidated;
+    private genesisHash?;
+    constructor(wallet: WalletInterface, connection: SteroidConnection, config?: SteroidWalletConfig);
+    /**
+     * Get the wallet's public key.
+     */
+    get publicKey(): PublicKey | null;
+    /**
+     * Signs and sends a transaction with full reliability guarantees.
+     * Handles blockhash refresh, retries, and multi-node confirmation.
+     */
+    signAndSend(transaction: Transaction | VersionedTransaction, options?: SteroidSendOptions): Promise<TransactionSignature>;
+    /**
+     * Sign a transaction safely with normalized error handling.
+     */
+    signTransaction<T extends Transaction | VersionedTransaction>(transaction: T): Promise<T>;
+    /**
+     * Sign multiple transactions safely.
+     */
+    signAllTransactions<T extends Transaction | VersionedTransaction>(transactions: T[]): Promise<T[]>;
+    /**
+     * Sign a message with standardized error handling.
+     */
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+    /**
+     * System-level state validation before operations.
+     */
+    private guardState;
+    /**
+     * Validates that the wallet and connection are on the same network.
+     */
+    private validateNetwork;
+    /**
+     * Ensures transaction has a fresh blockhash.
+     */
+    private ensureFreshBlockhash;
+    /**
+     * Safely sign a transaction with proper error handling.
+     */
+    private signTransactionSafe;
+    /**
+     * Normalizes different wallet errors into a consistent format.
+     */
+    private normalizeError;
+    /**
+     * Type guard for legacy transactions.
+     */
+    private isLegacyTransaction;
+    private log;
+    /**
+     * Get network information.
+     */
+    getNetworkInfo(): {
+        genesisHash?: string;
+        validated: boolean;
+    };
+    /**
+     * Force re-validation of network on next operation.
+     */
+    invalidateNetwork(): void;
+    /**
+     * Check if wallet supports message signing.
+     */
+    supportsMessageSigning(): boolean;
+}