@0xio/sdk 2.5.0 → 2.7.0

package/dist/index.umd.js

@@ -41,8 +41,9 @@
          */
         once(eventType, listener) {
             const onceListener = (event) => {
-                listener(event);
+                // Remove BEFORE calling so a throwing listener doesn't stay registered
                 this.off(eventType, onceListener);
+                listener(event);
             };
             this.on(eventType, onceListener);
         }
@@ -143,6 +144,135 @@
         }
     }
 
+    /**
+     * 0xio Wallet transport adapter.
+     *
+     * Implements the postMessage protocol used by the 0xio browser extension (>= v2.4.0).
+     *
+     * Outbound wire format:
+     *   window.postMessage({ source: '0xio-sdk-request', request: { id, method, params, timestamp } }, origin)
+     *
+     * Inbound wire format:
+     *   window.postMessage({ source: '0xio-sdk-bridge', response: { id, success, data, error }, sessionNonce })
+     *   window.postMessage({ source: '0xio-sdk-bridge', event: { type, data } })
+     *
+     * H-2: Session nonce validation — injected.ts broadcasts the nonce received from the
+     * isolated content script. Once set, any '0xio-sdk-bridge' response with a missing or
+     * mismatched nonce is rejected, preventing response injection by malicious page scripts.
+     */
+    /**
+     * Creates a 0xio adapter. The factory accepts optional extra trusted parent origins
+     * so the communicator can forward its own trustedOrigins setting to origin validation.
+     */
+    function createZeroXIOAdapter(extraTrustedOrigins = []) {
+        return {
+            name: '0xio',
+            displayName: '0xio Wallet',
+            detect() {
+                if (typeof window === 'undefined')
+                    return false;
+                const win = window;
+                return !!(win.wallet0xio ||
+                    win.ZeroXIOWallet ||
+                    // 0xio extension also exposes window.octra with isOctra=true; match it here
+                    // so this adapter (postMessage protocol) takes priority over OctraProviderAdapter
+                    (win.octra?.isOctra && (win.wallet0xio || win.ZeroXIOWallet)) ||
+                    win.chrome?.runtime?.id ||
+                    document.querySelector('meta[name="0xio-dapp"]') ||
+                    document.querySelector('[data-0xio-sdk-bridge]'));
+            },
+            postRequest(request) {
+                window.postMessage({ source: '0xio-sdk-request', request }, window.location.origin);
+            },
+            postRequestToParent(request, parentOrigin) {
+                try {
+                    window.parent.postMessage({ source: '0xio-sdk-request', request }, parentOrigin);
+                }
+                catch {
+                    // Do not fall back to '*' — silent failure is safer
+                }
+            },
+            listen(handler, options) {
+                const allowedOrigin = window.location.origin;
+                const trustedParentOrigins = new Set([
+                    allowedOrigin,
+                    'tauri://localhost',
+                    'https://tauri.localhost',
+                    'http://localhost',
+                    'https://localhost',
+                    ...(extraTrustedOrigins),
+                    ...(options?.trustedParentOrigins ?? []),
+                ]);
+                let _sessionNonce = null;
+                // H-2: receive session nonce from injected.ts (MAIN world content script)
+                const nonceListener = (e) => {
+                    if (e.origin !== allowedOrigin)
+                        return;
+                    if (e.data?.source === '0xio-sdk-nonce-init' && typeof e.data.nonce === 'string') {
+                        _sessionNonce = e.data.nonce;
+                        window.removeEventListener('message', nonceListener);
+                    }
+                };
+                window.addEventListener('message', nonceListener);
+                const msgListener = (e) => {
+                    const isFromSameOrigin = e.origin === allowedOrigin;
+                    const isLocalhost = e.origin.startsWith('http://localhost:') ||
+                        e.origin.startsWith('http://127.0.0.1:');
+                    const isFromTrustedParent = e.source === window.parent &&
+                        window.parent !== window &&
+                        (trustedParentOrigins.has(e.origin) || isLocalhost);
+                    if (!isFromSameOrigin && !isFromTrustedParent)
+                        return;
+                    if (e.source !== window && e.source !== window.parent)
+                        return;
+                    if (!e.data || e.data.source !== '0xio-sdk-bridge')
+                        return;
+                    // H-2: session nonce validation.
+                    // Preferred path: nonce set via 0xio-sdk-nonce-init from injected.ts.
+                    // Fallback path: if the init broadcast was missed (race between document_start
+                    // content script and page script load), capture nonce from the first same-origin
+                    // response so that all subsequent responses are validated.
+                    if (!_sessionNonce && isFromSameOrigin && typeof e.data.sessionNonce === 'string') {
+                        _sessionNonce = e.data.sessionNonce;
+                    }
+                    if (_sessionNonce && e.data.sessionNonce !== _sessionNonce)
+                        return;
+                    if (e.data.response) {
+                        const r = e.data.response;
+                        handler({
+                            requestId: r.id,
+                            success: r.success,
+                            data: r.data,
+                            error: r.error,
+                        });
+                    }
+                    else if (e.data.event) {
+                        handler({
+                            eventType: e.data.event.type,
+                            eventData: e.data.event.data ?? e.data.event,
+                        });
+                    }
+                };
+                window.addEventListener('message', msgListener);
+                return () => {
+                    window.removeEventListener('message', nonceListener);
+                    window.removeEventListener('message', msgListener);
+                };
+            },
+            listenForReady(onReady) {
+                const handler = () => onReady();
+                window.addEventListener('0xioWalletReady', handler);
+                window.addEventListener('wallet0xioReady', handler);
+                return () => {
+                    window.removeEventListener('0xioWalletReady', handler);
+                    window.removeEventListener('wallet0xioReady', handler);
+                };
+            },
+        };
+    }
+    /** Default 0xio adapter instance (no extra trusted origins). */
+    const ZeroXIOAdapter = createZeroXIOAdapter();
+
     /**
      * 0xio Wallet SDK - Utilities
      * Helper functions for validation, formatting, and common operations
@@ -162,9 +292,15 @@
         return addressRegex.test(address);
     }
     /**
-     * Validate transaction amount
+     * Validate transaction amount.
+     * Accepts both number and string representations.
+     * String amounts avoid JS number precision loss for very large values.
      */
     function isValidAmount(amount) {
+        if (typeof amount === 'string') {
+            const n = parseFloat(amount);
+            return !isNaN(n) && n > 0 && Number.isFinite(n);
+        }
         return typeof amount === 'number' &&
             amount > 0 &&
             Number.isFinite(amount) &&
@@ -174,11 +310,13 @@
      * Validate transaction message
      */
     function isValidMessage(message) {
-        if (!message) {
-            return true; // Empty messages are valid
-        }
+        // Type check first — falsy non-strings (0, false, null) are NOT valid messages
         if (typeof message !== 'string') {
-            return false;
+            return message === undefined || message === null ? true : false;
+        }
+        // Empty string is valid (optional field)
+        if (message.length === 0) {
+            return true;
         }
         // 100KB limit — contract call params can be large (serialized JSON)
         return message.length <= 100000;
@@ -190,16 +328,64 @@
         return feeLevel === 1 || feeLevel === 3;
     }
     // ===================
+    // ADDRESS DERIVATION
+    // ===================
+    const _B58_ALPHA = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+    function _base58Encode(buf) {
+        let zeros = 0;
+        for (let i = 0; i < buf.length && buf[i] === 0; i++)
+            zeros++;
+        const digits = [];
+        for (let i = zeros; i < buf.length; i++) {
+            let carry = buf[i];
+            for (let j = 0; j < digits.length; j++) {
+                carry += digits[j] << 8;
+                digits[j] = carry % 58;
+                carry = Math.floor(carry / 58);
+            }
+            while (carry > 0) {
+                digits.push(carry % 58);
+                carry = Math.floor(carry / 58);
+            }
+        }
+        let out = '';
+        for (let i = 0; i < zeros; i++)
+            out += _B58_ALPHA[0];
+        for (let i = digits.length - 1; i >= 0; i--)
+            out += _B58_ALPHA[digits[i]];
+        return out;
+    }
+    /**
+     * Derive the canonical Octra address from a base64-encoded Ed25519 public key.
+     * Algorithm: SHA-256(pubkey_bytes) → base58 → prepend "oct"
+     * Source of truth: ocho-push-server/src/index.ts#deriveAddressFromPubkey
+     */
+    async function deriveOctraAddress(publicKeyBase64) {
+        if (!publicKeyBase64 || typeof publicKeyBase64 !== 'string') {
+            throw new Error('publicKeyBase64 must be a non-empty string');
+        }
+        if (typeof crypto === 'undefined' || !crypto.subtle) {
+            throw new Error('Web Crypto API is not available in this environment');
+        }
+        const binStr = atob(publicKeyBase64);
+        const bytes = new Uint8Array(binStr.length);
+        for (let i = 0; i < binStr.length; i++)
+            bytes[i] = binStr.charCodeAt(i);
+        const hashBuf = await crypto.subtle.digest('SHA-256', bytes);
+        return 'oct' + _base58Encode(new Uint8Array(hashBuf));
+    }
+    // ===================
     // FORMATTING UTILITIES
     // ===================
     /**
      * Format OCT amount for display
      */
     function formatOCT(amount, decimals = 6) {
-        if (!isValidAmount(amount)) {
+        const n = typeof amount === 'string' ? parseFloat(amount) : amount;
+        if (!isValidAmount(n)) {
             return '0';
         }
-        return amount.toLocaleString(undefined, {
+        return n.toLocaleString(undefined, {
             minimumFractionDigits: 0,
             maximumFractionDigits: decimals
         });
@@ -401,7 +587,7 @@
             networkInfo: {
                 id: 'mainnet',
                 name: 'Octra Mainnet',
-                rpcUrl: 'http://46.101.86.250:8080',
+                rpcUrl: 'https://octra.network',
                 explorerUrl: 'https://lite.octrascan.io/tx.html?hash=',
                 explorerAddressUrl: 'https://lite.octrascan.io/address.html?addr=',
                 indexerUrl: 'https://lite.octrascan.io',
@@ -474,108 +660,54 @@
      * to ensure secure wallet interactions.
      *
      * @module communication
-     * @version 2.5.0
+     * @version 2.7.0
      * @license MIT
      */
-    /**
-     * ExtensionCommunicator - Manages communication with the 0xio Wallet browser extension
-     *
-     * @class
-     * @extends EventEmitter
-     *
-     * @description
-     * Handles all communication between the SDK and wallet extension including:
-     * - Request/response message passing with origin validation
-     * - Rate limiting to prevent DoS attacks
-     * - Automatic retry logic with exponential backoff
-     * - Extension detection and availability monitoring
-     * - Cryptographically secure request ID generation
-     *
-     * @example
-     * ```typescript
-     * const communicator = new ExtensionCommunicator(true); // debug mode
-     * await communicator.initialize();
-     *
-     * const response = await communicator.sendRequest('get_balance', {});
-     * console.log(response);
-     * ```
-     */
     class ExtensionCommunicator extends EventEmitter {
-        /**
-         * Creates a new ExtensionCommunicator instance
-         *
-         * @param {boolean} debug - Enable debug logging
-         */
-        constructor(debug = false, trustedOrigins = []) {
+        constructor(debug = false, trustedOrigins = [], adapter) {
             super(debug);
-            /** Legacy request counter (deprecated, kept for fallback) */
-            this.requestId = 0;
-            /** Map of pending requests awaiting responses */
             this.pendingRequests = new Map();
-            /** Initialization state flag */
             this.isInitialized = false;
-            /** Interval handle for periodic extension detection */
             this.extensionDetectionInterval = null;
-            /** Current extension availability state */
             this.isExtensionAvailableState = false;
-            /** Message listener reference for cleanup */
-            this.messageListener = null;
-            /** Trusted parent origins for iframe communication */
             this.trustedOrigins = [];
-            /** Parent origin learned from walletReady signal */
             this._parentOrigin = null;
-            // Rate limiting configuration
-            /** Maximum number of concurrent pending requests */
+            /** Teardown fn returned by adapter.listen() */
+            this._adapterTeardown = null;
+            /** Teardown fn returned by adapter.listenForReady() */
+            this._adapterReadyTeardown = null;
+            /**
+             * Set when a trusted walletReady has been received from window.parent.
+             * The polling fallback must NOT clear this flag.
+             */
+            this._parentTrusted = false;
+            /** walletReady postMessage listener stored for cleanup */
+            this._walletReadyMessageListener = null;
+            /**
+             * In-flight interactive request lock.
+             * Methods that open approval popups are serialized — only one at a time.
+             */
+            this._interactiveInFlight = false;
             this.MAX_CONCURRENT_REQUESTS = 50;
-            /** Time window for rate limiting (milliseconds) */
             this.RATE_LIMIT_WINDOW = 1000;
-            /** Maximum requests allowed per time window */
             this.MAX_REQUESTS_PER_WINDOW = 20;
-            /** Timestamps of recent requests for rate limiting */
             this.requestTimestamps = [];
             this.logger = createLogger('ExtensionCommunicator', debug);
             this.trustedOrigins = trustedOrigins;
+            this.adapter = adapter ?? createZeroXIOAdapter(trustedOrigins);
             this.setupMessageListener();
             this.startExtensionDetection();
         }
-        /**
-         * Add trusted origins for iframe/bridge communication
-         * Call this before connecting if your dApp runs inside a trusted frame
-         */
         setTrustedOrigins(origins) {
             this.trustedOrigins = origins;
         }
-        /**
-         * Initialize communication with the wallet extension
-         *
-         * @description
-         * Performs initial setup and verification:
-         * 1. Waits for extension to become available
-         * 2. Sends ping to verify communication
-         * 3. Establishes message handlers
-         *
-         * Must be called before any other methods.
-         *
-         * @returns {Promise<boolean>} True if initialization succeeded, false otherwise
-         * @throws {ZeroXIOWalletError} If extension is not available after timeout
-         *
-         * @example
-         * ```typescript
-         * const success = await communicator.initialize();
-         * if (!success) {
-         *   console.error('Failed to initialize wallet connection');
-         * }
-         * ```
-         */
         async initialize() {
             if (this.isInitialized) {
                 return true;
             }
             try {
-                // Wait for extension detection with timeout
                 const available = await this.waitForExtensionAvailability(10000);
                 if (available) {
-                    // Verify with ping
                     await withTimeout(this.sendRequestWithRetry('ping', {}, 3, 2000), 8000, 'Extension ping timeout during initialization');
                     this.isInitialized = true;
                     this.logger.log('Extension communication initialized successfully');
@@ -590,149 +722,106 @@
                 return false;
             }
         }
-        /**
-         * Check if extension is available
-         */
         isExtensionAvailable() {
             return this.isExtensionAvailableState && this.hasExtensionContext();
         }
-        /**
-         * Send request to extension
-         */
         async sendRequest(method, params = {}, timeout = 30000) {
             const isInteractive = ExtensionCommunicator.NO_RETRY_METHODS.has(method);
             const maxRetries = isInteractive ? 0 : 1;
-            // Give users 3 minutes for interactive approvals (review + sign + FHE proof generation)
             const effectiveTimeout = isInteractive ? Math.max(timeout, 180000) : timeout;
             return this.sendRequestWithRetry(method, params, maxRetries, effectiveTimeout);
         }
-        /**
-         * Send request to extension with automatic retry logic
-         */
         async sendRequestWithRetry(method, params = {}, maxRetries = 3, timeout = 30000) {
             if (!this.hasExtensionContext()) {
-                throw new ZeroXIOWalletError(exports.ErrorCode.EXTENSION_NOT_FOUND, '0xio Wallet extension is not installed or available', {
-                    method,
-                    params,
-                    browserContext: this.getBrowserDiagnostics()
-                });
+                throw new ZeroXIOWalletError(exports.ErrorCode.EXTENSION_NOT_FOUND, '0xio Wallet extension is not installed or available', { method, browserContext: this.getBrowserDiagnostics() });
             }
             if (!this.isExtensionAvailableState) {
-                // Wait a bit for extension to become available
                 await this.waitForExtensionAvailability(5000);
                 if (!this.isExtensionAvailableState) {
-                    throw new ZeroXIOWalletError(exports.ErrorCode.EXTENSION_NOT_FOUND, 'Extension not available for communication', {
-                        method,
-                        params,
-                        extensionState: this.getExtensionDiagnostics()
-                    });
+                    throw new ZeroXIOWalletError(exports.ErrorCode.EXTENSION_NOT_FOUND, 'Extension not available for communication', { method, extensionState: this.getExtensionDiagnostics() });
                 }
             }
-            // ✅ SECURITY: Check rate limits before processing
+            // Enforce one-at-a-time for interactive popup methods
+            const isInteractive = ExtensionCommunicator.INTERACTIVE_METHODS.has(method);
+            if (isInteractive) {
+                if (this._interactiveInFlight) {
+                    throw new ZeroXIOWalletError(exports.ErrorCode.RATE_LIMIT_EXCEEDED, 'Another approval popup is already open. Please wait for it to complete.');
+                }
+                this._interactiveInFlight = true;
+            }
             this.checkRateLimit();
-            return retry(async () => {
-                const requestId = this.generateRequestId();
-                const request = {
-                    id: requestId,
-                    method,
-                    params,
-                    timestamp: Date.now()
-                };
-                this.logger.log(`Sending request (${method}):`, { id: requestId, params });
-                return new Promise((resolve, reject) => {
-                    // Set up timeout
-                    const timeoutHandle = setTimeout(() => {
-                        const pending = this.pendingRequests.get(requestId);
-                        if (pending) {
+            try {
+                return await retry(async () => {
+                    const requestId = this.generateRequestId();
+                    const request = {
+                        id: requestId,
+                        method,
+                        params,
+                        timestamp: Date.now()
+                    };
+                    this.logger.log(`Sending request (${method}):`, { id: requestId });
+                    return new Promise((resolve, reject) => {
+                        const timeoutHandle = setTimeout(() => {
+                            const pending = this.pendingRequests.get(requestId);
+                            if (pending) {
+                                this.pendingRequests.delete(requestId);
+                                reject(new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, `Request timeout after ${timeout}ms`, { method, requestId, retryCount: pending.retryCount }));
+                            }
+                        }, timeout);
+                        this.pendingRequests.set(requestId, {
+                            resolve,
+                            reject,
+                            timeout: timeoutHandle,
+                            retryCount: 0
+                        });
+                        // Wrap postMessage so a DataCloneError cleans up the pending entry
+                        try {
+                            this.postMessageToExtension(request);
+                        }
+                        catch (cloneErr) {
+                            clearTimeout(timeoutHandle);
                             this.pendingRequests.delete(requestId);
-                            reject(new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, `Request timeout after ${timeout}ms`, {
-                                method,
-                                params,
-                                requestId,
-                                retryCount: pending.retryCount,
-                                extensionState: this.getExtensionDiagnostics()
-                            }));
+                            reject(new ZeroXIOWalletError(exports.ErrorCode.UNKNOWN_ERROR, 'Request params are not serializable', { method, requestId }));
                         }
-                    }, timeout);
-                    // Store request handlers
-                    this.pendingRequests.set(requestId, {
-                        resolve,
-                        reject,
-                        timeout: timeoutHandle,
-                        retryCount: 0
                     });
-                    // Send message to extension via content script bridge
-                    this.postMessageToExtension(request);
-                });
-            }, maxRetries, 1000);
-        }
-        /**
-         * Setup message listener for responses from extension
-         */
-        setupMessageListener() {
-            if (typeof window === 'undefined') {
-                return; // Not in browser environment
-            }
-            const allowedOrigin = window.location.origin;
-            // Store allowed origins for parent frame communication
-            // Desktop (Tauri): tauri://localhost or https://tauri.localhost
-            // Mobile (Expo): about:blank or custom scheme
-            const trustedParentOrigins = new Set([
-                allowedOrigin,
-                'tauri://localhost',
-                'https://tauri.localhost',
-                'http://localhost',
-                'https://localhost',
-            ]);
-            // Allow dApps to register additional trusted origins
-            if (this.trustedOrigins) {
-                for (const origin of this.trustedOrigins) {
-                    trustedParentOrigins.add(origin);
-                }
+                }, maxRetries, 1000);
             }
-            this.messageListener = (event) => {
-                // Strict origin validation
-                const isFromSameOrigin = event.origin === allowedOrigin;
-                const isLocalhost = event.origin.startsWith('http://localhost:') || event.origin.startsWith('http://127.0.0.1:');
-                const isFromTrustedParent = event.source === window.parent
-                    && window.parent !== window
-                    && (trustedParentOrigins.has(event.origin) || isLocalhost);
-                if (!isFromSameOrigin && !isFromTrustedParent) {
-                    return;
+            finally {
+                if (isInteractive) {
+                    this._interactiveInFlight = false;
                 }
-                // Only accept from same window (extension content script) or trusted parent frame
-                if (event.source !== window && event.source !== window.parent) {
-                    return;
-                }
-                // Verify message structure
-                if (!event.data || event.data.source !== '0xio-sdk-bridge') {
-                    return;
-                }
-                // Validate response has a pending request (prevents forged responses)
-                if (event.data.response) {
-                    const response = event.data.response;
-                    if (response && response.id && this.pendingRequests.has(response.id)) {
-                        this.handleExtensionResponse(response);
+            }
+        }
+        setupMessageListener() {
+            if (typeof window === 'undefined')
+                return;
+            this._adapterTeardown = this.adapter.listen((msg) => {
+                if (msg.requestId !== undefined) {
+                    // response — map AdapterIncomingMessage → ExtensionResponse shape
+                    if (this.pendingRequests.has(msg.requestId)) {
+                        this.handleExtensionResponse({
+                            id: msg.requestId,
+                            success: msg.success ?? false,
+                            data: msg.data,
+                            error: msg.error,
+                            timestamp: Date.now(),
+                        });
                     }
                 }
-                else if (event.data.event) {
-                    this.handleExtensionEvent(event.data.event);
+                else if (msg.eventType) {
+                    this.handleExtensionEvent({ type: msg.eventType, data: msg.eventData });
                 }
-            };
-            window.addEventListener('message', this.messageListener);
-            this.logger.log('Message listener setup complete');
+            }, { trustedParentOrigins: this.trustedOrigins });
+            this.logger.log(`Message listener setup complete (adapter: ${this.adapter.name})`);
         }
-        /**
-         * Handle extension event
-         */
         handleExtensionEvent(event) {
+            if (!event?.type || !ExtensionCommunicator.VALID_EVENT_TYPES.has(event.type)) {
+                this.logger.warn(`Received unknown event type from bridge: ${event?.type}`);
+                return;
+            }
             this.logger.log('Received extension event:', event.type);
-            // Forward the event to listeners
             this.emit(event.type, event.data);
         }
-        /**
-         * Handle response from extension
-         */
         handleExtensionResponse(response) {
             this.logger.log(`Received response:`, { id: response.id, success: response.success });
             const pending = this.pendingRequests.get(response.id);
@@ -740,192 +829,131 @@
                 this.logger.warn(`Received response for unknown request ID: ${response.id}`);
                 return;
             }
-            // Clear timeout and remove from pending
             clearTimeout(pending.timeout);
             this.pendingRequests.delete(response.id);
-            // Handle response
-            if (response.success) {
+            // Require strict boolean true — "false" string or other truthy values are failures
+            if (response.success === true) {
                 pending.resolve(response.data);
             }
             else {
                 const error = response.error;
                 if (error) {
-                    const enhancedError = new ZeroXIOWalletError(error.code, error.message, {
-                        ...error.details,
-                        requestId: response.id,
-                        retryCount: pending.retryCount,
-                        timestamp: Date.now(),
-                        extensionState: this.getExtensionDiagnostics()
-                    });
+                    // Handle both object {code, message} and legacy plain-string error formats
+                    const isObj = error !== null && typeof error === 'object';
+                    const code = isObj && error.code ? error.code : exports.ErrorCode.UNKNOWN_ERROR;
+                    const message = isObj
+                        ? (error.message ?? 'Unknown error')
+                        : (typeof error === 'string' ? error : 'Unknown error');
+                    const enhancedError = new ZeroXIOWalletError(code, message, 
+                    // Redact bridge-supplied error details; only keep non-sensitive metadata
+                    { requestId: response.id, retryCount: pending.retryCount, timestamp: Date.now() });
                     pending.reject(enhancedError);
                 }
                 else {
-                    pending.reject(new ZeroXIOWalletError(exports.ErrorCode.UNKNOWN_ERROR, 'Unknown error occurred', {
-                        requestId: response.id,
-                        retryCount: pending.retryCount,
-                        extensionState: this.getExtensionDiagnostics()
-                    }));
+                    pending.reject(new ZeroXIOWalletError(exports.ErrorCode.UNKNOWN_ERROR, 'Unknown error occurred', { requestId: response.id, retryCount: pending.retryCount }));
                 }
             }
         }
-        /**
-         * Post message to extension via content script
-         */
         postMessageToExtension(request) {
-            const msg = { source: '0xio-sdk-request', request };
-            // Post to same window (extension content script picks it up)
-            window.postMessage(msg, window.location.origin);
-            // Also post to parent frame if in an iframe (desktop/mobile bridge)
-            if (window.parent !== window) {
-                // Use the parent origin we learned from the walletReady signal, or wildcard
-                // Response validation is done by request ID matching, not origin
-                const parentOrigin = this._parentOrigin || '*';
-                try {
-                    window.parent.postMessage(msg, parentOrigin);
-                }
-                catch {
-                    // Fallback to wildcard if specific origin fails
-                    try {
-                        window.parent.postMessage(msg, '*');
-                    }
-                    catch { }
+            this.adapter.postRequest(request);
+            // Parent bridge (iframe/desktop mode) — only when a trusted origin is established.
+            // Sending with '*' would leak method + params to any intercepting frame.
+            if (window.parent !== window && this._parentOrigin) {
+                if (this.adapter.postRequestToParent) {
+                    this.adapter.postRequestToParent(request, this._parentOrigin);
                 }
             }
         }
-        /**
-         * Check if we're in a context that can communicate with extension
-         */
         hasExtensionContext() {
             return typeof window !== 'undefined' &&
                 typeof window.postMessage === 'function';
         }
-        /**
-         * Check and enforce rate limits to prevent denial-of-service attacks
-         *
-         * @private
-         * @throws {ZeroXIOWalletError} RATE_LIMIT_EXCEEDED if limits are exceeded
-         *
-         * @description
-         * Implements two-tier rate limiting:
-         * 1. Concurrent requests: Maximum 50 pending requests at once
-         * 2. Request frequency: Maximum 20 requests per second
-         *
-         * Rate limiting protects both the SDK and extension from:
-         * - Accidental infinite loops in dApp code
-         * - Malicious DoS attacks
-         * - Resource exhaustion
-         *
-         * @security Critical security function - enforces resource limits
-         */
         checkRateLimit() {
             const now = Date.now();
-            // ✅ SECURITY: Check concurrent request limit
             if (this.pendingRequests.size >= this.MAX_CONCURRENT_REQUESTS) {
                 throw new ZeroXIOWalletError(exports.ErrorCode.RATE_LIMIT_EXCEEDED, `Too many concurrent requests (max: ${this.MAX_CONCURRENT_REQUESTS})`);
             }
-            // ✅ SECURITY: Check requests per time window
+            // Trim expired timestamps — cap array size to prevent unbounded growth in idle tabs
             this.requestTimestamps = this.requestTimestamps.filter(t => now - t < this.RATE_LIMIT_WINDOW);
+            if (this.requestTimestamps.length > this.MAX_REQUESTS_PER_WINDOW) {
+                this.requestTimestamps = this.requestTimestamps.slice(-this.MAX_REQUESTS_PER_WINDOW);
+            }
             if (this.requestTimestamps.length >= this.MAX_REQUESTS_PER_WINDOW) {
                 throw new ZeroXIOWalletError(exports.ErrorCode.RATE_LIMIT_EXCEEDED, `Too many requests per second (max: ${this.MAX_REQUESTS_PER_WINDOW} per ${this.RATE_LIMIT_WINDOW}ms)`);
             }
             this.requestTimestamps.push(now);
         }
-        /**
-         * Generate cryptographically secure unique request ID
-         *
-         * @private
-         * @returns {string} A unique, unpredictable request identifier
-         *
-         * @description
-         * Uses Web Crypto API for secure random ID generation:
-         * 1. Primary: crypto.randomUUID() - UUID v4 format
-         * 2. Fallback: crypto.getRandomValues() - 128-bit random hex
-         * 3. Last resort: timestamp + counter (logs warning)
-         *
-         * Security importance:
-         * - Prevents request ID prediction attacks
-         * - Mitigates replay attacks
-         * - Makes session hijacking more difficult
-         *
-         * @security Critical - IDs must be cryptographically unpredictable
-         */
         generateRequestId() {
-            // ✅ SECURITY: Use crypto.randomUUID() for secure, unpredictable IDs
             if (typeof crypto !== 'undefined' && crypto.randomUUID) {
                 return `0xio-sdk-${crypto.randomUUID()}`;
             }
-            // Fallback to crypto.getRandomValues for older browsers
             if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
                 const array = new Uint8Array(16);
                 crypto.getRandomValues(array);
                 const hex = Array.from(array, b => b.toString(16).padStart(2, '0')).join('');
                 return `0xio-sdk-${hex}`;
             }
-            // Last resort fallback (not recommended for production)
-            this.logger.warn('Crypto API not available, using less secure ID generation');
-            return `0xio-sdk-${++this.requestId}-${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+            // Crypto API unavailable — throw rather than produce a guessable ID that
+            // could allow response spoofing via a known requestId.
+            throw new ZeroXIOWalletError(exports.ErrorCode.UNKNOWN_ERROR, 'Cryptographic random number generation is not available in this environment');
         }
-        /**
-         * Start continuous extension detection
-         */
         startExtensionDetection() {
             if (typeof window === 'undefined')
                 return;
-            // Listen for extension ready event (instant detection)
-            window.addEventListener('0xioWalletReady', () => {
-                this.logger.log('Received 0xioWalletReady event');
-                this.isExtensionAvailableState = true;
-            });
-            // Also listen for legacy event names
-            window.addEventListener('wallet0xioReady', () => {
-                this.logger.log('Received wallet0xioReady event');
-                this.isExtensionAvailableState = true;
-            });
-            window.addEventListener('octraWalletReady', () => {
-                this.logger.log('Received octraWalletReady event');
-                this.isExtensionAvailableState = true;
-            });
-            // Listen for desktop/mobile bridge walletReady via postMessage (with origin validation)
-            window.addEventListener('message', (event) => {
-                if (event.data?.source === '0xio-sdk-bridge' && event.data?.event?.type === 'walletReady') {
-                    const isSameOrigin = event.origin === window.location.origin;
-                    const isLocalhost = event.origin.startsWith('http://localhost:') || event.origin.startsWith('http://127.0.0.1:');
-                    const isTauri = event.origin === 'tauri://localhost' || event.origin === 'https://tauri.localhost';
-                    const isTrusted = this.trustedOrigins.includes(event.origin) || isTauri || isLocalhost;
-                    if (isSameOrigin || isTrusted) {
-                        this.logger.log('Received walletReady via postMessage from trusted origin');
-                        this.isExtensionAvailableState = true;
-                        // Capture parent origin for cross-origin reply targeting
-                        if (event.data.parentOrigin) {
-                            this._parentOrigin = event.data.parentOrigin;
-                        }
-                        else if (event.origin && event.origin !== 'null') {
-                            this._parentOrigin = event.origin;
-                        }
+            // Adapter-provided wallet-ready events (e.g. '0xioWalletReady', 'exampleWalletReady')
+            if (this.adapter.listenForReady) {
+                this._adapterReadyTeardown = this.adapter.listenForReady(() => {
+                    this.logger.log(`Received wallet-ready event (adapter: ${this.adapter.name})`);
+                    this.isExtensionAvailableState = true;
+                });
+            }
+            // walletReady via postMessage (desktop/mobile iframe bridge) — store ref for cleanup
+            this._walletReadyMessageListener = (event) => {
+                if (event.data?.source !== '0xio-sdk-bridge' || event.data?.event?.type !== 'walletReady') {
+                    return;
+                }
+                const isSameOrigin = event.origin === window.location.origin;
+                const isLocalhost = event.origin.startsWith('http://localhost:') || event.origin.startsWith('http://127.0.0.1:');
+                const isTauri = event.origin === 'tauri://localhost' || event.origin === 'https://tauri.localhost';
+                const isTrustedOrigin = this.trustedOrigins.includes(event.origin) || isTauri || isLocalhost;
+                // In iframe mode, only trust the actual parent window
+                const inIframe = window.parent !== window;
+                if (inIframe && event.source !== window.parent) {
+                    this.logger.warn(`Ignored walletReady from non-parent source in iframe mode`);
+                    return;
+                }
+                if (isSameOrigin || isTrustedOrigin) {
+                    this.logger.log('Received walletReady via postMessage from trusted origin');
+                    this.isExtensionAvailableState = true;
+                    this._parentTrusted = true; // Mark parent-bridge readiness separately
+                    if (event.data.parentOrigin) {
+                        this._parentOrigin = event.data.parentOrigin;
                     }
-                    else {
-                        this.logger.warn(`Ignored walletReady from untrusted origin: ${event.origin}`);
+                    else if (event.origin && event.origin !== 'null') {
+                        this._parentOrigin = event.origin;
                     }
                 }
-            });
-            // If running inside a frame, do NOT auto-trust the parent.
-            // Wait for a walletReady message from a trusted origin instead.
+                else {
+                    this.logger.warn(`Ignored walletReady from untrusted origin: ${event.origin}`);
+                }
+            };
+            window.addEventListener('message', this._walletReadyMessageListener);
             if (window.parent !== window) {
                 this.logger.log('Running inside a frame — waiting for trusted walletReady signal');
             }
-            // Initial check (in case extension was already injected)
             this.checkExtensionAvailability();
-            // Set up periodic checks as fallback
             this.extensionDetectionInterval = setInterval(() => {
                 this.checkExtensionAvailability();
             }, 2000);
         }
-        /**
-         * Check if extension is currently available
-         */
         checkExtensionAvailability() {
+            // If parent-bridge readiness was established via a trusted walletReady handshake,
+            // preserve that state — the polling fallback (detectExtensionSignals) does not
+            // consider the iframe parent signal and would incorrectly flip state back
+            if (this._parentTrusted) {
+                return;
+            }
             const wasAvailable = this.isExtensionAvailableState;
-            // Basic checks for extension context
             this.isExtensionAvailableState = this.hasExtensionContext() && this.detectExtensionSignals();
             if (!wasAvailable && this.isExtensionAvailableState) {
                 this.logger.log('Extension became available');
@@ -934,25 +962,9 @@
                 this.logger.warn('Extension became unavailable');
             }
         }
-        /**
-         * Detect extension signals/indicators
-         */
         detectExtensionSignals() {
-            if (typeof window === 'undefined')
-                return false;
-            // Check for extension-injected indicators
-            const win = window;
-            // Look for extension-injected globals (matches injected.ts)
-            return !!(win.wallet0xio ||
-                win.ZeroXIOWallet ||
-                win.octraWallet ||
-                (win.chrome?.runtime?.id) ||
-                document.querySelector('meta[name="0xio-dapp"]') ||
-                document.querySelector('[data-0xio-sdk-bridge]'));
+            return this.adapter.detect();
         }
-        /**
-         * Wait for extension to become available
-         */
         async waitForExtensionAvailability(timeoutMs) {
             if (this.isExtensionAvailableState) {
                 return true;
@@ -960,14 +972,11 @@
             return new Promise((resolve) => {
                 let resolved = false;
                 const startTime = Date.now();
-                // Cleanup function
+                let adapterReadyTeardown = null;
                 const cleanup = () => {
                     clearInterval(checkInterval);
-                    window.removeEventListener('0xioWalletReady', onReady);
-                    window.removeEventListener('wallet0xioReady', onReady);
-                    window.removeEventListener('octraWalletReady', onReady);
+                    adapterReadyTeardown?.();
                 };
-                // Event handler for instant resolution
                 const onReady = () => {
                     if (resolved)
                         return;
@@ -976,11 +985,10 @@
                     cleanup();
                     resolve(true);
                 };
-                // Listen for extension ready events
-                window.addEventListener('0xioWalletReady', onReady);
-                window.addEventListener('wallet0xioReady', onReady);
-                window.addEventListener('octraWalletReady', onReady);
-                // Polling fallback with shorter interval
+                // Use adapter's listenForReady for fast resolution; polling is the fallback
+                if (this.adapter.listenForReady) {
+                    adapterReadyTeardown = this.adapter.listenForReady(onReady);
+                }
                 const checkInterval = setInterval(() => {
                     if (resolved)
                         return;
@@ -998,9 +1006,6 @@
                 }, 100);
             });
         }
-        /**
-         * Get browser diagnostics for error reporting
-         */
         getBrowserDiagnostics() {
             if (typeof window === 'undefined') {
                 return { environment: 'non-browser' };
@@ -1012,29 +1017,21 @@
                 hasChromeRuntime: !!(win.chrome?.runtime),
                 hasPostMessage: typeof window.postMessage === 'function',
                 origin: window.location?.origin,
-                extensionDetection: {
-                    hasWallet0xio: !!win.wallet0xio,
-                    hasZeroXIOWallet: !!win.ZeroXIOWallet,
-                    hasOctraWallet: !!win.octraWallet,
-                    hasChromeRuntimeId: !!(win.chrome?.runtime?.id),
-                    hasSdkBridge: !!document.querySelector('[data-0xio-sdk-bridge]')
-                }
             };
         }
-        /**
-         * Get extension state diagnostics
-         */
         getExtensionDiagnostics() {
             return {
                 initialized: this.isInitialized,
                 available: this.isExtensionAvailableState,
+                parentTrusted: this._parentTrusted,
                 pendingRequests: this.pendingRequests.size,
                 hasExtensionContext: this.hasExtensionContext(),
-                browserDiagnostics: this.getBrowserDiagnostics()
             };
         }
         /**
-         * Cleanup pending requests
+         * Clean up SDK resources.
+         * After cleanup() the instance is terminal — do not call initialize() again.
+         * Construct a new instance instead.
          */
         cleanup() {
             if (this.extensionDetectionInterval) {
@@ -1048,18 +1045,22 @@
             this.pendingRequests.clear();
             this.isInitialized = false;
             this.isExtensionAvailableState = false;
-            // Remove message listener to prevent accumulation
-            if (this.messageListener) {
-                window.removeEventListener('message', this.messageListener);
-                this.messageListener = null;
+            this._parentTrusted = false;
+            this._parentOrigin = null;
+            this._interactiveInFlight = false;
+            // Tear down adapter listeners (response/event + wallet-ready)
+            this._adapterTeardown?.();
+            this._adapterTeardown = null;
+            this._adapterReadyTeardown?.();
+            this._adapterReadyTeardown = null;
+            // Remove walletReady postMessage listener (parent iframe bridge)
+            if (typeof window !== 'undefined' && this._walletReadyMessageListener) {
+                window.removeEventListener('message', this._walletReadyMessageListener);
+                this._walletReadyMessageListener = null;
             }
-            // Call parent cleanup
             this.removeAllListeners();
             this.logger.log('Communication cleanup complete');
         }
-        /**
-         * Get debug information
-         */
         getDebugInfo() {
             return {
                 initialized: this.isInitialized,
@@ -1070,23 +1071,30 @@
             };
         }
     }
-    // Methods that trigger user-facing popups — NEVER retry these
+    // Methods that trigger user-facing popups — NEVER retry these.
     // Retrying sends a second request while the first popup is still open,
-    // causing double popups where the second tx fails (stale nonce/state)
+    // causing double popups where the second tx fails (stale nonce/state).
     ExtensionCommunicator.NO_RETRY_METHODS = new Set([
         'connect', 'send_transaction', 'call_contract', 'signMessage',
         'send_private_transfer', 'claim_private_transfer',
         'encrypt_balance', 'decrypt_balance',
     ]);
+    ExtensionCommunicator.INTERACTIVE_METHODS = ExtensionCommunicator.NO_RETRY_METHODS;
+    // only forward known event types
+    ExtensionCommunicator.VALID_EVENT_TYPES = new Set([
+        'connect', 'disconnect', 'accountChanged', 'balanceChanged',
+        'networkChanged', 'transactionConfirmed', 'error',
+        'extensionLocked', 'extensionUnlocked'
+    ]);
 
     /**
      * Network configuration for 0xio SDK
      */
-    const NETWORKS = {
+    const _NETWORKS = {
         'mainnet': {
             id: 'mainnet',
             name: 'Octra Mainnet',
-            rpcUrl: 'http://46.101.86.250:8080',
+            rpcUrl: 'https://octra.network',
             explorerUrl: 'https://lite.octrascan.io/tx.html?hash=',
             explorerAddressUrl: 'https://lite.octrascan.io/address.html?addr=',
             indexerUrl: 'https://lite.octrascan.io',
@@ -1117,49 +1125,106 @@
             isTestnet: false
         }
     };
+    /**
+     * Immutable public copy of the built-in network table.
+     * Modifications to returned objects do not affect SDK-internal state.
+     */
+    const NETWORKS = Object.freeze(Object.fromEntries(Object.entries(_NETWORKS).map(([k, v]) => [k, Object.freeze({ ...v })])));
     const DEFAULT_NETWORK_ID = 'mainnet';
     /**
-     * Get network configuration by ID
+     * Get network configuration by ID.
+     * Returns a frozen copy — callers cannot mutate SDK-internal state.
      */
     function getNetworkConfig(networkId = DEFAULT_NETWORK_ID) {
-        const network = NETWORKS[networkId];
-        if (!network) {
+        if (!Object.prototype.hasOwnProperty.call(_NETWORKS, networkId)) {
             throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, `Unknown network ID: ${networkId}`);
         }
-        return network;
+        return Object.freeze({ ..._NETWORKS[networkId] });
     }
     /**
-     * Get all available networks
+     * Get all available networks.
+     * Returns frozen copies — callers cannot mutate SDK-internal state.
      */
     function getAllNetworks() {
-        return Object.values(NETWORKS);
+        return Object.values(_NETWORKS).map(n => Object.freeze({ ...n }));
     }
     /**
-     * Check if network ID is valid
+     * Check if network ID is valid (own property check, prevents prototype pollution).
      */
     function isValidNetworkId(networkId) {
-        return networkId in NETWORKS;
+        return typeof networkId === 'string' && Object.prototype.hasOwnProperty.call(_NETWORKS, networkId);
+    }
+    /**
+     * Validate a NetworkInfo shape from an untrusted source (bridge response).
+     * Returns a frozen copy if valid, null otherwise.
+     */
+    function validateNetworkInfo(raw) {
+        if (!raw || typeof raw !== 'object')
+            return null;
+        if (typeof raw.id !== 'string' || !raw.id)
+            return null;
+        if (typeof raw.name !== 'string')
+            return null;
+        if (typeof raw.rpcUrl !== 'string' || (!raw.rpcUrl && raw.id !== 'custom'))
+            return null;
+        if (typeof raw.supportsPrivacy !== 'boolean')
+            return null;
+        return Object.freeze({
+            id: raw.id,
+            name: raw.name,
+            rpcUrl: raw.rpcUrl,
+            explorerUrl: typeof raw.explorerUrl === 'string' ? raw.explorerUrl : undefined,
+            explorerAddressUrl: typeof raw.explorerAddressUrl === 'string' ? raw.explorerAddressUrl : undefined,
+            indexerUrl: typeof raw.indexerUrl === 'string' ? raw.indexerUrl : undefined,
+            supportsPrivacy: raw.supportsPrivacy,
+            color: typeof raw.color === 'string' ? raw.color : '#64748b',
+            isTestnet: typeof raw.isTestnet === 'boolean' ? raw.isTestnet : false,
+        });
     }
 
     /**
      * SDK Configuration
      */
     /**
-     * Default balance structure
+     * Default balance structure.
+     * Accepts a numeric total or undefined — never pass a Balance object here.
      */
     function createDefaultBalance(total = 0) {
+        const safeTotal = typeof total === 'number' && Number.isFinite(total) && total >= 0 ? total : 0;
         return {
-            total,
-            public: total,
+            total: safeTotal,
+            public: safeTotal,
             private: 0,
             currency: 'OCT'
         };
     }
+    /**
+     * Validate and normalise a Balance from an untrusted source (bridge response).
+     * Returns null if the payload cannot be coerced into a valid Balance.
+     */
+    function validateBalance(raw) {
+        if (raw === null || raw === undefined)
+            return null;
+        // If it's already a Balance-shaped object, extract numeric fields
+        // Use Number() not parseFloat() — parseFloat('10abc') silently returns 10
+        const pub = typeof raw === 'object' ? Number(raw.public ?? raw.total ?? 0) : Number(raw);
+        const priv = typeof raw === 'object' ? Number(raw.private ?? 0) : 0;
+        if (!Number.isFinite(pub) || pub < 0)
+            return null;
+        if (!Number.isFinite(priv) || priv < 0)
+            return null;
+        return {
+            public: pub,
+            private: priv,
+            total: pub + priv,
+            currency: 'OCT'
+        };
+    }
     /**
      * SDK Configuration constants
      */
     const SDK_CONFIG = {
-        version: '2.5.0',
+        version: '2.7.0',
         defaultNetworkId: DEFAULT_NETWORK_ID,
         communicationTimeout: 30000, // 30 seconds
         retryAttempts: 3,
@@ -1181,6 +1246,9 @@
             super(config.debug);
             this.connectionInfo = { isConnected: false };
             this.isInitialized = false;
+            this._initPromise = null;
+            // session version — stale write detection
+            this._sessionVersion = 0;
             this.config = {
                 ...config,
                 appVersion: config.appVersion || '1.0.0',
@@ -1188,7 +1256,7 @@
                 debug: config.debug || false
             };
             this.logger = createLogger('ZeroXIOWallet', this.config.debug || false);
-            this.communicator = new ExtensionCommunicator(this.config.debug);
+            this.communicator = new ExtensionCommunicator(this.config.debug, [], this.config.adapter);
             this.logger.log('Wallet instance created with config:', this.config);
         }
         // ===================
@@ -1202,35 +1270,45 @@
             if (this.isInitialized) {
                 return true;
             }
-            try {
-                // Initialize extension communication
-                const communicationReady = await this.communicator.initialize();
-                if (!communicationReady) {
-                    throw new ZeroXIOWalletError(exports.ErrorCode.EXTENSION_NOT_FOUND, 'Failed to establish communication with 0xio Wallet extension');
-                }
-                // Register this DApp with the extension
-                await this.communicator.sendRequest('register_dapp', {
-                    appName: this.config.appName,
-                    appDescription: this.config.appDescription,
-                    appVersion: this.config.appVersion,
-                    appUrl: typeof window !== 'undefined' ? window.location.origin : undefined,
-                    appIcon: this.config.appIcon,
-                    requiredPermissions: this.config.requiredPermissions,
-                    networkId: this.config.networkId
-                });
-                // Setup event forwarding from extension
-                this.setupExtensionEventListeners();
-                this.isInitialized = true;
-                this.logger.log('SDK initialized successfully');
-                return true;
+            // single-flight init
+            if (this._initPromise) {
+                return this._initPromise;
             }
-            catch (error) {
-                this.logger.error('Failed to initialize:', error);
-                if (error instanceof ZeroXIOWalletError) {
-                    throw error;
+            this._initPromise = (async () => {
+                try {
+                    // Initialize extension communication
+                    const communicationReady = await this.communicator.initialize();
+                    if (!communicationReady) {
+                        throw new ZeroXIOWalletError(exports.ErrorCode.EXTENSION_NOT_FOUND, 'Failed to establish communication with 0xio Wallet extension');
+                    }
+                    // Register this DApp with the extension
+                    await this.communicator.sendRequest('register_dapp', {
+                        appName: this.config.appName,
+                        appDescription: this.config.appDescription,
+                        appVersion: this.config.appVersion,
+                        appUrl: typeof window !== 'undefined' ? window.location.origin : undefined,
+                        appIcon: this.config.appIcon,
+                        requiredPermissions: this.config.requiredPermissions,
+                        networkId: this.config.networkId
+                    });
+                    // Setup event forwarding from extension
+                    this.setupExtensionEventListeners();
+                    this.isInitialized = true;
+                    this.logger.log('SDK initialized successfully');
+                    return true;
                 }
-                throw new ZeroXIOWalletError(exports.ErrorCode.UNKNOWN_ERROR, 'Failed to initialize SDK', error);
-            }
+                catch (error) {
+                    this.logger.error('Failed to initialize:', error);
+                    if (error instanceof ZeroXIOWalletError) {
+                        throw error;
+                    }
+                    throw new ZeroXIOWalletError(exports.ErrorCode.UNKNOWN_ERROR, 'Failed to initialize SDK', error);
+                }
+                finally {
+                    this._initPromise = null;
+                }
+            })();
+            return this._initPromise;
         }
         /**
          * Check if SDK is initialized
@@ -1248,31 +1326,53 @@
             this.ensureInitialized();
             try {
                 this.logger.log('Attempting to connect with options:', options);
+                // filter to declared perms only
+                const declaredPermissions = this.config.requiredPermissions || [];
+                const requestPermissions = options.requestPermissions
+                    ? options.requestPermissions.filter(p => declaredPermissions.includes(p))
+                    : declaredPermissions;
                 const result = await this.communicator.sendRequest('connect', {
-                    requestPermissions: options.requestPermissions || this.config.requiredPermissions,
+                    requestPermissions,
                     networkId: options.networkId || this.config.networkId
                 });
-                // Use networkInfo from extension response, fallback to config-based
-                const networkInfo = result.networkInfo || getNetworkConfig(result.networkId || this.config.networkId);
-                // Update connection info
+                // verify pubkey→addr binding
+                if (result.publicKey && result.address) {
+                    try {
+                        const derived = await deriveOctraAddress(result.publicKey);
+                        if (derived !== result.address) {
+                            throw new ZeroXIOWalletError(exports.ErrorCode.UNKNOWN_ERROR, 'Address-key binding verification failed — the reported public key does not derive to the reported address');
+                        }
+                    }
+                    catch (e) {
+                        if (e instanceof ZeroXIOWalletError)
+                            throw e;
+                        this.logger.warn('Address derivation check skipped (crypto unavailable):', e);
+                    }
+                }
+                // Use networkInfo from extension response — validate before caching
+                const networkInfo = validateNetworkInfo(result.networkInfo)
+                    ?? getNetworkConfig(result.networkId || this.config.networkId);
+                const permissions = result.permissions || [];
+                // Update connection info — including permissions
                 this.connectionInfo = {
                     isConnected: true,
                     address: result.address,
                     publicKey: result.publicKey,
                     balance: result.balance,
                     networkInfo,
-                    connectedAt: Date.now()
+                    connectedAt: Date.now(),
+                    permissions
                 };
                 const connectEvent = {
                     address: result.address,
                     publicKey: result.publicKey,
                     balance: result.balance,
                     networkInfo,
-                    permissions: result.permissions || []
+                    permissions
                 };
                 // Emit connect event
                 this.emit('connect', connectEvent);
-                this.logger.log('Connected successfully:', connectEvent);
+                this.logger.log('Connected successfully:', { address: connectEvent.address, network: networkInfo.id });
                 return connectEvent;
             }
             catch (error) {
@@ -1290,6 +1390,7 @@
             this.ensureInitialized();
             try {
                 await this.communicator.sendRequest('disconnect');
+                ++this._sessionVersion;
                 this.connectionInfo = { isConnected: false };
                 const disconnectEvent = {
                     reason: 'user_action'
@@ -1320,30 +1421,55 @@
         async getConnectionStatus() {
             this.ensureInitialized();
             try {
+                const sv = this._sessionVersion;
                 const result = await this.communicator.sendRequest('getConnectionStatus');
+                // skip if session changed mid-flight
+                if (this._sessionVersion !== sv)
+                    return { ...this.connectionInfo };
                 if (result.isConnected && result.address) {
-                    // Update internal state if we discover an existing connection
-                    const balanceInfo = createDefaultBalance(result.balance);
-                    // Use network from extension response (actual active network), fallback to config
-                    const activeNetworkId = result.networkId || this.config.networkId;
-                    const networkInfo = getNetworkConfig(activeNetworkId);
+                    // verify pubkey→addr binding
+                    if (result.publicKey) {
+                        try {
+                            const derived = await deriveOctraAddress(result.publicKey);
+                            if (derived !== result.address) {
+                                this.logger.warn('Address-key binding mismatch on session restore — ignoring stale session');
+                                this.connectionInfo = { isConnected: false };
+                                return { ...this.connectionInfo };
+                            }
+                        }
+                        catch (e) {
+                            this.logger.warn('Address derivation check skipped (crypto unavailable):', e);
+                        }
+                    }
+                    // validate untrusted balance/networkInfo before caching
+                    const balanceInfo = validateBalance(result.balance) ?? createDefaultBalance();
+                    const networkInfo = validateNetworkInfo(result.networkInfo)
+                        ?? getNetworkConfig(result.networkId || this.config.networkId);
+                    const wasConnected = this.connectionInfo.isConnected;
+                    const permissions = result.permissions || [];
+                    // preserve existing connectedAt
+                    const connectedAt = this.connectionInfo.connectedAt || result.connectedAt || Date.now();
                     this.connectionInfo = {
                         isConnected: true,
                         address: result.address,
                         publicKey: result.publicKey,
                         balance: balanceInfo,
                         networkInfo,
-                        connectedAt: result.connectedAt || Date.now()
-                    };
-                    this.logger.log('Discovered existing connection:', this.connectionInfo);
-                    // Emit connect event to notify the wrapper
-                    const connectEvent = {
-                        address: result.address,
-                        balance: balanceInfo,
-                        networkInfo,
-                        permissions: result.permissions || []
+                        connectedAt,
+                        permissions
                     };
-                    this.emit('connect', connectEvent);
+                    this.logger.log('Discovered existing connection:', { address: result.address, network: networkInfo.id });
+                    // only emit on disconnected→connected transition
+                    if (!wasConnected) {
+                        const connectEvent = {
+                            address: result.address,
+                            publicKey: result.publicKey,
+                            balance: balanceInfo,
+                            networkInfo,
+                            permissions
+                        };
+                        this.emit('connect', connectEvent);
+                    }
                 }
                 else {
                     // No existing connection
@@ -1363,10 +1489,14 @@
          * The extension broadcasts 'networkChanged' event to all connected dApps.
          */
         async switchNetwork(networkId) {
-            this.ensureInitialized();
+            this.ensureConnected();
             try {
+                const sv = this._sessionVersion;
                 const result = await this.communicator.sendRequest('switch_network', { networkId });
                 this.logger.log(`Network switch result:`, result);
+                // skip if session changed mid-flight
+                if (this._sessionVersion !== sv)
+                    return { network: result.network || networkId, switched: result.switched ?? false };
                 if (result.switched) {
                     // Update internal state
                     const networkInfo = getNetworkConfig(networkId);
@@ -1409,22 +1539,28 @@
                 // Fetch balance from extension (bypasses CORS, has access to private balance)
                 let publicBalance = 0;
                 let privateBalance = 0;
+                const sv = this._sessionVersion;
                 const extResult = await this.communicator.sendRequest('getBalance', { forceRefresh });
                 publicBalance = parseFloat(extResult.balance || '0');
                 privateBalance = parseFloat(extResult.privateBalance || '0');
-                this.logger.log('Balance fetched from extension:', { public: publicBalance, private: privateBalance });
+                this.logger.log('Balance fetched from extension:', { public: publicBalance });
                 const result = {
                     public: publicBalance,
                     private: privateBalance,
                     total: publicBalance + privateBalance,
                     currency: 'OCT'
                 };
+                // skip if session changed mid-flight
+                if (this._sessionVersion !== sv)
+                    return result;
                 // Update cached balance
                 if (this.connectionInfo.balance) {
                     const previousBalance = this.connectionInfo.balance;
                     this.connectionInfo.balance = result;
-                    // Emit balance changed event if different
-                    if (previousBalance.total !== result.total) {
+                    // emit on total or pub/priv split change
+                    if (previousBalance.total !== result.total ||
+                        previousBalance.public !== result.public ||
+                        previousBalance.private !== result.private) {
                         const balanceChangedEvent = {
                             address: this.connectionInfo.address,
                             previousBalance,
@@ -1439,6 +1575,8 @@
                 return result;
             }
             catch (error) {
+                if (error instanceof ZeroXIOWalletError)
+                    throw error;
                 throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Failed to get balance', error);
             }
         }
@@ -1448,26 +1586,37 @@
         async getNetworkInfo() {
             this.ensureInitialized();
             try {
+                const sv = this._sessionVersion;
                 const result = await this.communicator.sendRequest('get_network_info');
+                // validate network info before caching
+                const networkInfo = validateNetworkInfo(result);
+                if (!networkInfo) {
+                    throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Extension returned invalid network info');
+                }
+                // skip if session changed mid-flight
+                if (this._sessionVersion !== sv)
+                    return networkInfo;
                 // Update cached network info
                 if (this.connectionInfo.networkInfo) {
                     const previousNetwork = this.connectionInfo.networkInfo;
-                    this.connectionInfo.networkInfo = result;
+                    this.connectionInfo.networkInfo = networkInfo;
                     // Emit network changed event if different
-                    if (previousNetwork.id !== result.id) {
+                    if (previousNetwork.id !== networkInfo.id) {
                         const networkChangedEvent = {
                             previousNetwork,
-                            newNetwork: result
+                            newNetwork: networkInfo
                         };
                         this.emit('networkChanged', networkChangedEvent);
                     }
                 }
                 else {
-                    this.connectionInfo.networkInfo = result;
+                    this.connectionInfo.networkInfo = networkInfo;
                 }
-                return result;
+                return networkInfo;
             }
             catch (error) {
+                if (error instanceof ZeroXIOWalletError)
+                    throw error;
                 throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Failed to get network info', error);
             }
         }
@@ -1479,8 +1628,20 @@
          */
         async sendTransaction(txData) {
             this.ensureConnected();
+            // validate inputs
+            if (!isValidAddress(txData.to)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.INVALID_ADDRESS, 'Invalid recipient address');
+            }
+            if (!isValidAmount(txData.amount)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Invalid transaction amount');
+            }
+            // bound memo
+            if (txData.message && txData.message.length > 1000) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Transaction message too long (max 1,000 characters)');
+            }
             try {
-                this.logger.log('Sending transaction:', txData);
+                // log non-sensitive only
+                this.logger.log('Sending transaction:', { to: txData.to });
                 const result = await this.communicator.sendRequest('send_transaction', txData);
                 this.logger.log('Transaction result:', result);
                 // Refresh balance after successful transaction
@@ -1507,8 +1668,30 @@
          */
         async callContract(callData) {
             this.ensureConnected();
+            // validate inputs
+            if (!isValidAddress(callData.contract)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.INVALID_ADDRESS, 'Invalid contract address');
+            }
+            if (!callData.method || typeof callData.method !== 'string') {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Contract method is required');
+            }
+            // bound method + params size
+            if (callData.method.length > 200) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Contract method name too long (max 200 characters)');
+            }
+            try {
+                if (JSON.stringify(callData.params).length > 65536) {
+                    throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Contract params too large (max 64 KB)');
+                }
+            }
+            catch (e) {
+                if (e instanceof ZeroXIOWalletError)
+                    throw e;
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Contract params are not serialisable');
+            }
             try {
-                this.logger.log('Calling contract:', callData);
+                // log non-sensitive only
+                this.logger.log('Calling contract:', { contract: callData.contract, method: callData.method });
                 const result = await this.communicator.sendRequest('call_contract', {
                     contract: callData.contract,
                     method: callData.method,
@@ -1533,13 +1716,36 @@
          */
         async contractCallView(viewData) {
             this.ensureInitialized();
+            // validate inputs
+            if (!isValidAddress(viewData.contract)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.INVALID_ADDRESS, 'Invalid contract address');
+            }
+            if (!viewData.method || typeof viewData.method !== 'string') {
+                throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Contract method is required');
+            }
+            // bound method + params size
+            if (viewData.method.length > 200) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Contract method name too long (max 200 characters)');
+            }
+            try {
+                if (JSON.stringify(viewData.params).length > 65536) {
+                    throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Contract params too large (max 64 KB)');
+                }
+            }
+            catch (e) {
+                if (e instanceof ZeroXIOWalletError)
+                    throw e;
+                throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Contract params are not serialisable');
+            }
             try {
-                this.logger.log('Contract view call:', viewData);
+                // log non-sensitive only
+                this.logger.log('Contract view call:', { contract: viewData.contract, method: viewData.method });
                 const result = await this.communicator.sendRequest('contract_call_view', {
                     contract: viewData.contract,
                     method: viewData.method,
                     params: viewData.params,
-                    caller: viewData.caller || this.getAddress() || '',
+                    // only include caller if explicit
+                    ...(viewData.caller != null ? { caller: viewData.caller } : {}),
                 });
                 this.logger.log('Contract view result:', result);
                 return result;
@@ -1557,6 +1763,16 @@
          */
         async getContractStorage(contract, key) {
             this.ensureInitialized();
+            // validate inputs
+            if (!isValidAddress(contract)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.INVALID_ADDRESS, 'Invalid contract address');
+            }
+            if (!key || typeof key !== 'string') {
+                throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Storage key is required');
+            }
+            if (key.length > 200) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.NETWORK_ERROR, 'Storage key too long (max 200 characters)');
+            }
             try {
                 this.logger.log('Getting contract storage:', { contract, key });
                 const result = await this.communicator.sendRequest('get_contract_storage', {
@@ -1610,13 +1826,17 @@
          */
         async encryptBalance(amount) {
             this.ensureConnected();
+            // validate amount
+            if (!isValidAmount(amount)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Invalid amount');
+            }
             try {
                 const result = await this.communicator.sendRequest('encrypt_balance', { amount });
                 // Refresh balance after encryption
                 setTimeout(() => {
                     this.getBalance(true).catch(() => { });
                 }, 1000);
-                return result.success;
+                return result;
             }
             catch (error) {
                 throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Failed to encrypt balance', error);
@@ -1627,23 +1847,43 @@
          */
         async decryptBalance(amount) {
             this.ensureConnected();
+            // validate amount
+            if (!isValidAmount(amount)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Invalid amount');
+            }
             try {
                 const result = await this.communicator.sendRequest('decrypt_balance', { amount });
                 // Refresh balance after decryption
                 setTimeout(() => {
                     this.getBalance(true).catch(() => { });
                 }, 1000);
-                return result.success;
+                return result;
             }
             catch (error) {
                 throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Failed to decrypt balance', error);
             }
         }
         /**
-         * Send private transfer
+         * Send a private (encrypted) transfer to another address.
+         * The extension builds the PVAC ciphertext subtraction + range proof + zero proof,
+         * then submits the encrypted transaction to the network. The recipient's encrypted
+         * balance is updated by the node using re-encryption under their public key.
+         * Requires 'private_transfers' permission.
+         * @since 2.6.0
          */
         async sendPrivateTransfer(transferData) {
             this.ensureConnected();
+            // validate inputs
+            if (!isValidAddress(transferData.to)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.INVALID_ADDRESS, 'Invalid recipient address');
+            }
+            if (!isValidAmount(transferData.amount)) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Invalid transfer amount');
+            }
+            // bound msg size
+            if (transferData.message && transferData.message.length > 1000) {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Transfer message too long (max 1,000 characters)');
+            }
             try {
                 const result = await this.communicator.sendRequest('send_private_transfer', transferData);
                 // Refresh balance after transfer
@@ -1659,7 +1899,9 @@
             }
         }
         /**
-         * Get pending private transfers
+         * Get pending private transfers that can be claimed by this wallet.
+         * Returns transfers where the connected address is the recipient.
+         * @since 2.6.0
          */
         async getPendingPrivateTransfers() {
             this.ensureConnected();
@@ -1672,10 +1914,15 @@
             }
         }
         /**
-         * Claim private transfer
+         * Claim a pending private transfer, adding it to the wallet's encrypted balance.
+         * @since 2.6.0
          */
         async claimPrivateTransfer(transferId) {
             this.ensureConnected();
+            // validate transfer ID
+            if (!transferId || typeof transferId !== 'string') {
+                throw new ZeroXIOWalletError(exports.ErrorCode.TRANSACTION_FAILED, 'Invalid transfer ID');
+            }
             try {
                 const result = await this.communicator.sendRequest('claim_private_transfer', {
                     transferId
@@ -1733,6 +1980,30 @@
             }
         }
         // ===================
+        // AUTHENTICATION HELPERS
+        // ===================
+        /**
+         * Sign a domain-separated authentication message.
+         * Unlike `signMessage()`, this prepends a standard header that binds the signature
+         * to the calling service and a one-time nonce, preventing cross-service replay attacks.
+         *
+         * @param service - Identifies the relying service (e.g. 'MyDApp' or 'api.mydapp.com')
+         * @param nonce   - Unique one-time value — use a server-generated UUID or challenge
+         * @returns Promise resolving to the base64-encoded Ed25519 signature
+         */
+        async signAuthMessage(service, nonce) {
+            this.ensureConnected();
+            if (!service || typeof service !== 'string') {
+                throw new ZeroXIOWalletError(exports.ErrorCode.SIGNATURE_FAILED, 'Service name is required');
+            }
+            if (!nonce || typeof nonce !== 'string') {
+                throw new ZeroXIOWalletError(exports.ErrorCode.SIGNATURE_FAILED, 'Nonce is required');
+            }
+            const origin = typeof window !== 'undefined' ? window.location.origin : 'unknown';
+            const domainSeparated = `0xio auth\nService: ${service}\nNonce: ${nonce}\nOrigin: ${origin}`;
+            return this.signMessage(domainSeparated);
+        }
+        // ===================
         // PRIVATE METHODS
         // ===================
         ensureInitialized() {
@@ -1772,28 +2043,47 @@
          * Handle account changed event from extension
          */
         handleAccountChanged(data) {
+            ++this._sessionVersion;
             const previousAddress = this.connectionInfo.address;
             this.connectionInfo.address = data.address;
+            // clear stale pubkey on acct change
+            this.connectionInfo.publicKey = data.publicKey;
             if (data.balance) {
-                this.connectionInfo.balance = data.balance;
+                // validate balance before caching
+                const validated = validateBalance(data.balance);
+                if (validated) {
+                    this.connectionInfo.balance = validated;
+                }
+                else {
+                    this.connectionInfo.balance = undefined; // clear stale balance
+                }
             }
             const accountChangedEvent = {
                 previousAddress,
                 newAddress: data.address,
+                publicKey: data.publicKey,
                 balance: data.balance ?? this.connectionInfo.balance
             };
             this.emit('accountChanged', accountChangedEvent);
-            this.logger.log('Account changed:', accountChangedEvent);
+            this.logger.log('Account changed:', { newAddress: accountChangedEvent.newAddress });
         }
         /**
          * Handle network changed event from extension
          */
         handleNetworkChanged(data) {
             const previousNetwork = this.connectionInfo.networkInfo;
-            this.connectionInfo.networkInfo = data.networkInfo;
+            // validate networkInfo — drop invalid
+            const networkInfo = validateNetworkInfo(data.networkInfo);
+            if (!networkInfo) {
+                this.logger.warn('Received invalid networkInfo in networkChanged event, ignoring');
+                return;
+            }
+            this.connectionInfo.networkInfo = networkInfo;
+            // invalidate balance on network change
+            this.connectionInfo.balance = undefined;
             const networkChangedEvent = {
                 previousNetwork,
-                newNetwork: data.networkInfo
+                newNetwork: networkInfo
             };
             this.emit('networkChanged', networkChangedEvent);
             this.logger.log('Network changed:', networkChangedEvent);
@@ -1802,21 +2092,30 @@
          * Handle balance changed event from extension
          */
         handleBalanceChanged(data) {
+            // validate balance before caching
+            const balance = validateBalance(data.balance);
+            if (!balance) {
+                this.logger.warn('Received invalid balance in balanceChanged event, ignoring');
+                return;
+            }
             const previousBalance = this.connectionInfo.balance;
-            this.connectionInfo.balance = data.balance;
+            this.connectionInfo.balance = balance;
             const balanceChangedEvent = {
                 address: this.connectionInfo.address,
                 previousBalance,
-                newBalance: data.balance
+                newBalance: balance
             };
             this.emit('balanceChanged', balanceChangedEvent);
-            this.logger.log('Balance changed:', balanceChangedEvent);
+            this.logger.log('Balance changed:', { public: balance.public });
         }
         /**
          * Handle extension locked event
          */
         handleExtensionLocked() {
+            ++this._sessionVersion;
             this.connectionInfo = { isConnected: false };
+            // emit extensionLocked then disconnect
+            this.emit('extensionLocked', {});
             const disconnectEvent = {
                 reason: 'extension_locked'
             };
@@ -1827,6 +2126,8 @@
          * Handle extension unlocked event
          */
         handleExtensionUnlocked() {
+            // emit extensionUnlocked
+            this.emit('extensionUnlocked', {});
             // Attempt to restore connection
             this.getConnectionStatus().catch(() => {
                 this.logger.warn('Could not restore connection after unlock');
@@ -1859,6 +2160,8 @@
             this.removeAllListeners();
             this.connectionInfo = { isConnected: false };
             this.isInitialized = false;
+            this._initPromise = null;
+            ++this._sessionVersion;
             this.logger.log('SDK cleanup complete');
         }
     }
@@ -1868,6 +2171,200 @@
         ZeroXIOWallet: ZeroXIOWallet
     });
 
+    /**
+     * RFC-O-1 OctraProvider transport adapter.
+     *
+     * Targets any wallet that exposes `window.octra` per the RFC-O-1 specification:
+     *   window.octra.isOctra === true
+     *   window.octra.request({ method, params }) → Promise<unknown>
+     *   window.octra.on(event, listener) / removeListener(event, listener)
+     *
+     * This adapter translates the SDK's internal method names into RFC-O-1 method
+     * names and maps events back to the SDK event vocabulary.
+     *
+     * Non-standard SDK methods (ping, register_dapp, getTransactionHistory, etc.)
+     * are passed through as-is; the wallet's request() handles or rejects them.
+     */
+    /** SDK method → RFC-O-1 method name */
+    const SDK_TO_RFC = {
+        get_network_info: 'octra_networkInfo',
+        switch_network: 'octra_switchNetwork',
+        signMessage: 'octra_signMessage',
+        send_transaction: 'octra_sendTransaction',
+        call_contract: 'octra_callContract',
+        contract_call_view: 'octra_callContract',
+        get_private_balance_info: 'octra_getEncryptedBalance',
+        encrypt_balance: 'octra_encryptBalance',
+        decrypt_balance: 'octra_decryptBalance',
+        send_private_transfer: 'octra_sendPrivateTransfer',
+        claim_private_transfer: 'octra_claimStealth',
+    };
+    /** RFC-O-1 error code → SDK ErrorCode string */
+    const RFC_TO_SDK_ERROR = {
+        4001: 'USER_REJECTED',
+        4100: 'PERMISSION_DENIED',
+        4200: 'NETWORK_ERROR',
+        4900: 'CONNECTION_REFUSED',
+        4901: 'NETWORK_ERROR',
+    };
+    function getProvider() {
+        return typeof window !== 'undefined' ? window.octra : null;
+    }
+    function mapError(err) {
+        const code = RFC_TO_SDK_ERROR[err?.code] ?? 'UNKNOWN_ERROR';
+        return { code, message: err?.message ?? 'Request failed' };
+    }
+    /**
+     * Build a connect response compatible with what the SDK expects
+     * ({ address, networkInfo, permissions, balance }) by making
+     * three RFC-O-1 calls: octra_requestAccounts, octra_networkInfo, octra_permissions.
+     */
+    async function rfcConnect(provider, params) {
+        const requestPerms = params?.requestPermissions ?? [];
+        const accounts = (await provider.request({
+            method: 'octra_requestAccounts',
+            params: [{ permissions: requestPerms }],
+        }));
+        const address = accounts?.[0] ?? null;
+        const [networkInfo, permissions] = await Promise.all([
+            provider.request({ method: 'octra_networkInfo' }),
+            provider.request({ method: 'octra_permissions' }),
+        ]);
+        return { address, networkInfo, permissions, balance: null };
+    }
+    /**
+     * Build a getConnectionStatus response by checking octra_accounts.
+     */
+    async function rfcConnectionStatus(provider) {
+        const accounts = (await provider.request({ method: 'octra_accounts' }));
+        const address = accounts?.[0] ?? null;
+        if (!address)
+            return { isConnected: false };
+        const [networkInfo, permissions] = await Promise.all([
+            provider.request({ method: 'octra_networkInfo' }),
+            provider.request({ method: 'octra_permissions' }),
+        ]);
+        return { isConnected: true, address, networkInfo, permissions };
+    }
+    function createOctraProviderAdapter() {
+        let _handler = null;
+        return {
+            name: 'octra-provider',
+            displayName: 'Octra Wallet (RFC-O-1)',
+            detect() {
+                const p = getProvider();
+                return p?.isOctra === true;
+            },
+            postRequest(request) {
+                const { id, method, params } = request;
+                const provider = getProvider();
+                if (!provider) {
+                    _handler?.({
+                        requestId: id,
+                        success: false,
+                        error: { code: 'EXTENSION_NOT_FOUND', message: 'No RFC-O-1 provider found on window.octra' },
+                    });
+                    return;
+                }
+                (async () => {
+                    try {
+                        let data;
+                        if (method === 'ping') {
+                            data = { available: true };
+                        }
+                        else if (method === 'register_dapp') {
+                            data = { success: true };
+                        }
+                        else if (method === 'connect') {
+                            data = await rfcConnect(provider, params);
+                        }
+                        else if (method === 'disconnect') {
+                            await provider.request({ method: 'disconnect' }).catch(() => { });
+                            data = { success: true };
+                        }
+                        else if (method === 'getConnectionStatus') {
+                            data = await rfcConnectionStatus(provider);
+                        }
+                        else {
+                            const rfcMethod = SDK_TO_RFC[method] ?? method;
+                            data = await provider.request({ method: rfcMethod, params });
+                        }
+                        _handler?.({ requestId: id, success: true, data });
+                    }
+                    catch (err) {
+                        _handler?.({ requestId: id, success: false, error: mapError(err) });
+                    }
+                })();
+            },
+            listen(handler) {
+                _handler = handler;
+                const provider = getProvider();
+                if (!provider)
+                    return () => { _handler = null; };
+                // RFC-O-1 event → SDK event name + data shape
+                const onConnect = (data) => handler({ eventType: 'connect', eventData: data });
+                const onDisconnect = (data) => handler({ eventType: 'disconnect', eventData: { reason: 'network_error', ...data } });
+                const onAccountsChanged = (accounts) => handler({ eventType: 'accountChanged', eventData: { address: accounts?.[0] ?? null } });
+                const onNetworkChanged = (data) => handler({ eventType: 'networkChanged', eventData: { networkInfo: data } });
+                const onBalanceChanged = (data) => handler({ eventType: 'balanceChanged', eventData: data });
+                const onTransactionChanged = (data) => handler({ eventType: 'transactionConfirmed', eventData: data });
+                provider.on('connect', onConnect);
+                provider.on('disconnect', onDisconnect);
+                provider.on('accountsChanged', onAccountsChanged);
+                provider.on('networkChanged', onNetworkChanged);
+                provider.on('balanceChanged', onBalanceChanged);
+                provider.on('transactionChanged', onTransactionChanged);
+                const cleanup = () => {
+                    provider.removeListener('connect', onConnect);
+                    provider.removeListener('disconnect', onDisconnect);
+                    provider.removeListener('accountsChanged', onAccountsChanged);
+                    provider.removeListener('networkChanged', onNetworkChanged);
+                    provider.removeListener('balanceChanged', onBalanceChanged);
+                    provider.removeListener('transactionChanged', onTransactionChanged);
+                    _handler = null;
+                };
+                return cleanup;
+            },
+            listenForReady(onReady) {
+                const handler = () => onReady();
+                window.addEventListener('octraWalletReady', handler);
+                return () => window.removeEventListener('octraWalletReady', handler);
+            },
+        };
+    }
+    /** Default RFC-O-1 adapter instance. */
+    const OctraProviderAdapter = createOctraProviderAdapter();
+
+    /**
+     * 0xio SDK — Wallet Adapter Registry
+     *
+     * Add new wallet adapters here. Detection order determines which wallet takes
+     * priority when multiple wallets are installed at the same time.
+     */
+    const REGISTERED_ADAPTERS = [
+        ZeroXIOAdapter, // 0xio extension (postMessage protocol) — highest priority
+        OctraProviderAdapter, // any RFC-O-1 compliant wallet (window.octra)
+        // Add new wallet adapters here — detection runs in order, first match wins
+    ];
+    /**
+     * Auto-detects the first available wallet in the current page.
+     * Returns null if no supported wallet is found.
+     *
+     * @example
+     * const adapter = detectWalletAdapter();
+     * if (!adapter) throw new Error('No supported wallet found');
+     * const wallet = new ZeroXIOWallet({ appName: 'My DApp', adapter });
+     */
+    function detectWalletAdapter() {
+        if (typeof window === 'undefined')
+            return null;
+        return REGISTERED_ADAPTERS.find((a) => a.detect()) ?? null;
+    }
+    /** Returns all registered adapter instances. */
+    function getAllAdapters() {
+        return [...REGISTERED_ADAPTERS];
+    }
+
     /**
      * 0xio Wallet SDK - Main Entry Point
      * Official SDK for integrating with 0xio Wallet Extension
@@ -1894,7 +2391,7 @@
      */
     // Main exports
     // Version information
-    const SDK_VERSION = '2.5.0';
+    const SDK_VERSION = '2.7.0';
     const MIN_EXTENSION_VERSION = '2.0.1'; // Mainnet Alpha
     const MIN_EXTENSION_VERSION_DEVNET = '2.2.1'; // Devnet (contract calls, privacy)
     const SUPPORTED_EXTENSION_VERSIONS = '^2.0.1'; // Supports all versions >= 2.0.1
@@ -1904,7 +2401,8 @@
         const wallet$1 = new ZeroXIOWallet({
             appName: config.appName,
             appDescription: config.appDescription,
-            debug: config.debug || false
+            debug: config.debug || false,
+            ...(config.adapter ? { adapter: config.adapter } : {}),
         });
         await wallet$1.initialize();
         if (config.autoConnect) {
@@ -1918,23 +2416,35 @@
         }
         return wallet$1;
     }
-    // Legacy alias for backward compatibility
-    const createOctraWallet = createZeroXIOWallet;
     // Browser detection and compatibility check
     function checkSDKCompatibility() {
         const issues = [];
         const recommendations = [];
-        // Basic browser support check
+        // Hard blockers — SDK cannot function without these
         if (typeof window === 'undefined') {
             issues.push('Window object not available');
             recommendations.push('SDK must be used in a browser environment');
+            return { compatible: false, issues, recommendations };
+        }
+        if (typeof window.postMessage !== 'function') {
+            issues.push('postMessage API not available');
+            recommendations.push('Your browser environment must support postMessage');
+        }
+        if (typeof window.addEventListener !== 'function') {
+            issues.push('addEventListener not available');
+        }
+        if (typeof Promise === 'undefined') {
+            issues.push('Promise not available');
         }
-        // Check for extension APIs
-        if (typeof window !== 'undefined') {
+        // Informational: note which transport is likely active
+        if (issues.length === 0) {
             const win = window;
-            if (!win.chrome || !win.chrome.runtime) {
-                issues.push('Chrome extension APIs not available');
-                recommendations.push('This SDK requires a Chromium-based browser (Chrome, Edge, Brave, etc.)');
+            const hasExtension = !!(win.wallet0xio || win.ZeroXIOWallet || win.chrome?.runtime?.id ||
+                document.querySelector('meta[name="0xio-dapp"]') || document.querySelector('[data-0xio-sdk-bridge]'));
+            const hasParentBridge = window.parent !== window;
+            if (!hasExtension && !hasParentBridge) {
+                recommendations.push('No 0xio transport detected yet. Install the 0xio Wallet browser extension, ' +
+                    'or run inside the 0xio Desktop/Mobile app iframe bridge.');
             }
         }
         return {
@@ -1996,9 +2506,11 @@
     exports.MIN_EXTENSION_VERSION = MIN_EXTENSION_VERSION;
     exports.MIN_EXTENSION_VERSION_DEVNET = MIN_EXTENSION_VERSION_DEVNET;
     exports.NETWORKS = NETWORKS;
+    exports.OctraProviderAdapter = OctraProviderAdapter;
     exports.SDK_CONFIG = SDK_CONFIG;
     exports.SDK_VERSION = SDK_VERSION;
     exports.SUPPORTED_EXTENSION_VERSIONS = SUPPORTED_EXTENSION_VERSIONS;
+    exports.ZeroXIOAdapter = ZeroXIOAdapter;
     exports.ZeroXIOWallet = ZeroXIOWallet;
     exports.ZeroXIOWalletError = ZeroXIOWalletError;
     exports.checkBrowserSupport = checkBrowserSupport;
@@ -2006,9 +2518,12 @@
     exports.createDefaultBalance = createDefaultBalance;
     exports.createErrorMessage = createErrorMessage;
     exports.createLogger = createLogger;
-    exports.createOctraWallet = createOctraWallet;
+    exports.createOctraProviderAdapter = createOctraProviderAdapter;
+    exports.createZeroXIOAdapter = createZeroXIOAdapter;
     exports.createZeroXIOWallet = createZeroXIOWallet;
     exports.delay = delay;
+    exports.deriveOctraAddress = deriveOctraAddress;
+    exports.detectWalletAdapter = detectWalletAdapter;
     exports.formatAddress = formatAddress;
     exports.formatOCT = formatOCT;
     exports.formatTimestamp = formatTimestamp;
@@ -2017,6 +2532,7 @@
     exports.fromMicroOCT = fromMicroOCT;
     exports.fromMicroZeroXIO = fromMicroOCT;
     exports.generateMockData = generateMockData;
+    exports.getAllAdapters = getAllAdapters;
     exports.getAllNetworks = getAllNetworks;
     exports.getDefaultNetwork = getDefaultNetwork;
     exports.getNetworkConfig = getNetworkConfig;
@@ -2027,10 +2543,8 @@
     exports.isValidFeeLevel = isValidFeeLevel;
     exports.isValidMessage = isValidMessage;
     exports.isValidNetworkId = isValidNetworkId;
-    exports.retry = retry;
     exports.toMicroOCT = toMicroOCT;
     exports.toMicroZeroXIO = toMicroOCT;
-    exports.withTimeout = withTimeout;
 
 }));
 //# sourceMappingURL=index.umd.js.map