@0xobelisk/sui-client 1.2.0-pre.113 → 1.2.0-pre.117

package/dist/dubhe.d.ts

@@ -7,7 +7,7 @@ import { MapObjectStruct } from './types';
 import { SuiContractFactory } from './libs/suiContractFactory';
 import { SuiMoveMoudleFuncType } from './libs/suiContractFactory/types';
 import { NetworkConfig } from './libs/suiInteractor';
-import { DerivePathParams, FaucetNetworkType, MapMoudleFuncQuery, MapMoudleFuncTx, DubheParams, SuiTxArg, SuiObjectArg, SuiVecTxArg } from './types';
+import { DerivePathParams, FaucetNetworkType, MapMoudleFuncQuery, MapMoudleFuncTx, DubheParams, SuiTxArg, SuiObjectArg, SuiVecTxArg, NetworkType } from './types';
 import { DubheChannelClient } from './libs/dubheChannel';
 export declare function isUndefined(value?: unknown): value is undefined;
 export declare function withMeta<T extends {
@@ -24,8 +24,12 @@ export declare class Dubhe {
     contractFactory: SuiContractFactory;
     dubheChannelClient: DubheChannelClient;
     packageId: string | undefined;
+    /** Fully-qualified Move type string for this DApp's DappKey, e.g. `<64-hex>::dapp_key::DappKey`. */
+    dappKey: string | undefined;
     metadata: SuiMoveNormalizedModules | undefined;
     projectName: string | undefined;
+    frameworkPackageId: string | undefined;
+    dappStorageId: string | undefined;
     /**
      * Support the following ways to init the DubheClient:
      * 1. mnemonics
@@ -39,8 +43,9 @@ export declare 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, secretKey, networkType, fullnodeUrls, packageId, metadata, channelUrl }?: DubheParams);
+    constructor({ mnemonics, secretKey, networkType, fullnodeUrls, packageId, metadata, channelUrl, frameworkPackageId, dappStorageId }?: DubheParams);
     get query(): MapMoudleFuncQuery;
     get tx(): MapMoudleFuncTx;
     get object(): MapObjectStruct;
@@ -76,8 +81,27 @@ export declare class Dubhe {
     getAddress(derivePathParams?: DerivePathParams): string;
     currentAddress(): string;
     getPackageId(): string;
+    /**
+     * 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(): string | undefined;
     getMetadata(): SuiMoveNormalizedModules | undefined;
-    getNetwork(): import("./types").NetworkType | undefined;
+    getNetwork(): NetworkType | undefined;
     getNetworkConfig(): NetworkConfig;
     getTxExplorerUrl(txHash: string): string;
     getAccountExplorerUrl(address: string): string;
@@ -148,7 +172,7 @@ export declare class Dubhe {
      *   { onMessage: (data) => console.log(data) }
      * );
      */
-    subscribeChannelTable({ packageId, account, table, key }?: {
+    subscribeChannelTable({ packageId: _packageId, account, table, key }?: {
         packageId?: string;
         account?: string;
         table?: string;
@@ -221,4 +245,155 @@ export declare class Dubhe {
     entity_key_from_address_with_seed(objectId: string, seed: string): Promise<string | undefined>;
     entity_key_from_address_with_u256(objectId: string, x: number): Promise<string | undefined>;
     entity_key_from_u256(x: number): Promise<string>;
+    /**
+     * 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
+     */
+    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>;
+    /**
+     * 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)
+     */
+    activateSession({ userStorageId, sessionWallet, durationMs, clockObjectId, derivePathParams, onSuccess, onError }: {
+        userStorageId: string;
+        sessionWallet: string;
+        durationMs: number;
+        clockObjectId?: string;
+        derivePathParams?: DerivePathParams;
+        onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+        onError?: (error: Error) => void | Promise<void>;
+    }): 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
+     */
+    deactivateSession({ userStorageId, derivePathParams, onSuccess, onError }: {
+        userStorageId: string;
+        derivePathParams?: DerivePathParams;
+        onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+        onError?: (error: Error) => void | Promise<void>;
+    }): 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).
+     */
+    getUserStorageId(userAddress: string): Promise<string | 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.
+     */
+    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;
+    }>;
+    /**
+     * 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.
+     */
+    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;
+    }>;
+    /**
+     * Settle accumulated write debt for a user.
+     *
+     * Calls `<frameworkPackageId>::dapp_system::settle_writes<DappKey>` with the
+     * given DappHub, DappStorage, and UserStorage objects.
+     *
+     * This is safe to prepend to any PTB — 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.
+     */
+    settleWrites({ dappHubId, dappStorageId: dappStorageIdParam, 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>;
+    /**
+     * 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;
 }

package/dist/index.d.ts

@@ -14,3 +14,5 @@ export { MultiSigClient } from './libs/multiSig';
 export { SuiContractFactory } from './libs/suiContractFactory';
 export { loadMetadata } from './metadata';
 export type * from './types';
+export { getDefaultConfig, getDefaultURL, TESTNET_DUBHE_FRAMEWORK_PACKAGE_ID, TESTNET_DUBHE_HUB_OBJECT_ID, MAINNET_DUBHE_FRAMEWORK_PACKAGE_ID, MAINNET_DUBHE_HUB_OBJECT_ID } from './libs/suiInteractor/defaultConfig';
+export type { NetworkConfig } from './libs/suiInteractor/defaultConfig';