@0xobelisk/sui-client 1.2.0-pre.115 → 1.2.0-pre.118

package/dist/dubhe.d.ts

@@ -1,4 +1,4 @@
-import { Transaction, TransactionResult } from '@mysten/sui/transactions';
+import { Transaction } from '@mysten/sui/transactions';
 import type { SuiTransactionBlockResponse, DevInspectResults, SuiMoveNormalizedModules, SuiObjectData } from '@mysten/sui/client';
 import { SuiAccountManager } from './libs/suiAccountManager';
 import { SuiTx } from './libs/suiTxBuilder';
@@ -24,9 +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
@@ -42,7 +45,7 @@ export declare class Dubhe {
      * @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, frameworkPackageId }?: DubheParams);
+    constructor({ mnemonics, secretKey, networkType, fullnodeUrls, packageId, metadata, channelUrl, frameworkPackageId, dappStorageId }?: DubheParams);
     get query(): MapMoudleFuncQuery;
     get tx(): MapMoudleFuncTx;
     get object(): MapObjectStruct;
@@ -65,7 +68,7 @@ export declare class Dubhe {
      * it will generate signer from the mnemonic with the given derivePathParams.
      * @param derivePathParams, such as { accountIndex: 2, isExternal: false, addressIndex: 10 }, comply with the BIP44 standard
      */
-    getSigner(derivePathParams?: DerivePathParams): import("@mysten/sui/keypairs/ed25519").Ed25519Keypair;
+    getSigner(derivePathParams?: DerivePathParams): import("@mysten/sui/dist/cjs/keypairs/ed25519").Ed25519Keypair;
     /**
      * @description Switch the current account with the given derivePathParams
      * @param derivePathParams, such as { accountIndex: 2, isExternal: false, addressIndex: 10 }, comply with the BIP44 standard
@@ -78,6 +81,25 @@ 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(): NetworkType | undefined;
     getNetworkConfig(): NetworkConfig;
@@ -150,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;
@@ -224,244 +246,154 @@ export declare class Dubhe {
     entity_key_from_address_with_u256(objectId: string, x: number): Promise<string | undefined>;
     entity_key_from_u256(x: number): Promise<string>;
     /**
-     * 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;
-    /**
-     * Derive the Sui address that corresponds to a raw Ed25519 public key.
-     *
-     * Matches the on-chain `derive_sui_address_from_pubkey` helper in
-     * `proxy_system.move`:
-     *   address = SHA3-256( [0x00] || publicKey )
-     * where 0x00 is the Ed25519 scheme flag.
-     *
-     * @param publicKey  Raw 32-byte Ed25519 public key
-     * @returns 64-character lowercase hex string (without 0x prefix), matching
-     *          the format returned by Move's `address::to_ascii_string()`
-     */
-    deriveSuiAddressFromEd25519PublicKey(publicKey: Uint8Array): string;
-    /**
-     * Build the canonical proxy registration message.
+     * Call the DApp's generated `user_storage_init::init_user_storage` entry function,
+     * which creates and shares a `UserStorage` object for the signer.
      *
-     * Mirrors `build_expected_message` in `proxy_system.move`:
-     *   "dubhe proxy:<owner_hex>:<proxy_hex>:<dapp_key_str>:<expires_at>"
+     * 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.
      *
-     * The proxy wallet must sign this message before `createProxy` is called.
-     *
-     * @param ownerAddress   Owner wallet's Sui address (with or without 0x prefix)
-     * @param proxyPublicKey Raw 32-byte Ed25519 public key of the proxy wallet
-     * @param expiresAt      Expiry time — either a `Date` object or a millisecond
-     *                       timestamp number (e.g. `Date.now() + 86_400_000`)
-     * @param dappKeyType    Full DappKey type string — defaults to
-     *                       `<packageId>::dapp_key::DappKey`
-     */
-    buildProxyMessage({ ownerAddress, proxyPublicKey, expiresAt, dappKeyType }: {
-        ownerAddress: string;
-        proxyPublicKey: Uint8Array;
-        expiresAt: number | Date;
-        dappKeyType?: string;
-    }): Uint8Array;
-    /**
-     * Sign the proxy registration message using this client's current account.
-     *
-     * The proxy wallet creates a Dubhe instance with its own secret key and calls
-     * this method to produce the `publicKey` and `signature` that the owner then
-     * passes to `createProxy`.
-     *
-     * @param ownerAddress  Sui address of the owner wallet
-     * @param expiresAt     Expiry time — either a `Date` object or a millisecond
-     *                      timestamp number (e.g. `new Date(Date.now() + 86_400_000)`)
-     * @param dappKeyType   Optional DApp key type override
-     * @returns `{ publicKey, signature, message }` — all as `Uint8Array`
-     */
-    signProxyMessage({ ownerAddress, expiresAt, dappKeyType }: {
-        ownerAddress: string;
-        expiresAt: number | Date;
-        dappKeyType?: string;
-    }): Promise<{
-        publicKey: Uint8Array;
-        signature: Uint8Array;
-        message: Uint8Array;
-    }>;
-    /**
-     * Register a proxy wallet binding on-chain.
-     *
-     * Follows the same `tx` + `isRaw` convention as `contract.tx.*`:
-     * - `isRaw: true`  — appends the Move call to the provided `tx` and returns
-     *   a `TransactionResult`. The caller controls signing and submission.
-     *   Useful for wallet-based signers (e.g. `useSignAndExecuteTransaction`).
-     * - `isRaw` omitted — creates a fresh `Transaction` internally, signs with
-     *   the Dubhe instance's own keypair, and submits automatically.
-     *
-     * The current signer (owner) submits this transaction. The proxy wallet must
-     * have already signed the canonical message via `signProxyMessage`, producing
-     * the `publicKey` and `signature` parameters.
-     *
-     * Calls `<frameworkPackageId>::proxy_system::create_proxy<DappKey>`.
-     *
-     * @example Wallet signer (browser dApp)
-     * ```typescript
-     * const { publicKey, signature } = await proxyDubhe.signProxyMessage({ ownerAddress, expiresAt });
-     * const tx = new Transaction();
-     * await proxyDubhe.createProxy({ tx, dappHubId, publicKey, signature, expiresAt, isRaw: true });
-     * await signAndExecuteTransaction({ transaction: tx.serialize(), chain: `sui:${network}` });
-     * ```
-     *
-     * @param tx                 Existing Transaction to append to (required when `isRaw: true`)
-     * @param dappHubId          Object ID of the DappHub shared object
-     * @param publicKey          Raw 32-byte Ed25519 public key of the proxy wallet
-     * @param signature          64-byte Ed25519 signature from the proxy wallet
-     * @param expiresAt          Expiry time — either a `Date` object or a millisecond timestamp
-     * @param isRaw              When true, appends the call and returns without submitting
-     * @param frameworkPackageId Override the dubhe framework package ID
-     * @param dappKeyType        Override the DApp key type string
+     * @param dappHubId      Object ID of the DappHub shared object
+     * @param dappStorageId  Object ID of the DApp's DappStorage shared object
      */
-    createProxy({ tx: txIn, dappHubId, publicKey, signature, expiresAt, isRaw, frameworkPackageId, dappKeyType, derivePathParams, onSuccess, onError }: {
-        tx?: Transaction;
+    initUserStorage({ dappHubId, dappStorageId: dappStorageIdParam, derivePathParams, onSuccess, onError }: {
         dappHubId: string;
-        publicKey: Uint8Array;
-        signature: Uint8Array;
-        expiresAt: number | Date;
-        isRaw?: boolean;
-        frameworkPackageId?: string;
-        dappKeyType?: string;
+        dappStorageId?: string;
         derivePathParams?: DerivePathParams;
         onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
         onError?: (error: Error) => void | Promise<void>;
-    }): Promise<SuiTransactionBlockResponse | TransactionResult>;
+    }): Promise<SuiTransactionBlockResponse>;
     /**
-     * Extend (or shorten) the expiry of an existing proxy binding.
-     *
-     * Follows the same `tx` + `isRaw` convention as `contract.tx.*`:
-     * - `isRaw: true`  — appends the Move call to the provided `tx` and returns
-     *   a `TransactionResult`. The caller controls signing and submission.
-     *   Useful for wallet-based signers (e.g. `useSignAndExecuteTransaction`).
-     * - `isRaw` omitted — creates a fresh `Transaction` internally, signs with
-     *   the Dubhe instance's own keypair, and submits automatically.
+     * Activate a session key for the signer's `UserStorage`.
      *
-     * Only the owner who created the binding may call this. The binding must
-     * still be active (not expired) — use `createProxy` with a fresh signature
-     * to re-establish an expired proxy.
+     * The signer must be the `canonical_owner` of the `UserStorage` object.
+     * Calls `<frameworkPackageId>::dapp_system::activate_session<DappKey>`.
      *
-     * Calls `<frameworkPackageId>::proxy_system::extend_proxy<DappKey>`.
-     *
-     * @example Wallet signer (browser dApp)
-     * ```typescript
-     * const tx = new Transaction();
-     * await proxyDubhe.extendProxy({ tx, dappHubId, proxyAddress, newExpiresAt, isRaw: true });
-     * await signAndExecuteTransaction({ transaction: tx.serialize(), chain: `sui:${network}` });
-     * ```
+     * @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)
      */
-    extendProxy({ tx: txIn, dappHubId, proxyAddress, newExpiresAt, isRaw, frameworkPackageId, dappKeyType, derivePathParams, onSuccess, onError }: {
-        tx?: Transaction;
-        dappHubId: string;
-        proxyAddress: string;
-        newExpiresAt: number | Date;
-        isRaw?: boolean;
-        frameworkPackageId?: string;
-        dappKeyType?: string;
+    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 | TransactionResult>;
+    }): Promise<SuiTransactionBlockResponse>;
     /**
-     * Remove an existing proxy binding.
-     *
-     * Follows the same `tx` + `isRaw` convention as `contract.tx.*`:
-     * - `isRaw: true`  — appends the Move call to the provided `tx` and returns
-     *   a `TransactionResult`. The caller controls signing and submission.
-     * - `isRaw` omitted — creates a fresh `Transaction`, signs with this
-     *   instance's keypair, and submits automatically.
+     * Deactivate the current session key on a `UserStorage`.
      *
-     * Only the owner who originally created the proxy may remove it. Expired
-     * proxies can also be removed to reclaim storage.
+     * Allowed callers:
+     *   - The `canonical_owner` (revoke at any time).
+     *   - The session key itself (voluntary sign-out).
+     *   - Anyone, once the session has expired.
      *
-     * Calls `<frameworkPackageId>::proxy_system::remove_proxy<DappKey>`.
+     * Calls `<frameworkPackageId>::dapp_system::deactivate_session<DappKey>`.
      *
-     * @example Wallet signer (browser dApp)
-     * ```typescript
-     * const tx = new Transaction();
-     * await proxyDubhe.removeProxy({ tx, dappHubId, proxyAddress, isRaw: true });
-     * await signAndExecuteTransaction({ transaction: tx.serialize(), chain: `sui:${network}` });
-     * ```
+     * @param userStorageId  Object ID of the UserStorage to deactivate the session on
      */
-    removeProxy({ tx: txIn, dappHubId, proxyAddress, isRaw, frameworkPackageId, dappKeyType, derivePathParams, onSuccess, onError }: {
-        tx?: Transaction;
-        dappHubId: string;
-        proxyAddress: string;
-        isRaw?: boolean;
-        frameworkPackageId?: string;
-        dappKeyType?: string;
+    deactivateSession({ userStorageId, derivePathParams, onSuccess, onError }: {
+        userStorageId: string;
         derivePathParams?: DerivePathParams;
         onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
         onError?: (error: Error) => void | Promise<void>;
-    }): Promise<SuiTransactionBlockResponse | TransactionResult>;
+    }): Promise<SuiTransactionBlockResponse>;
     /**
-     * Check whether a proxy wallet is currently active (bound and not expired).
+     * Look up the `UserStorage` object ID for the given address in this DApp.
      *
-     * Uses `devInspect` — no gas required. The check uses the precise Clock
-     * timestamp, so accuracy is better than `epoch_timestamp_ms`.
+     * 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.
      *
-     * Calls `<frameworkPackageId>::proxy_system::is_proxy_active<DappKey>`.
+     * Returns the object ID on success, or `null` when:
+     *   - `packageId` or `frameworkPackageId` is not set.
+     *   - The user has not yet called `initUserStorage`.
      *
-     * @param dappHubId      Object ID of the DappHub shared object
-     * @param proxyAddress   Sui address of the proxy wallet (with or without 0x)
-     * @param clockObjectId  Object ID of the Sui Clock (default: 0x6)
-     * @returns `true` if the proxy binding exists and `clock < expires_at`
+     * @param userAddress  Sui address to look up (with or without 0x prefix).
      */
-    isProxyActive({ dappHubId, proxyAddress, clockObjectId, frameworkPackageId, dappKeyType }: {
-        dappHubId: string;
-        proxyAddress: string;
-        clockObjectId?: string;
-        frameworkPackageId?: string;
-        dappKeyType?: string;
-    }): Promise<boolean>;
+    getUserStorageId(userAddress: string): Promise<string | null>;
     /**
-     * Check whether a proxy binding record exists (regardless of expiry).
+     * Fetch and return the on-chain fields of a `UserStorage` shared object.
      *
-     * Uses `devInspect` — no gas required.
+     * 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
      *
-     * Calls `<frameworkPackageId>::proxy_config::has`.
+     * @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.
      *
-     * @param dappHubId      Object ID of the DappHub shared object
-     * @param proxyAddress   Sui address of the proxy wallet (with or without 0x)
-     * @returns `true` if a binding record exists (may be expired)
+     * Covers the full metadata + fee/credit subset of the Move struct.
+     *
+     * @param dappStorageId  Object ID of the DappStorage to inspect.
      */
-    hasProxy({ dappHubId, proxyAddress, frameworkPackageId, dappKeyType }: {
-        dappHubId: string;
-        proxyAddress: string;
-        frameworkPackageId?: string;
-        dappKeyType?: string;
-    }): Promise<boolean>;
+    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;
+    }>;
     /**
-     * Fetch the proxy binding record for a given proxy wallet address.
+     * Settle accumulated write debt for a user.
      *
-     * Uses `devInspect` — no gas required.
-     * Returns `null` if no binding exists for the given proxy address.
+     * Calls `<frameworkPackageId>::dapp_system::settle_writes<DappKey>` with the
+     * given DappHub, DappStorage, and UserStorage objects.
      *
-     * Calls `<frameworkPackageId>::proxy_config::get`.
+     * 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 proxyAddress Sui address of the proxy wallet (with or without 0x)
-     * @returns `{ owner, expiresAt }` where `owner` is the bound owner's Sui address
-     *          (with 0x prefix) and `expiresAt` is the expiry timestamp in milliseconds,
-     *          or `null` if no binding record exists.
+     * @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.
      */
-    getProxyBinding({ dappHubId, proxyAddress, frameworkPackageId, dappKeyType }: {
+    settleWrites({ dappHubId, dappStorageId: dappStorageIdParam, userStorageId, derivePathParams, onSuccess, onError }: {
         dappHubId: string;
-        proxyAddress: string;
-        frameworkPackageId?: string;
-        dappKeyType?: string;
-    }): Promise<{
-        owner: string;
-        expiresAt: number;
-    } | null>;
+        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;
 }