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

package/src/dubhe.ts

@@ -16,7 +16,7 @@ import { SuiInteractor } from './libs/suiInteractor';
 import { MapObjectStruct, MoveStructType, MoveEnumType } from './types';
 import { SuiContractFactory } from './libs/suiContractFactory';
 import { SuiMoveMoudleFuncType } from './libs/suiContractFactory/types';
-import { getDefaultURL, NetworkConfig } from './libs/suiInteractor';
+import { getDefaultConfig, NetworkConfig } from './libs/suiInteractor';
 import {
   ContractQuery,
   ContractTx,
@@ -27,10 +27,12 @@ import {
   DubheParams,
   SuiTxArg,
   SuiObjectArg,
-  SuiVecTxArg
+  SuiVecTxArg,
+  NetworkType
 } from './types';
 import {
   BasicBcsTypes,
+  normalizeDappKey,
   normalizeHexAddress,
   normalizePackageId,
   numberToAddressHex
@@ -112,6 +114,9 @@ function createTx(
   );
 }
 
+/** Sui's well-known shared Clock object ID, available on all networks. */
+const SUI_CLOCK_OBJECT_ID = '0x0000000000000000000000000000000000000000000000000000000000000006';
+
 /**
  * @class Dubhe
  * @description This class is used to aggregate the tools that used to interact with SUI network.
@@ -123,8 +128,13 @@ export class Dubhe {
   public dubheChannelClient: DubheChannelClient;
 
   public packageId: string | undefined;
+  /** Fully-qualified Move type string for this DApp's DappKey, e.g. `<64-hex>::dapp_key::DappKey`. */
+  public dappKey: string | undefined;
   public metadata: SuiMoveNormalizedModules | undefined;
   public projectName: string | undefined;
+  public frameworkPackageId: string | undefined;
+  public dappStorageId: string | undefined;
+  public dappHubId: string | undefined;
 
   readonly #query: MapMoudleFuncQuery = {};
   readonly #tx: MapMoudleFuncTx = {};
@@ -143,6 +153,7 @@ export class Dubhe {
    * @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,
@@ -150,12 +161,16 @@ export class Dubhe {
     networkType,
     fullnodeUrls,
     packageId,
+    dappKey: dappKeyParam,
     metadata,
-    channelUrl
+    channelUrl,
+    frameworkPackageId,
+    dappStorageId,
+    dappHubId
   }: DubheParams = {}) {
     networkType = networkType ?? 'mainnet';
 
-    const defaultParams = getDefaultURL(networkType);
+    const defaultParams = getDefaultConfig(networkType);
 
     // Init the account manager
     this.accountManager = new SuiAccountManager({ mnemonics, secretKey });
@@ -169,6 +184,19 @@ export class Dubhe {
     });
 
     this.packageId = packageId ? normalizePackageId(packageId) : undefined;
+    // Prefer the explicitly passed dappKey (stable across upgrades); fall back to
+    // computing it from packageId (only correct before the first upgrade).
+    this.dappKey = dappKeyParam;
+    // Prefer the explicitly provided frameworkPackageId; fall back to the
+    // well-known constant for the current network (defined for testnet/mainnet).
+    const networkDefault = defaultParams.frameworkPackageId;
+    this.frameworkPackageId = frameworkPackageId
+      ? normalizePackageId(frameworkPackageId)
+      : networkDefault
+      ? normalizePackageId(networkDefault)
+      : undefined;
+    this.dappStorageId = dappStorageId;
+    this.dappHubId = dappHubId;
     if (metadata !== undefined) {
       this.metadata = metadata as SuiMoveNormalizedModules;
 
@@ -1397,6 +1425,28 @@ export class Dubhe {
     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;
   }
@@ -1406,7 +1456,7 @@ export class Dubhe {
   }
 
   getNetworkConfig(): NetworkConfig {
-    return getDefaultURL(this.getNetwork());
+    return getDefaultConfig(this.getNetwork());
   }
 
   getTxExplorerUrl(txHash: string) {
@@ -1441,7 +1491,7 @@ export class Dubhe {
 
     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);
@@ -1458,6 +1508,11 @@ export class Dubhe {
     const packageIdChanged = config.packageId !== undefined && config.packageId !== this.packageId;
     const metadataChanged = config.metadata !== undefined && config.metadata !== this.metadata;
 
+    // dappKey is independent of packageId — update whenever explicitly provided.
+    if (config.dappKey !== undefined) {
+      this.dappKey = config.dappKey;
+    }
+
     if (packageIdChanged || metadataChanged) {
       // Update packageId
       if (config.packageId !== undefined) {
@@ -1703,15 +1758,12 @@ export class Dubhe {
   }) {
     packageId = packageId || this.packageId;
     account = account || this.getAddress();
-    // Remove 0x prefix if present
+    // Remove 0x prefix from account if present (required by the channel server)
     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: account,
       table: table,
       key: key
@@ -1759,7 +1811,7 @@ export class Dubhe {
    */
   async subscribeChannelTable(
     {
-      packageId,
+      packageId: _packageId,
       account,
       table,
       key
@@ -1776,20 +1828,13 @@ export class Dubhe {
       onClose?: () => void;
     }
   ) {
-    packageId = packageId || this.packageId;
-
-    // Remove 0x prefix if present (required by the channel server)
-    if (account !== undefined) {
-      if (account.startsWith('0x')) {
-        account = account.slice(2);
-      }
-    }
-    if (packageId && packageId.startsWith('0x')) {
-      packageId = packageId.slice(2);
+    // Remove 0x prefix from account if present (required by the channel server)
+    if (account !== undefined && account.startsWith('0x')) {
+      account = account.slice(2);
     }
 
     const payload: any = {
-      dapp_key: `${packageId}::dapp_key::DappKey`
+      dapp_key: this.dappKey
     };
 
     // Only include account if specified
@@ -2023,6 +2068,996 @@ export class Dubhe {
     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
+  }: {
+    dappHubId: string;
+    dappStorageId?: string;
+    derivePathParams?: DerivePathParams;
+    onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+  }): Promise<SuiTransactionBlockResponse> {
+    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 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
+    }) as Promise<SuiTransactionBlockResponse>;
+  }
+
+  /**
+   * 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
+  }: {
+    userStorageId: string;
+    sessionWallet: string;
+    durationMs: number;
+    dappHubId?: string;
+    clockObjectId?: string;
+    derivePathParams?: DerivePathParams;
+    onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+  }): Promise<SuiTransactionBlockResponse> {
+    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 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
+    }) as Promise<SuiTransactionBlockResponse>;
+  }
+
+  /**
+   * 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
+  }: {
+    userStorageId: string;
+    dappHubId?: string;
+    derivePathParams?: DerivePathParams;
+    onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+  }): Promise<SuiTransactionBlockResponse> {
+    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 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
+    }) as Promise<SuiTransactionBlockResponse>;
+  }
+
+  /**
+   * 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: string): Promise<string | null> {
+    const pkg = this.packageId;
+    const fwPkg = this.frameworkPackageId;
+    if (!pkg || !fwPkg) return null;
+
+    // Normalize to the 0x-prefixed form used in on-chain JSON.
+    const normalizedUser = userAddress.startsWith('0x') ? userAddress : `0x${userAddress}`;
+    // objectType includes the full framework package address prefix.
+    const expectedType = `${fwPkg}::dapp_service::UserStorage`;
+
+    let cursor: string | null | undefined = 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 !== undefined ? { cursor } : {}),
+        limit: 50
+      });
+
+      for (const tx of result.data) {
+        if (!tx.objectChanges) continue;
+        // Each SuiObjectChangeCreated carries a `sender` field that equals the
+        // transaction sender, which is the canonical_owner of the UserStorage.
+        const created = (tx.objectChanges as any[]).find(
+          (c: any) =>
+            c.type === 'created' &&
+            typeof c.objectType === 'string' &&
+            c.objectType === expectedType &&
+            c.sender === normalizedUser
+        );
+        if (created?.objectId) return created.objectId as string;
+      }
+
+      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: string): Promise<{
+    objectId: string;
+    dapp_key: string;
+    canonical_owner: string;
+    session_key: string;
+    session_expires_at: bigint;
+    write_count: bigint;
+    settled_count: bigint;
+    write_bytes: bigint;
+    settled_bytes: bigint;
+    unsettled_count: bigint;
+    unsettled_bytes: bigint;
+  }> {
+    const obj = await this.suiInteractor.getObject(userStorageId);
+    const fields = (obj?.content as any)?.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: string): Promise<{
+    objectId: string;
+    version: number;
+    framework_admin: string;
+    treasury: string;
+    pending_treasury: string;
+  }> {
+    const obj = await this.suiInteractor.getObject(dappHubId);
+    const fields = (obj?.content as any)?.fields ?? {};
+    // fee_config is a nested object; its fields contain treasury etc.
+    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: string): Promise<{
+    objectId: string;
+    dapp_key: string;
+    name: string;
+    description: string;
+    website_url: string;
+    admin: string;
+    version: number;
+    paused: boolean;
+    free_credit: bigint;
+    free_credit_expires_at: bigint;
+    credit_pool: bigint;
+    min_credit_to_unsuspend: bigint;
+    suspended: boolean;
+    total_settled: bigint;
+    base_fee_per_write: bigint;
+    bytes_fee_per_byte: bigint;
+    /**
+     * Settlement mode: 0 = DAPP_SUBSIDIZES (operator pays from credit_pool),
+     * 1 = USER_PAYS (user provides Coin via settle_writes_user_pays).
+     * Only `settle_writes` (no-coin variant) is safe to auto-call in mode 0.
+     */
+    settlement_mode: number;
+    /**
+     * BPS (0-10000) of each write-fee payment that flows into the DApp's
+     * revenue pool. The remainder goes to the framework treasury.
+     * Set exclusively by the framework admin via set_dapp_write_fee_share.
+     * Default: 0 (100% to framework treasury).
+     */
+    write_fee_dapp_share_bps: number;
+  }> {
+    const obj = await this.suiInteractor.getObject(dappStorageId);
+    const fields = (obj?.content as any)?.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: Transaction,
+    {
+      dappHubId,
+      dappStorageId: dappStorageIdParam,
+      userStorageId
+    }: { dappHubId: string; dappStorageId?: string; userStorageId: string }
+  ): void {
+    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
+  }: {
+    dappHubId: string;
+    dappStorageId?: string;
+    userStorageId: string;
+    derivePathParams?: DerivePathParams;
+    onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+  }): Promise<SuiTransactionBlockResponse> {
+    const tx = new Transaction();
+    this.buildSettleWritesTx(tx, { dappHubId, dappStorageId, userStorageId });
+    return this.signAndSendTxn({
+      tx,
+      derivePathParams,
+      onSuccess,
+      onError
+    }) as Promise<SuiTransactionBlockResponse>;
+  }
+
+  /**
+   * 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
+  }: {
+    dappHubId: string;
+    dappStorageId?: string;
+    coinObjectId: string;
+    coinType?: string;
+    derivePathParams?: DerivePathParams;
+    onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+  }): Promise<SuiTransactionBlockResponse> {
+    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 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
+    }) as Promise<SuiTransactionBlockResponse>;
+  }
+
+  /**
+   * 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: Transaction,
+    {
+      dappHubId,
+      dappStorageId: dappStorageIdParam,
+      userStorageId,
+      maxPaymentMist = 50_000_000n,
+      coinType = '0x2::sui::SUI'
+    }: {
+      dappHubId: string;
+      dappStorageId?: string;
+      userStorageId: string;
+      maxPaymentMist?: bigint;
+      coinType?: string;
+    }
+  ): void {
+    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..." }).'
+      );
+    }
+    // Split payment from the PTB's gas coin — no separate Coin object needed.
+    const [paymentCoin] = tx.splitCoins(tx.gas, [tx.pure.u64(maxPaymentMist)]);
+    // settle_writes_user_pays returns the change Coin (overpayment refund).
+    // Coin<T> has no `drop` ability, so the returned value MUST be consumed.
+    // Merge it back into tx.gas — it belongs to whoever is paying (the signer).
+    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
+  }: {
+    dappHubId: string;
+    dappStorageId?: string;
+    userStorageId: string;
+    coinObjectId: string;
+    coinType?: string;
+    derivePathParams?: DerivePathParams;
+    onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+  }): Promise<SuiTransactionBlockResponse> {
+    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 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
+    }) as Promise<SuiTransactionBlockResponse>;
+  }
+
+  /**
+   * 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?: { txDigest: string; eventSeq: string }
+  ): Promise<
+    Array<{
+      txDigest: string;
+      eventSeq: string;
+      timestampMs: number;
+      dappKey: string;
+      account: string;
+      writes: number;
+      bytes: string;
+      freeCost: string;
+      paidCost: string;
+    }>
+  > {
+    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: any) => {
+        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?: { txDigest: string; eventSeq: string }
+  ): Promise<
+    Array<{
+      txDigest: string;
+      eventSeq: string;
+      timestampMs: number;
+      dappKey: string;
+      listingId: string;
+      coinType: string;
+      totalFee: string;
+      treasuryAmount: string;
+      dappAmount: string;
+    }>
+  > {
+    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: any) => {
+        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: string, coinType = '0x2::sui::SUI'): Promise<bigint> {
+    const client = this.suiInteractor.currentClient;
+    // Normalise coinType to the bare module::name part for matching
+    const coinTail = coinType.split('::').slice(-2).join('::'); // e.g. "sui::SUI"
+    try {
+      let cursor: string | null | undefined = undefined;
+      do {
+        const page = await client.getDynamicFields({
+          parentId: dappStorageId,
+          cursor,
+          limit: 50
+        });
+        for (const field of page.data) {
+          // The dynamic field type contains DappRevenueKey and the coin type
+          const nameType: string = 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 as any)?.fields ?? {};
+            // Balance<T> is stored as { value: u64 }
+            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 {
+      // best-effort; return 0 on any RPC error
+    }
+    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
+  }: {
+    dappHubId: string;
+    dappStorageId?: string;
+    coinType?: string;
+    derivePathParams?: DerivePathParams;
+    onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+    onError?: (error: Error) => void | Promise<void>;
+  }): Promise<SuiTransactionBlockResponse> {
+    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 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
+    }) as Promise<SuiTransactionBlockResponse>;
+  }
+
+  /**
+   * 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
+  }: {
+    userStorageId: string;
+    dappStorageId?: string;
+  }): Promise<{
+    unsettledCount: bigint;
+    writeLimit: bigint;
+    utilizationPct: number;
+    isAtRisk: boolean;
+    isBlocked: boolean;
+    creditPool?: bigint;
+    baseFeePerWrite?: bigint;
+    estimatedWritesAffordable?: bigint;
+    creditAtRisk?: boolean;
+  }> {
+    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: bigint;
+      writeLimit: bigint;
+      utilizationPct: number;
+      isAtRisk: boolean;
+      isBlocked: boolean;
+      creditPool?: bigint;
+      baseFeePerWrite?: bigint;
+      estimatedWritesAffordable?: bigint;
+      creditAtRisk?: boolean;
+    } = {
+      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: NetworkType): NetworkConfig {
+    return getDefaultConfig(networkType);
+  }
+
   // async formatData(type: string, value: Buffer | number[] | Uint8Array) {
   //   const u8Value = Uint8Array.from(value);
   //   return bcs.de(type, u8Value);