@0xio/sdk 2.1.7 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to the 0xio Wallet SDK will be documented in this file.
 
+## [2.2.0] - 2026-03-08
+
+### Added
+- **Devnet Network Support**: Added full Octra Devnet configuration (`rpcUrl`, `explorerUrl`, `explorerAddressUrl`, `indexerUrl`) to the built-in `NETWORKS` registry.
+- **Expanded `NetworkInfo` Type**: Added `explorerAddressUrl`, `indexerUrl`, and `supportsPrivacy` fields to the `NetworkInfo` interface for richer network metadata.
+- **Privacy Flag**: Each network now exposes `supportsPrivacy: boolean` so DApps can detect FHE/encrypted balance support at the config level.
+- **Devnet Validation**: `isValidNetworkId()` now accepts `'devnet'` in addition to `'mainnet'` and `'custom'`.
+
+### Fixed
+- **Explorer URLs**: Mainnet `explorerUrl` and `explorerAddressUrl` now include trailing `/` to match all other 0xio platforms (extension, app, desktop).
+- **Mock Data**: `generateMockData()` now returns a `NetworkInfo` object with all new fields (`explorerAddressUrl`, `indexerUrl`, `supportsPrivacy`, correct URLs).
+
+### Network Configurations
+
+| Network | RPC | Explorer | Privacy | Testnet |
+|---------|-----|----------|---------|---------|
+| Mainnet Alpha | `https://octra.network` | `https://octrascan.io` | No | No |
+| Devnet | `http://165.227.225.79:8080` | `https://devnet.octrascan.io` | Yes | Yes |
+| Custom | User-defined | User-defined | No | No |
+
+---
+
+## [2.1.8] - 2026-02-13
+
+### Added
+- **Transaction Finality**: New `TransactionFinality` type (`'pending' | 'confirmed' | 'rejected'`) and `finality` field on `TransactionResult` and `Transaction` interfaces.
+- **RPC Error Codes**: 7 new `ErrorCode` entries for RPC-level transaction errors from `octra_submit` and `octra_submitBatch`:
+  - `MALFORMED_TRANSACTION` — Transaction is malformed
+  - `SELF_TRANSFER` — Cannot transfer to yourself
+  - `SENDER_NOT_FOUND` — Sender address not found
+  - `INVALID_SIGNATURE` — Invalid transaction signature
+  - `DUPLICATE_TRANSACTION` — Duplicate transaction detected
+  - `NONCE_TOO_FAR` — Transaction nonce is too far ahead
+  - `INTERNAL_ERROR` — Internal server error
+- **Error Messages**: All new error codes have corresponding human-readable messages in `createErrorMessage()`.
+
+### Fixed
+- Address validation now enforces `oct` prefix and 47-char length per Octra address spec.
+- Mock data generates correct `oct`-prefixed addresses instead of uppercase `OCT`.
+- `getBalance()` throws `ZeroXIOWalletError` instead of generic `Error` when address is missing.
+- Decimal conversion comment now references JSON-RPC spec (6 decimal places confirmed).
+- Stale REST endpoint comment (`/send-tx`, `/send-batch`) updated to JSON-RPC method names.
+- Mock data network config updated from testnet to mainnet (`octra.network`).
+
 ## [2.1.7] - 2026-01-27
 
 ### Added

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 0xio Team
+Copyright (c) 2026 0xio Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,14 +1,15 @@
 # 0xio Wallet SDK
 
-**Version:** 2.1.7
+**Version:** 2.2.0
 
 Official TypeScript SDK for integrating DApps with 0xio Wallet on Octra Network.
 
-## What's New in v2.1.7
+## What's New in v2.2.0
 
-- **Public Key Exposure**: `ConnectionInfo` and `ConnectEvent` now include `publicKey` (Base64 Ed25519 key)
-- **Address Verification**: DApps can verify `address == "oct" + Base58(SHA256(publicKey))`
-- **Improved API Auth**: Streamlined API key creation with direct public key verification
+- **Devnet Support**: Built-in Octra Devnet network configuration — DApps can now target devnet out of the box
+- **Expanded `NetworkInfo`**: New fields `explorerAddressUrl`, `indexerUrl`, and `supportsPrivacy` for richer network metadata
+- **Privacy Detection**: `supportsPrivacy` flag lets DApps check if a network supports FHE/encrypted balances
+- **Explorer URL Fix**: Mainnet explorer URLs now include trailing `/` for correct link generation
 
 ## Installation
 
@@ -84,7 +85,7 @@ interface Balance {
 ### Transactions
 
 #### `wallet.sendTransaction(txData): Promise<TransactionResult>`
-Send a transaction.
+Send a transaction. Returns result with transaction finality status.
 
 ```typescript
 interface TransactionData {
@@ -92,6 +93,14 @@ interface TransactionData {
   amount: number;    // Amount in OCT
   message?: string;  // Optional memo
 }
+
+interface TransactionResult {
+  txHash: string;
+  success: boolean;
+  finality?: 'pending' | 'confirmed' | 'rejected';
+  message?: string;
+  explorerUrl?: string;
+}
 ```
 
 ### Message Signing
@@ -130,15 +139,27 @@ wallet.on('networkChanged', (event) => console.log('Network:', event.newNetwork.
 import { ZeroXIOWalletError, ErrorCode } from '@0xio/sdk';
 
 try {
-  const signature = await wallet.signMessage('Hello');
+  const result = await wallet.sendTransaction({ to: 'oct1...', amount: 10 });
 } catch (error) {
   if (error instanceof ZeroXIOWalletError) {
     switch (error.code) {
       case ErrorCode.USER_REJECTED:
-        console.log('User rejected the signature request');
+        console.log('User rejected the request');
+        break;
+      case ErrorCode.INSUFFICIENT_BALANCE:
+        console.log('Not enough balance');
+        break;
+      case ErrorCode.INVALID_SIGNATURE:
+        console.log('Invalid transaction signature');
+        break;
+      case ErrorCode.DUPLICATE_TRANSACTION:
+        console.log('Transaction already submitted');
         break;
-      case ErrorCode.SIGNATURE_FAILED:
-        console.log('Signing failed:', error.message);
+      case ErrorCode.SELF_TRANSFER:
+        console.log('Cannot send to yourself');
+        break;
+      case ErrorCode.NONCE_TOO_FAR:
+        console.log('Transaction nonce too far ahead');
         break;
       case ErrorCode.WALLET_LOCKED:
         console.log('Please unlock your wallet');
@@ -148,6 +169,46 @@ try {
 }
 ```
 
+## Networks
+
+The SDK ships with built-in configurations for Octra networks:
+
+```typescript
+import { NETWORKS, getNetworkConfig } from '@0xio/sdk';
+
+// Get devnet config
+const devnet = getNetworkConfig('devnet');
+console.log(devnet.rpcUrl);           // http://165.227.225.79:8080
+console.log(devnet.supportsPrivacy);  // true
+console.log(devnet.isTestnet);        // true
+
+// Get mainnet config
+const mainnet = getNetworkConfig('mainnet');
+console.log(mainnet.rpcUrl);          // https://octra.network
+console.log(mainnet.supportsPrivacy); // false
+```
+
+| Network | Privacy (FHE) | Explorer |
+|---------|:---:|---|
+| Mainnet Alpha | No | [octrascan.io](https://octrascan.io) |
+| Devnet | Yes | [devnet.octrascan.io](https://devnet.octrascan.io) |
+
+### NetworkInfo Type
+
+```typescript
+interface NetworkInfo {
+  id: string;
+  name: string;
+  rpcUrl: string;
+  explorerUrl?: string;         // Transaction explorer base URL
+  explorerAddressUrl?: string;  // Address explorer base URL
+  indexerUrl?: string;          // Indexer/API base URL
+  supportsPrivacy: boolean;     // FHE encrypted balance support
+  color: string;                // Brand color hex
+  isTestnet: boolean;
+}
+```
+
 ## Requirements
 
 - 0xio Wallet Extension v2.0.1 or higher
@@ -159,4 +220,4 @@ See [DOCUMENTATION.md](DOCUMENTATION.md) for complete API reference.
 
 ## License
 
-MIT License. Copyright 2026 0xio Team.
+MIT License. Copyright 2026 0xio Labs.

package/dist/index.d.ts

@@ -17,6 +17,9 @@ interface NetworkInfo {
     readonly name: string;
     readonly rpcUrl: string;
     readonly explorerUrl?: string;
+    readonly explorerAddressUrl?: string;
+    readonly indexerUrl?: string;
+    readonly supportsPrivacy: boolean;
     readonly color: string;
     readonly isTestnet: boolean;
 }
@@ -38,9 +41,11 @@ interface SignedTransaction {
     readonly signature: string;
     readonly public_key: string;
 }
+type TransactionFinality = 'pending' | 'confirmed' | 'rejected';
 interface TransactionResult {
     readonly txHash: string;
     readonly success: boolean;
+    readonly finality?: TransactionFinality;
     readonly message?: string;
     readonly explorerUrl?: string;
 }
@@ -58,6 +63,7 @@ interface Transaction {
     readonly fee: number;
     readonly timestamp: number;
     readonly status: 'pending' | 'confirmed' | 'failed';
+    readonly finality?: TransactionFinality;
     readonly message?: string;
     readonly blockHeight?: number;
 }
@@ -125,7 +131,14 @@ declare enum ErrorCode {
     PERMISSION_DENIED = "PERMISSION_DENIED",
     WALLET_LOCKED = "WALLET_LOCKED",
     RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED",
-    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+    UNKNOWN_ERROR = "UNKNOWN_ERROR",
+    MALFORMED_TRANSACTION = "MALFORMED_TRANSACTION",
+    SELF_TRANSFER = "SELF_TRANSFER",
+    SENDER_NOT_FOUND = "SENDER_NOT_FOUND",
+    INVALID_SIGNATURE = "INVALID_SIGNATURE",
+    DUPLICATE_TRANSACTION = "DUPLICATE_TRANSACTION",
+    NONCE_TOO_FAR = "NONCE_TOO_FAR",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
 }
 declare class ZeroXIOWalletError extends Error {
     readonly code: ErrorCode;
@@ -361,7 +374,7 @@ declare class ZeroXIOWallet extends EventEmitter {
  * to ensure secure wallet interactions.
  *
  * @module communication
- * @version 1.2.0
+ * @version 2.2.0
  * @license MIT
  */
 
@@ -572,7 +585,7 @@ declare function createDefaultBalance(total?: number): Balance;
  * SDK Configuration constants
  */
 declare const SDK_CONFIG: {
-    readonly version: "2.1.2";
+    readonly version: "2.2.0";
     readonly defaultNetworkId: "mainnet";
     readonly communicationTimeout: 30000;
     readonly retryAttempts: 3;
@@ -678,6 +691,10 @@ declare function generateMockData(): {
         id: string;
         name: string;
         rpcUrl: string;
+        explorerUrl: string;
+        explorerAddressUrl: string;
+        indexerUrl: string;
+        supportsPrivacy: boolean;
         color: string;
         isTestnet: boolean;
     };
@@ -695,7 +712,7 @@ declare function createLogger(prefix: string, debug: boolean): {
     groupEnd: () => void;
 };
 
-declare const SDK_VERSION = "2.1.6";
+declare const SDK_VERSION = "2.2.0";
 declare const MIN_EXTENSION_VERSION = "2.0.1";
 declare const SUPPORTED_EXTENSION_VERSIONS = "^2.0.1";
 declare function createZeroXIOWallet(config: {
@@ -712,4 +729,4 @@ declare function checkSDKCompatibility(): {
 };
 
 export { DEFAULT_NETWORK_ID, ErrorCode, EventEmitter, ExtensionCommunicator, MIN_EXTENSION_VERSION, 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, DisconnectEvent, ErrorEvent, ExtensionRequest, ExtensionResponse, NetworkChangedEvent, NetworkInfo, PendingPrivateTransfer, Permission, PrivateBalanceInfo, PrivateTransferData, SDKConfig, SignedTransaction, Transaction, TransactionConfirmedEvent, TransactionData, TransactionHistory, TransactionResult, WalletAddress, WalletEvent, WalletEventType };
+export type { AccountChangedEvent, Balance, BalanceChangedEvent, ConnectEvent, ConnectOptions, ConnectionInfo, DisconnectEvent, ErrorEvent, ExtensionRequest, ExtensionResponse, NetworkChangedEvent, NetworkInfo, PendingPrivateTransfer, Permission, PrivateBalanceInfo, PrivateTransferData, SDKConfig, SignedTransaction, Transaction, TransactionConfirmedEvent, TransactionData, TransactionFinality, TransactionHistory, TransactionResult, WalletAddress, WalletEvent, WalletEventType };

package/dist/index.esm.js

@@ -119,6 +119,14 @@ var ErrorCode;
     ErrorCode["WALLET_LOCKED"] = "WALLET_LOCKED";
     ErrorCode["RATE_LIMIT_EXCEEDED"] = "RATE_LIMIT_EXCEEDED";
     ErrorCode["UNKNOWN_ERROR"] = "UNKNOWN_ERROR";
+    // RPC error types from octra_submit and octra_submitBatch
+    ErrorCode["MALFORMED_TRANSACTION"] = "MALFORMED_TRANSACTION";
+    ErrorCode["SELF_TRANSFER"] = "SELF_TRANSFER";
+    ErrorCode["SENDER_NOT_FOUND"] = "SENDER_NOT_FOUND";
+    ErrorCode["INVALID_SIGNATURE"] = "INVALID_SIGNATURE";
+    ErrorCode["DUPLICATE_TRANSACTION"] = "DUPLICATE_TRANSACTION";
+    ErrorCode["NONCE_TOO_FAR"] = "NONCE_TOO_FAR";
+    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
 })(ErrorCode || (ErrorCode = {}));
 class ZeroXIOWalletError extends Error {
     constructor(code, message, details) {
@@ -143,9 +151,8 @@ function isValidAddress(address) {
     if (!address || typeof address !== 'string') {
         return false;
     }
-    // Octra addresses should match the expected format
-    // This is a basic validation - adjust based on actual Octra address format
-    const addressRegex = /^[A-Za-z0-9]{20,64}$/;
+    // Octra addresses use "oct" prefix followed by alphanumeric characters (47 chars total)
+    const addressRegex = /^oct[A-Za-z0-9]{44}$/;
     return addressRegex.test(address);
 }
 /**
@@ -164,7 +171,7 @@ function isValidNetworkId(networkId) {
     if (!networkId || typeof networkId !== 'string') {
         return false;
     }
-    const validNetworks = ['mainnet', 'testnet', 'devnet'];
+    const validNetworks = ['mainnet', 'devnet', 'custom'];
     return validNetworks.includes(networkId.toLowerCase());
 }
 /**
@@ -244,7 +251,7 @@ function toMicroOCT(amount) {
     if (!isValidAmount(amount)) {
         throw new ZeroXIOWalletError(ErrorCode.INVALID_AMOUNT, 'Invalid amount for conversion');
     }
-    // Assuming OCT has 6 decimal places like many cryptocurrencies
+    // OCT uses 6 decimal places (1 OCT = 1,000,000 raw units per JSON-RPC spec)
     const microOCT = Math.round(amount * 1000000);
     return microOCT.toString();
 }
@@ -278,7 +285,14 @@ function createErrorMessage(code, context) {
         [ErrorCode.PERMISSION_DENIED]: 'Permission denied for this operation',
         [ErrorCode.WALLET_LOCKED]: 'Wallet is locked, please unlock first',
         [ErrorCode.RATE_LIMIT_EXCEEDED]: 'Rate limit exceeded, please try again later',
-        [ErrorCode.UNKNOWN_ERROR]: 'An unknown error occurred'
+        [ErrorCode.UNKNOWN_ERROR]: 'An unknown error occurred',
+        [ErrorCode.MALFORMED_TRANSACTION]: 'Transaction is malformed',
+        [ErrorCode.SELF_TRANSFER]: 'Cannot transfer to yourself',
+        [ErrorCode.SENDER_NOT_FOUND]: 'Sender address not found',
+        [ErrorCode.INVALID_SIGNATURE]: 'Invalid transaction signature',
+        [ErrorCode.DUPLICATE_TRANSACTION]: 'Duplicate transaction detected',
+        [ErrorCode.NONCE_TOO_FAR]: 'Transaction nonce is too far ahead',
+        [ErrorCode.INTERNAL_ERROR]: 'Internal server error'
     };
     const baseMessage = baseMessages[code] || 'Unknown error';
     return context ? `${baseMessage}: ${context}` : baseMessage;
@@ -371,7 +385,7 @@ function checkBrowserSupport() {
  */
 function generateMockData() {
     return {
-        address: 'OCT' + Math.random().toString(36).substr(2, 20).toUpperCase(),
+        address: 'oct' + Math.random().toString(36).substring(2, 22) + Math.random().toString(36).substring(2, 26),
         balance: {
             public: Math.floor(Math.random() * 10000),
             private: Math.floor(Math.random() * 1000),
@@ -379,11 +393,15 @@ function generateMockData() {
             currency: 'OCT'
         },
         networkInfo: {
-            id: 'testnet',
-            name: 'Octra Testnet',
-            rpcUrl: 'https://testnet.octra.network',
+            id: 'mainnet',
+            name: 'Octra Mainnet Alpha',
+            rpcUrl: 'https://octra.network',
+            explorerUrl: 'https://octrascan.io/transactions/',
+            explorerAddressUrl: 'https://octrascan.io/addresses/',
+            indexerUrl: 'https://network.octrascan.com',
+            supportsPrivacy: false,
             color: '#f59e0b',
-            isTestnet: true
+            isTestnet: false
         }
     };
 }
@@ -446,7 +464,7 @@ function createLogger(prefix, debug) {
  * to ensure secure wallet interactions.
  *
  * @module communication
- * @version 1.2.0
+ * @version 2.2.0
  * @license MIT
  */
 /**
@@ -836,17 +854,13 @@ class ExtensionCommunicator extends EventEmitter {
             return false;
         // Check for extension-injected indicators
         const win = window;
-        // Look for common extension indicators
+        // Look for extension-injected globals (matches injected.ts)
         return !!(win.wallet0xio ||
             win.ZeroXIOWallet ||
-            win.__0XIO_EXTENSION__ ||
-            win.__OCTRA_EXTENSION__ ||
             win.octraWallet ||
             (win.chrome?.runtime?.id) ||
-            document.querySelector('meta[name="0xio-extension"]') ||
-            document.querySelector('meta[name="octra-extension"]') ||
-            document.querySelector('[data-0xio-extension]') ||
-            document.querySelector('[data-octra-extension]'));
+            document.querySelector('meta[name="0xio-dapp"]') ||
+            document.querySelector('[data-0xio-sdk-bridge]'));
     }
     /**
      * Wait for extension to become available
@@ -911,11 +925,11 @@ class ExtensionCommunicator extends EventEmitter {
             hasPostMessage: typeof window.postMessage === 'function',
             origin: window.location?.origin,
             extensionDetection: {
-                hasOctraExtension: !!win.__OCTRA_EXTENSION__,
-                hasZeroXIOWallet: !!win.octraWallet,
+                hasWallet0xio: !!win.wallet0xio,
+                hasZeroXIOWallet: !!win.ZeroXIOWallet,
+                hasOctraWallet: !!win.octraWallet,
                 hasChromeRuntimeId: !!(win.chrome?.runtime?.id),
-                hasMetaTag: !!document.querySelector('meta[name=\"octra-extension\"]'),
-                hasDataAttribute: !!document.querySelector('[data-octra-extension]')
+                hasSdkBridge: !!document.querySelector('[data-0xio-sdk-bridge]')
             }
         };
     }
@@ -972,17 +986,34 @@ const NETWORKS = {
         id: 'mainnet',
         name: 'Octra Mainnet Alpha',
         rpcUrl: 'https://octra.network',
-        explorerUrl: 'https://octrascan.io/',
-        color: '#6366f1',
+        explorerUrl: 'https://octrascan.io/transactions/',
+        explorerAddressUrl: 'https://octrascan.io/addresses/',
+        indexerUrl: 'https://network.octrascan.com',
+        supportsPrivacy: false,
+        color: '#f59e0b',
         isTestnet: false
     },
+    'devnet': {
+        id: 'devnet',
+        name: 'Octra Devnet',
+        rpcUrl: 'http://165.227.225.79:8080',
+        explorerUrl: 'https://devnet.octrascan.io/tx.html?hash=',
+        explorerAddressUrl: 'https://devnet.octrascan.io/address.html?addr=',
+        indexerUrl: 'https://devnet.octrascan.io',
+        supportsPrivacy: true,
+        color: '#8b5cf6',
+        isTestnet: true
+    },
     'custom': {
         id: 'custom',
         name: 'Custom Network',
         rpcUrl: '',
         explorerUrl: '',
+        explorerAddressUrl: '',
+        indexerUrl: '',
+        supportsPrivacy: false,
         color: '#64748b',
-        isTestnet: false // User configurable - can be mainnet or testnet
+        isTestnet: false
     }
 };
 const DEFAULT_NETWORK_ID = 'mainnet';
@@ -1021,7 +1052,7 @@ function createDefaultBalance(total = 0) {
  * SDK Configuration constants
  */
 const SDK_CONFIG = {
-    version: '2.1.2',
+    version: '2.2.0',
     defaultNetworkId: DEFAULT_NETWORK_ID,
     communicationTimeout: 30000, // 30 seconds
     retryAttempts: 3,
@@ -1232,7 +1263,7 @@ class ZeroXIOWallet extends EventEmitter {
         try {
             const address = this.getAddress();
             if (!address) {
-                throw new Error('No address found');
+                throw new ZeroXIOWalletError(ErrorCode.INVALID_ADDRESS, 'No address found');
             }
             // Fetch balance from extension (bypasses CORS, has access to private balance)
             let publicBalance = 0;
@@ -1647,7 +1678,7 @@ var wallet = /*#__PURE__*/Object.freeze({
  */
 // Main exports
 // Version information
-const SDK_VERSION = '2.1.6';
+const SDK_VERSION = '2.2.0';
 const MIN_EXTENSION_VERSION = '2.0.1';
 const SUPPORTED_EXTENSION_VERSIONS = '^2.0.1'; // Supports all versions >= 2.0.1
 // Quick setup function for simple use cases