@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/CHANGELOG.md +50 -0
- package/README.md +45 -1
- package/dist/index.d.ts +291 -184
- package/dist/index.esm.js +972 -470
- package/dist/index.esm.js.map +1 -1
- package/dist/index.js +978 -472
- package/dist/index.js.map +1 -1
- package/dist/index.umd.js +978 -472
- package/dist/index.umd.js.map +1 -1
- package/package.json +1 -1
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
|
-
|
|
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
|
-
|
|
103
|
-
readonly
|
|
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
|
|
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
|
-
|
|
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<
|
|
528
|
+
encryptBalance(amount: string | number): Promise<TransactionResult>;
|
|
374
529
|
/**
|
|
375
530
|
* Decrypt private balance to public
|
|
376
531
|
*/
|
|
377
|
-
decryptBalance(amount: number): Promise<
|
|
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.
|
|
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
|
-
/**
|
|
499
|
-
private
|
|
500
|
-
/**
|
|
501
|
-
private
|
|
502
|
-
/**
|
|
503
|
-
private
|
|
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
|
-
*
|
|
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
|
-
|
|
639
|
+
private _parentTrusted;
|
|
640
|
+
/** walletReady postMessage listener stored for cleanup */
|
|
641
|
+
private _walletReadyMessageListener;
|
|
512
642
|
/**
|
|
513
|
-
*
|
|
514
|
-
*
|
|
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
|
-
*
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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,
|
|
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 };
|