@msafe/sui3-sdk 1.0.24 → 1.0.25

package/dist/index.d.cts

@@ -349,6 +349,16 @@ 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.
@@ -367,6 +377,15 @@ type PaymentCoinRef = {
  * ("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[];
 /**
@@ -658,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, 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, getAllCoins, getIntentionContent, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, isCoinReservationDigest, msafeChainToSuiNetwork, parkedPayloadHex, pickGasPaymentCoins, 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

@@ -349,6 +349,16 @@ 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.
@@ -367,6 +377,15 @@ type PaymentCoinRef = {
  * ("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[];
 /**
@@ -658,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, 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, getAllCoins, getIntentionContent, getMSafeConfig, getPublicKeyFromChain, httpUrlToGrpcBaseUrl, isCoinReservationDigest, msafeChainToSuiNetwork, parkedPayloadHex, pickGasPaymentCoins, 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

@@ -418,6 +418,8 @@ async function getAllCoins(input) {
 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;
@@ -433,22 +435,57 @@ 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((a, b) => a.balance === b.balance ? 0 : a.balance < b.balance ? 1 : -1);
+  const sorted = [...coins].filter((coin) => coin.balance > 0n).sort(compareBalanceDescending);
   const selected = [];
   let sum = 0n;
-  for (const coin of sorted) {
+  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) {
@@ -457,6 +494,46 @@ function pickGasPaymentCoins(coins, cover) {
   }
   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;
@@ -600,6 +677,12 @@ 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(pickGasPaymentCoins(paymentCoins, gasBudget)));
     return { mode: "classic", gasBudget, coinBalance, addressBalance };
@@ -655,7 +738,18 @@ async function estimateGasBudget(input) {
   const probe = mustResetGas ? cloneWithClearedGasConfig(tx) : Transaction.from(tx);
   probe.setSender(owner);
   probe.setGasPrice(gasPrice);
-  if (funding.paymentCoins.length > 0) {
+  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;
@@ -2121,6 +2215,7 @@ export {
   DEV_SYNCING_URL,
   ENV_CONFIGS,
   Formatter,
+  GasPaymentLimitError,
   HexToUint8Array,
   InfoTypeEnabledDto,
   InfoTypeKey,
@@ -2148,6 +2243,8 @@ export {
   computeGasBudget,
   createCoinReservationRef,
   estimateGasBudget,
+  gasCoinWithdrawal,
+  gasPaymentCover,
   getAllCoins,
   getIntentionContent,
   getMSafeConfig,