@0xobelisk/sui-client 1.2.0-pre.98 → 2.0.0

package/dist/index.js

@@ -50,11 +50,17 @@ var src_exports = {};
 __export(src_exports, {
   BcsType: () => import_bcs4.BcsType,
   Dubhe: () => Dubhe,
+  MAINNET_DUBHE_FRAMEWORK_PACKAGE_ID: () => MAINNET_DUBHE_FRAMEWORK_PACKAGE_ID,
+  MAINNET_DUBHE_HUB_OBJECT_ID: () => MAINNET_DUBHE_HUB_OBJECT_ID,
   MultiSigClient: () => MultiSigClient,
   SuiAccountManager: () => SuiAccountManager,
   SuiContractFactory: () => SuiContractFactory,
   SuiTx: () => SuiTx,
+  TESTNET_DUBHE_FRAMEWORK_PACKAGE_ID: () => TESTNET_DUBHE_FRAMEWORK_PACKAGE_ID,
+  TESTNET_DUBHE_HUB_OBJECT_ID: () => TESTNET_DUBHE_HUB_OBJECT_ID,
   bcs: () => import_bcs4.bcs,
+  getDefaultConfig: () => getDefaultConfig,
+  getDefaultURL: () => getDefaultURL,
   loadMetadata: () => loadMetadata
 });
 module.exports = __toCommonJS(src_exports);
@@ -838,19 +844,26 @@ var SuiInteractor = class {
 };
 
 // src/libs/suiInteractor/defaultConfig.ts
-var getDefaultURL = (networkType = "testnet") => {
+var TESTNET_DUBHE_FRAMEWORK_PACKAGE_ID = "0xae33be6675639d6f1a5c468ae6bbc457ae4e22e57cd7526741d6143ce219d995";
+var TESTNET_DUBHE_HUB_OBJECT_ID = "0x80391929a8772aba091156fd1f099bf79240d2cf4471a14026b4aa68e3a240cc";
+var MAINNET_DUBHE_FRAMEWORK_PACKAGE_ID = "0x5bc40de124588b1e3514ca50f5e7109869351c4d9544e5f0cb9d30dd47bf8de7";
+var MAINNET_DUBHE_HUB_OBJECT_ID = "0x96e92d9baccfd0a2927b4f209756e1edbc18904bff34e486e4bb4a151320e1e5";
+var getDefaultConfig = (networkType = "testnet") => {
   switch (networkType) {
-    case "localnet":
+    case "localnet": {
+      const localRpc = encodeURIComponent("http://127.0.0.1:9000");
       return {
         fullNode: "http://127.0.0.1:9000",
         graphql: "http://127.0.0.1:9125",
         network: "localnet",
-        txExplorer: "https://explorer.polymedia.app/txblock/:txHash?network=local",
-        accountExplorer: "https://explorer.polymedia.app/address/:address?network=local",
-        explorer: "https://explorer.polymedia.app?network=local",
+        txExplorer: `https://custom.suiscan.xyz/custom/tx/:txHash?network=${localRpc}`,
+        accountExplorer: `https://custom.suiscan.xyz/custom/account/:address?network=${localRpc}`,
+        explorer: `https://custom.suiscan.xyz/custom?network=${localRpc}`,
         indexerUrl: "http://127.0.0.1:3001",
         channelUrl: "http://127.0.0.1:8080"
+        // frameworkPackageId: undefined — set after deploying dubhe locally
       };
+    }
     case "devnet":
       return {
         fullNode: "https://fullnode.devnet.sui.io:443",
@@ -860,6 +873,7 @@ var getDefaultURL = (networkType = "testnet") => {
         explorer: "https://suiscan.xyz/devnet",
         indexerUrl: "http://127.0.0.1:3001",
         channelUrl: "http://127.0.0.1:8080"
+        // frameworkPackageId: undefined — no persistent deployment on devnet
       };
     case "testnet":
       return {
@@ -870,7 +884,9 @@ var getDefaultURL = (networkType = "testnet") => {
         accountExplorer: "https://suiscan.xyz/testnet/address/:address",
         explorer: "https://suiscan.xyz/testnet",
         indexerUrl: "http://127.0.0.1:3001",
-        channelUrl: "http://127.0.0.1:8080"
+        channelUrl: "http://127.0.0.1:8080",
+        frameworkPackageId: TESTNET_DUBHE_FRAMEWORK_PACKAGE_ID,
+        dappHubId: TESTNET_DUBHE_HUB_OBJECT_ID
       };
     case "mainnet":
       return {
@@ -881,7 +897,9 @@ var getDefaultURL = (networkType = "testnet") => {
         accountExplorer: "https://suiscan.xyz/mainnet/address/:address",
         explorer: "https://suiscan.xyz/mainnet",
         indexerUrl: "http://127.0.0.1:3001",
-        channelUrl: "http://127.0.0.1:8080"
+        channelUrl: "http://127.0.0.1:8080",
+        frameworkPackageId: MAINNET_DUBHE_FRAMEWORK_PACKAGE_ID || void 0,
+        dappHubId: MAINNET_DUBHE_HUB_OBJECT_ID || void 0
       };
     default:
       return {
@@ -892,10 +910,13 @@ var getDefaultURL = (networkType = "testnet") => {
         accountExplorer: "https://suiscan.xyz/testnet/address/:address",
         explorer: "https://suiscan.xyz/testnet",
         indexerUrl: "http://127.0.0.1:3001",
-        channelUrl: "http://127.0.0.1:8080"
+        channelUrl: "http://127.0.0.1:8080",
+        frameworkPackageId: TESTNET_DUBHE_FRAMEWORK_PACKAGE_ID,
+        dappHubId: TESTNET_DUBHE_HUB_OBJECT_ID
       };
   }
 };
+var getDefaultURL = getDefaultConfig;
 
 // src/libs/suiContractFactory/index.ts
 var SuiContractFactory = class {
@@ -1083,6 +1104,10 @@ function normalizePackageId(input) {
   const normalized = withoutPrefix.replace(/^0+/, "");
   return "0x" + normalized;
 }
+function normalizeDappKey(packageId) {
+  const raw = packageId.replace(/^0x/, "");
+  return `${raw.padStart(64, "0")}::dapp_key::DappKey`;
+}
 
 // src/errors/index.ts
 var ContractDataParsingError = class extends Error {
@@ -1381,6 +1406,7 @@ function createTx(meta, fn) {
     }
   );
 }
+var SUI_CLOCK_OBJECT_ID = "0x0000000000000000000000000000000000000000000000000000000000000006";
 var _query, _tx, _object, _exec, _read, _getVectorDepth, _bcs, _bcsenum, _processKeyParameter, processKeyParameter_fn;
 var Dubhe = class {
   /**
@@ -1396,6 +1422,7 @@ var Dubhe = class {
    * @param packageId
    * @param metadata
    * @param channelUrl, the base URL for Dubhe Channel API, optional
+   * @param frameworkPackageId, the published package ID of the dubhe framework, required for proxy operations
    */
   constructor({
     mnemonics,
@@ -1403,8 +1430,12 @@ var Dubhe = class {
     networkType,
     fullnodeUrls,
     packageId,
+    dappKey: dappKeyParam,
     metadata,
-    channelUrl
+    channelUrl,
+    frameworkPackageId,
+    dappStorageId,
+    dappHubId
   } = {}) {
     // async getTransactions({
     //   first,
@@ -2105,7 +2136,7 @@ var Dubhe = class {
       };
     });
     networkType = networkType ?? "mainnet";
-    const defaultParams = getDefaultURL(networkType);
+    const defaultParams = getDefaultConfig(networkType);
     this.accountManager = new SuiAccountManager({ mnemonics, secretKey });
     fullnodeUrls = fullnodeUrls || [defaultParams.fullNode];
     this.suiInteractor = new SuiInteractor(fullnodeUrls, networkType);
@@ -2113,6 +2144,11 @@ var Dubhe = class {
       baseUrl: channelUrl || defaultParams.channelUrl
     });
     this.packageId = packageId ? normalizePackageId(packageId) : void 0;
+    this.dappKey = dappKeyParam;
+    const networkDefault = defaultParams.frameworkPackageId;
+    this.frameworkPackageId = frameworkPackageId ? normalizePackageId(frameworkPackageId) : networkDefault ? normalizePackageId(networkDefault) : void 0;
+    this.dappStorageId = dappStorageId;
+    this.dappHubId = dappHubId;
     if (metadata !== void 0) {
       this.metadata = metadata;
       const maxLoopNum = 5;
@@ -2403,6 +2439,27 @@ var Dubhe = class {
   getPackageId() {
     return this.contractFactory.packageId;
   }
+  /**
+   * Return the fully-qualified Move type string for this DApp's `DappKey`.
+   *
+   * The format matches what `std::type_name::get<DappKey>()` returns on-chain:
+   * `<64-char-zero-padded-address>::dapp_key::DappKey`
+   *
+   * Use this whenever you need to pass a type argument or build a `target`
+   * string that references the DApp's DappKey type.
+   *
+   * @example
+   * ```typescript
+   * tx.moveCall({
+   *   target: `${frameworkPackageId}::dapp_system::settle_writes`,
+   *   typeArguments: [contract.getDappKey()],
+   *   arguments: [...],
+   * });
+   * ```
+   */
+  getDappKey() {
+    return this.dappKey;
+  }
   getMetadata() {
     return this.contractFactory.metadata;
   }
@@ -2410,7 +2467,7 @@ var Dubhe = class {
     return this.suiInteractor.network;
   }
   getNetworkConfig() {
-    return getDefaultURL(this.getNetwork());
+    return getDefaultConfig(this.getNetwork());
   }
   getTxExplorerUrl(txHash) {
     return this.getNetworkConfig().txExplorer.replace(":txHash", txHash);
@@ -2436,7 +2493,7 @@ var Dubhe = class {
     const fullnodeUrlsChanged = config.fullnodeUrls !== void 0;
     if (networkChanged || fullnodeUrlsChanged) {
       const newNetworkType = config.networkType ?? this.suiInteractor.network;
-      const defaultParams = getDefaultURL(newNetworkType);
+      const defaultParams = getDefaultConfig(newNetworkType);
       const newFullnodeUrls = config.fullnodeUrls || [defaultParams.fullNode];
       this.suiInteractor = new SuiInteractor(newFullnodeUrls, newNetworkType);
     }
@@ -2447,6 +2504,9 @@ var Dubhe = class {
     }
     const packageIdChanged = config.packageId !== void 0 && config.packageId !== this.packageId;
     const metadataChanged = config.metadata !== void 0 && config.metadata !== this.metadata;
+    if (config.dappKey !== void 0) {
+      this.dappKey = config.dappKey;
+    }
     if (packageIdChanged || metadataChanged) {
       if (config.packageId !== void 0) {
         this.packageId = normalizePackageId(config.packageId);
@@ -2638,11 +2698,8 @@ var Dubhe = class {
     if (account && account.startsWith("0x")) {
       account = account.slice(2);
     }
-    if (packageId && packageId.startsWith("0x")) {
-      packageId = packageId.slice(2);
-    }
     const payload = {
-      dapp_key: `${packageId}::dapp_key::DappKey`,
+      dapp_key: normalizeDappKey(packageId ?? ""),
       account,
       table,
       key
@@ -2681,22 +2738,16 @@ var Dubhe = class {
    * );
    */
   async subscribeChannelTable({
-    packageId,
+    packageId: _packageId,
     account,
     table,
     key
   } = {}, options) {
-    packageId = packageId || this.packageId;
-    if (account !== void 0) {
-      if (account.startsWith("0x")) {
-        account = account.slice(2);
-      }
-    }
-    if (packageId && packageId.startsWith("0x")) {
-      packageId = packageId.slice(2);
+    if (account !== void 0 && account.startsWith("0x")) {
+      account = account.slice(2);
     }
     const payload = {
-      dapp_key: `${packageId}::dapp_key::DappKey`
+      dapp_key: this.dappKey
     };
     if (account !== void 0) {
       payload.account = account;
@@ -2873,6 +2924,761 @@ var Dubhe = class {
   async entity_key_from_u256(x) {
     return numberToAddressHex(x);
   }
+  // ─── UserStorage helpers ────────────────────────────────────────────────────
+  /**
+   * Call the DApp's generated `user_storage_init::init_user_storage` entry function,
+   * which creates and shares a `UserStorage` object for the signer.
+   *
+   * Each DApp exposes this entry point under its own package ID.
+   * On Sui, the `UserStorage` object is shared immediately so all transactions
+   * can reference it without knowing the object ID in advance.
+   *
+   * @param dappHubId      Object ID of the DappHub shared object
+   * @param dappStorageId  Object ID of the DApp's DappStorage shared object
+   */
+  async initUserStorage({
+    dappHubId,
+    dappStorageId: dappStorageIdParam,
+    derivePathParams,
+    onSuccess,
+    onError
+  }) {
+    const storageId = dappStorageIdParam ?? this.dappStorageId;
+    if (!storageId) {
+      throw new Error(
+        "dappStorageId is required for initUserStorage. Pass it directly or set it in the Dubhe constructor."
+      );
+    }
+    const pkg = this.packageId;
+    if (!pkg)
+      throw new Error("packageId is required for initUserStorage.");
+    const tx = new import_transactions3.Transaction();
+    tx.moveCall({
+      target: `${pkg}::user_storage_init::init_user_storage`,
+      arguments: [tx.object(dappHubId), tx.object(storageId)]
+    });
+    return this.signAndSendTxn({
+      tx,
+      derivePathParams,
+      onSuccess,
+      onError
+    });
+  }
+  /**
+   * Activate a session key for the signer's `UserStorage`.
+   *
+   * The signer must be the `canonical_owner` of the `UserStorage` object.
+   * Calls `<frameworkPackageId>::dapp_system::activate_session<DappKey>`.
+   *
+   * @param userStorageId  Object ID of the UserStorage to activate a session for
+   * @param sessionWallet  Sui address of the session wallet
+   * @param durationMs     Session duration in milliseconds ([60_000, 604_800_000])
+   * @param clockObjectId  Object ID of the Sui Clock (default: 0x6)
+   */
+  async activateSession({
+    userStorageId,
+    sessionWallet,
+    durationMs,
+    dappHubId: dappHubIdParam,
+    clockObjectId,
+    derivePathParams,
+    onSuccess,
+    onError
+  }) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg) {
+      throw new Error(
+        'frameworkPackageId is required for activateSession. Set it in the Dubhe constructor ({ frameworkPackageId: "0x..." }).'
+      );
+    }
+    const typeArg = this.dappKey;
+    if (!typeArg) {
+      throw new Error(
+        'dappKey is required for activateSession. Set it in the Dubhe constructor ({ packageId: "0x..." }).'
+      );
+    }
+    const hubId = dappHubIdParam ?? this.dappHubId;
+    if (!hubId) {
+      throw new Error(
+        'dappHubId is required for activateSession. Pass it directly or set it in the Dubhe constructor ({ dappHubId: "0x..." }).'
+      );
+    }
+    const clockId = clockObjectId ?? SUI_CLOCK_OBJECT_ID;
+    const tx = new import_transactions3.Transaction();
+    tx.moveCall({
+      target: `${fwPkg}::dapp_system::activate_session`,
+      typeArguments: [typeArg],
+      arguments: [
+        tx.object(hubId),
+        tx.object(userStorageId),
+        tx.pure.address(sessionWallet),
+        tx.pure.u64(durationMs),
+        tx.object(clockId)
+      ]
+    });
+    return this.signAndSendTxn({
+      tx,
+      derivePathParams,
+      onSuccess,
+      onError
+    });
+  }
+  /**
+   * Deactivate the current session key on a `UserStorage`.
+   *
+   * Allowed callers:
+   *   - The `canonical_owner` (revoke at any time).
+   *   - The session key itself (voluntary sign-out).
+   *   - Anyone, once the session has expired.
+   *
+   * Calls `<frameworkPackageId>::dapp_system::deactivate_session<DappKey>`.
+   *
+   * @param userStorageId  Object ID of the UserStorage to deactivate the session on
+   */
+  async deactivateSession({
+    userStorageId,
+    dappHubId: dappHubIdParam,
+    derivePathParams,
+    onSuccess,
+    onError
+  }) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg) {
+      throw new Error(
+        'frameworkPackageId is required for deactivateSession. Set it in the Dubhe constructor ({ frameworkPackageId: "0x..." }).'
+      );
+    }
+    const typeArg = this.dappKey;
+    if (!typeArg) {
+      throw new Error(
+        'dappKey is required for deactivateSession. Set it in the Dubhe constructor ({ packageId: "0x..." }).'
+      );
+    }
+    const hubId = dappHubIdParam ?? this.dappHubId;
+    if (!hubId) {
+      throw new Error(
+        'dappHubId is required for deactivateSession. Pass it directly or set it in the Dubhe constructor ({ dappHubId: "0x..." }).'
+      );
+    }
+    const tx = new import_transactions3.Transaction();
+    tx.moveCall({
+      target: `${fwPkg}::dapp_system::deactivate_session`,
+      typeArguments: [typeArg],
+      arguments: [tx.object(hubId), tx.object(userStorageId)]
+    });
+    return this.signAndSendTxn({
+      tx,
+      derivePathParams,
+      onSuccess,
+      onError
+    });
+  }
+  /**
+   * Look up the `UserStorage` object ID for the given address in this DApp.
+   *
+   * Scans the transaction history for `user_storage_init::init_user_storage`
+   * calls from the given address and extracts the created `UserStorage` object
+   * ID from the transaction's object changes.
+   *
+   * Returns the object ID on success, or `null` when:
+   *   - `packageId` or `frameworkPackageId` is not set.
+   *   - The user has not yet called `initUserStorage`.
+   *
+   * @param userAddress  Sui address to look up (with or without 0x prefix).
+   */
+  async getUserStorageId(userAddress) {
+    const pkg = this.packageId;
+    const fwPkg = this.frameworkPackageId;
+    if (!pkg || !fwPkg)
+      return null;
+    const normalizedUser = userAddress.startsWith("0x") ? userAddress : `0x${userAddress}`;
+    const expectedType = `${fwPkg}::dapp_service::UserStorage`;
+    let cursor = null;
+    let hasNextPage = true;
+    while (hasNextPage) {
+      const result = await this.suiInteractor.currentClient.queryTransactionBlocks({
+        filter: {
+          MoveFunction: {
+            package: pkg,
+            module: "user_storage_init",
+            function: "init_user_storage"
+          }
+        },
+        options: { showObjectChanges: true },
+        ...cursor !== null && cursor !== void 0 ? { cursor } : {},
+        limit: 50
+      });
+      for (const tx of result.data) {
+        if (!tx.objectChanges)
+          continue;
+        const created = tx.objectChanges.find(
+          (c) => c.type === "created" && typeof c.objectType === "string" && c.objectType === expectedType && c.sender === normalizedUser
+        );
+        if (created?.objectId)
+          return created.objectId;
+      }
+      hasNextPage = result.hasNextPage;
+      cursor = result.nextCursor ?? null;
+    }
+    return null;
+  }
+  /**
+   * Fetch and return the on-chain fields of a `UserStorage` shared object.
+   *
+   * The returned object mirrors Move's `UserStorage` struct plus two
+   * convenience fields computed from the raw counters:
+   *   - `unsettled_count`  = write_count  − settled_count
+   *   - `unsettled_bytes`  = write_bytes  − settled_bytes
+   *
+   * @param userStorageId  Object ID of the UserStorage to inspect.
+   */
+  async getUserStorageFields(userStorageId) {
+    const obj = await this.suiInteractor.getObject(userStorageId);
+    const fields = obj?.content?.fields ?? {};
+    const writeCount = BigInt(fields.write_count ?? 0);
+    const settledCount = BigInt(fields.settled_count ?? 0);
+    const writeBytes = BigInt(fields.write_bytes ?? 0);
+    const settledBytes = BigInt(fields.settled_bytes ?? 0);
+    return {
+      objectId: userStorageId,
+      dapp_key: fields.dapp_key ?? "",
+      canonical_owner: fields.canonical_owner ?? "",
+      session_key: fields.session_key ?? "",
+      session_expires_at: BigInt(fields.session_expires_at ?? 0),
+      write_count: writeCount,
+      settled_count: settledCount,
+      write_bytes: writeBytes,
+      settled_bytes: settledBytes,
+      unsettled_count: writeCount - settledCount,
+      unsettled_bytes: writeBytes - settledBytes
+    };
+  }
+  /**
+   * Fetch and return the on-chain fields of a `DappStorage` shared object.
+   *
+   * Covers the full metadata + fee/credit subset of the Move struct.
+   *
+   * @param dappStorageId  Object ID of the DappStorage to inspect.
+   */
+  /**
+   * Read the framework-level fields from the DappHub shared object.
+   *
+   * Key fields:
+   * - `treasury`          — address that directly receives framework fee income
+   * - `pending_treasury`  — queued treasury address during two-step rotation
+   * - `framework_admin`   — address that can update framework configuration
+   * - `version`           — current framework version
+   */
+  async getDappHubFields(dappHubId) {
+    const obj = await this.suiInteractor.getObject(dappHubId);
+    const fields = obj?.content?.fields ?? {};
+    const feeConfig = fields.fee_config?.fields ?? fields.fee_config ?? {};
+    const adminConfig = fields.admin_config?.fields ?? fields.admin_config ?? {};
+    return {
+      objectId: dappHubId,
+      version: Number(fields.version ?? 0),
+      framework_admin: adminConfig.admin ?? fields.framework_admin ?? "",
+      treasury: feeConfig.treasury ?? fields.treasury ?? "",
+      pending_treasury: feeConfig.pending_treasury ?? fields.pending_treasury ?? ""
+    };
+  }
+  async getDappStorageFields(dappStorageId) {
+    const obj = await this.suiInteractor.getObject(dappStorageId);
+    const fields = obj?.content?.fields ?? {};
+    return {
+      objectId: dappStorageId,
+      dapp_key: fields.dapp_key ?? "",
+      name: fields.name ?? "",
+      description: fields.description ?? "",
+      website_url: fields.website_url ?? "",
+      admin: fields.admin ?? "",
+      version: Number(fields.version ?? 0),
+      paused: Boolean(fields.paused),
+      free_credit: BigInt(fields.free_credit ?? 0),
+      free_credit_expires_at: BigInt(fields.free_credit_expires_at ?? 0),
+      credit_pool: BigInt(fields.credit_pool ?? 0),
+      min_credit_to_unsuspend: BigInt(fields.min_credit_to_unsuspend ?? 0),
+      suspended: Boolean(fields.suspended),
+      total_settled: BigInt(fields.total_settled ?? 0),
+      base_fee_per_write: BigInt(fields.base_fee_per_write ?? 0),
+      bytes_fee_per_byte: BigInt(fields.bytes_fee_per_byte ?? 0),
+      settlement_mode: Number(fields.settlement_mode ?? 0),
+      write_fee_dapp_share_bps: Number(fields.write_fee_dapp_share_bps ?? 0)
+    };
+  }
+  /**
+   * Append a `dapp_system::settle_writes` moveCall to an existing PTB.
+   *
+   * Does NOT send the transaction — call this before your own moveCall(s) to
+   * settle any accumulated write debt within the same PTB at no extra round-trip.
+   *
+   * The framework function never aborts due to insufficient credit (it silently
+   * skips or partially settles), so prepending this to any PTB is always safe.
+   *
+   * @param tx             The Transaction object to append the moveCall to.
+   * @param dappHubId      Object ID of the DappHub shared object.
+   * @param dappStorageId  Object ID of the DApp's DappStorage (falls back to constructor value).
+   * @param userStorageId  Object ID of the user's UserStorage shared object.
+   */
+  buildSettleWritesTx(tx, {
+    dappHubId,
+    dappStorageId: dappStorageIdParam,
+    userStorageId
+  }) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg) {
+      throw new Error(
+        'frameworkPackageId is required for buildSettleWritesTx. Set it in the Dubhe constructor ({ frameworkPackageId: "0x..." }).'
+      );
+    }
+    const storageId = dappStorageIdParam ?? this.dappStorageId;
+    if (!storageId) {
+      throw new Error(
+        "dappStorageId is required for buildSettleWritesTx. Pass it directly or set it in the Dubhe constructor."
+      );
+    }
+    const typeArg = this.dappKey;
+    if (!typeArg) {
+      throw new Error(
+        'dappKey is required for buildSettleWritesTx. Set it in the Dubhe constructor ({ packageId: "0x..." }).'
+      );
+    }
+    tx.moveCall({
+      target: `${fwPkg}::dapp_system::settle_writes`,
+      typeArguments: [typeArg],
+      arguments: [tx.object(dappHubId), tx.object(storageId), tx.object(userStorageId)]
+    });
+  }
+  /**
+   * Settle accumulated write debt for a user (standalone transaction).
+   *
+   * Builds a PTB containing a single `dapp_system::settle_writes` call and
+   * sends it. For embedding settlement into an existing PTB, use
+   * `buildSettleWritesTx` instead.
+   *
+   * This is safe to call at any time — the framework function never aborts
+   * due to insufficient credit; it silently skips or partially settles.
+   *
+   * @param dappHubId      Object ID of the DappHub shared object.
+   * @param dappStorageId  Object ID of the DApp's DappStorage shared object.
+   * @param userStorageId  Object ID of the user's UserStorage shared object.
+   */
+  async settleWrites({
+    dappHubId,
+    dappStorageId,
+    userStorageId,
+    derivePathParams,
+    onSuccess,
+    onError
+  }) {
+    const tx = new import_transactions3.Transaction();
+    this.buildSettleWritesTx(tx, { dappHubId, dappStorageId, userStorageId });
+    return this.signAndSendTxn({
+      tx,
+      derivePathParams,
+      onSuccess,
+      onError
+    });
+  }
+  /**
+   * Recharge a DApp's credit pool by paying with the framework's accepted coin type.
+   *
+   * Wraps `dapp_system::recharge_credit<DappKey, CoinType>`. Any account may call
+   * this — no admin restriction. Payment is forwarded to the framework treasury and
+   * the DApp's `credit_pool` is increased by the coin value.
+   *
+   * Only valid in DAPP_SUBSIDIZES settlement mode. Aborts with
+   * `wrong_settlement_mode` if the DApp is in USER_PAYS mode.
+   *
+   * @param dappHubId      Object ID of the DappHub shared object.
+   * @param dappStorageId  Object ID of the DApp's DappStorage shared object.
+   * @param coinObjectId   Object ID of the Coin to use as payment.
+   * @param coinType       Move type of the coin (default: "0x2::sui::SUI").
+   */
+  async rechargeCredit({
+    dappHubId,
+    dappStorageId: dappStorageIdParam,
+    coinObjectId,
+    coinType = "0x2::sui::SUI",
+    derivePathParams,
+    onSuccess,
+    onError
+  }) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg) {
+      throw new Error(
+        'frameworkPackageId is required for rechargeCredit. Set it in the Dubhe constructor ({ frameworkPackageId: "0x..." }).'
+      );
+    }
+    const storageId = dappStorageIdParam ?? this.dappStorageId;
+    if (!storageId) {
+      throw new Error(
+        "dappStorageId is required for rechargeCredit. Pass it directly or set it in the Dubhe constructor."
+      );
+    }
+    const typeArg = this.dappKey;
+    if (!typeArg) {
+      throw new Error(
+        'dappKey is required for rechargeCredit. Set it in the Dubhe constructor ({ packageId: "0x..." }).'
+      );
+    }
+    const tx = new import_transactions3.Transaction();
+    tx.moveCall({
+      target: `${fwPkg}::dapp_system::recharge_credit`,
+      typeArguments: [typeArg, coinType],
+      arguments: [tx.object(dappHubId), tx.object(storageId), tx.object(coinObjectId)]
+    });
+    return this.signAndSendTxn({
+      tx,
+      derivePathParams,
+      onSuccess,
+      onError
+    });
+  }
+  /**
+   * Append a `dapp_system::settle_writes_user_pays` moveCall to an existing PTB.
+   *
+   * Splits `maxPaymentMist` MIST from `tx.gas` as the payment coin, then calls
+   * `settle_writes_user_pays`. The framework returns any overpayment automatically,
+   * so it is safe to over-estimate. This lets a session key pay for settlement
+   * inline without requiring a separate owned Coin object.
+   *
+   * @param tx              The Transaction object to append the moveCall to.
+   * @param dappHubId       Object ID of the DappHub shared object.
+   * @param dappStorageId   Object ID of the DApp's DappStorage (falls back to constructor value).
+   * @param userStorageId   Object ID of the user's UserStorage shared object.
+   * @param maxPaymentMist  Upper bound for the payment in MIST (default: 50_000_000 = 0.05 SUI).
+   * @param coinType        Move type of the payment coin (default: "0x2::sui::SUI").
+   */
+  buildSettleWritesUserPaysTx(tx, {
+    dappHubId,
+    dappStorageId: dappStorageIdParam,
+    userStorageId,
+    maxPaymentMist = 50000000n,
+    coinType = "0x2::sui::SUI"
+  }) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg) {
+      throw new Error(
+        'frameworkPackageId is required for buildSettleWritesUserPaysTx. Set it in the Dubhe constructor ({ frameworkPackageId: "0x..." }).'
+      );
+    }
+    const storageId = dappStorageIdParam ?? this.dappStorageId;
+    if (!storageId) {
+      throw new Error(
+        "dappStorageId is required for buildSettleWritesUserPaysTx. Pass it directly or set it in the Dubhe constructor."
+      );
+    }
+    const typeArg = this.dappKey;
+    if (!typeArg) {
+      throw new Error(
+        'dappKey is required for buildSettleWritesUserPaysTx. Set it in the Dubhe constructor ({ packageId: "0x..." }).'
+      );
+    }
+    const [paymentCoin] = tx.splitCoins(tx.gas, [tx.pure.u64(maxPaymentMist)]);
+    const changeCoin = tx.moveCall({
+      target: `${fwPkg}::dapp_system::settle_writes_user_pays`,
+      typeArguments: [typeArg, coinType],
+      arguments: [tx.object(dappHubId), tx.object(storageId), tx.object(userStorageId), paymentCoin]
+    });
+    tx.mergeCoins(tx.gas, [changeCoin]);
+  }
+  /**
+   * Settle accumulated write debt where the user pays directly (USER_PAYS mode).
+   *
+   * Wraps `dapp_system::settle_writes_user_pays<DappKey, CoinType>`. The exact
+   * cost is computed on-chain; any overpayment from the coin is returned to the
+   * sender after settlement.
+   *
+   * Aborts if:
+   * - The DApp is not in USER_PAYS mode (`wrong_settlement_mode`)
+   * - The coin type does not match the accepted type (`wrong_payment_coin_type`)
+   * - The coin value is less than the total cost (`insufficient_credit`)
+   *
+   * @param dappHubId      Object ID of the DappHub shared object.
+   * @param dappStorageId  Object ID of the DApp's DappStorage shared object.
+   * @param userStorageId  Object ID of the user's UserStorage shared object.
+   * @param coinObjectId   Object ID of the Coin to use as payment.
+   * @param coinType       Move type of the coin (default: "0x2::sui::SUI").
+   */
+  async settleWritesUserPays({
+    dappHubId,
+    dappStorageId: dappStorageIdParam,
+    userStorageId,
+    coinObjectId,
+    coinType = "0x2::sui::SUI",
+    derivePathParams,
+    onSuccess,
+    onError
+  }) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg) {
+      throw new Error(
+        'frameworkPackageId is required for settleWritesUserPays. Set it in the Dubhe constructor ({ frameworkPackageId: "0x..." }).'
+      );
+    }
+    const storageId = dappStorageIdParam ?? this.dappStorageId;
+    if (!storageId) {
+      throw new Error(
+        "dappStorageId is required for settleWritesUserPays. Pass it directly or set it in the Dubhe constructor."
+      );
+    }
+    const typeArg = this.dappKey;
+    if (!typeArg) {
+      throw new Error(
+        'dappKey is required for settleWritesUserPays. Set it in the Dubhe constructor ({ packageId: "0x..." }).'
+      );
+    }
+    const tx = new import_transactions3.Transaction();
+    tx.moveCall({
+      target: `${fwPkg}::dapp_system::settle_writes_user_pays`,
+      typeArguments: [typeArg, coinType],
+      arguments: [
+        tx.object(dappHubId),
+        tx.object(storageId),
+        tx.object(userStorageId),
+        tx.object(coinObjectId)
+      ]
+    });
+    return this.signAndSendTxn({
+      tx,
+      derivePathParams,
+      onSuccess,
+      onError
+    });
+  }
+  /**
+   * Query `WritesSettled` events from the Sui full node.
+   *
+   * Returns the most recent settlement events across ALL users of this DApp.
+   * Each event captures one user's write debt settlement: number of writes,
+   * bytes, and the amount charged (`paid_cost`).
+   *
+   * Note: Sui full nodes may prune old events. For long-term history use a
+   * dedicated indexer table (`writes_settled_history`).
+   *
+   * @param limit   Max events to return (default: 30, max: 50).
+   * @param cursor  Pagination cursor from a previous response.
+   */
+  async queryWritesSettledEvents(limit = 30, cursor) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg)
+      return [];
+    try {
+      const resp = await this.suiInteractor.currentClient.queryEvents({
+        query: { MoveEventType: `${fwPkg}::dubhe_events::WritesSettled` },
+        cursor,
+        limit: Math.min(limit, 50),
+        order: "descending"
+      });
+      return (resp.data ?? []).map((ev) => {
+        const p = ev.parsedJson ?? {};
+        return {
+          txDigest: ev.id?.txDigest ?? "",
+          eventSeq: ev.id?.eventSeq ?? "",
+          timestampMs: Number(ev.timestampMs ?? 0),
+          dappKey: p.dapp_key ?? "",
+          account: p.account ?? "",
+          writes: Number(p.writes ?? 0),
+          bytes: String(p.bytes ?? "0"),
+          freeCost: String(p.free_cost ?? "0"),
+          paidCost: String(p.paid_cost ?? "0")
+        };
+      });
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Query `MarketplaceFeeSettled` events from the Sui full node.
+   *
+   * Each event records the fee split for a completed marketplace purchase:
+   * total fee, framework treasury share, and DApp revenue share.
+   *
+   * @param limit   Max events to return (default: 30, max: 50).
+   * @param cursor  Pagination cursor from a previous response.
+   */
+  async queryMarketplaceFeeSettledEvents(limit = 30, cursor) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg)
+      return [];
+    try {
+      const resp = await this.suiInteractor.currentClient.queryEvents({
+        query: { MoveEventType: `${fwPkg}::dubhe_events::MarketplaceFeeSettled` },
+        cursor,
+        limit: Math.min(limit, 50),
+        order: "descending"
+      });
+      return (resp.data ?? []).map((ev) => {
+        const p = ev.parsedJson ?? {};
+        return {
+          txDigest: ev.id?.txDigest ?? "",
+          eventSeq: ev.id?.eventSeq ?? "",
+          timestampMs: Number(ev.timestampMs ?? 0),
+          dappKey: p.dapp_key ?? "",
+          listingId: p.listing_id ?? "",
+          coinType: p.coin_type ?? "",
+          totalFee: String(p.total_fee ?? "0"),
+          treasuryAmount: String(p.treasury_amount ?? "0"),
+          dappAmount: String(p.dapp_amount ?? "0")
+        };
+      });
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Read the DApp's accumulated revenue balance directly from the chain.
+   *
+   * `dapp_revenue` is stored as a dynamic field (`DappRevenueKey<CoinType>`)
+   * on the DappStorage object — it is NOT a top-level field, so `getObject`
+   * alone cannot return it. This method calls `getDynamicFields` to locate
+   * the correct child object and returns its balance.
+   *
+   * Returns 0n when the dynamic field has never been created (no revenue yet).
+   *
+   * @param dappStorageId  Object ID of the DApp's DappStorage shared object.
+   * @param coinType       Move type of the revenue coin (default: "0x2::sui::SUI").
+   */
+  async getDappRevenueBalance(dappStorageId, coinType = "0x2::sui::SUI") {
+    const client = this.suiInteractor.currentClient;
+    const coinTail = coinType.split("::").slice(-2).join("::");
+    try {
+      let cursor = void 0;
+      do {
+        const page = await client.getDynamicFields({
+          parentId: dappStorageId,
+          cursor,
+          limit: 50
+        });
+        for (const field of page.data) {
+          const nameType = field.name?.type ?? "";
+          if (nameType.includes("DappRevenueKey") && nameType.includes(coinTail)) {
+            const fieldObj = await client.getDynamicFieldObject({
+              parentId: dappStorageId,
+              name: field.name
+            });
+            const innerFields = fieldObj?.data?.content?.fields ?? {};
+            const balValue = innerFields?.value?.fields?.value ?? // nested Balance struct
+            innerFields?.value ?? 0;
+            return BigInt(balValue);
+          }
+        }
+        cursor = page.nextCursor;
+        if (!page.hasNextPage)
+          break;
+      } while (cursor);
+    } catch {
+    }
+    return 0n;
+  }
+  /**
+   * Withdraw all accumulated DApp revenue to the DApp admin address.
+   *
+   * Wraps `dapp_system::withdraw_dapp_revenue<DappKey, CoinType>`.
+   * The entire revenue balance is transferred to the DApp admin on-chain.
+   * Aborts if the balance is zero (`no_revenue_to_withdraw`).
+   *
+   * @param dappHubId     Object ID of the DappHub shared object.
+   * @param dappStorageId Object ID of the DApp's DappStorage shared object.
+   * @param coinType      Move type of the revenue coin (default: "0x2::sui::SUI").
+   */
+  async withdrawDappRevenue({
+    dappHubId,
+    dappStorageId: dappStorageIdParam,
+    coinType = "0x2::sui::SUI",
+    derivePathParams,
+    onSuccess,
+    onError
+  }) {
+    const fwPkg = this.frameworkPackageId;
+    if (!fwPkg) {
+      throw new Error(
+        'frameworkPackageId is required for withdrawDappRevenue. Set it in the Dubhe constructor ({ frameworkPackageId: "0x..." }).'
+      );
+    }
+    const storageId = dappStorageIdParam ?? this.dappStorageId;
+    if (!storageId) {
+      throw new Error(
+        "dappStorageId is required for withdrawDappRevenue. Pass it directly or set it in the Dubhe constructor."
+      );
+    }
+    const typeArg = this.dappKey;
+    if (!typeArg) {
+      throw new Error(
+        'dappKey is required for withdrawDappRevenue. Set it in the Dubhe constructor ({ packageId: "0x..." }).'
+      );
+    }
+    const tx = new import_transactions3.Transaction();
+    tx.moveCall({
+      target: `${fwPkg}::dapp_system::withdraw_dapp_revenue`,
+      typeArguments: [typeArg, coinType],
+      arguments: [tx.object(dappHubId), tx.object(storageId)]
+    });
+    return this.signAndSendTxn({
+      tx,
+      derivePathParams,
+      onSuccess,
+      onError
+    });
+  }
+  /**
+   * Return a combined settlement health snapshot for a user.
+   *
+   * Fetches `UserStorage` fields (always) and optionally `DappStorage` fields
+   * (when `dappStorageId` is supplied) to produce high-level diagnostic values:
+   *
+   * - `utilizationPct`  — how close the user is to the 2 000-write hard limit
+   * - `isAtRisk`        — utilization >= 80 % (settlement recommended soon)
+   * - `isBlocked`       — utilization >= 100 % (writes will be rejected)
+   * - `estimatedWritesAffordable` — writes the credit pool can still cover
+   * - `creditAtRisk`    — fewer than 500 writes of credit remaining
+   *
+   * @param userStorageId  Object ID of the user's UserStorage shared object.
+   * @param dappStorageId  Object ID of the DApp's DappStorage (optional).
+   */
+  async getSettlementHealth({
+    userStorageId,
+    dappStorageId
+  }) {
+    const WRITE_LIMIT = 2000n;
+    const userFields = await this.getUserStorageFields(userStorageId);
+    const unsettledCount = userFields.unsettled_count;
+    const utilizationPct = Number(unsettledCount * 100n / WRITE_LIMIT);
+    const result = {
+      unsettledCount,
+      writeLimit: WRITE_LIMIT,
+      utilizationPct,
+      isAtRisk: utilizationPct >= 80,
+      isBlocked: utilizationPct >= 100
+    };
+    if (dappStorageId) {
+      const dappFields = await this.getDappStorageFields(dappStorageId);
+      const creditPool = dappFields.credit_pool;
+      const baseFeePerWrite = dappFields.base_fee_per_write;
+      const estimatedWritesAffordable = baseFeePerWrite > 0n ? creditPool / baseFeePerWrite : BigInt(Number.MAX_SAFE_INTEGER);
+      result.creditPool = creditPool;
+      result.baseFeePerWrite = baseFeePerWrite;
+      result.estimatedWritesAffordable = estimatedWritesAffordable;
+      result.creditAtRisk = estimatedWritesAffordable < 500n;
+    }
+    return result;
+  }
+  // ─── Private helpers ─────────────────────────────────────────────────────────
+  /**
+   * Return the default network configuration for the given network type.
+   *
+   * Useful for reading `frameworkPackageId` without instantiating a full client:
+   *
+   * ```ts
+   * const { frameworkPackageId } = Dubhe.getDefaultConfig('testnet');
+   * // → '0x8817b...' (known constant for testnet/mainnet)
+   * // → undefined   (for localnet/devnet — supply after local deployment)
+   * ```
+   */
+  static getDefaultConfig(networkType) {
+    return getDefaultConfig(networkType);
+  }
   // async formatData(type: string, value: Buffer | number[] | Uint8Array) {
   //   const u8Value = Uint8Array.from(value);
   //   return bcs.de(type, u8Value);
@@ -2979,11 +3785,17 @@ async function loadMetadata(networkType, packageId, fullnodeUrls) {
 0 && (module.exports = {
   BcsType,
   Dubhe,
+  MAINNET_DUBHE_FRAMEWORK_PACKAGE_ID,
+  MAINNET_DUBHE_HUB_OBJECT_ID,
   MultiSigClient,
   SuiAccountManager,
   SuiContractFactory,
   SuiTx,
+  TESTNET_DUBHE_FRAMEWORK_PACKAGE_ID,
+  TESTNET_DUBHE_HUB_OBJECT_ID,
   bcs,
+  getDefaultConfig,
+  getDefaultURL,
   loadMetadata,
   ...require("@mysten/sui/client"),
   ...require("@mysten/sui/utils"),