@0xio/sdk 2.6.0 → 2.7.1

package/dist/index.d.ts

@@ -1,3 +1,140 @@
+/**
+ * 0xio SDK — Wallet Transport Adapter Interface
+ *
+ * Implement WalletTransportAdapter to add support for a new wallet without
+ * touching any core SDK code. Drop the adapter file in src/supports/ and
+ * pass it to ZeroXIOWallet via SDKConfig.adapter.
+ *
+ * @example
+ * ```typescript
+ * import { ZeroXIOWallet } from '@0xio/sdk';
+ * import { QubitzAdapter } from '@0xio/sdk/supports/qubitz';
+ *
+ * const wallet = new ZeroXIOWallet({
+ *   appName: 'My DApp',
+ *   adapter: QubitzAdapter,
+ * });
+ * ```
+ */
+/**
+ * Outbound request — the SDK passes this to adapter.postRequest() for every
+ * outbound wallet call. Adapters translate this into their wallet-specific wire format.
+ */
+interface AdapterRequest {
+    /** Unique request ID (UUID). Used to correlate the response. */
+    id: string;
+    /** Method name, e.g. 'connect', 'sendTransaction', 'signMessage' */
+    method: string;
+    /** Method parameters */
+    params: unknown;
+    /** Unix timestamp (ms) when the request was created */
+    timestamp: number;
+}
+/**
+ * Normalized inbound message from a wallet.
+ * Adapters translate their wallet-specific wire format into this structure
+ * and pass it to the handler registered via listen().
+ *
+ * A message is either a response (requestId set) or a push event (eventType set).
+ */
+interface AdapterIncomingMessage {
+    /** Must match the id from the outbound AdapterRequest */
+    requestId?: string;
+    /** Whether the request succeeded. Required when requestId is set. */
+    success?: boolean;
+    /** Response payload on success */
+    data?: unknown;
+    /** Structured error on failure */
+    error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    /** Event type, e.g. 'connect', 'disconnect', 'accountChanged', 'balanceChanged' */
+    eventType?: string;
+    /** Event payload */
+    eventData?: unknown;
+}
+/**
+ * Wallet transport adapter.
+ *
+ * Encapsulates the entire wallet-specific communication layer:
+ * - How to detect if the wallet is installed
+ * - How to send requests (postRequest)
+ * - How to receive responses and events (listen)
+ *
+ * Everything else — request lifecycle, timeouts, retries, rate limiting,
+ * event routing — is handled by the SDK core and does not change per wallet.
+ *
+ * @example Minimal adapter for a hypothetical wallet
+ * ```typescript
+ * export const MyWalletAdapter: WalletTransportAdapter = {
+ *   name: 'mywallet',
+ *   displayName: 'My Wallet',
+ *   detect: () => !!(window as any).myWallet,
+ *   postRequest: (req) =>
+ *     window.postMessage({ source: 'mywallet-request', ...req }, location.origin),
+ *   listen: (handler) => {
+ *     const fn = (e: MessageEvent) => {
+ *       if (e.data?.source !== 'mywallet-response') return;
+ *       handler({ requestId: e.data.id, success: e.data.ok, data: e.data.result });
+ *     };
+ *     window.addEventListener('message', fn);
+ *     return () => window.removeEventListener('message', fn);
+ *   },
+ * };
+ * ```
+ */
+interface WalletTransportAdapter {
+    /**
+     * Machine-readable wallet identifier. Used in logs and adapter selection.
+     * Examples: '0xio', 'qubitz', 'fhex'
+     */
+    readonly name: string;
+    /**
+     * Human-readable wallet name shown in error messages.
+     * Examples: '0xio Wallet', 'Qubitz Wallet', 'FHEX Wallet'
+     */
+    readonly displayName: string;
+    /**
+     * Returns true when this wallet's extension / injected provider is present
+     * in the current page context. Called periodically by the SDK to check availability.
+     */
+    detect(): boolean;
+    /**
+     * Send a request to the wallet.
+     * Called once per outbound request — translate AdapterRequest into your
+     * wallet's wire format and post it (window.postMessage, direct API call, etc.).
+     */
+    postRequest(request: AdapterRequest): void;
+    /**
+     * Optional: send the same request to a trusted parent frame (iframe/desktop bridge).
+     * Only implement this if your wallet supports an embedded iframe bridge mode.
+     * The SDK calls this when window.parent !== window and a trusted parent origin exists.
+     */
+    postRequestToParent?(request: AdapterRequest, parentOrigin: string): void;
+    /**
+     * Set up response and event listening.
+     * The SDK calls this once during initialization. Normalise all incoming wallet
+     * messages into AdapterIncomingMessage and pass them to handler.
+     *
+     * @param handler  Callback for responses and push events
+     * @param options  SDK-level options, e.g. additional trusted parent origins
+     * @returns        A teardown function — the SDK calls it on cleanup()
+     */
+    listen(handler: (msg: AdapterIncomingMessage) => void, options?: {
+        trustedParentOrigins?: string[];
+    }): () => void;
+    /**
+     * Optional: register wallet-ready event listeners (e.g. 'myWalletReady' CustomEvent).
+     * Called once during SDK init. When the wallet signals it is ready, call onReady().
+     * Returns a cleanup function.
+     *
+     * If not implemented, the SDK falls back to polling detect() every 2 seconds.
+     */
+    listenForReady?(onReady: () => void): () => void;
+}
+
 /**
  * 0xio Wallet SDK - Type Definitions
  * Comprehensive type system for 0xio wallet integration with Octra Network
@@ -25,7 +162,8 @@ interface NetworkInfo {
 }
 interface TransactionData {
     readonly to: string;
-    readonly amount: number;
+    /** Amount in OCT. Accepts string or number — use string for amounts above 9 billion OCT to avoid JS number precision loss. */
+    readonly amount: string | number;
     readonly message?: string;
     readonly feeLevel?: 1 | 3;
     readonly isPrivate?: boolean;
@@ -49,8 +187,8 @@ interface ContractCallData {
      */
     readonly params: ContractParams;
     /**
-     * Native OCT to send with the call (in micro-units, 1 OCT = 1000000).
-     * Set to 0 for calls that don't transfer native tokens.
+     * Native OCT to send with the call (in OCT, same unit as sendTransaction.amount).
+     * Set to '0' for calls that don't transfer native tokens.
      */
     readonly amount?: string | number;
     /**
@@ -81,10 +219,18 @@ interface SignedTransaction {
     readonly signature: string;
     readonly public_key: string;
 }
-type TransactionFinality = 'pending' | 'confirmed' | 'rejected';
+type TransactionFinality = 'pending' | 'confirmed' | 'rejected' | 'dropped';
 interface TransactionResult {
-    readonly txHash: string;
-    readonly success: boolean;
+    /** RFC-O-1 canonical hash field */
+    readonly hash?: string;
+    /** RFC-O-1 canonical accepted field */
+    readonly accepted?: boolean;
+    /** RFC-O-1 status field */
+    readonly status?: TransactionFinality;
+    /** @deprecated Use hash */
+    readonly txHash?: string;
+    /** @deprecated Use accepted */
+    readonly success?: boolean;
     readonly finality?: TransactionFinality;
     readonly message?: string;
     readonly explorerUrl?: string;
@@ -99,10 +245,12 @@ interface Transaction {
     readonly hash: string;
     readonly from: string;
     readonly to: string;
-    readonly amount: number;
-    readonly fee: number;
+    /** Amount in OCT as returned by the node (may be string or number depending on extension version). */
+    readonly amount: string | number;
+    /** Fee in OCT as returned by the node (may be string or number depending on extension version). */
+    readonly fee: string | number;
     readonly timestamp: number;
-    readonly status: 'pending' | 'confirmed' | 'failed';
+    readonly status: 'pending' | 'confirmed' | 'failed' | 'dropped';
     readonly finality?: TransactionFinality;
     readonly message?: string;
     readonly blockHeight?: number;
@@ -114,13 +262,17 @@ interface ConnectionInfo {
     balance?: Balance;
     networkInfo?: NetworkInfo;
     connectedAt?: number;
+    permissions?: Permission[];
 }
 interface ConnectOptions {
+    /** RFC-O-1 canonical field name */
+    readonly permissions?: Permission[];
+    /** @deprecated Use permissions */
     readonly requestPermissions?: Permission[];
     readonly networkId?: string;
 }
-type Permission = 'read_address' | 'read_balance' | 'send_transactions' | 'sign_messages' | 'view_private_balance' | 'private_transfers';
-type WalletEventType = 'connect' | 'disconnect' | 'accountChanged' | 'balanceChanged' | 'networkChanged' | 'transactionConfirmed' | 'error' | 'extensionLocked' | 'extensionUnlocked';
+type Permission = 'read_address' | 'read_balance' | 'read_public_key' | 'send_transactions' | 'sign_messages' | 'contract_calls' | 'view_private_balance' | 'view_encrypted_balance' | 'private_transfers' | 'encrypt_balance' | 'decrypt_balance' | 'stealth_scan' | 'stealth_claim';
+type WalletEventType = 'connect' | 'disconnect' | 'accountChanged' | 'balanceChanged' | 'networkChanged' | 'transactionConfirmed' | 'permissionsChanged' | 'message' | 'error' | 'extensionLocked' | 'extensionUnlocked';
 interface WalletEvent<T = any> {
     readonly type: WalletEventType;
     readonly data: T;
@@ -128,7 +280,7 @@ interface WalletEvent<T = any> {
 }
 interface ConnectEvent {
     readonly address: string;
-    readonly publicKey?: string;
+    readonly publicKey: string | undefined;
     readonly balance: Balance;
     readonly networkInfo: NetworkInfo;
     readonly permissions: Permission[];
@@ -140,6 +292,7 @@ interface AccountChangedEvent {
     readonly previousAddress?: string;
     readonly newAddress: string;
     readonly balance: Balance;
+    readonly publicKey?: string;
 }
 interface BalanceChangedEvent {
     readonly address: string;
@@ -192,7 +345,8 @@ interface PrivateBalanceInfo {
 }
 interface PrivateTransferData {
     readonly to: string;
-    readonly amount: number;
+    /** Amount in OCT. Accepts string or number — use string for amounts above 9 billion OCT to avoid JS number precision loss. */
+    readonly amount: string | number;
     readonly message?: string;
 }
 interface PendingPrivateTransfer {
@@ -212,6 +366,22 @@ interface SDKConfig {
     readonly requiredPermissions?: Permission[];
     readonly networkId?: string;
     readonly debug?: boolean;
+    /**
+     * Exact origins allowed as parent iframe bridge (e.g. 'https://app.example.com').
+     * When set, only these origins (plus tauri://) are trusted — implicit localhost trust
+     * is disabled. Leave unset for development (all localhost trusted by default).
+     */
+    readonly trustedParentOrigins?: string[];
+    /**
+     * Custom wallet transport adapter.
+     * Defaults to ZeroXIOAdapter (0xio extension postMessage protocol).
+     * Pass an adapter from src/supports/ to target a different wallet.
+     *
+     * @example
+     * import { QubitzAdapter } from '@0xio/sdk/supports/qubitz';
+     * new ZeroXIOWallet({ appName: 'My DApp', adapter: QubitzAdapter });
+     */
+    readonly adapter?: WalletTransportAdapter;
 }
 interface ExtensionRequest {
     readonly id: string;
@@ -231,74 +401,31 @@ interface ExtensionResponse<T = any> {
     readonly timestamp: number;
 }
 
-/**
- * 0xio Wallet SDK - Event System
- * Type-safe event emitter for wallet events
- */
-
 type EventListener<T = any> = (event: WalletEvent<T>) => void;
 declare class EventEmitter {
     private listeners;
-    private debug;
-    constructor(debug?: boolean);
-    /**
-     * Add event listener
-     */
+    constructor(_debug?: boolean);
     on<T = any>(eventType: WalletEventType, listener: EventListener<T>): void;
-    /**
-     * Remove event listener
-     */
     off<T = any>(eventType: WalletEventType, listener: EventListener<T>): void;
-    /**
-     * Add one-time event listener
-     */
     once<T = any>(eventType: WalletEventType, listener: EventListener<T>): void;
-    /**
-     * Emit event to all listeners
-     */
     emit<T = any>(eventType: WalletEventType, data: T): void;
-    /**
-     * Remove all listeners for a specific event type
-     */
     removeAllListeners(eventType?: WalletEventType): void;
-    /**
-     * Get number of listeners for an event type
-     */
     listenerCount(eventType: WalletEventType): number;
-    /**
-     * Get all event types that have listeners
-     */
     eventTypes(): WalletEventType[];
-    /**
-     * Check if there are any listeners for an event type
-     */
     hasListeners(eventType: WalletEventType): boolean;
 }
 
-/**
- * 0xio Wallet SDK - Main Wallet Class
- * Primary interface for DApp developers to interact with 0xio Wallet
- */
-
 declare class ZeroXIOWallet extends EventEmitter {
     private communicator;
     private config;
     private connectionInfo;
     private isInitialized;
+    private _initPromise;
+    private _sessionVersion;
     private logger;
     constructor(config: SDKConfig);
-    /**
-     * Initialize the SDK
-     * Must be called before using any other methods
-     */
     initialize(): Promise<boolean>;
-    /**
-     * Check if SDK is initialized
-     */
     isReady(): boolean;
-    /**
-     * Connect to wallet
-     */
     connect(options?: ConnectOptions): Promise<ConnectEvent>;
     /**
      * Disconnect from wallet
@@ -329,22 +456,22 @@ declare class ZeroXIOWallet extends EventEmitter {
      * Get the extension's current network ID ('mainnet' or 'devnet')
      */
     getNetworkId(): string | null;
-    /**
-     * Get current wallet address
-     */
     getAddress(): string | null;
-    /**
-     * Get current balance
-     */
     getBalance(forceRefresh?: boolean): Promise<Balance>;
+    getNetworkInfo(): Promise<NetworkInfo>;
+    sendTransaction(txData: TransactionData): Promise<TransactionResult>;
     /**
-     * Get network information
+     * Sign a transaction without broadcasting it (RFC-O-1 octra_signTransaction).
+     * Returns the signed transaction object for manual submission via submitTransaction().
      */
-    getNetworkInfo(): Promise<NetworkInfo>;
+    signTransaction(txData: TransactionData): Promise<{
+        signedTx: any;
+    }>;
     /**
-     * Send transaction
+     * Broadcast a pre-signed transaction (RFC-O-1 octra_submitTransaction).
+     * Use after signTransaction() to submit the signed tx to the network.
      */
-    sendTransaction(txData: TransactionData): Promise<TransactionResult>;
+    submitTransaction(signedTx: any): Promise<TransactionResult>;
     /**
      * Call a smart contract method (state-changing).
      * The extension builds, signs, and submits the transaction via octra_submit.
@@ -363,18 +490,15 @@ declare class ZeroXIOWallet extends EventEmitter {
      * Get transaction history
      */
     getTransactionHistory(page?: number, limit?: number): Promise<TransactionHistory>;
-    /**
-     * Get private balance information
-     */
     getPrivateBalanceInfo(): Promise<PrivateBalanceInfo>;
     /**
      * Encrypt public balance to private
      */
-    encryptBalance(amount: number): Promise<boolean>;
+    encryptBalance(amount: string | number): Promise<TransactionResult>;
     /**
      * Decrypt private balance to public
      */
-    decryptBalance(amount: number): Promise<boolean>;
+    decryptBalance(amount: string | number): Promise<TransactionResult>;
     /**
      * Send a private (encrypted) transfer to another address.
      * The extension builds the PVAC ciphertext subtraction + range proof + zero proof,
@@ -408,238 +532,92 @@ declare class ZeroXIOWallet extends EventEmitter {
      * ```
      */
     signMessage(message: string): Promise<string>;
+    /**
+     * 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
+     */
+    signAuthMessage(service: string, nonce: string): Promise<string>;
     private ensureInitialized;
     private ensureConnected;
     private setupExtensionEventListeners;
-    /**
-     * Handle account changed event from extension
-     */
     private handleAccountChanged;
-    /**
-     * Handle network changed event from extension
-     */
     private handleNetworkChanged;
-    /**
-     * Handle balance changed event from extension
-     */
     private handleBalanceChanged;
-    /**
-     * Handle extension locked event
-     */
     private handleExtensionLocked;
-    /**
-     * Handle extension unlocked event
-     */
     private handleExtensionUnlocked;
-    /**
-     * Handle transaction confirmed event
-     */
     private handleTransactionConfirmed;
     /**
-     * Clean up SDK resources
+     * Reject numeric amounts that cannot be represented exactly in micro-OCT.
+     * e.g. 0.1 + 0.2 = 0.30000000000000004 — the extension would sign the wrong value.
+     * String amounts bypass this check (caller is responsible for correctness).
      */
+    private assertExactOCTAmount;
     cleanup(): void;
 }
 
-/**
- * 0xio Wallet SDK - Extension Communication Module
- *
- * @fileoverview Manages secure communication between the SDK and browser extension.
- * Implements message passing, request/response handling, rate limiting, and origin validation
- * to ensure secure wallet interactions.
- *
- * @module communication
- * @version 2.6.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);
- * ```
- */
 declare class ExtensionCommunicator extends EventEmitter {
-    /** Legacy request counter (deprecated, kept for fallback) */
-    private requestId;
-    /** Map of pending requests awaiting responses */
     private pendingRequests;
-    /** Initialization state flag */
     private isInitialized;
-    /** Logger instance for debugging */
     private logger;
-    /** Interval handle for periodic extension detection */
     private extensionDetectionInterval;
-    /** Current extension availability state */
     private isExtensionAvailableState;
-    /** Message listener reference for cleanup */
-    private messageListener;
-    /** Trusted parent origins for iframe communication */
     private trustedOrigins;
-    /** Parent origin learned from walletReady signal */
     private _parentOrigin;
-    /** Maximum number of concurrent pending requests */
-    private readonly MAX_CONCURRENT_REQUESTS;
-    /** Time window for rate limiting (milliseconds) */
-    private readonly RATE_LIMIT_WINDOW;
-    /** Maximum requests allowed per time window */
-    private readonly MAX_REQUESTS_PER_WINDOW;
-    /** Timestamps of recent requests for rate limiting */
-    private requestTimestamps;
+    /** Pluggable transport — defaults to the 0xio postMessage protocol. */
+    private adapter;
+    /** Teardown fn returned by adapter.listen() */
+    private _adapterTeardown;
+    /** Teardown fn returned by adapter.listenForReady() */
+    private _adapterReadyTeardown;
     /**
-     * Creates a new ExtensionCommunicator instance
-     *
-     * @param {boolean} debug - Enable debug logging
+     * Set when a trusted walletReady has been received from window.parent.
+     * The polling fallback must NOT clear this flag.
      */
-    constructor(debug?: boolean, trustedOrigins?: string[]);
+    private _parentTrusted;
+    /** walletReady postMessage listener stored for cleanup */
+    private _walletReadyMessageListener;
     /**
-     * Add trusted origins for iframe/bridge communication
-     * Call this before connecting if your dApp runs inside a trusted frame
+     * In-flight interactive request lock.
+     * Methods that open approval popups are serialized — only one at a time.
      */
+    private _interactiveInFlight;
+    private readonly MAX_CONCURRENT_REQUESTS;
+    private readonly RATE_LIMIT_WINDOW;
+    private readonly MAX_REQUESTS_PER_WINDOW;
+    private requestTimestamps;
+    constructor(debug?: boolean, trustedOrigins?: string[], adapter?: WalletTransportAdapter);
     setTrustedOrigins(origins: string[]): void;
-    /**
-     * 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');
-     * }
-     * ```
-     */
     initialize(): Promise<boolean>;
-    /**
-     * Check if extension is available
-     */
     isExtensionAvailable(): boolean;
     private static readonly NO_RETRY_METHODS;
-    /**
-     * Send request to extension
-     */
+    private static readonly INTERACTIVE_METHODS;
     sendRequest<T = any>(method: string, params?: any, timeout?: number): Promise<T>;
-    /**
-     * Send request to extension with automatic retry logic
-     */
     sendRequestWithRetry<T = any>(method: string, params?: any, maxRetries?: number, timeout?: number): Promise<T>;
-    /**
-     * Setup message listener for responses from extension
-     */
     private setupMessageListener;
-    /**
-     * Handle extension event
-     */
+    private static readonly VALID_EVENT_TYPES;
     private handleExtensionEvent;
-    /**
-     * Handle response from extension
-     */
     private handleExtensionResponse;
-    /**
-     * Post message to extension via content script
-     */
     private postMessageToExtension;
-    /**
-     * Check if we're in a context that can communicate with extension
-     */
     private hasExtensionContext;
-    /**
-     * 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
-     */
     private checkRateLimit;
-    /**
-     * 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
-     */
     private generateRequestId;
-    /**
-     * Start continuous extension detection
-     */
     private startExtensionDetection;
-    /**
-     * Check if extension is currently available
-     */
     private checkExtensionAvailability;
-    /**
-     * Detect extension signals/indicators
-     */
     private detectExtensionSignals;
-    /**
-     * Wait for extension to become available
-     */
     private waitForExtensionAvailability;
-    /**
-     * Get browser diagnostics for error reporting
-     */
     private getBrowserDiagnostics;
-    /**
-     * Get extension state diagnostics
-     */
     private getExtensionDiagnostics;
     /**
-     * Cleanup pending requests
+     * Clean up SDK resources.
+     * After cleanup() the instance is terminal — do not call initialize() again.
+     * Construct a new instance instead.
      */
     cleanup(): void;
-    /**
-     * Get debug information
-     */
     getDebugInfo(): {
         initialized: boolean;
         available: boolean;
@@ -649,123 +627,138 @@ declare class ExtensionCommunicator extends EventEmitter {
     };
 }
 
+/**
+ * 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.
+ */
+declare function createZeroXIOAdapter(extraTrustedOrigins?: string[]): WalletTransportAdapter;
+/** Default 0xio adapter instance (no extra trusted origins). */
+declare const ZeroXIOAdapter: WalletTransportAdapter;
+
+/**
+ * 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.
+ */
+
+declare function createOctraProviderAdapter(): WalletTransportAdapter;
+/** Default RFC-O-1 adapter instance. */
+declare const OctraProviderAdapter: WalletTransportAdapter;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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 });
+ */
+declare function detectWalletAdapter(): WalletTransportAdapter | null;
+/** Returns all registered adapter instances. */
+declare function getAllAdapters(): WalletTransportAdapter[];
+
 /**
  * Network configuration for 0xio SDK
  */
 
-declare const NETWORKS: Record<string, NetworkInfo>;
+/**
+ * Immutable public copy of the built-in network table.
+ * Modifications to returned objects do not affect SDK-internal state.
+ */
+declare const NETWORKS: Readonly<Record<string, Readonly<NetworkInfo>>>;
 declare 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.
  */
 declare function getNetworkConfig(networkId?: string): NetworkInfo;
 /**
- * Get all available networks
+ * Get all available networks.
+ * Returns frozen copies — callers cannot mutate SDK-internal state.
  */
 declare function getAllNetworks(): NetworkInfo[];
 /**
- * Check if network ID is valid
+ * Check if network ID is valid (own property check, prevents prototype pollution).
  */
 declare function isValidNetworkId(networkId: string): boolean;
 
 /**
- * Default balance structure
+ * Default balance structure.
+ * Accepts a numeric total or undefined — never pass a Balance object here.
  */
 declare function createDefaultBalance(total?: number): Balance;
-/**
- * SDK Configuration constants
- */
 declare const SDK_CONFIG: {
-    readonly version: "2.6.0";
+    readonly version: "2.7.1";
     readonly defaultNetworkId: "mainnet";
     readonly communicationTimeout: 30000;
     readonly retryAttempts: 3;
     readonly retryDelay: 1000;
 };
-/**
- * Get default network configuration
- */
 declare function getDefaultNetwork(): NetworkInfo;
 
-/**
- * 0xio Wallet SDK - Utilities
- * Helper functions for validation, formatting, and common operations
- */
-
-/**
- * Validate wallet address for Octra blockchain
- */
 declare function isValidAddress(address: string): boolean;
 /**
- * Validate transaction amount
- */
-declare function isValidAmount(amount: number): boolean;
-/**
- * Validate transaction message
+ * Validate transaction amount.
+ * Accepts both number and string representations.
+ * String amounts avoid JS number precision loss for very large values.
  */
+declare function isValidAmount(amount: string | number): boolean;
 declare function isValidMessage(message: string): boolean;
-/**
- * Validate fee level
- */
 declare function isValidFeeLevel(feeLevel: number): boolean;
 /**
- * Format OCT amount for display
- */
-declare function formatOCT(amount: number, decimals?: number): string;
-/**
- * Format address for display (truncated)
+ * 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
  */
+declare function deriveOctraAddress(publicKeyBase64: string): Promise<string>;
+declare function formatOCT(amount: number | string, decimals?: number): string;
 declare function formatAddress(address: string, prefixLength?: number, suffixLength?: number): string;
-/**
- * Format timestamp for display
- */
 declare function formatTimestamp(timestamp: number): string;
-/**
- * Format transaction hash for display
- */
 declare function formatTxHash(hash: string, length?: number): string;
-/**
- * Convert OCT to micro OCT (for network transmission)
- */
 declare function toMicroOCT(amount: number): string;
-/**
- * Convert micro OCT to OCT (for display)
- */
 declare function fromMicroOCT(microAmount: string | number): number;
-/**
- * Create standardized error messages
- */
 declare function createErrorMessage(code: ErrorCode, context?: string): string;
-/**
- * Check if error is a specific type
- */
 declare function isErrorType(error: any, code: ErrorCode): boolean;
-/**
- * Create a promise that resolves after a delay
- */
 declare function delay(ms: number): Promise<void>;
-/**
- * Retry an async operation with exponential backoff
- */
-declare function retry<T>(operation: () => Promise<T>, maxRetries?: number, baseDelay?: number): Promise<T>;
-/**
- * Timeout wrapper for promises
- */
-declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutMessage?: string): Promise<T>;
-/**
- * Check if running in browser environment
- */
 declare function isBrowser(): boolean;
-/**
- * Check if browser supports required features
- */
 declare function checkBrowserSupport(): {
     supported: boolean;
     missingFeatures: string[];
 };
-/**
- * Generate mock data for development/testing
- */
 declare function generateMockData(): {
     address: string;
     balance: {
@@ -786,9 +779,6 @@ declare function generateMockData(): {
         isTestnet: boolean;
     };
 };
-/**
- * Create development logger
- */
 declare function createLogger(prefix: string, debug: boolean): {
     log: (...args: any[]) => void;
     warn: (...args: any[]) => void;
@@ -799,7 +789,7 @@ declare function createLogger(prefix: string, debug: boolean): {
     groupEnd: () => void;
 };
 
-declare const SDK_VERSION = "2.6.0";
+declare const SDK_VERSION = "2.7.1";
 declare const MIN_EXTENSION_VERSION = "2.0.1";
 declare const MIN_EXTENSION_VERSION_DEVNET = "2.2.1";
 declare const SUPPORTED_EXTENSION_VERSIONS = "^2.0.1";
@@ -808,13 +798,13 @@ declare function createZeroXIOWallet(config: {
     appDescription?: string;
     debug?: boolean;
     autoConnect?: boolean;
+    adapter?: WalletTransportAdapter;
 }): Promise<ZeroXIOWallet>;
-declare const createOctraWallet: typeof createZeroXIOWallet;
 declare function checkSDKCompatibility(): {
     compatible: boolean;
     issues: string[];
     recommendations: string[];
 };
 
-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 type { AccountChangedEvent, Balance, BalanceChangedEvent, ConnectEvent, ConnectOptions, ConnectionInfo, ContractCallData, ContractParam, ContractParams, ContractViewCallData, DisconnectEvent, ErrorEvent, ExtensionRequest, ExtensionResponse, NetworkChangedEvent, NetworkInfo, PendingPrivateTransfer, Permission, PrivateBalanceInfo, PrivateTransferData, SDKConfig, SignedTransaction, Transaction, TransactionConfirmedEvent, TransactionData, TransactionFinality, TransactionHistory, TransactionResult, WalletAddress, WalletEvent, WalletEventType };
+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 };
+export type { AccountChangedEvent, AdapterIncomingMessage, AdapterRequest, Balance, BalanceChangedEvent, ConnectEvent, ConnectOptions, ConnectionInfo, ContractCallData, ContractParam, ContractParams, ContractViewCallData, DisconnectEvent, ErrorEvent, ExtensionRequest, ExtensionResponse, NetworkChangedEvent, NetworkInfo, PendingPrivateTransfer, Permission, PrivateBalanceInfo, PrivateTransferData, SDKConfig, SignedTransaction, Transaction, TransactionConfirmedEvent, TransactionData, TransactionFinality, TransactionHistory, TransactionResult, WalletAddress, WalletEvent, WalletEventType, WalletTransportAdapter };