@msafe/sui3-sdk 1.0.23 → 1.0.25

package/dist/index.d.cts

@@ -334,6 +334,8 @@ declare class InvitationSDK {
     updateMSafeStatus(msafeAddress: string, status: UserMSafeStatus): Promise<void>;
 }
 
+/** Protocol cap: a transaction may smash at most this many gas payment objects. */
+declare const MAX_GAS_PAYMENT_OBJECTS = 256;
 type GasFundingMode = 'classic' | 'addressBalance' | 'mixedTopUp';
 interface GasFundingResult {
     mode: GasFundingMode;
@@ -347,11 +349,43 @@ declare class InsufficientGasFundsError extends Error {
     readonly addressBalance: bigint;
     constructor(gasBudget: bigint, coinBalance: bigint, addressBalance: bigint);
 }
+/**
+ * Gas coins cannot cover a SUI amount that is split from the gas coin.
+ * Happens when the largest 256 coins are still short of amount + gas budget.
+ */
+declare class GasPaymentLimitError extends Error {
+    readonly required: bigint;
+    readonly covered: bigint;
+    readonly coinCount: number;
+    constructor(required: bigint, covered: bigint, coinCount: number);
+}
 /**
  * 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;
+type PaymentCoinRef = {
+    objectId: string;
+    version: string;
+    digest: string;
+    balance: bigint;
+};
+/**
+ * Pick the fewest large SUI coins that cover `cover`, capped at 256.
+ * Never attach every owned coin — accounts with hundreds of SUI objects
+ * exceed max_gas_payment_objects and trip gasless estimate
+ * ("gas_budget must be 0 for gasless transactions").
+ */
+declare function pickGasPaymentCoins(coins: PaymentCoinRef[], cover: bigint): PaymentCoinRef[];
+/** SUI that CoinWithBalance intents will split out of the gas coin. */
+declare function gasCoinWithdrawal(tx: Transaction): bigint;
+/**
+ * Balance gas payment coins must hold.
+ * A SUI withdrawal is taken from the gas coin only when address balance cannot
+ * cover that withdrawal by itself. Mysten redeems address balance for the whole
+ * amount in that case, and gas payment only has to pay the gas budget.
+ */
+declare function gasPaymentCover(tx: Transaction, addressBalance: bigint, gasBudget: bigint): bigint;
 /** Object IDs a built payload already pins (inputs + gas payment). */
 declare function collectPayloadObjectIds(payload: string | Uint8Array): string[];
 /**
@@ -643,4 +677,4 @@ declare function getIntentionContent(intention: unknown): unknown;
  */
 declare function transactionFromContent(content: unknown): Transaction;
 
-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, collectPayloadObjectIds, collectQueueExcludeObjectIds, computeGasBudget, createCoinReservationRef, estimateGasBudget, getAllCoins, getIntentionContent, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, isCoinReservationDigest, msafeChainToSuiNetwork, parkedPayloadHex, preferClassicGasPayment, prepareGasFunding, selectGasFunding, stringToBuffer, toSuiTransaction, transactionFromContent };
+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, GasPaymentLimitError, HexToUint8Array, type HistorySendTx, type HistoryVote, type IWallet, InfoTypeEnabledDto, InfoTypeKey, InsufficientGasFundsError, LOCAL_API_URL, LOCAL_SYNCING_URL, MAINNET_RPC_URL, MAX_GAS_PAYMENT_OBJECTS, MSafeAccount, MSafeClient, type MSafeConfig, type MSafeConfigOptions, MSafeEnabledDto, MSafeEnv, MSafeGlobals, type NotificationData, type NotificationInfo, NotificationSubscribeDto, NotificationUpdateDto, PREV_API_URL, PROD_API_URL, type Pagination, type PaymentCoinRef, 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, collectPayloadObjectIds, collectQueueExcludeObjectIds, computeGasBudget, createCoinReservationRef, estimateGasBudget, gasCoinWithdrawal, gasPaymentCover, getAllCoins, getIntentionContent, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, isCoinReservationDigest, msafeChainToSuiNetwork, parkedPayloadHex, pickGasPaymentCoins, preferClassicGasPayment, prepareGasFunding, selectGasFunding, stringToBuffer, toSuiTransaction, transactionFromContent };

package/dist/index.d.ts

@@ -334,6 +334,8 @@ declare class InvitationSDK {
     updateMSafeStatus(msafeAddress: string, status: UserMSafeStatus): Promise<void>;
 }
 
+/** Protocol cap: a transaction may smash at most this many gas payment objects. */
+declare const MAX_GAS_PAYMENT_OBJECTS = 256;
 type GasFundingMode = 'classic' | 'addressBalance' | 'mixedTopUp';
 interface GasFundingResult {
     mode: GasFundingMode;
@@ -347,11 +349,43 @@ declare class InsufficientGasFundsError extends Error {
     readonly addressBalance: bigint;
     constructor(gasBudget: bigint, coinBalance: bigint, addressBalance: bigint);
 }
+/**
+ * Gas coins cannot cover a SUI amount that is split from the gas coin.
+ * Happens when the largest 256 coins are still short of amount + gas budget.
+ */
+declare class GasPaymentLimitError extends Error {
+    readonly required: bigint;
+    readonly covered: bigint;
+    readonly coinCount: number;
+    constructor(required: bigint, covered: bigint, coinCount: number);
+}
 /**
  * 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;
+type PaymentCoinRef = {
+    objectId: string;
+    version: string;
+    digest: string;
+    balance: bigint;
+};
+/**
+ * Pick the fewest large SUI coins that cover `cover`, capped at 256.
+ * Never attach every owned coin — accounts with hundreds of SUI objects
+ * exceed max_gas_payment_objects and trip gasless estimate
+ * ("gas_budget must be 0 for gasless transactions").
+ */
+declare function pickGasPaymentCoins(coins: PaymentCoinRef[], cover: bigint): PaymentCoinRef[];
+/** SUI that CoinWithBalance intents will split out of the gas coin. */
+declare function gasCoinWithdrawal(tx: Transaction): bigint;
+/**
+ * Balance gas payment coins must hold.
+ * A SUI withdrawal is taken from the gas coin only when address balance cannot
+ * cover that withdrawal by itself. Mysten redeems address balance for the whole
+ * amount in that case, and gas payment only has to pay the gas budget.
+ */
+declare function gasPaymentCover(tx: Transaction, addressBalance: bigint, gasBudget: bigint): bigint;
 /** Object IDs a built payload already pins (inputs + gas payment). */
 declare function collectPayloadObjectIds(payload: string | Uint8Array): string[];
 /**
@@ -643,4 +677,4 @@ declare function getIntentionContent(intention: unknown): unknown;
  */
 declare function transactionFromContent(content: unknown): Transaction;
 
-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, collectPayloadObjectIds, collectQueueExcludeObjectIds, computeGasBudget, createCoinReservationRef, estimateGasBudget, getAllCoins, getIntentionContent, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, isCoinReservationDigest, msafeChainToSuiNetwork, parkedPayloadHex, preferClassicGasPayment, prepareGasFunding, selectGasFunding, stringToBuffer, toSuiTransaction, transactionFromContent };
+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, GasPaymentLimitError, HexToUint8Array, type HistorySendTx, type HistoryVote, type IWallet, InfoTypeEnabledDto, InfoTypeKey, InsufficientGasFundsError, LOCAL_API_URL, LOCAL_SYNCING_URL, MAINNET_RPC_URL, MAX_GAS_PAYMENT_OBJECTS, MSafeAccount, MSafeClient, type MSafeConfig, type MSafeConfigOptions, MSafeEnabledDto, MSafeEnv, MSafeGlobals, type NotificationData, type NotificationInfo, NotificationSubscribeDto, NotificationUpdateDto, PREV_API_URL, PROD_API_URL, type Pagination, type PaymentCoinRef, 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, collectPayloadObjectIds, collectQueueExcludeObjectIds, computeGasBudget, createCoinReservationRef, estimateGasBudget, gasCoinWithdrawal, gasPaymentCover, getAllCoins, getIntentionContent, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, isCoinReservationDigest, msafeChainToSuiNetwork, parkedPayloadHex, pickGasPaymentCoins, preferClassicGasPayment, prepareGasFunding, selectGasFunding, stringToBuffer, toSuiTransaction, transactionFromContent };

package/dist/index.js

@@ -416,6 +416,10 @@ async function getAllCoins(input) {
 
 // src/utils/gasFunding.ts
 var GAS_SAFE_OVERHEAD = 1000n;
+var MAX_GAS_PAYMENT_OBJECTS = 256;
+var ESTIMATE_GAS_COVER = 1000000000n;
+var MAX_PROBE_GAS_BUDGET = 50000000000n;
+var COIN_WITH_BALANCE_INTENT = "CoinWithBalance";
 var InsufficientGasFundsError = class extends Error {
   gasBudget;
   coinBalance;
@@ -431,11 +435,105 @@ var InsufficientGasFundsError = class extends Error {
     this.addressBalance = addressBalance;
   }
 };
+var GasPaymentLimitError = class extends Error {
+  required;
+  covered;
+  coinCount;
+  constructor(required, covered, coinCount) {
+    super(gasPaymentLimitMessage(required, covered, coinCount));
+    this.name = "GasPaymentLimitError";
+    this.required = required;
+    this.covered = covered;
+    this.coinCount = coinCount;
+  }
+};
+function formatSui(mist) {
+  const negative = mist < 0n;
+  const value = negative ? -mist : mist;
+  const whole = value / 1000000000n;
+  const fraction = (value % 1000000000n).toString().padStart(9, "0").replace(/0+$/, "");
+  const text = fraction.length > 0 ? `${whole}.${fraction}` : `${whole}`;
+  return negative ? `-${text}` : text;
+}
+function gasPaymentLimitMessage(required, covered, coinCount) {
+  const requiredSui = formatSui(required);
+  const coveredSui = formatSui(covered);
+  if (coinCount >= MAX_GAS_PAYMENT_OBJECTS) {
+    return `This transfer needs ${requiredSui} SUI from gas coins, but the largest ${MAX_GAS_PAYMENT_OBJECTS} coins only cover ${coveredSui} SUI. Send a smaller amount, or consolidate coins into fewer objects first.`;
+  }
+  return `This transfer needs ${requiredSui} SUI from gas coins, but the available SUI coin objects only cover ${coveredSui} SUI.`;
+}
 function computeGasBudget(gasUsed, gasPrice) {
   const { computationCost, storageCost } = gasUsed;
   const safeOverhead = GAS_SAFE_OVERHEAD * gasPrice;
   return BigInt(computationCost) + BigInt(storageCost) + safeOverhead;
 }
+function compareBalanceDescending(a, b) {
+  if (a.balance === b.balance) {
+    return 0;
+  }
+  return a.balance < b.balance ? 1 : -1;
+}
+function pickGasPaymentCoins(coins, cover) {
+  if (cover <= 0n) {
+    return [];
+  }
+  const sorted = [...coins].filter((coin) => coin.balance > 0n).sort(compareBalanceDescending);
+  const selected = [];
+  let sum = 0n;
+  for (let index = 0; index < sorted.length; index += 1) {
+    if (selected.length >= MAX_GAS_PAYMENT_OBJECTS) {
+      break;
+    }
+    const coin = sorted[index];
+    selected.push(coin);
+    sum += coin.balance;
+    if (sum >= cover) {
+      break;
+    }
+  }
+  return selected;
+}
+function readBigInt(value) {
+  if (typeof value === "bigint") {
+    return value;
+  }
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return BigInt(Math.trunc(value));
+  }
+  if (typeof value === "string" && /^-?\d+$/.test(value)) {
+    return BigInt(value);
+  }
+  return 0n;
+}
+function gasCoinWithdrawal(tx) {
+  return tx.getData().commands.reduce((sum, command) => {
+    if (command.$kind !== "$Intent" || command.$Intent.name !== COIN_WITH_BALANCE_INTENT) {
+      return sum;
+    }
+    const data = command.$Intent.data;
+    if (data?.type !== "gas") {
+      return sum;
+    }
+    return sum + readBigInt(data.balance);
+  }, 0n);
+}
+function gasPaymentCover(tx, addressBalance, gasBudget) {
+  const withdrawal = gasCoinWithdrawal(tx);
+  const fromGasCoin = withdrawal > addressBalance ? withdrawal : 0n;
+  return gasBudget + fromGasCoin;
+}
+function sumBalances(coins) {
+  return coins.reduce((sum, coin) => sum + coin.balance, 0n);
+}
+function pickGasPaymentCoinsForCover(coins, cover) {
+  const picked = pickGasPaymentCoins(coins, cover);
+  const covered = sumBalances(picked);
+  if (cover > 0n && covered < cover) {
+    throw new GasPaymentLimitError(cover, covered, picked.length);
+  }
+  return picked;
+}
 function collectUsedObjectIds(tx) {
   const used = tx.getData().inputs.reduce((acc, input) => {
     const immOrOwned = input.Object?.ImmOrOwnedObject?.objectId;
@@ -579,8 +677,14 @@ async function selectGasFunding(input) {
   if (total < gasBudget) {
     throw new InsufficientGasFundsError(gasBudget, coinBalance, addressBalance);
   }
+  const cover = gasPaymentCover(tx, addressBalance, gasBudget);
+  if (cover > gasBudget) {
+    const picked = pickGasPaymentCoinsForCover(paymentCoins, cover);
+    tx.setGasPayment(toObjectRefs(picked));
+    return { mode: "classic", gasBudget, coinBalance, addressBalance };
+  }
   if (paymentCoins.length > 0 && coinBalance >= gasBudget) {
-    tx.setGasPayment(toObjectRefs(paymentCoins));
+    tx.setGasPayment(toObjectRefs(pickGasPaymentCoins(paymentCoins, gasBudget)));
     return { mode: "classic", gasBudget, coinBalance, addressBalance };
   }
   if (paymentCoins.length > 0 && total >= gasBudget) {
@@ -589,7 +693,7 @@ async function selectGasFunding(input) {
       tx,
       suiClient,
       owner,
-      paymentCoins,
+      paymentCoins: pickGasPaymentCoins(paymentCoins, 1n),
       topUpAmount
     });
     return { mode: "mixedTopUp", gasBudget, coinBalance, addressBalance };
@@ -634,8 +738,19 @@ async function estimateGasBudget(input) {
   const probe = mustResetGas ? cloneWithClearedGasConfig(tx) : Transaction.from(tx);
   probe.setSender(owner);
   probe.setGasPrice(gasPrice);
-  if (funding.paymentCoins.length > 0) {
-    probe.setGasPayment(toObjectRefs(funding.paymentCoins));
+  const fromGasCoin = gasPaymentCover(tx, funding.addressBalance, 0n);
+  if (fromGasCoin > 0n) {
+    const picked = pickGasPaymentCoins(funding.paymentCoins, fromGasCoin + ESTIMATE_GAS_COVER);
+    const covered = sumBalances(picked);
+    if (covered <= fromGasCoin) {
+      throw new GasPaymentLimitError(fromGasCoin, covered, picked.length);
+    }
+    probe.setGasPayment(toObjectRefs(picked));
+    const remainder = covered - fromGasCoin;
+    const probeBudget = remainder > MAX_PROBE_GAS_BUDGET ? MAX_PROBE_GAS_BUDGET : remainder;
+    probe.setGasBudget(probeBudget);
+  } else if (funding.paymentCoins.length > 0) {
+    probe.setGasPayment(toObjectRefs(pickGasPaymentCoins(funding.paymentCoins, ESTIMATE_GAS_COVER)));
   }
   let built;
   try {
@@ -710,7 +825,7 @@ async function preferClassicGasPayment(input) {
   if (funding.paymentCoins.length === 0) {
     return false;
   }
-  tx.setGasPayment(toObjectRefs(funding.paymentCoins));
+  tx.setGasPayment(toObjectRefs(pickGasPaymentCoins(funding.paymentCoins, ESTIMATE_GAS_COVER)));
   return true;
 }
 
@@ -2100,6 +2215,7 @@ export {
   DEV_SYNCING_URL,
   ENV_CONFIGS,
   Formatter,
+  GasPaymentLimitError,
   HexToUint8Array,
   InfoTypeEnabledDto,
   InfoTypeKey,
@@ -2107,6 +2223,7 @@ export {
   LOCAL_API_URL,
   LOCAL_SYNCING_URL,
   MAINNET_RPC_URL,
+  MAX_GAS_PAYMENT_OBJECTS,
   MSafeAccount,
   MSafeClient,
   MSafeEnabledDto,
@@ -2126,6 +2243,8 @@ export {
   computeGasBudget,
   createCoinReservationRef,
   estimateGasBudget,
+  gasCoinWithdrawal,
+  gasPaymentCover,
   getAllCoins,
   getIntentionContent,
   getMSafeConfig,
@@ -2134,6 +2253,7 @@ export {
   isCoinReservationDigest,
   msafeChainToSuiNetwork,
   parkedPayloadHex,
+  pickGasPaymentCoins,
   preferClassicGasPayment,
   prepareGasFunding,
   selectGasFunding,