suidouble 2.5.0 → 2.17.0-1

package/lib/SuiMaster.js

@@ -20,25 +20,28 @@ import { decodeSuiPrivateKey  } from '@mysten/sui/cryptography';
 
 
 /**
- * @typedef {import("@mysten/sui/jsonRpc").SuiJsonRpcClient} SuiJsonRpcClient
+ * @import { SuiClientTypes } from "@mysten/sui/client"
+ * 
+ * @typedef {import("@mysten/sui/grpc").SuiGrpcClient} SuiGrpcClient
+ * @typedef {import("@mysten/sui/graphql").SuiGraphQLClient} SuiGraphQLClient
  * @typedef {import("@mysten/sui/cryptography").Signer} SuiSigner
  * @typedef {import("@mysten/sui/cryptography").Keypair} SuiKeypair
- * @typedef {import("@mysten/sui/jsonRpc").SuiTransactionBlockResponse} SuiTransactionBlockResponse
+ * @typedef {import("./SuiInBrowser.js").default} SuiInBrowser
  */
 
 export default class SuiMaster extends SuiCommonMethods {
     /**
      * SuiMaster constructor
      * @param {Object} params - Initialization parameters
-     * @param {?SuiSigner} params.signer - instance of Sui SDK Signer (like Keypair)
-     * @param {?SuiKeypair} params.keypair - instance of Sui SDK Keypair
-     * @param {?string} param.privateKey - private key in Sui format, starting with "suiprivkey1"
-     * @param {?boolean} param.debug - enable debug mode
-     * @param {?string} param.phrase - mnemonic phrase to derive keypair from
-     * @param {?string} param.keypairAlgo - keypair algorithm to use with mnemonic phrase. One of 'ed25519' (default), 'secp256k1', 'secp256r1'
-     * @param {?number} param.accountIndex - index of account to derive from mnemonic phrase. Default is 0
-     * @param {?string} param.as - pseudo-random address generation seed string
-     * @param {?SuiJsonRpcClient|string} params.client - instance of SuiJsonRpcClient or chain name to make SuiJsonRpcClient connected to it (like 'local', 'devnet', 'testnet', 'mainnet')
+     * @param {SuiSigner|SuiInBrowser} [params.signer] - instance of Sui SDK Signer (like Keypair) or SuiInBrowser for browser wallet signing
+     * @param {SuiKeypair} [params.keypair] - instance of Sui SDK Keypair
+     * @param {string} [params.privateKey] - private key in Sui format, starting with "suiprivkey1"
+     * @param {boolean} [params.debug] - enable debug mode
+     * @param {string} [params.phrase] - mnemonic phrase to derive keypair from
+     * @param {string} [params.keypairAlgo] - keypair algorithm to use with mnemonic phrase. One of 'ed25519' (default), 'secp256k1', 'secp256r1'
+     * @param {number} [params.accountIndex] - index of account to derive from mnemonic phrase. Default is 0
+     * @param {string} [params.as] - pseudo-random address generation seed string
+     * @param {SuiGrpcClient|string} [params.client] - instance of SuiGrpcClient or chain name to make SuiGrpcClient connected to it (like 'local', 'devnet', 'testnet', 'mainnet')
      */
     constructor(params) {
         super(params);
@@ -47,7 +50,7 @@ export default class SuiMaster extends SuiCommonMethods {
         SuiMaster.instancesCount++;
         this._instanceN = SuiMaster.instancesCount;
 
-        /** @type {SuiSigner} */
+        /** @type {SuiSigner|SuiInBrowser|null} */
         this._signer = null;
         /** @type {SuiKeypair} */
         this._keypair = null;
@@ -57,8 +60,8 @@ export default class SuiMaster extends SuiCommonMethods {
 
         if (params.signer) {
             this._signer = params.signer;
-            if (this._signer && this._signer.connectedAddress) {
-                this._address = this._signer.connectedAddress;
+            if (this._signer && /** @type {any} */ (this._signer).connectedAddress) {
+                this._address = /** @type {any} */ (this._signer).connectedAddress;
             }
         } else if (params.keypair) {
             this._keypair = params.keypair;
@@ -102,19 +105,24 @@ export default class SuiMaster extends SuiCommonMethods {
                 }
             }
 
-            this.log('goint to use keypair of', this._keypair.getPublicKey().toSuiAddress());
+            this.log('going to use keypair of', this._keypair.getPublicKey().toSuiAddress());
         } else if (params.as) {
             // generate pseudo-random keypair
             this._keypair = SuiPseudoRandomAddress.stringToKeyPair(params.as);
 
-            this.log('goint to use keypair of', this._keypair.getPublicKey().toSuiAddress());
+            this.log('going to use keypair of', this._keypair.getPublicKey().toSuiAddress());
         }
 
 
-        /** @type {SuiClient} */
+        /** @type {SuiGrpcClient} */
         this._client = SuiUtils.normalizeClient(params.client);
+        /**
+         * Lazy — do not read directly, use the `graphqlClient` getter so it's built on first access.
+         * @type {?SuiGraphQLClient}
+         */
+        this._graphqlClient = null;
         /** @type {string} */
-        this._providerName = this._client ? this._client.providerName : null;
+        this._providerName = this._client.network;
 
         if (!this._client) {
             throw new Error('Can not do anything without Sui client. Set params.client at least to `local`, so we can make default one for the chain');
@@ -140,6 +148,7 @@ export default class SuiMaster extends SuiCommonMethods {
         });
     }
 
+    /** @returns {typeof SuiUtils} static SuiUtils helper class */
     get utils() {
         return SuiUtils;
     }
@@ -153,14 +162,17 @@ export default class SuiMaster extends SuiCommonMethods {
         return this._suiCoins;
     }
 
+    /** @returns {bigint} `1_000_000_000n` — number of MIST per SUI */
     get MIST_PER_SUI() {
         return BigInt(MIST_PER_SUI);
     }
 
+    /** @returns {typeof Transaction} SDK `Transaction` class, exposed to avoid extra imports at call sites */
     get Transaction() {
         return Transaction;
     }
 
+    /** @returns {typeof Commands} SDK `TransactionCommands` class, exposed to avoid extra imports at call sites */
     get Commands() {
         return Commands;
     }
@@ -189,27 +201,39 @@ export default class SuiMaster extends SuiCommonMethods {
     get SuiPaginatedResponse() {
         return SuiPaginatedResponse;
     }
-    /**
-
     /**
      * Storage storing all objects interacted by this suiMaster
-     * 
+     *
      * @type {SuiMemoryObjectStorage}
      */
     get objectStorage() {
         return this._objectStorage;
     }
 
+    /** @returns {number} monotonically increasing instance counter, useful for differentiating logs */
     get instanceN() {
         return this._instanceN;
     }
 
     static instancesCount = 0;
 
+    /** @returns {SuiGrpcClient} gRPC client for the connected chain */
     get client() {
         return this._client;
     }
 
+    /**
+     * Lazily-built SuiGraphQLClient that reuses the network of this suiMaster's gRPC client.
+     * @returns {SuiGraphQLClient}
+     */
+    get graphqlClient() {
+        if (!this._graphqlClient) {
+            this._graphqlClient = SuiUtils.suiGraphQLClientFromGrpc(this._client);
+        }
+        return this._graphqlClient;
+    }
+
+    /** @returns {string} connected chain identifier, e.g. `'mainnet'` or `'localnet'` */
     get connectedChain() {
         return this._providerName;
     }
@@ -219,6 +243,7 @@ export default class SuiMaster extends SuiCommonMethods {
      * @returns {boolean} is on mainnet
      */
     get onMainnet() {
+        // @todo: 
         const provider = this._providerName.split('sui:').join('').toLowerCase();
         if (provider === 'mainnet') {
             return true;
@@ -227,10 +252,12 @@ export default class SuiMaster extends SuiCommonMethods {
         return false;
     }
 
+    /** @returns {?string} connected Sui address, or null in read-only mode before `initialize()` */
     get address() {
         return this._address;
     }
 
+    /** @returns {SuiSigner|SuiInBrowser|null} active signer/keypair, or null in read-only mode */
     get signer() {
         return this._signer;
     }
@@ -276,11 +303,20 @@ export default class SuiMaster extends SuiCommonMethods {
         return suiPackage;
     }
 
+    /**
+     * Ensure `initialize()` has run, then return the gRPC client.
+     * @returns {Promise<SuiGrpcClient>}
+     */
     async getClient() {
         await this.initialize();
         return this._client;
     }
 
+    /**
+     * Resolve the connected address from the signer/keypair (if any) and mark the instance as
+     * ready. Idempotent — subsequent calls return immediately.
+     * @returns {Promise<boolean>}
+     */
     async initialize() {
         if (this._initialized) {
             return true;
@@ -295,12 +331,13 @@ export default class SuiMaster extends SuiCommonMethods {
         }
 
         if (this._signer) {
-            if (this._signer.toSuiAddress) {
-                this._address = this._signer.toSuiAddress();    // after Sui's refactor Keypair's method
-            } else if (this._signer.connectedAddress) {
-                this._address = this._signer.connectedAddress;
+            const s = /** @type {any} */ (this._signer);
+            if (s.toSuiAddress) {
+                this._address = s.toSuiAddress();    // after Sui's refactor Keypair's method
+            } else if (s.connectedAddress) {
+                this._address = s.connectedAddress;
             } else {
-                this._address = await this._signer.getAddress(); // old method
+                this._address = await s.getAddress(); // old method
             }
 
             this.log('initialized. connected as', this._address);
@@ -313,118 +350,251 @@ export default class SuiMaster extends SuiCommonMethods {
     }
 
     /**
-     * Return the first resolved name for the connected wallet if there's any, null otherwise
-     * 
-     * @param {Object} params parameters
-     * @param {'at' | 'dot' | undefined} params.format
-     * 
-     * @returns {string | null}
+     * Return the primary Name Service name for the connected wallet address, or null if none.
+     * Uses `client.core.defaultNameServiceName` (v2 gRPC).
+     * @returns {Promise<string | null>}
      */
-    async resolveNameServiceName(params = {}) {
-        const resolvedNames = await this.resolveNameServiceNames(params);
-        if (resolvedNames && resolvedNames.length) {
-            return resolvedNames[0];
+    async defaultNameServiceName() {
+        if (!this._address) {
+            return null;
+        }
+
+        try {
+            const resp = await this._client.core.defaultNameServiceName({
+                address: this._address,
+            });
+            return resp?.data?.name ?? null;
+        } catch (e) {
+            return null;
         }
-        return null;
     }
 
     /**
-     * Return the resolved names for the connected wallet, if multiple names are resolved, the first one is the primary name.
-     * Currently returns array with only the first name
-     * @param {Object} params parameters
-     * @param {'at' | 'dot' | undefined} params.format
-     * 
-     * @returns {Array.<string>}
+     * Fetch many on-chain objects. The v2 client batches internally (50 per request).
+     *
+     * Per-item behavior:
+     *   - if a `SuiObject` is passed in, it is updated in place via `replaceWithSuiObjectIfNeeded`
+     *     and returned at its original index in the output array (same instance reference).
+     *   - if a string id is passed in, a freshly-constructed `SuiObject` is returned at that index.
+     *   - if an item couldn't be matched in the response, the original (or a new bare) SuiObject is
+     *     still placed at that index — no nulls, no skipped slots.
+     *
+     * Errors-in-results entries from the client are skipped silently. Returns `[]` for empty input.
+     *
+     * @param {Array<string | SuiObject>} idsOrSuiObjects - mix of object ids and/or SuiObject instances
+     * @param {SuiClientTypes.ObjectInclude} [include] - fields to include; defaults to content/json/display
+     * @returns {Promise<SuiObject[]>} array aligned with input order
      */
-    async resolveNameServiceNames(params = {}) {
-        if (!this._address) {
+    async getObjects(idsOrSuiObjects, include) {
+        if (!Array.isArray(idsOrSuiObjects) || idsOrSuiObjects.length === 0) {
             return [];
         }
 
-        try {
-            const resp = await this._client.resolveNameServiceNames({
-                    address: this.address,
-                    format: params.format,
-                });
-            if (resp && resp.data) {
-                return resp.data;
+        const slots = idsOrSuiObjects.map((item) => {
+            const a = /** @type {any} */ (item);
+            if (a && a.address) {
+                return { id: a.address, obj: /** @type {SuiObject} */ (a) };
             }
+            const id = '' + a;
+            return {
+                id,
+                obj: new SuiObject({ suiMaster: this, debug: this._debug, id }),
+            };
+        });
+
+        const uniqueIds = [];
+        for (const s of slots) {
+            if (s.id && uniqueIds.indexOf(s.id) === -1) uniqueIds.push(s.id);
+        }
+
+        let raws = [];
+        try {
+            const { objects } = await this._client.getObjects({
+                objectIds: uniqueIds,
+                include: include || { content: true, json: true, display: true },
+            });
+            raws = (objects || []).filter((entry) => entry && !(entry instanceof Error) && entry.objectId);
         } catch (e) {
-            return [];
+            console.error(e);
+        }
+
+        for (const slot of slots) {
+            const raw = raws.find((r) => slot.obj.idEquals(r.objectId));
+            if (!raw) continue;
+            const fresh = new SuiObject({ suiMaster: this, debug: this._debug, raw });
+            slot.obj.replaceWithSuiObjectIfNeeded(fresh);
         }
+
+        return slots.map((s) => s.obj);
+    }
+
+    /**
+     * Fetch a single on-chain object and return it wrapped in a SuiObject.
+     *
+     * @param {string | SuiObject} idOrSuiObject - object id, or a SuiObject instance whose `.address` will be used
+     * @param {SuiClientTypes.ObjectInclude} [include] - fields to include; defaults to content/json/display
+     * @returns {Promise<?SuiObject>} SuiObject populated from the api, or null if not found
+     */
+    async getObject(idOrSuiObject, include) {
+        const a = /** @type {any} */ (idOrSuiObject);
+        const objectId = (a && a.address) ? a.address : a;
+
+        const { object } = await this._client.getObject({
+            objectId,
+            include: include || { content: true, json: true, display: true },
+        });
+
+        if (!object) return null;
+
+        return new SuiObject({
+            suiMaster: this,
+            debug: this._debug,
+            raw: object,
+        });
+    }
+
+    /**
+     * List objects owned by an address. Picks the right backend based on `input.type`:
+     *
+     *   - no type / full struct type (`pkg::mod::Struct[<...>]`) → gRPC `listOwnedObjects` (fast path)
+     *   - package (`pkg`) or module (`pkg::mod`) filter → GraphQL `address.objects` (gRPC can't parse those)
+     *
+     * @param {SuiClientTypes.ListOwnedObjectsOptions<SuiClientTypes.ObjectInclude>} input
+     * @param {Object} [extra]
+     * @param {string} [extra.order]
+     * @returns {Promise<SuiPaginatedResponse<SuiObject>>}
+     */
+    async getOwnedObjects(input, extra = {}) {
+        const useGraphql = SuiMaster._typeNeedsGraphqlOwned(input && input.type);
+
+        /** @type {SuiPaginatedResponse<SuiObject>} */
+        const paginatedResponse = new SuiPaginatedResponse({
+            suiMaster: this,
+            method: useGraphql ? 'graphqlOwnedObjects' : 'listOwnedObjects',
+            params: input,
+            order: extra.order,
+        });
+        await paginatedResponse.fetch();
+        return paginatedResponse;
+    }
+
+    /**
+     * gRPC `ListOwnedObjects.objectType` only accepts a full struct type. A bare package address or
+     * `package::module` string needs the GraphQL path.
+     * @param {?string} type
+     * @returns {boolean}
+     */
+    static _typeNeedsGraphqlOwned(type) {
+        if (!type) return false;
+        // Strip generic type params (content inside the outermost `<…>`) before counting `::` segments.
+        const bare = type.split('<')[0];
+        const segments = bare.split('::');
+        return segments.length < 3;
     }
 
     /**
      * Sign and execute a transaction on the Sui blockchain.
      * Uses the connected keypair or signer or browser extension wallet adapter to sign the transaction before submitting it.
      *
-     * @param {Object} params - Transaction parameters
-     * @param {Transaction} params.transaction - The Transaction object to sign and execute
-     * @param {Object} [params.options] - Options specifying what data to return in the response
-     * @param {boolean} [params.options.showEffects] - Whether to include transaction effects
-     * @param {boolean} [params.options.showEvents] - Whether to include emitted events
-     * @param {boolean} [params.options.showObjectChanges] - Whether to include object changes
-     * @param {boolean} [params.options.showBalanceChanges] - Whether to include balance changes
-     * @param {boolean} [params.options.showInput] - Whether to include transaction input
-     * @param {boolean} [params.options.showType] - Whether to include object types
-     * @param {boolean} [params.options.showContent] - Whether to include object content
-     * @param {boolean} [params.options.showOwner] - Whether to include object ownership info
-     * @param {boolean} [params.options.showDisplay] - Whether to include display data
-     * @param {string} [params.requestType] - Request type, use 'WaitForLocalExecution' to wait for transaction finality
-     * @param {string} [params.chain] - Chain identifier (defaults to connected chain, e.g., 'sui:mainnet')
-     * @param {Object} [params.account] - Account info (defaults to connected address)
-     * @param {string} [params.account.address] - The account address
+     * Throws on two failure paths, both with a normalised `executionError` + `digest` shape:
+     *
+     *  1. **`SimulationError`** (SDK, pre-submission) — thrown during `tx.build()` / gas selection
+     *     when the SDK simulates the transaction and detects an abort before even submitting.
+     *     `executionError` is set by the SDK; `digest` is `null` (no submission happened).
      *
-     * @returns {Promise<SuiTransactionBlockResponse>} The transaction execution response
+     *  2. **`FailedTransaction`** (on-chain) — the transaction was submitted and executed but aborted.
+     *     Both `executionError` and `digest` are set.
      *
-     * @example
-     * const tx = new Transaction();
-     * tx.moveCall({ target: '0x2::coin::transfer', arguments: [...] });
+     * In both cases the error has:
+     *   - `message` — human-readable failure reason
+     *   - `executionError` — `SuiClientTypes.ExecutionError`:
+     *       `{ message, command?, MoveAbort?, SizeError?, CommandArgumentError?, TypeArgumentError?, ... }`
+     *   - `digest` — transaction digest, or `null` for pre-submission failures
      *
-     * const result = await suiMaster.signAndExecuteTransaction({
-     *     transaction: tx,
-     *     requestType: 'WaitForLocalExecution',
-     *     options: {
-     *         showEffects: true,
-     *         showEvents: true,
-     *         showObjectChanges: true,
-     *     },
-     * });
+     * @param {{ transaction: Transaction, include?: SuiClientTypes.TransactionInclude, requestType?: string }} params
+     * @returns {Promise<SuiTransaction>}
+     * @throws {Error & { executionError: SuiClientTypes.ExecutionError, digest: ?string }} if the transaction fails on-chain
      */
     async signAndExecuteTransaction(params) {
-        if (!params.chain) {
-            const chainId = 'sui:'+(this._providerName.split('sui:').join('').toLowerCase());
-            params.chain = chainId;
-        }
-        if (!params.account) {
-            params.account = { address: this._address };
-        }
+        let signAndExecuteTransactionResponse;
+        try {
+            const tx = /** @type {Transaction} */ (params.transaction);
 
-        /** @type {SuiTransactionBlockResponse} */ 
-        let txResults = null;
-        if (this._keypair) {
-            params.signer = this._keypair;
-            txResults = await this._client.signAndExecuteTransaction(params);
-        } else if (this._signer) {
-            txResults = await this._signer.signAndExecuteTransaction(params);
-        }
+            tx.setSenderIfNotSet(this.address);
 
-        try {
-            if (params && params.requestType && params.requestType == 'WaitForLocalExecution') {
-                const detailedResults =  await this.client.waitForTransaction({
-                    digest: txResults.digest,
-                    options: (params.options || {}),
+            const signerAny = /** @type {any} */ (this._signer);
+
+            /** @type {?Uint8Array} */
+            let transactionBytes = null;
+            /** @type {?string} */
+            let signature = null;
+
+            if (signerAny.activeAdapter) {
+                // We are using browser adapter — build first to resolve intents, 
+                // then sign
+                const signer = /** @type {SuiInBrowser} */ (signerAny);
+
+                transactionBytes = await tx.build({
+                    client: this._client,
+                });
+
+                // Sign TX with browser extension
+                ({ signature } = await signer.signTransaction({
+                    ...params,
+                }));
+            } else {
+                const signer = /** @type {SuiSigner} */ (signerAny);
+
+                transactionBytes = await tx.build({
+                    client: this._client,
                 });
-    
-                return detailedResults;
+
+                ({ signature } = await signer.signTransaction(transactionBytes));
             }
+
+            signAndExecuteTransactionResponse = await this._client.executeTransaction({
+                transaction: transactionBytes,
+                signatures: [signature],
+                include: params.include ? params.include : {},
+            });
         } catch (e) {
-            this.log(e);
+            // SimulationError — SDK aborted during pre-submission simulation (tx.build / gas selection).
+            // Already has executionError; add digest = null for a consistent error shape.
+            if (e && e.executionError !== undefined) {
+                e.digest = e.digest ?? null;
+            }
+            throw e;
         }
 
-        return txResults;
+        if (signAndExecuteTransactionResponse.$kind === 'FailedTransaction') {
+            const executionError = signAndExecuteTransactionResponse.FailedTransaction?.status?.error;
+            const err = /** @type {Error & { executionError: any, digest: any }} */ (new Error(executionError?.message ?? 'Transaction failed'));
+            err.executionError = executionError ?? null;  // full SuiClientTypes.ExecutionError: { message, command?, MoveAbort?, ... }
+            err.digest = signAndExecuteTransactionResponse.FailedTransaction?.digest ?? null;
+            throw err;
+        }
+
+        const suiTransaction = new SuiTransaction({
+            suiMaster: this,
+            data: signAndExecuteTransactionResponse.Transaction,
+        });
+
+        if (params.requestType && params.requestType == 'WaitForLocalExecution') {
+            await suiTransaction.waitForTransaction(
+                /** @type {SuiClientTypes.WaitForTransactionOptions<{}>} */ (
+                    params.include ? { include: params.include } : {}
+                )
+            );
+        }
+
+        return suiTransaction;
     }
 
+    /**
+     * Request SUI tokens from the faucet for the connected address.
+     * Only works on localnet, devnet, and testnet.
+     * @returns {Promise<bigint>} total MIST received across all coin objects
+     */
     async requestSuiFromFaucet() {
         await this.initialize();
         let amount = BigInt(0);
@@ -433,7 +603,7 @@ export default class SuiMaster extends SuiCommonMethods {
         if (provider === "mainnet") {
             this.log(`no faucet on ${provider}`);
         } else {
-            const faucetHost = getFaucetHost(provider);
+            const faucetHost = getFaucetHost(/** @type {any} */ (provider));
             this.log(`requesting sui from faucet... ${faucetHost}`);
             const requested = await requestSuiFromFaucetV2({
                 host: faucetHost,
@@ -458,9 +628,9 @@ export default class SuiMaster extends SuiCommonMethods {
     /**
      * Query the balance of specific coinType for an owner. If owner == null, returns balance of connected address owner
      * 
-     * @param {String} coinType 
-     * @param {String|null} owner 
-     * @returns BigInt
+     * @param {string} [coinType='0x2::sui::SUI']
+     * @param {?string} [owner] - defaults to the connected address
+     * @returns {Promise<bigint>}
      */
     async getBalance(coinType = '0x2::sui::SUI', owner = null) {
         await this.initialize();
@@ -474,20 +644,34 @@ export default class SuiMaster extends SuiCommonMethods {
         return await (suiCoin.getBalance(queryingBalanceOf));
     }
 
+    /**
+     * Fetch events via the GraphQL `events` query. Lowest-level entry point —
+     * `SuiPackage.fetchEvents` and `SuiPackageModule.fetchEvents` both delegate here.
+     *
+     * The filter is a GraphQL `EventFilter`:
+     *   - `module` : "<package>" or "<package>::<module>"
+     *   - `type`   : "<package>::<module>::<EventName>" (or a prefix thereof)
+     *   - `sender` : SuiAddress
+     *   - `atCheckpoint` / `afterCheckpoint` / `beforeCheckpoint` : UInt53
+     *
+     * @param {Object} [params]
+     * @param {Object} [params.filter] - GraphQL EventFilter
+     * @param {number} [params.limit=50]
+     * @param {string} [params.order] - Passed through to the underlying paginated response
+     * @returns {Promise<SuiPaginatedResponse<SuiEvent>>}
+     */
     async fetchEvents(params = {}) {
-        let query = params.query;
-
         const queryParams = {
-            descending_order: params.descending_order || false,
-            query: query,
+            filter: params.filter || {},
             limit: params.limit || 50,
         };
 
+        /** @type {SuiPaginatedResponse<SuiEvent>} */
         const paginatedResponse = new SuiPaginatedResponse({
             debug: this._debug,
             suiMaster: this,
             params: queryParams,
-            method: 'queryEvents',
+            method: 'graphqlEvents',
             order: params.order,
         });
 
@@ -496,36 +680,48 @@ export default class SuiMaster extends SuiCommonMethods {
         return paginatedResponse;
     }
 
+    /**
+     * Fetch transactions via the GraphQL root `transactions(filter: TransactionFilter)` query.
+     *
+     * Accepts either a direct `params.filter` (GraphQL `TransactionFilter` shape) or the legacy
+     * convenience fields (`fromAddress`, `affectedAddress`, `affectedObject`, `function`, `atCheckpoint`,
+     * `afterCheckpoint`, `beforeCheckpoint`, `kind`) which get translated to the corresponding
+     * `TransactionFilter` fields.
+     *
+     * @param {Object} [params]
+     * @param {Object} [params.filter] - raw TransactionFilter; overrides the convenience fields if set
+     * @param {?string} [params.fromAddress]
+     * @param {?string} [params.affectedAddress]
+     * @param {?string} [params.affectedObject]
+     * @param {?string} [params.function]
+     * @param {?number} [params.atCheckpoint]
+     * @param {?number} [params.afterCheckpoint]
+     * @param {?number} [params.beforeCheckpoint]
+     * @param {?string} [params.kind]
+     * @param {number} [params.limit=50]
+     * @param {string} [params.order]
+     * @returns {Promise<SuiPaginatedResponse<SuiTransaction>>}
+     */
     async fetchTransactions(params = {}) {
-        let filter = {};
-        if (params.fromAddress) {
-            filter.FromAddress = params.fromAddress;
-        }
-        if (params.filter) {
-            filter = params.filter;
+        let filter = params.filter;
+        if (!filter) {
+            filter = {};
+            if (params.fromAddress) filter.sentAddress = params.fromAddress;
+            if (params.affectedAddress) filter.affectedAddress = params.affectedAddress;
+            if (params.affectedObject) filter.affectedObject = params.affectedObject;
+            if (params.function) filter.function = params.function;
+            if (params.atCheckpoint !== undefined) filter.atCheckpoint = params.atCheckpoint;
+            if (params.afterCheckpoint !== undefined) filter.afterCheckpoint = params.afterCheckpoint;
+            if (params.beforeCheckpoint !== undefined) filter.beforeCheckpoint = params.beforeCheckpoint;
+            if (params.kind) filter.kind = params.kind;
         }
 
-        const queryParams = {
-            descending_order: false,
-            filter: filter,
-            options: {
-                // showInput: true,
-                showEffects: true,
-                // showEvents: true,
-                // showObjectChanges: true,
-                // showBalanceChanges: true,
-                // showType: true,
-                // showContent: true,
-                // showOwner: true,
-                // showDisplay: true,
-            },
-            limit: params.limit || 50,
-        };
+        /** @type {SuiPaginatedResponse<SuiTransaction>} */
         const paginatedResponse = new SuiPaginatedResponse({
             debug: this._debug,
             suiMaster: this,
-            params: queryParams,
-            method: 'queryTransactionBlocks',
+            params: { filter, limit: params.limit || 50 },
+            method: 'graphqlTransactions',
             order: params.order,
         });