@0xio/sdk 2.5.0 → 2.7.0

package/dist/index.esm.js

@@ -35,8 +35,9 @@ class EventEmitter {
      */
     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);
     }
@@ -137,6 +138,135 @@ class ZeroXIOWalletError extends Error {
     }
 }
 
+/**
+ * 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
@@ -156,9 +286,15 @@ function isValidAddress(address) {
     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) &&
@@ -168,11 +304,13 @@ function isValidAmount(amount) {
  * 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;
@@ -184,16 +322,64 @@ function isValidFeeLevel(feeLevel) {
     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
     });
@@ -395,7 +581,7 @@ function generateMockData() {
         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',
@@ -468,108 +654,54 @@ function createLogger(prefix, debug) {
  * 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');
@@ -584,149 +716,106 @@ class ExtensionCommunicator extends EventEmitter {
             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(ErrorCode.EXTENSION_NOT_FOUND, '0xio Wallet extension is not installed or available', {
-                method,
-                params,
-                browserContext: this.getBrowserDiagnostics()
-            });
+            throw new ZeroXIOWalletError(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(ErrorCode.EXTENSION_NOT_FOUND, 'Extension not available for communication', {
-                    method,
-                    params,
-                    extensionState: this.getExtensionDiagnostics()
-                });
+                throw new ZeroXIOWalletError(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(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(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(ErrorCode.NETWORK_ERROR, `Request timeout after ${timeout}ms`, {
-                            method,
-                            params,
-                            requestId,
-                            retryCount: pending.retryCount,
-                            extensionState: this.getExtensionDiagnostics()
-                        }));
+                        reject(new ZeroXIOWalletError(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);
@@ -734,192 +823,131 @@ class ExtensionCommunicator extends EventEmitter {
             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 : 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(ErrorCode.UNKNOWN_ERROR, 'Unknown error occurred', {
-                    requestId: response.id,
-                    retryCount: pending.retryCount,
-                    extensionState: this.getExtensionDiagnostics()
-                }));
+                pending.reject(new ZeroXIOWalletError(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(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(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(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');
@@ -928,25 +956,9 @@ class ExtensionCommunicator extends EventEmitter {
             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;
@@ -954,14 +966,11 @@ class ExtensionCommunicator extends EventEmitter {
         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;
@@ -970,11 +979,10 @@ class ExtensionCommunicator extends EventEmitter {
                 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;
@@ -992,9 +1000,6 @@ class ExtensionCommunicator extends EventEmitter {
             }, 100);
         });
     }
-    /**
-     * Get browser diagnostics for error reporting
-     */
     getBrowserDiagnostics() {
         if (typeof window === 'undefined') {
             return { environment: 'non-browser' };
@@ -1006,29 +1011,21 @@ class ExtensionCommunicator extends EventEmitter {
             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) {
@@ -1042,18 +1039,22 @@ class ExtensionCommunicator extends EventEmitter {
         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,
@@ -1064,23 +1065,30 @@ class ExtensionCommunicator extends EventEmitter {
         };
     }
 }
-// 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',
@@ -1111,49 +1119,106 @@ const NETWORKS = {
         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(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,
@@ -1175,6 +1240,9 @@ class ZeroXIOWallet extends EventEmitter {
         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',
@@ -1182,7 +1250,7 @@ class ZeroXIOWallet extends EventEmitter {
             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);
     }
     // ===================
@@ -1196,35 +1264,45 @@ class ZeroXIOWallet extends EventEmitter {
         if (this.isInitialized) {
             return true;
         }
-        try {
-            // Initialize extension communication
-            const communicationReady = await this.communicator.initialize();
-            if (!communicationReady) {
-                throw new ZeroXIOWalletError(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(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(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(ErrorCode.UNKNOWN_ERROR, 'Failed to initialize SDK', error);
+            }
+            finally {
+                this._initPromise = null;
+            }
+        })();
+        return this._initPromise;
     }
     /**
      * Check if SDK is initialized
@@ -1242,31 +1320,53 @@ class ZeroXIOWallet extends EventEmitter {
         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(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) {
@@ -1284,6 +1384,7 @@ class ZeroXIOWallet extends EventEmitter {
         this.ensureInitialized();
         try {
             await this.communicator.sendRequest('disconnect');
+            ++this._sessionVersion;
             this.connectionInfo = { isConnected: false };
             const disconnectEvent = {
                 reason: 'user_action'
@@ -1314,30 +1415,55 @@ class ZeroXIOWallet extends EventEmitter {
     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
@@ -1357,10 +1483,14 @@ class ZeroXIOWallet extends EventEmitter {
      * 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);
@@ -1403,22 +1533,28 @@ class ZeroXIOWallet extends EventEmitter {
             // 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,
@@ -1433,6 +1569,8 @@ class ZeroXIOWallet extends EventEmitter {
             return result;
         }
         catch (error) {
+            if (error instanceof ZeroXIOWalletError)
+                throw error;
             throw new ZeroXIOWalletError(ErrorCode.NETWORK_ERROR, 'Failed to get balance', error);
         }
     }
@@ -1442,26 +1580,37 @@ class ZeroXIOWallet extends EventEmitter {
     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(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(ErrorCode.NETWORK_ERROR, 'Failed to get network info', error);
         }
     }
@@ -1473,8 +1622,20 @@ class ZeroXIOWallet extends EventEmitter {
      */
     async sendTransaction(txData) {
         this.ensureConnected();
+        // validate inputs
+        if (!isValidAddress(txData.to)) {
+            throw new ZeroXIOWalletError(ErrorCode.INVALID_ADDRESS, 'Invalid recipient address');
+        }
+        if (!isValidAmount(txData.amount)) {
+            throw new ZeroXIOWalletError(ErrorCode.TRANSACTION_FAILED, 'Invalid transaction amount');
+        }
+        // bound memo
+        if (txData.message && txData.message.length > 1000) {
+            throw new ZeroXIOWalletError(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
@@ -1501,8 +1662,30 @@ class ZeroXIOWallet extends EventEmitter {
      */
     async callContract(callData) {
         this.ensureConnected();
+        // validate inputs
+        if (!isValidAddress(callData.contract)) {
+            throw new ZeroXIOWalletError(ErrorCode.INVALID_ADDRESS, 'Invalid contract address');
+        }
+        if (!callData.method || typeof callData.method !== 'string') {
+            throw new ZeroXIOWalletError(ErrorCode.TRANSACTION_FAILED, 'Contract method is required');
+        }
+        // bound method + params size
+        if (callData.method.length > 200) {
+            throw new ZeroXIOWalletError(ErrorCode.TRANSACTION_FAILED, 'Contract method name too long (max 200 characters)');
+        }
+        try {
+            if (JSON.stringify(callData.params).length > 65536) {
+                throw new ZeroXIOWalletError(ErrorCode.TRANSACTION_FAILED, 'Contract params too large (max 64 KB)');
+            }
+        }
+        catch (e) {
+            if (e instanceof ZeroXIOWalletError)
+                throw e;
+            throw new ZeroXIOWalletError(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,
@@ -1527,13 +1710,36 @@ class ZeroXIOWallet extends EventEmitter {
      */
     async contractCallView(viewData) {
         this.ensureInitialized();
+        // validate inputs
+        if (!isValidAddress(viewData.contract)) {
+            throw new ZeroXIOWalletError(ErrorCode.INVALID_ADDRESS, 'Invalid contract address');
+        }
+        if (!viewData.method || typeof viewData.method !== 'string') {
+            throw new ZeroXIOWalletError(ErrorCode.NETWORK_ERROR, 'Contract method is required');
+        }
+        // bound method + params size
+        if (viewData.method.length > 200) {
+            throw new ZeroXIOWalletError(ErrorCode.NETWORK_ERROR, 'Contract method name too long (max 200 characters)');
+        }
+        try {
+            if (JSON.stringify(viewData.params).length > 65536) {
+                throw new ZeroXIOWalletError(ErrorCode.NETWORK_ERROR, 'Contract params too large (max 64 KB)');
+            }
+        }
+        catch (e) {
+            if (e instanceof ZeroXIOWalletError)
+                throw e;
+            throw new ZeroXIOWalletError(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;
@@ -1551,6 +1757,16 @@ class ZeroXIOWallet extends EventEmitter {
      */
     async getContractStorage(contract, key) {
         this.ensureInitialized();
+        // validate inputs
+        if (!isValidAddress(contract)) {
+            throw new ZeroXIOWalletError(ErrorCode.INVALID_ADDRESS, 'Invalid contract address');
+        }
+        if (!key || typeof key !== 'string') {
+            throw new ZeroXIOWalletError(ErrorCode.NETWORK_ERROR, 'Storage key is required');
+        }
+        if (key.length > 200) {
+            throw new ZeroXIOWalletError(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', {
@@ -1604,13 +1820,17 @@ class ZeroXIOWallet extends EventEmitter {
      */
     async encryptBalance(amount) {
         this.ensureConnected();
+        // validate amount
+        if (!isValidAmount(amount)) {
+            throw new ZeroXIOWalletError(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(ErrorCode.TRANSACTION_FAILED, 'Failed to encrypt balance', error);
@@ -1621,23 +1841,43 @@ class ZeroXIOWallet extends EventEmitter {
      */
     async decryptBalance(amount) {
         this.ensureConnected();
+        // validate amount
+        if (!isValidAmount(amount)) {
+            throw new ZeroXIOWalletError(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(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(ErrorCode.INVALID_ADDRESS, 'Invalid recipient address');
+        }
+        if (!isValidAmount(transferData.amount)) {
+            throw new ZeroXIOWalletError(ErrorCode.TRANSACTION_FAILED, 'Invalid transfer amount');
+        }
+        // bound msg size
+        if (transferData.message && transferData.message.length > 1000) {
+            throw new ZeroXIOWalletError(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
@@ -1653,7 +1893,9 @@ class ZeroXIOWallet extends EventEmitter {
         }
     }
     /**
-     * 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();
@@ -1666,10 +1908,15 @@ class ZeroXIOWallet extends EventEmitter {
         }
     }
     /**
-     * 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(ErrorCode.TRANSACTION_FAILED, 'Invalid transfer ID');
+        }
         try {
             const result = await this.communicator.sendRequest('claim_private_transfer', {
                 transferId
@@ -1727,6 +1974,30 @@ class ZeroXIOWallet extends EventEmitter {
         }
     }
     // ===================
+    // 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(ErrorCode.SIGNATURE_FAILED, 'Service name is required');
+        }
+        if (!nonce || typeof nonce !== 'string') {
+            throw new ZeroXIOWalletError(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() {
@@ -1766,28 +2037,47 @@ class ZeroXIOWallet extends EventEmitter {
      * 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);
@@ -1796,21 +2086,30 @@ class ZeroXIOWallet extends EventEmitter {
      * 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'
         };
@@ -1821,6 +2120,8 @@ class ZeroXIOWallet extends EventEmitter {
      * 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');
@@ -1853,6 +2154,8 @@ class ZeroXIOWallet extends EventEmitter {
         this.removeAllListeners();
         this.connectionInfo = { isConnected: false };
         this.isInitialized = false;
+        this._initPromise = null;
+        ++this._sessionVersion;
         this.logger.log('SDK cleanup complete');
     }
 }
@@ -1862,6 +2165,200 @@ var wallet = /*#__PURE__*/Object.freeze({
     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
@@ -1888,7 +2385,7 @@ var wallet = /*#__PURE__*/Object.freeze({
  */
 // 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
@@ -1898,7 +2395,8 @@ async function createZeroXIOWallet(config) {
     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) {
@@ -1912,23 +2410,35 @@ async function createZeroXIOWallet(config) {
     }
     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 {
@@ -1984,5 +2494,5 @@ if (typeof window !== 'undefined') {
     }
 }
 
-export { DEFAULT_NETWORK_ID, ErrorCode, EventEmitter, ExtensionCommunicator, MIN_EXTENSION_VERSION, MIN_EXTENSION_VERSION_DEVNET, NETWORKS, SDK_CONFIG, SDK_VERSION, SUPPORTED_EXTENSION_VERSIONS, ZeroXIOWallet, ZeroXIOWalletError, checkBrowserSupport, checkSDKCompatibility, createDefaultBalance, createErrorMessage, createLogger, createOctraWallet, createZeroXIOWallet, delay, formatAddress, formatOCT, formatTimestamp, formatTxHash, formatOCT as formatZeroXIO, fromMicroOCT, fromMicroOCT as fromMicroZeroXIO, generateMockData, getAllNetworks, getDefaultNetwork, getNetworkConfig, isBrowser, isErrorType, isValidAddress, isValidAmount, isValidFeeLevel, isValidMessage, isValidNetworkId, retry, toMicroOCT, toMicroOCT as toMicroZeroXIO, withTimeout };
+export { DEFAULT_NETWORK_ID, ErrorCode, EventEmitter, ExtensionCommunicator, MIN_EXTENSION_VERSION, MIN_EXTENSION_VERSION_DEVNET, NETWORKS, OctraProviderAdapter, SDK_CONFIG, SDK_VERSION, SUPPORTED_EXTENSION_VERSIONS, ZeroXIOAdapter, ZeroXIOWallet, ZeroXIOWalletError, checkBrowserSupport, checkSDKCompatibility, createDefaultBalance, createErrorMessage, createLogger, createOctraProviderAdapter, createZeroXIOAdapter, createZeroXIOWallet, delay, deriveOctraAddress, detectWalletAdapter, formatAddress, formatOCT, formatTimestamp, formatTxHash, formatOCT as formatZeroXIO, fromMicroOCT, fromMicroOCT as fromMicroZeroXIO, generateMockData, getAllAdapters, getAllNetworks, getDefaultNetwork, getNetworkConfig, isBrowser, isErrorType, isValidAddress, isValidAmount, isValidFeeLevel, isValidMessage, isValidNetworkId, toMicroOCT, toMicroOCT as toMicroZeroXIO };
 //# sourceMappingURL=index.esm.js.map