suidouble 2.5.0 → 2.17.0-1

package/lib/SuiCliCommands.js

@@ -9,9 +9,13 @@ const loadModule = async (modulePath) => {
 }
 
 /**
- * Wrapper to get system function available on node.js side only, returning null on the browser side
- * @param {string} name - execSync, spawn, fs, path, net
- * @returns {(function | null)}
+ * Load a node.js built-in on the server side. Returns null in environments where the module is not available (e.g. browser).
+ *
+ * For 'execSync' and 'spawn' resolves to the named function from `child_process`.
+ * For 'fs', 'path', 'net' resolves to the whole module's default export.
+ *
+ * @param {'execSync' | 'spawn' | 'fs' | 'path' | 'net'} name
+ * @returns {Promise<Function | object | null>} the function or module, or null if unavailable
  */
 const getSystemFunction = async (name) => {
     try {
@@ -64,7 +68,7 @@ export default class SuiCliCommands {
             __waitPortPromiseResolver(false);
         });
 
-        socket.connect(port, "0.0.0.0");
+        socket.connect(port, "127.0.0.1");
 
         const portIsThere = await __waitPortPromise;
         socket.destroy();
@@ -76,7 +80,7 @@ export default class SuiCliCommands {
         const doSpawn = await getSystemFunction('spawn');
 
         if (!doSpawn) {
-            throw new Error('can not spawn a proccess in this env');
+            throw new Error('can not spawn a process in this env');
         }
 
         return await new Promise((res,rej)=>{
@@ -84,7 +88,8 @@ export default class SuiCliCommands {
             let e = null;
             const proc = doSpawn(command, params, {
                 env: {
-                    ...process.env,
+                    // @ts-ignore — process is a Node.js global; not available in TypeScript without @types/node
+                    ...(process ? process.env : {}),
                     ...envVars,
                 }
             });
@@ -101,25 +106,13 @@ export default class SuiCliCommands {
                 }
             }, 100);
         });
-
-        // const proc = doSpawn(command, [], {
-        //     env: {
-        //         ...process.env,
-        //         ...envVars,
-        //     }
-        // });
-        // proc.on('error', function(err) {
-        //     console.log('Oh noez, teh errurz: ' + err);
-        // });
-
-        // return proc;
     }
 
     static async exec(command) {
         const doExecSync = await getSystemFunction('execSync');
 
         if (!doExecSync) {
-            throw new Error('can not exec a proccess in this env');
+            throw new Error('can not exec a process in this env');
         }
 
         return doExecSync(
@@ -137,19 +130,19 @@ export default class SuiCliCommands {
         }
 
         try {
-            const buildPathContent = await doFs.promises.readdir(path.join(this._path, 'build'));
-    
+            const buildPathContent = await doFs.promises.readdir(doPath.join(path, 'build'));
+
             // @todo: there may be some junk folders and we'd have to get project name from Move.toml ?
             const buildPath = buildPathContent[0];
-    
-            const dirents = await doFs.promises.readdir(doPath.join(this._path, 'build', buildPath, 'bytecode_modules'), { withFileTypes: true });
+
+            const dirents = await doFs.promises.readdir(doPath.join(path, 'build', buildPath, 'bytecode_modules'), { withFileTypes: true });
             const names = dirents
                 .filter(dirent => dirent.isFile())
                 .map(dirent => dirent.name.split('.mv').join(''));
-    
+
             return names;
         } catch (e) {
-            throw new Error('can not get modules names from local package path');
+            throw new Error('can not get modules names from local package path: ' + (e && e.message ? e.message : e));
         }
     }
 };

package/lib/SuiCoin.js

@@ -1,8 +1,9 @@
-import { TransactionCommands as Commands, Transaction } from '@mysten/sui/transactions';
+import { Transaction } from '@mysten/sui/transactions';
 
 /**
  * @typedef {import("@mysten/sui/transactions").TransactionObjectArgument} TransactionObjectArgument
  * 
+ * @import { SuiClientTypes } from "@mysten/sui/client"
  * 
  * @typedef CoinMeta
  * @type {object}
@@ -15,17 +16,16 @@ import { TransactionCommands as Commands, Transaction } from '@mysten/sui/transa
  * @property {string} [type] - Coin type string
  * 
  * 
- * @typedef SuidoubleCoinBalance
- * @type {object}
- * @property {SuiCoin} coin
- * @property {string} coinType
- * @property {number} coinObjectCount
- * @property {bigint} totalBalance
- * @property {Object.<string,string>} lockedBalance
- * 
+ * @typedef {SuiClientTypes.Balance & { coin: SuiCoin, totalBalance: bigint }} SuidoubleCoinBalance
+ * @typedef {import("./SuiMaster.js").default} SuiMaster
+ * @typedef {import("./SuiCoins.js").default} SuiCoins
  */
 
-/** Coin metadata object */
+
+/**
+ * Handle for a single coin type (e.g. `0x2::sui::SUI`). Caches metadata, formats amounts
+ * via decimals, and builds `Coin<T>` arguments for transactions.
+ */
 export default class SuiCoin {
 
     /**
@@ -34,7 +34,7 @@ export default class SuiCoin {
      * @param {string} params.coinType - sui object type for a coin, without Coin<...>, only the inside type
      * @param {SuiCoins} params.suiCoins - instance of SuiCoins
      */
-    constructor(params = {}) {
+    constructor(params) {
         this._coinType = params.coinType;
         this._suiCoins = params.suiCoins;
 
@@ -54,7 +54,7 @@ export default class SuiCoin {
                 throw new Error('Please load coin metadata first');
             }
 
-            return BigInt(Math.floor(parseFloat(amount, 10) * Math.pow(10, this.decimals)));
+            return BigInt(Math.floor(parseFloat(amount) * Math.pow(10, this.decimals)));
         }
 
         return BigInt(amount);
@@ -71,13 +71,13 @@ export default class SuiCoin {
     }
 
     /**
-     * Get readable representation of amount value (system one, bigint or converted from bigint, NOT the '1.99' etc) 
-     * based on coin decimals metadata ( so it expects metadata to be loaded or set).
-     * 
-     * @param {Object} params - format parameters
-     * @param {boolean} params.withAbbr - append K, M, B, T for large amounts. Suiet-style
-     * @param {boolean|string} params.separateThousands - separate thousands, by ',' or by specific delimeter
-     * 
+     * Get readable representation of a raw amount (bigint-native, NOT a pre-formatted "1.99" string),
+     * based on coin decimals metadata (requires metadata to be loaded or set).
+     *
+     * @param {bigint|number|string} amount - raw amount in the coin's base units
+     * @param {Object} [options] - format options
+     * @param {boolean} [options.withAbbr] - append K/M/B/T for large amounts (Suiet-style)
+     * @param {boolean|string} [options.separateThousands] - separate thousands by `,` (true) or by a custom delimiter
      * @returns {string}
      */
     amountToString(amount, options = {}) {
@@ -123,14 +123,14 @@ export default class SuiCoin {
 
     
     /**
-     * Format large amounts
-     * 
+     * Format large amounts.
+     *
      * thanks @bruceeewong and @suiet
-     * 
-     * @param {bigint} amount 
-     * @param {bigint} measureUnit 
-     * @param {string} abbrSymbol 
-     * 
+     *
+     * @param {bigint} amount
+     * @param {bigint} measureUnit - divisor for the unit (1_000n for K, 1_000_000n for M, …)
+     * @param {string} abbrSymbol - suffix to append (K, M, B, T)
+     * @param {boolean|string} [separateThousands=false] - separate thousands by `,` (true) or by a custom delimiter
      * @returns {string}
      */
     formatWithAbbr(amount, measureUnit, abbrSymbol, separateThousands = false) {
@@ -150,10 +150,14 @@ export default class SuiCoin {
     }
 
 
+    /**
+     * @type {SuiMaster}
+     */
     get suiMaster() {
         return this._suiCoins.suiMaster;
     }
 
+    /** @returns {string} coin type string, always prefixed with `0x` */
     get coinType() {
         if (this._coinType.indexOf('0x') === 0) {
             return this._coinType;
@@ -171,6 +175,7 @@ export default class SuiCoin {
         return '0x2::coin::Coin<'+this.coinType+'>';
     }
 
+    /** @returns {number | undefined} decimals from loaded metadata, or `undefined` if not yet loaded */
     get decimals() {
         if (this.metadata) {
             return this.metadata.decimals;
@@ -178,10 +183,12 @@ export default class SuiCoin {
         return undefined;
     }
 
+    /** @returns {?CoinMeta} loaded coin metadata, or null if not loaded */
     get metadata() {
         return this._metadata;
     }
 
+    /** @returns {?string} coin symbol from metadata, or null if metadata isn't loaded */
     get symbol() {
         if (this.metadata) {
             return this.metadata.symbol;
@@ -190,10 +197,19 @@ export default class SuiCoin {
         return null;
     }
 
+    /** @returns {?string} coin name from metadata, or null if metadata isn't loaded */
     get name() {
-        return this.metadata.name;
+        if (this.metadata) {
+            return this.metadata.name;
+        }
+
+        return null;
     }
 
+    /**
+     * True if this coin's type is the normalized SUI type (`0x2::sui::SUI` expanded to 64 hex chars).
+     * @returns {boolean}
+     */
     isSUI() {
         const lc = this._coinType.toLowerCase();
         if (lc == '0x0000000000000000000000000000000000000000000000000000000000000002::sui::sui') { // as it's normalized
@@ -217,6 +233,11 @@ export default class SuiCoin {
         return false;
     }
 
+    /**
+     * Returns true if the object looks like a usable CoinMeta (has positive `decimals`, `name`, `symbol`).
+     * @param {CoinMeta} meta
+     * @returns {boolean}
+     */
     static isValidMetadata(meta) {
         if (meta && meta.decimals && meta.decimals > 0 && meta.name && meta.symbol) {
             return true;
@@ -225,10 +246,10 @@ export default class SuiCoin {
     }
 
     /**
-     * Load coin metadata from the blockchain. As a good pattern, it's better to have metadata hard-coded or cached
-     * and set via suiMaster.suiCoins.setCoinMetas(...)  
-     * 
-     * @returns {Promise.<boolean>}
+     * Load coin metadata from the blockchain. Concurrent callers share the same in-flight request.
+     * As a good pattern, prefer hard-coded / cached metadata set via `suiMaster.suiCoins.setCoinMetas(...)`.
+     *
+     * @returns {Promise<?CoinMeta>} resolved metadata, or `null` if the coin type has none on chain
      */
     async getMetadata() {
         if (this._metadata) {
@@ -243,25 +264,24 @@ export default class SuiCoin {
         this.__getMetadataResolver = null;
         this.__getMetadataPromise = new Promise((res)=>{ this.__getMetadataResolver = res; });
 
-        let result = null;
         try {
-            result = await this.suiMaster.client.getCoinMetadata({
+            const result = await this.suiMaster.client.getCoinMetadata({
                     coinType: this.coinType,
                 });
+            if (result && result.coinMetadata && result.coinMetadata.decimals) {
+                this._exists = true;
+                this._metadata = result.coinMetadata;
+            } else {
+                this._exists = false;
+            }
         } catch (e) {
             console.error(e);
-            result = null;
-        }
-        if (!result) {
             this._exists = false;
-        } else {
-            this._metadata = result;
-            this._exists = true;
         }
 
-        this.__getMetadataResolver(true);
+        this.__getMetadataResolver(this._metadata);
 
-        return true;
+        return this._metadata;
     }
 
     /**
@@ -271,111 +291,33 @@ export default class SuiCoin {
      * @returns {Promise.<bigint>}
      */
     async getBalance(owner) {
-        const coins = [];
-        let result = null;
-        let cursor = null;
-        do {
-            result = await this.suiMaster.client.getCoins({
-                owner: owner,
-                coinType: this.coinType,
-                limit: 50,
-                cursor: cursor,
-            });
-            coins.push(...result.data);
-
-            cursor = result.nextCursor;
-        } while (result.hasNextPage);
-
-        let totalAmount = BigInt(0);
-        for (const coin of coins) {
-            totalAmount = totalAmount + BigInt(coin.balance);
+        const coinBalanceResponse = await this.suiMaster.client.getBalance({
+            owner: owner,
+            coinType: this.coinType,
+        });
+        if (coinBalanceResponse?.balance?.balance) {
+            return BigInt(coinBalanceResponse.balance.balance);
+        } else {
+            return BigInt(0);
         }
-
-        return totalAmount;
     }
 
 
     /**
-     * Returns TransactionObjectArgument with Coin of amount to be used in tranasctions
-     * 
+     * Return a TransactionObjectArgument with a Coin of the requested amount, ready to use in moveCall.
+     * Delegates to the v2 SDK's `tx.coinWithBalance` intent, which at build time fetches all owned
+     * coins of this type, merges them (including zero-balance dust), and splits off the requested amount.
+     *
      * @param {Transaction} txb - Native SUI SDK Transaction
-     * @param {string} owner - address of the owner
-     * @param {BigInt|string} amount - amount of coin. BigIng or String to be normalized via Coin decimals, "0.05" for 0.05 sui
-     * @param {boolean} addEmptyCoins - attach coins == 0 to the list
-     * 
+     * @param {string} _owner - unused; kept for signature compatibility. The resolver picks coins owned by the tx sender.
+     * @param {BigInt|string} amount - amount of coin. BigInt or string normalized via Coin decimals ("0.05" → 0.05 SUI)
      * @returns {Promise.<TransactionObjectArgument>}
      */
-    async coinOfAmountToTxCoin(txb, owner, amount, addEmptyCoins = false) {
+    async coinOfAmountToTxCoin(txb, _owner, amount) {
         const normalizedAmount = await this.lazyNormalizeAmount(amount);
-
-        const expectedAmountAsBigInt = BigInt(normalizedAmount);
-        const coinIds = await this.coinObjectsEnoughForAmount(owner, expectedAmountAsBigInt, addEmptyCoins);
-
-        if (!coinIds || !coinIds.length) {
-            throw new Error('you do not have enough coins of type '+this.coinType);
-        }
-
-        if (coinIds.length == 1) {
-            // only one coin object enough to cover the expense
-            if (this.isSUI()) {
-                const coinInput = txb.add(Commands.SplitCoins(txb.gas, [txb.pure.u64(expectedAmountAsBigInt)]));
-                return coinInput;
-            } else {
-                // some other coin
-                const coinInput = txb.add(Commands.SplitCoins(txb.object(coinIds[0]), [txb.pure.u64(expectedAmountAsBigInt)]));
-                return coinInput;
-            }
-        } else {
-            // few coin objects to merge
-            const coinIdToMergeIn = coinIds.shift();
-            txb.add(Commands.MergeCoins(txb.object(coinIdToMergeIn), coinIds.map((id)=>{return txb.object(id);})));
-            const coinInputSplet = txb.add(Commands.SplitCoins(txb.object(coinIdToMergeIn), [txb.pure.u64(expectedAmountAsBigInt)]));
-
-            return coinInputSplet;
-        }
-    }
-
-    async coinObjectsEnoughForAmount(owner, expectedAmount, addEmptyCoins = false) {
-        const expectedAmountAsBigInt = BigInt(expectedAmount);
-
-        const coinIds = [];
-        const coins = [];
-
-        let result = null;
-        let cursor = null;
-        do {
-            result = await this.suiMaster.client.getCoins({
-                owner: owner,
-                coinType: this.coinType,
-                limit: 50,
-                cursor: cursor,
-            });
-            coins.push(...result.data);
-
-            cursor = result.nextCursor;
-        } while (result.hasNextPage);
-
-        coins.sort((a, b) => {
-            // From big to small
-            return Number(b.balance) - Number(a.balance);
+        return txb.coin({
+            type: this.coinType,
+            balance: BigInt(normalizedAmount),
         });
-
-        let totalAmount = BigInt(0);
-        for (const coin of coins) {
-            if (totalAmount <= expectedAmountAsBigInt) {
-                coinIds.push(coin.coinObjectId);
-                totalAmount = totalAmount + BigInt(coin.balance);//  totalAmount.add(coin.balance);
-            } else {
-                if (addEmptyCoins && BigInt(coin.balance) == 0n) {
-                    coinIds.push(coin.coinObjectId);
-                }
-            }
-        }
-
-        if (totalAmount >= expectedAmountAsBigInt) {
-            return coinIds;
-        }
-
-        return null;
     }
 };

package/lib/SuiCoins.js

@@ -21,10 +21,11 @@ export default class SuiCoins extends SuiCommonMethods {
      * SuiCoins constructor
      * @param {Object} params - Initialization parameters
      * @param {SuiMaster} params.suiMaster - instance of SuiMaster
+     * @param {boolean} [params.debug]
      */
-    constructor(params = {}) {
+    constructor(params) {
         super(params);
-        
+
         /** @type {SuiMaster} */
         this._suiMaster = params.suiMaster;
         if (!this._suiMaster) {
@@ -40,17 +41,22 @@ export default class SuiCoins extends SuiCommonMethods {
         }
     }
 
+    /**
+     * @type {SuiMaster}
+     */
     get suiMaster() {
         return this._suiMaster;
     }
 
+    /** @returns {Object.<string, SuiCoin>} map of coinType → SuiCoin instance */
     get coins() {
         return this._coins;
     }
 
     /**
-     * set predefined coin metas so they will not be fetched from RPC
-     * @param {(Object.<string, CoinMeta> | Array.<CoinMeta>)}
+     * Set predefined coin metas so they will not need to be fetched from RPC.
+     *
+     * @param {Object.<string, CoinMeta> | Array.<CoinMeta>} coinMetas - keyed map by coin type, or an array of CoinMeta with `type` field
      * @returns {number} count of processed items
      */
     setCoinMetas(coinMetas) {
@@ -80,6 +86,12 @@ export default class SuiCoins extends SuiCommonMethods {
         return processedCount;
     }
 
+    /**
+     * Fetch the mainnet coin metadata bundle from `coinmeta.polymedia.app` and cache the promise so
+     * concurrent callers share a single request. Failures are swallowed and resolve to an empty array.
+     *
+     * @returns {Promise<Array.<CoinMeta>>} list of CoinMeta records, or an empty array on failure
+     */
     static async prefetchMainnetCoinMetas() {
         if (this.__preloadPromise) {
             return this.__preloadPromise;
@@ -109,12 +121,11 @@ export default class SuiCoins extends SuiCommonMethods {
     }
 
     /**
-     * Get all CoinBalance[] for the specific address or connected address
-     * 
-     * @param {Object} params
-     * @param {string?} params.owner - owner address, if skipped - will query for connected wallet address
-     * 
-     * @returns {Promise.<Array.<SuidoubleCoinBalance>>}
+     * Get all CoinBalance[] for the specific address or connected address.
+     *
+     * @param {Object} [params]
+     * @param {?string} [params.owner] - owner address; if omitted, uses the connected SuiMaster address
+     * @returns {Promise<Array<SuidoubleCoinBalance>>}
      */
     async getAllBalances(params = {}) {
         let owner = params.owner;
@@ -125,21 +136,22 @@ export default class SuiCoins extends SuiCommonMethods {
         /** @type {Array.<SuidoubleCoinBalance>} */
         const ret = [];
 
-        const nativeCoinBalances = await this._suiMaster.client.getAllBalances({
-                owner,
-            });
-
-        for (const nativeCoinBalance of nativeCoinBalances) {
-            /** @type {SuidoubleCoinBalance} */
-            const coinBalance = {
-                coin: this.get(nativeCoinBalance.coinType),
-                coinType: nativeCoinBalance.coinType,
-                coinObjectCount: nativeCoinBalance.coinObjectCount,
-                totalBalance: BigInt(nativeCoinBalance.totalBalance),
-                lockedBalance: nativeCoinBalance.lockedBalance,                
-            };
-            ret.push(coinBalance);
-        }
+        let cursor = null;
+        do {
+            const response = await this._suiMaster.client.listBalances({ owner, cursor });
+            for (const responseItem of (response?.balances ?? [])) {
+                /** @type {SuidoubleCoinBalance} */
+                ret.push({
+                    coin: this.get(responseItem.coinType),
+                    coinType: responseItem.coinType,
+                    balance: responseItem.balance,
+                    coinBalance: responseItem.balance,
+                    addressBalance: responseItem.addressBalance,
+                    totalBalance: BigInt(responseItem.balance),
+                });
+            }
+            cursor = response?.hasNextPage ? response.cursor : null;
+        } while (cursor);
 
         return ret;
     }
@@ -168,10 +180,10 @@ export default class SuiCoins extends SuiCommonMethods {
     }
 
     /**
-     * Return instance of SuiCoin of specific type
-     * 
+     * Return instance of SuiCoin of specific type. The result is cached per normalized coin type,
+     * so repeated calls with equivalent inputs return the same instance.
+     *
      * @param {string} coinType - MoveType, or 'SUI' as helper
-     * 
      * @returns {SuiCoin}
      */
     get(coinType) {
@@ -200,7 +212,7 @@ export default class SuiCoins extends SuiCommonMethods {
      * @param {SuiMaster} params.suiMaster - instance of SuiMaster
      * @returns {SuiCoins}
      */
-    static getSingleton(params = {}) {
+    static getSingleton(params) {
         const suiMaster = params.suiMaster;
         const connectedChain = suiMaster.connectedChain;
 

package/lib/SuiCommonMethods.js

@@ -1,37 +1,74 @@
-
-
+/**
+ * Minimal `CustomEvent` polyfill — `globalThis.CustomEvent` is not universally available
+ * in Node runtimes, so suidouble dispatches its own class with a `detail` field.
+ */
 class CustomEvent extends Event {
 	#detail;
 
+	/**
+	 * @param {string} type
+	 * @param {EventInit & { detail?: * }} [options]
+	 */
 	constructor(type, options) {
 		super(type, options);
 		this.#detail = options?.detail ?? null;
 	}
 
+	/** @returns {*} the payload passed via `options.detail` at construction time, or null */
 	get detail() {
 		return this.#detail;
 	}
 }
 
+/**
+ * Base class for suidouble domain objects. Extends `EventTarget` so subclasses can emit
+ * events via `this.emit(...)` and consumers can subscribe via `addEventListener(...)`.
+ * Also provides a debug-gated `log(...)` helper.
+ */
 export default class SuiCommonMethods extends EventTarget {
+    /**
+     * @param {Object} [params]
+     * @param {boolean} [params.debug] - enable debug logging via `log(...)`
+     */
     constructor(params = {}) {
 		super();
 
         this._debug = !!params.debug;
     }
 
+	/**
+	 * Debug logger. No-op unless the instance was constructed with `debug: true`.
+	 * Prefixes messages with the owning SuiMaster's instance number (if available) 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+' |' : '') );
 
 		args.unshift(this.constructor.name+' |');
 		args.unshift(prefix);
 		console.info.apply(null, args);
 	}
 
+	/**
+	 * Dispatch an event to registered `addEventListener` subscribers.
+	 *
+	 * If `data` is a `SuiEvent` (has `isSuiEvent === true`) and `forceCustom` is falsy, it is dispatched
+	 * directly so its own `.type` (the Move event name) is used — this lets consumers
+	 * `addEventListener('ChatShopCreated', …)` without wrapping. Otherwise dispatches a `CustomEvent`
+	 * of type `eventType` with `data` placed on the event's `detail` field.
+	 *
+	 * Any dispatch errors are caught and logged to `console.error` so a buggy listener can't abort the
+	 * surrounding flow.
+	 *
+	 * @param {string} eventType - event name when wrapping in a CustomEvent (ignored for direct SuiEvent dispatch)
+	 * @param {*} data - payload; SuiEvent is dispatched directly, anything else is wrapped
+	 * @param {boolean} [forceCustom=false] - if true, always wrap in a CustomEvent even for SuiEvent payloads
+	 */
 	emit(eventType, data, forceCustom = false) {
 		try {
 			if (data && data.isSuiEvent && !forceCustom) {