suidouble 2.5.0 → 2.17.0

package/lib/SuiEvent.js

@@ -1,27 +1,57 @@
+/**
+ * @typedef {import("./SuiMaster.js").default} SuiMaster
+ *
+ * @typedef SuiEventData
+ * @type {object}
+ * @property {string} [type] - Fully-qualified Move type of the event, e.g. `<pkg>::<module>::<EventName>`
+ * @property {Object} [parsedJson] - JSON representation of the event's Move struct contents
+ * @property {string|number} [timestampMs] - Timestamp (ms since epoch) of the checkpoint the event's tx was finalized in
+ * @property {string} [sender] - SuiAddress of the sender of the emitting transaction
+ * @property {string} [transactionDigest] - Digest of the emitting transaction
+ * @property {string|number} [sequenceNumber] - Event position within its transaction
+ * @property {string|Uint8Array} [bcs] - BCS bytes (base64 string from GraphQL, Uint8Array from gRPC)
+ */
 
-
+/**
+ * Wrapper over a Sui event. Extends the native `Event` so it can be dispatched through
+ * `EventTarget`-style listeners; also exposes the common Sui event fields directly.
+ */
 export default class SuiEvent extends Event {
-    constructor(params = {}) {
+    /**
+     * @param {Object} params - Initialization parameters
+     * @param {SuiMaster} params.suiMaster - instance of SuiMaster
+     * @param {SuiEventData} [params.data] - raw event data
+     * @param {boolean} [params.debug] - enable debug logging
+     */
+    constructor(params) {
         const typeName = params.data ? ((''+params.data.type).split('<')[0].split('::').pop()) : null;
         super(typeName, {});
 
         this._debug = !!params.debug;
+        /** @type {SuiMaster} */
         this._suiMaster = params.suiMaster;
         if (!this._suiMaster) {
-            throw new Error('suiMaster is requried for suiPackage');
+            throw new Error('suiMaster is required for SuiEvent');
         }
 
+        /** @type {SuiEventData} */
         this._data = params.data || {};
 
         this.detail = this; // quick backward support as this is the instance of CustomEvent
     }
 
+    /**
+     * Debug logger. No-op unless the instance was constructed with `debug: true`.
+     * Prefixes messages with the SuiMaster instance number and the class name.
+     * @param {...any} args
+     */
 	log(...args) {
 		if (!this._debug) {
 			return;
 		}
 
-		let prefix = (this._suiMaster ? (''+this._suiMaster.instanceN+' |') : (this.instanceN ? ''+this.instanceN+' |' : '') );
+		const self = /** @type {any} */ (this);
+		let prefix = (self._suiMaster ? (''+self._suiMaster.instanceN+' |') : (self.instanceN ? ''+self.instanceN+' |' : '') );
 		// prefix += this.constructor.name+' | ';
 
 		args.unshift(this.constructor.name+' |');
@@ -29,25 +59,39 @@ export default class SuiEvent extends Event {
 		console.info.apply(null, args);
 	}
 
+    /** Brand property for duck-typing. @returns {true} */
     get isSuiEvent() {
         return true;
     }
 
     /**
-     * In module type name, without package and module prefix and without <T..> suffix
+     * In-module type name — last segment of `package::module::Name<...>`, without package/module prefix or `<T..>` suffix.
+     * @returns {?string}
      */
     get typeName() {
         return this._data ? (''+this._data.type).split('<')[0].split('::').pop() : null;
     }
 
+    /**
+     * Fully-qualified Move type of the event, e.g. `<pkg>::<module>::<EventName>[<type-params>]`.
+     * @returns {?string}
+     */
     get type() {
         return this._data ? (''+this._data.type) : null;
     }
 
+    /**
+     * Raw event data as received from the client.
+     * @returns {SuiEventData}
+     */
     get data() {
         return this._data;
     }
 
+    /**
+     * JSON representation of the event's Move struct contents.
+     * @returns {?Object}
+     */
     get parsedJson() {
         if (this._data.parsedJson) {
             return this._data.parsedJson;
@@ -55,9 +99,13 @@ export default class SuiEvent extends Event {
         return null;
     }
 
+    /**
+     * Timestamp (milliseconds since epoch) of the checkpoint the emitting transaction was finalized in.
+     * @returns {?number}
+     */
     get timestampMs() {
         if (this._data.timestampMs) {
-            return parseInt(this._data.timestampMs, 10);
+            return parseInt('' + this._data.timestampMs, 10);
         } else {
             return null;
         }

package/lib/SuiInBrowser.js

@@ -2,28 +2,62 @@ import SuiCommonMethods from './SuiCommonMethods.js';
 import SuiInBrowserAdapter from './SuiInBrowserAdapter.js';
 import { getWallets } from '@wallet-standard/core';
 import SuiMaster from './SuiMaster.js';
+import { toBase64 } from '@mysten/bcs';
 
 import icons from './data/icons.js';
 
+/** 
+ * @typedef {import("@mysten/sui/grpc").SuiGrpcClient} SuiGrpcClient 
+ * @typedef {import("@mysten/sui/cryptography").SignatureWithBytes} SignatureWithBytes
+ */
+
+
 const DEFAULT_CHAIN = 'sui:devnet';
 
+/**
+ * Browser-side entry point for wallet integration. Manages a registry of SuiInBrowserAdapter
+ * instances (one per known wallet), tracks the active connection, and creates a SuiMaster
+ * pointing at the connected chain.
+ *
+ * Starts initialising itself 50 ms after construction so callers have time to attach listeners.
+ * Use SuiInBrowser.getSingleton({ defaultChain }) for the typical single-page-app pattern.
+ *
+ * Events emitted:
+ *   - 'adapter'      — a new SuiInBrowserAdapter was registered (detail: adapter)
+ *   - 'connected'    — the active adapter connected
+ *   - 'disconnected' — the active adapter disconnected
+ *   - 'rpc'          — the RPC endpoint was changed via setRPC
+ */
 export default class SuiInBrowser extends SuiCommonMethods {
+    /**
+     * @param {Object} [params]
+     * @param {string} [params.defaultChain='sui:devnet'] - chain used before any wallet connects
+     * @param {boolean} [params.debug]
+     */
     constructor(params = {}) {
         super(params);
 
+        /** @type {Object.<string, SuiInBrowserAdapter>} */
         this._adapters = {};
 
+        /** @type {string} */
         this._defaultChain = params.defaultChain || DEFAULT_CHAIN;
 
+        /** @type {?SuiInBrowserAdapter} */
         this._activeAdapter = null;
+        /** @type {?string} */
         this._connectedAddress = null;
+        /** @type {?string} */
         this._connectedChain = null;
+        /** @type {boolean} */
         this._isConnected = false;
+        /** @type {boolean} */
         this._isConnecting = false;
 
         this._client = null;
         this._suiMaster = null;
 
+        /** @type {?Object} */
         this._rpcSettings = null;
 
         setTimeout(()=>{
@@ -31,53 +65,103 @@ export default class SuiInBrowser extends SuiCommonMethods {
         }, 50);
     }
 
+    /** @returns {?SuiInBrowserAdapter} The currently active wallet adapter, or null. */
     get activeAdapter() {
         return this._activeAdapter;
     }
 
+    /**
+     * Returns the currently connected wallet address, or null if not connected.
+     * @returns {?string}
+     */
     getAddress() {
         return this._connectedAddress;
     }
 
+    /**
+     * Sign a transaction using the current `sui:signTransaction` feature.
+     * @param {Object} params
+     * @returns {Promise<SignatureWithBytes>}
+     */
+    async signTransaction(params) {
+        const enriched = { account: { address: this._connectedAddress }, chain: this._connectedChain, ...params };
+        return await this._activeAdapter.signTransaction(enriched);
+    }
+
+    /**
+     * Delegates to the active adapter using the legacy transaction-block API.
+     * @param {Object} params
+     * @returns {Promise<*>}
+     */
     async signAndExecuteTransactionBlock(params) {
         return await this._activeAdapter.signAndExecuteTransactionBlock(params);
     }
 
+    /**
+     * Delegates to the active adapter using the current transaction API.
+     * @param {Object} params
+     * @returns {Promise<*>}
+     */
     async signAndExecuteTransaction(params) {
-        return await this._activeAdapter.signAndExecuteTransaction(params);
+        const enriched = { account: { address: this._connectedAddress }, chain: this._connectedChain, ...params };
+        return await this._activeAdapter.signAndExecuteTransaction(enriched);
     }
 
+    /** @returns {*} The gRPC client instance, or null if not yet initialised. */
     get client() {
         return this._client;
     }
 
+    toSuiAddress() {
+        return this._connectedAddress;
+    }
+
+    /**
+     * Ensures the client is initialised, then returns it.
+     * @returns {Promise<*>}
+     */
     async getClient() {
         await this.initClient();
         return this._client;
     }
 
+    /**
+     * Ensures the client is initialised, then returns the SuiMaster instance.
+     * @returns {Promise<SuiMaster>}
+     */
     async getSuiMaster() {
         await this.initClient();
         return this._suiMaster;
     }
 
+    /** @returns {?SuiMaster} The current SuiMaster instance, or null if not yet initialised. */
     get suiMaster() {
         return this._suiMaster;
     }
 
+    /** @returns {boolean} True if a wallet adapter is currently connected. */
     get isConnected() {
         return this._isConnected;
     }
 
+    /** @returns {?string} The active wallet address, or null if not connected. */
     get connectedAddress() {
         return this._connectedAddress;
     }
 
+    /** @returns {?string} The chain the active adapter is connected to (e.g. 'sui:mainnet'), or null. */
     get connectedChain() {
         return this._connectedChain;
     }
 
     static _singleInstances = {};
+    /**
+     * Returns the singleton SuiInBrowser instance for the given defaultChain, creating it if
+     * necessary. Ideal for single-page-app usage where one instance is shared across the app.
+     * @param {Object} [params]
+     * @param {string} [params.defaultChain]
+     * @returns {SuiInBrowser}
+     */
     static getSingleton(params = {}) {
         let defaultChainKey = params.defaultChain || DEFAULT_CHAIN;
 
@@ -89,15 +173,20 @@ export default class SuiInBrowser extends SuiCommonMethods {
         return SuiInBrowser._singleInstances[defaultChainKey];
     }
 
+    /** @returns {Object.<string, SuiInBrowserAdapter>} Map of adapter name to SuiInBrowserAdapter. */
     get adapters() {
         return this._adapters;
     }
 
+    /**
+     * Connects to a named adapter or an adapter instance. Returns false if the adapter is not
+     * found in the registry.
+     * @param {string|SuiInBrowserAdapter} adapterOrAdapterName
+     * @returns {Promise<boolean|void>}
+     */
     async connect(adapterOrAdapterName) {
-        let adapterName = adapterOrAdapterName;
-        if (adapterOrAdapterName.name) {
-            adapterName = adapterOrAdapterName.name;
-        }
+        const a = /** @type {any} */ (adapterOrAdapterName);
+        const adapterName = a.name ?? a;
 
         if (!this._adapters[adapterName]) {
             return false;
@@ -113,11 +202,15 @@ export default class SuiInBrowser extends SuiCommonMethods {
         this._isConnecting = false;
     }
 
+    /**
+     * Called when an adapter fires its 'connected' event. Updates the active adapter, connected
+     * address and chain, rebuilds the gRPC client and SuiMaster, and emits 'connected'.
+     * @param {SuiInBrowserAdapter} suiInBrowserAdapter
+     */
     adapterConnected(suiInBrowserAdapter) {
         this._activeAdapter = suiInBrowserAdapter;
         this._isConnected = suiInBrowserAdapter.isConnected;
         this._connectedAddress = suiInBrowserAdapter.connectedAddress;
-        const wasConnectedToChain = this._connectedChain;
         this._connectedChain = suiInBrowserAdapter.connectedChain;
 
         if (this._connectedChain == 'sui:unknown') {
@@ -127,9 +220,9 @@ export default class SuiInBrowser extends SuiCommonMethods {
         this._client = null;
         this._suiMaster = null;
 
-        this.initClient();
-
-        this.emit('connected');
+        this.initClient().then(() => {
+            this.emit('connected');
+        });
     }
 
     /**
@@ -139,7 +232,7 @@ export default class SuiInBrowser extends SuiCommonMethods {
      * @param {Object} params.rpc rpc settings
      * @param {Object.<string, string>} params.rpc.headers rpc headers
      */
-    async setRPC(params = {}) {
+    async setRPC(params) {
         this._rpcSettings = params;
         this._client = null;
         this._suiMaster = null;
@@ -149,13 +242,29 @@ export default class SuiInBrowser extends SuiCommonMethods {
         this.emit('rpc');
     }
 
-    adapterDisconnected(suiInBrowserAdapter) {
+    /**
+     * Called when an adapter fires its 'disconnected' event. Resets connection state and emits
+     * 'disconnected'.
+     * @param {SuiInBrowserAdapter} [_suiInBrowserAdapter]
+     */
+    adapterDisconnected(_suiInBrowserAdapter) {
         this._isConnected = false;
         this._connectedAddress = null;
 
         this.emit('disconnected');
     }
 
+    /**
+     * Registers a wallet adapter in the registry. If the adapter is new, creates a
+     * SuiInBrowserAdapter instance, wires up its events, and emits 'adapter'. If the adapter
+     * already exists and a standartAdapter is provided, updates it instead.
+     * @param {Object} adapterParams
+     * @param {string} [adapterParams.name]
+     * @param {Object} [adapterParams.standartAdapter]
+     * @param {string} [adapterParams.icon]
+     * @param {Object} [adapterParams.downloadUrls]
+     * @returns {void|false}
+     */
     attachAdapter(adapterParams) {
         let adapterName = adapterParams.name;
         if (adapterParams.standartAdapter && adapterParams.standartAdapter.name) {
@@ -178,29 +287,38 @@ export default class SuiInBrowser extends SuiCommonMethods {
         } else {
             this._adapters[adapterName] = adapter;
             this._adapters[adapterName].addEventListener('connected', (e)=>{
-                this.adapterConnected(e.detail);
+                this.adapterConnected(/** @type {any} */ (e).detail);
             });
             this._adapters[adapterName].addEventListener('disconnected', (e)=>{
-                this.adapterDisconnected(e.detail);
+                this.adapterDisconnected(/** @type {any} */ (e).detail);
             });
             this.emit('adapter', adapter);
         }
     }
 
+    /**
+     * Returns the currently connected chain, or the default chain if no wallet is connected.
+     * @returns {string}
+     */
     getCurrentChain() {
         return this._connectedChain ? this._connectedChain : this._defaultChain;
     }
 
+    /**
+     * Builds the gRPC client and SuiMaster for the current chain. No-op if already built.
+     * Uses _rpcSettings when a custom RPC endpoint has been set via setRPC.
+     * @returns {Promise<void>}
+     */
     async initClient() {
         if (this._client) {
-            return true;
+            return;
         }
 
         let chainName = this.getCurrentChain();
 
         if (this._rpcSettings) {
             this._rpcSettings.providerName = chainName.split('sui:').join('');
-            this._client = SuiMaster.SuiUtils.suiClientForRPC(this._rpcSettings);
+            this._client = SuiMaster.SuiUtils.suiClientForRPC(this._rpcSettings.providerName ?? chainName, this._rpcSettings);
         } else if (!chainName) {
             this.log('error', 'invalid chain', chainName);
             throw new Error('invalid chain: '+chainName);
@@ -215,6 +333,11 @@ export default class SuiInBrowser extends SuiCommonMethods {
         });
     }
 
+    /**
+     * Seeds the adapter registry from the known-wallets list and the live Wallet Standard
+     * registry, then subscribes to future 'register' events for dynamically installed wallets.
+     * @returns {Promise<void>}
+     */
     async initialize() {
         await this.initClient(); // set default client
 
@@ -241,6 +364,11 @@ export default class SuiInBrowser extends SuiCommonMethods {
         });
     }
 
+    /**
+     * Returns the list of known wallet placeholder params used to pre-populate the adapter
+     * registry before the Wallet Standard registry is queried.
+     * @returns {Array<{name: string, icon: string, downloadUrls: Object}>}
+     */
     static getPossibleWallets() {
         return [
             {