suidouble 2.5.0 → 2.17.0-1

package/lib/SuiInBrowserAdapter.js

@@ -1,5 +1,15 @@
 import SuiCommonMethods from './SuiCommonMethods.js';
 
+
+/**
+ * @typedef {import("@mysten/sui/cryptography").SignatureWithBytes} SignatureWithBytes
+ */
+
+/**
+ * Wallet Standard feature identifiers — keys map to the string feature names used by the
+ * `@wallet-standard/core` registry.
+ * @enum {string}
+ */
 const Feature = {
     DISCONNECT: 'standard:disconnect',
     CONNECT: 'standard:connect',
@@ -12,25 +22,55 @@ const Feature = {
     SUI_SIGN_PERSONAL_MESSAGE: 'sui:signPersonalMessage',
 };
 
+/**
+ * Wrapper over a single Wallet Standard adapter (e.g. Sui Wallet, Martian, Suiet).
+ * Abstracts away legacy `signAndExecuteTransactionBlock` vs the current
+ * `signAndExecuteTransaction` API, and normalises connection state changes into
+ * `'connected'` / `'disconnected'` events on this instance.
+ */
 export default class SuiInBrowserAdapter extends SuiCommonMethods {
+    /**
+     * @param {Object} [params]
+     * @param {Object} [params.standardAdapter] - raw Wallet Standard adapter from `@wallet-standard/core`
+     * @param {?string} [params.name] - display name used when no adapter is attached (e.g. "not installed" placeholder)
+     * @param {?string} [params.icon] - data-URI icon used when no adapter is attached
+     * @param {Object} [params.downloadUrls] - map of browser name → extension store URL (e.g. `{ chrome: 'https://…' }`)
+     * @param {boolean} [params.debug]
+     */
     constructor(params = {}) {
         super(params);
 
-        this._standartAdapter = null;
-        //  params.standartAdapter || null; // instance returned from '@wallet-standard/core'
-        if (params.standartAdapter) {
-            this.setStandartAdapter(params.standartAdapter);
+        /** @type {?Object} raw Wallet Standard adapter */
+        this._standardAdapter = null;
+        if (params.standardAdapter) {
+            this.setStandartAdapter(params.standardAdapter);
         }
-        
+
+        /** @type {?string} */
         this._name = params.name || null;
+        /** @type {?string} */
         this._icon = params.icon || null;
+        /** @type {Object.<string, string>} */
         this._downloadUrls = params.downloadUrls || {};
 
+        /** @type {?string} */
         this._connectedAddress = null;
+        /** @type {?string} */
         this._connectedChain = null;
+        /** @type {boolean} */
         this._isConnected = false;
+        /** @type {boolean} */
+        this._userDisconnected = false;
+        /** @type {?string} */
+        this._preferredChain = null;
     }
 
+    /**
+     * Sign and execute a transaction. Prefers the current `sui:signAndExecuteTransaction`
+     * feature; falls back to the legacy `sui:signAndExecuteTransactionBlock` for older wallets.
+     * @param {Object} params
+     * @returns {Promise<*>}
+     */
     async signAndExecuteTransaction(params) {
         if (this.hasFeature(Feature.SUI_SIGN_AND_EXECUTE_TX)) {
             return await this.getFeature(Feature.SUI_SIGN_AND_EXECUTE_TX).signAndExecuteTransaction(params);
@@ -41,10 +81,32 @@ export default class SuiInBrowserAdapter extends SuiCommonMethods {
         }
     }
 
+    /**
+     * Sign and execute a transaction using the legacy `sui:signAndExecuteTransactionBlock` feature.
+     * @param {Object} params
+     * @returns {Promise<*>}
+     */
     async signAndExecuteTransactionBlock(params) {
         return await this.getFeature(Feature.SUI_SIGN_AND_EXECUTE_TX_BLOCK).signAndExecuteTransactionBlock(params);
     }
 
+    /**
+     * Sign a transaction using the current `sui:signTransaction` feature.
+     * @param {Object} params
+     * @returns {Promise<SignatureWithBytes>}
+     */
+    async signTransaction(params) {
+        /** @type {SignatureWithBytes} */
+        const resp = await this.getFeature(Feature.SUI_SIGN_TX).signTransaction(params);
+        return resp;
+    }
+
+    /**
+     * Sign a transaction. Prefers the current `sui:signTransaction` feature;
+     * falls back to the legacy `sui:signTransactionBlock` for older wallets.
+     * @param {Object} params
+     * @returns {Promise<*>}
+     */
     async signTransactionBlock(params) {
         if (this.hasFeature(Feature.SUI_SIGN_TX)) {
             return await this.getFeature(Feature.SUI_SIGN_TX).signTransaction(params);
@@ -55,10 +117,12 @@ export default class SuiInBrowserAdapter extends SuiCommonMethods {
         }
     }
 
-    async signTransactionBlock(params) {
-        return await this.getFeature(Feature.SUI_SIGN_TX_BLOCK).signTransactionBlock(params);
-    }
-
+    /**
+     * Sign a personal/arbitrary message. Prefers `sui:signPersonalMessage`;
+     * falls back to `sui:signMessage` for older wallets.
+     * @param {Object} params
+     * @returns {Promise<*>}
+     */
     async signPersonalMessage(params) {
         if (this.hasFeature(Feature.SUI_SIGN_PERSONAL_MESSAGE)) {
             return await this.getFeature(Feature.SUI_SIGN_PERSONAL_MESSAGE).signPersonalMessage(params);
@@ -67,16 +131,43 @@ export default class SuiInBrowserAdapter extends SuiCommonMethods {
         }
     }
 
+    /**
+     * Alias for `signPersonalMessage`.
+     * @param {Object} params
+     * @returns {Promise<*>}
+     */
     async signMessage(params) {
         return await this.signPersonalMessage(params);
     }
 
+    /**
+     * Disconnect from the wallet and refresh connection state.
+     * Force-clears local connection state even if the wallet doesn't support
+     * standard:disconnect or doesn't revoke site authorization (e.g. Phantom).
+     * @param {Object} [params]
+     * @returns {Promise<void>}
+     */
     async disconnect(params) {
-        const res = await this.getFeature(Feature.DISCONNECT).disconnect(params);
-        this.connectionUpdated();
-        return res;
+        try {
+            const feature = this.getFeature(Feature.DISCONNECT);
+            if (feature) {
+                await feature.disconnect(params);
+            }
+        } catch (e) {
+            console.warn('[SuiInBrowserAdapter] standard:disconnect failed:', e);
+        }
+
+        this._connectedAddress = null;
+        this._connectedChain = null;
+        this._isConnected = false;
+        this._userDisconnected = true;
+        this.emit('disconnected', this);
     }
 
+    /**
+     * Return the Chrome Web Store download URL, or null if not configured.
+     * @returns {?string}
+     */
     getDownloadURL() {
         if (this._downloadUrls && this._downloadUrls.chrome) {
             return this._downloadUrls.chrome;
@@ -84,26 +175,36 @@ export default class SuiInBrowserAdapter extends SuiCommonMethods {
         return null;
     }
 
+    /**
+     * True when no underlying adapter has been attached (i.e. this is a "not installed" placeholder).
+     * @returns {boolean}
+     */
     get isDefault() {
-        if (!this._standartAdapter) {
-            return true;
-        }
-        return false;
+        return !this._standardAdapter;
     }
 
+    /** @returns {?string} currently connected Sui address, or null */
     get connectedAddress() {
         return this._connectedAddress;
     }
 
+    /** @returns {?string} currently connected chain identifier (e.g. `'sui:mainnet'`), or null */
     get connectedChain() {
         return this._connectedChain;
     }
 
+    /** @returns {boolean} true if the wallet is connected and an address is available */
     get isConnected() {
         return this._isConnected;
     }
 
+    /**
+     * Request connection to the wallet. Errors are swallowed; connection state is refreshed
+     * via `connectionUpdated` regardless.
+     * @returns {Promise<void>}
+     */
     async connect() {
+        this._userDisconnected = false;
         try {
             await this.getFeature(Feature.CONNECT).connect();
         } catch (e) {
@@ -113,14 +214,26 @@ export default class SuiInBrowserAdapter extends SuiCommonMethods {
         this.connectionUpdated();
     }
 
+    /**
+     * Read the current connection state from the underlying adapter and update
+     * `connectedAddress`, `connectedChain`, and `isConnected`. Emits `'connected'` or
+     * `'disconnected'` if the state changed.
+     */
     connectionUpdated() {
+        if (this._userDisconnected) return;
+
         const wasConnectedAddress = ''+this._connectedAddress;
         const wasConnectedChain = ''+this._connectedChain;
 
         try {
-            if (this._standartAdapter && this._standartAdapter.accounts && this._standartAdapter.accounts.length) {
-                this._connectedAddress = this._standartAdapter.accounts[0].address;
-                this._connectedChain = this._standartAdapter.accounts[0].chains[0];
+            if (this._standardAdapter && this._standardAdapter.accounts && this._standardAdapter.accounts.length) {
+                this._connectedAddress = this._standardAdapter.accounts[0].address;
+                const accountChains = this._standardAdapter.accounts[0].chains;
+                if (this._preferredChain && accountChains.includes(this._preferredChain)) {
+                    this._connectedChain = this._preferredChain;
+                } else {
+                    this._connectedChain = accountChains[0];
+                }
             } else {
                 this._connectedAddress = null;
                 this._connectedChain = null;
@@ -141,16 +254,23 @@ export default class SuiInBrowserAdapter extends SuiCommonMethods {
         }
     }
 
-
-    setStandartAdapter(standartAdapter) {
-        if (this._standartAdapter) {
+    /**
+     * Attach a Wallet Standard adapter to this instance. No-op if already attached.
+     * Returns false and does nothing if the adapter has no `sui:` features.
+     * Subscribes to adapter `'change'` events to keep connection state up to date.
+     *
+     * @param {Object} standardAdapter - raw adapter from `@wallet-standard/core`
+     * @returns {boolean} false if the adapter lacks Sui features, undefined on success
+     */
+    setStandartAdapter(standardAdapter) {
+        if (this._standardAdapter) {
             // no need to re-attach
             return true;
         }
 
         // check if it has sui: features
         let hasSuiFeatures = false;
-        for (const key in standartAdapter.features) {
+        for (const key in standardAdapter.features) {
             if ((''+key).indexOf('sui:') === 0) {
                 hasSuiFeatures = true;
             }
@@ -160,65 +280,97 @@ export default class SuiInBrowserAdapter extends SuiCommonMethods {
             return false;
         }
 
-        this._standartAdapter = standartAdapter;
-        if (!this.__standartAdapterChangeListener) {
-            this.__standartAdapterChangeListener = (e) => {
+        this._standardAdapter = standardAdapter;
+        if (!this.__standardAdapterChangeListener) {
+            this.__standardAdapterChangeListener = () => {
                 this.connectionUpdated();
             };
         }
-        this.getFeature(Feature.EVENTS).on('change', this.__standartAdapterChangeListener);
+        this.getFeature(Feature.EVENTS).on('change', this.__standardAdapterChangeListener);
 
         this.connectionUpdated();
     }
 
+    /**
+     * True if the adapter is installed and supports the minimum required Sui features
+     * (`sui:signAndExecuteTransaction` or `sui:signAndExecuteTransactionBlock`, plus `standard:events`).
+     * @returns {boolean}
+     */
     get okForSui() {
         if (!this.isInstalled) {
             return false;
         }
 
-        return this.hasFeature(Feature.SUI_SIGN_AND_EXECUTE_TX_BLOCK) && this.hasFeature(Feature.EVENTS);
+        return (this.hasFeature(Feature.SUI_SIGN_AND_EXECUTE_TX_BLOCK) || this.hasFeature(Feature.SUI_SIGN_AND_EXECUTE_TX)) && this.hasFeature(Feature.EVENTS);
     }
 
+    /** @returns {boolean} true if a Wallet Standard adapter has been attached */
     get isInstalled() {
-        if (this._standartAdapter) {
-            return true;
-        }
-        return false;
+        return !!this._standardAdapter;
     }
 
+    /**
+     * Feature map from the underlying adapter, or an empty object if not installed.
+     * Keys are Wallet Standard feature strings (e.g. `'sui:signAndExecuteTransaction'`).
+     * @returns {Object}
+     */
     get features() {
-        if (this._standartAdapter) {
-            return this._standartAdapter.features;
+        if (this._standardAdapter) {
+            return this._standardAdapter.features;
         }
         return {};
     }
 
+    /**
+     * Display name — from the adapter if installed, otherwise from the constructor param.
+     * @returns {?string}
+     */
     get name() {
-        if (this._standartAdapter) {
-            return this._standartAdapter.name;
+        if (this._standardAdapter) {
+            return this._standardAdapter.name;
         } else {
             return this._name;
         }
     }
 
+    /**
+     * Data-URI icon — from the adapter if installed, otherwise from the constructor param.
+     * @returns {?string}
+     */
     get icon() {
-        if (this._standartAdapter) {
-            return this._standartAdapter.icon;
+        if (this._standardAdapter) {
+            return this._standardAdapter.icon;
         } else {
             return this._icon;
         }
     }
 
+    /**
+     * Wallet version string from the adapter, or undefined if not installed.
+     * @returns {?string}
+     */
     get version() {
-        if (this._standartAdapter) {
-            return this._standartAdapter.version;
+        if (this._standardAdapter) {
+            return this._standardAdapter.version;
         }
     }
 
+    /**
+     * Returns true if this adapter supports the given feature.
+     * Accepts either a `Feature` enum key (e.g. `'SUI_SIGN_TX'`) or a raw feature string.
+     * @param {string} featureName
+     * @returns {boolean}
+     */
     hasFeature(featureName) {
         return (!!this.getFeature(featureName));
     }
 
+    /**
+     * Return the feature object for `featureName`, or null if not available.
+     * Accepts either a `Feature` enum key (e.g. `'SUI_SIGN_TX'`) or a raw feature string.
+     * @param {string} featureName
+     * @returns {?Object}
+     */
     getFeature(featureName) {
         const features = this.features;
 

package/lib/SuiLocalTestValidator.js

@@ -2,29 +2,55 @@ import SuiCliCommands from "./SuiCliCommands.js";
 import SuiCommonMethods from "./SuiCommonMethods.js";
 import SuiUtils from "./SuiUtils.js";
 
+/** @typedef {import("@mysten/sui/grpc").SuiGrpcClient} SuiGrpcClient */
+
+/**
+ * Manages a local `sui start` test-validator process. The singleton pattern (`launch` / `stop`)
+ * means only one validator runs per test suite even when called from multiple test files.
+ *
+ * When `testFallbackEnabled` is true and `sui start` fails (e.g. Sui CLI not installed),
+ * the instance transparently switches to `sui:devnet` so tests can still run against a live node.
+ */
 export default class SuiLocalTestValidator extends SuiCommonMethods {
+    /**
+     * @param {Object} [params]
+     * @param {boolean} [params.testFallbackEnabled] - fall back to devnet if the local node can't start
+     * @param {?number} [params.epochDuration] - custom epoch duration in ms (only valid with `--force-regenesis`)
+     * @param {boolean} [params.debug]
+     */
     constructor(params = {}) {
         super(params);
 
+        /** @type {?Object} spawned child process */
         this._child = null;
+        /** @type {boolean} */
         this._active = false;
 
-        this._testFallbackEnabled = false;
-        if (params.testFallbackEnabled) { 
-            // option for unit tests to fallback to sui:dev network in case 
-            // there is no local validator installed
-            this._testFallbackEnabled = true;
-        }
+        /**
+         * When true, falls back to sui:devnet if the local node can't be started.
+         * @type {boolean}
+         */
+        this._testFallbackEnabled = !!params.testFallbackEnabled;
 
+        /** @type {?number} */
         this._epochDuration = params.epochDuration || null;
 
+        /** @type {string} */
         this._providerName = 'sui:localnet';
     }
 
+    /** @returns {string} active chain identifier, e.g. `'sui:localnet'` or `'sui:devnet'` after fallback */
     get providerName() {
         return this._providerName;
     }
 
+    /** @type {?SuiLocalTestValidator} */
+    static __instance = null;
+
+    /**
+     * gRPC client for the currently active chain.
+     * @returns {SuiGrpcClient}
+     */
     get client() {
         if (this._providerName === 'sui:localnet') {
             return SuiUtils.suiClientFor('localnet');
@@ -34,15 +60,19 @@ export default class SuiLocalTestValidator extends SuiCommonMethods {
         }
     }
 
+    /** @returns {boolean} true once the node is up and accepting transactions */
     get active() {
         return this._active;
     }
 
     /**
-     * Launch a localnet sui and wait for it to become available to accept transactions.
-     * Don't forget to .stop() it after usage.
-     * 
-     * @returns {SuiLocalTestValidator}
+     * Launch the local sui node (singleton). If already running, returns the existing instance.
+     * Don't forget to call `.stop()` after usage.
+     *
+     * @param {Object} [params]
+     * @param {boolean} [params.testFallbackEnabled]
+     * @param {?number} [params.epochDuration]
+     * @returns {Promise<SuiLocalTestValidator>}
      */
     static async launch(params = {}) {
         if (SuiLocalTestValidator.__instance) {
@@ -54,7 +84,8 @@ export default class SuiLocalTestValidator extends SuiCommonMethods {
     }
 
     /**
-     * Stop the local sui node 
+     * Stop the singleton local sui node if running.
+     * @returns {Promise<void>}
      */
     static async stop() {
         if (SuiLocalTestValidator.__instance) {
@@ -62,10 +93,20 @@ export default class SuiLocalTestValidator extends SuiCommonMethods {
         }
     }
 
+    /**
+     * @param {number} port
+     * @returns {Promise<boolean>} true if the port accepts a TCP connection within 3 seconds
+     */
     async isPortThere(port) {
         return await SuiCliCommands.isPortThere(port);
     }
 
+    /**
+     * Poll `isPortThere` every 500 ms until the port is open or the timeout elapses.
+     * @param {number} port
+     * @param {number} timeout - total wait time in ms
+     * @returns {Promise<boolean>}
+     */
     async waitForPort(port, timeout) {
         this.log('waiting for port', port);
         const startedCheckingAt = (new Date()).getTime();
@@ -82,9 +123,13 @@ export default class SuiLocalTestValidator extends SuiCommonMethods {
     }
 
     /**
-     * Launch a local sui node and wait for it to become available to accept transactions.
-     * 
-     * @returns {SuiLocalTestValidator}
+     * Start `sui start --with-faucet --with-indexer --with-graphql --force-regenesis`,
+     * wait for the faucet (port 9123) and GraphQL (port 9125) to come up,
+     * then return this instance with `active === true`.
+     *
+     * If `testFallbackEnabled` is set and the spawn fails, silently switches to devnet.
+     *
+     * @returns {Promise<SuiLocalTestValidator>}
      */
     async launch() {
         if (this._active) {
@@ -98,6 +143,8 @@ export default class SuiLocalTestValidator extends SuiCommonMethods {
             const params = [];
             params.push('start');
             params.push('--with-faucet');
+            params.push('--with-indexer');
+            params.push('--with-graphql');
             params.push('--force-regenesis');
             this._child = await SuiCliCommands.spawn('sui', params, { RUST_LOG: 'off,sui_node=info' });
         } catch (e) {
@@ -120,22 +167,37 @@ export default class SuiLocalTestValidator extends SuiCommonMethods {
             this.log(`child process exited with code ${code}`);
         });
 
+        // @ts-ignore — process is a Node.js global; not available in TypeScript without @types/node
         process.on('exit', ()=>{
             if (this._child) {
                 this._child.kill();
             }
         });
+        // @ts-ignore
         const cleanExit = function() { process.exit() };
+        // @ts-ignore
         process.on('SIGINT', cleanExit); // catch ctrl-c
+        // @ts-ignore
         process.on('SIGTERM', cleanExit); // catch kill
 
         this._active = await this.waitForPort(9123, 30000);
 
+        if (this._active) {
+            const graphqlUp = await this.waitForPort(9125, 30000);
+            if (!graphqlUp) {
+                this.log('warning: GraphQL port 9125 did not come up in time');
+            }
+        }
+
         // await this.__readyLaunchedPromise;
 
         return this;
     }
 
+    /**
+     * Kill the child `sui start` process if it is running.
+     * @returns {Promise<void>}
+     */
     async stop() {
         if (this._child) {
             await this._child.kill();