@msafe/sui3-sdk 1.0.14 → 1.0.17

package/dist/index.d.cts

@@ -334,6 +334,70 @@ declare class InvitationSDK {
     updateMSafeStatus(msafeAddress: string, status: UserMSafeStatus): Promise<void>;
 }
 
+type GasFundingMode = 'classic' | 'addressBalance' | 'mixedTopUp';
+interface GasFundingResult {
+    mode: GasFundingMode;
+    gasBudget: bigint;
+    coinBalance: bigint;
+    addressBalance: bigint;
+}
+declare class InsufficientGasFundsError extends Error {
+    readonly gasBudget: bigint;
+    readonly coinBalance: bigint;
+    readonly addressBalance: bigint;
+    constructor(gasBudget: bigint, coinBalance: bigint, addressBalance: bigint);
+}
+/**
+ * Gas budget must cover pre-rebate costs (computation + storage + overhead).
+ * storageRebate is refunded after execution and must not reduce the budget.
+ */
+declare function computeGasBudget(gasUsed: Pick<SuiClientTypes.GasCostSummary, 'computationCost' | 'storageCost'>, gasPrice: bigint): bigint;
+/**
+ * Select gas funding before tx.build() according to mixed coin/addressBalance policy:
+ * 1) budget without storageRebate (caller supplies computeGasBudget result)
+ * 2-3) fail if total < budget
+ * 4) coins exist and coinBal >= budget → classic setGasPayment(coins)
+ * 5) coins exist and total >= budget → mixed top-up via coin reservation
+ * 6) no usable coins and addrBal >= budget → Address Balance gas (payment: [])
+ */
+declare function selectGasFunding(input: {
+    tx: Transaction;
+    suiClient: SuiGrpcClient;
+    owner: string;
+    gasBudget: bigint;
+}): Promise<GasFundingResult>;
+/**
+ * Estimate gas budget (no storageRebate) using a probe build/simulate.
+ * Prefers classic coin gas when coin objects exist so the estimate matches the
+ * cheaper payment path. Budget is left unset so Mysten can dry-run with MAX_GAS
+ * overrides (avoids locking the full balance away from GasCoin splits).
+ */
+declare function estimateGasBudget(input: {
+    tx: Transaction;
+    suiClient: SuiGrpcClient;
+    owner: string;
+    gasPrice: bigint;
+}): Promise<bigint>;
+/**
+ * Resolve gasBudget (no rebate) and apply gas funding selection before build.
+ */
+declare function prepareGasFunding(input: {
+    tx: Transaction;
+    suiClient: SuiGrpcClient;
+    owner: string;
+    gasPrice: bigint;
+    gasBudget?: bigint;
+}): Promise<GasFundingResult>;
+/**
+ * @deprecated Use {@link prepareGasFunding} / {@link selectGasFunding}.
+ * Kept as a thin classic-only helper for callers that only want coin gas when available.
+ */
+declare function preferClassicGasPayment(input: {
+    tx: Transaction;
+    suiClient: SuiGrpcClient;
+    owner: string;
+}): Promise<boolean>;
+
 declare class Simulator {
     private globals;
     constructor(globals: MSafeGlobals);
@@ -523,9 +587,19 @@ declare class Coin {
     }): bigint | undefined;
 }
 
+declare const COIN_RESERVATION_MAGIC: Uint8Array;
+declare function isCoinReservationDigest(digestBase58: string): boolean;
+declare function createCoinReservationRef(reservedBalance: bigint, owner: string, chainIdentifier: string, epoch: string): {
+    objectId: string;
+    version: string;
+    digest: string;
+};
+
 /**
- * Normalize a transaction value to {@link Transaction} (handles plain Transaction or serialized legacy shapes).
+ * Normalize a transaction value to {@link Transaction}.
+ * Prefer V2 restore paths — avoid deprecated V1 serialize() when possible
+ * (V1 drops CallArg::FundsWithdrawal).
  */
 declare function toSuiTransaction(txb: Transaction | unknown): Transaction;
 
-export { AddressBookSDK, COIN_TYPE_ARG_REGEX, Coin, CoinHelper, CreateHelper, type CreateMSafeInfo, DEV_API_URL, DEV_SYNCING_URL, ENV_CONFIGS, Formatter, type FutureIntention, type GasObjectReference, HexToUint8Array, type HistorySendTx, type HistoryVote, type IWallet, InfoTypeEnabledDto, InfoTypeKey, LOCAL_API_URL, LOCAL_SYNCING_URL, MAINNET_RPC_URL, MSafeAccount, MSafeClient, type MSafeConfig, type MSafeConfigOptions, MSafeEnabledDto, MSafeEnv, MSafeGlobals, type NotificationData, type NotificationInfo, NotificationSubscribeDto, NotificationUpdateDto, PREV_API_URL, PROD_API_URL, type Pagination, type PendingTx, type PendingVote, type ProposeIntention, type ReceiveTransaction, SUI_COIN, SignatureVerifier, type SimulateDryRunResponse, type SimulationFailedResult, type SimulationOption, type SimulationResult, type SimulationSuccessResult, TESTNET_RPC_URL, Uint8ArrayToHex, addPrefix, getAllCoins, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, msafeChainToSuiNetwork, stringToBuffer, toSuiTransaction };
+export { AddressBookSDK, COIN_RESERVATION_MAGIC, COIN_TYPE_ARG_REGEX, Coin, CoinHelper, CreateHelper, type CreateMSafeInfo, DEV_API_URL, DEV_SYNCING_URL, ENV_CONFIGS, Formatter, type FutureIntention, type GasFundingMode, type GasFundingResult, type GasObjectReference, HexToUint8Array, type HistorySendTx, type HistoryVote, type IWallet, InfoTypeEnabledDto, InfoTypeKey, InsufficientGasFundsError, LOCAL_API_URL, LOCAL_SYNCING_URL, MAINNET_RPC_URL, MSafeAccount, MSafeClient, type MSafeConfig, type MSafeConfigOptions, MSafeEnabledDto, MSafeEnv, MSafeGlobals, type NotificationData, type NotificationInfo, NotificationSubscribeDto, NotificationUpdateDto, PREV_API_URL, PROD_API_URL, type Pagination, type PendingTx, type PendingVote, type ProposeIntention, type ReceiveTransaction, SUI_COIN, SignatureVerifier, type SimulateDryRunResponse, type SimulationFailedResult, type SimulationOption, type SimulationResult, type SimulationSuccessResult, TESTNET_RPC_URL, Uint8ArrayToHex, addPrefix, computeGasBudget, createCoinReservationRef, estimateGasBudget, getAllCoins, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, isCoinReservationDigest, msafeChainToSuiNetwork, preferClassicGasPayment, prepareGasFunding, selectGasFunding, stringToBuffer, toSuiTransaction };

package/dist/index.d.ts

@@ -334,6 +334,70 @@ declare class InvitationSDK {
     updateMSafeStatus(msafeAddress: string, status: UserMSafeStatus): Promise<void>;
 }
 
+type GasFundingMode = 'classic' | 'addressBalance' | 'mixedTopUp';
+interface GasFundingResult {
+    mode: GasFundingMode;
+    gasBudget: bigint;
+    coinBalance: bigint;
+    addressBalance: bigint;
+}
+declare class InsufficientGasFundsError extends Error {
+    readonly gasBudget: bigint;
+    readonly coinBalance: bigint;
+    readonly addressBalance: bigint;
+    constructor(gasBudget: bigint, coinBalance: bigint, addressBalance: bigint);
+}
+/**
+ * Gas budget must cover pre-rebate costs (computation + storage + overhead).
+ * storageRebate is refunded after execution and must not reduce the budget.
+ */
+declare function computeGasBudget(gasUsed: Pick<SuiClientTypes.GasCostSummary, 'computationCost' | 'storageCost'>, gasPrice: bigint): bigint;
+/**
+ * Select gas funding before tx.build() according to mixed coin/addressBalance policy:
+ * 1) budget without storageRebate (caller supplies computeGasBudget result)
+ * 2-3) fail if total < budget
+ * 4) coins exist and coinBal >= budget → classic setGasPayment(coins)
+ * 5) coins exist and total >= budget → mixed top-up via coin reservation
+ * 6) no usable coins and addrBal >= budget → Address Balance gas (payment: [])
+ */
+declare function selectGasFunding(input: {
+    tx: Transaction;
+    suiClient: SuiGrpcClient;
+    owner: string;
+    gasBudget: bigint;
+}): Promise<GasFundingResult>;
+/**
+ * Estimate gas budget (no storageRebate) using a probe build/simulate.
+ * Prefers classic coin gas when coin objects exist so the estimate matches the
+ * cheaper payment path. Budget is left unset so Mysten can dry-run with MAX_GAS
+ * overrides (avoids locking the full balance away from GasCoin splits).
+ */
+declare function estimateGasBudget(input: {
+    tx: Transaction;
+    suiClient: SuiGrpcClient;
+    owner: string;
+    gasPrice: bigint;
+}): Promise<bigint>;
+/**
+ * Resolve gasBudget (no rebate) and apply gas funding selection before build.
+ */
+declare function prepareGasFunding(input: {
+    tx: Transaction;
+    suiClient: SuiGrpcClient;
+    owner: string;
+    gasPrice: bigint;
+    gasBudget?: bigint;
+}): Promise<GasFundingResult>;
+/**
+ * @deprecated Use {@link prepareGasFunding} / {@link selectGasFunding}.
+ * Kept as a thin classic-only helper for callers that only want coin gas when available.
+ */
+declare function preferClassicGasPayment(input: {
+    tx: Transaction;
+    suiClient: SuiGrpcClient;
+    owner: string;
+}): Promise<boolean>;
+
 declare class Simulator {
     private globals;
     constructor(globals: MSafeGlobals);
@@ -523,9 +587,19 @@ declare class Coin {
     }): bigint | undefined;
 }
 
+declare const COIN_RESERVATION_MAGIC: Uint8Array;
+declare function isCoinReservationDigest(digestBase58: string): boolean;
+declare function createCoinReservationRef(reservedBalance: bigint, owner: string, chainIdentifier: string, epoch: string): {
+    objectId: string;
+    version: string;
+    digest: string;
+};
+
 /**
- * Normalize a transaction value to {@link Transaction} (handles plain Transaction or serialized legacy shapes).
+ * Normalize a transaction value to {@link Transaction}.
+ * Prefer V2 restore paths — avoid deprecated V1 serialize() when possible
+ * (V1 drops CallArg::FundsWithdrawal).
  */
 declare function toSuiTransaction(txb: Transaction | unknown): Transaction;
 
-export { AddressBookSDK, COIN_TYPE_ARG_REGEX, Coin, CoinHelper, CreateHelper, type CreateMSafeInfo, DEV_API_URL, DEV_SYNCING_URL, ENV_CONFIGS, Formatter, type FutureIntention, type GasObjectReference, HexToUint8Array, type HistorySendTx, type HistoryVote, type IWallet, InfoTypeEnabledDto, InfoTypeKey, LOCAL_API_URL, LOCAL_SYNCING_URL, MAINNET_RPC_URL, MSafeAccount, MSafeClient, type MSafeConfig, type MSafeConfigOptions, MSafeEnabledDto, MSafeEnv, MSafeGlobals, type NotificationData, type NotificationInfo, NotificationSubscribeDto, NotificationUpdateDto, PREV_API_URL, PROD_API_URL, type Pagination, type PendingTx, type PendingVote, type ProposeIntention, type ReceiveTransaction, SUI_COIN, SignatureVerifier, type SimulateDryRunResponse, type SimulationFailedResult, type SimulationOption, type SimulationResult, type SimulationSuccessResult, TESTNET_RPC_URL, Uint8ArrayToHex, addPrefix, getAllCoins, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, msafeChainToSuiNetwork, stringToBuffer, toSuiTransaction };
+export { AddressBookSDK, COIN_RESERVATION_MAGIC, COIN_TYPE_ARG_REGEX, Coin, CoinHelper, CreateHelper, type CreateMSafeInfo, DEV_API_URL, DEV_SYNCING_URL, ENV_CONFIGS, Formatter, type FutureIntention, type GasFundingMode, type GasFundingResult, type GasObjectReference, HexToUint8Array, type HistorySendTx, type HistoryVote, type IWallet, InfoTypeEnabledDto, InfoTypeKey, InsufficientGasFundsError, LOCAL_API_URL, LOCAL_SYNCING_URL, MAINNET_RPC_URL, MSafeAccount, MSafeClient, type MSafeConfig, type MSafeConfigOptions, MSafeEnabledDto, MSafeEnv, MSafeGlobals, type NotificationData, type NotificationInfo, NotificationSubscribeDto, NotificationUpdateDto, PREV_API_URL, PROD_API_URL, type Pagination, type PendingTx, type PendingVote, type ProposeIntention, type ReceiveTransaction, SUI_COIN, SignatureVerifier, type SimulateDryRunResponse, type SimulationFailedResult, type SimulationOption, type SimulationResult, type SimulationSuccessResult, TESTNET_RPC_URL, Uint8ArrayToHex, addPrefix, computeGasBudget, createCoinReservationRef, estimateGasBudget, getAllCoins, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, isCoinReservationDigest, msafeChainToSuiNetwork, preferClassicGasPayment, prepareGasFunding, selectGasFunding, stringToBuffer, toSuiTransaction };