suidouble 2.5.0 → 2.16.0

package/test/sui_object_properties.test.js

@@ -0,0 +1,85 @@
+'use strict'
+
+import t from 'tap';
+import { SuiMaster, SuiLocalTestValidator } from '../index.js';
+
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const { test } = t;
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+let suiLocalTestValidator = null;
+let suiMaster = null;
+let contract = null;
+
+test('spawn local test node', async t => {
+    suiLocalTestValidator = await SuiLocalTestValidator.launch({ testFallbackEnabled: true });
+    t.ok(suiLocalTestValidator.active);
+});
+
+test('setup — init, fund, publish', async t => {
+    suiMaster = new SuiMaster({ client: suiLocalTestValidator, as: 'somebody', debug: false });
+    await suiMaster.initialize();
+
+    await suiMaster.requestSuiFromFaucet();
+
+    contract = suiMaster.addPackage({
+        path: path.join(__dirname, './test_move_contracts/suidouble_chat/'),
+    });
+    await contract.build();
+    await contract.publish();
+    t.ok(contract.address, 'contract published');
+});
+
+test('localProperties — stores arbitrary data without touching the chain', async t => {
+    const chatShop = suiMaster.objectStorage.findMostRecentByTypeName('ChatShop');
+    t.ok(chatShop, 'ChatShop found in objectStorage');
+
+    // initial state — empty object
+    t.type(chatShop.localProperties, 'object', 'localProperties is an object');
+    t.notOk(chatShop.localProperties.myKey, 'myKey not set initially');
+
+    // write
+    chatShop.localProperties.myKey = 'hello';
+    chatShop.localProperties.count  = 42;
+
+    // read back from the same instance
+    t.equal(chatShop.localProperties.myKey, 'hello', 'myKey persists on the instance');
+    t.equal(chatShop.localProperties.count, 42, 'count persists on the instance');
+
+    // does NOT affect the object on chain — the object's fields are unrelated
+    t.notOk(chatShop.fields.myKey, 'myKey is not in on-chain fields');
+
+    // clear
+    delete chatShop.localProperties.myKey;
+    t.notOk(chatShop.localProperties.myKey, 'myKey removed after delete');
+});
+
+test('isImmutable — published package object is immutable', async t => {
+    // packages are always frozen / immutable on Sui after publishing
+    const packageObj = await suiMaster.getObject(contract.address);
+    t.ok(packageObj, 'package object fetched');
+    t.ok(packageObj.isImmutable, 'package object isImmutable is true');
+    t.notOk(packageObj.isShared, 'package object isShared is false');
+});
+
+test('display — fetchFields populates display property', async t => {
+    const chatShop = suiMaster.objectStorage.findMostRecentByTypeName('ChatShop');
+    t.ok(chatShop, 'ChatShop found');
+
+    await chatShop.fetchFields();
+
+    // display is always an object — {} when no Display template, otherwise keyed values
+    t.type(chatShop.display, 'object', 'display is an object after fetchFields');
+
+    // suidouble_chat has no Display template so we expect an empty map —
+    // but the field must exist and not throw
+    t.doesNotThrow(() => { void chatShop.display; }, 'accessing display does not throw');
+});
+
+test('stops local test node', async t => {
+    await SuiLocalTestValidator.stop().catch(() => {});
+    t.pass('stopped');
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationDir": "./types",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "ES2020",
+    "strict": false,
+    "skipLibCheck": true,
+    "checkJs": false
+  },
+  "include": ["index.js", "lib/*.js"]
+}

package/types/index.d.ts

@@ -0,0 +1,15 @@
+import SuiMaster from './lib/SuiMaster.js';
+import SuiObject from './lib/SuiObject.js';
+import SuiInBrowser from './lib/SuiInBrowser.js';
+import SuiLocalTestValidator from './lib/SuiLocalTestValidator.js';
+export const MIST_PER_SUI: bigint;
+import { Transaction } from '@mysten/sui/transactions';
+import { TransactionCommands as Commands } from '@mysten/sui/transactions';
+import SuiUtils from './lib/SuiUtils.js';
+export const txInput: typeof SuiUtils.txInput;
+import { bcs } from '@mysten/sui/bcs';
+import SuiMemoryObjectStorage from './lib/SuiMemoryObjectStorage.js';
+import SuiCoin from './lib/SuiCoin.js';
+import SuiCoins from './lib/SuiCoins.js';
+import SuiPaginatedResponse from './lib/SuiPaginatedResponse.js';
+export { SuiMaster, SuiObject, SuiInBrowser, SuiLocalTestValidator, Transaction, Commands, SuiUtils, bcs, SuiMemoryObjectStorage, SuiCoin, SuiCoins, SuiPaginatedResponse };

package/types/lib/SuiCliCommands.d.ts

@@ -0,0 +1,6 @@
+export default class SuiCliCommands {
+    static isPortThere(port: any): Promise<any>;
+    static spawn(command: any, params?: any[], envVars?: {}): Promise<any>;
+    static exec(command: any): Promise<any>;
+    static getModulesNamesFromPackagePath(path: any): Promise<any>;
+}

package/types/lib/SuiCoin.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @typedef {import("@mysten/sui/transactions").TransactionObjectArgument} TransactionObjectArgument
+ *
+ * @import { SuiClientTypes } from "@mysten/sui/client"
+ *
+ * @typedef CoinMeta
+ * @type {object}
+ * @property {number} decimals - Number of decimal places the coin uses.
+ * @property {string} description - Description of the token
+ * @property {string} iconUrl - URL for the token logo
+ * @property {string} name - Name for the token
+ * @property {string} symbol - Symbol for the token
+ * @property {string} [id] - Meta id
+ * @property {string} [type] - Coin type string
+ *
+ *
+ * @typedef {SuiClientTypes.Balance & { coin: SuiCoin, totalBalance: bigint }} SuidoubleCoinBalance
+ * @typedef {import("./SuiMaster.js").default} SuiMaster
+ * @typedef {import("./SuiCoins.js").default} SuiCoins
+ */
+/**
+ * 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 {
+    /**
+     * Returns true if the object looks like a usable CoinMeta (has positive `decimals`, `name`, `symbol`).
+     * @param {CoinMeta} meta
+     * @returns {boolean}
+     */
+    static isValidMetadata(meta: CoinMeta): boolean;
+    /**
+     * SuiCoin constructor
+     * @param {Object} params - Initialization parameters
+     * @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: {
+        coinType: string;
+        suiCoins: SuiCoins;
+    });
+    _coinType: string;
+    _suiCoins: import("./SuiCoins.js").default;
+    _exists: boolean;
+    _metadata: CoinMeta | SuiClientTypes.CoinMetadata;
+    /**
+     * Normalize amount based on .decimals. Pass a string with a dot ('5.22', '0.0005') to convert it to units
+     * always use a dot, event for '1.0' or '100.0'.
+     * @param {String|Number|BigInt} amount
+     * @returns {BigInt}
+     */
+    normalizeAmount(amount: string | number | bigint): bigint;
+    /**
+     * Normalize amount based on .decimals. Pass a string with a dot ('5.22', '0.0005') to convert it to units. No worries about loading metadata first.
+     * @param {String|Number|bigint} amount
+     * @returns {Promise.<bigint>}
+     */
+    lazyNormalizeAmount(amount: string | number | bigint): Promise<bigint>;
+    /**
+     * 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: bigint | number | string, options?: {
+        withAbbr?: boolean;
+        separateThousands?: boolean | string;
+    }): string;
+    /**
+     * Format large amounts.
+     *
+     * thanks @bruceeewong and @suiet
+     *
+     * @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: bigint, measureUnit: bigint, abbrSymbol: string, separateThousands?: boolean | string): string;
+    /**
+     * @type {SuiMaster}
+     */
+    get suiMaster(): SuiMaster;
+    /** @returns {string} coin type string, always prefixed with `0x` */
+    get coinType(): string;
+    /**
+     * Move type for the Coin object of this coin type
+     *
+     * @type {string}
+     */
+    get coinObjectType(): string;
+    /** @returns {number | undefined} decimals from loaded metadata, or `undefined` if not yet loaded */
+    get decimals(): number | undefined;
+    /** @returns {?CoinMeta} loaded coin metadata, or null if not loaded */
+    get metadata(): CoinMeta | null;
+    /** @returns {?string} coin symbol from metadata, or null if metadata isn't loaded */
+    get symbol(): string | null;
+    /** @returns {?string} coin name from metadata, or null if metadata isn't loaded */
+    get name(): string | null;
+    /**
+     * True if this coin's type is the normalized SUI type (`0x2::sui::SUI` expanded to 64 hex chars).
+     * @returns {boolean}
+     */
+    isSUI(): boolean;
+    /**
+     * set predefined coin metadata so it will not be fetched from RPC
+     * @param {CoinMeta} meta
+     *
+     * @returns {boolean} if processed ok
+     */
+    setMetadata(meta: CoinMeta): 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
+     */
+    getMetadata(): Promise<CoinMeta | null>;
+    __getMetadataResolver: (value: any) => void;
+    __getMetadataPromise: Promise<any>;
+    /**
+     * Get coin balance of the wallet
+     * @param {string} owner
+     *
+     * @returns {Promise.<bigint>}
+     */
+    getBalance(owner: string): Promise<bigint>;
+    /**
+     * 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 - 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>}
+     */
+    coinOfAmountToTxCoin(txb: Transaction, _owner: string, amount: bigint | string): Promise<TransactionObjectArgument>;
+}
+export type TransactionObjectArgument = import("@mysten/sui/transactions").TransactionObjectArgument;
+export type CoinMeta = {
+    /**
+     * - Number of decimal places the coin uses.
+     */
+    decimals: number;
+    /**
+     * - Description of the token
+     */
+    description: string;
+    /**
+     * - URL for the token logo
+     */
+    iconUrl: string;
+    /**
+     * - Name for the token
+     */
+    name: string;
+    /**
+     * - Symbol for the token
+     */
+    symbol: string;
+    /**
+     * - Meta id
+     */
+    id?: string;
+    /**
+     * - Coin type string
+     */
+    type?: string;
+};
+export type SuidoubleCoinBalance = SuiClientTypes.Balance & {
+    coin: SuiCoin;
+    totalBalance: bigint;
+};
+export type SuiMaster = import("./SuiMaster.js").default;
+export type SuiCoins = import("./SuiCoins.js").default;
+import type { SuiClientTypes } from "@mysten/sui/client";
+import { Transaction } from '@mysten/sui/transactions';

package/types/lib/SuiCoins.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @typedef {import("./SuiCoin.js").CoinMeta} CoinMeta
+ * @typedef {import("./SuiCoin.js").SuidoubleCoinBalance} SuidoubleCoinBalance
+ * @typedef {import("./SuiMaster.js").default} SuiMaster
+ */
+/**
+ * Common class to work with Coins and Coin objects. Expected to have single instance per SuiMaster instance
+ * @class
+ * @constructor
+ * @public
+ */
+export default class SuiCoins extends SuiCommonMethods {
+    /**
+     * 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 prefetchMainnetCoinMetas(): Promise<Array<CoinMeta>>;
+    static _singleInstances: {};
+    /**
+     * Return singleton instance of the SuiCoins object for the specific chain
+     *
+     * @param {Object} params - parameters
+     * @param {SuiMaster} params.suiMaster - instance of SuiMaster
+     * @returns {SuiCoins}
+     */
+    static getSingleton(params: {
+        suiMaster: SuiMaster;
+    }): SuiCoins;
+    /**
+     * SuiCoins constructor
+     * @param {Object} params - Initialization parameters
+     * @param {SuiMaster} params.suiMaster - instance of SuiMaster
+     * @param {boolean} [params.debug]
+     */
+    constructor(params: {
+        suiMaster: SuiMaster;
+        debug?: boolean;
+    });
+    /** @type {SuiMaster} */
+    _suiMaster: SuiMaster;
+    /** @type {Object.<string, SuiCoin>} */
+    _coins: {
+        [x: string]: SuiCoin;
+    };
+    /**
+     * @type {SuiMaster}
+     */
+    get suiMaster(): SuiMaster;
+    /** @returns {Object.<string, SuiCoin>} map of coinType → SuiCoin instance */
+    get coins(): {
+        [x: string]: SuiCoin;
+    };
+    /**
+     * 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: {
+        [x: string]: CoinMeta;
+    } | Array<CoinMeta>): number;
+    /**
+     * 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>>}
+     */
+    getAllBalances(params?: {
+        owner?: string | null;
+    }): Promise<Array<SuidoubleCoinBalance>>;
+    /**
+     * normalize coinType string to sui's coin type. As extra, may take 'sui' or 'SUI' as the type and return type for it
+     * @param {string} coinType
+     * @returns {string} normalized coin type
+     */
+    normalizeCoinType(coinType: string): string;
+    /**
+     * 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: string): SuiCoin;
+}
+export type CoinMeta = import("./SuiCoin.js").CoinMeta;
+export type SuidoubleCoinBalance = import("./SuiCoin.js").SuidoubleCoinBalance;
+export type SuiMaster = import("./SuiMaster.js").default;
+import SuiCommonMethods from './SuiCommonMethods.js';
+import SuiCoin from './SuiCoin.js';

package/types/lib/SuiCommonMethods.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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?: {
+        debug?: boolean;
+    });
+    _debug: boolean;
+    /**
+     * 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: any[]): void;
+    /**
+     * 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: string, data: any, forceCustom?: boolean): void;
+}

package/types/lib/SuiEvent.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @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 {
+    /**
+     * @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: {
+        suiMaster: SuiMaster;
+        data?: SuiEventData;
+        debug?: boolean;
+    });
+    _debug: boolean;
+    /** @type {SuiMaster} */
+    _suiMaster: SuiMaster;
+    /** @type {SuiEventData} */
+    _data: SuiEventData;
+    detail: this;
+    /**
+     * 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: any[]): void;
+    /** Brand property for duck-typing. @returns {true} */
+    get isSuiEvent(): true;
+    /**
+     * In-module type name — last segment of `package::module::Name<...>`, without package/module prefix or `<T..>` suffix.
+     * @returns {?string}
+     */
+    get typeName(): string | null;
+    /**
+     * Raw event data as received from the client.
+     * @returns {SuiEventData}
+     */
+    get data(): SuiEventData;
+    /**
+     * JSON representation of the event's Move struct contents.
+     * @returns {?Object}
+     */
+    get parsedJson(): any | null;
+    /**
+     * Timestamp (milliseconds since epoch) of the checkpoint the emitting transaction was finalized in.
+     * @returns {?number}
+     */
+    get timestampMs(): number | null;
+}
+export type SuiMaster = import("./SuiMaster.js").default;
+export type SuiEventData = {
+    /**
+     * - Fully-qualified Move type of the event, e.g. `<pkg>::<module>::<EventName>`
+     */
+    type?: string;
+    /**
+     * - JSON representation of the event's Move struct contents
+     */
+    parsedJson?: any;
+    /**
+     * - Timestamp (ms since epoch) of the checkpoint the event's tx was finalized in
+     */
+    timestampMs?: string | number;
+    /**
+     * - SuiAddress of the sender of the emitting transaction
+     */
+    sender?: string;
+    /**
+     * - Digest of the emitting transaction
+     */
+    transactionDigest?: string;
+    /**
+     * - Event position within its transaction
+     */
+    sequenceNumber?: string | number;
+    /**
+     * - BCS bytes (base64 string from GraphQL, Uint8Array from gRPC)
+     */
+    bcs?: string | Uint8Array;
+};