@0xio/sdk 2.6.0 → 2.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,3 +1,140 @@
1
+ /**
2
+ * 0xio SDK — Wallet Transport Adapter Interface
3
+ *
4
+ * Implement WalletTransportAdapter to add support for a new wallet without
5
+ * touching any core SDK code. Drop the adapter file in src/supports/ and
6
+ * pass it to ZeroXIOWallet via SDKConfig.adapter.
7
+ *
8
+ * @example
9
+ * ```typescript
10
+ * import { ZeroXIOWallet } from '@0xio/sdk';
11
+ * import { QubitzAdapter } from '@0xio/sdk/supports/qubitz';
12
+ *
13
+ * const wallet = new ZeroXIOWallet({
14
+ * appName: 'My DApp',
15
+ * adapter: QubitzAdapter,
16
+ * });
17
+ * ```
18
+ */
19
+ /**
20
+ * Outbound request — the SDK passes this to adapter.postRequest() for every
21
+ * outbound wallet call. Adapters translate this into their wallet-specific wire format.
22
+ */
23
+ interface AdapterRequest {
24
+ /** Unique request ID (UUID). Used to correlate the response. */
25
+ id: string;
26
+ /** Method name, e.g. 'connect', 'sendTransaction', 'signMessage' */
27
+ method: string;
28
+ /** Method parameters */
29
+ params: unknown;
30
+ /** Unix timestamp (ms) when the request was created */
31
+ timestamp: number;
32
+ }
33
+ /**
34
+ * Normalized inbound message from a wallet.
35
+ * Adapters translate their wallet-specific wire format into this structure
36
+ * and pass it to the handler registered via listen().
37
+ *
38
+ * A message is either a response (requestId set) or a push event (eventType set).
39
+ */
40
+ interface AdapterIncomingMessage {
41
+ /** Must match the id from the outbound AdapterRequest */
42
+ requestId?: string;
43
+ /** Whether the request succeeded. Required when requestId is set. */
44
+ success?: boolean;
45
+ /** Response payload on success */
46
+ data?: unknown;
47
+ /** Structured error on failure */
48
+ error?: {
49
+ code: string;
50
+ message: string;
51
+ details?: unknown;
52
+ };
53
+ /** Event type, e.g. 'connect', 'disconnect', 'accountChanged', 'balanceChanged' */
54
+ eventType?: string;
55
+ /** Event payload */
56
+ eventData?: unknown;
57
+ }
58
+ /**
59
+ * Wallet transport adapter.
60
+ *
61
+ * Encapsulates the entire wallet-specific communication layer:
62
+ * - How to detect if the wallet is installed
63
+ * - How to send requests (postRequest)
64
+ * - How to receive responses and events (listen)
65
+ *
66
+ * Everything else — request lifecycle, timeouts, retries, rate limiting,
67
+ * event routing — is handled by the SDK core and does not change per wallet.
68
+ *
69
+ * @example Minimal adapter for a hypothetical wallet
70
+ * ```typescript
71
+ * export const MyWalletAdapter: WalletTransportAdapter = {
72
+ * name: 'mywallet',
73
+ * displayName: 'My Wallet',
74
+ * detect: () => !!(window as any).myWallet,
75
+ * postRequest: (req) =>
76
+ * window.postMessage({ source: 'mywallet-request', ...req }, location.origin),
77
+ * listen: (handler) => {
78
+ * const fn = (e: MessageEvent) => {
79
+ * if (e.data?.source !== 'mywallet-response') return;
80
+ * handler({ requestId: e.data.id, success: e.data.ok, data: e.data.result });
81
+ * };
82
+ * window.addEventListener('message', fn);
83
+ * return () => window.removeEventListener('message', fn);
84
+ * },
85
+ * };
86
+ * ```
87
+ */
88
+ interface WalletTransportAdapter {
89
+ /**
90
+ * Machine-readable wallet identifier. Used in logs and adapter selection.
91
+ * Examples: '0xio', 'qubitz', 'fhex'
92
+ */
93
+ readonly name: string;
94
+ /**
95
+ * Human-readable wallet name shown in error messages.
96
+ * Examples: '0xio Wallet', 'Qubitz Wallet', 'FHEX Wallet'
97
+ */
98
+ readonly displayName: string;
99
+ /**
100
+ * Returns true when this wallet's extension / injected provider is present
101
+ * in the current page context. Called periodically by the SDK to check availability.
102
+ */
103
+ detect(): boolean;
104
+ /**
105
+ * Send a request to the wallet.
106
+ * Called once per outbound request — translate AdapterRequest into your
107
+ * wallet's wire format and post it (window.postMessage, direct API call, etc.).
108
+ */
109
+ postRequest(request: AdapterRequest): void;
110
+ /**
111
+ * Optional: send the same request to a trusted parent frame (iframe/desktop bridge).
112
+ * Only implement this if your wallet supports an embedded iframe bridge mode.
113
+ * The SDK calls this when window.parent !== window and a trusted parent origin exists.
114
+ */
115
+ postRequestToParent?(request: AdapterRequest, parentOrigin: string): void;
116
+ /**
117
+ * Set up response and event listening.
118
+ * The SDK calls this once during initialization. Normalise all incoming wallet
119
+ * messages into AdapterIncomingMessage and pass them to handler.
120
+ *
121
+ * @param handler Callback for responses and push events
122
+ * @param options SDK-level options, e.g. additional trusted parent origins
123
+ * @returns A teardown function — the SDK calls it on cleanup()
124
+ */
125
+ listen(handler: (msg: AdapterIncomingMessage) => void, options?: {
126
+ trustedParentOrigins?: string[];
127
+ }): () => void;
128
+ /**
129
+ * Optional: register wallet-ready event listeners (e.g. 'myWalletReady' CustomEvent).
130
+ * Called once during SDK init. When the wallet signals it is ready, call onReady().
131
+ * Returns a cleanup function.
132
+ *
133
+ * If not implemented, the SDK falls back to polling detect() every 2 seconds.
134
+ */
135
+ listenForReady?(onReady: () => void): () => void;
136
+ }
137
+
1
138
  /**
2
139
  * 0xio Wallet SDK - Type Definitions
3
140
  * Comprehensive type system for 0xio wallet integration with Octra Network
@@ -25,7 +162,8 @@ interface NetworkInfo {
25
162
  }
26
163
  interface TransactionData {
27
164
  readonly to: string;
28
- readonly amount: number;
165
+ /** Amount in OCT. Accepts string or number — use string for amounts above 9 billion OCT to avoid JS number precision loss. */
166
+ readonly amount: string | number;
29
167
  readonly message?: string;
30
168
  readonly feeLevel?: 1 | 3;
31
169
  readonly isPrivate?: boolean;
@@ -81,7 +219,7 @@ interface SignedTransaction {
81
219
  readonly signature: string;
82
220
  readonly public_key: string;
83
221
  }
84
- type TransactionFinality = 'pending' | 'confirmed' | 'rejected';
222
+ type TransactionFinality = 'pending' | 'confirmed' | 'rejected' | 'dropped';
85
223
  interface TransactionResult {
86
224
  readonly txHash: string;
87
225
  readonly success: boolean;
@@ -99,10 +237,12 @@ interface Transaction {
99
237
  readonly hash: string;
100
238
  readonly from: string;
101
239
  readonly to: string;
102
- readonly amount: number;
103
- readonly fee: number;
240
+ /** Amount in OCT as returned by the node (may be string or number depending on extension version). */
241
+ readonly amount: string | number;
242
+ /** Fee in OCT as returned by the node (may be string or number depending on extension version). */
243
+ readonly fee: string | number;
104
244
  readonly timestamp: number;
105
- readonly status: 'pending' | 'confirmed' | 'failed';
245
+ readonly status: 'pending' | 'confirmed' | 'failed' | 'dropped';
106
246
  readonly finality?: TransactionFinality;
107
247
  readonly message?: string;
108
248
  readonly blockHeight?: number;
@@ -114,6 +254,7 @@ interface ConnectionInfo {
114
254
  balance?: Balance;
115
255
  networkInfo?: NetworkInfo;
116
256
  connectedAt?: number;
257
+ permissions?: Permission[];
117
258
  }
118
259
  interface ConnectOptions {
119
260
  readonly requestPermissions?: Permission[];
@@ -128,7 +269,7 @@ interface WalletEvent<T = any> {
128
269
  }
129
270
  interface ConnectEvent {
130
271
  readonly address: string;
131
- readonly publicKey?: string;
272
+ readonly publicKey: string | undefined;
132
273
  readonly balance: Balance;
133
274
  readonly networkInfo: NetworkInfo;
134
275
  readonly permissions: Permission[];
@@ -140,6 +281,7 @@ interface AccountChangedEvent {
140
281
  readonly previousAddress?: string;
141
282
  readonly newAddress: string;
142
283
  readonly balance: Balance;
284
+ readonly publicKey?: string;
143
285
  }
144
286
  interface BalanceChangedEvent {
145
287
  readonly address: string;
@@ -192,7 +334,8 @@ interface PrivateBalanceInfo {
192
334
  }
193
335
  interface PrivateTransferData {
194
336
  readonly to: string;
195
- readonly amount: number;
337
+ /** Amount in OCT. Accepts string or number — use string for amounts above 9 billion OCT to avoid JS number precision loss. */
338
+ readonly amount: string | number;
196
339
  readonly message?: string;
197
340
  }
198
341
  interface PendingPrivateTransfer {
@@ -212,6 +355,16 @@ interface SDKConfig {
212
355
  readonly requiredPermissions?: Permission[];
213
356
  readonly networkId?: string;
214
357
  readonly debug?: boolean;
358
+ /**
359
+ * Custom wallet transport adapter.
360
+ * Defaults to ZeroXIOAdapter (0xio extension postMessage protocol).
361
+ * Pass an adapter from src/supports/ to target a different wallet.
362
+ *
363
+ * @example
364
+ * import { QubitzAdapter } from '@0xio/sdk/supports/qubitz';
365
+ * new ZeroXIOWallet({ appName: 'My DApp', adapter: QubitzAdapter });
366
+ */
367
+ readonly adapter?: WalletTransportAdapter;
215
368
  }
216
369
  interface ExtensionRequest {
217
370
  readonly id: string;
@@ -285,6 +438,8 @@ declare class ZeroXIOWallet extends EventEmitter {
285
438
  private config;
286
439
  private connectionInfo;
287
440
  private isInitialized;
441
+ private _initPromise;
442
+ private _sessionVersion;
288
443
  private logger;
289
444
  constructor(config: SDKConfig);
290
445
  /**
@@ -370,11 +525,11 @@ declare class ZeroXIOWallet extends EventEmitter {
370
525
  /**
371
526
  * Encrypt public balance to private
372
527
  */
373
- encryptBalance(amount: number): Promise<boolean>;
528
+ encryptBalance(amount: string | number): Promise<TransactionResult>;
374
529
  /**
375
530
  * Decrypt private balance to public
376
531
  */
377
- decryptBalance(amount: number): Promise<boolean>;
532
+ decryptBalance(amount: string | number): Promise<TransactionResult>;
378
533
  /**
379
534
  * Send a private (encrypted) transfer to another address.
380
535
  * The extension builds the PVAC ciphertext subtraction + range proof + zero proof,
@@ -408,6 +563,16 @@ declare class ZeroXIOWallet extends EventEmitter {
408
563
  * ```
409
564
  */
410
565
  signMessage(message: string): Promise<string>;
566
+ /**
567
+ * Sign a domain-separated authentication message.
568
+ * Unlike `signMessage()`, this prepends a standard header that binds the signature
569
+ * to the calling service and a one-time nonce, preventing cross-service replay attacks.
570
+ *
571
+ * @param service - Identifies the relying service (e.g. 'MyDApp' or 'api.mydapp.com')
572
+ * @param nonce - Unique one-time value — use a server-generated UUID or challenge
573
+ * @returns Promise resolving to the base64-encoded Ed25519 signature
574
+ */
575
+ signAuthMessage(service: string, nonce: string): Promise<string>;
411
576
  private ensureInitialized;
412
577
  private ensureConnected;
413
578
  private setupExtensionEventListeners;
@@ -449,197 +614,68 @@ declare class ZeroXIOWallet extends EventEmitter {
449
614
  * to ensure secure wallet interactions.
450
615
  *
451
616
  * @module communication
452
- * @version 2.6.0
617
+ * @version 2.7.0
453
618
  * @license MIT
454
619
  */
455
620
 
456
- /**
457
- * ExtensionCommunicator - Manages communication with the 0xio Wallet browser extension
458
- *
459
- * @class
460
- * @extends EventEmitter
461
- *
462
- * @description
463
- * Handles all communication between the SDK and wallet extension including:
464
- * - Request/response message passing with origin validation
465
- * - Rate limiting to prevent DoS attacks
466
- * - Automatic retry logic with exponential backoff
467
- * - Extension detection and availability monitoring
468
- * - Cryptographically secure request ID generation
469
- *
470
- * @example
471
- * ```typescript
472
- * const communicator = new ExtensionCommunicator(true); // debug mode
473
- * await communicator.initialize();
474
- *
475
- * const response = await communicator.sendRequest('get_balance', {});
476
- * console.log(response);
477
- * ```
478
- */
479
621
  declare class ExtensionCommunicator extends EventEmitter {
480
- /** Legacy request counter (deprecated, kept for fallback) */
481
- private requestId;
482
- /** Map of pending requests awaiting responses */
483
622
  private pendingRequests;
484
- /** Initialization state flag */
485
623
  private isInitialized;
486
- /** Logger instance for debugging */
487
624
  private logger;
488
- /** Interval handle for periodic extension detection */
489
625
  private extensionDetectionInterval;
490
- /** Current extension availability state */
491
626
  private isExtensionAvailableState;
492
- /** Message listener reference for cleanup */
493
- private messageListener;
494
- /** Trusted parent origins for iframe communication */
495
627
  private trustedOrigins;
496
- /** Parent origin learned from walletReady signal */
497
628
  private _parentOrigin;
498
- /** Maximum number of concurrent pending requests */
499
- private readonly MAX_CONCURRENT_REQUESTS;
500
- /** Time window for rate limiting (milliseconds) */
501
- private readonly RATE_LIMIT_WINDOW;
502
- /** Maximum requests allowed per time window */
503
- private readonly MAX_REQUESTS_PER_WINDOW;
504
- /** Timestamps of recent requests for rate limiting */
505
- private requestTimestamps;
629
+ /** Pluggable transport defaults to the 0xio postMessage protocol. */
630
+ private adapter;
631
+ /** Teardown fn returned by adapter.listen() */
632
+ private _adapterTeardown;
633
+ /** Teardown fn returned by adapter.listenForReady() */
634
+ private _adapterReadyTeardown;
506
635
  /**
507
- * Creates a new ExtensionCommunicator instance
508
- *
509
- * @param {boolean} debug - Enable debug logging
636
+ * Set when a trusted walletReady has been received from window.parent.
637
+ * The polling fallback must NOT clear this flag.
510
638
  */
511
- constructor(debug?: boolean, trustedOrigins?: string[]);
639
+ private _parentTrusted;
640
+ /** walletReady postMessage listener stored for cleanup */
641
+ private _walletReadyMessageListener;
512
642
  /**
513
- * Add trusted origins for iframe/bridge communication
514
- * Call this before connecting if your dApp runs inside a trusted frame
643
+ * In-flight interactive request lock.
644
+ * Methods that open approval popups are serialized only one at a time.
515
645
  */
646
+ private _interactiveInFlight;
647
+ private readonly MAX_CONCURRENT_REQUESTS;
648
+ private readonly RATE_LIMIT_WINDOW;
649
+ private readonly MAX_REQUESTS_PER_WINDOW;
650
+ private requestTimestamps;
651
+ constructor(debug?: boolean, trustedOrigins?: string[], adapter?: WalletTransportAdapter);
516
652
  setTrustedOrigins(origins: string[]): void;
517
- /**
518
- * Initialize communication with the wallet extension
519
- *
520
- * @description
521
- * Performs initial setup and verification:
522
- * 1. Waits for extension to become available
523
- * 2. Sends ping to verify communication
524
- * 3. Establishes message handlers
525
- *
526
- * Must be called before any other methods.
527
- *
528
- * @returns {Promise<boolean>} True if initialization succeeded, false otherwise
529
- * @throws {ZeroXIOWalletError} If extension is not available after timeout
530
- *
531
- * @example
532
- * ```typescript
533
- * const success = await communicator.initialize();
534
- * if (!success) {
535
- * console.error('Failed to initialize wallet connection');
536
- * }
537
- * ```
538
- */
539
653
  initialize(): Promise<boolean>;
540
- /**
541
- * Check if extension is available
542
- */
543
654
  isExtensionAvailable(): boolean;
544
655
  private static readonly NO_RETRY_METHODS;
545
- /**
546
- * Send request to extension
547
- */
656
+ private static readonly INTERACTIVE_METHODS;
548
657
  sendRequest<T = any>(method: string, params?: any, timeout?: number): Promise<T>;
549
- /**
550
- * Send request to extension with automatic retry logic
551
- */
552
658
  sendRequestWithRetry<T = any>(method: string, params?: any, maxRetries?: number, timeout?: number): Promise<T>;
553
- /**
554
- * Setup message listener for responses from extension
555
- */
556
659
  private setupMessageListener;
557
- /**
558
- * Handle extension event
559
- */
660
+ private static readonly VALID_EVENT_TYPES;
560
661
  private handleExtensionEvent;
561
- /**
562
- * Handle response from extension
563
- */
564
662
  private handleExtensionResponse;
565
- /**
566
- * Post message to extension via content script
567
- */
568
663
  private postMessageToExtension;
569
- /**
570
- * Check if we're in a context that can communicate with extension
571
- */
572
664
  private hasExtensionContext;
573
- /**
574
- * Check and enforce rate limits to prevent denial-of-service attacks
575
- *
576
- * @private
577
- * @throws {ZeroXIOWalletError} RATE_LIMIT_EXCEEDED if limits are exceeded
578
- *
579
- * @description
580
- * Implements two-tier rate limiting:
581
- * 1. Concurrent requests: Maximum 50 pending requests at once
582
- * 2. Request frequency: Maximum 20 requests per second
583
- *
584
- * Rate limiting protects both the SDK and extension from:
585
- * - Accidental infinite loops in dApp code
586
- * - Malicious DoS attacks
587
- * - Resource exhaustion
588
- *
589
- * @security Critical security function - enforces resource limits
590
- */
591
665
  private checkRateLimit;
592
- /**
593
- * Generate cryptographically secure unique request ID
594
- *
595
- * @private
596
- * @returns {string} A unique, unpredictable request identifier
597
- *
598
- * @description
599
- * Uses Web Crypto API for secure random ID generation:
600
- * 1. Primary: crypto.randomUUID() - UUID v4 format
601
- * 2. Fallback: crypto.getRandomValues() - 128-bit random hex
602
- * 3. Last resort: timestamp + counter (logs warning)
603
- *
604
- * Security importance:
605
- * - Prevents request ID prediction attacks
606
- * - Mitigates replay attacks
607
- * - Makes session hijacking more difficult
608
- *
609
- * @security Critical - IDs must be cryptographically unpredictable
610
- */
611
666
  private generateRequestId;
612
- /**
613
- * Start continuous extension detection
614
- */
615
667
  private startExtensionDetection;
616
- /**
617
- * Check if extension is currently available
618
- */
619
668
  private checkExtensionAvailability;
620
- /**
621
- * Detect extension signals/indicators
622
- */
623
669
  private detectExtensionSignals;
624
- /**
625
- * Wait for extension to become available
626
- */
627
670
  private waitForExtensionAvailability;
628
- /**
629
- * Get browser diagnostics for error reporting
630
- */
631
671
  private getBrowserDiagnostics;
632
- /**
633
- * Get extension state diagnostics
634
- */
635
672
  private getExtensionDiagnostics;
636
673
  /**
637
- * Cleanup pending requests
674
+ * Clean up SDK resources.
675
+ * After cleanup() the instance is terminal — do not call initialize() again.
676
+ * Construct a new instance instead.
638
677
  */
639
678
  cleanup(): void;
640
- /**
641
- * Get debug information
642
- */
643
679
  getDebugInfo(): {
644
680
  initialized: boolean;
645
681
  available: boolean;
@@ -649,34 +685,105 @@ declare class ExtensionCommunicator extends EventEmitter {
649
685
  };
650
686
  }
651
687
 
688
+ /**
689
+ * 0xio Wallet transport adapter.
690
+ *
691
+ * Implements the postMessage protocol used by the 0xio browser extension (>= v2.4.0).
692
+ *
693
+ * Outbound wire format:
694
+ * window.postMessage({ source: '0xio-sdk-request', request: { id, method, params, timestamp } }, origin)
695
+ *
696
+ * Inbound wire format:
697
+ * window.postMessage({ source: '0xio-sdk-bridge', response: { id, success, data, error }, sessionNonce })
698
+ * window.postMessage({ source: '0xio-sdk-bridge', event: { type, data } })
699
+ *
700
+ * H-2: Session nonce validation — injected.ts broadcasts the nonce received from the
701
+ * isolated content script. Once set, any '0xio-sdk-bridge' response with a missing or
702
+ * mismatched nonce is rejected, preventing response injection by malicious page scripts.
703
+ */
704
+
705
+ /**
706
+ * Creates a 0xio adapter. The factory accepts optional extra trusted parent origins
707
+ * so the communicator can forward its own trustedOrigins setting to origin validation.
708
+ */
709
+ declare function createZeroXIOAdapter(extraTrustedOrigins?: string[]): WalletTransportAdapter;
710
+ /** Default 0xio adapter instance (no extra trusted origins). */
711
+ declare const ZeroXIOAdapter: WalletTransportAdapter;
712
+
713
+ /**
714
+ * RFC-O-1 OctraProvider transport adapter.
715
+ *
716
+ * Targets any wallet that exposes `window.octra` per the RFC-O-1 specification:
717
+ * window.octra.isOctra === true
718
+ * window.octra.request({ method, params }) → Promise<unknown>
719
+ * window.octra.on(event, listener) / removeListener(event, listener)
720
+ *
721
+ * This adapter translates the SDK's internal method names into RFC-O-1 method
722
+ * names and maps events back to the SDK event vocabulary.
723
+ *
724
+ * Non-standard SDK methods (ping, register_dapp, getTransactionHistory, etc.)
725
+ * are passed through as-is; the wallet's request() handles or rejects them.
726
+ */
727
+
728
+ declare function createOctraProviderAdapter(): WalletTransportAdapter;
729
+ /** Default RFC-O-1 adapter instance. */
730
+ declare const OctraProviderAdapter: WalletTransportAdapter;
731
+
732
+ /**
733
+ * 0xio SDK — Wallet Adapter Registry
734
+ *
735
+ * Add new wallet adapters here. Detection order determines which wallet takes
736
+ * priority when multiple wallets are installed at the same time.
737
+ */
738
+
739
+ /**
740
+ * Auto-detects the first available wallet in the current page.
741
+ * Returns null if no supported wallet is found.
742
+ *
743
+ * @example
744
+ * const adapter = detectWalletAdapter();
745
+ * if (!adapter) throw new Error('No supported wallet found');
746
+ * const wallet = new ZeroXIOWallet({ appName: 'My DApp', adapter });
747
+ */
748
+ declare function detectWalletAdapter(): WalletTransportAdapter | null;
749
+ /** Returns all registered adapter instances. */
750
+ declare function getAllAdapters(): WalletTransportAdapter[];
751
+
652
752
  /**
653
753
  * Network configuration for 0xio SDK
654
754
  */
655
755
 
656
- declare const NETWORKS: Record<string, NetworkInfo>;
756
+ /**
757
+ * Immutable public copy of the built-in network table.
758
+ * Modifications to returned objects do not affect SDK-internal state.
759
+ */
760
+ declare const NETWORKS: Readonly<Record<string, Readonly<NetworkInfo>>>;
657
761
  declare const DEFAULT_NETWORK_ID = "mainnet";
658
762
  /**
659
- * Get network configuration by ID
763
+ * Get network configuration by ID.
764
+ * Returns a frozen copy — callers cannot mutate SDK-internal state.
660
765
  */
661
766
  declare function getNetworkConfig(networkId?: string): NetworkInfo;
662
767
  /**
663
- * Get all available networks
768
+ * Get all available networks.
769
+ * Returns frozen copies — callers cannot mutate SDK-internal state.
664
770
  */
665
771
  declare function getAllNetworks(): NetworkInfo[];
666
772
  /**
667
- * Check if network ID is valid
773
+ * Check if network ID is valid (own property check, prevents prototype pollution).
668
774
  */
669
775
  declare function isValidNetworkId(networkId: string): boolean;
670
776
 
671
777
  /**
672
- * Default balance structure
778
+ * Default balance structure.
779
+ * Accepts a numeric total or undefined — never pass a Balance object here.
673
780
  */
674
781
  declare function createDefaultBalance(total?: number): Balance;
675
782
  /**
676
783
  * SDK Configuration constants
677
784
  */
678
785
  declare const SDK_CONFIG: {
679
- readonly version: "2.6.0";
786
+ readonly version: "2.7.0";
680
787
  readonly defaultNetworkId: "mainnet";
681
788
  readonly communicationTimeout: 30000;
682
789
  readonly retryAttempts: 3;
@@ -697,9 +804,11 @@ declare function getDefaultNetwork(): NetworkInfo;
697
804
  */
698
805
  declare function isValidAddress(address: string): boolean;
699
806
  /**
700
- * Validate transaction amount
807
+ * Validate transaction amount.
808
+ * Accepts both number and string representations.
809
+ * String amounts avoid JS number precision loss for very large values.
701
810
  */
702
- declare function isValidAmount(amount: number): boolean;
811
+ declare function isValidAmount(amount: string | number): boolean;
703
812
  /**
704
813
  * Validate transaction message
705
814
  */
@@ -708,10 +817,16 @@ declare function isValidMessage(message: string): boolean;
708
817
  * Validate fee level
709
818
  */
710
819
  declare function isValidFeeLevel(feeLevel: number): boolean;
820
+ /**
821
+ * Derive the canonical Octra address from a base64-encoded Ed25519 public key.
822
+ * Algorithm: SHA-256(pubkey_bytes) → base58 → prepend "oct"
823
+ * Source of truth: ocho-push-server/src/index.ts#deriveAddressFromPubkey
824
+ */
825
+ declare function deriveOctraAddress(publicKeyBase64: string): Promise<string>;
711
826
  /**
712
827
  * Format OCT amount for display
713
828
  */
714
- declare function formatOCT(amount: number, decimals?: number): string;
829
+ declare function formatOCT(amount: number | string, decimals?: number): string;
715
830
  /**
716
831
  * Format address for display (truncated)
717
832
  */
@@ -744,14 +859,6 @@ declare function isErrorType(error: any, code: ErrorCode): boolean;
744
859
  * Create a promise that resolves after a delay
745
860
  */
746
861
  declare function delay(ms: number): Promise<void>;
747
- /**
748
- * Retry an async operation with exponential backoff
749
- */
750
- declare function retry<T>(operation: () => Promise<T>, maxRetries?: number, baseDelay?: number): Promise<T>;
751
- /**
752
- * Timeout wrapper for promises
753
- */
754
- declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, timeoutMessage?: string): Promise<T>;
755
862
  /**
756
863
  * Check if running in browser environment
757
864
  */
@@ -799,7 +906,7 @@ declare function createLogger(prefix: string, debug: boolean): {
799
906
  groupEnd: () => void;
800
907
  };
801
908
 
802
- declare const SDK_VERSION = "2.6.0";
909
+ declare const SDK_VERSION = "2.7.0";
803
910
  declare const MIN_EXTENSION_VERSION = "2.0.1";
804
911
  declare const MIN_EXTENSION_VERSION_DEVNET = "2.2.1";
805
912
  declare const SUPPORTED_EXTENSION_VERSIONS = "^2.0.1";
@@ -808,13 +915,13 @@ declare function createZeroXIOWallet(config: {
808
915
  appDescription?: string;
809
916
  debug?: boolean;
810
917
  autoConnect?: boolean;
918
+ adapter?: WalletTransportAdapter;
811
919
  }): Promise<ZeroXIOWallet>;
812
- declare const createOctraWallet: typeof createZeroXIOWallet;
813
920
  declare function checkSDKCompatibility(): {
814
921
  compatible: boolean;
815
922
  issues: string[];
816
923
  recommendations: string[];
817
924
  };
818
925
 
819
- 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 };
820
- 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 };
926
+ 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 };
927
+ 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 };