@0xobelisk/sui-client 1.2.0-pre.122 → 1.2.0-pre.124

package/dist/dubhe.d.ts

@@ -348,6 +348,22 @@ export declare class Dubhe {
      *
      * @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
+     */
+    getDappHubFields(dappHubId: string): Promise<{
+        objectId: string;
+        version: number;
+        framework_admin: string;
+        treasury: string;
+        pending_treasury: string;
+    }>;
     getDappStorageFields(dappStorageId: string): Promise<{
         objectId: string;
         dapp_key: string;
@@ -365,21 +381,54 @@ export declare class Dubhe {
         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;
     }>;
     /**
-     * Settle accumulated write debt for a user.
+     * 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;
+    /**
+     * Settle accumulated write debt for a user (standalone transaction).
      *
-     * Calls `<frameworkPackageId>::dapp_system::settle_writes<DappKey>` with the
-     * given DappHub, DappStorage, and UserStorage objects.
+     * 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 prepend to any PTB — the framework function never aborts
+     * 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.
      */
-    settleWrites({ dappHubId, dappStorageId: dappStorageIdParam, userStorageId, derivePathParams, onSuccess, onError }: {
+    settleWrites({ dappHubId, dappStorageId, userStorageId, derivePathParams, onSuccess, onError }: {
         dappHubId: string;
         dappStorageId?: string;
         userStorageId: string;
@@ -387,6 +436,192 @@ export declare class Dubhe {
         onSuccess?: (result: SuiTransactionBlockResponse) => void | Promise<void>;
         onError?: (error: Error) => void | Promise<void>;
     }): 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").
+     */
+    rechargeCredit({ dappHubId, dappStorageId: dappStorageIdParam, coinObjectId, coinType, 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>;
+    /**
+     * 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, coinType }: {
+        dappHubId: string;
+        dappStorageId?: string;
+        userStorageId: string;
+        maxPaymentMist?: bigint;
+        coinType?: string;
+    }): void;
+    /**
+     * 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").
+     */
+    settleWritesUserPays({ dappHubId, dappStorageId: dappStorageIdParam, userStorageId, coinObjectId, coinType, 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>;
+    /**
+     * 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.
+     */
+    queryWritesSettledEvents(limit?: number, 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;
+    }>>;
+    /**
+     * 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.
+     */
+    queryMarketplaceFeeSettledEvents(limit?: number, 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;
+    }>>;
+    /**
+     * 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").
+     */
+    getDappRevenueBalance(dappStorageId: string, coinType?: string): Promise<bigint>;
+    /**
+     * 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").
+     */
+    withdrawDappRevenue({ dappHubId, dappStorageId: dappStorageIdParam, coinType, 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>;
+    /**
+     * 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).
+     */
+    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;
+    }>;
     /**
      * Return the default network configuration for the given network type.
      *