@0xio/sdk 2.7.0 → 2.7.1

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to the 0xio Wallet SDK will be documented in this file.
 
+## [2.7.1] - 2026-05-27
+
+### Security
+
+- **LOW (re-assessed from HIGH):** Removed `this.config.networkId` silent fallback in `connect()` and `getConnectionStatus()`. If neither `networkInfo` nor `networkId` can be resolved from the response, `connect()` now throws `NETWORK_ERROR` and `getConnectionStatus()` returns cached state. The current extension always returns valid `networkInfo`; this hardens against malformed responses from custom or future adapters.
+- **MED-1:** Added `SDKConfig.trustedParentOrigins` — when set, only listed origins (+ `tauri://`) are trusted as parent iframe bridges; implicit localhost trust is disabled. Omitting the field keeps existing dev-friendly behavior.
+- **LOW-2:** `validateNetworkInfo()` now rejects `http://` `rpcUrl` values on non-testnet networks. Testnet networks (`isTestnet: true`) and localhost are unaffected. Prevents a malicious bridge from injecting an insecure RPC endpoint.
+- **LOW-19:** `encryptBalance()`, `decryptBalance()`, `sendPrivateTransfer()`, and `callContract()` now throw `INVALID_AMOUNT` when a numeric amount cannot be represented exactly in micro-OCT (6 decimal places). Pass a string (e.g. `"0.300000"`) for exact control.
+- **LOW-28 (docs):** `ContractCallData.amount` JSDoc corrected — field is OCT, not micro-units. No behavior change.
+
+### Added
+
+- **`OctraProviderAdapter`** (`src/supports/octra-provider.ts`): RFC-O-1 compliant transport adapter that uses `window.octra.request()` instead of the postMessage bridge. Detects any wallet exposing `window.octra.isOctra === true`. Translates SDK method names to RFC-O-1 method names (`send_transaction` → `octra_sendTransaction`, etc.) and maps events back to SDK vocabulary. Registered second in the adapter registry — existing DApps using the postMessage bridge are unaffected.
+- **`listenForReady`** in `OctraProviderAdapter` now also listens for `octra#initialized` CustomEvent (dispatched by 0xio extension v2.4.3+) in addition to `octraWalletReady`, ensuring the provider is detected immediately on page load.
+
+### Fixed
+
+- Mainnet RPC URL in docs updated to `https://octra.network` (was stale `http://46.101.86.250:8080`)
+
+### Compatibility
+
+- No breaking changes — `ZeroXIOAdapter` (postMessage bridge) remains the default and takes priority when `window.wallet0xio` is present
+- Old DApps work unchanged; new DApps can opt into `OctraProviderAdapter` explicitly or via `detectWalletAdapter()`
+- Requires 0xio Wallet Extension v2.4.3+ for `octra#initialized` event; falls back to `octraWalletReady` on older versions
+
 ## [2.7.0] - 2026-05-16
 
 ### Security (post-audit remediation)

package/README.md

@@ -1,6 +1,6 @@
 # 0xio Wallet SDK
 
-**Version:** 2.7.0
+**Version:** 2.7.1
 
 Official TypeScript SDK for integrating DApps with 0xio Wallet on Octra Network.
 
@@ -272,7 +272,7 @@ console.log(devnet.isTestnet);        // true
 
 // Get mainnet config
 const mainnet = getNetworkConfig('mainnet');
-console.log(mainnet.rpcUrl);          // http://46.101.86.250:8080
+console.log(mainnet.rpcUrl);          // https://octra.network
 console.log(mainnet.supportsPrivacy); // true
 ```
 
@@ -339,6 +339,37 @@ const wallet = new ZeroXIOWallet({ appName: 'My DApp', adapter: ZeroXIOAdapter }
 
 See `DOCUMENTATION.md → Wallet Adapter System` for the full interface spec.
 
+## RFC-O-1 Provider Interface (`window.octra`)
+
+The 0xio extension exposes a standard `window.octra` provider per the RFC-O-1 spec in addition to the legacy `window.wallet0xio` bridge. The SDK supports both automatically.
+
+```typescript
+// window.octra shape (injected by the extension)
+window.octra.isOctra  // true — standard wallet detection
+window.octra.request({ method: 'octra_requestAccounts', params: [{}] })
+window.octra.on('accountsChanged', handler)
+window.octra.removeListener('accountsChanged', handler)
+```
+
+### How adapter priority works
+
+When the SDK initializes, `detectWalletAdapter()` runs detection in order:
+
+1. **`ZeroXIOAdapter`** — detected via `window.wallet0xio` / `window.ZeroXIOWallet` (postMessage bridge). Priority when the 0xio extension is installed — existing DApps are unaffected.
+2. **`OctraProviderAdapter`** — detected via `window.octra.isOctra === true`. Used when only the RFC-O-1 provider is present (third-party RFC-O-1 wallets, or DApps that explicitly request it).
+
+Old DApps using the postMessage bridge continue to work unchanged. New DApps can opt into `OctraProviderAdapter` directly:
+
+```typescript
+import { ZeroXIOWallet, OctraProviderAdapter } from '@0xio/sdk';
+
+// Explicitly use the RFC-O-1 window.octra provider
+const wallet = new ZeroXIOWallet({
+  appName: 'My DApp',
+  adapter: OctraProviderAdapter,
+});
+```
+
 ## Requirements
 
 - 0xio Wallet Extension v2.0.1 or higher (Mainnet Alpha)

package/dist/index.d.ts

@@ -187,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;
     /**
@@ -221,8 +221,16 @@ interface SignedTransaction {
 }
 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;
@@ -257,11 +265,14 @@ interface ConnectionInfo {
     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;
@@ -355,6 +366,12 @@ 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).
@@ -384,55 +401,20 @@ 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;
@@ -442,18 +424,8 @@ declare class ZeroXIOWallet extends EventEmitter {
     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
@@ -484,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.
@@ -518,9 +490,6 @@ 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
@@ -576,48 +545,21 @@ declare class ZeroXIOWallet extends EventEmitter {
     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.7.0
- * @license MIT
- */
-
 declare class ExtensionCommunicator extends EventEmitter {
     private pendingRequests;
     private isInitialized;
@@ -779,29 +721,15 @@ declare function isValidNetworkId(networkId: string): boolean;
  * 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.7.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.
@@ -809,13 +737,7 @@ declare function isValidAddress(address: string): boolean;
  * String amounts avoid JS number precision loss for very large values.
  */
 declare function isValidAmount(amount: string | number): boolean;
-/**
- * Validate transaction message
- */
 declare function isValidMessage(message: string): boolean;
-/**
- * Validate fee level
- */
 declare function isValidFeeLevel(feeLevel: number): boolean;
 /**
  * Derive the canonical Octra address from a base64-encoded Ed25519 public key.
@@ -823,56 +745,20 @@ declare function isValidFeeLevel(feeLevel: number): boolean;
  * Source of truth: ocho-push-server/src/index.ts#deriveAddressFromPubkey
  */
 declare function deriveOctraAddress(publicKeyBase64: string): Promise<string>;
-/**
- * Format OCT amount for display
- */
 declare function formatOCT(amount: number | string, decimals?: number): string;
-/**
- * Format address for display (truncated)
- */
 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>;
-/**
- * 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: {
@@ -893,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;
@@ -906,7 +789,7 @@ declare function createLogger(prefix: string, debug: boolean): {
     groupEnd: () => void;
 };
 
-declare const SDK_VERSION = "2.7.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";