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

package/dist/dubhe.d.ts

@@ -1,4 +1,4 @@
-import { Transaction } from '@mysten/sui/transactions';
+import { Transaction, TransactionResult } from '@mysten/sui/transactions';
 import type { SuiTransactionBlockResponse, DevInspectResults, SuiMoveNormalizedModules, SuiObjectData } from '@mysten/sui/client';
 import { SuiAccountManager } from './libs/suiAccountManager';
 import { SuiTx } from './libs/suiTxBuilder';
@@ -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 {
@@ -26,6 +26,7 @@ export declare class Dubhe {
     packageId: string | undefined;
     metadata: SuiMoveNormalizedModules | undefined;
     projectName: string | undefined;
+    frameworkPackageId: string | undefined;
     /**
      * Support the following ways to init the DubheClient:
      * 1. mnemonics
@@ -39,8 +40,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 }?: DubheParams);
     get query(): MapMoudleFuncQuery;
     get tx(): MapMoudleFuncTx;
     get object(): MapObjectStruct;
@@ -63,7 +65,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/dist/cjs/keypairs/ed25519").Ed25519Keypair;
+    getSigner(derivePathParams?: DerivePathParams): import("@mysten/sui/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
@@ -77,7 +79,7 @@ export declare class Dubhe {
     currentAddress(): string;
     getPackageId(): string;
     getMetadata(): SuiMoveNormalizedModules | undefined;
-    getNetwork(): import("./types").NetworkType | undefined;
+    getNetwork(): NetworkType | undefined;
     getNetworkConfig(): NetworkConfig;
     getTxExplorerUrl(txHash: string): string;
     getAccountExplorerUrl(address: string): string;
@@ -221,4 +223,245 @@ 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>;
+    /**
+     * 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.
+     *
+     * Mirrors `build_expected_message` in `proxy_system.move`:
+     *   "dubhe proxy:<owner_hex>:<proxy_hex>:<dapp_key_str>:<expires_at>"
+     *
+     * 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
+     */
+    createProxy({ tx: txIn, dappHubId, publicKey, signature, expiresAt, isRaw, frameworkPackageId, dappKeyType, derivePathParams, onSuccess, onError }: {
+        tx?: Transaction;
+        dappHubId: string;
+        publicKey: Uint8Array;
+        signature: Uint8Array;
+        expiresAt: number | Date;
+        isRaw?: boolean;
+        frameworkPackageId?: string;
+        dappKeyType?: string;
+        derivePathParams?: DerivePathParams;
+        onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+        onError?: (error: Error) => void | Promise<void>;
+    }): Promise<SuiTransactionBlockResponse | TransactionResult>;
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * 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}` });
+     * ```
+     */
+    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;
+        derivePathParams?: DerivePathParams;
+        onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+        onError?: (error: Error) => void | Promise<void>;
+    }): Promise<SuiTransactionBlockResponse | TransactionResult>;
+    /**
+     * 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.
+     *
+     * Only the owner who originally created the proxy may remove it. Expired
+     * proxies can also be removed to reclaim storage.
+     *
+     * Calls `<frameworkPackageId>::proxy_system::remove_proxy<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}` });
+     * ```
+     */
+    removeProxy({ tx: txIn, dappHubId, proxyAddress, isRaw, frameworkPackageId, dappKeyType, derivePathParams, onSuccess, onError }: {
+        tx?: Transaction;
+        dappHubId: string;
+        proxyAddress: string;
+        isRaw?: boolean;
+        frameworkPackageId?: string;
+        dappKeyType?: string;
+        derivePathParams?: DerivePathParams;
+        onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
+        onError?: (error: Error) => void | Promise<void>;
+    }): Promise<SuiTransactionBlockResponse | TransactionResult>;
+    /**
+     * Check whether a proxy wallet is currently active (bound and not expired).
+     *
+     * Uses `devInspect` — no gas required. The check uses the precise Clock
+     * timestamp, so accuracy is better than `epoch_timestamp_ms`.
+     *
+     * Calls `<frameworkPackageId>::proxy_system::is_proxy_active<DappKey>`.
+     *
+     * @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`
+     */
+    isProxyActive({ dappHubId, proxyAddress, clockObjectId, frameworkPackageId, dappKeyType }: {
+        dappHubId: string;
+        proxyAddress: string;
+        clockObjectId?: string;
+        frameworkPackageId?: string;
+        dappKeyType?: string;
+    }): Promise<boolean>;
+    /**
+     * Check whether a proxy binding record exists (regardless of expiry).
+     *
+     * Uses `devInspect` — no gas required.
+     *
+     * Calls `<frameworkPackageId>::proxy_config::has`.
+     *
+     * @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)
+     */
+    hasProxy({ dappHubId, proxyAddress, frameworkPackageId, dappKeyType }: {
+        dappHubId: string;
+        proxyAddress: string;
+        frameworkPackageId?: string;
+        dappKeyType?: string;
+    }): Promise<boolean>;
+    /**
+     * Fetch the proxy binding record for a given proxy wallet address.
+     *
+     * Uses `devInspect` — no gas required.
+     * Returns `null` if no binding exists for the given proxy address.
+     *
+     * Calls `<frameworkPackageId>::proxy_config::get`.
+     *
+     * @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.
+     */
+    getProxyBinding({ dappHubId, proxyAddress, frameworkPackageId, dappKeyType }: {
+        dappHubId: string;
+        proxyAddress: string;
+        frameworkPackageId?: string;
+        dappKeyType?: string;
+    }): Promise<{
+        owner: string;
+        expiresAt: number;
+    } | null>;
 }

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';